This guide outlines the command-line interface to the DIRSIG4 model.

The goal of a robust set of command-line options is to better facilitate scripting and management of simulations. To address the limitations of the options in earlier releases, a new set of options were introduced with the DIRSIG 4.5.0 release.

Backward Compatibility

The following are the "old options" as outlined in the DIRSIG4 usage message prior to DIRSIG 4.5:

usage: dirsig4 [options] <CFG file>
    where [options] are:
    -standard                                   standard mode
    -xml                                        standard xml mode
    -preview                                    preview mode
    -interactive <Collector XML> <Bandpass XML> interactive mode
    -licenses                                   third party licenses

Here are a few notes and issues regarding the those old command-line options:

  • The -standard option refers to what we call Normal mode in the GUI, which runs the model with "full radiometry". This option is the default.

  • The -preview options is used to switch to Preview mode in the GUI.

  • The -xml option was actually the most common usage once users stopped using DIRSIG3 input files.

  • The -interactive syntax printed in the usage was incorrect.

  • The -licenses option printed licenses for all 3rd party software utilized in the DIRSIG software.

The old options had several limitations:

  • The old options did not really convey clear meaning or choices in many cases.

    • The -standard option was frequently confused with an non-existent option to specify a CFG file rather than a SIM file.

  • The parsing of the old options did not enforce mutual exclusions.

    • For example, supplying both the -standard and -preview options should have generated an error (full radiometry vs. preview) but it did not.

  • The old options supported a poorly documented component files syntax via the command-line.

    • This alternative to supplying a SIM file was actually very useful.

    • However, the old syntax was awkward. The order of the component files required the .options file to be specified first. But if the user didn’t have one, they needed to indicate this with an "empty" argument defined by a pair of double quotes (e.g. "").

All of the old command-line options are still be supported (but they are not advertised in the usage message).

Traditional Simulations

The following is the usage message generated by DIRSIG:

DIRSIG4
Release: 4.5.0 (r12082)
Build Date: Feb 15 2013 14:27:49
Copyright 2005-2013 Rochester Institute of Technology

Auto-sensing, full radiometry simulation syntax:
    dirsig <cfg_filename>
    dirsig <sim_filename>

Input file options:
    --cfg_filename=<filename>
    --sim_filename=<filename>
    --scene_filename=<filename> --atm_filename<filename> --platform_filename=<filename> --motion_filename=<filename> ...

Execution mode options:
    --mode=normal ...        (full radiometry)
    --mode=resume ...        (resume full radiometry)
    --mode=preview ...       (preview mode)
    --mode=interactive ...   (interactive radiometry)

Interactive mode inputs:
    --scene_filename=<filename>
    --atm_filename=<filename>
    --collector_filename=<filename>
    --bandpass_filename=<filename>
    --datetime=<ISO 8601>
   [--options_filename=<filename>]

Output options:
    --output_folder=<foldername>
    --output_prefix=<prefix>

General options:
    --version                (display version)
    --help                   (display usage)
    --licenses               (display 3rd party licenses)
    --random_seed=<value>    (set common seed value)
Note Although the syntax is verbose, the --option=value syntax is very easy to parse and to detect errors. Each token in the command line is a complete option rather than it sometimes being one token for some options and two for others, etc.

DIRSIG3 Simulation File Syntax

If you are running DIRSIG with a DIRSIG3 era simulation configuration file, the user needs to specify that file via the --cfg_filename option:

$ dirsig4 --cfg_filename=foo.cfg

DIRSIG4 Simulation File Syntax

The primary argument the user needs to supply is the simulation description as a DIRSIG4 .sim file:

$ dirsig4 --sim_filename=foo.sim

Auto-Sensing DIRSIG3 vs. DIRSIG4 Input Files

The "lightweight" command-line syntax supports a basic, full-radiometry run, which is used for 99% of all simulations:

$ dirsig4 foo.sim

Note that the model will auto-detect if this is an older DIRSIG3 .cfg file or a DIRSIG4 .sim file by looking at the extension of the supplied filename.

Using DIRSIG4 Component Files

To simplify the scripting of many simulations, DIRSIG also supports a component files syntax, where the user direcly provides the list of input component files with explicit options, rather than via a .sim file:

$ dirsig4 --scene_filename=foo.scene --atm_filename=foo.atm \
    --platform_filename=foo.platform --motion_filename=foo.ppd \
    --tasks_filename=foo.tasks
Note The order of the component mode arguments is not important, just that each component argument is supplied.

The --options_filename option is only required when the user desires to supply an options file.

The user can also define a single task via the command-line (rather than supplying a .tasks file) with the following syntax:

$ dirsig4 --scene_filename=foo.scene --atm_filename=foo.atm \
    --platform_filename=foo.platform --motion_filename=foo.ppd \
    --datetime="2008-07-29T14:35:00.0000-05:00"

This usage automatically constructs a task with a relative start and stop time of 0.0 seconds. If the simulation uses any relative time components (e.g. motion models with relative times), then it is sometimes desireable to give that internal task a relative start time of a value other than 0.0. To achive this, the --task_start option can be added:

$ dirsig4 --scene_filename=foo.scene --atm_filename=foo.atm \
    --platform_filename=foo.platform --motion_filename=foo.ppd \
    --datetime="2008-07-29T14:35:00.0000-05:00" --task_start=0.8

The previous example creates a single task with a duration of 0 seconds. If the user desires to change the duration, they can utilize the --task_duration option:

$ dirsig4 --scene_filename=foo.scene --atm_filename=foo.atm \
    --platform_filename=foo.platform --motion_filename=foo.ppd \
    --datetime="2008-07-29T14:35:00.0000-05:00" --task_duration=10

where the value of 10 indicates that the automatically constructed task has a duration of 10 seconds. This option can be combined with the --task_start option.

Additional Options

Execution Mode

The next option deals with what calculations the model is supposed to perform during the run. There are currently four, mutually exclusive options:

  • A "normal" or full radiometry simulation (the default).

  • "Resume" a "normal" or full radiometry simulation.

  • A "preview" or minimal simulation.

  • An "interactive" radiometry simulation (discussed in greater detail in this section).

The corresponding command-line syntax for these is:

$ dirsig4 --mode=normal ...
$ dirsig4 --mode=resume ...
$ dirsig4 --mode=preview ...
$ dirsig4 --mode=interactive ...

Minimal Simulation

The preview mode is provided as a fast way to generate representative output data while bypassing most of the internal calculations. The exact behavior of preview mode is dependent of the modality being modeled.

For passive simulations, preview mode reports the material ID of first surface seen by a pixel in the output image (much like a truth image) and reduces the sub-sampling to 1x1. No actual radiometry is done in this case and the output imagery is for visualization purposes only (e.g. to preview the FOV).

For LIDAR simulations, preview mode generates direct returns from surfaces. This provides enough information to check the appropriateness of the modeled time gate.

Resuming a Simulation

If for some reason a previous simulation was terminated before it completed (power outage, ran out of disk space, etc.) the simulation can be resumed. The software will reload all the inputs, determine how far it made it into the simulation and then resume the simulation at that point. The syntax to resume a simulation is to specify the resume execution mode:

$ dirsig4 --mode=resume foo.sim
Note The resume mode is only available to resume a previous "normal" or full-radiometry simulation.
Warning The resume option can only be used for passive EO/IR simulations at this time. You cannot resume a LIDAR or RADAR simulation (yet).

Setting the primary random seed

To specify the global random seed for a simulation, use the --random_seed option:

$ dirsig4 --random_seed=1234 ...

Display Usage/Help

The user can directly print the usage message by either supplying no command-line options or by explicitly supplying the --help option:

$ dirsig4 --help

Display 3rd Party Licenses

The user can print the 3rd party licenses using either the --license or -licenses option:

$ dirsig4 --license

or

$ dirsig4 --licenses

Output Folder and File Options

Specify the Output Folder

This option allows the user to specify the folder (directory) that all output files should be written to:

$ dirsig4 ... --output_folder=/Users/dirsig/output/sim1

For example, if a focal plane routes data to a file with the name band1.img, the file will be /Users/dirsig/output/sim1/band1.img

Specify an Output File Prefix

This option allows the user to specify a prefix for all output files that are written to:

$ dirsig4 ... --output_prefix=run1_

For example, when combined with the output folder option above, the same band1.img file will be /Users/dirsig/output/sim1/run1_band1.img

Options Dictionary Injection

One desired feature would be to add options on the command-line rather than via the .options file dictionary. For example, if the user wants to set the atm.verbose option to true, that can be performed via the command-line, with the following syntax:

$ dirsig4 ... --option="atm.verbose=true"
Note The quotations are required so that DIRSIG doesn’t parse the = within the option assignment.

Interactive Mode Simulations

The DIRSIG model supports an interactive mode, which facilitates integration of the model with third-party tools. To start DIRSIG in interactive mode, the user must supply:

  • The name of the .scene file describing the scene.

  • The name of the .atm file describing the atmospheric conditions.

  • The name of the collector file describing what data will be generated by the model for each inquery.

  • The name of the bandpass file describing the spectral bandpass and sampling to be output for each inquery.

  • The reference date/time as an ISO8601 format string.

$ dirsig4 --mode=interactive --scene_filename=foo.scene \
    --atm_filename=foo.atm \
    --collector_filename=foo.collectors \
    --bandpass_filename=foo.bandpass \
    --datetime="2008-07-29T14:35:00.0000-05:00"

If the user needs to supply a .options file, then the --options_filename option can be supplied.

More information about "interactive mode" can be found in the Interactive Mode Guide.