@@
Plot files:                  PLdsssvv



A. Overview


   Plot files are a generalized representation of a graphics display.
They contain scaling information and commands for drawing lines,
pixels, and characters.  Plot files for a certain type of plot
(contour maps, grey scales, etc.) are written by one routine
and then another routine must read the plot file and write to
a particular graphics device (plotter, graphics terminal, ect.).
In AIPS these functions are performed by separate tasks.
This two step approach offers several advantages.  A plot
file may exist for an extended period of time allowing plots to be
written to different devices and copies to be generated at later times
without duplicating the calculations needed in making the plot.
Also only one program for a particular plot need be written instead
of one program for each graphics device.

   I/O to the plot files consists of reading and writing 256-word
blocks.  The logical records are of 6 types and vary in length.  With
the exception of the 'draw pixels' record, logical records do not span
the 256-word blocks.  Unused space at the end of a block consists of
integer zeros.  All values in the plot file are I*4, R*4, L*4 variables
or ASCII characters.  This aids in exporting plot files to other
computers via tape.  Plot files have names of the format PLdsssvv,
where d is the disk volume number, sss is the Catalog slot number of
the associated map, and vv is the version number.  Plot files are
usually extension files associated with a cataloged map or uv data
set.



B. Record layouts


(0)  The first physical record(s)

     contains information about the task which created the file.  It
     is not logically part of the "plot file", but is there to provide
     documentation of the file's origins should it be needed.  The
     first logical record (see below) starts in word 1 of the second
     physical record in the file.  The contents of the first physical
     record are task-dependent and have the form:

FIELD   TYPE        DESCRIPTION
  1.    I*4(3)       Task name (2 chars / word)
  2.    I*4(6)       Date/time of file creation YYYY,MM,DD,HH,MM,SS
  3.    I*4          Number of words of task parameter data
  4.    R*4(*)       Task parameter block as transmitted from AIPS
                     (preferably with defaults replaced by the values
                      used).

      Starting in early 2023, a new record was added that simply lists the
      adverb names of the plot task with 8 characters (2 hollerith words)
      per adverb.  One record is sufficient for all tasks.

--------------------------------------------------------------------------
(1)  Initialize plot record.  GINIT

       The first logical record in a plot file must be of this type.

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equal to 1 for this record type).
  2.   I*4      User number.
  3.   I*4(3)   Date:  yyyy, mm, dd
  4.   I*4      Type of plot:  1 = miscellaneous
                               2 = contour
                               3 = grey scale
                               4 = 3D profile
                               5 = slice
                               6 = contour plus polarization lines
                               7 = histogram
                 and many more numbers reserved for each plot task
                 see precursor comments in $YSUB/GINIT

--------------------------------------------------------------------------
(2)  Initialize for line drawing record.  GINITL

       This record provides scaling information needed for a plot.
    The plot consists of a 'plot window' in which all lines are drawn
    and a border (defined in terms of character size) in which
    labeling may be written.  The second record in a plot file must be
    of this type.

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equal to 2 for this record type).
  2.   I*4      X Y ratio * 100.  The Ratio between units on the X axis
                and units on the Y axis (X / Y).  For example if the
                decrement between pixels in the X direction on a map
                is twice the decrement in the Y direction the X Y ratio
                can be set to 2 to provide proper scaling.  Some
                programs may ignore this field.  For example IISPL when
                writing grey scale plots to the IIS.
  3.   I*4      Scale factor (currently 16383 in most applications).
                This number is used in scaling graph positions before
                they are written to disk.  BLC values in field 4 are
                represented on disk by zero and TRC values are
                represented by integers equal to the scale factor).
  4.   I*4(4)   The bottom left hand corner X and Y values and the top
                right hand X and Y values respectively in the plot
                window (in pixels).
  5.   I*4(4)   1000 * the fractional part of a pixel allowed to occur
                outside the (integer) range of BLC and TRC (field 4
                above) in line drawing commands
  6.   I*4(4)   10 * the number of character positions outside the plot
                window on the left, bottom, right, and top respectively
  7.   I*4(5)   Location of the X Y plane on axes 3,4,5,6,7.  This
                field is valid only for plots associated with a map.

--------------------------------------------------------------------------
(3)  Initialize for grey scale record.  GINITG (code 13), GINITC (code 12)

       This record if needed must follow the 'init for line drawing'
    record.  This record allows proper interpretation of pixels for
    raster type display devices.  Programs that write to line drawing
    type devices (e.g. the TEKTRONIX 4012) ignore this record.

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equals 3 for this record type).
  2.   I*4      Lowest allowed pixel intensity.
  3.   I*4      Highest allowed pixel intensity.
  4.   I*4      Number of pixels on the X axis.
  5.   I*4      Number of pixels on the Y axis.

--------------------------------------------------------------------------
(4)  Position record.   GPOS

       This record tells a device where to start drawing a line,
    row/column of pixels or character string.

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equals 4 for this record type).
  2.   I*4      scaled x position i.e. a value of 0 represents the
                BLC values defined in the 'init for line drawing'
                record, and a value equal to the scale factor
                represents the TRC value.
  3.   I*4      Scaled Y position.

--------------------------------------------------------------------------
(5)  Draw vector record.    GVEC

       This record tells a device to draw a line from the current
    position to the final position specified by this record.

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equals 5 for this record type).
  2.   I*4      Scaled final X position.
  3.   I*4      Scaled final Y position.

--------------------------------------------------------------------------
(6)  Write character string record.    GCHAR, GICHAR

       This record tells a device to write a character string starting
    at the current position outside the main plot area (i.e. axis labels)

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equals 6 for this record type).
  2.   I*4      Number of characters.
  3.   I*4      Angle code: 0 = write characters horizontally.
                            1 = write characters vertically.
  4.   I*4      X offset from current position in characters * 100
  5.   I*4      Y offset from current position in characters * 100
                (net position refers to lower left corner of 1st char)
  6.   I*4(n)   ASCII characters (n = INT((field2 + 3) / 4))

--------------------------------------------------------------------------
(7)  Write pixels record.    GRAYPX

       This record tells a raster type device to write an n-tuple of
    pixel values starting at the current position.  Programs that write
    to line drawing type devices ignore records of this type.

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equals 7 for this record type).
  2.   I*4      Number of pixel values.
  3.   I*4      Angle code: 0 = write pixels horizontally.
                            1 = write pixels vertically (up).
  4.   I*4      X offset in characters * 100.
  5.   I*4      Y offset in characters * 100.
  6.   I*4(n)   n (equal to field 2) pixel values.

--------------------------------------------------------------------------
(8)  Write misc. info to image catalog record.

        This record tells the programs that write to interactive
     devices (TEKPL, IISPL) to put up to 20 words of miscellaneous
     information in the image catalog starting at word I2TRA + 2.
     This information is interpreted by routines such as AU9A
     ( TKSKYPOS, TKMAPPOS, ect.).  Routines that write to non-
     interactive graphics devices (LWPLA) ignore this record.

FIELD  TYPE      DESCRIPTION
  1.   I*4       Opcode (equals 8 for this record type).
  2.   I*4       Number of words of information.
  3.   I*4(n)    Miscellaneous info (n=value of field 2).

--------------------------------------------------------------------------
(9) Write line type record        GLTYPE

        This record defines a "line type" which is sometimes used t
     set graphics colors.  Initial definition 1 exterior labeling,
     2 contours, 3 polarization vectors, 4 stars, ?

FIELD  TYPE      DESCRIPTION
  1.   I*4       Opcode (equals 9 for this record type).
  2.   I*4       Line type

--------------------------------------------------------------------------
(10)  Draw dark vector record.     GDVEC

       This record tells a device to draw a black line from the current
    position to the final position specified by this record.

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equals 5 for this record type).
  2.   I*4      Scaled final X position.
  3.   I*4      Scaled final Y position.

--------------------------------------------------------------------------
(11)  Write 3-color pixels record.    G3COLR

       This record tells a raster type device to write an n-tuple of
    pixel values starting at the current position.  Programs that write
    to line drawing type devices ignore records of this type.

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equals 7 for this record type).
  2.   I*4      Number of pixel values.
  3.   I*4      Angle code: 0 = write pixels horizontally.
                            1 = write pixels vertically (up).
  4.   I*4      X offset in characters * 100.
  5.   I*4      Y offset in characters * 100.
  6.   I*4(3*n) n (equal to field 2) pixel values.

--------------------------------------------------------------------------
(12)  Initialize for 3-color grey scale record.  GINITC

       This record if needed must follow the 'init for line drawing'
    record.  This record allows proper interpretation of pixels for
    raster type display devices.  Programs that write to line drawing
    type devices (e.g. the TEKTRONIX 4012) ignore this record.

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equals 12 for this record type).
  2.   I*4      Lowest allowed pixel intensity.
  3.   I*4      Highest allowed pixel intensity.
  4.   I*4      Number of pixels on the X axis.
  5.   I*4      Number of pixels on the Y axis.
  6.   H*4      Transfer function (2 chars)
  7.   R*4(6)   Intensity range (min,max for R G B)

--------------------------------------------------------------------------
(13)  Initialize for grey scale record.  GINITG

       This record if needed must follow the 'init for line drawing'
    record.  This record allows proper interpretation of pixels for
    raster type display devices.  Programs that write to line drawing
    type devices (e.g. the TEKTRONIX 4012) ignore this record.

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equals 12 for this record type).
  2.   I*4      Lowest allowed pixel intensity.
  3.   I*4      Highest allowed pixel intensity.
  4.   I*4      Number of pixels on the X axis.
  5.   I*4      Number of pixels on the Y axis.
  6.   H*4      Transfer function (2 chars)
  7.   R*4(2)   Intensity range (min,max)

--------------------------------------------------------------------------
(14)  Write character string record.    GICHAR

       This record tells a device to write a character string starting
    at the current position inside the main plot in bright characters.

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equals 14 for this record type).
  2.   I*4      Number of characters.
  3.   I*4      Angle code: 0 = write characters horizontally.
                            1 = write characters vertically.
  4.   I*4      X offset from current position in characters * 100
  5.   I*4      Y offset from current position in characters * 100
                (net position refers to lower left corner of 1st char)
  6.   I*4(n)   ASCII characters (n = INT((field2 + 3) / 4))

--------------------------------------------------------------------------
(15)  Write dark character string record.    GICHAR

       This record tells a device to write a character string starting
    at the current position inside the main plot area and i black characters.

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equals 15 for this record type).
  2.   I*4      Number of characters.
  3.   I*4      Angle code: 0 = write characters horizontally.
                            1 = write characters vertically.
  4.   I*4      X offset from current position in characters * 100
  5.   I*4      Y offset from current position in characters * 100
                (net position refers to lower left corner of 1st char)
  6.   I*4(n)   ASCII characters (n = INT((field2 + 3) / 4))

--------------------------------------------------------------------------
(16) Set colors for 3-color line drawing   G3VCOL

       This records sets the RGB colors for color line drawing.

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equals 16 for this record type).
  2.   I*4      RGB colors to use

--------------------------------------------------------------------------
(17)  Draw 3-color vector record.   G3VEC

       This record tells a device to draw a line from the current
    position to the final position specified by this record in the
    current colors.

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equals 17 for this record type).
  2.   I*4      Scaled final X position.
  3.   I*4      Scaled final Y position.

--------------------------------------------------------------------------
(18)  Add comment to PostScript file  GCOMNT

       This record tells LWPLA to add a comment line to the PostScript
    file.

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equals 18 for this record type).
  2.   I*4      Number of characters in comment
  3.   H*4(n)   Comment characters n = (NCHAR+3)/4

--------------------------------------------------------------------------
(19)  Write 3-color character string record.    G3CHAR

       This record tells a device to write a character string starting
    at the current position inside the main plot in bright 3-color
    characters.  Uses colors set by OPCODE 16.

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equals 19 for this record type).
  2.   I*4      Number of characters.
  3.   I*4      Angle code: 0 = write characters horizontally.
                            1 = write characters vertically.
  4.   I*4      X offset from current position in characters * 100
  5.   I*4      Y offset from current position in characters * 100
                (net position refers to lower left corner of 1st char)
  6.   I*4(n)   ASCII characters (n = INT((field2 + 3) / 4))

--------------------------------------------------------------------------
(32767) This record marks the end of a plot file.   GFINIS

FIELD  TYPE     DESCRIPTION
  1.   I*4      Opcode (equals 32767 for this record type).


@@
C. Subroutines and Commons for Writing.

GINIT   Creates and opens a plot file, initializes the graphics
        common GPHCOM and writes an 'Initialize plot' record.
GINITL  Writes an 'init for line drawing' record to the plot file.
GINITG  Writes an 'init for grey scale' record to a plot file.
GPOS    Writes a 'position' record to the plot file.
GVEC    Writes a 'draw vector' record to the plot file.
GCHAR   Writes a 'write character string' record to the plot file.
GRAYPX  Writes a 'write pixels' record to the plot file.
GFINIS  Writes an 'end of plot' record to the plot file and closes
        the file.
GPHWRT  This routine is called by the above routines if I/O is needed.
        It writes the current buffer to the plot file and zeros the
        buffer.  Then the record count and buffer position pointer
        are updated in common GPHCOM.

Other routines in $YSUB as listed with each record type.

GPHCOM  (common) contains variables used for inter-subroutine
        communication.  It is declared by including DGPH.INC and has
        the structure:
           GPHSIZ  I*4      File size in 256-word blocks
           GPHLUN  I*4      Logical unit number
           GPHIND  I*4      Pointer to FTAB
           GPHPOS  I*4      Position in work buffer of last word used
           GPHRRN  I*4      Number of records written
           GPHVOL  I*4      Disk volume number
           GPHTLO  I*4      Lowest allowed pixel value
           GPHTHI  I*4      Highest allowed pixel value
           GPHX1   R*4      Leftmost (col) pixel position
                            (as passed in file logical record type 2,
                             field 4 above; i.e. integer part)
           GPHX2   R*4      Rightmost (col) pixel position
           GPHY1   R*4      Lowest (row) pixel position
           GPHY2   R*4      Highest (row) pixel position
           GPHNAM  C*48     Physical file name
           TVSUBR  C*6      Subroutine causing error GCINIT, YIMGIO
           GPHFUN  C*2      Transfer function to use for grey scale
           GPHDOT  L*4      DOTV
        parameters below for use when plot on TV
           GPHPAG  L*4      if true: wait for permission to plot next page
           GPHDOD  L*4      always true, allows dark vectors
           GPHCRN  I*4(2)   pixel of plot origin, often 0,0
           GPHTVC  I*4(3)   basic and secondary grey-scale TV channels
           GPHTVG  I*4(8)   selected graphics channel number(s)
           GPHIX0  I*4      TV pixel left corner of plot coordinates
           GPHIX1  I*4      BLC(1)
           GPHIX2  I*4      TRC(1)
           GPHIXL  I*4      Current X position
           GPHIY0  I*4      TV pixel lower corner of plot coordinates
           GPHIY1  I*4      BLC(2)
           GPHIY2  I*4      TRC(2)
           GPHIYL  I*4      Current Y position
           GPHTVW  I*4(4)   Current visible TV pixel window
           GPHCHL  I*4      Left TV pixels for external characters
           GPHCHB  I*4      Bottom TV pixels for external characters
           GPHCHR  I*4      Right TV pixels for external characters
           GPHCHT  I*4      Top TV pixels for external characters
           GPHNGR  I*4      Unused
           GPHCAT  I*4(256)     Header for TV plot
           GPHSCR  I*4(MAXIMG)  Temporary scratch memory
           GPHERO  I*4      Counts characters omitted due to overlaps
           GPHERG  I*4      Counts grey-scale lines truncated at edges
           GPHERC  I*4      Counts characters truncated at edges
           GPHERV  I*4      Counts vectors truncated at edges
           GPHPLX  I*4(2)   Previous character string X range
           GPHPLY  I*4(2)   Previous character string Y range
           GPHCNT  I*4      Counts vector commands.
                            YHOLD turned off at 5000, back on.
           GPHLTY  I*4      Current graphics line type
           GPHCON  I*4(32)  =1 -> channel initialized,
                                  catalog updated at end
           GPHCOL  I*4(3)   RGB colors for colored vectors, characters
           GPHSCX  R*4      TRC(1) - BLC(1)
           GPHSCY  R*4      TRC(2) - BLC(2)
           GPHRX1  R*4      Non-integer difference BLC(1) and GPHIX1
           GPHRX2  R*4      Non-integer difference TRC(1) and GPHIX2
           GPHRY1  R*4      Non-integer difference BLC(2) and GPHIY1
           GPHRY2  R*4      Non-integer difference TRC(2) and GPHIY2
           GPHCUT  R*4      0.33333 level above which dark is used
                            for contour lines and stars

        This common is handled fully by the routines listed here.  A
        user of these routines only needs to declare the common in his
        main program to insure that adequate space is reserved for it.


D. Tasks for Reading.

TVPL     Reads a plot file and writes the corresponding commands
         to the TV "device".
LWPLA    Reads a plot file, generates a PostScript file for immediate
         printing or to be saved for use in documents
