Metadata-Version: 2.4
Name: gdar-orbit
Version: 1.2.0.post2
Summary: GDAR-ORBIT - satellite orbits for GDAR
Author-email: Geir Engen <geen@norceresearch.no>, Yngvar Larsen <ynla@norceresearch.no>, Tom Grydeland <tgry@norceresearch.no>, Heidi Hindberg <hehi@norceresearch.no>, Jakob Grahn <jgra@norceresearch.no>, Daniel Johansen Trosten <dtro@norceresearch.no>, Temesgen Gebrie Yitayew <teyi@norceresearch.no>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: InSAR,SAR,geospatial,raster,remote-sensing,satellite-orbits
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Requires-Dist: gdar-base>=1.2.0
Requires-Dist: numpy-quaternion>=2023.0.0
Provides-Extra: interactive
Requires-Dist: gdar-base[interactive]; extra == 'interactive'
Requires-Dist: ipython; extra == 'interactive'
Provides-Extra: plotting
Requires-Dist: gdar-base[plotting]; extra == 'plotting'
Requires-Dist: matplotlib; extra == 'plotting'
Description-Content-Type: text/markdown

# gdar-orbit

Satellite orbit and attitude handling for the GDAR processing framework.
Part of the OpenGDAR family of packages. Requires `gdar-base`.

## Modules

### `gdar.orbit.orbit` -- Orbit interpolation and SAR geocoding

Core orbit classes built on Legendre polynomial interpolation of
statevectors (ECEF position + velocity):

- **`Sampled_orbit`** -- primary orbit class, constructed from a sequence
  of uniformly sampled statevectors.
- **`EllipsoidOrbit`** -- base class providing SAR geocoding methods.
- **`GbradarOrbit`** -- orbit representation for ground-based radar.

Key geocoding methods (on `EllipsoidOrbit`):

| Method | Description |
|---|---|
| `sar2xyz()` | SAR coordinates (azimuth time, range) to ECEF XYZ |
| `sar2geo()` | SAR coordinates to geographic (lat, lon, height) |
| `xyz2sar()` | ECEF XYZ to SAR coordinates |
| `geo2sar()` | Geographic coordinates to SAR coordinates |
| `sar2geometry()` | Full geometry recarray (incidence angle, look angle, etc.) |

Utilities:

- `canonical_svec()` -- convert various statevector formats to the
  standard recarray dtype.
- `merge_trajectories()` -- merge overlapping orbit segments.
- `replicate_vector()` -- broadcast a vector to match a position array.

### `gdar.orbit.attitude` -- Quaternion-based attitude

Satellite attitude as unit quaternions with SLERP interpolation:

- **`Attitude`** -- stores uniformly sampled quaternions, interpolates to
  arbitrary times.  Quaternions represent the rotation from the GDAR
  body-fixed frame to ITRF.
- **`zero_doppler_steering()`** -- compute attitude quaternions for
  zero-Doppler steering (boresight perpendicular to velocity).  Supports
  a roll parameter: positive roll points the boresight left of the ground
  track, negative roll points right.
- `pt_from_azel()` -- azimuth/elevation angles to unit pointing vector.
- `quat_as_tait_bryan_angles()` -- quaternion to roll/pitch/yaw.

Body-fixed frame convention:

- **x** -- forward (velocity direction)
- **y** -- completes right-handed system (approximately cross-track right)
- **z** -- boresight (nadir at zero roll)

### `gdar.orbit.frame_transformations` -- Coordinate frame transforms

Statevector-level transformations between standard reference frames.
Rotation matrices come from `gdar.base.coordinates` (ERFA / IAU 2006);
this module wraps them to operate on statevector recarrays and applies
velocity corrections where needed.

Available transforms (each function takes and returns a statevector):

- ITRS <-> GCRS
- ITRS <-> True of Date (via GCRS)
- ITRS <-> GM2000 / EME2000 / J2000.0 (via GCRS)
- ToD <-> TIRS (with Earth-rotation velocity correction)

## Installation

Install from PyPI:

```bash
pip install gdar-orbit
```

or with [uv](https://docs.astral.sh/uv/):

```bash
uv pip install gdar-orbit
```

Dependencies (including `gdar-base`) are installed automatically.

## Testing

```
pytest tests/
```

Three tests in `test_attitude.py` require `gdar-sar` and will be skipped
if it is not installed.

## Development

### Internal links

- [GDAR wiki](https://gitlab.norceresearch.no/earth-observation/wiki/-/wikis/0_home) — central documentation hub
- [OpenGDAR API Reference](https://earth-observation.pages.norce.dev/opengdar/docs/opengdar) — auto-generated from docstrings
- [Release schedule](https://gitlab.norceresearch.no/earth-observation/wiki/-/wikis/Deployment-&-Maintenance/Release-schedule)

## License

This project is licensed under the Apache License, Version 2.0.
You may obtain a copy of the license at
<https://www.apache.org/licenses/LICENSE-2.0> or in the
[LICENSE](./LICENSE) file distributed with this source.

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
either express or implied.  See the License for the specific
language governing permissions and limitations under the License.

