; TVDIC
;---------------------------------------------------------------
;! Task to copy a TV screen-image to a Dicomed film recorder.
;# TASK TV HARDCOPY
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2008
;;  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
;-----------------------------------------------------------------------
;---------------------------------------------------------------
TVDIC     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
TVDIC: Task to copy a TV image to a Dicomed film recorder.
OUTPRINT
                                   Name of the output file.
                                    blank -> place in film
                                             recorder queue.
APARM                              Control parameters:
                                    (1) Film size
                                        0 -> 35mm
                                        1 -> 2"x2"
                                        2 -> 4"x5"
                                    (2) File type
                                        0 -> colour positive
                                        1 -> colour negative
                                        2 -> B/W negative
COPIES               0          99 Number of copies to print.
                                    0 -> 1
FLMCOMM
                                   Comment to be placed in the
                                   Dicomed log file.
----------------------------------------------------------------
TVDIC
Type: task (NRAO specific).
Use:  TVDIC reads the current contents of an AIPS TV screen and
      copies them to an Dicomed image file.  The resulting image
      file is either automatically spooled to the film recorder
      or saved under a name chosen by the user.

      The Dicomed image file format is used only at NRAO
      Charlottesville and at the AOC.
Adverbs:
  OUTPRINT...The name of the image file.  If this is left blank
             then the image file is automatically placed in the
             film recorder queue.  If a name is provided the
             image file will be saved under this name and will
             not be placed in the Dicomed queue.
  APARM......Options.
             (1) The film size.
                 0 -> 35mm
                 1 -> 2"x2" (on 4"x5" Polaroid)
                 2 -> 4"x5" (on 4"x5" Polaroid)
             (2) The film type.
                 0 -> colour positive (slide or Polaroid)
                 1 -> colour negative
                 2 -> B/W negative
  COPIES.....Number of copies to produce.
              0 -> 1
  FLMCOMM...Comment to go into the Dicomed log file.
----------------------------------------------------------------
TVDIC: Task which copies the contents of an AIPS TV screen to
       a Dicomed image file.
DOCUMENTOR: Chris Flatters, NRAO

                         PURPOSE

TVDIC 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 enabled graphics planes are read from the TV device and
written to a Dicomed image file.  This file is either placed in a
queue of images to be exposed on a Dicomed film recorder or saved
under a name specified by the user to be queued by the user.

The Dicomed image file format is NRAO-specific and is only
used at the AOC and at NRAO Charlottesville.

TVDIC replaces the highly non-standard task TVFLM that was
previously used at the AOC.  Unlike TVFLM, TVDIC will
work with any AIPS TV.

                       LIMITATIONS

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

1) Information regarding the zoom and scroll state of the TV
   is not available to TVFLM so that images will be reproduced
   as if they had unit zoom and zero scroll.

   HINT: use the TBLC, TTRC, TXINC and TYINC adverbs to set
         position of an image on the screen and to expand
         small images rather than using hardware zoom and
         scroll if you want to make a hard copy.

2) AIPS TV images are gamma corrected (gamma correction takes
   account of the fact that colour intensity is not linearly
   related to the voltage fed to each of the colour guns).
   Dicomed images are not gamma corrected.  This may lead to
   inaccurate colour reproduction.  Gamma correction of
   Dicomed images is impractical since the correction depends
   on the film stock and the exposure time.

3) Images on black and white film use only the signal from the
   red channel and assume that overlay planes 1 to 3 are
   pure white and overlay plane 4 is black.

   HINT: Do not make black and white hard-copy of pseudocolour
         images.


                 DICOMED IMAGE FILE FORMAT

The Dicomed image format was designed by Arnold Rots.  A Dicomed
image file has three sections.  In order these are the header,
the LUT data (optional) and the image data.

Header
------

The header consists of 8 64-character ASCII "card images" (a
total of 512 bytes).  Each card image contains a number of
keyword and value pairs and is terminated with a newline
(ASCII LF).  The header layout is as follows, where Xs denote
variable fields.

000000000111111111122222222223333333333444444444455555555556666
123456789012345678901234567890123456789012345678901234567890123

Filename: XXXXXXXXXXXXXXXXXX            Origin: XXXXXXXX
Date: XXXXXXXXX     Time: XXXXXXXX      Userno: XXXX
Filmsize: XXXX      Filmtype: XXXXXXX   Copies: XXX
Bits/Pixel: XX      Columns: XXXX       Rows: XXXX
LUTs/Pixelbyte: X   Bits/LUTelement: XX OFMelements: XXXX
LUTpointer: XXXXXX  OFMpointer: XXXXX   Datapointer: XXXXX
Usercomments: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Recorded: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Note that values are left justified within the fields and
padded with blanks.

The header fields are filled in as follows.

Filename........The name under which the image file will be
                queued.  This has the format NNNN_DDD_HHMMSS_V1
                where NNNN is the (decimal) AIPS user number,
                DDD is the day of the year on which the file
                was created and HHMMSS is the time at which
                the file was created.
                Example: 0115_113_123554_V1
Origin..........The hostname of the computer on which the file
                was created.
Date............The file creation date in the format DD-MMM-YY
                where DD is the day, MMM is a 3-letter
                abbreviation for the month (mixed case) and YY
                is the last two digits of the year.
                Example: 22-Apr-92
Time............The file creation time in the format HH:MM:SS.
                Example: 12:35:54
Userno..........AIPS usernumber.
Filmsize........"35mm", "2x2" or "4x5".
Filmtype........"ColPos", "ColNeg", or "B/W"
Copies..........Number of copies to make.
Bits/Pixel......8 for monochrome film; 24 for colour film.
Columns.........Width of image in pixels.
Rows............Height of image in pixels.
LUTs/Pixelbyte..Number of LUTs per channel.
Bits/LUTelement.Number of bits in an LUT output value.
OFMelements.....Number of elements in an LUT.
LUTpointer......Address of the first byte of LUT data or zero
                if there is no LUT.  Uses the UNIX convention
                where the first byte in the file has address 0.
OFMpointer......Address of the first byte of OFM data or zero
                if there no OFMs.  Uses the UNIX convention
                where the first byte in the file has address 0.
Datapointer.....Address of the first byte of image data.  Uses
                the UNIX convention where the first byte in
                the file has address zero.
Comment.........Comment to be written into Dicomed log.
Recorded........Unused.

LUT and OFM data
----------------

TVDIC does not use the Dicomed image file look up tables.

Image Data
----------

Each pixel in a monochrome image is represented by a single byte
value.  Each pixel in a colour image is represented by three
byte values giving its red, green and blue intensities in that
order.  Pixels are written in row-wise order starting from the
top, leftmost pixel and ending with the bottom, rightmost pixel.

                 USING TVDIC AS A PARAFORM

The Dicomed image file specific code is isolated in 3 Z-routines.
ZDICOP opens a Dicomed image file and fills in the header,
ZDICIO writes an image row to file and ZDICCL closes the file
and saves it or places it in the Dicomed queue.  Other hard-copy
devices may be supported by replacing these Z-routines.  You
should also change the name of the task of course.

Other desirable changes are:

1) change the argument list for the ZxxxOP routine: ZDICOP
   has a long argument list most of which is only needed
   to fill in the Dicomed image file header.

2) make sure that rows are written to the image file in the
   order required by the file format for efficiency.

3) add any extra adverbs that may be needed.




