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.
- s1_geometry-0.2.0/.github/workflows/build.yml +22 -0
- s1_geometry-0.2.0/.github/workflows/ci.yml +22 -0
- s1_geometry-0.2.0/.github/workflows/docs.yml +21 -0
- s1_geometry-0.2.0/.github/workflows/publish.yml +21 -0
- s1_geometry-0.2.0/.gitignore +16 -0
- s1_geometry-0.2.0/.pre-commit-config.yaml +28 -0
- s1_geometry-0.2.0/.readthedocs.yaml +23 -0
- s1_geometry-0.2.0/AGENTS.md +22 -0
- s1_geometry-0.2.0/LICENSE +21 -0
- s1_geometry-0.2.0/PKG-INFO +226 -0
- s1_geometry-0.2.0/README.md +204 -0
- s1_geometry-0.2.0/apptainer.def +36 -0
- s1_geometry-0.2.0/docs/Makefile +20 -0
- s1_geometry-0.2.0/docs/_static/certification/ew_asc.png +0 -0
- s1_geometry-0.2.0/docs/_static/certification/ew_desc.png +0 -0
- s1_geometry-0.2.0/docs/_static/certification/iw_asc.png +0 -0
- s1_geometry-0.2.0/docs/_static/certification/iw_desc.png +0 -0
- s1_geometry-0.2.0/docs/_static/certification/sm_asc.png +0 -0
- s1_geometry-0.2.0/docs/_static/certification/sm_desc.png +0 -0
- s1_geometry-0.2.0/docs/_static/certification/stats.json +168 -0
- s1_geometry-0.2.0/docs/_static/certification/wv_asc.png +0 -0
- s1_geometry-0.2.0/docs/_static/certification/wv_desc.png +0 -0
- s1_geometry-0.2.0/docs/_static/figures/error_vs_lat.png +0 -0
- s1_geometry-0.2.0/docs/_static/figures/ew_example.png +0 -0
- s1_geometry-0.2.0/docs/_static/figures/iw_example.png +0 -0
- s1_geometry-0.2.0/docs/_static/figures/sm_example.png +0 -0
- s1_geometry-0.2.0/docs/_static/figures/wv_example.png +0 -0
- s1_geometry-0.2.0/docs/api/s1_geometry.angles.rst +5 -0
- s1_geometry-0.2.0/docs/api/s1_geometry.cli.rst +5 -0
- s1_geometry-0.2.0/docs/api/s1_geometry.footprint.rst +5 -0
- s1_geometry-0.2.0/docs/api/s1_geometry.geometry.rst +5 -0
- s1_geometry-0.2.0/docs/api/s1_geometry.heading.rst +5 -0
- s1_geometry-0.2.0/docs/api/s1_geometry.rst +21 -0
- s1_geometry-0.2.0/docs/api/s1_geometry.wv.rst +5 -0
- s1_geometry-0.2.0/docs/certification.rst +187 -0
- s1_geometry-0.2.0/docs/conf.py +26 -0
- s1_geometry-0.2.0/docs/figures.rst +109 -0
- s1_geometry-0.2.0/docs/index.rst +58 -0
- s1_geometry-0.2.0/docs/usage.rst +163 -0
- s1_geometry-0.2.0/examples/data/s1_sample_footprints.parquet +0 -0
- s1_geometry-0.2.0/examples/heading_from_footprint.py +41 -0
- s1_geometry-0.2.0/examples/incidence_elevation_end2end.py +90 -0
- s1_geometry-0.2.0/pyproject.toml +46 -0
- s1_geometry-0.2.0/src/s1_geometry/__init__.py +93 -0
- s1_geometry-0.2.0/src/s1_geometry/angles.py +648 -0
- s1_geometry-0.2.0/src/s1_geometry/cli.py +156 -0
- s1_geometry-0.2.0/src/s1_geometry/footprint.py +336 -0
- s1_geometry-0.2.0/src/s1_geometry/geometry.py +130 -0
- s1_geometry-0.2.0/src/s1_geometry/heading.py +151 -0
- s1_geometry-0.2.0/src/s1_geometry/wv.py +339 -0
- s1_geometry-0.2.0/tests/__init__.py +1 -0
- s1_geometry-0.2.0/tests/rings.py +78 -0
- s1_geometry-0.2.0/tests/test_angles.py +426 -0
- s1_geometry-0.2.0/tests/test_cli.py +102 -0
- s1_geometry-0.2.0/tests/test_footprint.py +152 -0
- s1_geometry-0.2.0/tests/test_geometry.py +106 -0
- s1_geometry-0.2.0/tests/test_heading.py +91 -0
- 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
|