libera_utils.footprint_matching.weighting#

Per-sample PSF weighting and coverage for footprint aggregation.

What this module provides#

The aggregation engine needs, for every native sample a reader served for a footprint, a weight proportional to how strongly that ground location contributes to what the radiometer measured – i.e. the instrument Point Spread Function (PSF) evaluated at that sample. This module defines the interface for producing those weights (PixelWeigher) and two implementations:

  • AngularPSFWeigher – the CERES-faithful weigher. It projects each sample into the radiometer’s along-scan/cross-scan angular frame (delta, beta) (via project_to_angular()) and evaluates the analytic CERES PSF psf_weight() there, honouring the asymmetric along-scan response, the scan direction (L1B Cone_Angle_Rate), and the stationary-scanner static FOV (design doc sections 2.4.2.5-2.4.2.7, 2.8.1.1).

  • RadialWeigher – a boresight-centered Gaussian stand-in. It sizes the PSF from the satellite radius and viewing zenith angle but needs no viewing frame, so it does not read the subsatellite point or the scan direction.

The weight is evaluated at the sample’s own location: no sample is averaged, binned or interpolated before it is weighted, and the aggregation engine is the only place the weighted samples are combined.

Coverage#

Each WeightField also carries the footprint’s coverage: the fraction of the PSF’s energy that is backed by a usable sample. Because a swath gap simply has no samples, coverage cannot be read off the samples alone. Each weigher therefore lays a fine reference grid over the PSF contour in its own frame (angular for the angular weigher, ground-plane for the radial one) holding the PSF energy of every cell, and treats each finite sample as covering the square centered on it whose half-width is the circumradius of the source’s native cell (RESOLUTION_KM / sqrt(2)), so a regular lattice of cells leaves no gap at any rotation relative to the reference axes. In the angular frame the square is foreshortened along-scan by cos(VZA), as the ground cell is when seen at an oblique view. Coverage is the share of the reference energy inside at least one such square. A complete source scores 1.0; a source missing half the contour scores about 0.5; a source with no samples scores 0.0 – exactly the quantity the CERES 75 % / 95 % rule is applied to. A source whose cell is wider than the contour (the 1 degree VIIRS composites) is complete as soon as one sample lies inside it.

References

Classes

AngularPSFWeigher([fov_halfangle_deg, ...])

Science-accurate PSF weighting via the radiometer angular frame.

PixelWeigher()

Interface: turn a footprint's samples + viewing geometry into per-sample PSF weights.

RadialWeigher([fov_halfangle_deg])

Boresight-centered radial Gaussian PSF weight -- the swappable stand-in.

WeightField(weights, total_energy, ...)

Per-sample PSF weights and coverage for one footprint and one source.