libera_utils.footprint_matching.geometry.compute_footprint_bounding_box#

libera_utils.footprint_matching.geometry.compute_footprint_bounding_box(boresight_lat_deg: float, boresight_lon_deg: float, subsatellite_lat_deg: float, subsatellite_lon_deg: float, *, satellite_radius_km: float, fov_halfangle_deg: float = 1.0, on_limb: Literal['flag', 'raise'] = 'flag') → BoundingBox#

Compute the lat/lon bounding box of one radiometer footprint on the surface.

Single-footprint form of compute_footprint_bounding_boxes(), which documents the method and inputs, that raises instead of returning None for an off-Earth view and can raise on limb truncation.

Parameters:

  • boresight_lat_deg (float) – Footprint centroid (L1B Latitude/Longitude), degrees.

  • boresight_lon_deg (float) – Footprint centroid (L1B Latitude/Longitude), degrees.

  • subsatellite_lat_deg (float) – Geodetic sub-point of the spacecraft (L1B Subsatellite_Latitude/Longitude), degrees.

  • subsatellite_lon_deg (float) – Geodetic sub-point of the spacecraft (L1B Subsatellite_Latitude/Longitude), degrees.

  • satellite_radius_km (float) – Distance of the spacecraft from Earth’s center (L1B Radius_of_Satellite_from_Center_of_Earth), km.

  • fov_halfangle_deg (float, optional) – Instrument FOV half-angle, degrees; the floor on the PSF extent. Defaults to libera_utils.footprint_matching.psf.LIBERA_FOV_HALFANGLE_DEG.

  • on_limb (str, optional) – Behavior when a box corner ray runs off the Earth limb at a severe angle while the boresight is still on Earth. "flag" (default) truncates those rays at the horizon and marks the box BoundingBox.truncated = True so the orchestrator can record partial coverage; "raise" raises PartialFootprintError instead. Note this does NOT cover the centroid being off-limb (or fill inputs) – those mean there is no footprint at all and always raise OffLimbError.

Returns:

Geographic bounding box enclosing the footprint. BoundingBox.truncated is True when the box was clipped at the limb (partial coverage).

Return type:

BoundingBox

Raises:

  • MissingGeolocationError – If the subsatellite point or satellite radius is fill, non-finite or out of range, or if the footprint is not visible from the satellite they place (it lies beyond the horizon). Not an OffLimbError: this is bad input, not a view off the Earth.

  • OffLimbError – If the boresight latitude or longitude is fill, non-finite or out of range: L1B’s encoding of a space/calibration view, whose boresight misses the Earth. There is no footprint to build, so this raises regardless of on_limb.

  • PartialFootprintError – A subclass of OffLimbError. Raised only when the boresight is on Earth but a corner ray of the box is off it (severe-angle truncation) and on_limb="raise".

  • ValueError – If on_limb is not "flag" or "raise".