idlastro / TV Display Procedures: TVLASER

[Source code]

NAME
TVLASER
PURPOSE
Prints screen or image array onto a Postscript file or printer.
Information from FITS header is optionally used for labeling.  
CALLING SEQUENCE
TVLASER, [header, Image, BARPOS = ,CARROWS =, CLABELS = ,/COLORPS, 
       COMMENTS = ,CSIZE = ,CTITLE = , DX = , DY =, /ENCAP, FILENAME =
       HEADER = ,/HELP, IMAGEOUT = ,/INTERP, /MAGNIFY, /NoCLOSE, 
       /NoDELETE, /NO_PERS_INFO, /NoEIGHT, /NoPRINT, /NoRETAIN, 
       /PORTRAIT, PRINTER = , /REVERSE, /SCALE, TITLE = , /TrueColor, 
       XDIM=, XSTART=, YDIM=, YSTART=, BOTTOMDW=, NCOLORSDW= ]    
 Note that the calling sequence was changed in May 1997
OPTIONAL INPUTS
HEADER - FITS header string array.   Object and astrometric info from
        the FITS header will be used for labeling, if available
IMAGE - if an array is passed through this parameter, then this image
        will be used rather than reading off the current window.  This
         allows easy use of large images.     It is usually preferable
        to optimally byte scale IMAGE before supplying it to TVLASER   
OPTIONAL KEYWORD INPUT PARAMETERS
BARPOS - A four- or five-element vector giving the position and
     orientation of the color bar.  The first four elements
     [X0,Y0,XSize,YSize] indicate the position and size of the color
     bar in INCHES, relative to origin of the displayed image.
     (X0,Y0) are the position of the lower left corner and 
     (XSize,YSize) are the width and height.  The fifth element is
     optional, and if present, the color bar will be printed
     horizontally rather than vertically.  If BARPOS is set to
     anything but a four- or five-element vector, the bar is NOT
     printed.  The default value is BARPOS = [-0.25, 0.0, 0.2, 2.0] 
BOTTOMDW - The lowest value to use in building the density
     wedge.  Used with NCOLORSDW.  Compatible with BOTTOM and
     NCOLORS keywords of XLOADCT.
CARROWS - The color to print the North-East arrows.  Default is dark.
     Three types of values can be passed:
          SCALAR: that value's color in the current color table
          3-ELEMENT VECTOR: the color will be [R,G,B]
          STRING: A letter indicating the color.  Valid names are:  
          'W' (white), 'D' (dark/black), 'R' (red),    'G' (green), 
          'B' (blue),  'T' (turquoise),  'V' (violet), 'Y' (yellow), 
      If the keyword is set to a value of -1, the arrows are
      NOT printed.
COLORPS - If present and non-zero, the idl.ps file is written using
      color postscript.
COMMENTS - A string that will be included in the comment line below the
         image.  For multi-line comments you can either use "!C" in the
         string as a carriage return {although the vertical spacing
         might be a little off} or, preferably, make the COMMENTS a
         string array with each line as a separate element. 
CLABELS - Color to print the labels, same format as for CARROWS.
CSIZE - Color to print the size-scale bar and label, same format as for
         CARROWS.
CTITLE - Color to print the title, same format as for CARROWS.
DX,DY - offsets in INCHES added to the position of the figure on the
        paper.  As is the case for the device keywords XOFFSET and
        YOFFSET, when in landscape mode DX and DY are the same
        *relative to the paper*, not relative to the plot (e.g., DX is
        the horizontal offset in portrait mode, but the *vertical*
        offset in landscape mode).
ENCAP - If present and non-zero, the IDL.PS file is written in
        encapsulated postscript for import into LaTeX documents
FILENAME - scalar string giving name of output postscript file.
        Default is idl.ps.   Automatically sets /NODELETE
HEADER = FITS header.   This is an alternative to supplying the FITS
         header in the first parameter.
HELP - print out the sytax for this procedure.
INTERP - If present and non-zero, current color table will be
         interpolated to fill the full range of the PostScript color
         table (256 colors).  Otherwise, the current color table will be
         directly copied.   You probably will want to use this if you
         are using IMAGE keyword and a shared color table.
MAGNIFY - The net magnification of the entire figure.  At this point,
         the figure is not automatically centered on the paper if the
         value of MAGNIFY is not equal to 1, but the DX and DY keywords
         can be used to shift location.  For example, to fit a full plot
         on the printable area (8.5x8.5 inches) of the Tek PhaserIISD
         color printer use:  MAGNIFY=0.8, DX=0.5, DY=0.5.;       
NCOLORSDW - The number of values to include in the density
         wedge.  Used with BOTTOMDW.  Compatible with
         BOTTOM/NCOLORS keywords of XLOADCT.
NoCLOSE - If present and non-zero, then the postscript file is not
      closed (or printed), the device is set to 'PS', and the data 
      coordinate system is set to match the image size.  This allows the
      user to add additional plotting commands before printing.  For 
      example, to include a 15 pixel circle around a source at 
      coordinates (150,160), around an image, im, with FITS header 
      array, h
         IDL> tvlaser,h,im,/NoClose      ;Write image & annotation
         IDL> tvcircle,15,150,160,/data  ;Draw circle
         IDL> device,/close              ;Close postscript file & print
NoDELETE - If present and non-zero, the postscript file is kept AND is 
          also sent to the printer
NoEIGHT - if set then only four bits sent to printer (saves space)
NO_PERS_INFO - if present and non-zero, output notation will NOT
          include date/user block of information.
NoPRINT - If present and non-zero, the output is sent to a file (default
         name 'idl.ps'), which is NOT deleted and is NOT sent to the 
         printer.
NoRETAIN - In order to avoid possible problems when using TVRD with
          an obscured window, TVLASER will first copy the current window
          to a temporary RETAIN=2 window.    Set /NORETAIN to skip this
          step and improve performance
PORTRAIT - if present and non-zero, the printer results will be in
          portrait format; otherwise, they will be in landscape format.
          If labels are requested, image will be in portrait mode,
          regardless
PRINTER - scalar string giving the OS command to send a the postscript
        file to the printer.   Under Unix, the default value of PRINTER
        is 'lpr ' while for other OS it is 'print ' 
REVERSE - if present and non-zero, color table will be fliped, so black
        and white are reversed.
SCALE - if present and non-zero, image will be bytscaled before being
        sent to postscript file.      
TITLE - if present and non-zero, the string entered here will be the
        title of the picture.  Default is the OBJECT field in the
        header (if present).
TRUECOLOR - if present and non-zero, the postscript file is created
        using the truecolor switch (i.e. true=3). The colorbar is
        not displayed in this mode.  
XDIM,YDIM - Number of pixels.  Default is from !d.x_size and !d.y_size,
        or size of image if passed with IMAGE keyword.
XSTART,YSTART - lower left corner (default of (0,0))
OPTIONAL KEYWORD OUTPUT PARAMETER
IMAGEOUT = the image byte array actually sent to the postscript file.
SIDE EFFECTS
A postscript file is created in the current directory.  User must have 
write privileges in the current directory.  The file is named idl.ps
unless the FILENAME keyword is given.   The file is directed to the
printer unless the /ENCAP, /NoCLOSE, or /NOPRINT keywords are given.
After printing, the file is deleted unless the /NODELETE or FILENAME 
keywords are given. 
PROCEDURE
Read display or take IMAGE and then redisplay into a postscript file.
If a header exists, printout header information.  If header has
astrometry, then print out orientation and scale information.
PROCEDURES USED
ARROWS, EXTAST, FDECOMP, GETROT, PIXCOLOR, SXPAR(), XYAD, ZPARCHECK
EXAMPLE
1) Send a true color image (xsize,ysize,3) to a printer (i.e. print23l),
         tvlaser,huv,cpic,/colorps,/truecolor,printer="print23l"
         % TVLASER: Now printing image: $print23l idl.ps
MODIFICATION HISTORY
Major rewrite from UIT version   W. Landsman   Dec 94
Massive rewrite.  Added North-East arrows, pixel scale bar, color bar,
and keywords DX, DY, MAGNIFY, INTERP, HELP, and COMMENTS.
Created ablility to define colors for annotation and
text.  Repositioned text labels.     J.Wm.Parker, HITC, 5/95
Make Header and Image parameters instead of keywords.   Add PRINTER
keyword.   Include alternate FITS keywords.   W. Landsman May 97      
Copy to a RETAIN=2 window, work without FITS header W. Landsman June 97
Cleaner output when no astrometry in header  W. Landsman  June 97
Added /INFO to final MESSAGE  W. Landsman   July 1997
12/4/97  jkf/acc - added TrueColor optional keyword.
Added /NoClose keyword, trim Equinox format  W. Landsman 9-Jul-1998
Don't display coordinate labels if no astrometry, more flexible
formatting of exposure time W. Landsman 30-Aug-1998
BottomDW and NColorsDW added.  R. S. Hill, 1-Mar-1999
Apply func tab to color bar if not colorps.  RSH, 21 Mar 2000
Fix problem with /NOCLOSE and unequal X,Y sizes  W. Landsman Feb 2001
Use TVRD(True=3) if /TRUECOLOR set    W. Landsman   November 2001
More synonyms, check for header supplied W. Landsman November 2007