orbisim

Orbital mechanics sandbox for planning and visualizing trajectories with multiple burns.

Now includes a local web app UI (default) plus the original Tkinter UI.

Quickstart

Requires Python 3.10+ and a virtual environment.

python -m venv .venv
./.venv/bin/python -m pip install -U pip
./.venv/bin/python -m pip install -e .
./.venv/bin/python -m orbisim

If you see Defaulting to user installation because normal site-packages is not writeable, you are not using the venv Python; use ./.venv/bin/python ... as shown above (or source .venv/bin/activate).

Web UI (default)

Start the server (it serves a single-file web UI), then open the printed URL:

./.venv/bin/python -m orbisim --host 127.0.0.1 --port 8000

Or (same idea, plus venv bootstrap):

./run.sh --host 127.0.0.1 --port 8000

Or using Flask’s built-in runner:

export FLASK_APP=orbisim.web.server:app
flask run --host 127.0.0.1 --port 8000

Controls:

• Starts paused; press p to toggle time pause/resume.
• Mouse drag rotates; mouse wheel zooms.
• , slows time; . speeds time (warp shown in the left panel and HUD).
• Code editor + Lisp-ish REPL drive navigation; define plans with (flightplan ...), queue them with (execute ...), then click “Run Code”.

Multiplayer-first Branch (Experimental)

On the multiplayer-first branch:

• Warp controls are disabled; simulation runs at a fixed accelerated rate (TIME_SCALE in orbisim/web/static/index.html).
• The web server is now a Flask app and exposes a simple multiplayer relay API (host/browser sim publishes snapshots; clients subscribe via SSE).

Run the server:

./.venv/bin/python -m orbisim --host 0.0.0.0 --port 8000

Open the URL in two browser windows:

• First window becomes host (runs simulation).
• Later windows become clients (render host state; arrow keys control the assigned craft).

Tutorial + Example Scripts

• In-app: click Keys (or press ?) for controls/commands, and Tutorial for a quick walkthrough.
• Repo docs: docs/TUTORIAL.md
• Example script: scenarios/lunly_crash.orbi (load via (load-script) in the REPL)

Tkinter UI (legacy)

./.venv/bin/python -m orbisim.ui.app

What It Does (MVP)

• Runs a local single-file web app for a code-driven space navigation sandbox.
• Simulates multiple crafts under gravity from system bodies (craft-craft gravity ignored).
• Executes flightplans as timed events (point/lock/burn/dock) via an embedded Lisp-ish language.

About SPICE (High Accuracy Ephemerides)

Orbital planning quality depends heavily on where bodies are (ephemerides) and how frames/orientations are defined.

Using SPICE kernels (via spiceypy) provides:

• More accurate body positions/velocities than simple analytic Keplerian elements
• Better encounter timing/geometry for interplanetary transfers
• Access to well-defined reference frames and body orientations (useful for surface targets)

Tradeoffs:

• Users must download kernels and keep them available locally (large files).
• The app needs a kernel management setup (data/kernels/) and an ephemeris selection toggle.

This repository currently ships with an analytic ephemeris for the Kerbol system; SPICE mode is planned.