Software Documentation
- About Generate Tool
- Design
- Installation
- Operation
- Template Guide
Download
Project Documentation
This document describes how to operate the Generate Tool software. The following topics can be found in this document:
Note: The command-line examples in this section have been broken into multiple lines for readability. The commands should be reassembled into a single line prior to execution.
Generate Tool can be executed in various ways. This section describes how to run the tool, as well as its behaviors and caveats.
The following table describes the command-line options available:
| Command-Line Option | Description |
|---|---|
| -b,--base-path <base path mask> | Specify the base file path mask to be stripped from the input file path to allow output in a relative directory structure. Requires -o flag to also be specified. |
| -d,--debug | Verbose debugging output. Shows each step of parsing and label generation. |
| -h,--help | Display usage. |
| -o,--output-path <output path> | Specify an output path to output the new PDS4 labels. By default, the file will output in same location as the input file. |
| -p,--pds3-label <pds3 label> | Parse the file or list of files as PDS3 Standard labels (also applicable for VICAR labels). |
| -t,--template <velocity template> | Specify the file path for the Velocity template used to convert the input label(s). |
| -I, --include <paths> | Specify paths to search for files referenced by pointers in a label. This flag is valid only when using the product-tools library as the underlying parser. Separate each path with a comma. Default is to always look in the directory of the label, then search the specified directories. |
| -V,--version | Display application version. |
This section demonstrates execution of the tool using the command-line options. The examples below execute the tool via the batch/shell script.
The following command demonstrates how to run the Generate Tool to convert from a PDS3 Label to a PDS4 Label using a Velocity template file and output to a file:
% generate -p <pds3-label-path> -t <velocity-template-path>
The output would go into a file <pds3-label-path>.xml (i.e. $HOME/mpf123.img -> $HOME/mpf123.xml
The following command demonstrates how to run the Generate Tool to convert from a PDS3 Label to a PDS4 Label using a Velocity template file and output all debug information to standard out:
% generate -d -p <pds3-label-path> -t <velocity-template-path>
This section describes more advanced ways to run the tool, as well as its behaviors and caveats.
The Generate Tool defaults to using the VicarIO library as the underlying parser when parsing input labels. The tool provides a capability to change the underlying parser to use the Product-Tools library instead. A common use case of changing the underlying parser is when an input label contains a ^STRUCTURE pointer. This section details how to set the underlying parser to the product-tools library.
UNIX-Based Environment
To change the underlying parser, set the pds.generate.parser.type Java system property to product-tools in the generate shell script as follows:
Change the following line
"${JAVA_HOME}"/bin/java -jar ${GENERATE_JAR} "$@"
to
"${JAVA_HOME}"/bin/java -Dpds.generate.parser.type=product-tools -jar ${GENERATE_JAR} "$@"
Windows Environmnet
To change the underlying parser, set the pds.generate.parser.type Java system property to product-tools in the generate.bat batch file as follows:
Change the following line
"%JAVA_HOME%"\bin\java -jar "%GENERATE_JAR%" %*
to
"%JAVA_HOME%"\bin\java -Dpds.generate.parser.type=product-tools -jar "%GENERATE_JAR%" %*
API Method
When calling the Generate Tool through the API, add the following line of code to change the underlying parser to use the Product-Tools library:
System.setProperty("pds.generate.parser.type", "product-tools");