; CANPL
;---------------------------------------------------------------
;! translates a plot file to a Canon printer/plotter
;# Task Plot
;-----------------------------------------------------------------------
;;  Copyright (C) 1995
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
CANPL     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
CANPL:  Task to send a plot file to the Canon printer/plotter
USERID     -32000.0     32000.0    User ID. 0 => current user
                                     32000 => all users
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
ASPMM           0.0                Arc sec. per mm. 0=self scale
COPIES          0.0        99.0    Number of copies needed.
LPEN            0.0         4.0    Pen width 0 => 2.
                                   1 => thin
                                   2 => moderately thin
                                   3 => moderately thick
                                   4 => thick
OUTFILE
                                   Save output in file named ..
                                   ' ' => print and delete
OPTYPE                             Type of grey scale encoding
                                   'NONE','QRAN','MRAN','RAND',
                                   'BITS' -- else 'MBIT'
FUNCTYPE                           'NE','LG','NG','PL','NL'
                                         else linear
FACTOR                             Power law index for use with
                                     'PL' or 'NL' FUNCTYPE's
AXVAL                              (1) Input and (2) output
                                   values at inflection point
DPARM                              (1,2) Clip recorded greys
                                       before FUNCTYPE (0 to 1)
                                   (3,4) After FUNCTYPE scale
                                       by g*DPARM(3) + DPARM(4)
                                   Parms for .BIT. modes:
                                   (5) 0, 2 => ignore DPARM
                                       1, 3 => use DPARM
                                       0, 1 => Gaussian mask
                                       2, 3 => Sine wave mask
                                   (6) size of mask in dots
                                   (7) Linear scale factor
                                   (8) x-shift of function
                                   (9) y-shift of function
                                   For .MRAN. and .MBIT. modes:
                                   (10) plot DPARM(10) levels
----------------------------------------------------------------
CANPL:Task
Use:  CANPL will find an extension file of type PL and use the
      graphics commands in that file to display the image on
      the Canon LPB-8 laser printer.
Adverbs:
  USERID......The ID of the owner of the image.  0 => current
              user.  32000 => any user.
  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 #
  ASPMM.......Arc seconds per millimeter.  0 => self scale.
  COPIES......Number of copies to make.  0 => 1.
  LPEN........Width of lines. 0 => 2.
                                   1 => thin
                                   2 => moderately thin
                                   3 => moderately thick
                                   4 => thick
  OUTFILE.....If not blank, write the output print file to the
              specified file name and print it.  If blank, print
              and delete the output.
  OPTYPE......Determines the method by which grey scale images
              are converted to dots on the paper: 'NONE' means
              to suppress the grey scales.  'MBIT', 'QRAN',
              and 'MRAN' use "fonts" loaded into the QMS, which
              is fast but may have bad repetitive dot patterns.
              QRAN uses a random number generator to generate 26
              levels and a random number to choose which of 3
              equal versions of that level are used for each
              pixel.  'MRAN' uses 78 levels instead but uses a
              fixed "character" for each level.  'MBIT' is like
              'MRAN' but instead of a random number font, it
              uses one generated by the Starlink algorithm.
              'RAND' uses a random number generator to set each
              dot and 'BITS' uses a STARLINK method of comparing
              the value with a mask pattern.  The last two are
              very slow.
  FUNCTYPE....Convert the recorded grey levels using inverse
              linear ('NE'), logarithmic ('LG'), inverse log
              ('NG'), power law ('PL'), inverse power law
              ('NL') or linear (anything else).  Note that
              linear produces "negative" images --- ones in
              which the most intense sources are the blackest.
  FACTOR......Specifies the power law index used in converting
              the recorded grey levels when FUNCTYPE 'PL' or
              'NL' is specified.  < 0.001 or > 999. => 1.0
  AXVAL.......Specifies the input and output values of the
              inflection point in the transfer function between
              a 1./FACTOR and FACTOR power law. (0,0) => simple
              FACTOR power law.  If either value is outside the
              range 0.001 - 0.999, a simple power law is used.
  DPARM.......(1,2) The recorded grey 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 < DPARM(3) < 100, -0.9 < DPARM(4) < 0.9.
                 When using 'NE' or 'NG' functions, it is often
                 good to limit the darkest areas if they are
                 large to grey (i.e. DPARM(3) around .85).
  Parameters which control the mask generation for .BIT. OPTYPEs
              DPARM(5): = 0 -> use Gaussian with defaults
                        = 1 -> use Gaussian with DPARM parms
                        = 2 -> use Sine with defaults
                        = 3 -> use Sine with DPARM parameters
                        < 0 or > 3 => 0.
              DPARM(6): mask size in dots, default = 8.
                        (< 0 for 'MDOT' => force to this, else
                        MDOT uses between 7 and 13 to come close
                        to the desired ASPMM.)  Let mx, my =
                        mask size in x, y (in dots). Then
              DPARM(7): G = e ** (-D(2) * x * x/ ((mx/4)**2))
                        S = sin (2PI * D(2) * x / mx)
                        default = 1.0
              DPARM(8): X-shift of function wrt dots in dots
                        default = 0.25 * (mx/8.0), limit < 0.9.
              DPARM(9): Y-shift of function wrt dots in dots
                        default = 0.133 * (my/8.0), limit < 0.9.
----------------------------------------------------------------
Explanation of CANPL

Notes on scaling grey levels:

(1) GREYS puts the user-specified image intensities into the
    plot file in a form which is converted to the range 0.0
    to 1.0 by CANPL.
(2) Then CANPL clips these intensities, setting any < DPARM(1)
    to DPARM(1) and any > DPARM(2) to DPARM(2) where 0 <=
    DPARM(1) < DPARM(2) <= 1.0.  The range DPARM(1) - DPARM(2)
    is then rescaled to 0 - 1.
(3) Then CANPL applies a transfer function which can be linear
    (do nothing), negative linear (v = 1-v), logarithmic
    (v = log10(30*v+1)/log10(30.42) -  .007), negative log
    (v=1-v, then log), power law (v = v ** FACTOR) or negative
    power law (v=1-v, then power law).  A two part power law
    with inflection point is obtained with nonzero values of
    AXVAL yielding v = AXVAL(2)*(v/AXVAL(1))**(1/FACTOR)
    for v < AXVAL(1), and v = AXVAL(2)+(1-AXVAL(2))*
    ((v-AXVAL(1))/(1-AXVAL(1)))**FACTOR for v > or = AXVAL(1).
    These functions convert the range 0 - 1 into the range 0 - 1
(4)  Then CANPL rescales the image data as v = DPARM(3) * v +
     DPARM(4) and clips it at 0 and 1.
The results of all this are converted into a grey level on the
paper.
