isis2pds Documentation

isis2pds - Convert ISIS cube file to standard PDS image file
isis2pds translates an ISIS cube to a PDS image file format.  The ISIS
cube file must be a standard cube file that is translated as is to the
PDS image file.  Note that there is no SFROM parameter whereby a subcube
can be selected.  There are two reasons for this:  1) Any subcube
specified would alter the map projection information contained within
the ISIS cube label, and 2) isis2pds does not support suffixes in any
axis.  Therefore, the input ISIS cube file must be a standard ISIS cube
file with no suffixes.  This can be achieved using ISIS's "dsk2dsk"
application to remove suffixes from a cube file.

The optional ISISLBL parameter specifies the name of an ISIS deteched
label file that will be generated to map back into QUBE data object
extracted in the FROM ISIS cube and placed into the PDS file TOPDS.
The QUBEFILE parameter is provided should the need arise to give
and optional path to the resulting PDS file (TOPDS).  This becomes
useful especially when creating PDS products that wind up in CDs.

The user is responsible for providing a PDS label template (PDSTMPL)
that will be used to create the output PDS image label.  isis2pds
preserves the formatting of this template so the output product will
look very close to the format of the input template.  Values of the
PDS keywords in the template may come from three different sources:
user input, the application provides it, or it comes from a translation
table (TRANSTAB) also provided by the user.

The PDS label template has a special format that allows the creator of
the template to specify where, and, in some cases, how a PDS keyword is
resolved.  The format for variable keyword values is:

MISSION_NAME                   = ?x?

where x =  1 -  Application provides the value for this keyword
           2 -  User input provides the value
           3 -  The translation table (TRANSTAB) contains information
                on how to resolve this keyword value

Below is a short and incomplete example of how a PDS label might look
using this format:

###################################################################
#  This is an example a PDS label template format demonstrating how
#  the format is used.
#
#  Note that this format supports PDS-like comments and blank lines
#  all preserved as written.  Also preserved is keyword indentation
#  and "=" sign alignment.
#
#  Also note that lines beginning with a "#" character in the
#  first column is deemed a comment within the PDS template and is
#  ignored by the parser when read in.  These comments can be
#  placed anywhere in the PDS template.
#
#  Please note that this label is incomplete!!!!  It is simply
#  provided to show an example of how to use the format.
###################################################################
PDS_VERSION_ID                 = PDS3

/*          FILE FORMAT AND LENGTH */

RECORD_TYPE                    = FIXED_LENGTH
RECORD_BYTES                   = ?1?
FILE_RECORDS                   = ?1?
LABEL_RECORDS                  = ?1?
INTERCHANGE_FORMAT             = BINARY

/*          POINTERS TO START RECORDS OF OBJECTS IN FILE */

^IMAGE                         = ?1?

/*          IMAGE DESCRIPTION */

DATA_SET_ID                    = ?2?
PRODUCT_ID                     = ?2?
PRODUCER_INSTITUTION_NAME      = "United States Geological Survey"
PRODUCT_TYPE                   = MDIM
MISSION_NAME                   = ?3?
SPACECRAFT_NAME                = ?3?

/*          DESCRIPTION OF OBJECTS CONTAINED IN FILE */

OBJECT                         = IMAGE
  BANDS                        = ?3?
  BAND_STORAGE_TYPE            = ?3?
  BAND_NAME                    = "N/A"
  LINES                        = ?3?
  LINE_SAMPLES                 = ?3?
  SAMPLE_TYPE                  = ?3?
  SAMPLE_BITS                  = ?3?
  CHECKSUM                     = ?3?
END_OBJECT                     = IMAGE

OBJECT                         = IMAGE_MAP_PROJECTION
  ^DATA_SET_MAP_PROJECTION     = ?2?
  COORDINATE_SYSTEM_TYPE       = "BODY-FIXED ROTATING"
  COORDINATE_SYSTEM_NAME       = "PLANETOGRAPHIC"
  A_AXIS_RADIUS                = ?3?
  B_AXIS_RADIUS                = ?3?
  C_AXIS_RADIUS                = ?3?
END_OBJECT                     = IMAGE_MAP_PROJECTION
END

Note that constants may be provided where necessary and prudent when
the values are not variable or dependant upon the input ISIS cube file.
Both data and dataless objects are supported by isis2pds.  Data objects
are detected only by finding an associated OBJECT pointer keyword.  In
the above example, the IMAGE OBJECT has a pointer keyword "^IMAGE" in
the label prior to the definition in the label.  This pointer keyword
must not have a constant value otherwise the object is deemed a dataless
object.  The IMAGE_MAP_PROJECTION is an example of a dataless object
because no pointer keyword exists in the PDS template for the object.

isis2pds has the ability to generate a IMAGE_HISTOGRAM object but with
 certain restrictions.  It will only work on 8-bit data.  This option
does not require the IMAGE_HISTOGRAM object to already exist in the
 template.  If it does exist, it will be honored otherwise one will
be created.

The SPECIAL flag is used to allow future expansion of the program to
handle unusual or specific PDS file generation that is cannot be
handled in a generic sense.  Currently, the only special processing
mode supported is MDIM which invokes the following behavior:

  1)  If a histogram is requested or implied, it will always be
      written as VAX_INTEGER to stay compatable with existing MDIM
      products.  Note this will only occur when the data is 8-bit.

  2)  There are a few quirks in the way LONGITUDE values are
      handled in MDIM.  There can never be LONGITUDEs less than
      0.0 or greater than or equal to 360.0.  Adjustments are
      made to the IMAGE_MAP_PROJECTION (or IMAGE_MAP_PROJECTION_CATALOG)
      object keywords to ensure these values are enforced.

Programmer: Kris Becker, U.S.G.S., Flagstaff, AZ

Input cube file name
 (Default extension: .cub)

NONE

Output PDS file name
 (Default extension: .img)

NONE

Optional name of ISIS
detached label file into
PDS file data objects
 (Default extension: .lbl)

--

An optional path and file
name to the TOPDS file to
be placed in QUBE object
keyword in ISISLBL file

--

Name of PDS/ISIS translation
table file.
Default extension: .txt

--

Name of generic PDS-style
label template to use
to create output file

NONE

The data set identifier

"N/A"

Product identifier

"N/A"

Path and file name containing
the description of the map
projection

"NONE"

Text that will be placed
in the PDS label "NOTE"
keyword.

"NONE"

Request generation of
histogram in output
PDS file

"NO"

Optional special processing
of the PDS file.  See LEVEL2
help for details on what is
currently supported.

--

User comment

" "

ADDITIONAL NOTES:

Parm	Description
FROM	The name of the ISIS file that is to be translated. The default file extention is ".cub"
TOPDS	Name of the output PDS file generated by isis2pds. This file should conform to PDS standards and is intended to be used as an archived PDS distribution file.
ISISLBL	This is an optional output parameter that can be used to generate an ISIS detached label that maps the data object of the TOPDS file to the ISIS file FROM. It will utilize the labels in the FROM file but map the ISIS QUBE object to the TOPDS file. It is intended to be included in the archive for ISIS users who would like to access the data but not have to go through PDS to do so. With this label ISIS users can access the data directly.
QUBEFILE	This parameter is optional and used only when ISISLBL is given. It replaces the complete path in the ISIS QUBE object statement to the resulting TOPDS PDS file IMAGE object. It is intended to be used for generation of CD products.
TRANSTAB	The name of the ISIS to PDS keyword translation table. This file has a special format that provides bi-directional mapping of associated PDS and ISIS keywords. In isis2pds, this will map input ISIS keywords to output PDS keywords. It has a special format that is expected for this file. An example entry in the table would look something like the following: &O\ROOT\TARGET_NAME="MOON" | &O\QUBE\TARGET_NAME="MOON" PDS keywords are always on the left, ISIS keywords on the right. Syntax uses following conventions: &O = an "object" name follows &G = a "group" name follows \ = separator for group/object/keyword sections | = separator between PDS/IMAGE-OBJECT and ISIS/QUBE translation =? = use a value Special words such as "ROOT" are meant to specify the top level keyword section in a label (PDS mostly). There are also some special "functions" available that will perform or return specific elements in the translation process. Here is a list of those functions: $INTEGER(?) - converts values to INTEGER $REAL(?) - converts values to REAL $LITERAL(?) - converts values to LITERAL $STRING(?) - converts values to STRING $CHARACTER(?) - converts values to CHARACTER $CLOAK(?) - hides the primary targeted keyword in searches. This is handy for setting output keywords to a constant if an input keyword exists $SET(?) - converts muli-valued keywords to a set which is brace delimited $ARRAY(?) - converts muli-valued keywords to an array which is parentheses delimited $SAMPLES(?) - returns the number of samples in the primary search target $LINES(?) - returns the number of lines in the primary search target $BANDS(?) - returns the number of bands in the primary search target $DATIME(?) - returns the current date and time in ISO format
PDSTMPL	This is an input file that will be look very much like a PDS label only with special syntax. This file is parsed and used as a signaling mechanism for translation of ISIS keywords to PDS keywords. The PDS label template has a special format that allows the creator of the template to specify where, and, in some cases, how a PDS keyword is resolved. The format for variable keyword values is: MISSION_NAME = ?x? where x = 1 - Application provides the value for this keyword 2 - User input provides the value 3 - The translation table (TRANSTAB) contains information on how to resolve this keyword value Generally, it should follow PDS keyword and value syntax rules for all other keywords and comments. It may also contain constants where appropriate.
DATASET	This is the unique data set identifier that almost always accompanies a NASA mission. This is used used to select a specific keyword set contained with a generally defined translation table. These are signified with ">>" as the first two characters in the TRANSTAB file followed by the data set id. isis2pds will only use the unamed keyword section of the TRANSTAB (translations specified before any ">>"), the "GENERIC" keyword translations (translations that occur after ">>GENERIC") and finally any translations that exist after DATASET before the next occurance of a line with ">>". This allows for many translation sets to be included in a single file.
PRODID	This value allows the user to specify the name that will be placed in the "PRODUCT_ID" keyword in the output PDS label if it exists. It is ignored if the keyword does not exist in the PDSTMPL file.
MAPDESC	This is an optional parameter that is used to provide the name of a file containing a description of the image map projection used to represent the data in the TOPDS file. If one does not exist if can be ignored. If the user decides to provide one, it will be placed in the PDS keyword "^DATA_SET_MAP_PROJECTION" in the IMAGE_MAP_PROJECTION object in the TOPDS file.
LBLNOTE	Optional parameter that is written to the "NOTE" keyword in the TOPDS file if it exists.
HIST	isis2pds will generate a histogram if and only if the input bit type of the ISIS cube data is 8-bit. The results of this processing is an IMAGE_HISTOGRAM object that is written to the output TOPDS file. This OBJECT is written even if the PDSTMPL does not specifically include an IMAGE_HISTOGRAM object description.
SPECIAL	This parameters specifies special handling of the output file for certain missions. Currently it performs the following processing: MDIM Mission Processing: 1) If a histogram is requested or implied, it will always be written as VAX_INTEGER to stay compatable with existing MDIM products. Note this will only occur when the data is 8-bit. 2) There are a few quirks in the way LONGITUDE values are handled in MDIM. There can never be LONGITUDEs less than 0.0 or greater than or equal to 360.0. Adjustments are made to the IMAGE_MAP_PROJECTION (or IMAGE_MAP_PROJECTION_CATALOG) object keywords to ensure these values are enforced.
USERNOTE	Comment from the user. This will be recorded in the ISIS session log file and also in the History entry that is put into the History object of the output file.