19.3. How-To

19.3.1. Collector Configuration File

Interactive Mode takes an XML Collector Configuration File and a DIRSIG cfg file as input. An example of the collector XML follows:

<?xml version="1.0" standalone="no"?>
<!DOCTYPE interactive SYSTEM "http://www.dirsig.org/dtds/interactive.dtd">
<interactive format="plain" pausepolicy="never">

  <simulationcollectors>
    <simscenefilename/>
    <simbandpasses/>
    <simscenebbox/>
  </simulationcollectors>

  <solutioncollectors>
    <pathviewray/>
    <pathsolidangle/>
    <pathsurfacecount/>
  </solutioncollectors>

  <surfacecollectors>
    <surfacematid/>
    <surfacetemperature/>
    <surfaceentrypoint/>
    <surfaceexitpoint/>
    <surfacepathlength/>
    <surfacenormal/>
    <surfacetransmission/>
    <surfaceradiance/>
  </surfacecollectors>

</interactive>
  

The interactive section has four attributes which may be set:

1. The "format" attribute may be set to "plain", "xml", or "binary". It controls the output formatting of the Interactive Session.

2. The "pausepolicy" is an experimental feature which may be set to "never", "percollector", or "persurface". Rather than immediately output all the results, the interactive session will halt at the specified points, waiting for the user to type an abitrary character (or characters) followed by a new line.

3. The "startupoutputredirect" may specify a filename to which all the DIRSIG startup text gets redirected. This does not include the output portion of the interactive session. If this attribute is not specified, then all output will go to either stdout or stderr, as in a normal DIRSIG simulation. Note that input must still be provided via stdin.

4. The "interactiveoutputredirect" may specify a filename to which all the DIRSIG interactive results are redirected. If this attribute is not specified, then all output will go to stdout. Note that input must still be provided via stdin.

In the collector configuration file, the "<simulationcollectors>" corresponds to the Simulation Level Queries. Likewise, "<solutioncollectors>" go with Solutions and "<surfacecollectors>" are applied to each surface in a given solution. A full list of available collectors are given in: Table 19-1, Table 19-2, and Table 19-3. The Document Type Definition (DTD) associated with this input file also lists the available options and provides a means for syntax validation using external tools.

Note that Polarized Mueller Matrices are stored in Row Major Order (M₀₁,M₀₂, M₀₃,M₀₄, M₁₀, ... ,M₄₄). In the current release of Interactive Mode, the location attribute associated with each Mueller Matrix or Stokes Vector in a Spectral Vector gives the spectral location in Microns.

Note also that the Surfaces are output in ascending order sorted by Entry Distance.

19.3.2. Bandpass Configuration File

The spectral coverage computed by Interactive Mode is determined by a Bandpass Configuration File. DIRSIG defines spectral regions using a minimum, maximum, and a uniform delta. These spectral regions are termed a "bandpass". Multiple bandpasses can be assembled in to a "bandpass list". A bandpass with a minimum wavelength of 0.3 microns, a maximum wavelength of 0.5 microns, and a sampling delta of 0.1 microns tells DIRSIG to simulate for the wavelengths 0.3, 0.4, and 0.5 microns. This means that internally, all the radiances, transmissions, irradiances, etc are computed for these three wavelengths. An example of the bandpass XML follows:

<bandpasslist>
  <bandpass spectralunits="microns">
    <minimum>0.3</minimum>
    <maximum>0.5</maximum>
    <delta>0.1</delta>
  </bandpass>  
</bandpasslist>
  

Spectral units of "microns", "nanometers", and "wavenumbers" are currently supported. An example of a bandpass XML specifying two bandpasses follows. This example will cause DIRSIG to simulate at 0.3, 0.31, 0.32, 0.33, 0.4, and 0.5 microns.

<bandpasslist>
  <bandpass spectralunits="microns">
    <minimum>0.3</minimum>
    <maximum>0.5</maximum>
    <delta>0.1</delta>
  </bandpass>  

  <bandpass spectralunits="nanometers">
    <minimum>310</minimum>
    <maximum>330</maximum>
    <delta>10</delta>
  </bandpass>  
</bandpasslist>
  

19.3.3. Interactive Mode Input

With a collector configuration file in place, DIRSIG4 can be placed in Interactive Mode as follows:

    dirsig4 -interactive ./collector.xml ./bandpass.xml nadir.cfg
  

In this case, collector.xml is the name of a Collector Configuration File. The bandpass.xml is the Bandpass Configuration File. The nadir.cfg is a traditional DIRSIG3 cfg file corresponding to a simulation. Parts of this CFG file, such as the atmosphere and the simulation base time, are still used by Interactive Mode. Future releases will allow all this information to be supplied via the command line, doing away entirely with the CFG file. When DIRSIG4 has finished loading the scene, the following prompt will appear:

Interactive Mode Ready
<!-- [time] [omega] [orX] [orY] [orZ] [dirX] [dirY] [dirZ] -->
  

The XML style comment indicates the input which Interactive Mode expects, summarized in Table 19-4. This informational prompt does not appear when operating in "binary" output mode.

Note that the ray direction vector does not need to be normalized. However, it may never be the zero vector. Also, the solid angle must obviously be greater than zero.

19.3.4. Interactive Mode Output

Interactive Mode is capable of outputting plain text, XML, or binary. The is controlled by setting the "format" attribute in the Collector Configuration File.

Interactive Mode Ready

# Simulation Parameters #
Scene Bounding Box: 
    minimum: (-521.713,-543.484,-953.792)
    maximum: (1654.42,1632.64,1222.34)

# Solution Results #
View Ray: 
    origin: (800,800,1000)
    direction: (0,0,-1)
Solid Angle: 1
Surface Count: 1
Path Radiance: 
    [0.47 microns] 0.00279327
    [0.48 microns] 0.00281209
    [0.49 microns] 0.00275102
    [0.5 microns] 0.0028744

# Surface 1 #
Entry Distance: 859.254
Entry Angle: 0.485803
Material ID: 25

Interactive Mode Finished
    

<?xml version="1.0" standalone="no"?>
<!DOCTYPE interactivesession 
  SYSTEM "http://www.dirsig.org/dtds/interactive_out.dtd">
<interactivesession>
  <simulationinfo>
    <simscenebbox>
	<box>
          <lowerextent>
            <point><x>-521.713</x><y>-543.484</y><z>-953.792</z></point>
          </lowerextent>
          <upperextent>
            <point><x>1654.42</x><y>1632.64</y><z>1222.34</z></point>
          </upperextent>
        </box>
    </simscenebbox>
  </simulationinfo>

  <solutioninfo>
    <pathviewray>
      <ray>
        <origin><point><x>800</x><y>800</y><z>1000</z></point></origin>
        <direction><vector><x>0</x><y>0</y><z>-1</z></vector></direction>
      </ray>
    </pathviewray>
    <pathsolidangle>1</pathsolidangle>
    <pathsurfacecount>1</pathsurfacecount>
    <pathradiance>
      <spectralvector>
        <stokesvector location="0.47"> 0.00279327 </stokesvector>
        <stokesvector location="0.48"> 0.00281209 </stokesvector>
        <stokesvector location="0.49"> 0.00275102 </stokesvector>
        <stokesvector location="0.5"> 0.0028744 </stokesvector>
      </spectralvector>
    </pathradiance>

    <surfaceinfo>
      <surfaceentrydistance>859.254</surfaceentrydistance>
      <surfaceentryangle>0.485803</surfaceentryangle>
      <surfacematid>25</surfacematid>
    </surfaceinfo>
  </solutioninfo>
</interactivesession>