11# Humeris
22
3- [](packages/core/pyproject.toml) [](packages/core/pyproject.toml) [](tests/) [-green.svg)](LICENSE) [-red.svg)](COMMERCIAL-LICENSE.md) [](docs/architecture.md)
3+ [](packages/core/pyproject.toml) [](packages/core/pyproject.toml) [](tests/) [-green.svg)](LICENSE) [-red.svg)](COMMERCIAL-LICENSE.md) [](docs/architecture.md)
44
55Generate Walker constellation satellite shells and fetch live orbital data for orbit simulation tools.
66
77
88
9+ ### Capabilities
10+
11+ - Walker constellation generation with configurable shells
12+ - Live satellite data from CelesTrak (TLE/OMM, SGP4 propagation)
13+ - Keplerian, J2/J3 secular, and RK4/Dormand-Prince numerical propagation
14+ - Pluggable perturbation forces (drag, SRP, third-body, relativistic, tidal, albedo)
15+ - NRLMSISE-00 atmosphere model with solar cycle prediction
16+ - Coordinate frames (ECI, ECEF, geodetic, topocentric)
17+ - Coverage analysis and revisit time computation
18+ - Access window prediction
19+ - Eclipse prediction and beta angle analysis
20+ - Conjunction screening and collision probability
21+ - Orbit design (sun-synchronous, frozen, repeat ground track)
22+ - Trade studies with Pareto optimization
23+ - Maneuver planning (Hohmann, bi-elliptic, plane change)
24+ - Orbit lifetime and deorbit compliance assessment
25+ - Station-keeping delta-V budgets
26+ - Inter-satellite links and link budget analysis
27+ - Network topology analysis (Hodge Laplacian, spectral)
28+ - Orbit determination (EKF) and maneuver detection (CUSUM/EWMA)
29+ - Hazard reporting (NASA-STD-8719.14)
30+ - Kessler cascade and debris density modeling
31+ - High-fidelity time systems (UTC/TAI/TT/TDB/GPS)
32+ - IAU 2006 precession, IAU 2000B nutation, planetary ephemeris
33+ - Relativistic and tidal force models
34+ - Interactive 3D CesiumJS viewer with 21 analysis types
35+ - Export to CSV, GeoJSON, CZML, KML, Celestia, Blender, SpaceEngine, KSP, Universe Sandbox, Stellarium
36+
937> **Disclaimer**: This library provides computational models for educational,
1038> research, and engineering analysis purposes. It is **not certified** for
1139> operational mission planning, safety-of-flight decisions, or regulatory
@@ -16,6 +44,8 @@ Generate Walker constellation satellite shells and fetch live orbital data for o
1644
1745## Install
1846
47+ ### From PyPI
48+
1949```bash
2050# Core MIT package (constellation generation, propagation, coverage, export)
2151pip install humeris-core
@@ -25,15 +55,50 @@ pip install "humeris-core[live]"
2555
2656# Full suite (core + 66 commercial analysis modules)
2757pip install humeris-pro
58+ ```
59+
60+ ### From GitHub Releases
61+
62+ Download `.whl` files from the [Releases](https://github.com/pljeroen/humeris/releases) page:
63+
64+ ```bash
65+ pip install humeris_core-1.26.3-py3-none-any.whl
66+ pip install humeris_pro-1.26.3-py3-none-any.whl
67+ ```
68+
69+ ### Windows executable
70+
71+ Download `humeris-windows-x64.zip` from [Releases](https://github.com/pljeroen/humeris/releases), extract, and run:
72+
73+ ```
74+ humeris.exe -i simulation.json -o output.json
75+ humeris.exe --serve
76+ ```
2877
29- # Development (editable, from repo)
78+ No Python installation required.
79+
80+ ### Development (from source)
81+
82+ ```bash
83+ git clone https://github.com/pljeroen/humeris.git
84+ cd humeris
3085pip install -e ./packages/core -e ./packages/pro
3186```
3287
3388**Python**: 3.11, 3.12, 3.13. **Platforms**: Linux, macOS, Windows (pure Python, no compiled extensions).
3489
3590## Usage
3691
92+ ### Interactive 3D viewer
93+
94+ ```bash
95+ # Launch viewer server (opens browser at http://localhost:8765)
96+ humeris --serve
97+
98+ # Custom port
99+ humeris --serve --port 9000
100+ ```
101+
37102### Synthetic constellations (Walker shells)
38103
39104```bash
@@ -611,11 +676,14 @@ write_czml(cov_packets, "coverage.czml")
611676Launch an interactive 3D viewer with on-demand analysis layers:
612677
613678```bash
614- # Interactive server mode (opens browser)
615- python scripts/view_constellation.py --serve
679+ # Interactive server mode via CLI (opens browser)
680+ humeris --serve
616681
617682# Custom port
618- python scripts/view_constellation.py --serve --port 9000
683+ humeris --serve --port 9000
684+
685+ # Or via script directly
686+ python scripts/view_constellation.py --serve
619687
620688# Static HTML mode (generates constellation_viewer.html, no server needed)
621689python scripts/view_constellation.py
@@ -626,14 +694,14 @@ python scripts/view_constellation.py --open
626694
627695**Server mode** pre-loads three Walker shells (500/450/400 km, 1584 sats each)
628696and live ISS data from CelesTrak. The browser UI supports adding/removing
629- constellations, ground stations, and 15 analysis layer types via the API.
697+ constellations, ground stations, and 21 analysis layer types via the API.
630698
631699**Static mode** generates a self-contained HTML file (~10 MB) with baked-in
632700CZML data. No server required — just open the file in a browser.
633701
634702##### Analysis layer types
635703
636- The viewer dispatches 15 analysis types, each with sensible defaults:
704+ The viewer dispatches 21 analysis types, each with sensible defaults:
637705
638706| Type | Visualization | Default parameters |
639707|------|---------------|--------------------|
@@ -650,6 +718,14 @@ The viewer dispatches 15 analysis types, each with sensible defaults:
650718| `conjunction` | Two-satellite close approach replay with proximity line | states[0] vs states[n/2], ±30 min window, 10s step |
651719| `kessler_heatmap` | Altitude × inclination debris density grid | 200-2000 km, 0-180°, 50 km × 10° bins |
652720| `conjunction_hazard` | Conjunction screening with NASA-STD-8719.14 hazard levels | 2h window, 100 km threshold, color by ROUTINE/WARNING/CRITICAL |
721+ | `dop_grid` | Ground heatmap colored by dilution of precision | 10° grid |
722+ | `radiation` | Satellites colored by radiation environment | 2h duration, 60s step |
723+ | `beta_angle` | Satellites colored by solar beta angle | Snapshot |
724+ | `deorbit` | Satellites colored by deorbit compliance status | Cd=2.2, A=0.01 m², m=4 kg |
725+ | `station_keeping` | Satellites colored by station-keeping ΔV budget | Cd=2.2, A=0.01 m², m=4 kg |
726+ | `cascade_sir` | SIR epidemic cascade debris evolution | 2h duration, 60s step |
727+ | `relative_motion` | Relative motion trajectory between two satellites | states[0] vs states[1], 2h duration |
728+ | `maintenance` | Satellites colored by maintenance schedule status | Cd=2.2, A=0.01 m², m=4 kg |
653729| `ground_station` | Station marker + visibility circle + access tracks | 10° min elevation |
654730
655731##### Default RF link configuration (Ka-band)
@@ -794,7 +870,7 @@ port interfaces.
794870## Tests
795871
796872```bash
797- pytest # all 3227 tests (offline, no network required)
873+ pytest # all 3236 tests (offline, no network required)
798874pytest tests/test_live_data.py # live CelesTrak tests (requires network)
799875```
800876
@@ -865,7 +941,7 @@ results without network access.
865941- [Getting Started](docs/getting-started.md) — installation, quickstart, CLI
866942- [Simulation JSON](docs/simulation-json.md) — input/output JSON schema
867943- [Architecture](docs/architecture.md) — hexagonal design, module categories
868- - [Viewer Server](docs/viewer-server.md) — interactive 3D viewer, 15 analysis types
944+ - [Viewer Server](docs/viewer-server.md) — interactive 3D viewer, 21 analysis types
869945- [API Reference](docs/api-reference.md) — HTTP endpoints
870946- [Integration Guide](docs/integration-guide.md) — CelesTrak, CesiumJS, custom sources
871947- [Export Formats](docs/export-formats.md) — CSV, GeoJSON, CZML
0 commit comments