hidtmgen

This application is designed to produce a set of PDS products from an ISIS Digital Terrain Model (DTM) cube and/or a list of MRO HiRISE orthorectified images. The purpose of this program is to:

1. Export the input cubes to PDS-formatted images.
2. Modify the output label to include extra information.

The input DTM file for this program must have been generated using a set of HiRISE stereo pair images. If both input orthorecitfied files and an input DTM have been provided by the user, they should all have the same original stereo pair source. These files are usually generated using Socet Set and require some processing before they are passed into this program. In some cases, restrictions to the input file names are enforced. See the documentation for the DTM and ORTHOTOLIST parameters for details.

The table below indicates the requirements for program parameters under the indicated conditions.

DEFAULTNAMES	Input file type	Required Parameters	Required PARAMSPVL Keywords
FALSE	Both DTM and ORTHOFROMLIST provided	The following parameters are enabled: DTMTO (required) DTM_PRODUCT_ID (required) ORTHOTOLIST (required) ORTHOPRODUCTIDLIST (required) PARAMSPVL (required)	DATA_SET_ID DATA_SET_NAME PRODUCER_INSTITUION_NAME PRODUCER_ID PRODUCER_FULL_NAME PRODUCING_INSTITUTION PRODUCT_VERSION_ID RATIONALE_DESC SOFTWARE_NAME DTM_SOURCE_PRODUCT_ID
	DTM provided only	The following parameters are enabled: DTMTO (required) DTM_PRODUCT_ID (required) PARAMSPVL (required)	DATA_SET_ID DATA_SET_NAME PRODUCER_INSTITUION_NAME PRODUCER_ID PRODUCER_FULL_NAME PRODUCING_INSTITUTION PRODUCT_VERSION_ID RATIONALE_DESC SOFTWARE_NAME DTM_SOURCE_PRODUCT_ID
	ORTHOFROMLIST provided only	The following parameters are enabled: ORTHOTOLIST (required) ORTHOPRODUCTIDLIST (required) PARAMSPVL (required)	DATA_SET_ID DATA_SET_NAME PRODUCER_INSTITUION_NAME PRODUCER_ID PRODUCER_FULL_NAME PRODUCING_INSTITUTION PRODUCT_VERSION_ID RATIONALE_DESC SOFTWARE_NAME ORTHO_SOURCE_DTM_ID
TRUE	Both DTM and ORTHOFROMLIST provided	The following parameters are enabled: OUTPUTDIR (optional - defaults to current working directory) Ortho input file name requirements - each file must have orbit/target IDs for itself, as described in the documentation for the ORTHOFROMLIST parameter. OUTPUTDIR (optional - defaults to current working directory) ORTHOSEQUENCENUMBERLIST (required) PARAMSPVL (required)	DATA_SET_ID DATA_SET_NAME PRODUCER_INSTITUION_NAME PRODUCER_ID PRODUCER_FULL_NAME PRODUCING_INSTITUTION PRODUCT_VERSION_ID RATIONALE_DESC SOFTWARE_NAME DTM_SOURCE_PRODUCT_ID
	DTM provided only	The following parameters are enabled: OUTPUTDIR (optional - defaults to current working directory) PARAMSPVL (required)	DATA_SET_ID DATA_SET_NAME PRODUCER_INSTITUION_NAME PRODUCER_ID PRODUCER_FULL_NAME PRODUCING_INSTITUTION PRODUCT_VERSION_ID RATIONALE_DESC SOFTWARE_NAME DTM_SOURCE_PRODUCT_ID
	ORTHOFROMLIST provided only	The following parameters are enabled: File name requirements - input orthorectified file names must have orbit/target IDs for itself, as described in the documentation for the ORTHOFROMLIST parameter. OUTPUTDIR (optional - defaults to current working directory) ORTHOSEQUENCENUMBERLIST (required) PARAMSPVL (required)	DATA_SET_ID DATA_SET_NAME PRODUCER_INSTITUION_NAME PRODUCER_ID PRODUCER_FULL_NAME PRODUCING_INSTITUTION PRODUCT_VERSION_ID RATIONALE_DESC SOFTWARE_NAME ORTHO_SOURCE_DTM_ID

Description

This parameter is used for convenience so that output file names and PRODUCT_IDs do not need to be specified by the user. If this parameter is selected, then the parameters DTMTO, ORTHOTOLIST, DTM_PRODUCT_ID, and ORTHOPRODUCTIDLIST are disabled since the program will use the default output values for these. See the table in the main description of this program for specific requirements. If this parameter is selected, the names of the output files will match the corresponding PRODUCT_IDs (minus the file path and extension). The values for each PRODUCT_ID is generated using the name of the input cube, the corresponding sequence number (for orthorectified output images), and other cube attributes. For this reason, input orthorectified file names of a certain form are required. See the documentation for the ORTHOFROMLIST parameter for specifications. Also, certain keyword values are provided by the PARAMSPVL file. See the documentation for PARAMSPVL for specifications.

The output PRODUCT_IDs used when DEFAULTNAMES=TRUE are explained below.

For DTMs files the form is 
DTems_xxxxxx_xxxx_xxxxxx_xxxx_vnn
    e is the code for the type of elevation data 
          E for areoid elevations 
          R for radii (hidtmgen does not currently support this option)
    m is the map projection code 
          E for equirectangular
          P for polar stereographic
    s is the grid spacing (i.e. map scale) code
          A for 0.25 m 
          B for 0.5 m 
          C for 1.0 m 
          D for 2.0 m
          etc. 
          Z is used if no match is found, a 10% tolerance on the 
             resolution value is used to catch values that are close. 
    xxxxx_xxxx_yyyyy_yyyy is the orbit (five digit) number 
          and target (four digit) codes
          for the stereo pairs used to create this DTM
    v is the code for the producing institution 
          U for USGS 
          A for University of Arizona 
          C for CalTech 
          N for NASA Ames 
          J for JPL 
          O for Ohio State 
          Z for other 
    nn is the 2 digit product version ID number 

For orthorectified image files, the form is 
pSP_xxxxxx_xxxx_ccc_s_nn_ORTHO
    p is the code for the mission phase
          E for Extended Science Phase
          P for Primary Science Phase
    xxxxxx_xxxx is the orbit number and target code for this ORTHO
    ccc is the color content code
          RED for visible RED, 1 band image
          IRB for 3 band enhanced color (IR, RED, BG)
    s is the grid spacing (i.e. map scale) code
          A for 0.25 m 
          B for 0.5 m 
          C for 1.0 m 
       	  D for 2.0 m
          etc. 
          Z is used if no match is found, a 10% tolerance on the 
             resolution value is used to catch values that are close. 
    nn is a sequence number to distinguish between orthorectified images
          from the same HiRISE observation that may be created from different DTMs.
    ORTHO indicates that the image has been orthorectified

NOTE: The first 15 characters of the product ID pSP_xxxxxx_xxxx are taken
      directly from the first 15 characters of the input ortho file name.

          

Type	boolean
Default	TRUE
Exclusions	DTMTO ORTHOTOLIST DTM_PRODUCT_ID ORTHOPRODUCTIDLIST
Inclusions	OUTPUTDIR ORTHOSEQUENCENUMBERLIST

Description

The directory where output image files will be written. This parameter only applies when DEFAULTNAMES=TRUE. The default is the current working directory.

Type	string
Default	./

Description

The name of the DTM file to be exported. The given file must be an ISIS cube whose label contains a mapping group. This DTM, usually created using Socet Set, must be generated from a stereo pair of MRO HiRISE images. The user may specify the corresponding output file name using the DTMTO parameter. Otherwise, the output file name can be generated by hidtmgen by setting DEFAULTNAMES=TRUE. Note: DTM is not a required parameter. The user may choose to only export a list orthorectified images.

Type	cube
File Mode	input
Internal Default	None
Filter	*.cub

Description

The name of the exported DTM file. This parameter is required when DTM has been provided and DEFAULTNAMES=FALSE.

Type	filename
File Mode	output
Internal Default	Automatic
Inclusions	DTM
Filter	*.IMG

Description

The PRODUCT_ID for the output DTM product. This parameter is required when DTM has been provided and DEFAULTNAMES=FALSE.

Type	string
Internal Default	None
Inclusions	DTM

Description

A list of orthorectified images to be exported. The given files in this list must be ISIS cubes from the MRO HiRISE camera that have been orthorectified to the input DTM, if provided. The user may specify the corresponding output file names using the ORTHOTOLIST parameter. Otherwise, these output file names can be generated by hidtmgen by setting DEFAULTNAMES=TRUE. In this case, the name of each input image file in this list must begin with the prefix pSP_######_####_ where p is the code for the mission phase and the #'s represent the orbit number followed by the target code for this image.

Type	filename
File Mode	input
Internal Default	Automatic
Filter	*.txt *.lis *.lst

Description

An ordered list of output PDS file names. It is expected that the order of the file names in this list will correspond to the orthorectified cubes in the ORTHOFROMLIST. Each file in this list should have a full path to the output location where the PDS file will be created. Note that the DEFAULTNAMES and OUTPUTDIR options may be selected instead of ORTHOTOLIST if the user prefers to specify only the location of the output PDS files (and not the file names). This parameter is required when ORTHOFROMLIST has been provided and DEFAULTNAMES=FALSE.

Type	filename
File Mode	input
Internal Default	Automatic
Inclusions	ORTHOFROMLIST
Filter	*.txt *.lis *.lst

Description

An ordered list of strings representing the PRODUCT_ID values that correspond to each of the input orthorectified images given in the ORTHOFROMLIST. This parameter is required when ORTHOFROMLIST has been provided and DEFAULTNAMES=FALSE.

Type	filename
File Mode	input
Internal Default	Automatic
Inclusions	ORTHOFROMLIST
Filter	*.txt *.lis *.lst

Description

An ordered list of two digit sequence numbers that correspond to each of the input images given in the ORTHOFROMLIST. These sequence numbers are used to distinguish between orthorectified images from the same HiRISE observation that may be created from different DTMs. This parameter is required when ORTHOFROMLIST has been provided and DEFAULTNAMES=TRUE.

Type	filename
File Mode	input
Internal Default	Automatic
Inclusions	ORTHOFROMLIST
Filter	*.txt *.lis *.lst

Description

This should be a PVL-formatted file that contains the keywords indicated below.

Keywords that are always required:

• DATA_SET_ID
• DATA_SET_NAME
• PRODUCER_INSTITUION_NAME
• PRODUCER_ID
• PRODUCER_FULL_NAME
• PRODUCING_INSTITUTION*
• PRODUCT_VERSION_ID**
• RATIONALE_DESC
• SOFTWARE_NAME

*  The PRODUCING_INSTITUTION value must be a single character code: 
       U for USGS 
       A for University of Arizona 
       C for CalTech 
       N for NASA Ames 
       J for JPL 
       O for Ohio State 
       Z for other 
** The PRODUCT_VERSION_ID must be a real number (i.e. double 
   precision) value. When DEFAULTNAMES=TRUE this number will be used
   to generate the 2 digit version ID code used as the last two digits
   of the output DTM's PRODUCT_ID.
        Case 1: If the number given is greater than 10,
                the first two digits will be used for the output code.
        Case 2: If it is of the form N.0 (where N is between 0 and 9),
                the output code will be 0N.
        Case 3: If it is of the form N.M (where N and M are between
                0 and 9), the output code will be NM.
        Case 4: If it is less than 1.0, the output code will be 0N,
                where N is the first significant digit
                (i.e the first non-zero from the left).
   Note that except for the special case of N.0, the most significant
   digits are used. 

          

Keywords that are required under particular circumstances:

• DTM_SOURCE_PRODUCT_ID (required if DTM provided) *
• ORTHO_SOURCE_DTM_ID (required if DTM was not provided) **

*  The DTM_SOURCE_PRODUCT_ID is an array that indicates the source of the input DTM.
   If the user enters a DTM, this value must be an array containing the PRODUCT_IDs
   of the stereo pair used to generate the DTM.

** The ORTHO_SOURCE_DTM_ID is the PRODUCT_ID of the DTM used to generate the given
   orthorectified input cubes.

          

Type	filename
Default	$ISISROOT/appdata/templates/hidtmgen/hidtmgenParamsTemplate.pvl

Description

This parameter is used to select the output data storage order. The output can be streamed starting with the most significant byte (MSB) or starting with the least significant bytes (LSB). The choice should be made by the user depending upon the format read by the system architecture from which they plan to read the raw data.

Type	string
Default	LSB
Option List:	Option Brief Description LSB Least significant byte. The least significant byte will be the first byte output. MSB Most significant byte. The most significant byte will be the first byte output.

Description

If set to true, the minimum value of the raw output data will be reserved for null pixels. The actual value used for null pixels will be denoted in the print.prt file as well as displayed onscreen.

Type	boolean
Default	true

Description

If set to true, then an output DN value is set aside for the LRS input pixels. The actual DN value used for LRS pixels will be denoted in the print.prt file as well as displayed onscreen.

Type	boolean
Default	false

Description

If set to true, then an output DN value is set aside for the LIS input pixels. The actual DN value used for LIS pixels will be denoted in the print.prt file as well as displayed onscreen.

Type	boolean
Default	false

Description

If set to true, then an output DN value is set aside for the HIS input pixels. The actual DN value used for HIS pixels will be denoted in the print.prt file as well as displayed onscreen.

Type	boolean
Default	false

Description

If set to true, then an output DN value is set aside for the HRS input pixels. The actual DN value used for HRS pixels will be denoted in the print.prt file as well as displayed onscreen.

Type	boolean
Default	false

Description

Bit type of output:

• 8-bit (0=black, 255=white)
• 16-bit unsigned (0=black, 65535=white)
• 16-bit signed (-32767=black, 32768=white)
• 32-bit (1.17549435e-38=black, 3.40282347e+38=white)

Type	string
Default	32BIT
Option List:	Option Brief Description 8BIT Output 8-bit data in DTM product. Pixels are in 8-bit data range (0 to 255). U16BIT Output 16-bit unsigned data in DTM product. Pixels are in the 16-bit data range (0 to 65535). S16BIT Output 16-bit signed data in DTM product. Pixels are in 16-bit signed data range (-32768 to 32767). 32BIT Output 32-bit data in DTM product. Pixels are in the 32-bit floating point data range (-3.40282347e+38 to 3.40282347e+38).

Description

Bit type of output:

• 8-bit (0=black, 255=white)
• 16-bit unsigned (0=black, 65535=white)
• 16-bit signed (-32767=black, 32768=white)
• 32-bit (1.17549435e-38=black, 3.40282347e+38=white)

Type	string
Default	8BIT
Option List:	Option Brief Description 8BIT Output 8-bit data in orthorectified PDS products. Pixels are in 8-bit data range (0 to 255). U16BIT Output 16-bit unsigned data in orthorectified PDS products. Pixels are in the 16-bit data range (0 to 65535). S16BIT Output 16-bit signed data in orthorectified PDS products. Pixels are in 16-bit signed data range (-32768 to 32767). 32BIT Output 32-bit data in orthorectified PDS products. Pixels are in the 32-bit floating point data range (-3.40282347e+38 to 3.40282347e+38).