Template Guide

The Generate Tool leverages Apache Velocity Templates to provide a robust, generic method of creating PDS4 Labels. The labels can be generated from an existing PDS3 label (attached or detached) or some other defined data object. This section contains the various scenarios that the base version of the tool handles. Scenarios, in this context, can be defined as the specific types of problems a user may come across when attempting to develop a PDS4 label. These will be extended as the the data objects and PDS4 standard become more refined.

This section contains the following information:

Scenario Format

Each scenario described below will follow a format in order to provide a tutorial-like experience when developing a PDS4 label. The progression through a scenario will include a problem description, PDS3 label input (if applicable), the desired PDS4 output, and the Velocity Template solution.

PDS3 (if applicable) (pds3_example.lbl) 
PDS3 Label Input
PDS4 (pds4_example.xml) 
PDS4 XML Output
Velocity (template_example.vm) 
Velocity Template Solution

Scenarios

The scenarios provided are some of the problems elicited from translating from data objects, specifically PDS3 standard, into PDS4. They are by no means all inclusive. These solutions are NOT PDS4-compliant, they are simply proof-of-concept examples to prove the functionality of the tool and how they can be applied to PDS4-compliant labels.

Hard-Coded Value

Allows the user to specify default values for a tag.

PDS4 
<Product_Array_2D_Image>
  <Data_Standards>
    <dd_version_id>0311B_20110709</dd_version_id>
  </Data_Standards>
</Product_Array_2D_Image>
Velocity 
<Product_Array_2D_Image>
  <Data_Standards>
    <dd_version_id>0311B_20110709</dd_version_id>
  </Data_Standards>
</Product_Array_2D_Image>

Base Element

Provides a mechanism for translating base elements from PDS3 to PDS4. A base element in a PDS3 label is a KEYWORD-VALUE that is not a part of an OBJECT or GROUP. Often seen flush up against the left side of the label file.

PDS3 
TARGET_NAME		= "DEIMOS"
PDS4 
<Subject_Area>
  <target_name>DEIMOS</target_name>
</Subject_Area>
Velocity 
<Subject_Area>
  <target_name>$label.TARGET_NAME</target_name>
</Subject_Area>

Sub-Element

Provides a mechanism for translating sub-elements from PDS3 to PDS4. A sub-element in a PDS3 label is a KEYWORD-VALUE that is included within an OBJECT or GROUP.

PDS3 
OBJECT				= IMAGE
	MEAN			= 8.6319
	MEDIAN			= 8
	MINIMUM			= 8
END_OBJECT			= IMAGE
PDS4 
<Object_Statistics>
  <mean>8.6319</maximum>
  <median>8</mean>
  <minimum>8</median>
</Object_Statistics>
Velocity 
<Object_Statistics>
  <mean>$label.IMAGE.MEAN</mean>
  <median>$label.IMAGE.MEDIAN</median>
  <minimum>$label.IMAGE.MINIMUM</minimum>
</Object_Statistics>

Note: For keywords within nested OBJECTs/GROUPs, simply continue the dot notation, i.e. $label.OBJECT1.OBJECT2.KEYWORD

Multiple Instance

Provides a mechanism for translating PDS3 Keywords with an array of values into multiple instances of a PDS4 class.

PDS3 
GROUP				= BAND_BIN
  BANDS 			= 4
  BAND_BIN_UNIT			= MICROMETER
  CENTER			= (0.374, 0.384, 0.394, 0.404)
  WIDTH				= (0.0155, 0.0115, 0.0114, 0.0112)
END_GROUP			= BAND_BIN
PDS4 
<Band_Bin_Set>
  <Band_Bin>
    <center>0.374</center>
    <width>0.0155</width>
  </Band_Bin>
  <Band_Bin>
    <center>0.384</center>
    <width>0.0115</width>
  </Band_Bin>
  <Band_Bin>
    <center>0.394</center>
    <width>0.0114</width>
  </Band_Bin>
  <Band_Bin>
    <center>0.404</center>
    <width>0.0112</width>
  </Band_Bin>
</Band_Bin_Set>
Velocity 
<!-- Scenario 4 - Multiple Instances  -->
<Band_Bin_Set>
<!-- Get size of one of the arrays from the PDS3 Label -->
#set($length = $label.BAND_BIN.CENTER.size())
<!-- Loop through the length of the array -->
#foreach ( $i in [1..$length] )
  <Band_Bin>
     <center>$label.BAND_BIN.CENTER.get($foreach.index)</center>
     <width>$label.BAND_BIN.WIDTH.get($foreach.index)</width>
  </Band_Bin>
#end
</Band_Bin_Set>

Same Class-Different Value

Provides a mechanism for translating multiple KEYWORD-VALUE combinations into multiple instances of the same class.

PDS3 
OBJECT					= IMAGE
  INTERCHANGE_FORMAT			= BINARY
  LINES					= 192
  LINE_SAMPLES				= 320
END_OBJECT				= IMAGE
PDS4 
<Array_Axis>
  <name>SAMPLES</name>
  <elements>320</elements>
  <sequence_number>1</sequence_number>
</Array_Axis>
<Array_Axis>
  <name>LINES</name>
  <elements>192</elements>
  <sequence_number>2</sequence_number>
</Array_Axis>
Velocity 
<Array_Axis>
  <name>SAMPLES</name>
  <elements>$label.IMAGE.LINE_SAMPLES</elements>
  <sequence_number>1</sequence_number>
</Array_Axis>
<Array_Axis>
  <name>LINES</name>
  <elements>$label.IMAGE.LINES</elements>
  <sequence_number>2</sequence_number>
</Array_Axis>

Units

Provides a mechanism for translating a PDS3 KEYWORD-VALUE along with its units into PDS4 standard.

PDS3 
INST_AZIMUTH			= 114.0210 <deg>
PDS4 
<Geometry_Parameters>
  <azimuth units="deg">114.0210</azimuth>
</Geometry_Parameters>
Velocity 
<Geometry_Parameters>
  <azimuth units="$label.getUnits('INST_AZIMUTH')">$label.INST_AZIMUTH</azimuth>
</Geometry_Parameters>

Generated Value

Provides a mechanism for generating values of keywords from known algorithms. This aspect of the software can be extended, if necessary.

PDS4 
<File_Area>
  <md5_checksum>2a6f0be7f63d0aa032457f1f29d3e51d</md5_checksum>
</File_Area>
Velocity 
<File_Area>
  <md5_checksum>$generate.md5_checksum</md5_checksum>
</File_Area>

Note: The currently available generated values include:

  • md5_checksum
  • file_name
  • file_size

Examples

The following examples are NOT finished products or follow PDS4 standards. They are merely proof-of-concept.

Common Errors

Object Not Found

<generated-node>Object Not Found</generated-node>

When a node is populated with the text "Object Not Found", it means that the keyword specified was not found. This error applies to generated values and often means that either the mapping was not specified in the generated-mappings.xml, or the class was never created to generate that value

Advanced Users

See the Velocity User Guide for more detailed documentation on leveraging the Java objects represented by the variables noted above (label, bandBinList, etc.).

References