; POSTSCRIPT
;---------------------------------------------------------------
;! General comments about AIPS use of PostScript incl macros
;# INFORMATION PLOT GENERAL HARDCOPY
;-----------------------------------------------------------------------
;;  Copyright (C) 2004
;;  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
;-----------------------------------------------------------------------
POSTSCRIPT LLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
----------------------------------------------------------------
POSTSCRIPT
Type: information
Use:  AIPS converts printed and plotted output into PostScript files.
      These are straightforward text files which can be modified with
      an editor prior to printing or inclusion in some other document
      (e.g. LaTeX papers).  The explain section of this help file
      describes the macros used by AIPS tasks to display plot data.
      It also includes some macros that you could invoke inside your
      plot file to add annotation such as arrows to point to and label
      image features ("component A, B, C...") or to provide an
      additional scale ("1 pc").
Tasks:
  LWPLA.....Convert a plot file to PostScript with coloring options.
  TVCPS.....Convert the current TV display to PostScript.
  TVRGB.....Make TV image and output PostScript from true color (RGB)
            images or from 3 images taken as RGB.
----------------------------------------------------------------
POSTSCRIPT: Information about AIPS' usage of PostScript

AIPS deliberately tries to keep its output PostScript files as simple
as possible.  This allows the user to modify them without too much
difficulty.  Note that PostScript is a programming language very
similar to FORTH and that PostScript files are simple text files which
may be edited by your favorite editor (emacs, vi, et al.).  Some
graphics programs can read in PostScript, modify the picture, and then
write the result back out as PostScript (usually with much more
complicated forms).

PostScript is a full language and we cannot describe it in detail
here.  references are given below.  Critical things to know:

1. Comments are text following a % sign in the line

2. Graphics commands
       x y moveto         moves attention to (x,y)
       x y lineto         draws line to (x,y)
       x y r a1 a2 arc    draws arc of radius r about (x,y) from angle
                          a1 to angle a2

3. Text written
      /TextFont  /Courier-Bold findfont 22 scalefont def
      TextFont setfont
      (TAN) show

      Where the first line defines a symbol as a particular font
      the second line sets the font to that symbol and the third line
      draws a string ("TAN") in that font starting at the current
      position.

4. Global things to do
      You can rotate, shift, and scale the whole plot by the addition
      of commands near the top:
          Fx Fy scale
          Dx Dy translate
          a rotate

5. Encapsulated PostScript requires the first line to declare the file
to be PostScript and EPSF and somewhere there must be a bounding box
command giving the plot coordinate range (in points):
          %!PS-Adobe-2.0 EPSF-2.0
          %%BoundingBox:  llx  lly  urx  ury
Note that these are both "comments".  Ghostview is useful in
determining the correct bounding box.


Text taken from a recent LWPLA output as a start of an AIPS PS file
(with added comments)

%!PS-Adobe-3.0 EPSF-3.0
%%BoundingBox:      0 0 988 778
%   ....
%                                  etc
%
%%EndComments
%%BeginProcSet: lwpla.pro

%                                  define symbols

%                                  2 arguments moves current point
   /m {moveto} def
%                                  2 arguments actually draws line
%                                  (with stroke) starts new section
   /v {lineto currentpoint stroke moveto} def
%                                  offsets and drawa a character string
   /c {rmoveto gsave currentpoint translate rotate
       show grestore} def
%                                   Grey scale
   /g {save hafpix hafpiy rmoveto currentpoint
       translate pscalx pscaly scale
       npix 1 8 [npix 0 0 1 0 0] {currentfile npix string readhexstring pop} image
       restore} def
%                                    RGB scale
   /G {save hafpix hafpiy rmoveto currentpoint
       translate pscalx pscaly scale
       npix 1 8 [npix 0 0 1 0 0] {currentfile 3 npix mul string readhexstring pop} false 3 colorimage
       restore} def
%                                   CMYK scale
   /H {save hafpix hafpiy rmoveto currentpoint
       translate pscalx pscaly scale
       npix 1 8 [npix 0 0 1 0 0] {currentfile 4 npix mul string readhexstring pop} false 4 colorimage
       restore} def
%%EndProcSet
%                Dots       BoundingBox
%            (1/300 inch)   (1/72 inch)
%%EndProlog

%                                     usual start up stuff
userdict /start-hook known {start-hook} if
%%Page:       1      1
%%Extensions: CMYK
%%Requirements: color
userdict /bop-hook known {bop-hook} if
/vmsave save def

%                                     draws a box around the full area
%                                     and fills it with a background
%                                     color - black
%                                     these were edited to correct for
%                                     the hand shifting and scaling
   0 0 moveto  988 0 lineto 988 778 lineto  0 778 lineto
   0 0 lineto fill stroke
%                                     scales to make larger for
%                                     conversion to jpg
%                                     these were added by hand
1.54 1.54 scale
-76 -54 translate

%                                     all AIPS plots are in dots for a
%                                     300 dots/inch printer
72 300 div dup scale
%                                     sample rotation commented out
%% 2550 0 translate 90 rotate
1 setlinejoin 1 setlinecap
  3 setlinewidth
/Helvetica-Bold findfont 54 scalefont setfont
newpath gsave
% following vectors are of type labeling
 0.850 0.850 0.900 setrgbcolor
 681 2244 m
%                                     the arguments to c are
%                                     (str) rotate Dx Dy
(CENTAUR  IPOL  4635.100 MHZ  CENTAU-C1BC.ICLN.1)  0 0 21 c
%                                     thus
  681 1386 m
(DECLINATION \(J2000\))  90  -297  -257 c

%                                     standard ending
stroke
vmsave restore
showpage
userdict /eop-hook known {eop-hook} if
%%Trailer
%%Pages:       1
userdict /end-hook known {end-hook} if
%%EOF

%                                     sample of color image
%                                     one row of step wedge (mostly red)
  609 1836 m
/hafpix    -5 def
/hafpiy    -5 def
/pscalx  2492 def
/pscaly    10 def
/npix     250 def
 G
0000000525E30091C000D27900EF2A27FF008FFF00F7FF00FFFF00FFF600FFCE00FFAA00
FF8100FF6100FF3C00FF1C00FF0000FF0000FF0000FF0000FF0000FF0000FF0000FF0000
FF0000FF0000FF0000FF0000FF0000FF0000FF0000FF0000FF0000FF0000FF0000FF0000
%                                     which goes on a longgggg ways


==============================

Useful macros

1. Bar
/Bar {
%                     args
   /drop exch def
   /endheight exch 2 div def
   /length exch 2 div def
   /ypos exch def   /xpos exch def
%                     draw
   xpos ypos moveto
   length endheight rmoveto
   0 -2 endheight mul rlineto
   0 endheight rmoveto
   -2 length mul 0 rlineto
   0 endheight rlineto
   0 -2 endheight mul rlineto
%                               label
   xpos ypos moveto
   dup stringwidth pop
   2 div neg  drop rmoveto
   show stroke
} def

Takes a string, bar x and y center coordinate, bar full length,
end-bar full length and character y offset as its arguments.  You are
responsible for setlinewidth, setrgbcolor/setgray, and setfont in
advance of this command as well.  Thus

      newpath
        /Helvetica-Bold findfont 33 scalefont setfont
        4 setlinewidth  0 2.8 0.8 setrgbcolor
        (1 pc) 950 2100 173.4 30 14 Bar

Copy the /Bar definition to the definition section of your AIPS plot,
copy some text such as the example above to just before the end of
your AIPS plot (just ahead of "vmsave restore showpage") and then look
at it with gv.  Adjust the parameters to make the most pleasing (and
correct) display.  It looks more complicated than it is.


2. Arrow

/arrowdict 14 dict def
arrowdict begin
   /mtrx matrix def
end

/arrow
 {arrowdict begin
%                                  pick args off stack
   /headlength exch def
   /halfheadthick exch 2 div def
   /halfthick exch 2 div def
   /tipy exch def  /tipx exch def
   /taily exch def /tailx exch def
%                                  internal parms
   /dx tipx tailx sub def
   /dy tipy taily sub def
   /arrowlength dx dx mul dy dy mul add sqrt def
   /angle dy dx atan def
   /base arrowlength headlength sub def
%                                  save state
   /savematrix mtrx currentmatrix def
%                                  set local coords
   tailx taily translate   angle rotate
%                                  draw arrow
   0 halfthick neg moveto
   base halfthick neg lineto
   base halfheadthick neg lineto
   arrowlength 0 lineto
   base halfheadthick lineto
   base halfthick lineto
   0 halfthick lineto
   closepath
%                                  restore state
   savematrix setmatrix
 end
} def

Useage:
   7 Arguments are
      x y of center of tail
      x y of arrow tip
      tail thickness
      max arrow head thickness
      length of arrowhead

Examples:
%                            black arrow to left
   newpath
   318 340 72 340 10 30 72 arrow
   0 setgray fill
%                            outline arrow to upper right
   newpath
   382 400 542 560 72 232 116 arrow
   3 setlinewidth stroke
%                            grey and outline arrow down
   newpath
   400 300 400 90 90 200 200 3 sqrt mul 2 div arrow
   gsave .65 setgray fill grestore
   5 setlinewdith stroke

%                            Example from aips plot file
newpath
   900 1700 1100 1700 9 17 30 arrow
   1 setgray fill
newpath
   902 1700 1098 1700 3 11 28 arrow
   0 setgray fill
   stroke
newpath
   860 1690 moveto  1 .5 0 setrgbcolor
   (a) show stroke



                         REFERENCES

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

Arrow above from
PostScript Language Tutorial and Cookbook
Adobe Systems Incorporated
Addison-Wesley, 1986
ISBN 0-201-10179-3

                 STUFF TO KEEP LAWYERS HAPPY

PostScript is a registered trademark of Adobe Systems Incorporated.
