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.
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:
-standardoption refers to what we call Normal mode in the GUI, which runs the model with "full radiometry". This option is the default.
-previewoptions is used to switch to Preview mode in the GUI.
-xmloption was actually the most common usage once users stopped using DIRSIG3 input files.
-interactivesyntax printed in the usage was incorrect.
-licensesoption 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.
-standardoption 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
-previewoptions 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
.optionsfile 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).
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)
Although the syntax is verbose, the
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
$ dirsig4 --cfg_filename=foo.cfg
DIRSIG4 Simulation File Syntax
The primary argument the user needs to supply is the simulation description
as a DIRSIG4
$ 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
file or a DIRSIG4
.sim file by looking at the extension of the supplied
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
$ dirsig4 --scene_filename=foo.scene --atm_filename=foo.atm \ --platform_filename=foo.platform --motion_filename=foo.ppd \ --tasks_filename=foo.tasks
|The order of the component mode arguments is not important, just that each component argument is supplied.|
--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
0.0. To achive this, the
--task_start option can be
$ 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
If the user desires to change the duration, they can utilize the
$ 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 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 ...
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
|The resume mode is only available to resume a previous "normal" or full-radiometry simulation.|
|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
$ dirsig4 --random_seed=1234 ...
The user can directly print the usage message by either supplying
no command-line options or by explicitly supplying the
$ dirsig4 --help
Display 3rd Party Licenses
The user can print the 3rd party licenses using either the
$ dirsig4 --license
$ 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
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
band1.img file will be
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"
The quotations are required so that DIRSIG doesn’t parse the
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
.scenefile describing the scene.
The name of the
.atmfile 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.