;+ ; 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 ; Logic fix for case when XSIZE & YSIZE given together, CM, 2012-09-27 ; ; $Id: pxperfect.pro,v 1.5 2012/09/27 23:18:54 cmarkwar Exp $ ; ;- ; Copyright (C) 2010-2011,2012 Craig Markwardt ; This software is provided as is without any warranty whatsoever. ; Permission to use, copy, modify, and distribute modified or ; unmodified copies is granted, provided this copyright and disclaimer ; are included unchanged. ;-