uax2isis Documentation

uax2isis - Convert IMP UAX format Pathfinder files to ISIS cubes
uax2isis will convert UAX (University of Arizona) IMP (Imager for
Mars Pathfinder) files to ISIS cube format.  These input files
are assumed to be in XDR format and follow IDL I/O using this
unformatted scheme.  See the IDL User's Guide, pages 17-32 to
17-35 for a detailed description on this format.

The TO parameter is optional.  If the output filename is not
provided in the TOP parameter, uax2isis will generate a filename
by the first 3 or 4 digits from the filter wavelength followed by
an "R" or "L" to signify right or left IMP camera, respectively.

Note that ODIR may be provided to specify a directory where to
create files whose names are generated by uax2isis.  If the
user specifies a file name in the TO parameter, this parameter
is ignored.  If TO is not specified, then the file name generated
by uax2isis will have the directory path specified in ODIR
prepended to the file name.

These most common UAX images are to be 2-dimensional 16-bit
images with a header length no larger than 256 entries.  There
are other data types of (UAX) files that uax2isis can process
as well.  These are:

  8-bit unsigned integer       (written as ISIS type 1)
 16-bit [un]signed integer     (written as ISIS type 2)
 32-bit signed integer         (converted to ISIS REAL*4)
 32-bit floating point         (written as ISIS REAL*4, type 3)
 64-bit double floating point  (converted to ISIS REAL*4
                                w/saturation)
 32-bit complex floating point (converted to ISIS REAL*4
                                w/2*#SAMPLES)

uax2isis provides the STOWRNG parameter so that the user can
specify ranges of image numbers that have the mast stowed
when the image was taken.

uax2isis will parse through the UAX input file header and extract
all defined and relevant keywords.  All these keywords and there
values can be listed by setting SHOWKEYS = "YES".  The listing
goes to both the terminal device and log file.  If SHOWKEYS = "NO",
then this feature is suppressed.

uax2isis allows the user to select only the listing of the
UAX keywords that exist in the image file by setting LISTONLY
to "YES".  Under this condition, the output cube file will not
be generated.  Also, the value of SHOWKEYS is virtually ignored
as listing only the UAX keywords overrides this option and will
result in the keys always being printed.

The output ISIS file will be a 3-dimensional ISIS cube file of
type 2 (16-bit integer) core data where the BAND axis is
dimensioned to 1.  No additional QUBE elements are added to the
output ISIS file by this program.  The number of lines and samples
are a function of the dimensions of the input UAX image.  There are
actually two image orientations that these UAX files can attain.
Each are specific to the right or left side of the CCD on the Imager
where the images are taken.  Images taken by the right side are
oriented whereby the top of the image is the right edge and the right
side of the image is the bottom.  Thus uax2isis rotates these images
-90.0 degrees.  The left side image has the opposite orientation.
The top of the image is the left edge and the right side of the
image is the bottom.  These images are rotated +90.0 degrees by
uax2isis.  Thus, the X dimension (H_XSIZE) corresponds to the number
of ISIS LINEs in the output cube.  The Y dimension (H_YSIZE)
corresponds to the number of ISIS SAMPLEs in the output cube.  The
orientation of the UAX image is determined by the set number of the
image (H_SET_NUMBER).  If the set number is odd, then it is from the
right side.  An even set number indicated an image from the left
side.  The following diagram shows the CCD image orientation in
memory as of Feb 22, 1996:


             R                   L
    -----------------------------------------
    |                  |                    |
    |                  |                    |
    |                  |                    |
    |                  |                    |
    |                  |                    |
top |   left image     |    right image     | top
    |                  |                    |
    |                  |                    |
    |                  |                    |
    |                  |                    |
    |                  |                    |
    -----------------------------------------
             L                   R

uax2isis orients correctly the top-bottom and left-right as
normally viewed.

The following ISIS keywords are generated in the output ISIS file.
Note that some keywords are generated from keywords that exist in
the UAX input file header.  These keywords are so noted:

ISIS Keyword                    UAX Keyword     Description
------------------------------  --------------- ----------------------
IMAGE_NUMBER                    H_SET_NUMBER    Unique image
                                                identifier
SPACECRAFT_NAME                 none            Spacecraft identifica-
                                                tion
                                                ("MARS_PATHFINDER")
START_TIME                      H_DATE  *or*    Date the observation
                                H_IMAGE_TIME    was made
INSTRUMENT_ID                   none            Name of instrument
                                                ("IMP")
EXPOSURE_DURATION               H_EXPTIME       Exposure time
                                                converted to
                                                milliseconds
LENS_TEMPERATURE                H_OPTICS_TEMP   Temperature of the CCD
                                                optics
FOCAL_PLANE_TEMPERATURE         H_CCDTEMP       Temperature of the CCD
EXPOSURE_TYPE                   H_EXPOSURE_TYPE CCD Exposure type
FILTER_NUMBER                   H_FILTER        Filter number in use
DARK_CURRENT_CORRECTION_FLAG    H_DARK_CORRECT  Dark correction flag
BAD_PIXEL_REPLACEMENT_FLAG      H_BADPIX_CORREC Bad pixel correction
                                                flag
SHUTTER_EFFECT_CORRECTION_FLAG  H_SHUTTER_CORRE Shutter effect
                                                correction flag
AZIMUTHAL_MOTOR_CLICKS          H_AZIMUTH_R     Raw azimuth reading
ELEVATIONAL_MOTOR_CLICKS        H_ELEVATION_R   Raw elevation counts


Note that ISIS keywords that are dependant on the existance of a UAX
keyword that does not exist in the input UAX file will not be
created in the output ISIS file and a warning message is generated.

uax2isis will also generate keywords appropriate for projection using
ISIS's imp2prj application.

Programmer: Kris Becker

File name of UAX file

NONE

Output file name

--

Optional output directory
to place file

--

Specify format of file
generation
ARCHIVE - produces same as
          pds2isis program
WAVEL   - uses the wavelength
          in nanometers

"ARCHIVE"

Perform flipping and
rotating of images

"NO"

Range of image numbers
where mast is stowed

"2594-2657","2726-2853","2858-2863"

Select listing of UAX
keywords

"YES"

Select listing of UAX
keywords only

"NO"

Returns the name of the
output file

LOCAL1

ADDITIONAL NOTES:

Parm	Description
FROM	The name of the input UAX file. This file is in XDR format. There is no default file extension.
TO	The output ISIS cube file created by uax2isis. This file will contain the converted UAX data in ISIS format. Note that this may be optionally specified. When the output file name is not provided, a file name with the format xxxy.cub is generated where "xxx" is the wavelength in nanometers and "y" is "R" or "L" which indicates the right or left IMP camera, respectively. (Default extenstion is .cub)
ODIR	This is can be used to specify a directory where the output file will be created. This parameter is optional. If not given, the file will be generated in the default directory. There need not be a "/" at the end of the path. uax2isis will append one if it is not present prior to prepending it to the generated output file name.
FILEFORM	Format used to generate the output file name if one is not provided by the caller. The ARCHIVE option produces a file of the form: iMMMMMMMMCsSSSSUfXX.cub where MMMMMMMM is the last 8 digits of the mission time, C is "r" or "l" for right or left camera, respectively, SSSS is the sequence number, U is the sub-sequence number and XX is the filter number. The WAVEL option produces a file of the form: xxxC.cub where xxx is the wavelength (in nanometers) of for the image (which could be 4 digits) and C is "R" for right and "L" for left camera.
STOWRNG	Allows the user to specify a range of image numbers where the mast is stowed. This specified as a set of numbers separated by a comma, space or a dash. This will result in the ISIS label keyword called INSTRUMENT_DEPLOYMENT_STATE_ID to be set to "STOWED" if the image number is within any of the specified ranges or set to "DEPLOYED" for all other numbers.
SHOWKEYS	This parameter allows the user to have the UAX keywords listed to the ISIS log file. If SHOWKEYS = "YES", then all valid and defined UAX keywords will be listed to the log file.
LISTONLY	This allows the user to only read the input UAX file and list the keywords found for that file to the ISIS log file. Note that the TO parameter is ignored in this case and is not required. Also, it would make no sense if the user did not set SHOWKEYS to "YES", so this will always be the case for this option.
IMGTRANS	Perform image translations for the right and left cameras as described in general help. If this is "NO", then the image is transfered as it is stored in the UAX file.
OFILE	This is a STRING parameter that can be provided by the calling PDF that will contain the name of the output file. This is useful for accummulating a list of file names from successive runs. Note that this is always returned with the name and path of the output file even if the file name is provided by the caller. Note that it is also an optional parameter and need not be provided by the caller if it is not of interest.