Truth Collectors

This document outlines the various truth collectors available in the DIRSIG5 model.

Consult the DIRSIG4 Truth Collectors manual for details about truth collection in DIRSIG4.

The truth collectors are objects that extract information about important image formation parameters on a per-pixel basis. Because a pixel may contain multiple contributions, many of the truth collectors provide statistical summaries. For example, the material index truth reports the most common material within a pixel whereas the temperature truth reports the average temperature within a pixel.

Because the DIRSIG model utilizes ray-tracing, the granularity of the extracted values is subject to sub-pixel sampling. For example, if the user is employing a single sample per pixel, then the collector cannot produce fractional values. The more samples that used per pixel, the better the sampling of the sub-pixel geometry will be and, hence, the more accurate both the radiometry and the truth will be.

In DIRSIG5, truth is collected by the sensor plugins. Each sensor plugin has it’s own interface for configuring what truth is collected and how that collected data is presented. However, they all use the same request mechanism and most present the data as a raster data set using the spectral dimension as a feature vector, with each band containing data for a specific collector.

In DIRSIG5, the truth collection sub-system was designed to be configurable at a more granular scale. This means that in addition to the DIRSIG4-era collection sets, the individual truth elements that composed those sets can be selected. These individual collectors can be specified using their unique names in the sensor plugins that support the truth collection.

Most users utilize the BasicPlatform plugin, and this section describes the details of configuring truth for that plugin.

The table below summarizes the individual collector names, the corresponding collector label (this longer label is what is used in truth output products, e.g., the band name in a rather truth data file), the name of any collector sets they are included in and finally a short description. In DIRSIG5 either an individual name or a set name can be supplied and the names are case-insensitive.

Table 1. Individual Truth Collectors and Sets
Collector Name	Collector Label	Set Name	Description
`materialindex`	Dominant Material Index	`material`	The index of the most abundant material
`materialvariantindex`	Dominant Optical Property Index	`material`	The index of the variant within the most abundant material
`scenex`	Scene ENU X Coordinate [m]	`intersection`	The average X coordinate (Scene ENU)
`sceney`	Scene ENU Y Coordinate [m]	`intersection`	The average Y coordinate (Scene ENU)
`scenez`	Scene ENU Z Coordinate [m]	`intersection`	The average Z coordinate (Scene ENU)
`distance`	Distance [m]	`intersection`	The average distance from the sensor
`viewcosine`	View Angle Cosine	`intersection`	The average cosine of the surface normal vs. view vector
`textureu`	Texture U Coordinate	`intersection` & `texturecoords`	The average U texture coordinate
`texturev`	Texture V Coordinate	`intersection` & `texturecoords`	The average V texture coordinate
`normx`	Surface Normal X Component	`normal`	The X component of the average surface normal (Scene ENU)
`normy`	Surface Normal Y Component	`normal`	The Y component of the average surface normal (Scene ENU)
`normz`	Surface Normal Z Component	`normal`	The Y component of the average surface normal (Scene ENU)
`baryu`	Barycentric U Coordinate	`barycentriccoords`	The U component of the average barycentric coordinate
`baryv`	Barycentric V Coordinate	`barycentriccoords`	The V component of the average barycentric coordinate
`baryw`	Barycentric W Coordinate	`barycentriccoords`	The W component of the average barycentric coordinate
`latitude`	Geodetic Latitude [+N deg]	`geolocation`	The average latitude of the pixel (degrees, +N)
`longitude`	Geodetic Longitude [+E deg]	`geolocation`	The average longitude of the pixel (degrees, +E)
`altitude`	WGS84 Altitude [m]	`geolocation`	The average altitude of the pixel (meters WGS84)
`ecefx`	ECEF X Coordinate [m]	`geolocation`	The average X coordinate (ECEF)
`ecefy`	ECEF Y Coordinate [m]	`geolocation`	The average Y coordinate (ECEF)
`ecefz`	ECEF Z Coordinate [m]	`geolocation`	The average Z coordinate (ECEF)
`sceneindex`	Scene Index	`geoids`	The index of the most abundant scene
`geometryindex`	Geometry Index	`geoids`	The index of the most abundant base geometry
`instanceindex`	Instance Index	`geoids`	The index of the most abundant instance
`primitiveindex`	Primitive Index	`geoids`	The index of the most abundant element within the base geometry
`pathzenith`	Path Zenith [degrees]	`pathangles` & `atmosphere`	The zenith (declination) angle of paths for the pixel.
`pathazimuth`	Path Azimuth [degrees]	`pathangles` & `atmosphere`	The azimuth (East of North) angle of paths for the pixel.
`pathdeclination`	Path Declination [degrees]	`pathangles` & `atmosphere`	The declination (DECL) angle in the celestial sphere frame.
`pathrightaccension`	Path Right Accension [degrees]	`pathangles` & `atmosphere`	The right accension (RA) angle in the celestial sphere frame.
`pathradiance`	Path Radiance	`atmosphere`	The atmospheric path radiance at the reference wavelength.
`pathtransmission`	Path Transmission	`atmosphere`	The atmospheric path transmission for the reference wavelength.
`pathlighttime`	Path Light Time [seconds]	`atmosphere` & `propagation`	The average propagation time between the sensor and the intersected surfaces.
`propstartdirx`	Path Direction ECEF X Component (at sensor)	`propagation`	The initial (at sensor) X component of the average ray in ECEF
`propstartdiry`	Path Direction ECEF Y Component (at sensor)	`propagation`	The initial (at sensor) Y component of the average ray in ECEF
`propstartdirz`	Path Direction ECEF Y Component (at sensor)	`propagation`	The initial (at sensor) Z component of the average ray in ECEF
`propenddirx`	Path Direction ECEF X Component (at scene)	`propagation`	The final (at scene) X component of the average propagated ray in ECEF
`propenddiry`	Path Direction ECEF Y Component (at scene)	`propagation`	The final (at scene) Y component of the average propagated ray in ECEF
`propenddirz`	Path Direction ECEF Z Component (at scene)	`propagation`	The final (at scene) Z component of the average propagated ray in ECEF
`sunshadow`	Sun Fraction	`shadow`	The fraction of the pixel that is directly lit by the sun
`sunexposure`	Sun Exposure	`shadow`	Cosine weighted version of the sun shadow.
`moonshadow`	Moon Fraction	`shadow`	The fraction of the pixel that is directly lit by the moon
`moonexposure`	Moon Exposure	`shadow`	Cosine weighted version of the moon shadow.
`skyfraction`	Sky Fraction	`shadow`	The fraction of the sky illuminating the pixel
`solarirradiance`	Solar Irradiance (w/ cos)	`irradiance`	The cosine weighted solar irradiance for the reference wavelength.
`lunarirradiance`	Lunar Irradiance (w/ cos)	`irradiance`	The cosine weighted lunar irradiance for the reference wavelength.
`mediumx`	Scene ENU X Coordinate (medium) [m]	`mediumintersection`	The average X coordinate of the first boundary inside a medium (Scene ENU)
`mediumy`	Scene ENU Y Coordinate (medium) [m]	`mediumintersection`	The average Y coordinate of the first boundary inside a medium (Scene ENU)
`mediumz`	Scene ENU Z Coordinate (medium) [m]	`mediumintersection`	The average Z coordinate of the first boundary inside a medium (Scene ENU)
`volpathlength`	Volume Path Length [m]	`volume`	The length of a path through the first volume
`volconclength`	Volume Concentration Length [conc*m]	`volume`	The concentration path length of a path through the first volume
`temperature`	Temperature [K]	`temperature`	The average temperature with the pixel [Kelvin]
`samplecount`	Sample Count	`paths`	The number of primary rays used for the pixel
`bouncecount`	Bounce Count	`paths`	The average number of bounces for rays in the pixel
`sourcecount`	Source Count	`paths`	The number of sources contributing in a pixel
`abundance`	Abundance	(none)	The abundance (fill fraction) of a material within a pixel
`convergencestatus`	Convergence Status	(none)	A flag capturing how the problem converged (or not)
`cloudlayerfraction`	Cloud layer fraction	(none)	The fraction number of samples that hit a cloud layer (not a VDB cloud)

In DIRSIG5, you can also specify the name all and collect data from all the available truth collectors.

Material Indexes

The material index truth collectors extract information about the materials and/or material variants are present within each pixel. Since a pixel may contain more than one material, this collector reports information about the most commonly found materials and optical properties sampled within the pixel.

The material truth set requests the following individual truth collectors:

materialindex: This is the index of the most common material in the pixel. This index can be linked back to a specific material via the scene_tool utility’s lookup tool. The corresponding long name for this collector is Dominant Material Index.

materialvariantindex: This is the index of the most common variant or property for a material in the pixel. The most common example of a variant is which curve is used in a material with spatial variation using multiple curves (e.g., a material using a texture map or curve map). This index can be linked back to a specific optical property via the scene_tool utility’s lookup tool. The corresponding long name for this collector is Dominant Optical Property Index.

Geometry Indexes

The geometry truth collectors extract information about the geometry of the first surface intersected within a pixel.

The geoids truth set requests the following individual truth collectors:

sceneindex: This is the index of the most common scene within a pixel. When multiple scenes are employed in a simulation, this index indicates which scene was the most common within the pixel.

instanceindex: Internally, each instance of every object has a unique "index" that can be used to resolve where instances of each object are located at a given time. The "instance index" truth collector gathers the unique instance index that dominates the spatial area of the pixel.

geometryindex: Internally, each base geometry object has a unique "index" that can be used to resolve geometry shared by instances and the source of that geometry. The "geometry index" truth collector gathers the unique base geometry index that dominates the spatial area of the pixel.

primitiveindex: Internally, each base geometry object is made up of one or more geometry "primitives". In the case of facetized geometry, these primitives are facets. In the case of built-in geometry (boxes, spheres, etc.), the index does not have a meaning.

Surface Intersections

The surface intersection truth collectors extract information about the location, distances, angles, etc. the first surface intersected within a pixel.

The intersection truth set requests the following individual truth collectors:

scenex, sceney and scenez: The average XYZ location for the geometry intersected within a pixel in the Scene ENU coordinate system.

distance: The distance (in meters) from the sensor to the object.

viewcosine: The cosine of the relative angle between the viewing ray and the surface normal.
textureu and texturev: The intersection truth set also includes the texture coordinate collectors.

To get geographic intersection information (rather than values in the Scene ENU coordinate system) use the Geolocation collector.

A useful way to determine the Scene ENU coordinates of an object in a scene is to render the scene with the Intersection truth enabled and then load the X, Y and Z intersection bands as the Red, Green and Blue bands in the image viewer. As you hover your mouse over any pixel, the "data value" will be the XYZ location of that object.

Texture Coordinates

The intersection truth collectors extract information about the texture coordinates with the first surface intersected within a pixel.

The texture truth set requests the following individual truth collectors:

textureu and texturev: The average UV mapping coordinate within the pixel. These coordinates will be -1 if there is no UV coordinate information associated with the object.

These value can be unexpected when multiple surfaces are intersected within a pixel and the UV coordinates vary greatly.

Surface Normals

The normal truth collectors extract information about the average normal of the first surface intersected within a pixel.

The normal truth set requests the following individual truth collectors:

normx, normy and normz: The unitless XYZ values of the average normal for the surfaces intersected within a pixel in the Scene ENU coordinate system.

Barycentric Coordinates

The barycentric coordinate truth collectors extract information about the average barycentric coordinate of the intersection within a pixel. These coordinates are internally generated and then used for interpolating geometric properties across a facet, including vertex normals and texture coordinates.

The barycentriccoords truth set requests the following individual truth collectors:

baryu, baryv and baryw: The unitless UVW values of the average barycentric coordinate for the surfaces intersected within a pixel.

Geolocation

The geolocation truth collector gathers the average latitude, longitude and altitude of the intersection within the pixel.

latitude, longitude and altitude: The average latitude (degrees, positive North), longitude (degrees, positive East), and altitude (meters above the WGS-84 ellipsoid) in the Geodetic coordinate system.

ecefx, ecefy and ecefz: The average XYZ coordinate in the Earth-Centered, Earth-Fixed coordinate system.

Temperature

The temperature truth collectors gather temperature information about objects intersected within a pixel.

The temperature truth set requests the following individual truth collectors:

temperature: The average temperature in Kelvin of the surface(s) intersected within the pixel.

Atmosphere

The atmospheric path collectors gather information about the atmospheric contributions along the primary path from the sensor to the first intersection. Internally these are a spectral quantities but are reported for the reference wavelength only.

These path radiance and transmission values can be used to verify the additive "path" or "upwelled" radiance and multiplicative transmission term extracted from an atmosphere compensation algorithm.

The atmosphere truth set requests the following individual truth collectors:

pathzenith: The average zenith (declination) angle in degrees for the paths within the pixel. This collector is also included in the pathangles truth set).
pathazimuth: The average azimuth angle in degrees (East of North) for paths within the pixel. This collector is also included in the pathangles truth set.

pathradiance: The average spectral radiance (at the reference wavelength) from the atmosphere within the pixel. The units are Watts / (cm² sr micron).

pathtransmission: The average transmission (at the reference wavelength) from the atmosphere within the pixel. This quantity is unitless.

Shadows

The shadow truth collectors gather information about solar and lunar shadows within the pixel.

The shadow truth set requests the following individual truth collectors:

sunshadow: The fraction of the pixel that is directly illuminated by the sun.

sunexposure: The fraction of the pixel that is directly illuminated by the sun and cosine weighted by the relative angle between the surface and the sun direction.

moonshadow: The fraction of the pixel that is directly illuminated by the moon.

moonexposure: The fraction of the pixel that is directly illuminated by the moon and cosine weighted by the relative angle between the surface and the moon direction.

skyfraction: The fraction of the sky that is illuminating the pixel. Note that this quantity is not directly used in the radiometry solution, rather it is computed from the solution to provide insights into the solution.

Medium Intersections

The medium intersection truth collectors extract information about the location, distances, angles, etc. the first medium (volume, cloud, plume, etc.) intersected within a pixel.

The medium truth set requests the following individual truth collectors:

mediumx, mediumy and mediumz: The medium intersection collectors return the respective Scene ENU coordinate for the first boundary encountered with a medium. In the case of a plume or cloud, this could be an internal object (e.g., a plane inside the cloud) or the exit boundary of the plume or cloud.

Path Angles

The path angle collectors gather information about the average direction of the paths sampling a pixel.

The pathangles truth set requests the following individual truth collectors:

pathzenith: The average zenith (declination) angle in degrees for the paths within the pixel.

pathazimuth: The average azimuth angle in degrees (East of North) for paths within the pixel.

pathdeclination: The average declination (DECL) angle in degrees, which is the celestial sphere’s equivalent of latitude.

pathrightaccension: The average right accension (RA) angle in degrees, which is the celestial sphere’s equivalent of longitude.

Propagation

The propagation truth captures information about light propagation between the sensor and the intersected surface. This includes the propagaton time (aka light time) and the inital (at the sensor) and final (at the scene) view direction vector components, which maybe be different due to refraction.

pathlighttime: The average light propagation time in seconds between the sensor and surface(s) intersected within the pixel. This time reflects the varying index of refraction through the atmosphere.

propstartdirx: The X component of the average pixel sampling ray direction at the sensor (before refraction) in ECEF coordinates.

propstartdiry: The Y component of the average pixel sampling ray direction at the sensor (before refraction) in ECEF coordinates.

propstartdirz: The Z component of the average pixel sampling ray direction at the sensor (before refraction) in ECEF coordinates.

propstartdirx: The X component of the average pixel sampling ray direction at the scene (after refraction) in ECEF coordinates.

propstartdiry: The Y component of the average pixel sampling ray direction at the scene (after refraction) in ECEF coordinates.

propstartdirz: The Z component of the average pixel sampling ray direction at the scene (after refraction) in ECEF coordinates.

Path Tracing Data

The path intersection truth captures data about the sampling performed by the path tracer, including how many paths (samples) per pixel are used and the average number of bounces (scattering events) were used.

The paths truth set requests the following individual truth collectors:

samplecount: The number of paths used to sample the pixel.

bouncecount: The average number of bounces used in the paths sampling the pixel.

sourcecount: The average number of user-defined sources contribution to the pixel.

Volume, Cloud and Plume Data

When working with volumetric data (e.g., via the OpenVDB plugins), it is useful to get data for volumes in the pixel. The currently available collectors gather data about the path within the first volume along the path.

If the volume includes scattering, then this data is collected for the scattered path within the volume. Hence, the "length" of the path reflects distance that the ray wandered within the volume and not the distance through the volume.

If there are multiple, overlapping volumes within a pixel, this truth does not distinguish between them and the combined values are provided.

The volume truth set requests the following individual truth collectors (note the cloud and plume sets are an alias for this set):

volpathlength: The length of a path in meters within the first volume.

volconclength: The concentration path length in ppm-meters of a path within the first volume.

Other truth products will contain information about the volume. See this section of the VDB plugins manual for an example of volume properties for a volumetric plume being captured in other truth products.

Abundance

The abundance truth collector gathers precise sub-pixel abundance fractions for a user-supplied list of material IDs or tags names. This is especially handy in situations where the user is looking to generate a truth mask for a target detection algorithm. The resulting truth "band" for each requested material ID will contain how much of the pixel was occupied by that material or tag as a fraction from 0 - 1. This data can be used to drive pixel resolution receiver operator characteristic (ROC) curve analysis of a target detection algorithm.

Material Abundance

The user must supply the truth collector the list of material IDs to be collected as a comma separated list.

Important Notes:

In a simulation with multiple-scenes, the abundance collector will find materials with the supplied ID across all scenes. This allows for the abundance of the same material in each scene to be collected into a single truth map.
In some cases, different scenes might contain materials with the same material ID that were not intended to be same. In those cases, the supplied material ID can be combined with the scene name to only track the material in a specific scene. The format for the material ID in this case is a scene name and material ID pair separated by "::" (i.e., tile1::grass, where tile1 is the scene name name and grass is the material ID).

Tagged (Geometry) Abundance

Alternatively, the collector can be configured to track abundance based on geometry tags.

Convergence Status

The convergence status flag indicates how or if the problem (pixel) convergence was satisfied (or not). The status flag can have the following values:

0 → The radiance converged using some number of samples greater than the minimum and less than the maximum.

1 → The radiance converged using only the minimum number of samples.

2 → The radiance did not converge after using the maximum number of samples.

3 → No user scene was hit and the default earth core was hit instead.

4 → The radiance never reached the radiance threshold and was set to 0.

Cloud layer fraction

The cloud layer fraction indicates the decimal fraction of samples that hit a cloud layer and were scattered versus continuing along a free path to other geometry/sky. This only tracks clouds that are defined in CloudModelInterface based plugins that define clouds in global layers, not OpenVDB or other free-standing clouds which are handled as normal volumes.