Keywords: plugins, pointcollectors

Summary

This demo provides a working example of the PointCollectors sensor plugin. This plugin allows the user to arbitrarily place a number of point radiometers in the scene and they can be configured to collect in a variety of modes. This type of sensor can be useful for measuring the illumination within a scene as either a function of location, time or both.

Related Materials

The following demos, manuals and tutorials can provide additional information about the topics at the focus of this demo:

Details

This demo leverages a specific illumination configuration combined with specially crafted scene geometry that results in specific locations in the scene to receive and reflect specific radiometric fluxes. Rather than use a conventional imaging array to verify the computed values at the limited number of predictable locations, this plugin allows the values at those locations to be directly measured.

Important Files

This section highlights key files important to the simulation.

The Scene

The scene used in this simulation is a copy of a scene referred to as the "SkyTubes" scene, which is used behind-the-scenes for DIRSIG testing. The scene is composed of 9 cylinder "tubes" of various depths. The bottoms of the tubes have a 100% Lambertian reflector and the sides of the tubes are 100% absorbers (0% Lambertian reflector). The depth of the tubes were calculated to yield specific reflected radiance steps based on the uniform sky illumination conditions. For example, the 1st tube is the deepest and "sees" the least amount of sky so the least amount of illumination reaches the bottom. In contrast, the 9th tube is the the shallowest and "sees" the most sky and the most illumination reaches the bottom.

slant view
Figure 1. A slant-view rendering of the "SkyTubes" scene used in this demo.

The PointCollectors Configuration

The PointCollectors plugin is configured via a a DIRSIG5 JSIM file. The details of the configuration options are discussed in detail in the PointCollectors plugin manual. There are three simulations, and in all three setups there are point collectors positioned just above the bottom of each tube. The three simulations exercise the three different types of collectors:

  1. Spherical,

  2. Hemispherical, and

  3. Directional

The spherical collectors are collecting the energy from the bottom and sides of the tubes plus some portion of the sky. The hemispherical collectors are pointed up, effectively ignoring the reflected energy from the bottom of the tubes but still collecting comse amount of sky radiance. The directional collectors are pointing down at the bottoms and only collecting the reflected energy.

Because of the design of the scene, we expect the radiance for all three simulations to be the same. Remeber that although the three collectors are collecting over dramatically different angles, they are outputting in radiance, which is normalized by solid angle. For example, even though the spherical collector is gathering energy from the bottom of the tube and the hemispherical collector is not, they are both weighted by their respective solid angles. Hence, the spherical collector might gather 2x as many photons, but it will get normalized by a 2x larger solid angle.

Below is the contents of the points_spherical.jsim file. The primary difference in the three point collector JSIM files is the type of collector and the direction of the collector.

Contents of the points_spherical.jsim file.
[{
  "scene_list" : [
    { "inputs" : "./demo.scene" }
  ],
  "plugin_list" : [
    {
      "name" : "BasicAtmosphere",
      "inputs" : {
        "atmosphere_filename" : "uniform.atm"
      }
    },
    {
      "name" : "PointCollectors",
      "inputs" : {
        "input" : {
          "sample_count" : 100000,
          "bandpass" : {
            "minimum" :  0.50,
            "maximum" :  0.50
          },
          "spectrally_integrated" : false,
          "cosine_weighted" : true,
          "date_time" : {
            "start"      : "2009-09-01T12:10:00.0000-05:00",
            "step_time"  : 0.1,
            "step_count" : 1
          },
          "collectors" : [
            [ "Tube #1", "spherical", -2.0, -2.0, -2.939, 0.0, 0.0, 1.0 ],
            [ "Tube #2", "spherical",  0.0, -2.0, -1.959, 0.0, 0.0, 1.0 ],
            [ "Tube #3", "spherical",  2.0, -2.0, -1.496, 0.0, 0.0, 1.0 ],
            [ "Tube #4", "spherical", -2.0, -0.0, -1.199, 0.0, 0.0, 1.0 ],
            [ "Tube #5", "spherical",  0.0, -0.0, -0.979, 0.0, 0.0, 1.0 ],
            [ "Tube #6", "spherical",  2.0, -0.0, -0.799, 0.0, 0.0, 1.0 ],
            [ "Tube #7", "spherical", -2.0,  2.0, -0.640, 0.0, 0.0, 1.0 ],
            [ "Tube #8", "spherical",  0.0,  2.0, -0.489, 0.0, 0.0, 1.0 ],
            [ "Tube #9", "spherical",  2.0,  2.0, -0.325, 0.0, 0.0, 1.0 ]
          ]
        },
        "output" : {
          "units" : "radiance",
          "filename" : "points_spherical.txt"
        }
      }
    }
  ]
}]

Simulations and Results

This section includes any step-by-step instructions for running and visualizing the simulations included in this demo.

The Framing Array Simulation

The visualize the scene, a traditional framing array simulation has been provided.

To run the simulation using DIRSIG4:

$ dirsig4 framing.sim

or using DIRSIG5:

$ dirsig5 framing.sim

The simulation produces a broad-band, panchromatic radiance image and truth. The image is captured from overhead looking down into the tubes. The Z intersection truth (below) illustrates the relative depth of the 9 tubes.

z truth
Figure 2. Linearly-scaled DIRSIG "Z intersection" truth is an easy way to visualize the depths of the tubes.

The reflected radiance in the tubes (below) is from the bottom and arises from the fraction of the hemisphere above the bottom that is sky. The deeper tubes have less of the hemisphere being sky. Within each tube, the gradient in reflected radiance across the bottom arises from the decreased amount of sky closer to the walls of each tube.

demo.img
Figure 3. Linearly-scaled DIRSIG radiance output shows the correlation with tube depth.

The PointCollectors Simulations

To run the point collectors simulation, you must use DIRSIG5. There are three different point collection

$ dirsig5 points_spherical.jsim
$ dirsig5 points_hemispherical.jsim
$ dirsig5 points_directional.jsim

The primary output of this simulation is a text file, which was configured in the output section of the plugin configuration. Each simulation produces a uniquely named output file.

Contents of the points_spherical.txt output file.
# DIRSIG5 'PointCollectors' plugin output file
# Generated on Thu Feb 3 17:02:55 2022
#
# Samples/collector: 100000
# Bandpass: 0.5 - 0.5 @ 0.02 (1 points)
# Time: 1 samples @ 0.1 second intervals
#
# Collectors:
#    Tube #1: [-2,-2,-2.93], [0,0,-1]
#    Tube #2: [0,-2,-1.95], [0,0,-1]
#    Tube #3: [2,-2,-1.49], [0,0,-1]
#    Tube #4: [-2,-0,-1.19], [0,0,-1]
#    Tube #5: [0,-0,-0.97], [0,0,-1]
#    Tube #6: [2,-0,-0.79], [0,0,-1]
#    Tube #7: [-2,2,-0.64], [0,0,-1]
#    Tube #8: [0,2,-0.48], [0,0,-1]
#    Tube #9: [2,2,-0.32], [0,0,-1]
#
# Output units: Radiance [W/cm^2/sr]
#
0.000e+00,[1.004e-01],[1.990e-01],[3.026e-01],[4.009e-01],[5.016e-01],[5.997e-01],[7.001e-01],[8.021e-01],[9.013e-01],

Since a single time was requested (the step_time and step_count were not provided), the single, non-comment line at the end of the file is the output of the simulation. The first token is the time. A multiple time step simulation would have multiple lines, with each time token indicating the time. The remaining 9 tokens are the outputs for each collector (9 tubes and 1 collectors per tube). Since the spectral radiance was requested, the tokens appear in [] but since a single wavelength was requested the list contains a single value.

The table below summarizes the output of the three different collector scenarios with the expected values (the depths of the tubes were externally calculated as part of the design of this scene to produce the uniform interval in expected radiances):

Table 1. Expected and Computed Radiances
Tube # Expected Directional Hemispherical Spherical

1

0.1000

0.1004

0.0996

0.1002

2

0.2000

0.1990

0.1985

0.2015

3

0.3000

0.3026

0.2991

0.2941

4

0.4000

0.4009

0.4013

0.3996

5

0.5000

0.5016

0.4995

0.4996

6

0.6000

0.5977

0.6009

0.6017

7

0.7000

0.7001

0.7018

0.7001

8

0.8000

0.8021

0.8008

0.8004

9

0.9000

0.9013

0.9015

0.9004

The deviation of the predicted (computed) values vs. the analytically derived expected values arises from the random sampling of the sphere or hemisphere around the point. Increasing the sample_count used in the plugin will drive down the variation by using more samples in the Monte-Carlo integral used inside the model.

General comments:

  • Because the bottoms of the tubes are 100% reflectors, the total radiance for the hemispherical and spherical collectors is the same.

  • Changing the collector output to "irradiance" would show that the total flux onto the spherical collectors is 2x more than the hemispherical collectors.

  • Since a directional collector has no solid associated with it, you can only request "radiance" output.