; LWPLA
;---------------------------------------------------------------
;! translates plot file(s) to a PostScript printer or file
;# Task Plot
;-----------------------------------------------------------------------
;;  Copyright (C) 1995-1996, 1999, 2002-2004, 2009-2010
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
LWPLA     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
LWPLA:   Sends plot file(s) to a PostScript printer or file
INNAME                             Image name (name)
INCLASS                            Image name (class)
INSEQ           0.0      9999.0    Image name (seq. #)
INDISK          0.0         9.0    Disk drive #
PLVER           0.0     46655.0    Version # of PL file. 0=>last
INVERS          0.0     46655.0    PL file version #, upper
                                   limit if > PLVER
ASPMM           0.0                Arc sec. per mm. 0=self scale
LPEN            0.0        20.0    Pen width (dots).
RGBGAMMA        0.0                Gamma correction to apply
FUNCTYPE                           'NE','LG','NG', 'SQ', 'NQ'
                                   else linear
DPARM                              (1,2) Clip recorded grays
                                       before FUNCTYPE (0 to 1)
                                   (3,4) After FUNCTYPE scale
                                       by g*DPARM(3) + DPARM(4)
                                   (5) Page orientation
                                       0: fill page
                                       1: portrait  2: landscape
                                   (6) Paper type, for centering
                                       0: quarto,      1: legal,
                                       2: 4x5 in Slide,3: A3,
                                       4: A4,     5: 35 mm Slide
                                       6: 11 x 17
                                       1000*X + Y -> XxY inches
                                   (7) Font type, default
                                       Helvetica-Bold (see help)
                                   (8) Font size (in points,
                                       default 13).
                                   (9) Use CMYK color out rather
                                       than RGB if > 0. Do this
                                       for journals.
OUTFILE
                                   ' ' => print/delete
                                   otherwise write named file.
COPIES         0.0        50.0     Number of copies if going
                                   directly to a printer
DODARK        -1.0         1.0     Paint dark vectors as "dark"
OFMFILE                            Color grey scales....
DOCOLOR       -1.0         1.0     Use PLCOLORS ?
PLCOLORS      -1.0         1.0     Line, character, background
                                   colors - see HELP.
----------------------------------------------------------------
LWPLA
Type: Task
Use:  LWPLA will find an extension file of type PL and use the graphics
      commands in that file to display the image on PostScript devices.
      The output file follows the conventions for Encapsulated
      PostScript, allowing it to be inserted into other documents.
      WARNING: it is possible with this task to create multi-page
      PostScript files.  These cannot be properly called encapsulated
      and cannot be inserted into a document (actually they can - the
      pages overprint each other).

      See HELP POSTSCRIPT for additional info about PostScript and
      AIPS usage of it.
Adverbs:
  INNAME......Image name(name).  blank => any
  INCLASS.....Image name(class).  blank => any
  INSEQ.......Image name(seq. #).  0 => any
  INDISK......Disk drive # of image.  0 => any
  PLVER.......Version # of the PL file.  0 => largest version #
  INVERS......Upper PL version # of loop from PLVER to INVERS.
              < PLVER => PLVER.
  ASPMM.......Arc sec. per millimeter.  0 => self scale.
  LPEN........Width of lines in dots.  0 => 3 (less than 3 is not
              recommended for copying).
  RGBGAMMA....The gamma corrections to be applied to grey-scale and
              colored grey-scale pixel values after application of any
              FUNCTYPE and DPARM(1)-DPARM(4).  The grey-scale values
              (0 <= v <= 1) are adjusted by v' = v ** (1/gamma).  0 ->
              1 for red, 0 -> red for green, 0 -> green for blue.
              Greys are adjusted with the red value.
  FUNCTYPE....Convert the recorded gray levels using inverse linear
              ('NE'), logarithmic ('LG'), inverse log ('NG'), square
              root ('SQ'), inverse square root ('NQ'), or  linear
              (anything else).  Note that linear produces "negative"
              images --- ones in which the most intense sources are the
              blackest.
  DPARM.......(1,2) The recorded gray values (0 to 1.0) may be clipped
                 and linearly rescaled before applying FUNCTYPE, where
                 0 <= DPARM(1) < DPARM(2) <= 1.  Default is DPARM(1) =
                 0.0, DPARM(2) = 1.0.
              (3,4) After FUNCTYPE has been applied, the values range
                 from 0 to 1.  These may be shifted, scaled, and
                 reclipped to 0,1 by g*DPARM(3) + DPARM(4).  Defaults
                 are 1.0 and 0.0 from limits
                       0.01 < ABS(DPARM(3)) < 100    and
                       -100 < DPARM(4) < 100
                 When using 'NE' or 'NG' functions, it is often good to
                 limit the darkest areas if they are large to gray (i.e.
                 DPARM(3) around .85).
              (5) Page orientation
                     0: choose the orientation to fill the page
                     1: force portrait
                     2: force landscape
              (6) Paper type (used for scaling, orienting, and centering
                  the plot)
                     0: quarto       (8.5 x 11 inch = 216 x 279 mm))
                     1: legal        (8.5 x 14 inch = 216 x 356 mm)
                     2: 4x5in slide  (7.5 x 10 inch = 190 x 254 mm)
                     3: A3           (297 x 420 mm = 11.7 x 16.5 inch)
                     4: A4           (210 x 297 mm = 8.3 x 11.7 inch)
                     5: 35 mm slides (7.33 x 11 inch = 186 x 279 mm)
                     6: double       (11 x 17 inch = 279 x 432 mm)
                     > 1001 => user  (x by y inches where
                                          y = MOD (DPARM(6), 100.0)
                                          DPARM(6) = 1000*x+y. Thus
                                          8511 => 8.5 x 11 inch)
                     (The Freedom of the press slide software emulates a
                      11x7.333 inches page size for 35 mm slides, the
                      2:3 35mm aspect ratio, For 4x5in, the slide
                      software fills a 7.5x10 inch page.)
                     The file can now go to about 330 inches!
              (7) Font type.  Courier, Helvetica, and Times are
                  PostScript standards, but most PostScript printers
                  support the other font families also. The default font
                  is Helvetica-Bold.
                     01) AvantGarde-Book
                     02) AvantGarde-BookOblique
                     03) AvantGarde-Demi
                     04) AvantGarde-DemiOblique
                     11) Bookman-Demi
                     12) Bookman-DemiItalic
                     13) Bookman-Light
                     14) Bookman-LightItalic
                     21) Courier
                     22) Courier-Bold
                     23) Courier-Oblique
                     24) Courier-BoldOblique
                     31) Helvetica
                     32) Helvetica-Bold
                     33) Helvetica-Oblique
                     34) Helvetica-BoldOblique
                     41) Helvetica-Narrow
                     42) Helvetica-Narrow-Bold
                     43) Helvetica-Narrow-Oblique
                     44) Helvetica-Narrow-BoldOblique
                     51) NewCenturySchlbk-Roman
                     52) NewCenturySchlbk-Bold
                     53) NewCenturySchlbk-Italic
                     54) NewCenturySchlbk-BoldItalic
                     61) Palatino-Roman
                     62) Palatino-Bold
                     63) Palatino-Italic
                     64) Palatino-BoldItalic
                     71) Times-Roman
                     72) Times-Bold
                     73) Times-Italic
                     74) Times-BoldItalic
                     81) ZapfChancery-MediumItalic
              (8) Font size (in points, 1/72 inch), default is 13pt.
              (9) > 0 => write the PostScript in the CMYK (cyan,
                  magenta, yellow, black) color scheme used by
                  printers.  Journals prefer this despite the fact
                  that it makes the PostScript files 1/3 bigger.
                  <= 0 => use the traditional RGB (red, green, blue)
                  color scheme.  The OFMFILE and PLCOLORS and plot
                  files are all in RGB independent of the setting of
                  this parameter.  LWPLA will do the conversion which
                  is quite simple (C=1-R, M=1-G, Y=1-B, K=0 except
                  for nearly pure blacks).  Note that the two color
                  schemes are not identical.  Gamma corrections
                  (RGBGAMMA = 2.2 = XAS default gamma value) are often
                  okay for RGB print outs, but values much closer to
                  1.0 seem better for CMYK print outs.  If using, CMYK,
                  be sure to experiment and test the results by actual
                  printing.
   OUTFILE....' ' => send plot file to laser printer, then delete.
              Otherwise, create the named disk file but do not submit it
              for printing.  If the file already exists, the task
              append new pages (correctly) to the existing file.
   COPIES.....Number of copies to print (0 => 1).  Set to 1 when OUTFILE
              is specified.
   DODARK.....controls whether contours, polarization lines, and stars
              are drawn as "dark" overlay lines when the grey-scale or
              color image is bright (>0) or in the same color as used
              for the lines when the image is not bright (<= 0).
   OFMFILE....' ' => plot in black and white
              'TV' => read the TV OFM (before initializing it)
              other => read a text file giving the OFM to use (as in
              OFMDIR, OFMGET, OFMLIST, OFMSAVE).
              OFMFILE may be of the form 'Logical:File' where Logical
              is an logical (environment) name for a directory and
              File is a file name.  It may also be of the form
              'Stdfile' which is either a file $OFMFIL/Stdfile.uuu
              where uuu is the login user number or a file
              $AIPSOFM/Stdfile.001 in the OFM area distributed with
              AIPS.  Use verb OFMDIR to show what is available in
              the OFMFIL and AIPSOFM directories.  There is a web site
                 http://www.nro.nao.ac.jp/~sawada/aipscb/
              with color images of all standard AIPS OFMFILEs.
   DOCOLOR....If DOCOLOR > 0 use PLCOLORS.  Otherwise use black and
              white labels etc..  Note: If DOCOLOR is TRUE (> 0) and
              PLCOLORS is all zeros, then all the lines/symbols in
              your image will be black.
   PLCOLORS...Array of RGB colors for background, labels, borders etc..
              You can specify colors for both the bright and dark
              lines/symbols/characters.  If this is left all zeros and
              DOCOLOR is TRUE then all the lines/symbols/characters in
              the image will be black.  The first axis is red-green-blue
              in that order, while the second is used to select
              line/symbol/character type.  Each color fraction must be
              equal to or between 0 and 1, if any one of them is outside
              this range DOCOLOR is automatically set to -1.
              The line types are:
                 Bright
                   1  Border lines, tick marks, internal character labels
                   2  Contours, model lines
                   3  Polarization vectors
                   4  Stars (incl labels), symbols
                 Dark
                   5  internal character labels
                   6  Contours, model lines
                   7  Polarization vectors
                   8  Stars (incl labels), symbols
                 Other
                   9  Character labels outside the plot area
                  10  Overall background

               Procedure TVCOLORS will set PLCOLORS to those values
               currently set for your TV display.  See HELP PLCOLORS
               for further information and an example.
----------------------------------------------------------------
LWPLA:  Task which takes an AIPS plot file and produces a PostScript
        File and optionally sends it to a printer.
Submitted by Bruce Cogan, Mt. Stromlo Observatory, Australia.
DOCUMENTORS: Bruce Cogan, Mt. Stromlo Observatory, Australia,
             G. Langston NRAO,
             Mark Calabretta, Australia Telescope.

PostScript
     PostScript (PS) syntax is described, with hints on how to edit a PS
file.  One great advantage of PostScript is that it is all "normal"
ASCII, and can be edited with any text editor.  However, one great
disadvantage is that the syntax is very "non-intuitive".  Within
PostScript, almost any type of image can be created, once the commands
are known.

      See HELP POSTSCRIPT for additional info about PostScript and
      AIPS usage of it.

A very few PostScript commands:
%       - A PS comment, all remaining text on the line is ignored
/?{}def - defines a PS command

Below are the top few lines of a PS file that was edited by hand after
being created by LWPLA:

% Annotation added by hand follows
% Move to near the middle of the plot
 1250 1500 m
% Draw a vector upwards
 1250 1650 v
% Move back a little and draw the left half of an arrow head
 1225 1625 m 1250 1650 v
% Move back a little and draw the right half of an arrow head
 1275 1625 m  1250 1650 v
% Move above the center of the plot
 1300 1800 m
% Write 5 Characters 3C161
% (33="3", "43"=C, 31="1", 36="6", 31="1")
<3343313631>   0   -38   -63 c
% end of text inserted by hand.

% below is normal AIPS CNTR output via LWPLA:
    0    1 m  301  681 m 2237  681 v 2237 2617 v
  301 2617 v  301  681 v  301 2617 m
  ...

Clearly this is not a very convenient way of annotating plot files, and
is only presented as a temporary solution to the need for a general AIPS
plot file editor.

There are several PS tools available.  The SUN command pageview was used
to create the text added to the LWPLA file above.  The standard
X-Windows tool ghostview is recommended.

                         REFERENCES

PostScript Language Reference Manual, Second Edition
Adobe Systems Incorporated
Addison-Wesley, 1990
ISBN 0-201-18127-4

                 STUFF TO KEEP LAWYERS HAPPY

PostScript is a registered trademark of Adobe Systems Incorporated.
----------------------------------------------------------------
