For the complete documentation index, see llms.txt.
The Spacecraft page lets you manage your satellite fleet. Each spacecraft is organised by fidelity tier — identifiers, the cannonball model (bulk mass plus single drag and SRP area coefficients), advanced geometry (bus dimensions, panel definition, and mounted components), and a Danger Zone for archive and restore actions.
Route: /spacecraft
Page Layout
The page shows a single spacecraft at a time. Use the spacecraft selector at the top-left to switch. Each spacecraft renders four sections — Identifiers, Cannonball model, Advanced geometry, and Danger Zone — in that order, with a real-time 3D viewer inside the Advanced geometry section.
The page opens with a compact header showing:
- A colour dot — the same colour the rest of the app uses to identify this spacecraft on plots and lists.
- The spacecraft name.
- A status badge:
| Status | Meaning |
|---|
| Active | Operational and available for all operations. |
| Archived | Deactivated; data is preserved but the spacecraft is hidden from active lists. |
Switching Spacecraft
Use the dropdown in the top-left corner to switch between spacecraft. The dropdown is disabled while any card on the page is in edit mode — finish or cancel the edit first, then switch.
Per-Card Editing
Each card on the page has its own Edit, Save, and Cancel controls. Entering edit mode on one card leaves every other card in read mode. While a save is in flight, the card’s button shows Saving... and its inputs are disabled until the save completes.
If a save fails, the card stays in edit mode with your draft intact so you can correct the value and retry. Cancel discards your draft and restores the last-saved values.
The Identifiers section is the one exception: it edits all four identifier fields under a single section-level Edit control.
Identifiers Section
The Identifiers strip carries four fields:
| Field | Description |
|---|
| Name | The spacecraft’s display name. Required. |
| NORAD ID | Public catalog reference number. Optional — see NORAD catalog number for the accepted format. |
| COSPAR ID | International designation. Optional. |
| Colour | Colour used to identify this spacecraft throughout the app. |
"Name is required." inline and blocks the save. All other fields are optional.
NORAD catalog number
The NORAD ID is the public catalog number VALAR uses to fetch the spacecraft’s orbit. It is optional, and when provided it must be a whole number between 1 and 999999 — including 6-digit numbers (100000–999999).
- Blank is allowed. Leave the field empty and the spacecraft is saved with no catalog number; it simply isn’t fetched from a public catalog. This is a normal state — for example, a spacecraft that hasn’t launched yet — not an error.
- Letters and Alpha-5 identifiers are not accepted. A catalog number must be a plain whole number. Alpha-5 identifiers such as
B1234 (the compressed form some tools use for numbers above 99999) are rejected — enter the full numeric catalog number instead.
- Analyst / reserved numbers (
70000–99999) are saved but not looked up. These are valid to record, but they are not part of CelesTrak’s public catalog, so VALAR will not query CelesTrak for a spacecraft in that range.
A 6-digit catalog number can be entered and stored today. Propagating a 6-digit object’s orbit is not yet supported — a known limitation tracked separately.
Cannonball Model Section
The Cannonball model is the default fidelity tier — bulk mass plus single drag and SRP area coefficients. The platform’s default propagation and conjunction stack uses these values for spacecraft without a full geometry. The section header includes a Learn more link to the First spacecraft tutorial.
The section contains two cards side by side: a Mass card and an Isotropic model card.
Mass card
| Field | Description | Unit |
|---|
| Launch Mass | Initial mass at launch. | kg |
| Dry Mass | Mass without propellant. | kg |
| Inertia tensor | The three principal moments (Ixx, Iyy, Izz) shown as a 3×3 matrix — moments on the diagonal, zeros off-diagonal. Optional. | kg·m² |
0 in every off-diagonal cell. When all three moments are unset the matrix collapses to a Inertia tensor not configured hint.
Inertia validation messages:
| Condition | Message |
|---|
| Some moments set but not all three | "Inertia tensor must have all three moments set, or none." |
| Any moment is zero or negative | "Inertia principal moments must be positive numbers." |
Isotropic model card
The Isotropic model card holds two self-contained blocks side by side — Drag and SRP:
| Block | Field | Unit |
|---|
| Drag | Drag area | m² |
| Drag | Drag coefficient | — |
| SRP | SRP area | m² |
| SRP | Coefficient | — |
Drag area and SRP area are always operator-typed. The page does not prefill them from box or panel dimensions, even when those are configured.
Advanced Geometry Section
The Advanced geometry section is the high-fidelity tier — bus dimensions, panel definition, and mounted components. It’s used by the faceted radiation model and attitude-aware perturbations. The section header includes a Learn more link to the First spacecraft tutorial.
The section lays out a Bus card beside the 3D viewer, with a tabbed components area below.
Bus card
A Shape selector at the top of the Bus card chooses the bus body shape — Box or Regular prism — and the dimension inputs below it change to match. You define the whole bus from this single card.
A Box bus exposes three dimension fields:
| Field | Unit |
|---|
| Box length | m |
| Box width | m |
| Box height | m |
| Field | Description | Unit |
|---|
| Sides | Number of polygon sides — an integer from 3 to 12. Out-of-range values are rejected with "Sides must be between 3 and 12". | — |
| Diameter | Cross-section diameter, paired with an Inscribed / Circumscribed toggle that sets how it is measured: Inscribed is across the flats, Circumscribed is across the corners. A non-positive value is rejected with "Diameter must be greater than 0". | m |
| Height | Prism height along the extrusion axis. A non-positive value is rejected with "Height must be greater than 0". | m |
| Axis | Extrusion axis — X, Y, or Z (default Z). | — |
1.0 m (Inscribed). Switching the Shape clears the dimension inputs entered for the previous shape.
The card also holds Surface optics beside the dimensions:
| Field | Unit |
|---|
| Absorption (α) | — |
| Specular reflection (ρs) | — |
3D Viewer
The right side of the Advanced geometry section displays a real-time 3D model of the spacecraft:
- Renders the bus in its true shape — a box for a Box spacecraft, or the configured polygon prism for a Regular prism spacecraft.
- Draws each configured panel as a flat plate at its mount position, oriented so its broad face points along its facing, and sized to its length and width — so the model reflects the true arrangement of the panels.
- Updates automatically as you save box, prism, panel, or thruster changes.
- Rotate the view by clicking and dragging.
- Zoom with the scroll wheel.
- Shows accurate proportions based on configured dimensions.
The viewer stays mounted while you edit any other card on the page — entering edit mode on the Bus card or a panel card does not unmount or reposition it.
Components Tabs
Below the Bus + viewer row, the Panels, Thrusters, and Payloads tabs hold the mounted components. Each tab trigger shows an item-count badge.
Panels tab
The Panels tab holds the spacecraft’s solar and radiator panels. Each panel is configured independently as its own card — mount point, orientation, size, and optics are set per panel, not shared across a fixed arrangement. The tab trigger badge shows the number of configured panels.
A spacecraft holds 0 to 8 panels. Click Add panel to append a new panel card and fill it in place; each card has its own Edit, Save, and Cancel controls and a delete control that prompts for confirmation before applying. Once eight panels are configured, the Add panel button is disabled and hovering it shows a Maximum 8 panels tooltip. When the spacecraft has no panels yet, the tab shows a No panels configured prompt with a single Add panel button.
Each panel card carries:
| Field | Description | Unit |
|---|
| Name | Display name for the panel. Required, and must be unique within the spacecraft. | — |
| Mount position | The panel’s attachment point on the spacecraft body — X, Y, Z in the body frame. Each component may be negative. | m |
| Mount axis | The body-frame axis the panel mounts along; choose from the options below (default PLUS Z). | — |
| Rotation | In-plane rotation of the panel about its mount axis. Range 0° up to (but not including) 360° (default 0°). | ° |
| Facing | A read-only readout of the panel’s outward normal — the live unit vector its broad face points along, recomputed as you change the mount axis and rotation. A degenerate axis shows —. | — |
| Dimensions | The panel plate’s length × width. Each must be greater than 0. | m |
| Double-sided | When on, both faces of the plate are active surfaces; when off, only the outward face is (default off). | — |
| Optics | The panel’s optical coefficients — Absorption (α) and Specular reflection (ρs). | — |
| Option | Effect |
|---|
| PLUS X, MINUS X, PLUS Y, MINUS Y, PLUS Z, MINUS Z | The panel mounts along the chosen spacecraft body axis. |
| Custom | Reveals three numeric sub-inputs — Custom axis X, Y, Z — for an arbitrary body-frame direction. |
| Field | Condition | Message |
|---|
| Name | Blank | Name is required |
| Dimensions | Length not greater than 0 | Length must be greater than 0 |
| Dimensions | Width not greater than 0 | Width must be greater than 0 |
| Rotation | 360° or above, or below 0° | Rotation must be between 0° and 360° |
| Custom axis | A custom direction of (0, 0, 0) (or otherwise zero-length) | Enter a non-zero direction |
| Absorption (α) | Outside 0–1 | Absorption must be between 0 and 1 |
| Specular reflection (ρs) | Outside 0–1 | Specular reflection must be between 0 and 1 |
| Optics | Absorption + specular reflection exceeds 1 | Absorption + specular reflection must not exceed 1 |
— and the panel cannot be saved.
A spacecraft that had a solar-panel array configured before independent panels were introduced is converted automatically: the former array becomes two symmetric panels — Solar array (port) and Solar array (starboard) — that reproduce the original array’s drag and SRP exactly. No action is required; you can refine, rename, or remove them like any other panel. (A spacecraft that had no panel array simply starts with none.)
Panel facing drives drag and SRP forces only once an attitude profile is configured. Until then, panels save and display normally, but the spacecraft stays on the isotropic model — using the scalar Drag coefficient and Coefficient from the Isotropic model card. Thrusters tab
The Thrusters tab lists every thruster mounted on the spacecraft. Click Add thruster to open the thruster dialog, or edit and delete existing thrusters from the list.
| Field | Description |
|---|
| Name | Display name for the thruster. |
| Thrust | Thrust force output. |
| Specific Impulse (Isp) | Propellant efficiency. |
| Max Burn Time | Maximum continuous burn duration. |
| Position (X, Y, Z) | Thruster location on the spacecraft body. |
| Direction | Thrust vector direction — one of X+, X-, Y+, Y-, Z+, Z-. |
Payloads tab
The Payloads tab lists every payload mounted on the spacecraft. A payload is an on-board sensor — a body-frame boresight axis plus a field of view describing the cone of sky it sees. Unlike the thruster dialog, payloads are added and edited inline: click Add payload to append a new payload card, fill it in place, and Save it. Each card has its own Edit, Save, and Cancel controls, and a delete control that prompts for confirmation before applying. When the spacecraft has no payloads yet, the tab shows a No payloads configured prompt with a single Add payload button.
Each payload card carries:
| Field | Description |
|---|
| Name | Display name for the payload. Required. |
| Position (m) | The payload’s attachment position on the spacecraft body — X, Y, Z in metres, in the body frame. Each component may be negative. |
| Boresight | The body-frame axis the payload points along — one of the six cardinal axes X+, X-, Y+, Y-, Z+, Z-. |
| FOV shape | The field-of-view shape — one of Conical, Rectangular, Elliptical, or Polygon. Choosing a shape reveals only that shape’s angle fields (below). |
| Shape | Fields | Range |
|---|
| Conical | A single half-angle | 0°–90°, where 90° opens the field of view to a full hemisphere. |
| Rectangular | A half-width and a half-height | Each above 0° and below 90°. |
| Elliptical | A half-width and a half-height | Each above 0° and below 90°. |
| Polygon | A number of sides and a radius | At least 3 sides; the radius is a half-angle above 0° and below 90°, measured from the boresight to a vertex. |
90° conical field of view renders as a hemisphere.
A payload is an on-board sensor carried by the spacecraft — it points along a body-frame axis and moves with the spacecraft. Do not confuse it with a tracking sensor, which is a fixed ground-based observer that watches spacecraft from the surface. Danger Zone
The Danger Zone is the final section on the page and hosts the lifecycle actions:
| Spacecraft state | Action | Effect |
|---|
| Active | Archive | Deactivate the spacecraft. Data is preserved; the spacecraft is hidden from active lists. |
| Archived | Restore | Reactivate an archived spacecraft. The spacecraft returns to active operations. |
Validation Feedback
As you edit any card, each input shows inline feedback below it. The feedback uses four states:
| State | Indicator | Meaning |
|---|
| Error (red) | Alert icon + red text | The value is invalid and blocks save. Examples: a blank Name, a negative inertia moment, a panel’s custom mount axis of (0, 0, 0). |
| Warning (amber) | Alert icon + amber text | The value saves but falls outside the typical range. Examples: a Reflectivity coefficient outside the typical band, a soft-warned Drag area above 1000 m². |
| Unable to validate (grey) | Muted text | The validator could not respond — usually a transient network or backend issue. You can still save; the per-field rule will re-run on the next attempt. |
| Valid (green) | Check icon | The value passed validation. |
Ratio of SRP area to drag area is outside typical range — check for unit confusion or stale geometry
The warning is non-blocking — you can still save — but is a strong hint that one of the two values is wrong (commonly a cm² vs. m² slip, or a stale value from an earlier geometry).
Per-field validation messages carried across the page:
| Field | Condition | Message |
|---|
| Name (Identifiers) | Blank or whitespace-only | Name is required. |
| Inertia tensor (Mass card) | Some moments set but not all three | Inertia tensor must have all three moments set, or none. |
| Inertia tensor (Mass card) | Any moment is zero or negative | Inertia principal moments must be positive numbers. |
| Custom axis (Panel) | Custom mount axis of (0, 0, 0) | Enter a non-zero direction |
Creating a New Spacecraft
Click New Spacecraft in the top-bar to navigate to the /spacecraft/new creation page. The page mirrors the detail-page layout — the same Identifiers, Cannonball model, and Advanced geometry sections — but starts with empty values and every card already in edit mode. A page-level Create Spacecraft button at the bottom of the page submits the form; Cancel returns to the spacecraft list without saving.
| Section | Required fields | Optional fields |
|---|
| Identifiers | Name | NORAD ID, COSPAR ID, Colour |
| Cannonball model | Launch Mass, Drag area, SRP area, Drag coefficient, Reflectivity coefficient | Dry Mass |
| Advanced geometry | (none) | Box or prism dimensions, panels, surface optics |
| Field | Default |
|---|
| Drag coefficient | 2.2 |
| Reflectivity coefficient | 1.5 |
| Colour | Neutral blue (#3b82f6) |
Name is required.) and blocks the submit until every required field is filled. The Danger Zone does NOT appear on the creation page; archive and restore only apply to spacecraft that already exist.
On success the page shows a confirmation toast and navigates to the new spacecraft’s detail page so you can complete the remaining configuration — inertia tensor, additional surface optics, panels, and thrusters.
Related Pages
- Creating Your First Spacecraft: Step-by-step walkthrough for new users — also the destination of the Learn more link from the Cannonball model and Advanced geometry section headers.
- Force Model: How geometry and optical inputs drive attitude-dependent drag and SRP.
- Attitude Overview: Configure an attitude profile so the platform uses per-facet drag and SRP based on the Bus surface optics and panel definitions.
- Burn Plan: Plan maneuvers using configured thrusters.
- State Vectors: View orbit solutions for this spacecraft.
