Skip to content

Commit 9877a34

Browse files
planet.jeroenclaude
andcommitted
Update README and docs: version 1.26.3, 21 analysis types, all install methods
- Fix version badge (1.26.1 → 1.26.3) and test count (3227 → 3236) - Add feature list below hero image - Add install sections for GitHub Releases wheels and Windows exe - Add humeris --serve as primary viewer launch method - Update analysis dispatch types from 15 to 21 across all docs - Fix getting-started.md install commands for monorepo layout - Update tier2 research paper version references Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent ae4265c commit 9877a34

8 files changed

+120
-25
lines changed

README.md

Lines changed: 85 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,39 @@
11
# Humeris
22

3-
[![Version](https://img.shields.io/badge/version-1.26.1-blue.svg)](packages/core/pyproject.toml) [![Python](https://img.shields.io/badge/python-3.11_%7C_3.12_%7C_3.13-blue.svg)](packages/core/pyproject.toml) [![Tests](https://img.shields.io/badge/tests-3227_passing-brightgreen.svg)](tests/) [![License](https://img.shields.io/badge/license-MIT_(core)-green.svg)](LICENSE) [![License](https://img.shields.io/badge/license-Commercial_(pro)-red.svg)](COMMERCIAL-LICENSE.md) [![Architecture](https://img.shields.io/badge/architecture-hexagonal-purple.svg)](docs/architecture.md)
3+
[![Version](https://img.shields.io/badge/version-1.26.3-blue.svg)](packages/core/pyproject.toml) [![Python](https://img.shields.io/badge/python-3.11_%7C_3.12_%7C_3.13-blue.svg)](packages/core/pyproject.toml) [![Tests](https://img.shields.io/badge/tests-3236_passing-brightgreen.svg)](tests/) [![License](https://img.shields.io/badge/license-MIT_(core)-green.svg)](LICENSE) [![License](https://img.shields.io/badge/license-Commercial_(pro)-red.svg)](COMMERCIAL-LICENSE.md) [![Architecture](https://img.shields.io/badge/architecture-hexagonal-purple.svg)](docs/architecture.md)
44

55
Generate Walker constellation satellite shells and fetch live orbital data for orbit simulation tools.
66

77
![Humeris interactive viewer](docs/interface.png)
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)
2151
pip install humeris-core
@@ -25,15 +55,50 @@ pip install "humeris-core[live]"
2555

2656
# Full suite (core + 66 commercial analysis modules)
2757
pip 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
3085
pip 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")
611676
Launch 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)
621689
python 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)
628696
and 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
632700
CZML 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)
798874
pytest 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

docs/getting-started.md

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,17 @@
99
## Installation
1010

1111
```bash
12-
# Core only (synthetic constellations, no external deps)
13-
pip install .
12+
# Core MIT package (constellation generation, propagation, coverage, export)
13+
pip install humeris-core
1414

1515
# With live CelesTrak / SGP4 support
16-
pip install ".[live]"
16+
pip install "humeris-core[live]"
1717

18-
# Development (includes pytest)
19-
pip install ".[dev]"
18+
# Full suite (core + 66 commercial analysis modules)
19+
pip install humeris-pro
20+
21+
# Development (editable, from repo)
22+
pip install -e ./packages/core -e ./packages/pro
2023
```
2124

2225
## Quick start
@@ -49,6 +52,10 @@ iss = celestrak.fetch_satellites(name="ISS (ZARYA)")
4952
### Launch the interactive viewer
5053

5154
```bash
55+
# Via CLI entry point
56+
humeris --serve
57+
58+
# Or via script directly
5259
python scripts/view_constellation.py --serve
5360
```
5461

@@ -58,7 +65,7 @@ shells and live ISS data. See [Viewer Server](viewer-server.md) for details.
5865
### Run tests
5966

6067
```bash
61-
pytest # 3227 tests, all offline
68+
pytest # 3236 tests, all offline
6269
pytest tests/test_live_data.py # live CelesTrak (requires network)
6370
```
6471

@@ -82,7 +89,7 @@ humeris -i sim.json -o out.json --export-csv sats.csv --export-geojson sats.geoj
8289

8390
- [Simulation JSON](simulation-json.md) — input/output JSON schema
8491
- [Architecture](architecture.md) — hexagonal design, domain purity
85-
- [Viewer Server](viewer-server.md) — interactive 3D viewer with 15 analysis types
92+
- [Viewer Server](viewer-server.md) — interactive 3D viewer with 21 analysis types
8693
- [API Reference](api-reference.md) — HTTP endpoints
8794
- [Integration Guide](integration-guide.md) — CelesTrak, CesiumJS, custom sources, reproducibility
8895
- [Export Formats](export-formats.md) — CSV, GeoJSON, CZML output

docs/papers/tier2/tier2_06_network_sir_cascade.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
**Authors**: Humeris Research
44
**Status**: Tier 2 -- Validated Conceptually, Not Yet Implemented
55
**Date**: February 2026
6-
**Library Version**: Humeris v1.26.1
6+
**Library Version**: Humeris v1.26.3
77

88
---
99

docs/papers/tier2/tier2_07_hamiltonian_fisher_rao.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
**Authors**: Humeris Research
44
**Status**: Tier 2 -- Validated Conceptually, Not Yet Implemented
55
**Date**: February 2026
6-
**Library Version**: Humeris v1.26.1
6+
**Library Version**: Humeris v1.26.3
77

88
---
99

docs/papers/tier2/tier2_08_surface_code_coverage.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
**Authors**: Humeris Research
44
**Status**: Tier 2 -- Validated Conceptually, Not Yet Implemented
55
**Date**: February 2026
6-
**Library Version**: Humeris v1.26.1
6+
**Library Version**: Humeris v1.26.3
77

88
---
99

docs/papers/tier2/tier2_09_percolation_debris_coupled.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
**Authors**: Humeris Research
44
**Status**: Tier 2 -- Validated Conceptually, Not Yet Implemented
55
**Date**: February 2026
6-
**Library Version**: Humeris v1.26.1
6+
**Library Version**: Humeris v1.26.3
77

88
---
99

docs/papers/tier2/tier2_10_bayesian_intent_estimation.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
**Authors**: Humeris Research
44
**Status**: Tier 2 -- Validated Conceptually, Not Yet Implemented
55
**Date**: February 2026
6-
**Library Version**: Humeris v1.26.1
6+
**Library Version**: Humeris v1.26.3
77

88
---
99

docs/viewer-server.md

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,21 @@
44

55
The viewer server provides a browser-based 3D visualization of satellite
66
constellations using CesiumJS. It runs a local HTTP server that serves a
7-
Cesium globe and generates CZML data on demand for 15 analysis layer types.
7+
Cesium globe and generates CZML data on demand for 21 analysis layer types.
88

99
## Launching
1010

1111
### Server mode (interactive)
1212

1313
```bash
14-
# Default port 8765
15-
python scripts/view_constellation.py --serve
14+
# Via CLI entry point
15+
humeris --serve
1616

1717
# Custom port
18+
humeris --serve --port 9000
19+
20+
# Or via script directly
21+
python scripts/view_constellation.py --serve
1822
python scripts/view_constellation.py --serve --port 9000
1923
```
2024

@@ -48,7 +52,7 @@ Plus live ISS data from CelesTrak (animated track).
4852

4953
## Analysis layer types
5054

51-
The viewer dispatches 15 analysis types via `_generate_czml()`. Each uses
55+
The viewer dispatches 21 analysis types via `_generate_czml()`. Each uses
5256
sensible defaults that can be overridden via the `params` dict in the API.
5357

5458
### Core layers
@@ -80,6 +84,14 @@ sensible defaults that can be overridden via the `params` dict in the API.
8084
| `conjunction` | Two-satellite close approach replay with proximity line | states[0] vs states[n/2], ±30 min, 10s step |
8185
| `kessler_heatmap` | Altitude × inclination debris density heatmap | 200-2000 km, 0-180°, 50 km × 10° bins |
8286
| `conjunction_hazard` | Conjunction screening with NASA-STD-8719.14 hazard levels | 2h window, 100 km threshold, ROUTINE/WARNING/CRITICAL coloring |
87+
| `dop_grid` | Ground heatmap colored by dilution of precision | 10° grid |
88+
| `radiation` | Satellites colored by radiation environment | 2h duration, 60s step |
89+
| `beta_angle` | Satellites colored by solar beta angle | Snapshot |
90+
| `deorbit` | Satellites colored by deorbit compliance status | Cd=2.2, A=0.01 m², m=4 kg |
91+
| `station_keeping` | Satellites colored by station-keeping ΔV budget | Cd=2.2, A=0.01 m², m=4 kg |
92+
| `cascade_sir` | SIR epidemic cascade debris evolution | 2h duration, 60s step |
93+
| `relative_motion` | Relative motion trajectory between two satellites | states[0] vs states[1], 2h duration |
94+
| `maintenance` | Satellites colored by maintenance schedule status | Cd=2.2, A=0.01 m², m=4 kg |
8395

8496
## Default configurations
8597

0 commit comments

Comments
 (0)