s1-geometry
Tool to estimate geometric quantities (such as incidence, elevation or ground heading angle) from a Sentinel-1 SAR footprint.
The current release (v0.2) provides the IW ground heading as a function of the reference point and the SAFE footprint polygon, with a latitude-dependent uncertainty, and the incidence / elevation angles of IW and EW acquisitions at a reference point.
Install
# from PyPI
python -m pip install s1-geometry
# from a checkout (editable)
python -m pip install -e .
# optional: CDSE daily-Parquet footprint indexer (load_sar_polygons)
python -m pip install -e '.[parquet]'
Python >= 3.11 is required; the only hard dependency is numpy.
Usage
Python
The generic entry point estimates every available geometric quantity from the SAFE footprint:
from s1_geometry import estimate_geometry
# sar_polygon: the CDSE GeoFootprint — a (lon, lat) vertex sequence,
# a GeoJSON Polygon string, or a GeoJSON Polygon dict (STAC geometry)
result = estimate_geometry(sar_polygon, ref_lat=36.592652)
result.orbit_direction # "ascending" | "descending" | "turning"
result.ref_lat # reference latitude (deg)
result.heading_deg # ground heading (deg, clockwise from North)
result.heading_uncertainty_deg # latitude-dependent uncertainty (deg)
When ref_lat is omitted it defaults to the mean latitude of the footprint
vertices. Catalogue-oriented named functions are also exported (this is the
function behind the SOBA sar_ground_heading column):
from s1_geometry import (
sar_ground_heading, # heading (deg) at ref_lat
sar_ground_heading_uncertainty, # U(lat) (deg), per hemisphere
sar_heading_and_uncertainty, # (heading, U) at once
orbit_direction_from_ring, # pass direction (flight rule)
)
The incidence / elevation angles of an IW or EW acquisition are estimated at a reference point from the SAFE footprint and the imaging mode:
from s1_geometry import estimate_incidence_elevation
# sar_polygon as above; mode "IW" (default) or "EW"
angles = estimate_incidence_elevation(sar_polygon, ref_lon=10.5, ref_lat=36.59, mode="IW")
angles.mode # "IW" | "EW"
angles.dfrac # 0 = near range line, 1 = far range line
angles.swath_width_km # across-track ground width of the footprint (km)
angles.r_s_km # inverted satellite geocentric distance (km)
angles.incidence_deg # incidence angle from the local vertical (deg)
angles.elevation_deg # 90 - incidence (deg, exact)
The same quantities are available on the generic entry point
(estimate_geometry(sar_polygon, ref_lon=10.5, ref_lat=36.59, mode="IW"))
and through the catalogue-oriented functions sar_incidence_angle(...) /
sar_elevation_angle(...) (the functions behind the sar_incidence_angle /
sar_elevation_angle columns).
The reference point must lie inside the SAFE footprint (the 4-vertex
parallelogram, boundary included). If it is outside,
estimate_incidence_elevation raises a ValueError ("outside the SAFE
footprint") instead of returning an extrapolated, meaningless value.
CLI
s1-geometry heading footprint.geojson --lat 36.59
s1-geometry heading '{"type": "Polygon", "coordinates": [[...]]}' --lat 36.59 --json
s1-geometry angles footprint.geojson --lon 10.5 --lat 36.59 --mode IW
s1-geometry angles footprint.geojson --lon 10.5 --lat 36.59 --json
The polygon argument is a GeoJSON file path or an inline JSON string: a
GeoJSON Polygon object, a GeoJSON Feature, or a bare ring of [lon, lat]
vertices; --json prints a machine-readable result.
Runnable examples: examples/heading_from_footprint.py
and examples/incidence_elevation_end2end.py
(the end-to-end script turns a Parquet of footprints + reference positions
into a Parquet with the sar_incidence_angle / sar_elevation_angle columns;
a bundled 10-row sample lives in examples/data/).
The model
The heading of an IW acquisition depends almost only on the latitude and the orbit direction; the four satellites agree within a fraction of a degree, so two pooled degree-4 polynomials (ascending / descending) describe the whole constellation. Beyond |lat| = 70 deg the polynomials extrapolate and the uncertainty model carries the extra error.
The orbit direction is the pass (flight) direction derived from the
footprint, not the orbit branch: a northbound pass is ascending, a
southbound pass descending. The flight runs along the burst (along-track)
edges of the 4-vertex SAFE parallelogram, which are the shorter opposite-
edge family for IW. The rule is order-robust: it handles both the standard
CDSE GeoFootprint vertex order (counter-clockwise) and the clockwise ring
copied from the CDSE product page, and reduces to the historical
dlat = lat(v[1]) - lat(v[0]) rule for the standard order. The pass is
turning (polar turnaround, near-due-west heading of 270 deg) when the
flight's north component is below 0.3 deg in magnitude.
The uncertainty is per hemisphere: the p95 of the fit error binned by |lat| (degree-4 for |lat| <= 70, piecewise-linear beyond, clamped at the measured turning latitudes 84.5 N / 77.5 S). It grows with latitude so that users can decide for themselves instead of rejecting high-latitude acquisitions.
The incidence / elevation angles combine two consistent models (verified against the ESA / SentiWiki documented angles to <= 0.07 deg):
- Constant slant range (the CDSE catalogue footprint): the across-track ground width W of the 4-vertex ring is a monotonic function of the satellite geocentric distance R_s; the catalogue polygon is computed with the mean Earth radius (6371 km), so inverting W -> R_s (bisection) calibrates the satellite altitude from the footprint alone, with no orbit file. In the standard CDSE vertex order (GRDH/GRDM/SLC/OCN) the range lines are the v0-v1 (far) and v2-v3 (near) edges, ascending and descending alike; rings with a rotated vertex order (e.g. ETA) fall back to the other edge pair when the standard width does not invert to a valid orbit altitude.
- Off-nadir (the actual radar steering): with R_s, the WGS84 geocentric
radius R_e of the reference point and the off-nadir angle sigma (the linear
roll law between the documented min / max-altitude values per sub-swath),
the geocentric incidence is the closed form
theta_c = asin[(R_s/R_e) * sin(sigma)]; the local (ellipsoid-normal) incidence adds the deflection of the vertical (max ~0.19 deg near |lat| = 45 deg) and the elevation is exactly90 deg - incidence.
The reference point selects sigma through its across-track position
dfrac (0 = near range line, 1 = far range line). Full-swath footprints are
the supported case; a partial-swath EW footprint whose width does not invert
to an orbit altitude in the documented 697.6-725.8 km band raises
ValueError.
Validation
Fitted on 13 consecutive days of S1 IW OCN OWI data from all four satellites (11107 products, 44428 grid corners; fit window |lat| <= 70 deg, headings wrapped to the per-orbit median): ascending n = 4739 residual std 0.30 deg (p95 0.64), descending n = 5104 residual std 0.32 deg (p95 0.65).
Against the measured OWI heading of the 11107 products: mean |error| 0.749 deg, median 0.139 deg, p95 2.90 deg; 98.88 % of the headings fall within the returned U(lat) and 99.96 % within 2 U(lat). In the fitted window |lat| <= 70 deg the mean error is 0.14-0.25 deg per latitude band and the p95 stays below 1.19 deg.
The orbit-direction rule was validated against the orbitDirection
attribute of 66243 CDSE IW/EW rings (13 daily v2 Parquets,
2026-11-01..13): IW 99.70 % and EW 92.05 % (both unchanged by the
order-robust rule), ETA 97.82 % (the historical dlat rule gave 55.66 %,
because ETA rings use a rotated vertex order). The remaining EW errors are
the pre-existing high-latitude ones. The flight direction is two-valued from
the ring alone (the near/far and start/end corners are unlabeled, a Z2
symmetry): the rule resolves it for the two documented vertex orders
(standard CDSE and product-page); a fully reversed ring may be
misclassified.
The angle model was validated on 66243 CDSE IW/EW rings: 98.9 % (IW) and 90.8 % (EW) of the products invert an orbit altitude in the documented 697.6-725.8 km band; the off-nadir model reproduces the documented per-sub-swath angles to <= 0.07 deg, and the full chain (ring -> W -> R_s -> incidence) is simulated to <= 0.11 deg (IW) and <= 0.05 deg (EW) maximum error.
Roadmap
- IW ground heading
sar_ground_heading = F(ref_lat, SAR_polygon)+ U(lat) - Incidence angle estimator
sar_incidence_angle(IW + EW) - Elevation angle estimator
sar_elevation_angle(IW + EW)
Development
python -m pip install -e '.[parquet]' pytest pre-commit
pre-commit run --all-files # ruff + file hygiene
python -m pytest -q # test suite
GitHub workflows: CI (pre-commit + pytest), Build (wheel + CLI smoke
test), Docs (sphinx), Publish (PyPI on release). Container image:
apptainer build s1-geometry.sif apptainer.def.
Metadata
Release files for s1-geometry 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| s1_geometry-0.2.0.tar.gz | 3.2 MB | With provenance | Details for s1_geometry-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| s1_geometry-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for s1_geometry-0.2.0-py3-none-any.whl |
Total release size: 3.3 MB
Release files / s1_geometry-0.2.0.tar.gz
| Download URL | s1_geometry-0.2.0.tar.gz |
|---|---|
| Size | 3.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0efed793e86aa33594e89247200cf593c821f5396650146dcc9959b1102e9edb
|
|
BLAKE2b-256 checksum How to use checksums |
0dc6f6a105fd9e30e03b72b0bbfd38d1bc7dca3d9bbb8db50137081c4059630e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / s1_geometry-0.2.0-py3-none-any.whl
| Download URL | s1_geometry-0.2.0-py3-none-any.whl |
|---|---|
| Size | 32.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
02cb44c8c24a1671d93f63c391b87d6e37128ebf975dc770b4ba016a9b1b1f9e
|
|
BLAKE2b-256 checksum How to use checksums |
acefd0e3fe47d907e74b57e4f45ad9881bacbb0bbfd77e40370ec8227fef5f75
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for s1-geometry 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for s1_geometry-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.