AIPS NRAO AIPS HELP file for POSTSCRIPT in 31DEC18



As of Mon Jul 23 5:38:06 2018



HELP SECTION

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.

EXPLAIN SECTION

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  percent 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
   The "translate" will be illustrated in the example describing how
   to handle outputs of HUINT at the end of this file.

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):
           percent!PS-Adobe-2.0 EPSF-2.0
           percent percentBoundingBox:  llx  lly  urx  ury
Note that these are both "comments".  Ghostview is useful in
determining the correct bounding box.  Modern LWPLA outputs put the
BoundingBox information at the end by putting this line near the
start

 percent percentBoundingBox:(atend)

and then the actual BoundingBox at the end

 percent percentTrailer
 percent percentPages:       1
 percent percentBoundingBox:      36    178    576    613
userdict /end-hook known {end-hook} if
 percent percentEOF


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

 percent!PS-Adobe-3.0 EPSF-3.0
 percent percentBoundingBox:      0 0 988 778
 percent   ....
 percent                                  etc
 percent
 percent percentEndComments
 percent percentBeginProcSet: lwpla.pro

 percent                                  define symbols

 percent                                  2 arguments moves current point
   /m {moveto} def
 percent                                  2 arguments actually draws line
 percent                                  (with stroke) starts new section
   /v {lineto currentpoint stroke moveto} def
 percent                                  offsets and draws a character string
   /c {rmoveto gsave currentpoint translate rotate
       show grestore} def
 percent                                   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
 percent                                    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
 percent                                   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
 percent percentEndProcSet
 percent                Dots       BoundingBox
 percent            (1/300 inch)   (1/72 inch)
 percent percentEndProlog

 percent                                     usual start up stuff
userdict /start-hook known {start-hook} if
 percent percentPage:       1      1
 percent percentExtensions: CMYK
 percent percentRequirements: color
userdict /bop-hook known {bop-hook} if
/vmsave save def

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

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


 percent                                     standard ending
stroke
vmsave restore
showpage
userdict /eop-hook known {eop-hook} if
 percent percentTrailer
 percent percentPages:       1
userdict /end-hook known {end-hook} if
 percent percentEOF

 percent                                     sample of color image
 percent                                     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
 percent                                     which goes on a longgggg ways


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

Useful macros

1. Bar
/Bar {
 percent                     args
   /drop exch def
   /endheight exch 2 div def
   /length exch 2 div def
   /ypos exch def   /xpos exch def
 percent                     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
 percent                               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
 percent                                  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
 percent                                  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
 percent                                  save state
   /savematrix mtrx currentmatrix def
 percent                                  set local coords
   tailx taily translate   angle rotate
 percent                                  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
 percent                                  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:
 percent                            black arrow to left
   newpath
   318 340 72 340 10 30 72 arrow
   0 setgray fill
 percent                            outline arrow to upper right
   newpath
   382 400 542 560 72 232 116 arrow
   3 setlinewidth stroke
 percent                            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

 percent                            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


               COMBINING TWO POSTSCRIPT FILES

Sometimes, one would like to combine two independent plots in AIPS
into one PostScript file for inclusion in a talk or paper.  In
particular, task HUINT can make a "true-color" image plus a
two-dimensional true-color step wedge.  KNTR or GREYS (with LTYPE=7
to reduce the extraneous text lines) plus LWPLA can then make two
PostScript files which one would like to combine into a single file.
Exactly what one does to do this will depend on what one wants to get
in the end, so keep looking at the plot in ghostview at every step in
the process.

1. Simply append the wedge PostScript file at the end of the image
file to start with.

2. At the beginning is a set of commands, 1 "moveto", 4 "lineto"'s,
followed by a "fill stroke".  This sets the background color which you
may wish to change from black by putting a
     r g b setrgbcolor
command ahead of the moveto - e.g.
   1.000 1.000 1.000 setrgbcolor
   150   742 moveto  2400   742 lineto  2400  2554 lineto
   150  2554 lineto 150   742 lineto fill stroke
for a white background.

3. With color and grey-scale images, AIPS first draws the multi-bit
image and then paints the labeling (so that the tick marks will be on
top of the image and hence visible.)  Thus, the (large) image
grey-scale section of the file may be skipped over in the editor by
searching for, e.g., the string "Declination".  The string Declination
will get you to the axis labeling.  You may wish to add more
setrgbcolor commands here - e.g. 1 1 1 setrgbcolor ahead of the "v"
commands drawing tics inside the plot followed by 0 0 0 setrgbcolor
ahead of the commands writing text outside the image:
   570   944 m 1.000 1.000 1.000 setrgbcolor   569   900 v
   569   900 m 0.000 0.000 0.000 setrgbcolor
   (17 52)  0  -113   -62 c

4. Working through the concatenated file, following the image
labeling, you will encounter the trailing comments from the image
PostScript file and preliminary somments from the wedge file.  Delete
these.  Thus the end of the image plot - start of the wedge plot will
look something like:

  2306  2013 m  2350  2014 v
  2306  1705 m  2350  1706 v
  2306  1397 m  2350  1397 v
  2306  1089 m  2350  1089 v
stroke
 percent   step wedge addition
 0 1000 translate
 percent Start grey-scale at plane    1
     1     4 m   413  1547 m
/hafpix    -2 def
/hafpiy    -2 def
/pscalx  1937 def
/pscaly     4 def
/npix     620 def
 G
00020A00061600071C000820000923000A26000A29000B2B000C2D000C2F000D31000D33

where the first four lines are right hand tick marks, "stroke"
completes the image section, the "0 x translate" is added to move the
wedge above the image, and the remainder shows the first lines of the
wedge file retained in the combined file.

The translate means that we do not have to change other Y position
values, they are now wrt that translation point (which may need
adjusting).

5. The wedge labeling comes at the end of the wedge grey-scale values
- i.e. almost at the end of your combined PostScript file.  You will
probably want to change the axis label strings.  The "c" command has 4
arguments - the string in parentheses, the angle, an X, and a Y
offset.  To change the vertical label, change the string and the Y
offset (to center it again).  The horizontal tick labels and axis
label may well want to move to the top of the wedge from the bottom.
Thus:

  (Kilo JY/B INT)  0  -158  -116 c
   413  1544 m
   413  1572 m 1.000 1.000 1.000 setrgbcolor   413  1544 v
   413  1544 m 0.000 0.000 0.000 setrgbcolor
   (0.0)   0   -59   -62 c

became, in the final file,

   (Kilo Jy/Beam Intensity)   0  -258  72 c
   413  1544 m
   413  1572 m 1.000 1.000 1.000 setrgbcolor   413  1544 v
   413  1860 m 0.000 0.000 0.000 setrgbcolor
   (0.0)   0   -59   12 c

Note that we leave the "m" commands alone and just change the offset
(in the "c" command) from those reference positions.

7. Finally at the end of the file, the upper Y value (4'th value) of
the " percent percentBoundingBox:" command will need to be increased to include the
full size of the image and wedge.

8. Keep checking your changes with gv (ghostview) to make sure they
are what you want.  Re-set BoundingBox to include everything but
without too much white around the edges.

9. If you choose to change the font size or type, you will probably
want to change the offsets.  LWPLA chooses offsets based on the font
type and size it uses, so they are in general not correct for some
significantly different font size.

                         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.

AIPS