s1-geometry 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. s1_geometry-0.2.0/.github/workflows/build.yml +22 -0
  2. s1_geometry-0.2.0/.github/workflows/ci.yml +22 -0
  3. s1_geometry-0.2.0/.github/workflows/docs.yml +21 -0
  4. s1_geometry-0.2.0/.github/workflows/publish.yml +21 -0
  5. s1_geometry-0.2.0/.gitignore +16 -0
  6. s1_geometry-0.2.0/.pre-commit-config.yaml +28 -0
  7. s1_geometry-0.2.0/.readthedocs.yaml +23 -0
  8. s1_geometry-0.2.0/AGENTS.md +22 -0
  9. s1_geometry-0.2.0/LICENSE +21 -0
  10. s1_geometry-0.2.0/PKG-INFO +226 -0
  11. s1_geometry-0.2.0/README.md +204 -0
  12. s1_geometry-0.2.0/apptainer.def +36 -0
  13. s1_geometry-0.2.0/docs/Makefile +20 -0
  14. s1_geometry-0.2.0/docs/_static/certification/ew_asc.png +0 -0
  15. s1_geometry-0.2.0/docs/_static/certification/ew_desc.png +0 -0
  16. s1_geometry-0.2.0/docs/_static/certification/iw_asc.png +0 -0
  17. s1_geometry-0.2.0/docs/_static/certification/iw_desc.png +0 -0
  18. s1_geometry-0.2.0/docs/_static/certification/sm_asc.png +0 -0
  19. s1_geometry-0.2.0/docs/_static/certification/sm_desc.png +0 -0
  20. s1_geometry-0.2.0/docs/_static/certification/stats.json +168 -0
  21. s1_geometry-0.2.0/docs/_static/certification/wv_asc.png +0 -0
  22. s1_geometry-0.2.0/docs/_static/certification/wv_desc.png +0 -0
  23. s1_geometry-0.2.0/docs/_static/figures/error_vs_lat.png +0 -0
  24. s1_geometry-0.2.0/docs/_static/figures/ew_example.png +0 -0
  25. s1_geometry-0.2.0/docs/_static/figures/iw_example.png +0 -0
  26. s1_geometry-0.2.0/docs/_static/figures/sm_example.png +0 -0
  27. s1_geometry-0.2.0/docs/_static/figures/wv_example.png +0 -0
  28. s1_geometry-0.2.0/docs/api/s1_geometry.angles.rst +5 -0
  29. s1_geometry-0.2.0/docs/api/s1_geometry.cli.rst +5 -0
  30. s1_geometry-0.2.0/docs/api/s1_geometry.footprint.rst +5 -0
  31. s1_geometry-0.2.0/docs/api/s1_geometry.geometry.rst +5 -0
  32. s1_geometry-0.2.0/docs/api/s1_geometry.heading.rst +5 -0
  33. s1_geometry-0.2.0/docs/api/s1_geometry.rst +21 -0
  34. s1_geometry-0.2.0/docs/api/s1_geometry.wv.rst +5 -0
  35. s1_geometry-0.2.0/docs/certification.rst +187 -0
  36. s1_geometry-0.2.0/docs/conf.py +26 -0
  37. s1_geometry-0.2.0/docs/figures.rst +109 -0
  38. s1_geometry-0.2.0/docs/index.rst +58 -0
  39. s1_geometry-0.2.0/docs/usage.rst +163 -0
  40. s1_geometry-0.2.0/examples/data/s1_sample_footprints.parquet +0 -0
  41. s1_geometry-0.2.0/examples/heading_from_footprint.py +41 -0
  42. s1_geometry-0.2.0/examples/incidence_elevation_end2end.py +90 -0
  43. s1_geometry-0.2.0/pyproject.toml +46 -0
  44. s1_geometry-0.2.0/src/s1_geometry/__init__.py +93 -0
  45. s1_geometry-0.2.0/src/s1_geometry/angles.py +648 -0
  46. s1_geometry-0.2.0/src/s1_geometry/cli.py +156 -0
  47. s1_geometry-0.2.0/src/s1_geometry/footprint.py +336 -0
  48. s1_geometry-0.2.0/src/s1_geometry/geometry.py +130 -0
  49. s1_geometry-0.2.0/src/s1_geometry/heading.py +151 -0
  50. s1_geometry-0.2.0/src/s1_geometry/wv.py +339 -0
  51. s1_geometry-0.2.0/tests/__init__.py +1 -0
  52. s1_geometry-0.2.0/tests/rings.py +78 -0
  53. s1_geometry-0.2.0/tests/test_angles.py +426 -0
  54. s1_geometry-0.2.0/tests/test_cli.py +102 -0
  55. s1_geometry-0.2.0/tests/test_footprint.py +152 -0
  56. s1_geometry-0.2.0/tests/test_geometry.py +106 -0
  57. s1_geometry-0.2.0/tests/test_heading.py +91 -0
  58. s1_geometry-0.2.0/tests/test_wv.py +251 -0
@@ -0,0 +1,22 @@
1
+ name: Build
2
+
3
+ on:
4
+ push:
5
+ pull_request:
6
+
7
+ jobs:
8
+ distributions:
9
+ runs-on: ubuntu-latest
10
+ steps:
11
+ - uses: actions/checkout@v7
12
+ - uses: actions/setup-python@v7
13
+ with:
14
+ python-version: "3.11"
15
+ - run: pip install build
16
+ - run: python -m build
17
+ - run: pip install dist/*.whl
18
+ - run: s1-geometry --help
19
+ - uses: actions/upload-artifact@v7
20
+ with:
21
+ name: dist
22
+ path: dist/
@@ -0,0 +1,22 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ pull_request:
6
+
7
+ jobs:
8
+ checks:
9
+ runs-on: ubuntu-latest
10
+ steps:
11
+ - uses: actions/checkout@v7
12
+ - uses: actions/setup-python@v7
13
+ with:
14
+ python-version: "3.11"
15
+ cache: pip
16
+ - uses: actions/cache@v6
17
+ with:
18
+ path: ~/.cache/pre-commit
19
+ key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
20
+ - run: pip install -e '.[parquet]' pytest pre-commit
21
+ - run: pre-commit run --all-files --show-diff-on-failure
22
+ - run: python -m pytest -q
@@ -0,0 +1,21 @@
1
+ name: Docs
2
+
3
+ on:
4
+ push:
5
+ pull_request:
6
+
7
+ jobs:
8
+ sphinx:
9
+ runs-on: ubuntu-latest
10
+ steps:
11
+ - uses: actions/checkout@v7
12
+ - uses: actions/setup-python@v7
13
+ with:
14
+ python-version: "3.11"
15
+ cache: pip
16
+ - run: pip install -e ".[docs]"
17
+ - run: sphinx-build -b html -W docs docs/_build/html
18
+ - uses: actions/upload-artifact@v7
19
+ with:
20
+ name: docs-html
21
+ path: docs/_build/html
@@ -0,0 +1,21 @@
1
+ name: Publish
2
+
3
+ on:
4
+ release:
5
+ types: [published]
6
+ workflow_dispatch:
7
+
8
+ jobs:
9
+ pypi:
10
+ runs-on: ubuntu-latest
11
+ environment: pypi
12
+ permissions:
13
+ id-token: write
14
+ steps:
15
+ - uses: actions/checkout@v7
16
+ - uses: actions/setup-python@v7
17
+ with:
18
+ python-version: "3.11"
19
+ - run: pip install build
20
+ - run: python -m build
21
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,16 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ dist/
5
+ build/
6
+ .pytest_cache/
7
+ .venv/
8
+
9
+ # generated documentation, rebuilt by `make -C docs html`
10
+ docs/_build/
11
+
12
+ # end2end example output, rebuilt by `python examples/incidence_elevation_end2end.py`
13
+ examples/data/*_angles.parquet
14
+
15
+ # container images, built with `apptainer build <name>.sif apptainer.def`
16
+ *.sif
@@ -0,0 +1,28 @@
1
+ repos:
2
+ - repo: https://github.com/pre-commit/pre-commit-hooks
3
+ rev: v6.0.0
4
+ hooks:
5
+ - id: trailing-whitespace
6
+ - id: end-of-file-fixer
7
+ - id: check-yaml
8
+ - id: check-toml
9
+ - id: check-merge-conflict
10
+ - id: check-added-large-files
11
+ args: [--maxkb=2048]
12
+
13
+ - repo: https://github.com/astral-sh/ruff-pre-commit
14
+ rev: v0.17.3
15
+ hooks:
16
+ - id: ruff
17
+ args: [--fix]
18
+ # - id: ruff-format # enable to adopt its formatting
19
+
20
+ - repo: local
21
+ hooks:
22
+ - id: pytest
23
+ name: pytest
24
+ entry: /scratch/agrouaze/opencode_sandbox/micromamba/envs/dev-agent/bin/python -m pytest -q
25
+ language: system
26
+ pass_filenames: false
27
+ # not part of a normal commit: use `pre-commit run --hook-stage manual pytest`
28
+ stages: [manual]
@@ -0,0 +1,23 @@
1
+ # Read the Docs configuration.
2
+ # Reference: https://docs.readthedocs.io/en/stable/config-file/v2.html
3
+ #
4
+ # The project needs this file to build at all: Read the Docs requires the v2 schema even for a
5
+ # standard Sphinx layout. `fail_on_warning` mirrors the `Docs` workflow, which runs sphinx-build -W.
6
+
7
+ version: 2
8
+
9
+ build:
10
+ os: ubuntu-24.04
11
+ tools:
12
+ python: "3.11"
13
+
14
+ sphinx:
15
+ configuration: docs/conf.py
16
+ fail_on_warning: true
17
+
18
+ python:
19
+ install:
20
+ - method: pip
21
+ path: .
22
+ extra_requirements:
23
+ - docs
@@ -0,0 +1,22 @@
1
+ # s1-geometry
2
+
3
+ ## Project
4
+ Library to estimate geometric quantities (ground heading today; incidence
5
+ and elevation angles planned) from a Sentinel-1 SAR footprint (the SAFE
6
+ polygon, e.g. the CDSE `GeoFootprint` column).
7
+
8
+ ## Conventions
9
+ - Python >= 3.11, hatchling + `src/s1_geometry` layout, MIT (LOPS).
10
+ - Ruff line-length 100 (`select = E, F, W`); pre-commit before commits.
11
+ - Tests: `python -m pytest -q` (dev-agent env on the HPC sandbox).
12
+ - Public API is re-exported from `s1_geometry/__init__.py`; the catalogue
13
+ column name `sar_ground_heading` must stay a public function name.
14
+ - Coefficients live in `src/s1_geometry/heading.py` (embedded, validated on
15
+ 11107 IW OCN products); do not change them without refitting and
16
+ revalidating (see README "The model" and "Validation").
17
+ - Future estimators (incidence, elevation) plug into `estimate_geometry`
18
+ in `geometry.py`; shared footprint handling belongs in `footprint.py`.
19
+
20
+ ## Environment
21
+ - Use the dev-agent interpreter:
22
+ `/scratch/agrouaze/opencode_sandbox/micromamba/envs/dev-agent/bin/python`.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 LOPS Laboratory for Ocean Physics and Satellite remote sensing
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,226 @@
1
+ Metadata-Version: 2.5
2
+ Name: s1-geometry
3
+ Version: 0.2.0
4
+ Summary: Tool to estimate geometric quantities (such as incidence, elevation or ground heading angle) from a Sentinel-1 SAR footprint.
5
+ Project-URL: Repository, https://github.com/umr-lops/s1-geometry
6
+ License-Expression: MIT
7
+ License-File: LICENSE
8
+ Classifier: Intended Audience :: Science/Research
9
+ Classifier: Operating System :: OS Independent
10
+ Classifier: Programming Language :: Python :: 3.11
11
+ Classifier: Topic :: Scientific/Engineering
12
+ Requires-Python: >=3.11
13
+ Requires-Dist: numpy
14
+ Provides-Extra: docs
15
+ Requires-Dist: furo; extra == 'docs'
16
+ Requires-Dist: myst-parser; extra == 'docs'
17
+ Requires-Dist: sphinx; extra == 'docs'
18
+ Provides-Extra: parquet
19
+ Requires-Dist: pandas; extra == 'parquet'
20
+ Requires-Dist: pyarrow; extra == 'parquet'
21
+ Description-Content-Type: text/markdown
22
+
23
+ # s1-geometry
24
+
25
+ Tool to estimate geometric quantities (such as incidence, elevation or
26
+ ground heading angle) from a Sentinel-1 SAR footprint.
27
+
28
+ The current release (v0.2) provides the **IW ground heading** as a function
29
+ of the reference point and the SAFE footprint polygon, with a
30
+ latitude-dependent uncertainty, and the **incidence / elevation angles** of
31
+ IW and EW acquisitions at a reference point.
32
+
33
+ ## Install
34
+
35
+ ```bash
36
+ # from PyPI
37
+ python -m pip install s1-geometry
38
+
39
+ # from a checkout (editable)
40
+ python -m pip install -e .
41
+
42
+ # optional: CDSE daily-Parquet footprint indexer (load_sar_polygons)
43
+ python -m pip install -e '.[parquet]'
44
+ ```
45
+
46
+ Python >= 3.11 is required; the only hard dependency is `numpy`.
47
+
48
+ ## Usage
49
+
50
+ ### Python
51
+
52
+ The generic entry point estimates every available geometric quantity from
53
+ the SAFE footprint:
54
+
55
+ ```python
56
+ from s1_geometry import estimate_geometry
57
+
58
+ # sar_polygon: the CDSE GeoFootprint — a (lon, lat) vertex sequence,
59
+ # a GeoJSON Polygon string, or a GeoJSON Polygon dict (STAC geometry)
60
+ result = estimate_geometry(sar_polygon, ref_lat=36.592652)
61
+
62
+ result.orbit_direction # "ascending" | "descending" | "turning"
63
+ result.ref_lat # reference latitude (deg)
64
+ result.heading_deg # ground heading (deg, clockwise from North)
65
+ result.heading_uncertainty_deg # latitude-dependent uncertainty (deg)
66
+ ```
67
+
68
+ When `ref_lat` is omitted it defaults to the mean latitude of the footprint
69
+ vertices. Catalogue-oriented named functions are also exported (this is the
70
+ function behind the SOBA `sar_ground_heading` column):
71
+
72
+ ```python
73
+ from s1_geometry import (
74
+ sar_ground_heading, # heading (deg) at ref_lat
75
+ sar_ground_heading_uncertainty, # U(lat) (deg), per hemisphere
76
+ sar_heading_and_uncertainty, # (heading, U) at once
77
+ orbit_direction_from_ring, # pass direction (flight rule)
78
+ )
79
+ ```
80
+
81
+ The incidence / elevation angles of an IW or EW acquisition are estimated at
82
+ a reference point from the SAFE footprint and the imaging mode:
83
+
84
+ ```python
85
+ from s1_geometry import estimate_incidence_elevation
86
+
87
+ # sar_polygon as above; mode "IW" (default) or "EW"
88
+ angles = estimate_incidence_elevation(sar_polygon, ref_lon=10.5, ref_lat=36.59, mode="IW")
89
+
90
+ angles.mode # "IW" | "EW"
91
+ angles.dfrac # 0 = near range line, 1 = far range line
92
+ angles.swath_width_km # across-track ground width of the footprint (km)
93
+ angles.r_s_km # inverted satellite geocentric distance (km)
94
+ angles.incidence_deg # incidence angle from the local vertical (deg)
95
+ angles.elevation_deg # 90 - incidence (deg, exact)
96
+ ```
97
+
98
+ The same quantities are available on the generic entry point
99
+ (`estimate_geometry(sar_polygon, ref_lon=10.5, ref_lat=36.59, mode="IW")`)
100
+ and through the catalogue-oriented functions `sar_incidence_angle(...)` /
101
+ `sar_elevation_angle(...)` (the functions behind the `sar_incidence_angle` /
102
+ `sar_elevation_angle` columns).
103
+
104
+ The reference point must lie **inside the SAFE footprint** (the 4-vertex
105
+ parallelogram, boundary included). If it is outside,
106
+ `estimate_incidence_elevation` raises a `ValueError` ("outside the SAFE
107
+ footprint") instead of returning an extrapolated, meaningless value.
108
+
109
+ ### CLI
110
+
111
+ ```bash
112
+ s1-geometry heading footprint.geojson --lat 36.59
113
+ s1-geometry heading '{"type": "Polygon", "coordinates": [[...]]}' --lat 36.59 --json
114
+ s1-geometry angles footprint.geojson --lon 10.5 --lat 36.59 --mode IW
115
+ s1-geometry angles footprint.geojson --lon 10.5 --lat 36.59 --json
116
+ ```
117
+
118
+ The polygon argument is a GeoJSON file path or an inline JSON string: a
119
+ GeoJSON Polygon object, a GeoJSON Feature, or a bare ring of [lon, lat]
120
+ vertices; `--json` prints a machine-readable result.
121
+
122
+ Runnable examples: [`examples/heading_from_footprint.py`](examples/heading_from_footprint.py)
123
+ and [`examples/incidence_elevation_end2end.py`](examples/incidence_elevation_end2end.py)
124
+ (the end-to-end script turns a Parquet of footprints + reference positions
125
+ into a Parquet with the `sar_incidence_angle` / `sar_elevation_angle` columns;
126
+ a bundled 10-row sample lives in `examples/data/`).
127
+
128
+ ## The model
129
+
130
+ The heading of an IW acquisition depends almost only on the latitude and the
131
+ orbit direction; the four satellites agree within a fraction of a degree, so
132
+ two pooled degree-4 polynomials (ascending / descending) describe the whole
133
+ constellation. Beyond |lat| = 70 deg the polynomials extrapolate and the
134
+ uncertainty model carries the extra error.
135
+
136
+ The **orbit direction** is the *pass* (flight) direction derived from the
137
+ footprint, not the orbit branch: a northbound pass is `ascending`, a
138
+ southbound pass `descending`. The flight runs along the burst (along-track)
139
+ edges of the 4-vertex SAFE parallelogram, which are the *shorter* opposite-
140
+ edge family for IW. The rule is order-robust: it handles both the standard
141
+ CDSE `GeoFootprint` vertex order (counter-clockwise) and the clockwise ring
142
+ copied from the CDSE product page, and reduces to the historical
143
+ `dlat = lat(v[1]) - lat(v[0])` rule for the standard order. The pass is
144
+ **turning** (polar turnaround, near-due-west heading of 270 deg) when the
145
+ flight's north component is below 0.3 deg in magnitude.
146
+
147
+ The **uncertainty** is per hemisphere: the p95 of the fit error binned by
148
+ |lat| (degree-4 for |lat| <= 70, piecewise-linear beyond, clamped at the
149
+ measured turning latitudes 84.5 N / 77.5 S). It grows with latitude so that
150
+ users can decide for themselves instead of rejecting high-latitude
151
+ acquisitions.
152
+
153
+ The **incidence / elevation angles** combine two consistent models (verified
154
+ against the ESA / SentiWiki documented angles to <= 0.07 deg):
155
+
156
+ * **Constant slant range** (the CDSE catalogue footprint): the across-track
157
+ ground width W of the 4-vertex ring is a monotonic function of the
158
+ satellite geocentric distance R_s; the catalogue polygon is computed with
159
+ the mean Earth radius (6371 km), so inverting W -> R_s (bisection)
160
+ calibrates the satellite altitude from the footprint alone, with no orbit
161
+ file. In the standard CDSE vertex order (GRDH/GRDM/SLC/OCN) the range lines
162
+ are the v0-v1 (far) and v2-v3 (near) edges, ascending and descending alike;
163
+ rings with a rotated vertex order (e.g. ETA) fall back to the other edge
164
+ pair when the standard width does not invert to a valid orbit altitude.
165
+ * **Off-nadir** (the actual radar steering): with R_s, the WGS84 geocentric
166
+ radius R_e of the reference point and the off-nadir angle sigma (the linear
167
+ roll law between the documented min / max-altitude values per sub-swath),
168
+ the geocentric incidence is the closed form
169
+ `theta_c = asin[(R_s/R_e) * sin(sigma)]`; the local (ellipsoid-normal)
170
+ incidence adds the deflection of the vertical (max ~0.19 deg near
171
+ |lat| = 45 deg) and the elevation is exactly `90 deg - incidence`.
172
+
173
+ The reference point selects sigma through its across-track position
174
+ `dfrac` (0 = near range line, 1 = far range line). Full-swath footprints are
175
+ the supported case; a partial-swath EW footprint whose width does not invert
176
+ to an orbit altitude in the documented 697.6-725.8 km band raises
177
+ `ValueError`.
178
+
179
+ ## Validation
180
+
181
+ Fitted on 13 consecutive days of S1 IW OCN OWI data from all four satellites
182
+ (11107 products, 44428 grid corners; fit window |lat| <= 70 deg, headings
183
+ wrapped to the per-orbit median): ascending n = 4739 residual std 0.30 deg
184
+ (p95 0.64), descending n = 5104 residual std 0.32 deg (p95 0.65).
185
+
186
+ Against the measured OWI heading of the 11107 products: mean |error|
187
+ 0.749 deg, median 0.139 deg, p95 2.90 deg; **98.88 % of the headings fall
188
+ within the returned U(lat)** and 99.96 % within 2 U(lat). In the fitted
189
+ window |lat| <= 70 deg the mean error is 0.14-0.25 deg per latitude band and
190
+ the p95 stays below 1.19 deg.
191
+
192
+ The orbit-direction rule was validated against the `orbitDirection`
193
+ attribute of 66243 CDSE IW/EW rings (13 daily v2 Parquets,
194
+ 2026-11-01..13): **IW 99.70 % and EW 92.05 %** (both unchanged by the
195
+ order-robust rule), **ETA 97.82 %** (the historical dlat rule gave 55.66 %,
196
+ because ETA rings use a rotated vertex order). The remaining EW errors are
197
+ the pre-existing high-latitude ones. The flight direction is two-valued from
198
+ the ring alone (the near/far and start/end corners are unlabeled, a Z2
199
+ symmetry): the rule resolves it for the two documented vertex orders
200
+ (standard CDSE and product-page); a fully reversed ring may be
201
+ misclassified.
202
+
203
+ The angle model was validated on 66243 CDSE IW/EW rings: **98.9 % (IW) and
204
+ 90.8 % (EW) of the products invert an orbit altitude in the documented
205
+ 697.6-725.8 km band**; the off-nadir model reproduces the documented
206
+ per-sub-swath angles to <= 0.07 deg, and the full chain (ring -> W -> R_s ->
207
+ incidence) is simulated to <= 0.11 deg (IW) and <= 0.05 deg (EW) maximum
208
+ error.
209
+
210
+ ## Roadmap
211
+
212
+ - [x] IW ground heading `sar_ground_heading = F(ref_lat, SAR_polygon)` + U(lat)
213
+ - [x] Incidence angle estimator `sar_incidence_angle` (IW + EW)
214
+ - [x] Elevation angle estimator `sar_elevation_angle` (IW + EW)
215
+
216
+ ## Development
217
+
218
+ ```bash
219
+ python -m pip install -e '.[parquet]' pytest pre-commit
220
+ pre-commit run --all-files # ruff + file hygiene
221
+ python -m pytest -q # test suite
222
+ ```
223
+
224
+ GitHub workflows: `CI` (pre-commit + pytest), `Build` (wheel + CLI smoke
225
+ test), `Docs` (sphinx), `Publish` (PyPI on release). Container image:
226
+ `apptainer build s1-geometry.sif apptainer.def`.
@@ -0,0 +1,204 @@
1
+ # s1-geometry
2
+
3
+ Tool to estimate geometric quantities (such as incidence, elevation or
4
+ ground heading angle) from a Sentinel-1 SAR footprint.
5
+
6
+ The current release (v0.2) provides the **IW ground heading** as a function
7
+ of the reference point and the SAFE footprint polygon, with a
8
+ latitude-dependent uncertainty, and the **incidence / elevation angles** of
9
+ IW and EW acquisitions at a reference point.
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ # from PyPI
15
+ python -m pip install s1-geometry
16
+
17
+ # from a checkout (editable)
18
+ python -m pip install -e .
19
+
20
+ # optional: CDSE daily-Parquet footprint indexer (load_sar_polygons)
21
+ python -m pip install -e '.[parquet]'
22
+ ```
23
+
24
+ Python >= 3.11 is required; the only hard dependency is `numpy`.
25
+
26
+ ## Usage
27
+
28
+ ### Python
29
+
30
+ The generic entry point estimates every available geometric quantity from
31
+ the SAFE footprint:
32
+
33
+ ```python
34
+ from s1_geometry import estimate_geometry
35
+
36
+ # sar_polygon: the CDSE GeoFootprint — a (lon, lat) vertex sequence,
37
+ # a GeoJSON Polygon string, or a GeoJSON Polygon dict (STAC geometry)
38
+ result = estimate_geometry(sar_polygon, ref_lat=36.592652)
39
+
40
+ result.orbit_direction # "ascending" | "descending" | "turning"
41
+ result.ref_lat # reference latitude (deg)
42
+ result.heading_deg # ground heading (deg, clockwise from North)
43
+ result.heading_uncertainty_deg # latitude-dependent uncertainty (deg)
44
+ ```
45
+
46
+ When `ref_lat` is omitted it defaults to the mean latitude of the footprint
47
+ vertices. Catalogue-oriented named functions are also exported (this is the
48
+ function behind the SOBA `sar_ground_heading` column):
49
+
50
+ ```python
51
+ from s1_geometry import (
52
+ sar_ground_heading, # heading (deg) at ref_lat
53
+ sar_ground_heading_uncertainty, # U(lat) (deg), per hemisphere
54
+ sar_heading_and_uncertainty, # (heading, U) at once
55
+ orbit_direction_from_ring, # pass direction (flight rule)
56
+ )
57
+ ```
58
+
59
+ The incidence / elevation angles of an IW or EW acquisition are estimated at
60
+ a reference point from the SAFE footprint and the imaging mode:
61
+
62
+ ```python
63
+ from s1_geometry import estimate_incidence_elevation
64
+
65
+ # sar_polygon as above; mode "IW" (default) or "EW"
66
+ angles = estimate_incidence_elevation(sar_polygon, ref_lon=10.5, ref_lat=36.59, mode="IW")
67
+
68
+ angles.mode # "IW" | "EW"
69
+ angles.dfrac # 0 = near range line, 1 = far range line
70
+ angles.swath_width_km # across-track ground width of the footprint (km)
71
+ angles.r_s_km # inverted satellite geocentric distance (km)
72
+ angles.incidence_deg # incidence angle from the local vertical (deg)
73
+ angles.elevation_deg # 90 - incidence (deg, exact)
74
+ ```
75
+
76
+ The same quantities are available on the generic entry point
77
+ (`estimate_geometry(sar_polygon, ref_lon=10.5, ref_lat=36.59, mode="IW")`)
78
+ and through the catalogue-oriented functions `sar_incidence_angle(...)` /
79
+ `sar_elevation_angle(...)` (the functions behind the `sar_incidence_angle` /
80
+ `sar_elevation_angle` columns).
81
+
82
+ The reference point must lie **inside the SAFE footprint** (the 4-vertex
83
+ parallelogram, boundary included). If it is outside,
84
+ `estimate_incidence_elevation` raises a `ValueError` ("outside the SAFE
85
+ footprint") instead of returning an extrapolated, meaningless value.
86
+
87
+ ### CLI
88
+
89
+ ```bash
90
+ s1-geometry heading footprint.geojson --lat 36.59
91
+ s1-geometry heading '{"type": "Polygon", "coordinates": [[...]]}' --lat 36.59 --json
92
+ s1-geometry angles footprint.geojson --lon 10.5 --lat 36.59 --mode IW
93
+ s1-geometry angles footprint.geojson --lon 10.5 --lat 36.59 --json
94
+ ```
95
+
96
+ The polygon argument is a GeoJSON file path or an inline JSON string: a
97
+ GeoJSON Polygon object, a GeoJSON Feature, or a bare ring of [lon, lat]
98
+ vertices; `--json` prints a machine-readable result.
99
+
100
+ Runnable examples: [`examples/heading_from_footprint.py`](examples/heading_from_footprint.py)
101
+ and [`examples/incidence_elevation_end2end.py`](examples/incidence_elevation_end2end.py)
102
+ (the end-to-end script turns a Parquet of footprints + reference positions
103
+ into a Parquet with the `sar_incidence_angle` / `sar_elevation_angle` columns;
104
+ a bundled 10-row sample lives in `examples/data/`).
105
+
106
+ ## The model
107
+
108
+ The heading of an IW acquisition depends almost only on the latitude and the
109
+ orbit direction; the four satellites agree within a fraction of a degree, so
110
+ two pooled degree-4 polynomials (ascending / descending) describe the whole
111
+ constellation. Beyond |lat| = 70 deg the polynomials extrapolate and the
112
+ uncertainty model carries the extra error.
113
+
114
+ The **orbit direction** is the *pass* (flight) direction derived from the
115
+ footprint, not the orbit branch: a northbound pass is `ascending`, a
116
+ southbound pass `descending`. The flight runs along the burst (along-track)
117
+ edges of the 4-vertex SAFE parallelogram, which are the *shorter* opposite-
118
+ edge family for IW. The rule is order-robust: it handles both the standard
119
+ CDSE `GeoFootprint` vertex order (counter-clockwise) and the clockwise ring
120
+ copied from the CDSE product page, and reduces to the historical
121
+ `dlat = lat(v[1]) - lat(v[0])` rule for the standard order. The pass is
122
+ **turning** (polar turnaround, near-due-west heading of 270 deg) when the
123
+ flight's north component is below 0.3 deg in magnitude.
124
+
125
+ The **uncertainty** is per hemisphere: the p95 of the fit error binned by
126
+ |lat| (degree-4 for |lat| <= 70, piecewise-linear beyond, clamped at the
127
+ measured turning latitudes 84.5 N / 77.5 S). It grows with latitude so that
128
+ users can decide for themselves instead of rejecting high-latitude
129
+ acquisitions.
130
+
131
+ The **incidence / elevation angles** combine two consistent models (verified
132
+ against the ESA / SentiWiki documented angles to <= 0.07 deg):
133
+
134
+ * **Constant slant range** (the CDSE catalogue footprint): the across-track
135
+ ground width W of the 4-vertex ring is a monotonic function of the
136
+ satellite geocentric distance R_s; the catalogue polygon is computed with
137
+ the mean Earth radius (6371 km), so inverting W -> R_s (bisection)
138
+ calibrates the satellite altitude from the footprint alone, with no orbit
139
+ file. In the standard CDSE vertex order (GRDH/GRDM/SLC/OCN) the range lines
140
+ are the v0-v1 (far) and v2-v3 (near) edges, ascending and descending alike;
141
+ rings with a rotated vertex order (e.g. ETA) fall back to the other edge
142
+ pair when the standard width does not invert to a valid orbit altitude.
143
+ * **Off-nadir** (the actual radar steering): with R_s, the WGS84 geocentric
144
+ radius R_e of the reference point and the off-nadir angle sigma (the linear
145
+ roll law between the documented min / max-altitude values per sub-swath),
146
+ the geocentric incidence is the closed form
147
+ `theta_c = asin[(R_s/R_e) * sin(sigma)]`; the local (ellipsoid-normal)
148
+ incidence adds the deflection of the vertical (max ~0.19 deg near
149
+ |lat| = 45 deg) and the elevation is exactly `90 deg - incidence`.
150
+
151
+ The reference point selects sigma through its across-track position
152
+ `dfrac` (0 = near range line, 1 = far range line). Full-swath footprints are
153
+ the supported case; a partial-swath EW footprint whose width does not invert
154
+ to an orbit altitude in the documented 697.6-725.8 km band raises
155
+ `ValueError`.
156
+
157
+ ## Validation
158
+
159
+ Fitted on 13 consecutive days of S1 IW OCN OWI data from all four satellites
160
+ (11107 products, 44428 grid corners; fit window |lat| <= 70 deg, headings
161
+ wrapped to the per-orbit median): ascending n = 4739 residual std 0.30 deg
162
+ (p95 0.64), descending n = 5104 residual std 0.32 deg (p95 0.65).
163
+
164
+ Against the measured OWI heading of the 11107 products: mean |error|
165
+ 0.749 deg, median 0.139 deg, p95 2.90 deg; **98.88 % of the headings fall
166
+ within the returned U(lat)** and 99.96 % within 2 U(lat). In the fitted
167
+ window |lat| <= 70 deg the mean error is 0.14-0.25 deg per latitude band and
168
+ the p95 stays below 1.19 deg.
169
+
170
+ The orbit-direction rule was validated against the `orbitDirection`
171
+ attribute of 66243 CDSE IW/EW rings (13 daily v2 Parquets,
172
+ 2026-11-01..13): **IW 99.70 % and EW 92.05 %** (both unchanged by the
173
+ order-robust rule), **ETA 97.82 %** (the historical dlat rule gave 55.66 %,
174
+ because ETA rings use a rotated vertex order). The remaining EW errors are
175
+ the pre-existing high-latitude ones. The flight direction is two-valued from
176
+ the ring alone (the near/far and start/end corners are unlabeled, a Z2
177
+ symmetry): the rule resolves it for the two documented vertex orders
178
+ (standard CDSE and product-page); a fully reversed ring may be
179
+ misclassified.
180
+
181
+ The angle model was validated on 66243 CDSE IW/EW rings: **98.9 % (IW) and
182
+ 90.8 % (EW) of the products invert an orbit altitude in the documented
183
+ 697.6-725.8 km band**; the off-nadir model reproduces the documented
184
+ per-sub-swath angles to <= 0.07 deg, and the full chain (ring -> W -> R_s ->
185
+ incidence) is simulated to <= 0.11 deg (IW) and <= 0.05 deg (EW) maximum
186
+ error.
187
+
188
+ ## Roadmap
189
+
190
+ - [x] IW ground heading `sar_ground_heading = F(ref_lat, SAR_polygon)` + U(lat)
191
+ - [x] Incidence angle estimator `sar_incidence_angle` (IW + EW)
192
+ - [x] Elevation angle estimator `sar_elevation_angle` (IW + EW)
193
+
194
+ ## Development
195
+
196
+ ```bash
197
+ python -m pip install -e '.[parquet]' pytest pre-commit
198
+ pre-commit run --all-files # ruff + file hygiene
199
+ python -m pytest -q # test suite
200
+ ```
201
+
202
+ GitHub workflows: `CI` (pre-commit + pytest), `Build` (wheel + CLI smoke
203
+ test), `Docs` (sphinx), `Publish` (PyPI on release). Container image:
204
+ `apptainer build s1-geometry.sif apptainer.def`.
@@ -0,0 +1,36 @@
1
+ Bootstrap: docker
2
+ From: python:3.11-slim
3
+
4
+ # Build from a checkout of this repository:
5
+ #
6
+ # apptainer build /tmp/s1-geometry.sif apptainer.def
7
+ #
8
+ # then run it like the console script:
9
+ #
10
+ # apptainer run /tmp/s1-geometry.sif --help
11
+
12
+ %files
13
+ pyproject.toml /opt/s1-geometry/pyproject.toml
14
+ README.md /opt/s1-geometry/README.md
15
+ LICENSE /opt/s1-geometry/LICENSE
16
+ src /opt/s1-geometry/src
17
+
18
+ %post
19
+ python -m pip install --no-cache-dir -e /opt/s1-geometry
20
+
21
+ %environment
22
+ export PYTHONUNBUFFERED=1
23
+
24
+ %runscript
25
+ exec s1-geometry "$@"
26
+
27
+ %labels
28
+ org.soba.tool s1-geometry
29
+ org.soba.description Geometric quantities from a Sentinel-1 SAR footprint
30
+
31
+ %help
32
+ Estimate the ground heading of a Sentinel-1 IW acquisition from its
33
+ SAFE footprint polygon:
34
+
35
+ apptainer run --bind /path/to/footprints:/footprints s1-geometry.sif \
36
+ heading /footprints/footprint.geojson --lat 36.59