; TVCPS
;---------------------------------------------------------------
;! Task to copy a TV screen-image to a PostScript file.
;# TASK TV HARDCOPY
;-----------------------------------------------------------------------
;;  Copyright (C) 1995-1996, 2001, 2003
;;  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
;-----------------------------------------------------------------------
TVCPS     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
TVCPS:  Task to copy a TV image to a PostScript file.
OUTFILE
                                   Name of the output file.
                                    blank -> place in printer
                                             queue.
COPIES         0.0        50.0     Number of copies if going
                                   directly to a printer
GRCHAN               0   88888888  Graphics channels included.
                                   0=>none; 12345678=>all on.
APARM                              Miscellaneous controls
                                   Paper size:
                                    (1) width
                                    (2) height
                                    (3) margin
                                    (4) units: 0 = in, 1 = cm
                                               2 = pt
                                   Gamma correction (see help)
                                    (5) red channel gamma
                                    (6) green channel gamma
                                    (7) blue channel gamma
                                   Labeling
                                    (9) > 0 -> use portrait
                                        shape always
                                    (10) > 0 -> Use CMYK color
                                       rather than RGB.
OPCODE                             'COL ' or '    ' - produce
                                      color output
                                   'GREY' or 'GRAY' or 'B/W ' -
                                      produce grey-scale output
                                   'COLB' - color with blanked
                                      pixels white (DOINV <= 0)
ASPMM                              Scaling factor (arcsec/mm)
                                      (<= 0) => fill page.
DOINVERS       -1.0         1.0    > 0 invert grey scales
DOTV           -2.0         1.0    < -1 => read image from disk
TBLC            0.0      4096.0    Bottom Left Corner of image
                                     0=>entire image
TTRC            0.0      4096.0    Top Right Corner of image
                                     0=>entire image
TXINC        -100.0       256.0    Load every TXINC'th column
TYINC        -100.0       256.0    Load every TYINC'th row
REASON                             String added at bottom
----------------------------------------------------------------
TVCPS
Type: task.
Use:  TVCPS reads the current contents of an AIPS TV screen and creates
      a PostScript file that will produce a hard copy of the image on
      the TV screen.
Adverbs:
  OUTFILE....The name of the PostScript file.  If this is left blank
             then the it is automatically placed in the current AIPS
             printer queue.  If a name is provided, the PostScript image
             file will be saved under this name and will not be placed
             in the printer queue.
  COPIES.....Number of copies to print (0 => 1).  Set to 1 when OUTFILE
             is specified.
  GRCHAN.....Decimal coded list of graphics channels to include in the
             output image.  For example, if GRCHAN = 241 then graphics
             planes 1, 2 and 4 will be included in the output image EVEN
             IF THEY ARE NOT CURRENTLY VISIBLE.  If GRCHAN=0, then the
             graphics overlays will not appear in the PostScript output
             even if they are currently visible.  GRCHAN=12345678 => all
             graphics planes included.
  APARM......Miscellaneous controls
             Page size.
             (1) - width.  Default = 8.5 in.
             (2) - height. Default = 11 in.
             (3) - minimum margin to leave on each side. Default 0.5 in
             (4) - units for width and height.
                   0 - inches
                   1 - cm
                   2 - points
             (5,6,7) Gamma correction to use (red,green,blue)
                 < 0  => remove the TV gamma correction, but add none.
                 >= 0 & < 0.1 => use TV gamma correction in the color
                 PostScript
                 >= 0.1 & < 10 => remove TV gamma correction and apply
                 APARM(5) to red, APARM(6) to green, and APARM(7) to
                 blue instead.  If APARM(6) and/or APARM(7) are zero,
                 APARM(5) is used for them.
                 The color values (0 <= v <= 1) are adjusted by
                 v' = v ** (1/gamma).  This is done to the graphics as
                 well as the black-and-white or color grey-scales.
             (8) Not currently used.
             (9) TVCPS will use landscape mode (x-axis along height)
                 whenever that produces a better fit to the paper.  To
                 force it to use portrait mode at all times, set
                 APARM(9) to a positive number.
             (10) > 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.
                 TVCPS will convert the RGB of the TV to CMYK using
                 the simple formulae (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.  The default gamma
                 corrections (APARM(5)-APARM(7) = 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.
  OPCODE.....Color or grey-scale output: 'GREY', 'GRAY' or 'B/W ' ->
             grey-scale output, otherwise color.  Pure zero pixels
             (blanked or edge) are black unless OPCODE = 'COLB' where
             they are made white.  The latter is transparent on some
             color printers.  'COLB' does nothing when DOINV > 0.
  ASPMM......If positive, the scale of the output image in arcseconds
             per millimeter.  If this is negative or zero the image
             will be scaled to fit the paper.  If ASPMM is positive
             and more than one image is displayed on the screen then
             you will be asked to select the image to which the
             scaling will be applied.
  DOINVERS...Normally areas that are dark on the TV screen are shown as
             dark on the output PostScript printer.  To reverse this,
             set DOINVERS > 0.  One might wish to do this in some cases,
             because printers do not show large areas of black well.
  DOTV.......If DOTV < -1, then the TV is used to set the intensity
             range, function type, and enhancements, but the image data
             are read from disk and the plot size is set by the size of
             the image read.  If DOTV >= -1 (its normal range of
             values), then the TV provides the data and the size of the
             visible screen (not the area actually used) sets the plot
             size.  If DOTV < -1, the graphics planes are ignored.
             NOTE: This option only works when the image on the TV was
             loaded from the current AIPS session (or at least an AIPS
             session with the same disk assignments).
  TBLC.......The Bottom Left-hand pixel of the sub-array of the map to
             be displayed when DOTV < -1.   0 => 1 in each axis.
  TTRC.......The Top Right-hand pixel of the sub-array of the map to be
             displayed when DOTV < -1.  TTRC(3-7) are ignored and 0 =>
             the full image on that axis.
  TXINC......Use every TXINC'th column beginning at TBLC when DOTV < -1.
             0 => 1
  TYINC......Use every TYINC'th row beginning at TBLC when DOTV < -1.
             0 => 1
  REASON.....User text to add at bottom of plot along with (optionally)
             the AOC management user number string.
----------------------------------------------------------------
TVCPS: Task which copies the contents of an AIPS TV screen to a
       PostScript file.
DOCUMENTER: Chris Flatters, NRAO

                         PURPOSE

TVCPS is used to make a hard copy of the contents of an AIPS TV display.
The contents of all enabled grey-scale planes and all graphics planes
specified in GRCHAN are read from the TV device and written to a
PostScript file.  This file is either placed in the current AIPS printer
queue or saved under a name specified by the user.  The file is always
encapsulated.

                       LIMITATIONS

TVCPS will not provide a perfect reproduction of the TV display.

1) AIPS TV images are gamma corrected (gamma correction takes account of
   the fact that color intensity is not linearly related to the voltage
   fed to each of the color guns). Gamma correction is applied to the
   output image by APARM(5), APARM(6), and APARM(7).  The higher the
   gamma correction the brighter are the low levels.

2) Grey-scale images use the image intensities from the red channel and
   assume that overlay planes 1 to NGRAPH-1 are pure white and overlay
   plane NGRAPH (now 8 with XAS) is black.
   HINT: Do not make black and white hard-copy of pseudocolour images.

3) Further hints: turn off the grey channels you do not want.  Channels
   which are merely cleared are read and computed upon, even if they are
   all zero.  Select only those graphics channels you want with GRCHAN.
   All selected graphics channels are read and computed even if they are
   all zero or if they are not currently visible.

TVCPS does honor zoom and scroll, giving as faithful a representation of
what you see on the TV screen as possible.


                 NOTES ON THE POSTSCRIPT OUTPUT

Color images from TVCPS can only be handled by Level 1 PostScript
interpreters that support the CMYK operators or by Level 2 PostScript
interpreters.  In general this includes color printers and film
recorders but not some ordinary laser printers.  Don't try sending a
color image to any device unless you are sure that it can handle it.
AIPS will detect the presence of color in your file and send it to a
color printer if there is one defined for your site (if INFILE was not
specified).

Grey-scale images can be handled by any PostScript interpreter.

Encapsulated PostScript files contain information that allows images
defined in them to be included in other documents.

TVCPS output conforms to version 3.0 of the Document Structuring
Conventions including version 3.0 of the Encapsulated PostScript File
Format.

                         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.
