Command-Line Options

The following table describes the command-line options available:

Format Types

The following table describes the format types available to both PDS3 and PDS4 target inputs:

The following table describes the format types available only to PDS4 products:

The following table describes the format types available only to PDS3 products:

Running the Transform Tool

The Transform Tool requires the passing in of a PDS3 or PDS4 product label that contains a reference to an image file. In addition, the tool assumes that the referenced image file is co-located with the product label. Under the current implementation, if there are multiple image files referenced in a target label, the tool will default to only transforming the first image file reference. Other notable caveats with this initial version of the tool include:

• Transformations of PDS3 images greater than 8-bits are not supported at the moment.
• For PDS3 to TIFF transformations, the output tile size defaults to 8 lines by the image width.

This section demonstrates some of the ways that the tool can be executed using the command-line option flags:

• Transform a Single PDS4 Array 2D Image
• Transform a Single PDS4 Label To Parameter Value Language (PVL) File
• Transform a Single 8-Bit PDS3 Image
• Transform a PDS3 Label to PDS4 Label
• List the Supported Objects

The files used in the command-line examples below are packaged with the tool in the examples directory.

Transform a Single PDS4 Array 2D Image

The following command demonstrates transforming a PDS4 array 2D image referenced in the associated product label, i943630r.xml, into a jpeg image file named i943630r.jpg:

% transform ../examples/i943630r.xml -f jpg
        

Under the current implementation, for PDS4 data products, the tool only supports the transformation of array 2D images.

If the -o flag option is not specified on the command-line, the tool will default to creating an output file using the target image file name with the user-specified format as the file extension. The resulting output file will be written to the current working directory. The following command demonstrates transforming a PDS4 array 2D image referenced in the associated product label, i943630r.xml, into a graphics interchange format file:

% transform ../examples/i943630r.xml -f gif
        

The resulting output is written to the output file i943630r.gif in the current working directory.

Transform a Single PDS4 Label To Parameter Value Language (PVL) File

The following command demonstrates transforming a PDS4 label, i943630r.xml, to a PVL file, i943630r.pvl:

% transform ../examples/i943630r.xml -f pvl
        

Transform a Single 8-Bit PDS3 Image

The following command demonstrates transforming a PDS3, 8-bit image referenced in the associated attached label, FHA01118.LBL, into a bitmap image file named FHA01118.BMP:

% transform ../examples/FHA01118.LBL -f bmp
        

The following command demonstrates transforming a PDS3, 8-bit image referenced in the associated detached label, FF01.LBL, into a portable network graphics file named FF01.PNG:

% transform ../examples/FF01.LBL -f png
        

Transform a PDS3 Label to PDS4 Label

The following command demonstrates transforming a PDS3 data product label, ELE_MOM.LBL, into a PDS4 Product Observational label named ele_mom.xml:

% transform ../examples/ELE_MOM.LBL -f pds4-label
        

Advanced Use Cases

A common use case scenario of the Transform Tool is to transform a label that points to a single data file containing a single image or table. A more advanced use case scenario is handling a label that points to multiple data files where each data file contains multiple images or tables. This section details how to tell the Transform Tool to transform a specific image or table if given a more complex label.

Note: The flag options that allow control of which images to transform, -n, -d, -a, are not supported with PDS3 labels pointing to multiple, non-FITS, image transformations.

Transform a Specific Table

Use the -O,--list-objects flag option to first list the table objects being supported by the tool:

% transform ../examples/Product_Table_Multiple_Tables.xml -O
        

This will display the supported table objects:

Supported Images:

  None Found

Supported Tables:

  Data file: PDS4_ATM_TABLE_CHAR_MULTIPLE.TAB

    index = 1
    local identifier = TABLE_CHAR_1
    type = fixed-width character table
    records = 23
    record length = 88
    groups = 0
    fields = 10

    index = 2
    local identifier = TABLE_CHAR_2
    type = fixed-width character table
    records = 23
    record length = 88
    groups = 0
    fields = 10
        

To perform a table to CSV transformation of the 2nd table, run the following command:

% transform ../examples/Product_Table_Multiple_Tables.xml -f csv -n 2
        

Transform a Specific Data File

Use the -O,--list-objects flag option to first list the table objects being supported by the tool:

% ./transform ../examples/Product_Table_Multiple_Datafiles.xml -O
        

This will display the supported table objects:

Supported Images:

  None Found

Supported Tables:

  Data file: PDS4_ATM_TABLE_CHAR.TAB

    index = 1
    local identifier = PHX-M-TT-5-WIND-VEL-DIR_TABLE_CHAR
    type = fixed-width character table
    records = 23
    record length = 88
    groups = 0
    fields = 10

  Data file: PDS4_TABLE_DELIMITED.csv

    index = 1
    local identifier = null
    type = delimited table
    records = 3
    groups = 0
    fields = 13

  Data file: 2d234493326edratf3d2537n0m1.dat

    index = 1
    local identifier = null
    type = fixed-width binary table
    records = 336
    record length = 96
    groups = 1
    fields = 20
        

The following command demonstrates transforming the table associated with the data file PDS4_TABLE_DELIMTED.csv:

% transform ../examples/Product_Table_Multiple_Datafiles.xml -f csv -d PDS4_TABLE_DELIMITED.csv
        

Transform Everything

Display the list of FITS images supported by the tool using the -O, --list-objects flag option:

% ./transform ../examples/20140804T205944Z_MAP_bias_V001.xml -O
        

This will display the following:

Supported Images:

  Data file: 20140804T205944Z_MAP_bias_V001.fits

    index = 1
    local identifier = PDU
    data type = IEEE754LSBSingle
    lines = 1024
    samples = 1024

    index = 2
    local identifier = SDU
    data type = IEEE754LSBSingle
    lines = 1044
    samples = 1112

Supported Tables:

  None Found
        

The following command demonstrates transforming all FITS images found in the label:

% transform ../examples/20140804T205944Z_MAP_bias_V001.xml -f jpg -a
        

The label points to a single data file that contains multiple images. So the tool ends up creating the following output files:

• 20140804T205944Z_MAP_bias_V001_1.jpg
• 20140804T205944Z_MAP_bias_V001_2.jpg

Note that the tool appends an index value to the end of each output file name whenever the tool has to transform multiple images or tables contained within a single data file.

Populating PDS4 Elements

This section describes how the tool leverages the PDS3 label in order to populate some of the PDS4 elements. Below is a list of PDS4 elements and a description of how the tool goes about populating that element.

logical_identifier

The tool will populate the logical_identifier element in the following mannner:

urn:nasa:pds:data:${DATA_SET_ID}:${PRODUCT_ID}
        

If PRODUCT_ID does not exist in the PDS3 label, then the tool will default to using the label filename instead:

urn:nasa:pds:data:${DATA_SET_ID}:${labelFilename}
        

title

The tool will populate the title element in the PDS4 label based on the existency of one or more of the following keywords:

• OBSERVATION_NAME or
• OBSERVATION_ID or
• PRODUCT_NAME or
• DATA_SET_ID + PRODUCT_ID or
• DATA_SET_ID

So if OBSERVATION_NAME exists in the PDS3 label, it will use that to populate the title element. If it does not exist, it will use OBSERVATION_ID. If that does not exist, then it will use PRODUCT_NAME, and so forth.

Investigation_Area

For the Investigation_Area, the tool will use MISSION_NAME to populate this element in the following manner:

<name>${MISSION_NAME}</name>
<type>Mission</type>
<Internal_Reference>
  <lid_reference>urn:nasa:pds:investigation.${MISSION_NAME}</lid_reference>
  <reference_type>data_to_investigation</reference_type>
</Internal_Reference>
        

If MISSION_NAME does not exist, then the tool will use MISSION_PHASE_NAME instead.

Observing_System

For the Observing_System, the tool will populate this element with INSTRUMENT_HOST_NAME, INSTRUMENT_NAME, and INSTRUMENT_ID in the following manner:

<Observing_System_Component>
  <name>${INSTRUMENT_HOST_NAME}</name>
  <type>Spacecraft</type>
</Observing_System_Component>

<Observing_System_Component>
  <name>${INSTRUMENT_NAME}</name>
  <type>Instrument</type>
</Observing_System_Component>

<Observing_System_Component>
  <name>${INSTRUMENT_ID}</name>
  <type>Instrument</type>
</Observing_System_Component>