Help for UNMOSAIC

PURPOSE:  UNMOSAIC will separate the elements of a Galileo SSI on-chip
  mosaic (OCM) image.

EXECUTION:

  UNMOSAIC  INP=S0001234568.MM2  DIR=WMS_GLL:[SSI.UDR]          CATSRV=MIPSDB1 CATDB=devCat CATUSR=xxx  CATPW=xxxxxx          AREAS=(sclk1,sl1,ss1,el1,es1,                 sclk2,sl2,ss2,el2,es2,                 sclk3,sl3,ss3,el3,es3,                 ...............
               sclkN,slN,ssN,elN,esN)
where

  INP is an SSI UDR or merged UDR of an OCM (800x800 full-frame or 400x400
    summation-mode).  UNMOSAIC is restricted to Phase 2 UDR formats and will
    not process images acquired during the Shoemaker-Levy impact.  The expected
    standard naming scheme of the file is ?XXXXXXXXXX.?Y (where ? is any
    alphanumerical string ending with an alphabetical character, the 10 X's are
    10 numerical digits that signifies the parent SCLK, and Y is the parent 
    raw number for ssiraw). See help for PARENTSCLK or PARENTRAWNUM if the file
    name is not of the standard naming.
  DIR specifies the disk and directory for the output UDRs.
  CATSRV is the name of the catalog server.
  CATDB is the name of the Sybase catalog.
  CATUSR is the user's Unix ID.
  CATPW is the user's Sybase password.
     Note that parameters CATSRV, CATDB, CATUSR, and CATPW are case sensitive.
  AREAS specifies the areas corresponding to the elements (exposure) of the
    mosaic.  Each area is specified by 5 integers: spacecraft clock
    (100*RIM+MOD91), starting line, starting sample, ending line, and
    ending sample).

The maximum number of output images (N) is 100.  Multiple executions can be
used to process OCMs consisting of more elements.

UNMOSAIC should be followed by executing CATLABEL on each output file created
to replace various label items with those corresponding to each exposure of
the OCM.

NEW FEATURES SINCE THE LAST DELIVERY

Version (January 15, 1997):
The program will call ABEND if ssioverview's predgainmodeid is greater than 3,
which denotes an undefined value according to current SIS.  Reason for this is
that this value determines the value of the GAIN in binary label, and if not
defined will affect subsequent programs on the image to fail.

Version (June 16, 1997):
If ssioverview's predfiltname or predframedur is undefined, the program will 
display an appropriate error message and call ABEND. This prevents NULL values
from appearing in the database.

SPECIAL FEATURE

UNMOSAIC, although not normally needed, will process input image which does not
contain binary label.  Much of the calculation and information exchange between the binary header and catalog would be lost when using this feature.  Since 
this was not formally specified, nor would it be used often there is not a
definite behavior that one can expect; however, the program basically should
behave as normal as the absence of binary label would allow.

BACKGROUND

On-chip mosaics (OCMs) are images acquired in a multiple exposure/single read-
out mode.  A typical application is where four images of a target-body are
acquired by slewing the camera (and stepping the filter wheel) to image the
target in each of the four corners of the CCD array.  CCD read-out is suppressed
until all four exposures are completed, thus resulting in a 2x2 mosaic.  3x3,
5x5, or nxm mosaics are possible, where n and m are limited only by the pixel
diameter of the target and pointing accuracy of the scan platform.

The OCM is referred to as the parent frame.  When the OCM is separated into
areas, the resulting UDRs are referred to as its children.  Predict information
for each child (exposure) is stored in the Overview table of the SSI Catalog.

The onchipmosaicflag and prtsclkstrtcnt fields of the Overview table are used
to identify the children of an OCM and match them with the SCLK of their parent.

The following is a typical example of how an OCM would appear as consecutive
records of the Overview table:

  SCLK     OCM FLAG   PARENT SCLK
  -------  --------   ------------
  1234500      1      1234630        (exposure, read-out suppressed)
  1234530      1      1234630        (exposure, read-out suppressed)
  1234600      1      1234630        (exposure, read-out suppressed) 
  1234627      1      1234630        (exposure + read-out)
  1234630      3      1234630        (parent frame)

The SCLK of the last child has been decremented by 3 (2 for summation mode) so
that it is different from that of the parent.

The following is an example where four exposures are taken 2 1/3 seconds apart.
The full-frame OCM is then read out at 8 2/3 seconds.

  SCLK     OCM FLAG   PARENT SCLK
  -------  --------   ------------
  1234557      1      1234671        (exposure, read-out suppressed)
  1234560      1      1234671        (exposure, read-out suppressed)
  1234664      1      1234671        (exposure, read-out suppressed) 
  1234667      1      1234671        (exposure, read-out suppressed)
  1234671      2      1234671        (no exposure, read-out, parent frame)

This is a special case where a mode change (from 2 1/3 seconds to 8 2/3
seconds) is required in order to read the image out in full frame mode (only
summation-mode read-out is possible at 2 1/3 seconds).  In this case, since
the read-out occurs in the frame cycle following the last exposure, the SCLK
of the last child is already different the parent SCLK and no adjustment is
required.

When the OCM is transmitted to Earth and processed by the MIPS real-time system,
the OCM is output as a UDR with the letters MOS affixed to its filename, e.g.
S0001234671.MOS1.  The SCLK (100*RIM + MOD91) and all VICAR label information
for the UDR correspond to the frame cycle during which read-out occurs.

If more than one version of an OCM is received, these versions should be merged
(see SSIMERGE) before running UNMOSAIC.

OPERATION

The following parameters must be specified: INP, DIR, and AREA.

INP specifies the filename of the input OCM.

DIR specifies the disk and directory in which the output UDRs are to be stored.
DIR may point to working mission storage (e.g. VMS_GLL:[SSI.UDR]) or local
disk (e.g. GLL:[SSI.UDR]).

AREAS specifies the areas corresponding to the elements (exposure) of the
mosaic.  Each area is specified by 5 integers: spacecraft clock
(100*RIM+MOD91), starting line, starting sample, ending line, and
ending sample).

  Ex:     AREAS=(1234567800,1,1,400,400,                 1234567900,1,390,400,800,                 1234568000,390,1,800,400,                 1234568100,390,390,800,800)

UNMOSAIC will extract each image area specified by the AREAS command and output
it as a separate image.  Each output image will be the same size (800x800 full-
frame or 400x400 summation-mode) as the input image.  Each image area is
placed in the same pixel position as in the input image.

Note, as in the example above, that the areas may overlap.

UNMOSAIC will replace the SCLK and SCET in the VICAR label of each output image
so that these values correspond to the frame cycle during which each exposure
occurs.

UNMOSAIC will create a new record in the RAW domain of the SSI Catalog for each
output UDR.  This feature can be suppressed via the 'NOUPDATE parameter.  (see
help page CHILD'S SSI RAW RECORD).

CHILD's SSI RAW RECORD

The following fields of the RAW domain of the SSI Catalog are copied directly 
from the parent's and these fields can only serve as very rough approximations 
for the child:
       meantruncbits
       meantruncsamp
       meanictratio
       minictratio
       maxictratio
       meanhufratio
       minhufratio
       maxhufratio
       averagedn (only if processing a non-binary header input file)

The start/stopgapline of the raw record:
  The SSI Catalog allows up to 3 gap lines in a file; however the extracted
child might contain more due to the possible segmentations of lines (a gap line
may occur if the user specified area falls out of both of the 2 segments of the
parent image).  The program does not try to take this into account because it
might run out of the gap line entries from catalog.  The only way to find these
'new' gaps is to identify the segmentation values (es's and ss's) of the binary
prefix being all zero (as the definition of gap line is too).

MODIFICATIONS TO THE VICAR LABEL (BINARY and ASCII)

For each output image, the SCLK and SCET are modified in the ASCII portion of
the VICAR label so that these values correspond to the given exposure.  
CUT_OUT_WINDOW is also corrected to be the intersection area of the Parent's
CUT_OUT_WINDOW and the Child's unmosaicking area.

Similarly, the following fields of the binary header are corrected: Starting
SCLK, Ending SCLK, SCET, Mean DN, Activity, filter, gain, exposure, range, 
pointing[0], pointing[1], pointing[2], miss_lines, part_lines, version and 
Histogram, and many other more...

Finally, the Segments field of the binary prefix are updated to indicate the
location of the valid data in each UDR.


NOTE:
After executing UNMOSAIC, program CATLABEL should be executed to update the
remaining items in the VICAR label.

BINARY HEADER INFORMATION

In the event that the input parent image does not contain a binary header, the
output image will also not contain a binary header.  If the output image
already exists in the specified directory (and the output image is one without
binary header) then the image output fails, and the user is informed to rename
or delete the existing image file.  The reason for doing so is to safeguard
against creation of a unreadable image file.  Such would happen if the existing
image file is one containg binary header.

NOTE: because of the safeguarding feature, the user may run into a situation 
where the execution of unmosaic on non-binary a header file is impossible.  This
is true when the user does not have rights to rename/delete the existing file.
Under  this circumstance the user should resolve with the owner of the file or
simply write to another directory.

OUTPUT FILE NAMING CONVENTION

UNMOSAIC will automatically name each output UDR by using the SCLK corresponding
to the exposure and prefixing the rawnum with the letters UM, as in the
following example:

    UNMOSAIC  INP=S0001234671.MOS2  DIR=WMS_GLL:[SSI.UDR]          AREAS=(1234557,1,1,350,450,                 1234560,1,340,300,800,                 1234664,400,1,800,425,                 1234557,625,425,720,550)

The children of this OCM will be named as follows:

        S0001234557.UM1
        S0001234560.UM1
        S0001234664.UM1
        S0001234667.UM1

The rawnum (= 1 in this example) is determined by getting its current value
from the ssiRaw table and incrementing it by one.

PROGRAM HISTORY

Written by:           Allan Runkle, February 12, 1995
Cognizant Programmer: Gary Yagi
Revisions:
 WHEN       WHO WHAT
 ---------- --- ---------------------------------------------------------------
 02/18/1998 GMY * Change from C to ANSI C compiler
 06/16/1997 DZS * ABENDs with error message if predframedur=NULL or 
                  predfiltname=NULL                                  (FR 90033)
 04/16/1997 SMC * Corrected ERT Hour calculation so that 0 oclock = 12.   (DFR)
 04/14/1997 SMC * Zeroed out the RA, DEC and TWIST fields of the binary header
                  because the HK's cournterparts are to be used.          (DFR)
                * Modified program to copy (framedur, gainmodeid, filtname)
                  of SsiRaw from their repspective fields of SsiOverview.  
                  These fields were copied from the binary header before the 
                  change.                                             (FR87991)
                * For Child's SSI Raw Record, fields (expostype, blemprotflag, 
                  invclckstflag, litefldstflag, ccdtemp, rearopttemp) are 
                  modified, so that all are obtained from the Housekeeping
                  fields when available.  AND if Housekeeping is not available
                  all are obtained from the binary header, except (ccdtemp,
                  rearopttemp) are obtained from Parent's SSI Raw Record.
                                                                      (FR87991)
                * Obtain SSI Raw's (mergenum) from Parent SSI Raw Record; and
                  calculate (bestversion) base on (producttype) of Parent, 
                  where if (producttype=="MM") then 1 else 0.  Due to the need
                  to modify these 2 fields of the record, the data type of
                  RawRec (which refers to the SSI Raw of Child) is changed from
                  cat_ssiRtsRaw_struct_query_typ to 
                  cat_ssiMergeRaw_struct_query_typ, and the catalog updating
                  routine is changed from catSsiRtsRaw to catSsiMergeRaw.
                                                                      (FR87991)
                * Modified (start/stop gapline*) of Child's RawRec to reflect
                  the SIS specification change of January.  The gapline*
                  definition was changed from representing valid data gaps to
                  invalid data gapes.                                     (DFR)
                * Corrected (maxcml, tml) of Child's RawRec, also Binary 
                  Header's miss_lines and part_lines are now updated. (FR87991)
                * Modified to use getSsiOver to obtain child's SSIOverview
                  record rather than the original catSsiRtsOver because 
                  catSsiRtsOver always obtains a those record which has
                  sclkstrtcnt/sclkstopcnt containing the given sclk, which
                  is not desirable given the possibility for multiple records
                  returns.                                                (DFR)
                * Enhanced the program to print complete file name.   (FR90011)
 02/26/1997 SMC save the constant (2) to all record_id of the binary prefix for
                  all the uncopied lines.                             (FR89939)
 01/15/1997 SMC * Fixed RANGE for binary label to 0 as SIS specified. (FR89996)
                * > Update rawrec.ertmilli from binary header       (FR89951,2)
                  > Translated GAIN for binary header by
                       (3 - Overview->predgainmodeid)               (FR89951,3)
                  > Corrected the VERSION of binary label.          (FR89951,4)
 12/18/1996 SMC * Modified so that the program terminates when parent's SSIRaw
                  record is not found.                                (FR89998)
                * Modified TSTUNMOSAIC so OUT_PATH is a required user
                  parameter, and CATPW is explicitly specified.       (FR89999)
 11/08/1996 SMC Improved the -4.1667 offset detection, function ExposureNo will
                  now try to get the closes Exposure Number taking the offset 
                  into account, instead of allowing only 0.1 tolerance.   (DFR)
 11/07/1996 SMC Implemented the -4.1667 offset to exposdure time in 
                compensating for the malfunction of Galileo Instrument.   (DFR)
 10/31/1996 ADC Added find_hist_key call to ensure program will run on data 
                output from SSIMERGE2.                                    (DFR)
 10/22/1996 SMC Calculate SCET using the new convert_scet_to_ydhms from 
                gll_ssi_gen.com.                                      (FR89385)
 08/26/1996 SMC * Added check condition so that histogram and prefix are only 
                  computed when binary header exists.                     (DFR)
                * Check that user parameter for valid start line/samp.    (DFR)
                * Added non-binary header file notification to user.      (DFR)
                * Fixed histogram calculation by excluding gaplines.      (DFR)
 08/15/1996 SMC * Made fix so that the child retains the VICAR label order as 
                  the parent's.                                           (DFR)
                * Made fix so that the SCET information of VICAR label is 
                  correctly updated when processing images with no binary 
                  header.                                                 (DFR)
 05/03/1996 SMC Took out the bin header condition check when updating SCET 
                ASCII labels.                                         (FR89218)
 04/16/1996 SMC Revised UNMOSAIC so it allows processing of input parent images
                  which does not contain binary header nor prefix.    (FR89231)
 03/27/1996 SMC * fix the calculation of the average dn in the database.
                                                                      (FR89166)
                * fixed lein so that the Mean Dn for the Binary Header is 
                  poperly calculated.
 03/26/1996 SMC * copied obstrucid from parent raw record.            (FR89122)
                * fixed the extra pixel data on line 800.             (FR89167)
                * check if the 2nd segment contains data, so the histogram is 
                  calculated properly.                                (FR89169)
 03/21/1996 SMC Fixed exposure assignment so it looks up the table rather 
                  than hardcoding it to 0.                            (FR89168)
 03/20/1996 SMC * Modified for 'NOUPDATE to obtain ssioverview information and 
                  store it in the VICAR label.                        (FR89164)
                * fixed leins so that the Compression Statistics, Truncated 
                  samples & bits, and Picture Count are copied from the 
                  parent's record. 
                * fixed lein so that the gap identification of the Raw Table 
                  Fields are written for the children correctly.
 03/14/1996 ADC Modified code to properly name child UDRs both in ssiraw and on
                  disk. Modified help to reflect correct file names.  (FR89161)
 02/29/1996 SMC Fixed the header file so program can be compiled.     (FR89194)

LEINS:

The following fields are not correctly implemented:
  Binary Header
	Starting SCLK
	Ending SCLK

PARAMETERS: