This DIRSIG5 sensor plugin allows the user to configure one or more "point" measurement sensors within a scene.

Summary

The point measurement devices defined by this plugin collect incident energy from a given direction, integrated over a hemisphere or integrated over a full sphere. The latter two options support either cosine or uniform weighting. This plugin is useful for creating a network of point measurements across a scene to capture gradients in illumination or monitor the progress of some sort of dynamic scene element.

Related Materials

The following demos, manuals and tutorials can provide additional information related to this plugin:

Input Variables

The input configuration for this plugin takes the form of a JSON formatted document. And example is show below:

{
  "input" : {
    "sample_count" : 10000,
    "cosine_weighted" : true,
    "spectrally_integrated" : true,
    "bandpass" : {
      "minimum" :  0.40,
      "maximum" :  2.50,
      "delta"   :  0.02
    },
    "date_time" : {
      "start"      : "2009-09-01T12:10:00.0000-05:00",
      "step_time"  : 0.1,
      "step_count" : 10
    },
    "collectors" : [
      [ "Sensor #1", "directional",   -2.0, -2.0, -2.939, 0.0, 0.0, 1.0 ],
      [ "Sensor #2", "hemispherical", -2.0, -2.0, -2.939, 0.0, 0.0, 1.0 ],
      [ "Sensor #3", "spherical",     -2.0, -2.0, -2.939, 0.0, 0.0, 1.0 ]
    ]
  },
  "output" : {
    "units" : "radiance",
    "filename" : "collectors_out.txt"
  }
}

Sample Count

The incident flux is determined by the DIRSIG5 radiometry core using a number of samples sent into the direction, distributed over the hemisphere or sphere. The number of samples can be specified using the sample_count variable. The default number of samples is 1000.

Note This value defines the number of samples for the directional or hemispherical collection geometries. This value is automatically doubled for spherical sensors.
Important The sample_count specifies the number of samples per collector and is not impacted by the command-line convergence option.

Cosine Weighting

The incident flux may be calculated using cosine or uniform weighting. As the terminology may imply, cosine weighting is appropriate to calculate the irradiance (or normalized radiance) on a flat detector, where it is necessary to account for the projected area of the detector itself. On the other hand, uniform weighting is appropriate to uniformly integrate over the hemisphere or sphere without accounting for projected area.

    "cosine_weighted" : true,

If left unspecified, cosine_weighted defaults to true.

Spectral Bandpass

The sensors all have the same spectral bandpass. If you have different sensors with different bandpasses then model them as a separate collection. The output may be spectrally integrated over the bandpass (by summing and multiplying by the bandpass delta), or not.

Example spectral sampling setup.
    "bandpass" : {
      "minimum" :  0.40,
      "maximum" :  2.50,
      "delta"   :  0.02
    },
    "spectrally_integrated": true

If the spectrally_integrated variable is not provided, it defaults to true.

Date/Time

The date/time for the collection of sensors 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.

Example date/time setup for running all collectors 10 times, each 0.1 seconds apart.
    "date_time" : {
      "start"      : "2009-09-01T12:10:00.0000-05:00",
      "step_count" : 10,
      "step_time"  : 0.1
    }

If the step_count variable is not provided, the number of temporal samples defaults to 1.

Example date/time setup for running all the collectors once.
    "date_time" : {
      "start"      : "2009-09-01T12:10:00.0000-05:00"
    }

Collector List

The collectors array describes each collector in the simulation. Each element of the array defines a collector and is an array itself. The elements of an individual collector array are:

  1. The name for the collector.

  2. The collector type (it can be either directional, hemispherical or spherical).

  3. The location of the collector in the Scene ENU coordinate system as an XYZ triplet.

  4. The pointing direction of the collector as an XYZ triplet. The XYZ direction components will be converted into a normalized vector. The direction is only used for the hemisphere collector to indicate the direction of hemisphere the collector is looking into.

  5. And optional field that varies by collector type:

    1. For the directional collector type, this is the (optional) solid angle sampled by the collector.

    2. For the hemispherical and spherical collector types, this is the (optional) area of the collector in m2. This area is only required if the output units are to be integrated over the detector area (for example, the output units are "power").

Example collector set featuring all three collector types.
      "collectors" : [
        [ "Sensor #1", "directional",   0.0, 0.0, 2.5, 0.0, 0.0, 1.0 ],
        [ "Sensor #2", "hemispherical", 0.0, 0.0, 2.5, 0.0, 0.0, 1.0 ],
        [ "Sensor #3", "spherical",     0.0, 0.0, 2.5, 0.0, 0.0, 1.0 ]
      ]

Output Related Variables

Units

The units variable defines the units of the output radiometric quantity for the collectors. It can be assigned on of the following values:

  • radiance (flux per area, per solid angle)

  • irradiance (flux per area)

  • power (flux)

Table 1. Table of collector types and respective, available output units.
Collector Type Output Units Options Cosine Weighting Options

Directional

Radiance only

N/A

Hemispherical

Radiance, irradiance, power

True (default) or False

Spherical

Radiance, irradiance, power

True (default) or False

Usage

To use the PointCollectors plugin in DIRSIG5, the user must use the newer JSON formatted simulation input file (referred to a JSIM file with a .jsim file extension).

$ dirsig5 point_collectors.jsim

The JSON configuration for this plugin can be supplied via the JSIM file using one of two methods.

External File Configuration

The JSON configuration can be stored in an external file and then referenced via the input_filename variable inside the inputs of the plugin. This method is useful if the same same configuration is going to be used with different scenes, different atmosphere plugins, etc. because the configuration will not be duplicated across multiple JSIM files.

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

Internal JSON Configuration

The JSON configuration can also be included directly in the inputs section of the plugin in the JSIM file. This method is useful for unique simulations where sharing the configuration across multiple simulations is not required. It also simplifies the setup by eliminating and external file that needs to be accounted for when the simulation is shared.

[{
  "scene_list" : [
    { "inputs" : "./demo.scene" }
  ],
  "plugin_list" : [
    {
      "name" : "BasicAtmosphere",
      "inputs" : {
        "atmosphere_filename" : "./uniform.atm"
      }
    },
    {
      "name" : "PointCollectors",
      "inputs" : {
        "input" : {
          "sample_count" : 10000,
          "cosine_weighted" : true,
          "spectrally_integrated" : true,
          "bandpass" : {
            "minimum" :  0.40,
            "maximum" :  2.50,
            "delta"   :  0.02
          },
          "date_time" : {
            "start"      : "2009-09-01T12:10:00.0000-05:00",
            "step_time"  : 0.1,
            "step_count" : 10
          },
          "collectors" : [
            [ "Sensor #1", "directional",   0.0, 0.0, 2.5, 0.0, 0.0, 1.0 ],
            [ "Sensor #2", "hemispherical", 0.0, 0.0, 2.5, 0.0, 0.0, 1.0 ],
            [ "Sensor #3", "spherical",     0.0, 0.0, 2.5, 0.0, 0.0, 1.0 ]
          ]
        },
        "output" : {
          "units" : "radiance",
          "filename" : "collectors_out.txt"
        }
      }
    }
  ]
}]

Output Data File

The output file is an ASCII/Text file that includes a short header (lines starting with #) that summarize key inputs. This is followed by a series of lines, where each line contains the output of the collector set for a given time.

# DIRSIG5 'PointCollectors' plugin output file
# Generated on Wed Jan 9 14:20:43 2019
#
# Samples/collector: 10000
# Bandpass: 0.4 - 2.5 @ 0.02 (106 points)
# Time: 10 samples @ 0.1 second intervals
#
# Collectors:
#    Sensor #1: [0,0,2.5], [0,0,1]
#    Sensor #2: [0,0,2.5], [0,0,1]
#    Sensor #3: [0,0,2.5], [0,0,1]
#
# Output units: Radiance [W/(cm^2 sr um)]
#
0.000,[0.219,0.221,...,0.438],[0.219,0.220,...,0.438],[0.220,0.223,...,0.435]
0.100,[0.217,0.222,...,0.438],[0.216,0.221,...,0.439],[0.217,0.221,...,0.436]
...
[data deleted for documentation purposes]
...
0.900,[0.219,0.221,...,0.438],[0.219,0.221,...,0.438],[0.219,0.221,...,0.436]

The first token in each line is the relative time for the output in seconds. The remainder of each line is the radiometric output of each sensor.

If spectrally_integrated is true, the remaining comma-separated tokens contain the spectrally-integrated measurements for each point collector (in this example there are 3 collectors).

0.000,[0.255],[0.256],[0.255]
0.100,[0.265],[0.265],[0.266]
...
[data deleted for documentation purposes]
...
0.900,[0.265],[0.265],[0.266]

If spectrally_integrated is false, each measurement token will be a a series of spectral values (rather than the single spectrally integrated value). Each array is formatted as a comma-separated list of numbers inside square-brackets. For example, [0.1,0.2,0.3]. Every array has the same number of entries, which is identical to the number of wavelength samples. The spectrally integrated measurements may be obtained by summing the values in each array and multiplying by the bandpass delta.

0.000,[0.219,0.221,...,0.438],[0.219,0.220,...,0.438],[0.220,0.223,...,0.435]
0.100,[0.217,0.222,...,0.438],[0.216,0.221,...,0.439],[0.217,0.221,...,0.436]
...
[data deleted for documentation purposes]
...
0.900,[0.219,0.221,...,0.438],[0.219,0.221,...,0.438],[0.219,0.221,...,0.436]
Note Since the number of wavelengths in this example is large, The "…​" in the output above represents a series of wavelengths that were removed for documentation purposes.