4.2. Framing Array Tutorial

4.2.2.1. Selecting a GDB file

To begin, we need to select a DIRSIG Geometric Database (commonly referred to as a DIRSIG GDB file). Each DIRSIG distribution comes with a set of pre-constructed DIRSIG scenes. The construction of new DIRSIG scenes is a long and complex process and is not covered in this tutorial. To select the GDB file, click on the Browse button next to the "GDB Filename" edit box. The next window that appears is a standard file selection window. At the top of the window is an edit-able drop-down box box labeled "Look in". We want to select a file that is in the examples/urban directory of the DIRSIG_HOME directory. Unfortunately, the file dialog window does not understand environment variables so we will have to enter the directory manually. Assuming that DIRSIG was installed in /usr/local/dirsig, click on the text in this box and change it to /usr/local/dirsig/examples/urban. Once you press the Return key in this edit box, the contents of the file box will change to show all the files matching the current extension filter in this directory. The default file extension for a DIRSIG GDB file is .gdb. If the contents of the window do not change then the directory path you have specified does not exist or you do not have sufficient permissions to access the contents of the directory. If you have successfully acquired the GDB file list for the Urban scene, then you should be able to either double-click on the file urban1.gdb or single-click on the file and press the Open button to select this file.

4.2.2.2. Setting the GDB file units

The next parameter in this window is the "GDB Units". This drop-down selection box provides the user with a choice of common measurement units. The choice of this parameter instructs DIRSIG on how to interpret the units in the GDB file. Future updates to the DIRSIG GDB file format will include a field to store this information, however, for now this information can be found in the various README files in each scene directory. The units for the Urban scene are Feet. If the user incorrectly selects the GDB units, the scaling of the atmospheric path contributions will be performed incorrectly and unexpected results may occur.

4.2.2.3. Excluding an ODB file

Some DIRSIG scenes are assembled using a different method which will be discussed in another part of this manual. These scenes are stored into a file known as an object database and they have a .odb file extension. The Urban scene is entirely contained in the GDB file we already selected and, therefore, does not have an object database (at this time).

Click the button labeled Use an object database (ODB) file off which will disable the fields associated with this variable.

4.2.2.4. Selecting the material database

Each scene consists of a large family of facets which have been assigned material ID codes by the scene constructor. These material ID's are linked to optical and thermodynamic properties by a DIRSIG material database file (usually denoted by a .mat file extension). The material database file is usually specific to a GDB file since it contains the properties of specific materials featured in the scene. Select the file urban.mat in the /usr/local/dirsig/examples/urban directory with the the Browse button next to the "Material Filename" edit using the same methods used in selecting the GDB file earlier.

4.2.2.5. Setting the date

DIRSIG needs to know the date of the simulation to correctly predict ephemeris data including the position of the Sun and Moon. The parameters inside the "Date" box allow the user set the GMT data for the simulation. The GMT date must be carefully selected when modeling a late evening acquisition. For example, to simulate 11:00 pm EDT on June 1, the user needs to set the date to June 2, since that is the date in Greenwich at the time of the simulation.

4.2.2.6. Setting the time

The user has the ability to set the time as either the Local time at the simulation location or the GMT time. In either case, the user must also specify the GMT offset to avoid ambiguities with irregular time lines. Both of the time variables must be assigned decimal 24-hour clock values. For example, 3:15 pm is denoted as 15.25. The "GMT Offset" sign convention used requires time zones West of Greenwich to be positive ("Greenwich time is +N hours ahead of this time zone"). For example, GMT in the Eastern Time zone is +5 hours during Eastern Standard Time (EST) and +4 hours during Eastern Daylight Time (EDT).

4.2.2.7. Setting the location

The location of the scene's origin on the Earth's surface is specified by the "Latitude" and "Longitude" variables. These values are assumed to be in decimal degrees. Input values that are in degrees, minutes, seconds, etc. must be converted to decimal measurements. DIRSIG assumes locations West of the Prime Meridian as a positive Longitude value.

The DIRSIG urban scene is actually a detail reconstruction of an area of Rochester, NY. A ball park location for the actual scene is 43 degrees North latitude and 77 degrees West longitude.

The "Ground Altitude" field is used to adjust the origin of the GDB to the appropriate altitude. For example, the scene constructor may have built the scene using the lowest point in the scene as zero altitude, or the average area height as zero. In either case, the zero altitude in the GDB does not correspond to altitude above sea level. This field allows the user to correct for this offset or to easily relocate a scene at a different altitude (perhaps to simulate a high altitude scenario).

4.2.2.8. Finalizing the Scene parameters

At this point all of the parameters in the Scene Editor should be assigned values (see Figure 4-4). At this point you can close the window by clicking the OK button. If you click the Cancel button instead, the window will close and your current settings will be discarded.

4.2.4.1. Configuring a standard MODTRAN atmosphere

An optical description of the atmosphere must be created so that the atmospheric radiation propagation models MODTRAN and FASCODE can compute the optical components for various paths through the atmosphere. Rather than introduce a new type of database file, DIRSIG uses standard MODTRAN input files (which are normally called TAPE5 or tape5) as a template for the series of MODTRAN and FASCODE runs required to generate the DIRSIG Atmospheric Database (ADB) file. The format of the MODTRAN TAPE5 file is extremely complex and is described in the documentation provided by AFRL with the MODTRAN distribution. To make the management of the MODTRAN input file easier, the DIRSIG user interface also includes a simple MODTRAN TAPE5 editor tool. This tool can be started directly from the "Environment Editor" window by clicking the Edit button next to the "MODTRAN Tape5 Filename" edit box, or from the command line at any time using the command name tape5_edit.

In this example, we are going to create a simple MODTRAN template from scratch using the user interface. To begin, click the Edit button next to the "MODTRAN Tape5 Filename" edit box. The main editor window should appear shortly afterward (see Figure 4-7). It is assumed that the user has some previous knowledge of MODTRAN and understands the structure and layout of the input file. To summarize, the input file is broken down into a series of "cards" which each contain a series of variables that control specific aspects of the atmospheric modeling process. The DIRSIG Tape5 Editor presents these "cards" in the input file as a hierarchical list in the main editor window. By clicking on any card in the list, a window is opened that allows the user to edit the various variables associated with that selected card.

When spawned from the DIRSIG user interface, the Tape5 editing tool is started with the -dirsig_cards option. This option means that only cards which are not automatically filled out from other DIRSIG inputs are displayed.

For this example, we are going to construct a simple input file using one of the Standard Atmospheric Models and a few user defined properties. We will begin by setting the general atmospheric model parameters in Card #1. Open the Card #1 editor by clicking on the CARD 1 entry in the main window. To configure this card for this example, make sure that the following variables are set as described in Table 4-1. Any other variables in this card that are not described below have either the correct default values or will be set automatically by DIRSIG when the atmospheric database is created.

When all of the variables are set the editor should look like Figure 4-8. When the settings are correct, close the window by clicking the OK.

You should then proceed to set the parameters in Card #2 according to Table 4-2 in a similar fashion as you did with Card #1. The one difference between the edits made in Card #1 and Card #2 is that the VIS variable uses a widget known as a "read-write drop-down box". The user can edit the contents of the box by selecting the current text and replacing with the desired value (in this case 17.0). However, to "commit" the edit, you must press the return key after typing 17.0 into the box. When you are done setting the values, the editor window should look like Figure 4-9. Click the OK button to close this window.

At this point you have configured a very simple MODTRAN atmosphere. You need to save your current settings to a file to be used by DIRSIG. Select the Save option on the File menu in the Tape5 Editor and save your settings to the file tutorial1.tp5 in your simulation directory. Once your values have been successfully saved, you can exit from the Editor using the Quit option on the File menu.

The final step is to tell the DIRSIG interface that you wish to use your newly created MODTRAN file for your simulation. To do so, select your file using the Browse button next to the "MODTRAN Tape5 Filename" edit box.

4.2.4.2. Setting the name of the Atmospheric Database file

The "ADB Filename" variable indicates the name of the Atmospheric Database (ADB extension) file that will be generated using the configured atmospheric radiation propagation codes. The ADB file is essentially a large look-up table that has been specifically created for the current simulation parameters. This file is usually unique for almost every different simulation scenario since any change in the time of day, day of year, sensor position, meteorological conditions will change the radiative transfer properties of the atmosphere. The name of this file should be, therefore, appropriately named for the scenario.

Although you can use the Browse button, at this point you are specifying the name of a file that does not exist yet (we will create it shortly). Therefore, you can type the name tutorial1.adb directly into the text box.

4.2.4.3. Selecting a default Weather History file

A meteorological weather history for the scene is required for at least the previous 24-hours before the simulation time to insure that the thermal model can accurately predict the current temperatures of objects in the scene. The format of this file is described in Chapter 34.

For this example, we are going to use a weather history file from the default DIRSIG databases. Clicking on the Browse button next to the "Weather History Filename" edit box will open up a file selection dialog in directory $DIRSIG_HOME/lib/data/weather (the default directory). In this directory is a set of default Weather History files that were generated using a simple forecasting tool. The filenames are meant to reflect the geographical breakdown utilized by MODTRAN standard atmospheric models, but they do not necessarily imply the same atmospheric conditions. These files are useful for testing purposes but actual site measurements are preferred for important simulations. For this example, select the approximate "Mid-Latitude Summer" file which is named mls.wth.

4.2.4.4. Finalizing the Environment parameters

With the previously described values set in the Environment Editor window, your window should look like Figure 4-10. When your values match the desired values, close the Environment Editor window by clicking the OK button.

4.2.5.1. Setting the instrument parameters

The "Instrument" tab provides the user with access to the various variables that define the imaging system on the platform. This example describes the configuration of a simple 2D array or framing array.

To begin, you should use the Name variable to give your imaging instrument a name (examples include AVIRIS, HYDICE, etc.). This name does not have any effect on the simulation, however, this name can be very useful in identifying the scenario for this configuration. In this case, set the name to "Tutorial #1".

The default instrument Type is a FRAMING_ARRAY however, this selection box can be used to change the instrument type to any of the other supported DIRSIG sensor models. The FRAMING_ARRAY model is used to simulate any 2D array-type sensor (including a conventional film camera) and this is the desired sensor model for this tutorial.

The Focal Length defines the effective focal length of the forward optics in the instrument. In this example, we will be configuring an electronic sensor that has properties very similar to a 35 mm camera. Therefore, set the focal length to 50.0 which is a common focal length for off-the-shelf SLR cameras.

At the bottom of the window is the list of "bands" defined for this sensor. A "band" in the DIRSIG world is any geometrically or spectrally unique region of the focal plane. Therefore, a DIRSIG "band" may be one of the bands in the Landsat TM+ sensor, which is both geometrically and spectrally different from the other bands in this instrument. In contrast, a DIRSIG band may also be a whole spectrometer - a single location on the focal plane that is spectrally separated into a series of N continuous spectral channels. The complexities of setting up a spectrometer instrument will be explained later in this tutorial. By default, the list starts empty and the user will have to define the desired bands. We will start be creating a simple Panchromatic visible region band.

4.2.5.2. Creating a Pan Visible region band

To create the first band in this instrument, click the Add button in the Band List box. This will open up the Band Editor window which allows the user to define both the geometric and spectral properties of this band using the variables in each of the four (4) tabs. Regardless of the instrument type being simulated, the information on these four tabs remains essentially the same.

The first tab is labeled General. Presently, this tab contains the Name and Image Filename variables. The Name variable (like most of the DIRSIG name variables) does not affect the simulation in anyway, but rather it provides the user with an easy way to identify the properties assigned to this band. The name placed in this variable will be the name that appears in the Band List in the instrument editor. In this case, type in the name "Pan Visible".

The Image Filename variable is the name of the image file that will contain the results from the simulation. This image file could be a single band or a multi-, hyper- or ultra-spectral image cube (if this band is configured with a series of spectral channels). The format of the image file is not discussed here, but all DIRSIG image files are created with ASCII ENVI compatible header files which contain all the formatting information required to read the images into ENVI or any other image exploitation package. The image filename can be selected by either typing the name into the dialog, or by using the Browse button to select an existing filename or to create a new one. For this tutorial, set the image filename to pan_vis.img. When you are finished, your Band Editor window should look like Figure 4-12.

The next step is to define the geometric attributes of this band. In general, these attributes include the size of the array or pixels in the array and any offsets from the primary optical axis. For this example, we wish to model a simple 256 x 256 array. Type these dimensions into the respective variables inside the Layout box at the top of the Geometry window. The Layout box allows the user to define the number of pixel detectors, but the box labeled Size provides an interface for the user to define the physical size of the focal plane elements. You can select the default array size for the framing instrument, define the total array size, or define the individual detector sizes. With the "Default array size" currently selected, the "Array size" variables will reflect the default size. The "Pixel size" variables will start with a value of 0.0. If the user clicks the Apply button, the current values will be saved for this band and the "Pixel size" variables will be updated to reflect the current array size and the number of detectors (see Figure 4-13). Regardless of the method used to define the size of the array, clicking the Apply button will always update the disabled values.

The next step is to define the optical properties for this band. The Optical tab of the Band Editor window contains the variables that define the optical sensitivity of the detector(s). The Optical tab is comprised of two regions: the Detector Response box allows the user to select the type of response the detector(s) have, and the Detector Bandpass box allows the user to control aspects of the spectral bandpass. By default, a new band is configured to output spectral radiance (creating an image cube) over a user defined bandpass (see Figure 4-14).

For this simulation, we want to use a predefined sensor response function that has a panchromatic response in the Visible region. To select this option, click the Use response function button which will enable the Response Filename variables. Clicking on the Browse button will open a file dialog window in the DIRSIG sensor response directory within which you should be able to find a file called vis_broad.rsp. Once you have found this file and clicked the OK button on the file dialog window, you will notice that the information in the Detector Bandpass window has been updated with the bandpass defined by the response function (see Figure 4-15). The user can change various aspects of the bandpass by clicking the Specify Spectral Bandpass button. However, changing the extents of the bandpass when a spectral response function is defined does not change the extents of the response. On the other hand, the user may wish to increase the internal resolution that is used to compute integrated value by adjusting the Delta value.

The last tab in the Band Editor window is labeled PSF and contains variables to control the Point Spread Function of the focal plane detectors. By default, the DIRSIG model samples the scene using a Delta function since it is based on a ray tracing renderer. As a result, the output radiance images are comprised of "pure" pixels. There are two alternatives to this approach. The first is to create a spatially oversampled image which has the same total area coverage (or the same physical array size) but each pixel has been oversampled N x N. The resulting image size is then increased by a factor of N x N, but it can be manually degraded back to the desired size using external degradation and resampling tools. The other option is to supply the DIRSIG model with a spectrally dependent point spread function which it will apply during the rendering phase by performing the oversampling and degradation internally. Either of the two non-Delta sampling techniques increase the run-time by a factor of N x N.

For this simple example we will utilize the default delta sampling mode.

At this point the characteristics of the Pan Visible band are completed. By clicking the OK button at the bottom of the Band Editor window, the current values will be saved back to the current Instrument settings and the band list in the Instrument Editor window should be updated to contain one band named "Pan Visible".

4.2.5.3. Creating a Spectral Thermal region band

The thermal band for this simulation is very similar to the Pan Visible band with the obvious exception that the spectral sensitivity is different. Rather than guide you through each step in the configuration of this band, we only cover the optical settings in detail. However, set-up the rest of this band by adding a new band to the band list and use the values summarized below:

• Set the band Name to Thermal and the Image Filename to thermal.img.

• Set the array Layout to 256 x 256 and the array Size to the default.

• Use the default Delta sampling for the sensor PSF.

The differences between the "Pan Visible" and the "Thermal" band are isolated to the Optical tab. For this band, we want to generate a spectral radiance cube for the long-wave infrared (LWIR) region of the spectrum. To do this, the user should select the Output spectral radiance option from the Detector Response box. In the Detector Bandpass box, the user must specify the bandpass over which to generate the spectral radiances and the spectral units of the bandpass. For this example, you want to set the Spectral Units to Frequency [cm-1] and the Bandpass to 720.0 to 1320.0 [cm-1] on 2.0 [cm-1] deltas (see Figure 4-16).

Once all the settings are correct, save them back to your current instrument configuration by clicking the OK button at the bottom of the Band Editor box.

4.2.5.4. Finalizing the Platform settings

After you have finished configuring the two bands for the instrument, the Instrument Editor window should look like Figure 4-17. Click the Apply button to store the current instrument configuration (including the currently defined bands) to the current scenario configuration. If the user clicks the Cancel at this point all the Instrument settings will be discarded including any changes to the band list.

4.2.10.1. Creating the atmospheric database

The generation of the atmospheric database is handled by a DIRSIG support program called make_adb. This program can be called from the command line using the following syntax:

	prompt> make_adb tutorial.cfg
      

The atmospheric database can also be created from within the user interface by clicking the Create button next to the ADB Filename variable in the Environment editor window. The output from the make_adb utility is logged in the current directory to a file called make_adb.log. The atmospheric database may take minutes or several hours to generate depending on the type of scenario you have configured. During this time, the user interface will be stopped and may appear "hung". Upon completion, the Create button will pop back up and user interface will behave as before. It is always smart to review the results of the atmospheric database construction by checking the make_adb.log file for errors.

If you have configured everything correctly, then the make_adb program will run smoothly. In the event that you have not setup your simulation correctly and the make_adb "quits unexpectedly" there are several log files that will help you debug what exactly went wrong. Please consult The make_adb User Manual for more information.

For the simulation described in this tutorial, the "Thermal" band was configured to use 2 wavenumber resolution. This fine resolution will take some time for the MODTRAN model to simulate, and hence it will result in a long execution time for make_adb (perhaps a 1/2 hour). If you are in a hurry, you can always change the spectral resolution of this "Thermal" band from 2 wavenumbers to 5, 10 or 20 wavenumbers.

4.2.10.2. Running the simulation

At this point, your simulation is now ready to run. You run the DIRSIG model from the command line using the command dirsig. If you run the DIRSIG command without any arguments you will get a standard usage message from the program. This usage output includes the three lines shown below which indicate the version number and when it was compiled (the exact output will obviously be slightly different for your version). This information is useful to have if you need to upgrade your distribution or report a bug in the software.

	DIRSIG - Digital Imaging and Remote Sensing Image 
	Generation Model
	Release 3.5.1
	Build Date: Mar 22 2003 11:56:44
      

To run your simulation, start DIRSIG from the command line using the following syntax:

	prompt> dirsig tutorial1.cfg
      

This syntax will start the model using the scenario you have defined in your input file. The model will output a significant amount of information during the initialization phase and will eventually get to the rendering phase. The progress of the rendering can be monitored by the status information output by the model. An explanation of the messages output by DIRSIG are described throughout this manual.

If your simulation is expected to be especially long, the model can be run "in the background" and the output redirected to a log file using the following C-shell syntax (use the appropriate syntax for your shell if you are not using C-shell):

	prompt> dirsig tutorial.cfg >& tutorial1.log &
      

When the simulation is done a completion message will be sent to the terminal window (or log file).

4.2.11.1. Viewing a single band image

To begin, open the image generated for the visible band by selecting the pan_vis.img filename in your tutorial directory. Once the file has been selected, the name will show up in the Available Band List in the main window as Band 1:pan_vis.img. By double-clicking on the name, the image will be opened in an image window. Since the image data is floating-point radiance values, Freelook must scale and quantize the image down to your display. The user has some control over the scaling of the image data through the options on the Stretch menu. The image in Figure 4-22 was scaled for display using the "Equalization" stretch option.

Selecting the Cursor Location/Value from the Options will open another window that will tell you the radiance data value for the pixel under the cursor in the image window.

4.2.11.2. Viewing a multi-band image

The second detector focal plane that was simulated in this run captures a spectral image. The image data is stored in a single image file as 3-dimensional spatial-spatial-spectral data. Open the spectral thermal image by using the Open Image File... menu option to select the thermal.img file. The Available Band List in the main window will be updated with 301 band entries starting with Band 1 (1318.0000):thermal.img. The number in parentheses is the frequency [cm-1] of the band. The image in Figure 4-23 is band #45 (1232.0 [cm-1]).

Selecting the Z Profile option from the Options will open up a plot window that will plot the spectrum of the selected pixel as a function of wavelength or frequency depending on the original bandpass that was configured (see Figure 4-24). The user can select another pixel for plotting by clicking on a different location in the image window.

4.2.11.3. Viewing the truth images

The truth images that you selected for generation are stored as one large image file named truth.img. When you open this file, you will notice that the Available Band List in the main window lists the names of the different truth images. The image in Figure 4-25 shows the material ID of the first surface intersected along the path from the detector. The value in the Cursor Location/Value window is the material ID that can be resolved through the material file used for the simulation.