Metadata-Version: 2.4
Name: nstk
Version: 0.1.3
Summary: Nebula Space Toolkit (nstk) for space systems engineering and analysis.
Author-email: Nathan Spencer <nathanss1997@gmail.com>
License: Apache 2.0
License-File: LICENSE
Keywords: astrodynamics,coverage,orbit,orekit,satellite,space,systems-engineering
Classifier: Development Status :: 3 - Alpha
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: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.6
Requires-Dist: nstk-data>=0.1.0
Requires-Dist: numba>=0.59.0
Requires-Dist: numpy>=1.22
Requires-Dist: pyshp>=2.3
Requires-Dist: rasterio>=1.3
Requires-Dist: shapely>=2.0
Provides-Extra: all
Requires-Dist: astropy>=5.0; extra == 'all'
Requires-Dist: cartopy>=0.21; extra == 'all'
Requires-Dist: orekit-jpype[jdk4py]>=11.0.2; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'all'
Provides-Extra: plotting
Requires-Dist: cartopy>=0.21; extra == 'plotting'
Provides-Extra: propagation
Requires-Dist: astropy>=5.0; extra == 'propagation'
Requires-Dist: orekit-jpype[jdk4py]>=11.0.2; extra == 'propagation'
Provides-Extra: test
Requires-Dist: astropy>=5.0; extra == 'test'
Requires-Dist: cartopy>=0.21; extra == 'test'
Requires-Dist: orekit-jpype[jdk4py]>=11.0.2; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'test'
Description-Content-Type: text/markdown

# Nebula Space Toolkit

`nstk` is the Python package for Nebula Space Toolkit, a library for space
systems engineering and analysis. It is designed for users who need reusable
building blocks for orbit propagation, coordinate transforms, geometry,
coverage analysis, localization workflows, and mission-oriented plotting.

## What NSTK Provides

- Orbit construction and propagation interfaces built around Orekit
- Coordinate and frame transforms for common astrodynamics workflows
- Coverage and access analysis utilities
- Line-of-sight, terrain, and other geometric analysis tools
- Localization and measurement helpers for angle, time-difference, and
  frequency-difference studies
- 2D and 3D plotting tools for orbits and geospatial views

## Package Layout

The top-level package is organized into the following modules:

- `nstk.propagation`: orbit creation, propagation, and Walker constellations
- `nstk.transforms`: geodetic, ECEF, ENU, AER, and timed frame transforms
- `nstk.geometry`: line-of-sight, terrain, raster-mask, and sun-position tools
- `nstk.coverage`: interval and fixed-step coverage analysis
- `nstk.localization`: measurement models and localization helpers
- `nstk.plotting`: basemaps and orbit visualization
- `nstk.time_utils`: shared Orekit and Astropy time conversion helpers

## Installation

Install the base package with:

```bash
pip install nstk
```

The base install includes the core package plus the offline data dependency
`nstk-data`.

Optional extras are available for heavier workflows:

```bash
pip install "nstk[propagation]"
pip install "nstk[plotting]"
pip install "nstk[all]"
```

Extras are intended for:

- `propagation`: Orekit-backed propagation and timed frame operations
- `plotting`: Cartopy and related geospatial plotting support
- `all`: all optional dependencies used by the project

## Installing From Source

For local development, install from the repository root:

```bash
python -m pip install -e .
```

To include optional features during development:

```bash
python -m pip install -e ".[propagation]"
python -m pip install -e ".[plotting]"
python -m pip install -e ".[all]"
```

If Orekit-backed features later report that `nstk-data` is missing, install it
into the same environment as `nstk` and your Jupyter kernel:

```bash
python -m pip install nstk-data
```

## Data and Runtime Behavior

Nebula Space Toolkit uses the separate `nstk-data` package for bundled Orekit
and Cartopy assets. This keeps the code package smaller and allows data updates
to be managed independently.

Orekit-backed features initialize lazily on first use. Most users do not need
to do anything beyond installing the appropriate extra.

If you want one simple top-level setup call for Orekit plus NSTK's bundled
offline Cartopy assets, initialize the runtime once near the top of your
script or notebook:

```python
import nstk

nstk.initialize()
```

For fully offline-friendly workflows, disable Astropy IERS downloads and relax
its IERS age checks through the same entry point:

```python
import nstk

nstk.initialize(offline=True)
```

If you want to use custom data directories instead of the bundled
`nstk-data` package, pass them explicitly:

```python
import nstk

nstk.initialize(
    orekit_data_path="/path/to/orekit-data",
    cartopy_data_path="/path/to/cartopy-data",
)
```

For Orekit-only advanced workflows, the lower-level helpers
`nstk.initialize_orekit(...)` and `nstk.set_orekit_data_path(...)` remain
available.

## Minimal Example

The example below shows a simple Orekit-backed orbit workflow:

```python
import nstk
nstk.initialize()

from astropy.time import Time
from nstk.propagation import Orbit, build_two_body_propagator

propagator = build_two_body_propagator(
    epoch=Time("2026-01-01T00:00:00", scale="utc"),
    a=7000e3,
    e=0.001,
    i=0.9,
    raan=0.1,
    argp=0.2,
    anomaly=0.3,
    anomaly_type="mean",
    inertial_frame="gcrf",
)
orbit = Orbit(propagator)

position_m = orbit.get_position(0.0, frame="gcrf")
print(position_m)
```

This example requires the `propagation` extra.

## Orbit Attitude Defaults

NSTK orbit propagators default to `attitude="vvlh"`, which is implemented as
Orekit `LofOffset(native_frame, LOFType.VVLH)`. This is a reasonable default
for a general Earth-observing satellite because it keeps the spacecraft body in
a local orbital, nadir-pointing attitude law.

Supported local-orbital attitude names include:

- `vvlh` and `lvlh_ccsds` for the CCSDS-style local orbital frame family
- `lvlh` and `qsw` for Orekit's STK/Vallado-style LVLH family
- `tnw`, `ntw`, `vnc`, `eqw`, `enu`, and `ned` for other built-in Orekit
  local orbital frames

You can also pass an Orekit `LOFType`, a prebuilt Orekit `AttitudeProvider`,
or one of NSTK's attitude-provider helpers through `attitude_provider=` on a
propagator factory, and later swap the installed provider with
`Orbit.set_attitude_provider(...)`.

## Examples

Additional usage examples are provided in the `examples/` directory, including:

- orbit usage
- orbit attitude configuration
- transforms
- Walker constellations
- interval coverage

## Project Identity

- Brand name: `Nebula Space Toolkit`
- PyPI package: `nstk`
- Python import: `import nstk`


## Attribution

NSTK is a part of Nebula Space Systems
