PXPERFECT Name
PXPERFECT
Author
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov Purpose
Postscript device settings for "pixel perfect" matching to screen plot layout
Calling Sequence
PS_EXTRA = PXPERFECT([/LANDSCAPE], [/INCHES], [THICK_FACTOR=tf], [SCALE=s])
Description
PXPERFECT is designed to achieve nearly "pixel perfect" matching
of plot layout when rendering a plot on the IDL Postscript device.
The dimensions and character sizes of the current display device
are used to construct a group of settings which can be passed to
the Postscript device driver using the DEVICE procedure.
The key capability of PXPERFECT is to determine the size of fonts
to match the on-screen size. Once this size is determined, IDL
will adjust other Postscript output dimensions such as plot
margins, font sizes, symbol sizes, etc, to match exactly the
on-screen layout.
The current direct graphics device must be a screen display
device, such as 'X' or 'WIN'. The user wouuld first call
PXPERFECT() to determine what the appropriate settings for the
Postscript device would be. At a later time, the user may switch
to the Postscript device to render the plot for output.
This is the approximate order of calling:
;; Prerequisite: current graphics device is display device
SET_PLOT, 'X' ;; or 'WIN'
TF = 1.0 ;; Thickness factor (see "Dealing with line thickness" below)
;; User adjusts the plot layout to taste
PLOT, ... data ..., thick=1.0*TF
;; Capture layout settings and then initialize Postscript
PS_EXTRA = PXPERFECT(THICK_FACTOR=TF)
SET_PLOT, 'PS' ;; NOTE: PXPERFECT() called *before* SET_PLOT
DEVICE, _EXTRA=PS_EXTRA
;; User calls same plot command(s) with no changes to layout
PLOT, ... data ..., thick=1.0*TF
;; Close output plot file
DEVICE, /CLOSE
If the display window is resized, then PXPERFECT should be called
again to capture the new layout settings.
The value returned by PXPERFECT is an IDL structure, with fields
that are meant to be passed to the IDL Postscript driver using the
DEVICE, _EXTRA=(...) statement.
Output Page Size. The dimensions of the Postscript output page
will be set so that the output page exactly matches the displayed
plot window. The algorithm does assume that the user's display
density settings are correct, in particular, that !D.X_PX_CM is a
correct reflection of the number of screen pixels per centimeter.
The user can adjust the output page size in several ways.
PXPERFECT accepts the XSIZE, YSIZE and SCALE_FACTOR keywords and
interprets them in the same way that the standard procedure DEVICE
does. In order to maintain the same layout, the user may specify
XSIZE or YSIZE, but not both. If both XSIZE and YSIZE are
specified, then the aspect ratio of the output page will not match
the on-screen display window, and pixel-perfect layout matching
cannot be attained in that case.
Dealing with Line Thickness. The Postscript device has a
different base line thickness compared to most on-screen display
devices. The value returned in the THICK_FACTOR keyword is a
scale factor which should be multiplied by all thicknesses when
rendering to Postscript.
Thus, if the desired on-screen line width is 2.0 units, then the
Postscript line thickness will be 2.0*TF, where TF is the value
returned in the THICK_FACTOR keyword.
Passing Other Keywords to DEVICE. PXPERFECT() accepts all the
keywords that the DEVICE procedure accepts. Any keywords that do
not specifically affect PXPERFECT's operation are passed
along to the output structure, and hence to DEVICE.
Positional Parameters
NONE
Keyword Parameters
INCHES - set this keyword if Postscript dimensions are to be
specified in inches instead of centimeters. This keyword
also specifies the units of the user-passed keywords
XSIZE, YSIZE, XOFFSET, YOFFSET.
Default: not set (i.e. centimeter units)
LANDSCAPE - set this keyword to indicate landscape orientation instead
of portrait orientation.
Default: not set (i.e. portrait orientation)
SCALE_FACTOR - a unitless scale factor which is used to scale the
size of the Postscript page output. By default the
output page size in inches or centimeters is scaled
to match the on-screen size. Use this keyword to
increase (>1.0) or decrease (<1.0) the size of the
output page.
Default: 1.0
THICK_FACTOR - upon output, THICK_FACTOR, which contain a factor
which should be used to multiply all line width
thicknesses.
XSIZE, YSIZE - user-requested output page size which may differ
from default Postscript page size. The user should
specify either XSIZE or YSIZE, but not both;
specifying both will cause the output page layout to not
exactly match the on-screen graphic layout. Also,
XSIZE or YSIZE override the SCALE_FACTOR keyword.
Default: not set (i.e. output page size will match
on-screen size)
XOFFSET, YOFFSET - user-requested page offsets.
Default: plot at origin (landscape plots are
adjusted appropriately) Returns
PXPERFECT returns a single IDL structure, which is meant to be
passed to the IDL Postscript device. This structure is passed
using the DEVICE procedure and the _EXTRA mechanism.
Side Effects
The graphics device must be set to a screen display device when
PXPERFECT is called.
Upon the first call to PXPERFECT, the graphics device is
momentarily switched to 'PS' in order to retrieve Postscript
device settings. Example
;; Plot to screen display
PLOT, FINDGEN(10), charsize=1.5
;; Initialize Postscript
PS = PXPERFECT()
SET_PLOT, 'PS'
DEVICE, _EXTRA=PS, FILENAME='outfile.ps'
;; Same plot, to Postscript page
PLOT, FINDGEN(10), charsize=1.5
;; Finish output
DEVICE, /CLOSE
See Also
DEVICE, SET_PLOT
Modification History
Written, CM, 2010
Documented, CM, 2011-04-15
Square bracket array notation, CM, 2011-12-21