Summary

The SphericalCollector plugin was created to allow users to easily collect either the inbound spectral radiance onto a point or the outbound spectral radiance from a point. The user can choose to measure either over a hemisphere or an entire sphere at the point. The user also has a choice at how the sampling is projected into the output spectral radiance data cube.

Input

The input configuration file is a JSON formatted description. An example is shown below:

{
    "input" : {
        "bandpass" : {
            "minimum" : 0.45,
            "maximum" : 0.7,
            "delta"   : 0.05
        },
        "date_time" : {
            "start"      : "2009-09-01T12:10:00.0000-05:00",
            "step_time"  : 0.1,
            "step_count" : 1
        },
        "coverage" : "sphere",
        "location" : [0, 0, 5],
        "direction" : [0, 0, 1]
        "mode" : "inbound",
        "projection" : "orthogonal",
        "xsamples" : 180,
        "ysamples" : 180,
    },
    "output" : {
        "filename" : "inbound_ortho.img"
    }
}

Input Parameters

Spectral Bandpass

The sensors all have the same spectral bandpass. If you have different scenarios with different bandpasses then model them as a separate collection.

        "bandpass" : {
            "minimum" : 0.45,
            "maximum" : 0.7,
            "delta"   : 0.05
        }

Date/Time

The date/time for the collection is described in the date_time section. The start variable is an ISO8601 date/time. The number of temporal measurements is defined by the step_count variable and the time between measurements is defined by the step_time variable.

        "date_time" : {
            "start"      : "2009-09-01T12:10:00.0000-05:00",
            "step_time"  : 0.001,
            "step_count" : 10
        }

Coverage

The coverage variable defines if the collection will sample either a hemisphere ("coverage" : "hemisphere") or sphere ("coverage" : "sphere").

Location and (optional) Direction

The location defines where in the scene the collection point is located (in Scene ENU units). The optional direction defines the direction to the top of the hemisphere for a hemispherical coverage scenario.

Mode and (optional) Radius

The mode describes if the collection is measuring the "inbound" radiance arriving onto the defined location ("mode" : "inbound") or the "outbound" radiance leaving from the defined location ("mode" : "outbound"). In the case of an "outbound" scenario, the user must also provide the radius defining the distance from the defined location that the radiances are collected.

Projection and Samples

The projection defines how hemisphere or sphere is sampled and represented in the output data cube file. The orthogonal projection directly couples the output image X axis to the azimuth sampling dimension and the Y axis to the zenith sampling dimension ("projection" : "orthogonal"). The polar projection maps the zenith and azimuth into the X/Y axes of the output image to produce circular or fisheye style visualizations.

The xsamples and ysamples define the number of samples in the zenith and azimuth dimensions. In general, these two parameters define the dimensions of the output image cube. If a spherical projection is used, the image will be 2x larger in the Y dimension.

The Output Parameters

Filename

The name of the output ENVI image file. Note that this plugin does honor the --output_folder and --output_prefix command line options.

Output

The output generated by this plugin is a spectral data cube with two spatial (angular) dimensions and one spectral dimension. The spatial (X/Y) dimensions are driven by the input xsamples, ysamples and projection variables. The orthographic projection option will generate an image where the xsamples and ysamples correspond to the azimuth and zenith dimensions, respectively. The xsamples will be evenly distributed across 0 - 360 degrees in azimuth. The ysamples will be even distributed across 0 - 90 degrees in zenith. If a "coverage" is "spherical", the ysamples will be distributed across the upper and lower hemisphere, doubling the number of total samples in this dimension. The image below shows the output of an orthographic projection collection in a jungle scene. The apparent distortion at the top of the image reflects the solid angle of the samples getting smaller but being represented in the output image as a single pixel.

images/spherical_collector/inbound_ortho.png
Figure 1. Inbound hemispherical output using the orthographic projection.
Tip The orthographic projection is most useful when using the output as the input to another model because the zenith and azimuth indexing is straightforward.

The polar projection option produces traditional "fisheye" type data, which can be more intuitive for visualization purposes. In this case the xsamples and ysamples are used to define a square grid into which the zenith and azimuth samples are projected. As a result, the output image contains a circular border around the projected samples (these border pixels have values of zero). The outer ring of pixels correspond to a zenith (declination) angle of 90 degrees and then progressing to smaller and smaller zenith (declination) angles toward the middle of the image.

images/spherical_collector/inbound_polar.png
Figure 2. Inbound hemispherical output using the polar projection.
Tip The polar projection is most useful for visualizations of the environment around an object.

The units of the image data are Watts/(cm^2 sr micron).

Usage

To use the SphericalCollector plugin in DIRSIG5, the user must use the newer JSON formatted simulation input file (referred to a JSIM file with a .jsim file extension). At this time, these files are hand-crafted (no graphical editor is available).

The user has two choices for how to construct the input. The first option is to embed the JSON description for the collector in the JSIM file, which results in a self-contained simulation configuration. An example is shown below:

[{
    "scene_list" : [
        { "inputs" : "./demo.scene" }
    ],
    "plugin_list" : [
        {
            "name" : "BasicAtmosphere",
            "inputs" : {
                "atmosphere_filename" : "./demo.atm"
            }
        },
        {
            "name" : "SphericalCollector",
            "inputs" : {
                "input" : {
                    "bandpass" : {
                        "minimum" : 0.45,
                        "maximum" : 0.7,
                        "delta"   : 0.05
                    },
                    "date_time" : {
                        "start"      : "2009-09-01T12:10:00.0000-05:00",
                        "step_time"  : 0.1,
                        "step_count" : 1
                    },
                    "coverage" : "sphere",
                    "location" : [0, 0, 5],
                    "direction" : [0, 0, 1]
                    "mode" : "inbound",
                    "projection" : "orthogonal",
                    "xsamples" : 180,
                    "ysamples" : 180,
                },
                "output" : {
                    "filename" : "inbound_ortho.img"
                }
            }
        }
    ]
}]

The second option is to place the JSON collector description in a separate file and supply the name of that file in the JSIM file:

[{
    "scene_list" : [
        { "inputs" : "./demo.scene" }
    ],
    "plugin_list" : [
        {
            "name" : "BasicAtmosphere",
            "inputs" : {
                "atmosphere_filename" : "./demo.atm"
            }
        },
        {
            "name" : "SphericalCollector",
            "inputs" : {
                "input_filename" : "./demo.json"
            }
        }
    ]
}]

The SphericalCollector1 contains a working example of this plugin.