Hypersphere guide

The workstation

The Scene fills the window, and the workstation’s panels float over it as glass cards: Objects on the left, the Overview and the Inspector on the right, Events and the Timeline below. Every view reads the same mission from the engine and shares one selection and one clock, so selecting an object or an event anywhere moves all of them.

Title bar and modes

The title bar holds four modes, which lay the workstation out for a task: Analysis (Objects, the Overview and Events around the Scene), Events, Reports and Scene, which hides the panels for an immersive view with only the Scene’s own Objects card. Switch with ⌃⌘1–⌃⌘4 on a Mac or Ctrl+Alt+1–Ctrl+Alt+4 elsewhere, or from the Command Palette. The search field (⌘K, Ctrl+K, outside text fields) finds objects, events and commands; Go to Mission Item (⇧⌘;, Ctrl+Shift+;) jumps to any object, analysis, saved view, plot or report.

Objects and Views

The Mission card on the left lists the mission’s objects in their folders, its analyses with the state of each result, and below them the saved camera Views, plots and reports. A click selects a row, the eye beside it shows or hides it in the Scene, and its context menu holds its commands: Show Properties, Follow in Scene, Duplicate, Rename ID, Delete Object, and for a catalog Refresh from CelesTrak. The + button opens Add to Mission, and each folder’s context menu adds the kind of object it holds.

Scene

The Scene draws the mission in 3D: bodies with their atmosphere, clouds and night lights, orbits, catalog populations with their orbital-plane rings while a catalog is selected or hovered, ground stations, targets and regions, sensor volumes, access and communications link lines, and coverage overlays. Its playback bar plays and pauses the clock, changes the rate and jumps to the start; its tool cluster holds Layers, Views, Follow and immersive mode. The Scene describes navigation.

Overview and Inspector

The Overview on the right summarizes the mission: the Scene’s header (central body, frame, layers, immersive mode), the orbital population and its altitude histogram from a population analysis, the orbital plane of the selected spacecraft, the state of every analysis, the next events after the playhead, and a card per analysis with its summary metrics. Below it, Properties shows and edits the selected object or analysis; every edit is one undo step. In the Analysis mode Properties appears once you ask for it (Show Properties) and stays until the selection is cleared.

Events

Events lists every event of the mission in time order: acquisitions and losses of signal, culminations, eclipse entries and exits, apsides, nodes, close approaches and conjunctions, each with a severity. Filter by type or severity, search, show only the selected objects, or show each contact as one row. Selecting a row selects its objects and moves the clock to it; Track Primary Object follows its object in the Scene. Export Shown Events as CSV writes what the filters show.

Timeline

The Timeline lays the mission span out in lanes: one per access pair, one per communications link (its contacts, with the windows in which the link closes drawn over them) or other interval series of an analysis (coverage, for example), eclipses, mission events and maneuvers. Drag along the time axis to scrub the clock; click an interval or an event to select its objects and go to it. Zoom with ⌘/Ctrl and the wheel or a pinch; Zoom In, Zoom Out, Fit Mission and Follow Playhead are in its title bar.

Access & Links and Results

Access & Links shows the access and communications analyses. For an access analysis it lists every pass and summarizes each observer–target pair, with the selected pass’s azimuth, elevation and range beside it. For a communications analysis it lists every contact of every transmitter–receiver link, numbered in time order, with its data volume, lowest margin and highest data rate first; the number, link and acquisition time stay in view while the table scrolls sideways. It summarizes each link with its link-closed time and data volume. Beside the selected contact are its link-closed windows, its margin and data rate through the contact, and its Link budget: the design control table at the contact’s worst point or at its culmination, line by line from the transmitter power to the margin. Selecting a pass or a contact goes to its acquisition.

Results shows any analysis result: its summary, intervals, events and every table, with Export Result Table as CSV, Export Intervals as CSV and Export Analysis Result as JSON. Every panel can move to an editor (Open … in Editor) or its own window (Open … in New Window).

Assistant

The Assistant is the workstation’s Chat view. ⌘I (Ctrl+I) opens it beside the Inspector. The AI assistant covers what it does.

Keyboard shortcuts

Save, Undo and Redo apply to the mission while a Hypersphere view or the Scene has focus; elsewhere they keep their usual meaning. The Scene’s own keys are listed with its navigation.

Missions and objects

A mission is one file, mission.json, in a mission folder: its name, time span, central body and kernels, objects, analyses, plots, reports and saved views. The engine is its only writer; every view, script and agent changes it through catalogue commands, so each change is validated, undoable and visible everywhere at once.

Start a mission

Open a folder, then run New Mission from the Command Palette: it asks for a name, writes mission.json and opens the Scene. Open Example Mission opens one of the shipped examples instead. Epochs are always written with their time scale, such as 2026-10-14T00:00:00 UTC.

Spacecraft and propagators

Add Spacecraft starts from an orbit preset (ISS, sun-synchronous, GPS, Molniya, geostationary), Keplerian elements, a Cartesian state, pasted or imported two-line elements, or an ephemeris file in the mission folder; create_object also takes a CCSDS OMM element set. The propagator follows from the source:

Impulsive maneuvers (Δv in VNC, RIC or inertial axes) apply to Keplerian and Cartesian spacecraft; the trajectory splits into arcs at each burn. Add Walker Constellation creates a Walker delta or star pattern in one step, and Import Two-Line Elements imports a TLE file as spacecraft or as one catalog.

Stations, sensors, targets and regions

Add Ground Station places a station by geodetic latitude, longitude and height above WGS 84, with an optional elevation mask. Add Sensor attaches a field of view to a spacecraft or station, pointed along the parent’s attitude or at a target. Add Analysis Target marks a point of interest on a body, and Add Region draws an area as a polygon, a latitude–longitude box or a circle, for coverage and display. Radio equipment is not an object: a communications analysis states its transmitters and receivers (Communications).

Catalogs and CelesTrak

A catalog is a whole element-set file (TLE, OMM CSV or OMM JSON) drawn and screened as one population, propagated with SGP4. Hypersphere ships a dated snapshot of CelesTrak’s public GP groups (13 October 2026); the LEO operations example uses ten of them. Add Catalog from CelesTrak downloads a current group into the mission folder and Refresh from CelesTrak downloads a catalog again. Each download writes a new dated file with a provenance file beside it, at most once per group every two hours. It is the only command that reaches the network, and the workstation asks before each download.

Catalog members are not mission objects; to analyze one (access, lighting, ground track), promote it to a spacecraft with promote_catalog_member. Element sets more than 14 days from the mission span are flagged, and members more than 60 days away are not propagated.

Save, undo and recovery

Save Mission (⌘S) writes mission.json with the current playback state, selection and camera, so the mission reopens where you left it. Undo and Redo step through the engine’s history, whichever client made the change; an assistant answer or a Python undo_group is one step. If the workstation stops with unsaved changes, the next start offers Recover Unsaved Work or Discard Unsaved Work.

Analyses and results

New Analysis adds one of ten types. Analyses run in the engine whenever their inputs change, and a result depends only on the mission, the kernels and the analysis definition, never on playback, open views or thread count.

Analysis types

Communications

A communications analysis links every transmitter it lists to every receiver, on one carrier frequency, over the passes an access search with the same constraints finds. The radio parameters live in the analysis, not on the objects:

In the workstation, Access & Links lists the contacts and links of a communications analysis, the Timeline draws a lane per link with its link-closed windows, and the Scene draws the link line between the two ends while the link closes. Plot a contact’s margin, data rate or Doppler with New Plot.

get_link_budget returns the link budget behind one instant of a link as a design control table (transmitter power and gains, EIRP, path losses, G/T, C/N0, Eb/N0, the required values and the margin). It reads the link-budget table, so its numbers are the table’s own. The assistant answers “show me the link budget” with it, and Python calls it as hs.get_link_budget(…).

Maneuver targeting

A targeting analysis varies the Δv of a spacecraft’s named maneuvers until the orbit or rendezvous goals are met. New Analysis → Maneuver targeting, or Target a Maneuver… in a spacecraft’s properties, sets up the common cases on one burn (an apoapsis or periapsis altitude, circularize, an inclination) with a preview of the solved Δv. The engine solves it again whenever its inputs change and never changes a maneuver on its own: the Properties inspector shows the solution, each burn’s Δv now and solved and whether every goal is met, and Apply Solution writes it into the maneuvers as one undo step. From MCP or the assistant, solve_targeting returns a solution without changing anything and apply_targeting applies it; in Python, hs.targeting("geo-transfer") returns the solution and its apply() writes it. Only Δv components of impulsive burns are varied, not burn times or finite burns. The orbit raising example solves a transfer to geostationary orbit.

Results and events

A result has a status, summary metrics, interval series, events, tables and diagnostics. Tables start with et_s (TDB seconds past J2000) and utc_ms, and every column states its unit. While an analysis recomputes after a change, the views keep showing the previous result, marked as stale.

Export

From the workstation: Export Results as CSV on an analysis, Export Result Table as CSV and Export Intervals as CSV in Results, and Export Events as CSV in Events. From any client, export_results writes CSV or JSON into the mission folder (by default exports/<analysis>-<table>.csv). Exports never replace an existing file unless asked to with overwrite, and they never write outside the mission folder.

Plots and reports

New Plot saves a plot of result columns against time, optionally with shaded interval bands, and New Report a report of text, mission summary, results, plots and events sections. Both live in the mission. Export a plot with Export Plot as PNG or Export Plot Data as CSV, and a report with Export Report as HTML or Export Report as Markdown.

The Scene

Mouse, trackpad and keyboard

The camera orbits the followed object, keeping the pole up.

Follow, frames and views

The Scene follows the central body or any object: F, Follow in Scene or the Follow tool. Following a spacecraft or a station brings the camera to the view straight down from above it after you let go. The globe button in the playback bar switches between inertial axes and axes fixed to the central body. Views saves the camera, follow target and frame under a name, optionally with the epoch, and applies a saved view later; the same views are listed under Objects.

Scene mode and immersive

The Scene mode, or Toggle Immersive Mode (⌃⌘F, F11), hides the panels and gives the Scene the whole window, with its own Objects card; Esc brings the panels back. Without the backdrop, the Scene is an ordinary editor: set hypersphere.scene.backdrop to false.

Layers and quality

Layers turns the atmosphere, clouds, stars, sky map, grid, labels, orbits, ground tracks, sensors, and access and link lines on and off, sets the lighting (Sun or flat) and exposure, and picks a coverage overlay. The hypersphere.scene.quality setting chooses auto, high, balanced or low rendering when a Scene opens.

Python

The hypersphere package sends catalogue commands to the engine of a mission and reads mission snapshots and results. It needs only the standard library; its [dataframe] extra adds pandas and numpy for DataFrames. In the workstation, New Mission Notebook opens a notebook with the package already connected (Notebooks in the workstation). The samples below run against the Quickstart example; the comments show the values they return.

Connect

With the workstation open on a mission, connect from its folder:

import hypersphere

hs = hypersphere.connect()
hs.wait()                             # until every analysis has its final result
hs.mission.name                       # 'Earth — Quickstart'
list(hs.mission.objects)              # ['quickstart-1', 'sg1s']
list(hs.mission.analyses)             # ['sg1s-contacts', 'quickstart-1-lighting', 'quickstart-1-elements']

connect() tries, in order: an explicit url and token; the HYPERSPHERE_URL and HYPERSPHERE_TOKEN environment variables; then the engine serving workspace (default: the current folder or its nearest ancestor), or the only engine running. hs.wait() blocks until the listed analyses (all of them by default) are final. Mission snapshots do not change behind your back: read hs.mission again, or call refresh(), to see later changes.

Commands and undo groups

Every catalogue command is a keyword-only method. Queries return JSON; document commands return an Outcome with the new revision. Epochs are strings with a time scale, and hypersphere.to_epoch() builds them from timezone-aware datetime values.

state = hs.get_object_state(id="quickstart-1", epoch="2026-10-14T09:25:53 UTC")
round(state["geodetic"]["alt_km"], 1) # 563.4
look = hs.compute_geometry(observer="sg1s", target="quickstart-1", epoch="2026-10-14T09:25:53 UTC")
round(look["elevation_deg"], 2)       # 28.91
look["line_of_sight"]                 # True

with hs.undo_group("Add Kiruna"):     # one undo step for everything inside
    hs.create_object(object={
        "kind": "ground_station", "id": "kir-1", "name": "Kiruna KIR-1",
        "location": {"lat_deg": 67.857, "lon_deg": 20.964, "alt_km": 0.402}})
    hs.update_analysis(id="sg1s-contacts", patch={"observers": ["sg1s", "kir-1"]})
hs.results("sg1s-contacts").wait().summary["passes"]   # 23.0
hs.undo()                             # both changes at once

Engine failures raise hypersphere.EngineError subclasses such as ValidationError and NotFoundError, with the diagnostics and JSON pointers the engine reported.

Results and DataFrames

contacts = hs.results("sg1s-contacts").wait()      # blocks until the result is final
contacts.summary["passes"]                          # 13.0
contacts.summary.units["total_duration_s"]          # 's'
passes = contacts.intervals.to_dataframe()          # a row per pass: start, stop, duration_s, max_elevation_deg, …
aer = contacts.table("aer:sg1s:quickstart-1").to_dataframe()   # indexed by UTC
list(aer.columns)                                   # ['et_s', 'azimuth_deg', 'elevation_deg', 'range_km', 'range_rate_km_s']
hs.export_results(analysis="sg1s-contacts", format="csv")["paths"]
# ['exports/sg1s-contacts-aer-sg1s-quickstart-1.csv']

to_dataframe() indexes tables by utc as datetime64[ns, UTC] and keeps et_s as a column; df.attrs["units"] holds the units. table.to_csv(path) writes the engine’s own CSV. A communications result reads the same way: its contacts are the interval series comms:<transmitter>:<receiver> and its link budget the table link:<transmitter>:<receiver>.

Notebooks in the workstation

New Mission Notebook opens a notebook whose kernel is already connected: hs is ready in the first cell, tables display as tables and matplotlib figures inline. Open Results in Notebook starts one from an analysis. The kernel runs in a Python environment the workstation manages, with the hypersphere package, IPython, numpy, pandas and matplotlib; Set Up Python Environment builds it again, and Select Python Interpreter or hypersphere.python.interpreterPath picks the Python (3.10 or newer) it is built from.

AI agents over MCP

MCP clients such as Claude Code and Claude Desktop get the whole catalogue as tools: one tool per command, with the same names, schemas and descriptions the workstation and Python use. Queries are marked read-only, commands that discard work are marked destructive, and fetch_gp_group, the one command that reaches the network, is marked as such. Every call goes to the engine of the mission open in the workstation, so an agent’s changes appear live and undo like your own.

Connect an agent

In the workstation, with the mission open, run Copy MCP Configuration from the Command Palette. It copies a ready mcpServers entry for the open mission, with nothing to fill in and no token. Paste it into the agent’s MCP settings: a project’s .mcp.json for Claude Code, or the file Settings → Developer → Edit Config opens in Claude Desktop. Then restart the agent, which lists the Hypersphere tools.

Things to ask

• “List the objects in the mission and describe the orbit of Quickstart-1.”
• “Add a ground station at Kiruna, 67.857° N, 20.964° E, with a 5° elevation mask, and add it to the contacts analysis.”
• “What are the azimuth, elevation and range of Quickstart-1 from Svalbard at 09:25:53 UTC?”
• “Create a Walker constellation of 24 satellites in 3 planes at 1,000 km and 55°.”
• “Export the contact table as CSV.”

The AI assistant

The assistant is the workstation’s Chat view, answering with Claude. Its tools are the catalogue commands, generated from the same schemas as the GUI, Python and MCP, plus a few workstation actions (open a view, plot or report, start a notebook, switch mode). The Chat view shows each call it makes.

Models and the API key

The hosted workstation that opens from the showcase needs no key: its assistant runs on Claude Haiku 5.5 (the default) or Claude Sonnet 5.5 through the server’s own access. With your own Anthropic API key the model picker offers Claude Opus 5.5 as well: run Manage Anthropic API Key from the Command Palette, or open Manage Language Models, choose Anthropic and enter the key. The key is kept in the system’s secret storage, never in settings, logs, the mission or the chat; a workstation can also read it from ANTHROPIC_API_KEY, or from a key file named by HYPERSPHERE_ANTHROPIC_KEY_FILE that only you can read. Without a key, the assistant answers with these steps and sends nothing.

Ask and Agent

Pick the mode under the input. Ask reads the mission and never changes it: it has only the read-only tools, and no exports. Agent builds and edits the mission. Each model has a thinking-effort option, and the tool picker limits which Hypersphere tools a request may use.

What it can do

Anything the catalogue can: create and edit objects and analyses, read results and events, compute states and geometry, build plots and reports, export files and move the clock, the selection and the camera. Ask it for a report and it writes one from the mission’s results and opens it. Ask About Selection starts a question about what is selected.

Confirmations and undo

Destructive commands, and exports that would replace a file, wait for your confirmation in the chat; the permission picker under the input can approve them automatically. Everything one answer changes is one undo step, and Undo These Changes beside the answer reverts exactly that step while nothing newer has changed the mission.

Data and sources

Kernels, frames and time

Frames, ephemerides, orientation and time come from ANISE with JPL kernels: the DE440s planetary ephemeris, and Earth orientation in ITRF93 from 1962 to 2126. Every epoch carries its time scale and every vector its frame. Outside a kernel’s coverage an analysis fails with a diagnostic that names the kernel, never a zero or a silent gap; IAU_EARTH is used only when you choose it. Link physics (free-space loss, EIRP, G/T, C/N0, Eb/N0, Shannon capacity, Doppler) comes from the linkbudget crate.

The catalog snapshot

The shipped CelesTrak GP groups were retrieved on 13 October 2026 and are kept byte for byte, with their checksums; one file, the active satellites outside the other groups, is derived from CelesTrak’s active group. SGP4 errors grow by kilometres per day away from the element epoch, so the snapshot suits missions within days of that date; download current groups for later spans (Catalogs and CelesTrak).

The data manifest

Every shipped file (kernels, imagery, the star catalogue, the catalog snapshot, ground station coordinates) is listed with its SHA-256, source and license, and every file is checked against that list. The credits on the home page are generated from it.

Validation

Each example mission ships with expected/validation.json: checks of the engine’s answers against analytic formulas, published values and independent brute-force searches, each with its provenance and a tolerance from a written error budget. The test suite runs every example’s checks on each change.

Troubleshooting

The engine stopped or will not start

The title bar shows Engine Failed: Show Engine Log. Read the log with Show Engine Log, fix the cause, then run Restart Engine. One engine serves a mission folder at a time.

The Scene says WebGPU is unavailable

The Scene lists the adapter it found and the reason. Update the graphics driver; on Linux, use a GPU with Vulkan. hypersphere.scene.quality set to low lowers the load on weaker GPUs.

An analysis fails with a kernel coverage diagnostic

The mission span reaches outside the data of a kernel the analysis needs, such as Earth orientation before 1962 or after 2126. Move the span inside the coverage the diagnostic names.

A communications link never closes

Check the contacts first: without passes there is nothing to close. Then compare the link-budget table’s C/N0 with the threshold of the reference option (the lowest) in rate_options; the margin column is their difference. A receiver stated by G/T carries no system temperature, so the atmosphere adds loss but no sky noise.

Python cannot find the engine

hypersphere.connect() raises HypersphereNotRunning when no engine serves the folder. Open the mission in the workstation, then connect from inside that folder, or pass workspace=.

The assistant asks for a key

No Anthropic API key is set up, or the key was rejected. Run Manage Anthropic API Key and enter an Anthropic API key from the Claude Console; a malformed key is reported as soon as you enter it, and a rejected one when the assistant first answers.

Catalogs warn about stale element sets

Some element sets are more than 14 days from the mission span. Download the group again with Refresh from CelesTrak, or keep the span within days of the element epochs.