radiomax: observation geometry and radiometry for JAX

radiomax converts and locates what a sensor saw: solar and viewing angles per pixel, the Earth–Sun distance, the conversions from counts to radiance to reflectance, Planck and brightness temperature, the geometric air-mass factor, parallax and geostationary navigation, swath and bowtie geometry, and the empirical retrievals applied pixel by pixel. It sits at GeoNumerics tier 1 and has no state to retrieve; radiative transfer, which does, is radtrax’s. Status: proposed, at design-sketch depth.

At a glance¶

The test that places a name, from the layer map: does it need a model of radiation moving through the atmosphere? Then it is radtrax’s. Is it geometry, a unit conversion, or an empirical formula with fitted coefficients applied pixel by pixel? Then it is radiomax’s. The import goes one way, radtrax to radiomax. This page is the design; core types, algorithms and the code survey are in radiomax: design details.

The problem¶

Before a matched filter or a retrieval sees a methane pixel, the scene is calibrated, located and converted, and each of those steps is coded more than once:

Brightness temperature is written three times in geotoolz and the geometric air-mass factor three times across radtrax and plumax. The rest lives inside geoops Operators, so radtrax and plumax, which sit on plain arrays, cannot reuse it without importing a GeoStack toolkit; they copy it instead.

Angles, units and fitted formulas¶

Everything radiomax computes is a function of a pixel’s position, the time, the sensor and a few coefficients. None of it follows light through the air.

Solar geometry. With δ the solar declination and ω the hour angle at time t, the solar zenith angle θₛ at latitude φ is

and the Earth–Sun distance d(t), in astronomical units, scales the solar irradiance by 1 / d².

Viewing geometry. From the satellite’s position s and the pixel’s position p, both in Earth-centred coordinates from geophysix, the line of sight is s − p; its angle from the local vertical is the view zenith θᵥ, and its direction in the local east–north plane is the view azimuth. The relative azimuth and the scattering angle follow from the solar and viewing directions.

Radiometry. Counts become radiance through a gain g and offset o, and radiance becomes top-of-atmosphere reflectance through the band’s solar irradiance E₀:

with R(λ) the band’s spectral response; the two integrals are an integrix rule.

Thermal bands. Planck’s law gives the radiance of a black body at temperature T, with h, c and k_B from geophysix:

A sensor’s brightness temperature inverts it with band coefficients; GOES, for one, publishes T = (fₖ₂ / ln(fₖ₁ / L + 1) − b₁) / b₂.

Geometric air-mass factor. The path length through a plane-parallel atmosphere, down to the surface and back up to the sensor, relative to the vertical:

The full air-mass factor, with scattering weights per layer, is radtrax’s.

Parallax. A cloud or plume at height H, seen at view zenith θᵥ, appears displaced along the view azimuth by H tan θᵥ; geostationary navigation maps a sensor’s scan angles to latitude and longitude on geophysix’s ellipsoid.

Empirical retrievals. Formulas with fitted coefficients, applied pixel by pixel: split-window sea- and land-surface temperature from two thermal bands, SST = a₀ + a₁ T₁₁ + a₂ (T₁₁ − T₁₂) + a₃ (sec θᵥ − 1); ocean-colour band ratios; and kernel BRDF, R = f_iso + f_vol K_vol + f_geo K_geo, with fixed Ross–Li kernels and fitted weights.

Modules and boundaries¶

Six modules. Each takes plain arrays (angles, radiances, coefficients) and returns plain arrays; sensor metadata such as calibration coefficients and spectral responses arrive as arguments from the readers.

What radiomax owns, and what it hands off¶

What moves in¶

In use¶

A methane scene from counts to the inputs a matched filter needs: angles, reflectance, the air-mass factor of the target signature, and a brightness temperature for cloud screening. Every radiomax name is proposed.

# Shapes: B bands; Ny × Nx pixels; W wavelengths of the spectral responses

import geophysix as gpx
import radiomax as rmx

# --- angles ---
# proposed (radiomax)
# cos θₛ = sin φ sin δ + cos φ cos δ cos ω
solar_zenith = rmx.geometry.solar_zenith(lat, lon, time)  # (Ny, Nx) → (Ny, Nx)
# proposed (radiomax)
# θᵥ = angle between the line of sight s − p and the local vertical
view_zenith = rmx.geometry.view_zenith(  # (Ny, Nx) → (Ny, Nx)
    lat, lon, satellite_position, earth=gpx.earth.WGS84
)
# proposed (radiomax)
# d(t), in astronomical units
distance = rmx.geometry.earth_sun_distance(time)  # → ()

# --- counts to reflectance ---
# proposed (radiomax)
# L = g · DN + o, per band
radiance = rmx.radiometry.counts_to_radiance(counts, gain, offset)  # (B, Ny, Nx)
# proposed (radiomax)
# E₀ = ∫ E⊙ R dλ / ∫ R dλ, an integrix rule over each response
irradiance = rmx.radiometry.band_irradiance(  # (W,), (B, W) → (B,)
    solar_spectrum, responses, wavelength
)
# proposed (radiomax)
# ρ = π L d² / (E₀ cos θₛ)
reflectance = rmx.radiometry.reflectance(  # (B, Ny, Nx) → (B, Ny, Nx)
    radiance, irradiance, solar_zenith, distance
)

# --- what the matched filter and the cloud screen need ---
# proposed (radiomax)
# AMF = 1 / cos θₛ + 1 / cos θᵥ
air_mass = rmx.radiometry.air_mass_factor(solar_zenith, view_zenith)  # → (Ny, Nx)
# proposed (radiomax)
# T = (fₖ₂ / ln(fₖ₁ / L + 1) − b₁) / b₂
brightness = rmx.thermal.brightness_temperature(  # (Ny, Nx) → (Ny, Nx)
    thermal_radiance, coefficients
)

radtrax takes solar_zenith, view_zenith and air_mass as inputs to its forward model and builds the target signature from them; nothing in this block models the atmosphere.

Integration across the stack¶

Four libraries would import radiomax. geoops and geoproducts keep their Operators and readers and call radiomax inside them; radtrax and plumax drop their copies.

For a geoops user nothing changes; for a library below GeoStack the import moves down:

# Today:
# today (geoops)
from geoops.radiometry import bt_from_radiance

# After:
# proposed (radiomax)
from radiomax.thermal import brightness_temperature

geoops keeps bt_from_radiance as a deprecated alias for one release, and its BTFromRadiance Operator keeps its name.

Decisions and open questions¶

Two decided on the layer map, three leaning, two open. Each entry gives the position first, then the trade-off.

1. Layer: GeoNumerics tier 1¶

Decided (5 Nov 2026, on the layer map). radiomax imports geophysix and integrix and nothing from GeoStack, so radtrax and plumax can use it on plain arrays. geoops and geoproducts sit above it.

2. The line with radtrax¶

Decided (5 Nov 2026, on the layer map). Geometry, unit conversions and empirical formulas with fitted coefficients are radiomax’s; anything that needs radiation moving through an atmospheric state is radtrax’s. Kernel BRDF falls on radiomax’s side (fixed kernels, fitted weights, no path); convolving a modelled spectrum with an SRF falls on radtrax’s.

3. Spectral responses and coefficients arrive as arguments¶

Leaning. The SRF tables stay in georeader, which is spaceml-org’s and read-only to us. radiomax never imports it: a reader or a geoops Operator loads the SRF and the calibration coefficients and passes arrays in. That keeps radiomax free of file formats and of any GeoStack dependency.

4. Replace the lazy calls into georeader.reflectance¶

Leaning. geoops reaches into georeader.reflectance for counts, radiance and reflectance conversions. Those become radiomax calls, traceable under JAX, with georeader’s results kept as the test reference.

5. Coefficient tables as data¶

Leaning. Split-window, ocean-colour and BRDF coefficients differ by sensor and by version. They ship as plain data specs, one per sensor, passed to the formula, as geoproducts’ presets become plain data; the formula itself has no sensor in it.

6. Which solar-position algorithm¶

Open. The simple almanac formulas are accurate to about 0.01° and trace cheaply; NREL’s SPA reaches about 0.0003° at many times the cost. Leaning: the almanac formulas by default, SPA behind an argument, both tested against pvlib.

7. SAR and altimetry: now or when needed?¶

Open. The layer map gives radiomax SAR calibration, despeckling and altimetry corrections, but only geoops’ despeckling filters exist today and nothing below GeoStack calls them. Leaning: move the despeckling filters in wave 4, and write the altimetry corrections when a consumer asks.

Roadmap¶

Six waves, each a GitHub issue epic in the radiomax repository once it exists. Geometry and radiometry come first: they end the most copies and every methane retrieval needs them.

Waves 2, 3 and 4 can run side by side. Wave 5 is one issue per consumer, filed in that consumer’s repository and linked to the radiomax epic.

Sources¶

• The GeoStack layer map: radiomax’s layer, tier, imports and moves, and the section “radiomax and radtrax: where the line is”.

• Reda & Andreas (2004): NREL’s solar position algorithm.

• NOAA & NASA (n.d.): the Planck coefficients behind brightness temperature.

• Lucht et al. (2000): the Ross–Li kernels.

• Code read on 5 Nov 2026 at geotoolz d2f53f4 and geostack’s submodule pins: geoops radiometry/_src/ (array.py, solar.py, operators.py), geom/_src/array.py and operators.py, restore/_src/array.py; geoproducts himawari/reader.py, goes/l1b.py, _src/geostationary.py; radtrax atmosphere/geometry.py, slab/config.py; plumax hapi_lut/beers.py, radtran/config.py.