Example Products

The Transform Tool package contains an examples/ folder which contains example PDS3 and PDS4 data products. The intent is to provide example products to demonstrate the different transformations that can be performed by the tool. The table below lists the target inputs that can be passed into the tool and the format types that are valid for each target input listed:

Format Types

The following table lists the output formats available to both PDS3 and PDS4 target inputs:

The following table lists the output formats available to only PDS4 target inputs:

The following table lists the output formats available to only PDS3 target inputs:

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. Other notable caveats with this version of the tool include:

• 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:

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

The tool creates an output file on the current working directory using the target image file name with the user-specified format as the file extension. Using the example above, the tool creates the output file i943630r.jpg.

To write the output file in another directory location, use the -o flag option. The following command demonstrates writing the output to a location named /home/pds/images:

% transform ../examples/i943630r.xml -f jpg -o /home/pds/images          
        

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.IMG, into a gif image file named FHA01118.gif:

% transform ../examples/FHA01118.IMG -f gif
        

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
        

Transforming Complex Labels

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
    object type = Table_Character
    name = null
    local identifier = TABLE_CHAR_1
    records = 23
    record length = 88
    groups = 0
    fields = 10

    index = 2
    object type = Table_Character
    name = null
    local identifier = TABLE_CHAR_2
    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
    object type = Table_Character
    name = null
    local identifier = PHX-M-TT-5-WIND-VEL-DIR_TABLE_CHAR
    records = 23
    record length = 88
    groups = 0
    fields = 10

  Data file: PDS4_TABLE_DELIMITED.csv

    index = 1
    object type = Table_Delimited
    name = null
    local identifier = null
    records = 3
    groups = 0
    fields = 13

  Data file: 2d234493326edratf3d2537n0m1.dat

    index = 1
    object type = Table_Binary
    name = null
    local identifier = null
    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
    object type = Array_2D_Image
    name = Primary Data Unit
    local identifier = PDU
    data type = IEEE754LSBSingle
    lines = 1024
    samples = 1024

    index = 2
    object type = Array_2D_Image
    name = Secondary Data Unit (Full Detector Array
    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.

Improving Tool Performance

The Transform Tool uses the Java Advanced Imaging (JAI) library to perform image transformations. By default, the tool turns off JAI's acceleration layer since that requires installing platform-dependent libraries. The purpose of the acceleration layer is to improve image processing performance. This section details how to install the platform dependent libraries locally to enable the acceleration layer if needed.

Mac OS X Environment

For Mac OS X platforms, they automatically ship with these dependency libraries. They should be found at the following location: /System/Library/Java/Extensions and should contain the following files:

• libmlib_jai.jnilib
• mlibwrapper_jai.jar

So, to enable JAI's native acceleration feature, open the bin/transform shell script file and remove the -Dcom.sun.media.jai.disableMediaLib=true setting from the command-line call in the script. The resulting command-line call should look like the following:

"${JAVA_HOME}"/bin/java -Xms256m -Xmx1024m -Doverwrite.output=true -Dexternal.programs.home=${PARENT_DIR}/external-programs -jar ${TRANSFORM_JAR} "$@"    
        

To check that the native acceleration feature is working, run an image transformation:

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

Verify that an "Error: Could not find mediaLib accelerator wrapper classes. Continuing in pure Java mode." message does not appear during the transformation.

UNIX-Based Environment

For Unix and Linux installations, download the appropriate installer located in the Java Advanced Imaging Image I/O Tools 1.0_01 section from here. Once the installer has finished downloading, double-click the file and follow the installation instructions.

Once this installation step is complete, open the bin/transform shell script file and remove the -Dcom.sun.media.jai.disableMediaLib=true setting from the command-line call in the script. The resulting command-line call should look like the following:

"${JAVA_HOME}"/bin/java -Xms256m -Xmx1024m -Doverwrite.output=true -Dexternal.programs.home=${PARENT_DIR}/external-programs -jar ${TRANSFORM_JAR} "$@"    
        

To check that the native acceleration feature is working, run an image transformation:

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

Verify that an "Error: Could not find mediaLib accelerator wrapper classes. Continuing in pure Java mode." message does not appear during the transformation.

Windows Environment

Download the appropriate Windows installer located in the Java Advanced Imaging Image I/O Tools 1.0_01 section from here. Once the installer has finished downloading, double-click the file and follow the installation instructions.

Once this installation step is complete, open the bin/transform.bat batch file and remove the -Dcom.sun.media.jai.disableMediaLib=true setting from the command-line call in the script. The resulting command-line call should look like the following:

"%JAVA_HOME%"\bin\java -Xms256m -Xmx1024m -Doverwrite.output=true -Dexternal.programs.home=%PARENT_DIR%\external-programs -jar "%TRANSFORM_JAR%" %*       
        

To check that the native acceleration feature is working, run an image transformation:

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

Verify that an "Error: Could not find mediaLib accelerator wrapper classes. Continuing in pure Java mode." message does not appear during the transformation.

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 existence 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>
        

Naming Convention of PDS3 Objects

In order to support multiple table and image objects in a label, the tool uses the following naming convention for objects:

 TRANSFORM<int value>_<object type>
        

where int value represents an integer value and object type represents the type of object (e.g. IMAGE, TABLE, SPREADSHEET). As an example, if a PDS4 label contains multiple table objects, then the objects will have the following names:

• TRANSFORM1_TABLE
• TRANSFORM2_TABLE
• TRANSFORM3_TABLE
• ...

Populating PDS3 Objects

Mapping from a PDS4 object to its PDS3 equivalent is mostly a straightforward process. However, it has been discovered that there are some non-required elements of a PDS4 object that are found to be required for its PDS3 equivalent object. This section details what those inconsistencies are and what the tool does to populate those required attributes.

Delimited Tables

For PDS4 Delimited Tables, if the Record_Delimited area is missing the optional maximum_record_length element, the tool will default to populating the required ROW_BYTES attribute to 10000 in the equivalent PDS3 SPREADSHEET object. Furthermore, if a Field_Delimited area is missing its optional maximum_field_length element, then the tool will default to populating the required BYTES attribute to 256 in the equivalent PDS3 FIELD object.

Mapping of Group_Field_Delimited elements is not supported at this time as it is missing elements needed to calculate the required BYTES attribute value for a PDS3 CONTAINER object.