Measurements

Measurement configuration classes that specify which radiometric quantities to simulate, covering irradiance, reflectance factors (BRF, HDRF, HCRF, BHR), pixel-level variants, and the location of hemispherical measurements.

s2gos_simulator.config.measurements.IrradianceConfig pydantic-model

Bases: BaseModel

Configuration for BOA irradiance measurement using white reference disk.

Measures downward hemispheric irradiance at bottom-of-atmosphere using the white reference disk technique:

• Places a small white Lambertian disk (ρ=1.0) at the measurement location
• By sampling the incident radiance we indirectly get the total incident flux (E = π × L)

Fields:

• type (Literal['irradiance'])
• id (str)
• location (HemisphericalMeasurementLocation)
• samples_per_pixel (int)

Attributes

id pydantic-field

id: str

Unique identifier for this irradiance measurement

location pydantic-field

location: HemisphericalMeasurementLocation

Geographic or scene location for the measurement

samples_per_pixel pydantic-field

samples_per_pixel: int = 512

Monte Carlo samples per pixel

type pydantic-field

type: Literal['irradiance'] = 'irradiance'

Measurement type (always 'irradiance')

s2gos_simulator.config.measurements.BRFConfig pydantic-model

Bases: BaseModel

Configuration for BRF measurement without atmosphere.

BRF = (π × L) / (E_toa × cos(SZA))

Two modes:

1. Reference mode: Specify radiance_sensor_id (sensor already exists)
2. Auto-generation mode: Specify viewing, backend creates sensors

Fields:

• type (Literal['brf'])
• id (str)
• radiance_sensor_id (Optional[str])
• viewing (Optional[Union[AngularFromOriginViewing, DistantViewing]])
• srf (Optional[SRFType])
• samples_per_pixel (int)
• terrain_relative_height (bool)

Validators:

• validate_brf_mode

Attributes

id pydantic-field

id: str

Unique identifier

radiance_sensor_id pydantic-field

radiance_sensor_id: Optional[str] = None

ID of sensor providing radiance measurement

samples_per_pixel pydantic-field

samples_per_pixel: int = 1024

Monte Carlo samples per pixel

srf pydantic-field

srf: Optional[SRFType] = None

Spectral response function

terrain_relative_height pydantic-field

terrain_relative_height: bool = True

Interpret z-coordinates as terrain-relative offsets

type pydantic-field

type: Literal['brf'] = 'brf'

Measurement type (always 'brf')

viewing pydantic-field

viewing: Optional[
    Union[AngularFromOriginViewing, DistantViewing]
] = None

Viewing geometry for radiancemeter (auto-generation)

Functions

validate_brf_mode pydantic-validator

validate_brf_mode()

Validate that either sensor reference OR auto-generation specs are provided.

s2gos_simulator.config.measurements.HDRFConfig pydantic-model

Bases: BaseModel

Configuration for Hemispherical-Directional Reflectance Factor (HDRF).

HDRF = π × L_r / E_i

1. Reference mode: Specify radiance_sensor_id + irradiance_measurement_id
2. Auto-generation mode: Specify instrument + location/viewing, backend creates sensor + measurement

Fields:

• type (Literal['hdrf'])
• id (str)
• radiance_sensor_id (Optional[str])
• irradiance_measurement_id (Optional[str])
• instrument (Optional[Literal['radiancemeter', 'hemispherical']])
• location (Optional[HemisphericalMeasurementLocation])
• viewing (Optional[Union[LookAtViewing, AngularFromOriginViewing, DistantViewing]])
• reference_height_offset_m (Optional[float])
• srf (Optional[SRFType])
• samples_per_pixel (int)
• terrain_relative_height (bool)

Validators:

• validate_hdrf_mode

Attributes

id pydantic-field

id: str

Unique identifier

instrument pydantic-field

instrument: Optional[
    Literal["radiancemeter", "hemispherical"]
] = None

Instrument type for auto-generation

irradiance_measurement_id pydantic-field

irradiance_measurement_id: Optional[str] = None

ID of IrradianceConfig providing BOA irradiance

location pydantic-field

location: Optional[HemisphericalMeasurementLocation] = None

Location for hemispherical HDRF (auto-generation)

radiance_sensor_id pydantic-field

radiance_sensor_id: Optional[str] = None

ID of sensor providing radiance measurement

reference_height_offset_m pydantic-field

reference_height_offset_m: Optional[float] = None

Height offset for reference irradiance disk (auto-generation)

samples_per_pixel pydantic-field

samples_per_pixel: int = 64

Samples per pixel for auto-generated sensors

srf pydantic-field

srf: Optional[SRFType] = None

SRF for auto-generated sensors

terrain_relative_height pydantic-field

terrain_relative_height: bool = True

Terrain-relative height interpretation

type pydantic-field

type: Literal['hdrf'] = 'hdrf'

Measurement type (always 'hdrf')

viewing pydantic-field

viewing: Optional[
    Union[
        LookAtViewing,
        AngularFromOriginViewing,
        DistantViewing,
    ]
] = None

Viewing geometry for radiancemeter HDRF (auto-generation)

Functions

validate_hdrf_mode pydantic-validator

validate_hdrf_mode()

Validate that either sensor references OR auto-generation specs are provided.

s2gos_simulator.config.measurements.HCRFConfig pydantic-model

Bases: BaseModel

Configuration for Hemispherical-Conical Reflectance Factor (HCRF).

Two modes:

1. Reference mode: Specify radiance_sensor_id + irradiance_measurement_id
2. Auto-generation mode: Specify camera geometry, backend creates a sensor + irradiance measurement.

Fields:

• type (Literal['hcrf'])
• id (str)
• radiance_sensor_id (Optional[str])
• irradiance_measurement_id (Optional[str])
• platform_type (Optional[Literal['ground', 'uav']])
• viewing (Optional[Union[LookAtViewing, AngularFromOriginViewing]])
• fov (Optional[float])
• film_resolution (Optional[Tuple[int, int]])
• location (Optional[HemisphericalMeasurementLocation])
• srf (Optional[SRFType])
• reference_height_offset_m (Optional[float])
• samples_per_pixel (int)
• terrain_relative_height (bool)

Validators:

• validate_hcrf_mode

Attributes

film_resolution pydantic-field

film_resolution: Optional[Tuple[int, int]] = None

Camera resolution (auto-generation)

fov pydantic-field

fov: Optional[float] = None

Camera field of view (auto-generation)

id pydantic-field

id: str

Unique identifier

irradiance_measurement_id pydantic-field

irradiance_measurement_id: Optional[str] = None

ID of IrradianceConfig providing BOA irradiance

location pydantic-field

location: Optional[HemisphericalMeasurementLocation] = None

Location for the reference irradiance measurement (auto-generation)

platform_type pydantic-field

platform_type: Optional[Literal['ground', 'uav']] = None

Platform type for auto-generated camera

radiance_sensor_id pydantic-field

radiance_sensor_id: Optional[str] = None

ID of camera sensor providing conical radiance (must have FOV)

reference_height_offset_m pydantic-field

reference_height_offset_m: Optional[float] = None

Height offset for reference irradiance disk (auto-generation)

samples_per_pixel pydantic-field

samples_per_pixel: int = 64

Samples per pixel

srf pydantic-field

srf: Optional[SRFType] = None

Spectral response function for auto-generated sensors

terrain_relative_height pydantic-field

terrain_relative_height: bool = True

Terrain-relative height

type pydantic-field

type: Literal['hcrf'] = 'hcrf'

Measurement type (always 'hcrf')

viewing pydantic-field

viewing: Optional[
    Union[LookAtViewing, AngularFromOriginViewing]
] = None

Camera viewing geometry (auto-generation)

Functions

validate_hcrf_mode pydantic-validator

validate_hcrf_mode()

Validate that either sensor references OR auto-generation specs are provided.

s2gos_simulator.config.measurements.BHRConfig pydantic-model

Bases: HemisphericalMeasurementLocation

Configuration for Bi-Hemispherical Reflectance (BHR) measurement.

BHR = radiosity_surface / radiosity_white_reference

Uses distant_flux measure type in Eradiate. Requires two simulations per measurement: one for the surface radiosity and one for a white reference patch (ρ=1.0 Lambertian disk) at the same location.

Fields:

• target_lat (Optional[float])
• target_lon (Optional[float])
• target_x (Optional[float])
• target_y (Optional[float])
• target_z (Optional[float])
• samples_per_pixel (int)
• srf (Optional[SRFType])
• height_offset_m (float)
• terrain_relative_height (bool)
• type (Literal['bhr'])
• id (Optional[str])
• reference_height_offset_m (float)
• viewing (Optional[DistantViewing])

Validators:

• validate_coordinates

Attributes

id pydantic-field

id: Optional[str] = None

Unique identifier

reference_height_offset_m pydantic-field

reference_height_offset_m: float = 0.1

Height offset for white reference patch above surface (meters)

type pydantic-field

type: Literal['bhr'] = 'bhr'

Measurement type (always 'bhr')

viewing pydantic-field

viewing: Optional[DistantViewing] = None

Optional viewing geometry for pixel-level surface radiosity. When set (e.g. DistantViewing with RectangleTarget), the distant_flux surface measure uses this target instead of the point coordinates.

s2gos_simulator.config.measurements.PixelBRFConfig pydantic-model

Bases: BasePixelMeasurementConfig

BRF measurement at satellite pixel (no atmosphere).

BRF = (π × L) / (E_toa × cos(SZA))

Uses satellite sensor geometry to map pixels to scene coordinates. Simpler than PixelHDRF - uses TOA irradiance from results, no white disk needed. Requires N simulations for N pixels (radiance only).

Fields:

• id (str)
• satellite_sensor_id (str)
• pixel_indices (List[Tuple[int, int]])
• height_offset_m (float)
• samples_per_pixel (int)
• srf (Optional[SRFType])
• type (Literal['pixel_brf'])

Validators:

• validate_pixel_indices → pixel_indices

Attributes

type pydantic-field

type: Literal['pixel_brf'] = 'pixel_brf'

Measurement type (always 'pixel_brf')

s2gos_simulator.config.measurements.PixelHDRFConfig pydantic-model

Bases: BasePixelMeasurementConfig

BOA HDRF measurement at satellite pixel.

HDRF = π × L_surface / E_boa

Uses satellite sensor geometry to map pixels to scene coordinates. Requires 2N simulations for N pixels (irradiance + radiance per pixel).

Fields:

• id (str)
• satellite_sensor_id (str)
• pixel_indices (List[Tuple[int, int]])
• height_offset_m (float)
• samples_per_pixel (int)
• srf (Optional[SRFType])
• type (Literal['pixel_hdrf'])

Validators:

• validate_pixel_indices → pixel_indices

Attributes

type pydantic-field

type: Literal['pixel_hdrf'] = 'pixel_hdrf'

Measurement type (always 'pixel_hdrf')

s2gos_simulator.config.measurements.PixelBHRConfig pydantic-model

Bases: BasePixelMeasurementConfig

BHR measurement at satellite pixel.

BHR = radiosity_surface / radiosity_white_reference

Uses satellite sensor geometry to map pixels to scene coordinates. Requires 2N simulations for N pixels (surface + reference per pixel).

Fields:

• id (str)
• satellite_sensor_id (str)
• pixel_indices (List[Tuple[int, int]])
• height_offset_m (float)
• samples_per_pixel (int)
• srf (Optional[SRFType])
• type (Literal['pixel_bhr'])
• reference_height_offset_m (float)

Validators:

• validate_pixel_indices → pixel_indices

Attributes

reference_height_offset_m pydantic-field

reference_height_offset_m: float = 0.1

Height offset for white reference patch above surface (meters)

type pydantic-field

type: Literal['pixel_bhr'] = 'pixel_bhr'

Measurement type (always 'pixel_bhr')

s2gos_simulator.config.measurements.HemisphericalMeasurementLocation pydantic-model

Bases: BaseModel

Location specification for hemispheric measurements.

Used when measuring at a point with hemispherical integration (e.g., BOA irradiance, polar HDRF). Specifies target location using either geographic (lat/lon) or scene (x/y/z) coordinates.

This class provides the location where a hemispheric measurement is performed, typically for measurements that integrate over all directions (hemisphere) at a specific point in space.

Fields:

• target_lat (Optional[float])
• target_lon (Optional[float])
• target_x (Optional[float])
• target_y (Optional[float])
• target_z (Optional[float])
• samples_per_pixel (int)
• srf (Optional[SRFType])
• height_offset_m (float)
• terrain_relative_height (bool)

Validators:

• validate_coordinates

Attributes

height_offset_m pydantic-field

height_offset_m: float = 0.0

Height offset above terrain surface (meters)

samples_per_pixel pydantic-field

samples_per_pixel: int = 64

Number of samples per pixel for Monte Carlo integration

srf pydantic-field

srf: Optional[SRFType] = None

Spectral response function

target_lat pydantic-field

target_lat: Optional[float] = None

Target latitude in decimal degrees (WGS84)

target_lon pydantic-field

target_lon: Optional[float] = None

Target longitude in decimal degrees (WGS84)

target_x pydantic-field

target_x: Optional[float] = None

Target X coordinate in scene coordinate system (meters)

target_y pydantic-field

target_y: Optional[float] = None

Target Y coordinate in scene coordinate system (meters)

target_z pydantic-field

target_z: Optional[float] = None

Target Z coordinate in scene coordinate system (meters)

terrain_relative_height pydantic-field

terrain_relative_height: bool = True

If True, z-coordinates are interpreted as offsets from terrain elevation

Functions

validate_coordinates pydantic-validator

validate_coordinates() -> (
    "HemisphericalMeasurementLocation"
)

Validate that either geographic or Cartesian coordinates are provided.

Ensures: - Either lat/lon OR x/y/z are fully specified (not both) - No partial coordinate specifications