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

Note 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.

Important 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.

Note 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)

Note 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.

Note To get geographic intersection information (rather than values in the Scene ENU coordinate system) use the Geolocation collector.
Tip 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.

Note 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.

Tip 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 / (cm2 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.

Important 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.
Important 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.

Tip 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, 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.