13.2. How-To

13.2.2.1. Standard Mode

The standard mode of operation for DIRSIG entails the generation of images for all the sensor bands set-up in the specified CFG file. To run in standard mode, the user runs DIRSIG with the specified CFG file:

      prompt> dirsig example.cfg
    

The standard mode can be explicitly requested by supplying the -standard option:

      prompt> dirsig -standard example.cfg
    

Once DIRSIG starts execution, the model will begin to output messages regarding the progress of the model (the details of which are discussed in the section titled "Understanding DIRSIG program output"). In many cases, the user may wish to start the execution of a DIRSIG run and then logout from the machine. In these instances, it is wise to redirect the output from the model into a log file for later review. This can be achieved using the standard redirection facilities available in most UNIX shells. The following example describes the syntax for C-Shell (the most common UNIX shell):

      prompt> dirsig example.cfg >& example.log &
      [1] 4071
      prompt>
    

This command line will capture both the standard and error message output (indicated by the \>& characters) from the DIRSIG run and store it in a file called example.log. Additionally, the trailing & character indicates that we wanted this program to be executed "in the background" so that control will immediately return to your shell.

If you wish to check the progress of a DIRSIG run that is still executing, the end of the log file can always be checked using the standard UNIX tail command:

      prompt> tail example.log 
      Rendering line #13
      Rendering line #14
      Rendering line #15
      Rendering line #16
      Rendering line #17
      Rendering line #18
      Rendering line #19
      Rendering line #20
      Rendering line #21
      Rendering line #22
      Rendering line #23

      prompt>
    

If the user wishes to continually monitor the log file, the -f option can be supplied to tail as follows:

      prompt> tail -f example.log 
      Rendering line #24
      Rendering line #25
      Rendering line #26
    

Using this option, the screen will be updated as each new line is completed by the model. Although this may be a convenient means to monitor the model's progress, it will also consume some computation and I/O resources and slow down the model's execution.

13.2.2.2. Preview Mode

When the user is configuring the sensor platform for complex viewing geometries, or is importing flight data for a scanning platform it is desirable to run DIRSIG in a "quick-look" mode to verify these viewing parameters. The -preview option to DIRSIG loads the geometric databases and sensor configuration in the same manner as -standard mode, except that the rendered scene does not include any surface modeling characteristics. The output image is written to a single file called preview.img and is essentially a material map of the scene as seen by the configured sensor. The benefit of preview mode is that the user can quickly generate an image with many of the geometric information required to verify their sensor parameters. Depending on the complexity of the scenario, a DIRSIG preview mode run will take a few minutes on most modern workstations.

This mode is extremely valuable when adjusting the sensor's location to acquire a specific target or when attempting to adjust a flight to image a specific region of your seen. The image in Figure 13-1 is an example preview image generated from a pushbroom scanner simulation over the Foxbat scene.

13.2.2.3. Probe Pixel Mode

In some cases the user may wish to examine the intermediate values that contribute to the final spectral radiance for a given pixel. The probe pixel mode allows the user to run DIRSIG on a per pixel basis and output internal spectral and non-spectral values to a file. In most cases, it is desirable to generate the entire image first (using the standard mode) so that the image coordinates of candidate pixels can be determined.

To utilize the probe pixel mode, the user must first prepare a file that contains a list of the pixel coordinates and the name output file to record the values for the pixel in. For example, the contents of an example pixel list file is shown below:

      31 32 pixel_31-32.probe
      33 32 pixel_33-32.probe
      55 37 pixel_54-36.probe
      55 18 pixel_54-17.probe
    

The first two values on each line are the X and Y coordinates (using a 0 to N-1 convention) of the pixel in the output image to be examined. The last value on each line is the name of the file that the results of this pixel will be written to. If the name of this file is probe_example.list, then the complete command line for calling DIRSIG using this pixel list file is:

      prompt> dirsig -probe probe_example.list example.cfg
    

When DIRSIG starts, the model will initialize itself the same way it does in standard mode. Once all the data required for the simulation has been loaded, DIRSIG will compute and record the available values for each pixel in the pixel list file. An example probed pixel output file is illustrated below:

# DIRSIG Probe Pixel output file

# Non-Spectral information
First opaque surface {
    Material ID = 16
    Surface temperature = -273.15
    In solar shadow = FALSE
    In lunar shadow = TRUE
    Hit point = (34.772362, -35.520069, 28.959652)
    Hit angle = 51.0824
    Sky fraction = 1.0000
}

# Spectral information
#     Wavelength units are [microns]
#     Radiance units are [W/(cm^2 sr microns)]
#            Incident    Surface      Surface      Plume        Total
# Wavelength Radiance    Reflectance  Emission     Radiance     Radiance
    0.400  2.03402e-03  9.69529e-02  0.00000e+00  0.00000e+00  3.24152e-03
    0.417  2.50938e-03  9.69529e-02  0.00000e+00  0.00000e+00  3.76652e-03
    0.435  2.62732e-03  9.69529e-02  0.00000e+00  0.00000e+00  3.72628e-03
    0.455  3.28191e-03  9.69529e-02  0.00000e+00  0.00000e+00  4.42011e-03
    0.476  3.47410e-03  9.69529e-02  0.00000e+00  0.00000e+00  4.46881e-03
    0.500  3.39299e-03  9.69529e-02  0.00000e+00  0.00000e+00  4.18858e-03
    0.526  3.38536e-03  9.69529e-02  0.00000e+00  0.00000e+00  4.02430e-03
    0.556  3.43463e-03  9.69529e-02  0.00000e+00  0.00000e+00  3.89857e-03
    0.588  3.29708e-03  9.69529e-02  0.00000e+00  0.00000e+00  3.35636e-03
    0.625  3.14550e-03  9.69529e-02  0.00000e+00  0.00000e+00  3.24684e-03
    0.667  2.91897e-03  9.69529e-02  0.00000e+00  0.00000e+00  2.71659e-03
    0.714  2.80185e-03  9.69529e-02  0.00000e+00  0.00000e+00  1.58048e-03
    

The non-spectral section of the file includes information about the surface or surfaces that were imaged by the pixel. This information includes the material ID number, the surface temperature, shadowing conditions, the intersected location on the surface, the angle between the surface normal and the sensor ray, and the sky fraction. Note that the surface temperature and sky fraction fraction values will depend on whether the temperature and bi-directional reflectance computations enabled.

The spectral section will contain spectral data for all the sensor bands configured in the CFG file. The incident radiance is combination of the solar, lunar, man-made and sky radiance incident on the surface. The surface reflectance is the hemispherical reflectance of the surface. The surface emission is the graybody emission from the surface. The plume radiance is the radiance from the internal plume model along the path to the surface. The total radiance is the final computed radiance before the detector response function.

It is important to note that the total radiance may not reflect the combination of the individual components listed in the file. The relative amounts of reflected radiance from the various sources of incident radiance depend on the angles of incidence and the bi-directional reflectance properties of the surface. The surface reflectance is the hemispherical reflectance and does not describe the various specific reflectance factor utilized in the reflected radiance computation for each reflected source.

13.2.2.4. Restart Mode

The final DIRSIG run mode of interest is referred to as restart mode. Some simulations require extensive run-times and during those modeling runs the simulation may be aborted because the machine running the model crashed, or the disk that the model was writing too filled up. In those instances, it would be desirable for all of the accumulated results to be saved and have the model "restart" where it left off. This capability is what the restart mode provides.

While DIRSIG is running, it routinely writes the model status to a special file called a "restart" file. The name of this file is created by appending the .rst extension to the DIRSIG Input Configuration File used for the simulation. If the simulation successfully completes, DIRSIG will delete this restart/status file. However, if the simulation is aborted for any reason, this status file can be used to restart DIRSIG where it left off.

For this example, the user was running a simulation described by the DIRSIG Input Configuration File my_sim.cfg. While the model is running, the status file my_sim.cfg.rst is routinely updated. If the simulation is aborted, this status file should be found in the directory where the model was run from. To restart the DIRSIG model using the status file, use the following syntax:

      prompt> dirsig -restart my_sim.cfg.rst
    

The model will initialize itself in the same manner that it does when the model is run under normal conditions. However, after the model has loaded all the required data, it should start rendering near where the model was when it aborted rather than at the beginning.

13.2.3.1. Supported Platforms

The DIRSIG model is also available as a parallel version for most supported platforms. The host parallel computer must have support for the parallel programming Message Passing Interface (MPI). The specific subsystem to support MPI-based programs on each host platform varies:

• On the Solaris platform, this subsystem is "Sun HPC ClusterTools" which is supported on Sun's SMP (Symmetric Multi-Processing) hardware. More information about ClusterTools can be found at the Sun HPC website:

• On the Linux platform, this subsystem is "LAM" (Local Area Multicomputer) which allows separate computers to form a virtual parallel computer (sometimes referred to "Beowulf Clusters"). The LAM software is included in most Linux distributions, but it might not be installed by default. However, the software is open-source (like most Linux software) and can be downloaded and installed from the LAM/MPI website:

The setup of the MPI environment to run MPI-based programs on each platform is something that is beyond the scope of this manual. However, documentation and support is usually available from your hardware and/or operating system vendor.

13.2.3.2. Running DIRSIG in parallel mode

To run DIRSIG on a parallel processing computer you do not use the standard or serial version DIRSIG program described in the previous sections. A slightly different version of the program is used that includes all the code to use the MPI interface to distribute the computations to each of the processor nodes. This program is called dirsig-mpi (or dirsig-X.X.X-mpi where "X.X.X" represents the release identifier, for example dirsig-3.6.4-mpi).

To run an MPI-based parallel processing program on most platforms involves running the desired program with the help of an executor program. On most platforms, this executor program is called mpirun or mprun, and the purpose of this program is to simplify the differences of running parallel program on different types of hardware and configurations.

To run a simulation, the command line is slightly different than using the standard DIRSIG program. Assuming that the name of the MPI executor program is called mpirun and you want to run a simulation described in my_sim.cfg in standard mode, you would need to use the following command line syntax:

      prompt> mpirun -np 8 dirsig-mpi my_sim.cfg
    

The -np 8 tells the MPI subsystem that we want to use 8 processors. This number can be as many as you want up to the number of physical processors available. The parallel version of DIRSIG uses a master/slave design that is best suited for true multiple processor machines (e.g. the number of processors is greater than two (2)). In this design, one of the processors (the "master") is in charge of distributing computations and writing the generated data to the output files, and the remaining processors (the "slaves") receive computations from the "master", perform those computations and send the results back to the "master". Therefore, on computer with only two (2) processors, the model does not run faster than a single processor since there is only one (1) slave processor doing all the computations.

13.2.3.3. Troubleshooting a parallel run

In the event that the DIRSIG model does not run to completion, the MPI environment can make it difficult to understand what exactly went wrong. In many cases, mpirun will report a short error message that a "bad" message was received from a specific node or that a specific node has exited. In these cases, it is helpful to consult the log files that are created by the DIRSIG "slave" processors. If you ran the simulation with eight (8) processors, then there should be eight (8) log files named dirsig-1.log through dirsig-8.log. If the error message includes a specific node number that generated the error, then you should be able to look at the end of the log file from that node number and see what went wrong. However, it is suggested that all of the log files be consulted.

In practice, if a simulation runs correctly with the serial version of DIRSIG then it should run correctly with the parallel version.