Skip to content

Latest commit

 

History

History
215 lines (156 loc) · 6.6 KB

getting-started.md

File metadata and controls

215 lines (156 loc) · 6.6 KB

Getting Started

Requirements

  • Python 3.11+
  • NumPy >= 1.24 (hard dependency)
  • sgp4>=2.22 for live CelesTrak data (optional)

Platforms: Linux, macOS, Windows (pure Python, no compiled extensions).

Installation

From PyPI

# Core MIT package (constellation generation, propagation, coverage, export)
pip install humeris-core

# With live CelesTrak / SGP4 support
pip install "humeris-core[live]"

# Full suite (core + 71 commercial analysis modules)
pip install humeris-pro

From GitHub Releases

Download .whl files from the Releases page:

pip install humeris_core-1.28.1-py3-none-any.whl
pip install humeris_pro-1.28.1-py3-none-any.whl

Windows executable

Download humeris-windows-x64.zip from Releases, extract, and run:

humeris.exe generate -i simulation.json -o output.json
humeris.exe serve

No Python installation required.

Development (from source)

git clone https://github.com/pljeroen/humeris.git
cd humeris
pip install -e ./packages/core -e ./packages/pro

Quick start

Generate a Walker shell

from humeris.domain.constellation import ShellConfig, generate_walker_shell

shell = ShellConfig(
    altitude_km=550, inclination_deg=53,
    num_planes=10, sats_per_plane=20,
    phase_factor=1, raan_offset_deg=0,
    shell_name="LEO-550",
)
satellites = generate_walker_shell(shell)
print(f"Generated {len(satellites)} satellites")

Fetch live data

from humeris.adapters.celestrak import CelesTrakAdapter

celestrak = CelesTrakAdapter()
gps = celestrak.fetch_satellites(group="GPS-OPS")
iss = celestrak.fetch_satellites(name="ISS (ZARYA)")

Launch the interactive viewer

humeris serve
humeris serve --port 9000

Opens a Cesium 3D globe at http://localhost:8765 with pre-loaded Walker shells and live ISS data. See Viewer Server for details.

Run tests

pytest                          # 3487 tests, all offline
pytest tests/test_live_data.py  # live CelesTrak (requires network)

CLI reference

Subcommands

humeris serve                    # interactive 3D viewer
humeris generate -i ... -o ...   # constellation generation + export
humeris import opm FILE          # CCSDS OPM import
humeris import oem FILE          # CCSDS OEM import
humeris sweep --param ... -o ... # parameter sweep
humeris --version                # show version

Generate: synthetic constellations

# Default: 3 Walker shells + SSO band
humeris generate -i simulation_old.json -o simulation.json

# Custom base ID
humeris generate -i sim_old.json -o sim.json --base-id 200

Generate: live data from CelesTrak

# Real GPS constellation (32 satellites)
humeris generate -i sim.json -o out.json --live-group GPS-OPS

# All Starlink satellites (~6000+) with concurrent SGP4 propagation
humeris generate -i sim.json -o out.json --live-group STARLINK --concurrent

# Search by name
humeris generate -i sim.json -o out.json --live-name "ISS (ZARYA)"

# By NORAD catalog number
humeris generate -i sim.json -o out.json --live-catnr 25544

Available CelesTrak groups

STATIONS, GPS-OPS, STARLINK, ONEWEB, ACTIVE, WEATHER, GALILEO, BEIDOU, IRIDIUM-NEXT, PLANET, SPIRE, GEO, INTELSAT, SES, TELESAT, AMATEUR, SCIENCE, NOAA, GOES

Generate: export formats

Export satellite positions as geodetic coordinates (lat/lon/alt) alongside the simulation JSON:

# CSV export
humeris generate -i sim.json -o out.json --export-csv satellites.csv

# GeoJSON export
humeris generate -i sim.json -o out.json --export-geojson satellites.geojson

# Both at once
humeris generate -i sim.json -o out.json --export-csv sats.csv --export-geojson sats.geojson

CSV columns: name, lat_deg, lon_deg, alt_km, epoch, plane_index, sat_index, raan_deg, true_anomaly_deg, altitude_km, inclination_deg, orbital_period_min, beta_angle_deg, atmospheric_density_kg_m3, l_shell.

GeoJSON produces a FeatureCollection with Point geometries. Coordinates follow the GeoJSON spec: [longitude, latitude, altitude_km]. Properties include the same orbital analysis fields as CSV.

Generate: simulator exports

Export directly to 3D space simulators, game engines, and planetarium software:

humeris generate -i sim.json -o out.json --export-celestia sats.ssc      # Celestia
humeris generate -i sim.json -o out.json --export-kml sats.kml            # Google Earth
humeris generate -i sim.json -o out.json --export-tle sats.tle            # Stellarium / STK / GMAT
humeris generate -i sim.json -o out.json --export-blender sats.py         # Blender
humeris generate -i sim.json -o out.json --export-spaceengine sats.sc     # SpaceEngine
humeris generate -i sim.json -o out.json --export-ksp sats.sfs            # Kerbal Space Program
humeris generate -i sim.json -o out.json --export-ubox sats.ubox          # Universe Sandbox

Optional visual layer flags:

--no-orbits          # Omit orbit path lines from KML and Blender exports
--kml-planes         # Organize KML by orbital plane folders
--kml-isl            # Include ISL topology lines in KML export
--blender-colors     # Color-code satellites by orbital plane in Blender export

All exporters include orbital analysis data (altitude, inclination, period, beta angle, atmospheric density, L-shell). See Simulator Integrations for setup instructions per tool.

Default shell configuration

Shell Altitude Inclination Planes x Sats Phase Factor
LEO-Shell500 500 km 30 22 x 72 17
LEO-Shell450 450 km 30 22 x 72 17
LEO-Shell400 400 km 30 22 x 72 17
SSO Band 525-2200 km (50 km step) SSO-computed 1 x 72 0

Next steps