# Maneuver API Source: https://docs.valar.space/api-reference/maneuvers Exchange stored spacecraft maneuvers through CCSDS OCM, delete records, and import corrections. > For the complete documentation index, see [llms.txt](/llms.txt). The Maneuver API exchanges stored spacecraft maneuver records through **CCSDS OCM** at **`https://api.valar.space`**. Import OCM files, export selected records or time ranges, and delete records when needed. Each record belongs to one spacecraft and contains burn segments. Importing a record stores data in VALAR; it does not uplink a command to a spacecraft. ## API contract Download the [standalone OpenAPI contract](/api-reference/contracts/maneuvers-v1.openapi.json) to generate a client or pin an integration. Its `info.version` identifies the contract version. The complete live customer API is available at [`/api-docs/mintlify`](https://api.valar.space/api-docs/mintlify), with the maneuver version in `x-valar-maneuver-api-version` and each operation's version in `x-valar-contract-version`. The three public operations are: | Method | Path | Purpose | | - | - | - | | DELETE | `/operations/maneuvers/{maneuverId}` | Delete one record | | POST | `/operations/maneuvers/import` | Add records from OCM files | | GET | `/operations/maneuvers/export` | Export selected IDs or a spacecraft/time range | The [maneuver planner](/features/planner), approval, and orbit-raise workflows are available in the application and are outside this published API. ## Authenticate a mission-control integration Use an [API key](/features/api-keys) issued for your organization and granted the **Operations** environment. Send `Authorization: Bearer $VALAR_API_KEY` on every request. The key inherits its owner's resource permissions, and requests are recorded in the API-key usage audit log. Organization and environment are derived from authentication and the route. | Operation | Required permission | | - | - | | Export | `read:plannedmaneuvers` | | Import | `write:plannedmaneuvers` | | Delete | `delete:plannedmaneuvers` | Look up the **VALAR spacecraft ID** before making maneuver requests: ```bash theme={null} curl --fail-with-body 'https://api.valar.space/operations/spacecraft' \ --header "Authorization: Bearer $VALAR_API_KEY" ``` Use that returned ID as `SPACECRAFT_ID` below. Names, NORAD IDs, COSPAR IDs, and external keys are lookup filters, not substitutes for the VALAR spacecraft ID in export or delete requests. ## Identify records through OCM Use an OCM export to inspect stored burn definitions. Select known `MAN_ID` values or export a spacecraft/time range using the [examples below](#import-and-export-ocm-files). OCM `MAN_ID` is the stable maneuver identity within its spacecraft, with a maximum length of 63 characters. An editable display name is not a substitute for that identity. Address a deletion by **`maneuverId` plus `spacecraftId`**; URL-encode path values when necessary. ## Resolve conflicts Imports must not overlap another stored maneuver on the same spacecraft. The check uses each record's enclosing start-to-end interval, including gaps between segments. Adjoining intervals may touch: a record ending at 12:01 may be followed by one starting at 12:01. Records on different spacecraft do not conflict with each other. Duplicate identities and overlaps with stored records return **409 `MANEUVER_CONFLICT`**. Use the reported identities to export and inspect conflicting records, then decide which records to retain or explicitly delete. No record is automatically merged, shortened, replaced, or deleted. A conflict may be outside your current export window. Records with existing overlaps remain exportable and deletable. Computation results retain their captured maneuver data; new computations use the current records. ## Delete a record ```bash theme={null} curl --fail-with-body --request DELETE \ "https://api.valar.space/operations/maneuvers/BURN-001?spacecraftId=$SPACECRAFT_ID" \ --header "Authorization: Bearer $VALAR_API_KEY" ``` Success is **204** with no response body. Deletion removes the live record and cannot be undone. ## Correct a stored maneuver 1. Export and inspect the record, retaining the file if you need a copy. 2. Prepare corrected OCM that satisfies the [import requirements](/file-formats/ocm#valar-import-requirements). 3. Explicitly [delete the stored record](#delete-a-record) and confirm that deletion succeeded. 4. Import the corrected file and check its result: ```bash theme={null} curl --fail-with-body \ "https://api.valar.space/operations/maneuvers/import?spacecraftId=$SPACECRAFT_ID" \ --header "Authorization: Bearer $VALAR_API_KEY" \ --form 'files=@corrected-burn.ocm' ``` Deletion and import are **two separate operations**, not an atomic replacement. If the import fails, the deleted record stays deleted. Import never overwrites an existing record; duplicate, overlap, spacecraft-resolution, and physical validation still apply. Review failed-file results and correct the file before retrying. ## Import and export OCM files Import adds records from CCSDS OCM files: ```bash theme={null} curl --fail-with-body \ "https://api.valar.space/operations/maneuvers/import?spacecraftId=$SPACECRAFT_ID" \ --header "Authorization: Bearer $VALAR_API_KEY" \ --form 'files=@burns.ocm' ``` Repeat the multipart **`files`** part for several files. `spacecraftId` is optional when file metadata resolves the target unambiguously. Files require thrust, ISP, and physical wet mass; see [OCM import requirements](/file-formats/ocm#valar-import-requirements). `MAN_BASIS` is optional format metadata and has no effect on stored-record behavior. Exports omit it. OCM `MAN_ID` remains the stable identity, even after the editable name changes. Each file commits atomically and independently. **200** means every file succeeded; **207** contains per-file successes and failures, including ambiguous targets. Inspect `successCount`, `failureCount`, and `results`. An all-ambiguous batch also returns 207. If every file fails without ambiguity, the request returns an error, such as 400 for invalid input or 409 for a stored-record conflict. A failed file adds none of its records; successful files remain saved. Reimporting an existing `MAN_ID` fails. To submit a correction, follow [Correct a stored maneuver](#correct-a-stored-maneuver). Optional `X-Content-Hash` and `X-Resolution-Fingerprint` headers bind an import to a previously inspected file. A stale preview returns **409 `IMPORT_STALE_PREVIEW`**. Direct callers may omit these headers. Submit preview-bound files individually rather than binding a multi-file batch to one preview. All exports use `GET /operations/maneuvers/export`. Export one record by supplying one `spacecraftIds` value and one `maneuverIds` value, for example `/operations/maneuvers/export?spacecraftIds=SC-1&maneuverIds=BURN-001`. For selected IDs, use the collection GET with exactly one `spacecraftIds` value and 1–100 unique `maneuverIds`. Repeat the `maneuverIds` parameter for each identity; commas inside a value are literal name characters, not separators. One ID produces `text/plain` OCM; multiple IDs produce `application/zip`. Send these selections as query parameters with no request body. ```bash theme={null} curl --fail-with-body --get 'https://api.valar.space/operations/maneuvers/export' \ --header "Authorization: Bearer $VALAR_API_KEY" \ --data-urlencode "spacecraftIds=$SPACECRAFT_ID" \ --data-urlencode 'maneuverIds=BURN-001' \ --data-urlencode 'maneuverIds=BURN-002' \ --output maneuvers.zip ``` Export by range using exact instants (no expansion to calendar-day boundaries): ```bash theme={null} curl --fail-with-body --get 'https://api.valar.space/operations/maneuvers/export' \ --header "Authorization: Bearer $VALAR_API_KEY" \ --data-urlencode "spacecraftIds=$SPACECRAFT_ID" \ --data-urlencode 'startDate=2026-10-01T00:00:00Z' \ --data-urlencode 'endDate=2026-10-02T00:00:00Z' \ --output maneuvers.ocm ``` Range export accepts 1–50 spacecraft IDs (repeated or comma-separated) and requires both time bounds, with `endDate` after `startDate`. One spacecraft produces OCM text; multiple spacecraft produce a ZIP of OCM files. ID and time-range selection are mutually exclusive: do not send time bounds with `maneuverIds`. Missing, empty, or mixed selections return 400. URI size limits still apply; divide a large selection into smaller GET requests if its encoded URL is too long. Integration software owns downstream submission and uplink procedures. ## Handle errors and retries Resource, validation, and permission errors use VALAR's shared error envelope, including `timestamp`, `status`, `error`, `message`, and `path`, with structured details where available. Use the machine-readable error token and HTTP status instead of parsing prose messages. | Status | Integration response | | - | - | | 400 | Correct invalid input, file syntax, or physical values. | | 401 | Check for a missing, invalid, expired, revoked key, or disabled owner. | | 403 | Check owner permissions, environment grant, and IP allowlist. | | 404 | Check record IDs and their owning spacecraft/organization. | | 409 | Resolve `MANEUVER_CONFLICT`, or inspect again for `IMPORT_STALE_PREVIEW`. | | 413 | Reduce file or total multipart request size. | | 422 | Correct the unmet precondition reported in the error details. | | 5xx | Preserve request details and any correlation ID for diagnosis. | GET exports can be retried with bounded backoff. Import has no idempotency-key contract: if a connection drops after submission, export the affected identities or time range and inspect the stored data before repeating the write. Do not retry successful files in a 207 batch. After an uncertain DELETE result, verify the record's state through export before importing a correction; distinguish a missing record from authentication, permission, or transport errors. # Delete a stored maneuver Source: https://docs.valar.space/api-reference/maneuvers/delete-a-stored-maneuver https://api.valar.space/api-docs/mintlify delete /operations/maneuvers/{maneuverId} # Export stored maneuvers Source: https://docs.valar.space/api-reference/maneuvers/export-stored-maneuvers https://api.valar.space/api-docs/mintlify get /operations/maneuvers/export Select IDs using exactly one spacecraftIds value and 1–100 maneuverIds, without time bounds; or select a range using 1–50 spacecraftIds and both startDate and endDate, without maneuverIds. endDate must be after startDate. spacecraftIds accepts repeated or comma-separated parameters. maneuverIds accepts repeated parameters only; commas are literal identity characters. Duplicate maneuverIds are invalid. One selected ID returns OCM; multiple IDs return ZIP. Range exports return OCM for one spacecraft and ZIP for multiple spacecraft. No request body is used. # Import generic OCM records Source: https://docs.valar.space/api-reference/maneuvers/import-generic-ocm-records https://api.valar.space/api-docs/mintlify post /operations/maneuvers/import # Bulk mark or unmark measurements as outliers by ID list Source: https://docs.valar.space/api-reference/measurements/bulk-mark-or-unmark-measurements-as-outliers-by-id-list https://api.valar.space/api-docs/mintlify patch /operations/measurements/outliers Performs a bulk update of the outlier status on multiple measurements simultaneously. Maximum 1000 measurement IDs per request. Non-existent IDs are silently ignored. The returned count reflects only actually updated measurements. # Bulk mark or unmark measurements as outliers by source file Source: https://docs.valar.space/api-reference/measurements/bulk-mark-or-unmark-measurements-as-outliers-by-source-file https://api.valar.space/api-docs/mintlify patch /operations/measurements/outliers/by-file Performs a bulk update of the outlier status on all measurements originating from a specific source file. File name matching is exact and case-sensitive. The returned count reflects all matching measurements updated within the current tenant. # Delete measurements by source file Source: https://docs.valar.space/api-reference/measurements/delete-measurements-by-source-file https://api.valar.space/api-docs/mintlify delete /operations/measurements/by-file Permanently deletes all measurements for a spacecraft from a specific source file. This is useful when an uploaded file contains incorrect data. WARNING: This operation cannot be undone. Returns 200 with deletedCount=0 if no matching measurements are found. # Query measurements with pagination and filtering Source: https://docs.valar.space/api-reference/measurements/query-measurements-with-pagination-and-filtering https://api.valar.space/api-docs/mintlify get /operations/measurements Retrieves paginated measurements with optional filtering by spacecraft, measurement type, date range, and outlier status. Results are sorted by epoch descending by default. # Upload measurement files Source: https://docs.valar.space/api-reference/measurements/upload-measurement-files https://api.valar.space/api-docs/mintlify post /operations/measurements Upload one or more measurement files for asynchronous processing. Supported formats: TDM (Tracking Data Message), SP3 (Standard Product 3), and OEM (Orbit Ephemeris Message). Each file is validated synchronously and then queued as a background job for full processing. The response includes per-file results with job IDs for tracking processing status. # Add a payload Source: https://docs.valar.space/api-reference/payloads/add-a-payload https://api.valar.space/api-docs/mintlify post /operations/spacecraft/{spacecraftId}/payloads Adds a payload under a parent spacecraft resolved strictly by id. The server assigns the lowest-free slot index [0,7]; the 9th sensor is refused with 422 PAYLOAD_LIMIT_EXCEEDED. Returns 404 if the parent spacecraft does not exist. # Get a payload by id Source: https://docs.valar.space/api-reference/payloads/get-a-payload-by-id https://api.valar.space/api-docs/mintlify get /operations/spacecraft/{spacecraftId}/payloads/{payloadId} Retrieves a payload reached only through the parent's collection. Returns a uniform 404 PAYLOAD_NOT_FOUND for an unknown id / foreign-tenant / wrong-parent (indistinguishable). # List payloads for a spacecraft Source: https://docs.valar.space/api-reference/payloads/list-payloads-for-a-spacecraft https://api.valar.space/api-docs/mintlify get /operations/spacecraft/{spacecraftId}/payloads Retrieves all payloads for a parent spacecraft resolved strictly by id, ordered by payloadIndex ascending. Returns 404 if the parent spacecraft does not exist. # Partially update a payload Source: https://docs.valar.space/api-reference/payloads/partially-update-a-payload https://api.valar.space/api-docs/mintlify patch /operations/spacecraft/{spacecraftId}/payloads/{payloadId} Updates only the provided scalars of a payload in place (the UUID is never re-minted). The FOV group is an atomic replace: restate fovShape to change any FOV param; a lone FOV param without fovShape is a 400. Returns a uniform 404 for any miss vector. A genuine change to this payload's offNadirAlongTrackDeg or offNadirCrossTrackDeg field auto-mints a new slew-envelope revision as a same-transaction side effect. A mint failure over frame/attitude interpretability still rolls back the entire PATCH, so the payload's scalar fields revert to their pre-PATCH persisted values; a mint refused only because the payload's own aperture is non-isotropic does NOT roll back — the scalar edit still commits, and the rejection surfaces later via the affected AOI opportunities' own off-nadir disclosure rather than in this response. # Remove a payload Source: https://docs.valar.space/api-reference/payloads/remove-a-payload https://api.valar.space/api-docs/mintlify delete /operations/spacecraft/{spacecraftId}/payloads/{payloadId} Removes a payload reached only through the parent's collection; the freed slot index is left as a gap (never repacked). Returns a uniform 404 for any miss vector. # Get spacecraft by UUID Source: https://docs.valar.space/api-reference/spacecraft/get-spacecraft-by-uuid https://api.valar.space/api-docs/mintlify get /operations/spacecraft/{id} Retrieves a spacecraft by its canonical UUID id. A non-UUID value (NORAD, COSPAR, or name) is rejected with 400 VALIDATION_ERROR before resolution. Returns 404 if no such spacecraft exists. # List spacecraft Source: https://docs.valar.space/api-reference/spacecraft/list-spacecraft https://api.valar.space/api-docs/mintlify get /operations/spacecraft Retrieves a paginated list of spacecraft for the current tenant. # Partially update a spacecraft Source: https://docs.valar.space/api-reference/spacecraft/partially-update-a-spacecraft https://api.valar.space/api-docs/mintlify patch /operations/spacecraft/{id} Updates only the provided fields of a spacecraft resolved strictly by id. Returns 404 if it does not exist. # Register a new spacecraft Source: https://docs.valar.space/api-reference/spacecraft/register-a-new-spacecraft https://api.valar.space/api-docs/mintlify post /operations/spacecraft Creates a spacecraft. # Update a spacecraft lifecycle status Source: https://docs.valar.space/api-reference/spacecraft/update-a-spacecraft-lifecycle-status https://api.valar.space/api-docs/mintlify put /operations/spacecraft/{id}/lifecycle Updates the lifecycle status (Active or Archived) of a spacecraft resolved strictly by id. Returns 404 if it does not exist. # Delete a state vector Source: https://docs.valar.space/api-reference/state-vectors/delete-a-state-vector https://api.valar.space/api-docs/mintlify delete /operations/state-vectors/{id} Deletes a state vector by its unique identifier. Deletion is not allowed if the state vector is linked to an orbit solution (returns 409 Conflict). # Export a state vector as OMM Source: https://docs.valar.space/api-reference/state-vectors/export-a-state-vector-as-omm https://api.valar.space/api-docs/mintlify get /operations/state-vectors/{id}/export-omm Export a state vector in CCSDS OMM v2.0 format with mean Keplerian elements. Uses DSST (Draper Semi-analytical Satellite Theory) for osculating-to-mean element conversion. # Export a state vector as OPM Source: https://docs.valar.space/api-reference/state-vectors/export-a-state-vector-as-opm https://api.valar.space/api-docs/mintlify get /operations/state-vectors/{id}/export-opm Export a state vector in CCSDS OPM v2.0 format. Optionally includes covariance data if available. # Generate a fitted TLE Source: https://docs.valar.space/api-reference/state-vectors/generate-a-fitted-tle https://api.valar.space/api-docs/mintlify get /operations/spacecraft/{spacecraftId}/tle Returns an own-computed TLE at the explicit requested epoch. Uses the latest eligible stored state by epoch: manual/imported states or accepted converged orbit solutions. Propagates with the existing accurate force model and applicable maneuvers, then fits a single-state TLE. This does not retrieve provider TLEs, select a historical state, persist a resource, or start a background job. Required spacecraft force-model configuration must be present. Assigned numeric catalogue IDs through 339999 can be serialized (Alpha-5 above 99999); larger IDs are rejected, never truncated. A missing NORAD ID retains the generator's 99999 placeholder. Requires a valid API key with read:ephemeris permission and access to the spacecraft. Success is text/plain only; an unsupported or malformed Accept header returns 406. Request and generation failures use JSON error envelopes even when Accept is text/plain. Missing credentials or malformed bearer tokens may instead receive an empty 401 with WWW-Authenticate: Bearer. No receiver compatibility or orbit accuracy guarantee is implied. # Generate OEM from a state vector Source: https://docs.valar.space/api-reference/state-vectors/generate-oem-from-a-state-vector https://api.valar.space/api-docs/mintlify post /operations/state-vectors/{id}/generate-oem Generate CCSDS OEM v2.0 format ephemerides from a state vector with specified time range, reference frame, time system, and optional covariance propagation. Maximum time span is 30 days. # Get a state vector by ID Source: https://docs.valar.space/api-reference/state-vectors/get-a-state-vector-by-id https://api.valar.space/api-docs/mintlify get /operations/state-vectors/{id} Retrieves a specific state vector by its unique identifier. # Get the latest state vector for a spacecraft Source: https://docs.valar.space/api-reference/state-vectors/get-the-latest-state-vector-for-a-spacecraft https://api.valar.space/api-docs/mintlify get /operations/state-vectors/latest Retrieves the most recent state vector for a spacecraft. By default, only converged state vectors are returned (imports are always valid, OD results only if converged). Set includeNonConverged=true to include all state vectors. # Import a state vector Source: https://docs.valar.space/api-reference/state-vectors/import-a-state-vector https://api.valar.space/api-docs/mintlify post /operations/state-vectors/import Import a state vector from an external source (OPM or SpaceX OPM format). For OPM format, the spacecraft can be auto-resolved from OBJECT_ID and OBJECT_NAME in the CCSDS metadata when spacecraftId is omitted. SpaceX OPM format requires an explicit spacecraftId. Creates a StateVector only, not an OrbitSolution. # List state vectors for one or more spacecraft Source: https://docs.valar.space/api-reference/state-vectors/list-state-vectors-for-one-or-more-spacecraft https://api.valar.space/api-docs/mintlify get /operations/state-vectors Retrieves a paginated list of state vectors for the specified spacecraft(s), with optional date range filtering. The spacecraftId parameter may be repeated to query multiple spacecraft in a single call (e.g. ?spacecraftId=A&spacecraftId=B); results are merged into a single paginated set. Results are sorted by epoch descending by default. Empty results return 200 with an empty page. # Create a thruster Source: https://docs.valar.space/api-reference/thrusters/create-a-thruster https://api.valar.space/api-docs/mintlify post /operations/spacecraft/{spacecraftId}/thrusters Creates a thruster under a parent spacecraft resolved strictly by id. Type is auto-computed from ISP and rendered UPPER_CASE (DT-17). Returns 404 if the parent spacecraft does not exist. # Delete a thruster Source: https://docs.valar.space/api-reference/thrusters/delete-a-thruster https://api.valar.space/api-docs/mintlify delete /operations/spacecraft/{spacecraftId}/thrusters/{thrusterId} Deletes a thruster resolved strictly by id. Returns 404 if it does not exist. # Get a thruster by id Source: https://docs.valar.space/api-reference/thrusters/get-a-thruster-by-id https://api.valar.space/api-docs/mintlify get /operations/spacecraft/{spacecraftId}/thrusters/{thrusterId} Retrieves a thruster resolved strictly by id. Type is rendered UPPER_CASE (DT-17). Returns 404 if it does not exist. # List thrusters for a spacecraft Source: https://docs.valar.space/api-reference/thrusters/list-thrusters-for-a-spacecraft https://api.valar.space/api-docs/mintlify get /operations/spacecraft/{spacecraftId}/thrusters Retrieves all thrusters for a parent spacecraft resolved strictly by id. Each type is rendered UPPER_CASE (DT-17). Returns 404 if the parent spacecraft does not exist. # Partially update a thruster Source: https://docs.valar.space/api-reference/thrusters/partially-update-a-thruster https://api.valar.space/api-docs/mintlify patch /operations/spacecraft/{spacecraftId}/thrusters/{thrusterId} Updates only the provided fields of a thruster resolved strictly by id. Type is re-computed from ISP and rendered UPPER_CASE (DT-17). Returns 404 if it does not exist. # Ground Track Visualization Source: https://docs.valar.space/features/3d-ground-track Explore spacecraft ground tracks and orbital trajectories in 2D and 3D > For the complete documentation index, see [llms.txt](/llms.txt). Ground Track shows spacecraft positions and trajectories at the selected time on an interactive map or globe. If your account has the consolidated **Operations Map**, open **Map** (`/map`) and follow the [Map guide](/features/map). For these accounts, `/orbits/ground-track` redirects to Map with ground tracks enabled. Accounts outside that rollout retain **Orbits → Ground Track**. VALAR Ground Track with spacecraft paths, view controls, and playback timeline ## Select spacecraft and a view The spacecraft filter determines which trajectories appear. With no explicit filter, the page selects the available spacecraft. Apply your selection to update the view. Spacecraft keep their assigned colors across the map and charts. | Control | Behavior | | - | - | | **2D** (default) | Geographic map covering the entire Earth, including both poles. Shows subsatellite ground tracks. | | **3D** | WGS84 ellipsoid with trajectories at their physical altitudes. Drag to orbit the camera; scroll or pinch to zoom. | | **ECEF** (default) | Earth-fixed coordinates. Available in both views. | | **ECI** | Inertial coordinates, available in 3D. Earth rotates with the selected time. | | **Reset view** | Stop tracking and reset the camera without leaving the page or clearing spacecraft selection. In 3D, fit the available trajectories. | | **Charts** | Open the existing latitude/longitude and coordinate-versus-time charts. | Changing view preserves the playhead and playback. Each view remembers its camera position. Entering 2D selects ECEF; the 3D frame badge identifies the actual inertial frame, such as **GCRF**, when ECI is selected. Different inertial frames cannot share a single inertial scene. Use ECEF or select spacecraft with the same inertial frame. Hover the frame badge for its description and the link to the [reference frame catalog](/platform-overview/reference-frames). ## Geographic backgrounds The map and globe use Valar-hosted, theme-aware monochrome cartography. Operational objects keep their assigned colours; there is no Monochrome / Colored selector. Light and dark mode change the geographic styling automatically. The worldwide basemap retains regional detail through zoom 8. Closer views reuse that detail while operational geometry remains precise; zooming does not introduce finer geographic source data. In 3D, the surface is the WGS84 ellipsoid, not terrain. If a background cannot load, the page reports it and keeps orbital geometry and navigation available. The background loads independently of orbit computation. ## Positions and paths The 2D marker represents the subsatellite point. The 3D marker represents the spacecraft's physical position. Colors identify the same spacecraft in both views. Labels behind Earth are hidden in 3D; 2D labels are decluttered when they overlap. Paths show up to **one hour behind** and **24 hours ahead** of the playhead, limited to the available orbit data. Ground tracks split at the date line and handle polar crossings. The map does not connect gaps, interpolate through declared maneuver boundaries, or extrapolate beyond supplied data. Click a marker or choose **Inspect spacecraft** to see its latitude, longitude and ellipsoidal altitude at the playhead. **Track spacecraft** follows that craft; **Stop tracking** or **Reset view** releases it. Longitude is undefined at an exact pole. Displayed decimal places describe the computed position, not orbit uncertainty; uncertainty is shown as unavailable when it has not been supplied. In 3D, illumination follows the supplied Sun direction and selected epoch. It illustrates geometric sunlight; it is not an eclipse-duration or power analysis product. Earth is withheld in ECI when its orientation is unavailable. ## Navigation | Input | 2D | 3D | | - | - | - | | Drag | Pan | Orbit camera | | Scroll / pinch | Zoom | Zoom | | Right drag / two-finger drag | Pan | Pan camera target | | Arrow keys with the view focused | Pan | Orbit camera | | Plus / minus with the view focused | Zoom | Zoom | The globe uses damped navigation and respects the reduced-motion preference when the view opens. Map and globe remain navigable while trajectories are loading. ## Timeline Ground Track playback controls and UTC playhead Playback starts paused at **300×** speed. The floating toolbar provides: * **Reset to start:** jump to the beginning of the available interval. * **Reverse:** play backward; press again to pause reverse playback. * **Play / Pause:** start or pause forward playback. * **Sync to real-time:** follow the browser clock while it falls within available trajectory data. If it lies outside the data, a message explains why sync is unavailable. * **Timeline slider:** seek to a time within the data interval. Seeking exits real-time sync. * **Speed:** choose 0.5×, 1×, 2×, 5×, 10×, 50×, 100×, 300× or 1000×. Changing speed exits real-time sync. The timestamp is UTC. Playback progresses in elapsed physical seconds and supports a supplied leap second. The browser clock itself cannot represent a leap second. At an interval boundary, ordinary playback wraps; live sync stops when data no longer covers the browser time. ## Data and charts By default, the page requests seven days before and seven days after its reference time, with samples every 60 seconds. Use the time-range presets and past/future controls to change that interval. Paths are prepared in a background worker for a bounded window around the playhead. The map appears while these samples are being computed; it does not wait for the complete orbit response before allowing navigation. The existing five-minute per-spacecraft/time-range cache and request deduplication remain in use. Latitude/longitude, latitude-versus-time and longitude-versus-time charts are available in the Charts panel, with hover values and loading or empty states. **Display quality** notices identify missing or invalid samples, unavailable Earth orientation or illumination, and interpolation gaps. No coordinate or altitude is invented to fill missing data. Orbit propagation accuracy and source freshness remain properties of the selected orbit; geographic background detail does not improve them. ## When the orbit is stale or unusable The map draws each spacecraft from a **fresh** orbit. A spacecraft's [orbit age](/features/orbit-age#orbit-age) is measured from its latest [state vector](/features/state-vectors) — the position and velocity at an epoch you provide through orbit determination, an [OPM](/file-formats/opm) import, or manual entry. As that age grows it crosses two levels in turn — the [degraded level](/features/orbit-age#degraded-level), then the [stale level](/features/orbit-age#stale-level) — and the map reacts differently at each. The track normally draws the moment you open the page; on a stale orbit it waits for you to choose to proceed. What you see depends on the selected spacecraft's orbit age: | Orbit state | What the map shows | | - | - | | **Fresh** (within both levels) | The ground track, globe position, and charts draw normally — nothing extra. | | **Degraded** (past the [degraded level](/features/orbit-age#degraded-level)) | The track draws from the platform-fetched public [TLE](/file-formats/tle), with an inline aging notice above the map reading **This spacecraft's orbit is stale**, the orbit's age (`last determined N days ago`), and the level it crossed (`exceeds your N-day threshold`). When the fallback orbit is itself stale, the notice adds **the public-TLE fallback is also stale**. The track still draws — the notice is a heads-up, not a block. | | **Stale** (past the [stale level](/features/orbit-age#stale-level)) | The track is **held** until you choose to proceed. Above the map, the page shows the same **This spacecraft's orbit is stale** panel — with the age and threshold lines — plus a **Compute anyway** button. Click **Compute anyway** to draw the ground track and globe position from the stale orbit. | | **No usable orbit** | When a selected spacecraft has no orbit data of any kind to draw from, the page shows a panel reading **Can't compute — `{spacecraft}` has no usable orbit**, explaining that **There is no usable orbit data for this spacecraft, so this product can't be computed. Add tracking data to continue**, with an **Add orbit data** button that opens the [Spacecraft](/features/spacecraft-management) page. This is never shown as a raw error. | Both `N` values are whole days — the spacecraft's actual orbit age and your configured stale level. The stale and degraded levels are workspace-wide values set once in **Settings → Orbits → Orbit age** (stale level default `14 days`); the same values govern the [Keplerian-elements plot](/features/orbit-elements-plots) and [AOI overflight](/features/areas-of-interest/overflight-events), changed in one place rather than per surface. See [Orbit age](/features/orbit-age#stale-level) for the workspace-wide policy and the block message. Every spacecraft affected at either level is also named in the unified [orbit-data-age footer](/features/orbit-age#the-orbit-data-age-footer) at the bottom of the page — tagged **Degraded** at the degraded level, or **Blocked** once past the stale level — so you can see which spacecraft are affected at a glance. ## Loading and unavailable data | State | What remains available | | - | - | | Renderer loading | A short map or globe placeholder while the local renderer loads. | | Trajectories loading | Geographic navigation; a loading indicator and disabled playback until data arrives. | | Paths being prepared | Current positions and navigation, with a progress message. | | Missing physical samples | Geographic navigation and an explanation; unsupported positions are withheld. | | Background unavailable | Operational geometry, navigation and a background status message. | | WebGL unavailable | An explanation directing you to 2D or the numerical state panel. | | Charts loading | Chart skeletons; the geographic view remains available. | ### Geographic context The map and globe include country borders and place names. Labels adjust with zoom to keep the display readable. The 2D map stays within the poles even at maximum zoom-out, filling the available space. Satellite imagery is historical background context; its date and resolution are shown on the map. If an orbit request fails, Ground Track shows the failure and offers **Retry trajectories**. A spacecraft with a usable public TLE can be plotted without a primary state vector, subject to the same backend freshness policy. A stale-orbit refusal still requires an explicit **Compute anyway** decision. # API Keys Source: https://docs.valar.space/features/api-keys Create and manage API keys for programmatic access to the VALAR platform > For the complete documentation index, see [llms.txt](/llms.txt). API Keys allow you to access the VALAR API programmatically. Use them to integrate VALAR with your own systems, automate workflows, or build custom applications. **Route:** `/settings` ## Page Layout The API Keys section is located in the Settings page. It displays all your organization's API keys in a table with management actions. Api Key ## API Keys Table The table shows all API keys for your organization: | Column | Description | | - | - | | **Name** | The descriptive name you assigned to the key | | **Key Prefix** | First 12 characters of the key (full key is never shown after creation) | | **Status** | Active (green) or Revoked (red) | | **Expires** | Expiration date, or "Never" if no expiry set | | **Last Used** | When the key was last used to make an API request | ### Actions Menu Click the three-dot menu on any row to access these actions: | Action | Description | | - | - | | **Edit** | Modify key name, status, or IP restrictions | | **Rotate** | Generate a new secret (invalidates the old one) | | **View Audit Log** | See all API requests made with this key | | **Delete** | Permanently delete the key | ## Creating an API Key Click **Create API Key** to open the creation dialog. This is a two-step process. ### Step 1: Configure Key Settings | Field | Description | | - | - | | **Name** | A descriptive name to identify this key (e.g., "Production API") | | **Expiration** | When the key should expire | | **IP Allowlist** | Optional IP addresses that can use this key | **Expiration Options:** * 1 Day * 1 Week * 1 Month * 3 Months * 1 Year * No Expiry **IP Allowlist:** Restrict which IP addresses can use this key. Enter individual IPs or CIDR ranges (e.g., `192.168.1.1` or `10.0.0.0/24`). Maximum 50 entries. Leave empty to allow all IPs. ### Step 2: Copy Your Key After clicking **Create Key**, your new API key is displayed. **Important:** This is the only time you will see the full API key. Copy it immediately and store it securely. You cannot retrieve it later. * Use the **copy button** to copy the key to your clipboard * Use the **eye icon** to show/hide the key value * Click **Done** when you've saved the key ## Editing an API Key Click **Edit** from the actions menu to modify an existing key. | Field | Description | | - | - | | **Name** | Update the display name | | **Status** | Set to Active or Revoked | | **IP Allowlist** | Add or remove IP restrictions | Changing status to **Revoked** immediately stops all API access using this key. Applications will receive authentication errors until the key is re-enabled. ## Rotating an API Key Rotation generates a new secret value for the key while keeping the same name and settings. Use this to periodically refresh credentials or if you suspect a key may be compromised. **To rotate a key:** 1. Click **Rotate** from the actions menu 2. Type the key name to confirm 3. Click **Rotate Key** 4. Copy the new key value (shown only once) The old key is **immediately invalidated** when you rotate. Update your applications with the new key before they attempt to make API requests. ## Deleting an API Key Permanently remove an API key when it's no longer needed. **To delete a key:** 1. Click **Delete** from the actions menu 2. Type the key name to confirm 3. Click **Delete Key** Deletion is **permanent and cannot be undone**. All applications using this key will immediately lose access. ## Viewing Audit Logs The audit log shows all API requests made with a specific key. Use it to monitor usage, troubleshoot issues, or investigate security concerns. Click **View Audit Log** from the actions menu to open the dialog. | Column | Description | | - | - | | **Timestamp** | Date and time of the request | | **Method** | HTTP method (GET, POST, PUT, DELETE, etc.) | | **Endpoint** | API path that was accessed | | **IP Address** | Source IP of the request | | **Country** | Country flag based on IP geolocation | | **Status** | HTTP response code (green for success, red for errors) | **Navigation:** * Click **Refresh** to fetch the latest logs * Use **Previous/Next** buttons to navigate through pages ## Security Best Practices Follow these guidelines to keep your API keys secure: | Practice | Description | | - | - | | **Store securely** | Use environment variables or secrets managers, never commit keys to code | | **Use IP allowlisting** | Restrict production keys to known IP addresses | | **Set expiration dates** | Use time-limited keys for temporary access or integrations | | **Rotate periodically** | Generate new keys regularly, especially for production use | | **Monitor audit logs** | Review usage patterns and investigate unexpected activity | | **Revoke unused keys** | Delete or disable keys that are no longer needed | | **Use descriptive names** | Name keys by purpose (e.g., "CI/CD Pipeline", "Production Server") | ## Using Your API Key Include your API key in the `Authorization` header using the Bearer scheme: ``` Authorization: Bearer vsp_sk_your_key_here ``` All API keys use the `vsp_sk_` prefix to identify them as VALAR Space secret keys. ## Environment grant Each API key is granted access to exactly **one environment** — either `OPERATIONS` or `MISSION_ANALYSIS` — and that grant is fixed when the key is created. When no environment is specified at creation, the key is granted `OPERATIONS`. The environment grant is **immutable**: it is never changed after the key is created. There is no way to move an existing key to a different environment — create a new key for the other environment instead. A key may only be used against routes for the environment it was granted. Calling a route for a different environment with a mismatched key is rejected with a **403** — *"API key is not granted access to this environment."* ## Limits | Limit | Value | | - | - | | **Maximum keys per org** | 20 | | **Maximum IPs per key** | 50 | # Create an AOI Source: https://docs.valar.space/features/areas-of-interest/create-aoi Define an Area of Interest by drawing on the map, typing coordinates, or pasting GeoJSON > For the complete documentation index, see [llms.txt](/llms.txt). Click **New AOI** in the top bar from either the [AOI Overview](/features/areas-of-interest/overview) or [AOI Map](/features/areas-of-interest/map) page to start creating an AOI. The button always lands you on the AOI Map first, then opens a method picker so you choose how to define the geometry: by drawing on the map, by typing coordinates into a form, or by pasting a GeoJSON document. **Save** persists the AOI; an automatic recompute fires once you save so the events forecast populates immediately. **Route:** Opened from the **New AOI** button on the [AOI Overview](/features/areas-of-interest/overview) page or the [AOI Map](/features/areas-of-interest/map) page. Clicking the button from either page navigates to `/aoi/map` first and then opens the method picker. ## Method Picker Create-AOI method picker with the Draw, Coordinate form, GeoJSON, and KML cards The picker is a modal headed **Create a new AOI** with the subtitle *Pick how you want to define the area of interest.* It offers four cards — none is preselected: | Card | When to use | | - | - | | **Draw on map** | Sketch the AOI directly on the map. Use this when you have a visual reference and want to define the shape interactively. | | **Coordinate form** | Type latitude / longitude coordinates by hand. Use this when you have precise vertices in mind, or when you are converting from another system. | | **GeoJSON** | Paste or upload a GeoJSON file. Use this when you already have a GeoJSON document from QGIS, ArcGIS, or another GIS tool. | | **KML** | Upload a `.kml` or `.kmz` file. Use this when you have an area exported from Google Earth or another GIS tool as KML. | Click a card to pick the method; the picker closes and the corresponding creation surface opens. Click **Cancel**, click outside the modal, or press **Escape** to dismiss the picker without choosing. ## Draw on Map Picking **Draw on map** keeps you on the AOI Map and surfaces a floating toolbar in the top-left corner of the canvas. The toolbar segments are: | Segment | Behaviour | | - | - | | **Polygon** | Click each vertex on the map; double-click or click the first vertex to close the shape. | | **Rectangle** | Click and release for the first corner, then click and release for the opposite corner. | | **Disk** | Click the centre, drag to the desired radius, and release. The radius is computed as the great-circle distance from the centre to the furthest sketched point. | A helper text reading `Draw a shape on the map to continue` renders beneath the toolbar until the shape is complete. Once you finish the shape, a small popover anchors at the top-right corner of the map with the AOI form (described below). The shape stays visible on the map and updates live when you adjust fields. ## Coordinate Form Picking **Coordinate form** opens the AOI form in a centered modal dialog headed **New AOI — Coordinate form**. As you type vertices, a dashed sky-blue preview of the shape renders on the world map behind the dialog so you can sanity-check the geometry against the basemap. The geometry editor at the top of the form lets you pick the primitive (Polygon, Disk, or Multipolygon) and enter the structured fields: | Primitive | Inputs | | - | - | | **Polygon** | A list of vertices, each a latitude (`-90..90`) and longitude (`-180..180`) pair. **Add vertex** extends the list. | | **Disk** | Centre latitude, centre longitude, and a radius (in kilometres in the form; the wire format uses metres internally). | | **Multipolygon** | Two or more piece blocks, each a polygon vertex list. **Add piece** extends the list. | A polygon with fewer than 3 vertices surfaces `Add at least 3 vertices to continue` and disables **Save** until the geometry is valid. The form caps each polygon at 100 vertices. ## GeoJSON Picking **GeoJSON** opens the AOI form in a centered modal dialog headed **New AOI — GeoJSON**. A textarea + file picker at the top accepts your GeoJSON; the live preview on the map behind the dialog updates as soon as the document parses. | Control | Behaviour | | - | - | | **GeoJSON textarea** | Paste any GeoJSON document. The placeholder reads *Paste a Polygon / Disk / MultiPolygon GeoJSON Feature here…*. Live preview updates on every keystroke. | | **Upload .geojson file** | Opens the file picker. Accepts `.geojson` and `application/geo+json` content. Files larger than 1 MB are rejected before being read; the textarea is not populated. | While the textarea is empty, a helper line reads `Paste valid GeoJSON to continue`. While a parse fails, the helper reads `GeoJSON must be a Polygon, Disk, or MultiPolygon`. While a file is too large, the helper reads `GeoJSON file must be 1 MB or smaller`. See the [GeoJSON file format](/file-formats/aoi-geojson) page for the supported RFC 7946 subset. ## KML Picking **KML** opens the AOI form in a centered modal dialog headed **New AOI — KML**. Unlike the GeoJSON flow there is no paste box — KML areas (and especially `.kmz` archives) are file-based, so the KML card is upload-only. Click **Upload .kml or .kmz file** to open the file picker; it accepts `.kml` and `.kmz` files. VALAR reads a single area from the file and previews it on the map behind the dialog, editable just like a drawn or GeoJSON-imported area. Before you choose a file, a muted helper reads `Select a .kml or .kmz file` and **Save** stays disabled. The KML file's own name, description, and styling are ignored — you name and colour the AOI in the form below, exactly as for the other methods. If a file cannot be imported, an inline red message on the card explains why (see [Validation Errors](#validation-errors)). The full catalogue of accepted geometry, what is silently dropped, the size limits, and each error meaning lives on the [KML and KMZ file format](/file-formats/kml) page. ## Shared Form Fields Regardless of the creation method, every AOI form surfaces the same sections beneath the geometry block. ### Identity | Field | Description | | - | - | | **Name** | Required. Up to 100 characters. Must be unique within the workspace. | | **Description** | Optional. Up to 100 characters with a live counter beneath the field. | | **Tags** | Optional. Up to 20 chips, each ≤64 characters. Press **Enter** or `,` to commit a chip; press **Backspace** on an empty input to remove the last chip. | | **Color** | A 12-swatch palette: Emerald, Teal, Sky, Blue, Indigo, Violet, Fuchsia, Rose, Red, Orange, Amber, Lime. Defaults to **Emerald**. | ### Lifecycle | Field | Description | | - | - | | **Active** | Default on. When off, the AOI generates no overflight events even if it has a populated schedule. | | **Validity start (UTC)** | Optional. When set, also requires **Validity end (UTC)**. | | **Validity end (UTC)** | Optional. When set, also requires **Validity start (UTC)**. Must be strictly after the start. | The create form is paired — leave both bounds empty for an always-active AOI, or set both together. To produce a one-bound (open-ended) window, create the AOI without bounds, then edit it via the dialog on the [AOI Overview](/features/areas-of-interest/overview) page, which exposes a per-bound **Set / Open-ended** switch. All times are UTC. ## Validation Errors The form validates input inline before letting you **Save**. The error strings are surfaced verbatim: | Error | What triggered it | | - | - | | `Name is required` | The Name field is blank or contains only whitespace. | | `Both validity dates required, or neither` | Only one of the validity bounds is filled in. | | `Validity end must be after validity start` | Both validity bounds are set and the end is at or before the start. | | `Up to 20 tags, each ≤64 characters` | Either the tag count exceeds 20 or a single tag exceeds 64 characters. | | `Add at least 3 vertices to continue` | The Coordinate-form polygon has fewer than 3 vertices. | | `GeoJSON must be a Polygon, Disk, or MultiPolygon` | The pasted or uploaded GeoJSON could not be parsed as a supported AOI primitive. | | `GeoJSON file must be 1 MB or smaller` | The uploaded `.geojson` file exceeds 1 MB. | | `Polygon edges must not intersect` | The polygon has self-intersecting edges. | | `Polygon must have at least 3 distinct vertices` | The polygon has fewer than 3 distinct vertices after submission. | | `Polygon must have at most 500 distinct vertices` | The polygon exceeds the 500-vertex backend cap (the Coordinate form caps at 100). | | `Polygon must have positive area` | The polygon is degenerate (zero area). | | `Polygon must not span more than a hemisphere` | The polygon extent is too large for the spherical model. | | `MultiPolygon must have at least 2 disjoint pieces` | A multipolygon needs at least 2 pieces; use a single polygon for one piece. | | `MultiPolygon must have at most 50 disjoint pieces` | The multipolygon exceeds the 50-piece cap. | | `MultiPolygon pieces must have disjoint interiors` | Two or more multipolygon pieces overlap. | | `Disk radius must be greater than 0 m and at most 500,000 m` | The disk radius is outside the accepted range. | | `Latitude must be between -90° and 90°` | A latitude input is outside `[-90, 90]`. | | `Longitude must be between -180° and 180°` | A longitude input is outside `[-180, 180]`. | | `This primitive is not supported. Supported primitives: Polygon, CircularDisk, MultiPolygon.` | The geometry is a primitive outside the supported subset. | | `GeoJSON must be a Polygon, Disk, or MultiPolygon` | The pasted or uploaded GeoJSON is malformed, or is a type outside the supported subset — including a Polygon with holes, a `GeometryCollection`, a `Point` / `MultiPoint`, a `LineString` / `MultiLineString`, or a `FeatureCollection` that does not hold exactly one Feature. | | `GeoJSON file must be 1 MB or smaller` | The pasted or uploaded GeoJSON exceeds 1 MB. | | `The file could not be read as KML` | The uploaded `.kml` / `.kmz` is not valid KML, or the KML carries a `DOCTYPE`. | | `The KML area must be a Polygon or set of Polygons` | The KML geometry is a point, a line, or a mix that is not all polygons. | | `This KML file contains multiple areas — import a single area` | The KML file has more than one placemark / area. | | `No supported area (Polygon) was found in the KML` | The KML file, or the `.kmz` archive, has no importable polygon inside. | | `The KML or KMZ file is too large to import` | The `.kmz` exceeds 5 MB, or the extracted KML exceeds 1 MB. | | `This KML/KMZ file is encrypted and cannot be read` | The `.kmz` archive is password-protected. | | `An AOI with this name already exists in this workspace.` | An AOI with the same name already exists in the workspace. | | `End date must be after start date.` | The validity window's end is at or before the start. | | `Provide either structured geometry or GeoJSON, not both` | Both a structured geometry block and a GeoJSON body were submitted. | ## Saving and Cancelling Click **Save** to create the AOI. The button reads **Saving…** while the request is in flight. On success the form closes, the new AOI is selected on the map, and an automatic recompute fires so the events forecast populates immediately. If the save rejects, an inline banner above the form reads `Couldn't save AOI — try again`; the banner clears the moment you edit any field. Click **Cancel** to discard the draft. If you have unsaved changes, a confirmation dialog **Discard changes** appears with the body `Discard your changes? Your edits will be lost.` Choose **Keep editing** to return to the form or **Discard** to close it. A non-dirty cancel routes straight to the closing transition. ## Editing an Existing AOI To edit an existing AOI, open the [AOI Overview](/features/areas-of-interest/overview) page, select the AOI, and click the pen icon in the identity hero to enter edit mode. Identity fields become inline-editable; the validity window opens an edit dialog from the geometry block. The full editing workflow — including the kebab actions for **Set active**, **Set inactive**, and **Delete AOI** — is documented on the Overview page. Editing the geometry, the validity window, or the **Active** flag automatically triggers a recompute. Editing only identity fields (name, description, tags, colour) does not trigger a recompute; existing events stay in the list. ## Deleting an AOI Deletion is initiated from the kebab menu in the identity hero on the [AOI Overview](/features/areas-of-interest/overview) page, or from the kebab menu on a hovercard on the [AOI Map](/features/areas-of-interest/map) page. Both paths surface a **Delete AOI** confirmation dialog; click **Delete** to confirm or **Cancel** to keep the AOI. After deletion the page navigates to the next remaining AOI, or to the empty state if it was the only one. ## Related Pages * [Areas of Interest overview](/features/areas-of-interest/overview) — read and edit an existing AOI in depth. * [AOI Map](/features/areas-of-interest/map) — the world map where every creation flow begins. * [Overflight events](/features/areas-of-interest/overflight-events) — the 7-day forecast that follows every AOI save. * [GeoJSON file format](/file-formats/aoi-geojson) — the supported RFC 7946 subset accepted by the **GeoJSON** flow. * [KML and KMZ file format](/file-formats/kml) — the KML / KMZ geometry accepted by the **KML** flow. # AOI Map Source: https://docs.valar.space/features/areas-of-interest/map See every Area of Interest in the workspace on a single world map, inspect any AOI in a hovercard, and start any creation flow from the same surface > For the complete documentation index, see [llms.txt](/llms.txt). The **AOI Map** is a full-bleed world map that plots every Area of Interest in the workspace. Use it to see your AOIs in their geographic context, click any shape to open a compact summary hovercard, and start a new AOI from the same surface. The map shares the top bar and the right-docked AOI list with the [AOI Overview](/features/areas-of-interest/overview) page so navigating between the two routes is seamless. **Route:** `/aoi/map` Open the page via the **AOIs** entry in the sidebar, then switch to the map view, or click any **New AOI** button anywhere in the AOI surface — that button always lands you on the map first. ## Page Layout AOI Map page with multiple AOIs plotted on the world basemap The page is a three-region layout: | Region | Contents | | - | - | | **Top bar** | Tags filter, status filter, **New AOI** button, **Cheatsheet** button, and a toggle that collapses the right-hand list pane. | | **Map canvas** | Full-bleed, theme-aware monochrome basemap showing each AOI in its assigned colour. Pan / zoom / click are all native map interactions. | | **Right-docked list pane** | The same AOI list used on the Overview page, with the same search box, filters, and rows. | The map respects your light / dark theme, and the camera opens at a full-world view. Drag to pan; scroll or pinch to zoom; click the zoom buttons in the top-right corner for click-driven zoom. The camera is clamped to the WGS84 world envelope so pan cannot wrap the globe. When your browser does not support WebGL or the map is otherwise unavailable, the canvas is replaced by a fallback element reading `Map unavailable — couldn't load in this browser`. ## AOI Shapes on the Map Every AOI in the workspace renders as a filled shape on the basemap, painted in the AOI's chosen palette colour. Hovering a shape thickens its outline and switches the cursor to a pointer. Clicking the shape selects the AOI: * The URL updates to `/aoi/map?selected=` so the selection survives reloads. * The shape's outline thickens and the fill darkens slightly so the active AOI reads clearly against the basemap. * A hovercard opens, anchored to the centroid of the shape, summarising the AOI and its next overflights. On reload, a valid `?selected=` value restores the selected AOI. If the value is bogus or no longer identifies an available AOI, selection falls back to another available AOI instead of leaving the surface without a selection. When the workspace has no AOIs, the canvas surfaces a single floating banner reading `No AOIs yet — click + New AOI to create one`. ## AOI Hovercard AOI hovercard with name, status, next overflight, 7-day timeline, and Upcoming list The hovercard is a floating panel anchored to the AOI's centroid by a dashed leader line. The leader line tracks the map's pan and zoom, so the hovercard stays connected to its shape as you move the camera. From top to bottom, the hovercard composes: | Section | Contents | | - | - | | **Header** | Colour swatch, AOI name, status pill, and a vertical three-dot kebab menu (described below). | | **Next overflight** | The earliest future event for any spacecraft. Shows the spacecraft's name + swatch, a relative countdown (e.g. `in 2h 30m`), the peak elevation, and the pass duration. Empty branch reads `No upcoming overflights in the next 7 days`. | | **7-day timeline** | Compact per-spacecraft timeline that mirrors the one on the [Overview](/features/areas-of-interest/overview) page. Empty branch reads `No upcoming overflights in the next 7 days`. | | **Upcoming · next 3** | The next three events after the hero, listed with the spacecraft name, the relative entry time, and the peak elevation. | | **Footer** | An **Open details** button that navigates to the [AOI Overview](/features/areas-of-interest/overview) page for the same AOI. | The hovercard closes when you click outside it, press **Escape**, or click the colour-swatch shape again. ### Kebab Menu Actions The kebab menu in the hovercard offers three actions: | Action | Behaviour | | - | - | | **Set active / Set inactive** | Label flips with the current state. Setting **Inactive** pauses the AOI — no events are generated. Setting **Active** re-enables forecasting. | | **Edit AOI** | Navigates to the [AOI Overview](/features/areas-of-interest/overview) page for this AOI. You enter edit mode on the Overview page by clicking the pen icon in the identity hero. | | **Delete AOI** | Opens a confirmation dialog **Delete AOI** with the body `This will permanently delete "". This action cannot be undone.` Click **Delete** to confirm or **Cancel** to keep the AOI. | After deletion the shape disappears from the map and the hovercard closes. A toast confirms `AOI was deleted`. ## Creating an AOI From the Map Click **New AOI** in the top bar (or **Create your first AOI** on the empty-workspace list pane) to start the creation flow. The button drops you into the method picker described on the [Create an AOI](/features/areas-of-interest/create-aoi) page; the map stays visible behind the picker so you keep your geographic reference. The three methods route to different surfaces on this same map: * **Draw on map** — a floating toolbar appears in the top-left corner. Draw the shape directly on the canvas; once the shape is complete, a compact form anchors at the top-right corner of the map. Save the AOI and the new shape stays plotted on the map, selected, with its hovercard open. * **Coordinate form** — a centered modal dialog opens. As you type vertices (or centre + radius for a disk), a dashed sky-blue preview of the geometry renders live on the map behind the dialog. * **GeoJSON** — a centered modal dialog opens with a textarea + file picker. As you paste or upload GeoJSON, the dashed live preview updates on the map behind the dialog. For the full set of fields, validation rules, and error strings, see the [Create an AOI](/features/areas-of-interest/create-aoi) page. When a save rejects, an inline banner above the form reads `Couldn't save AOI — try again`. The banner clears the moment you edit any field. Cancelling a dirty form opens a confirmation dialog **Discard changes** with the body `Discard your changes? Your edits will be lost.` — choose **Keep editing** to keep the form open, or **Discard** to close it. ## Shared Top Bar and List Pane The top bar and the right-docked AOI list pane are identical to those on the [AOI Overview](/features/areas-of-interest/overview) page: * The **Tags** and **Status** filters in the top bar narrow the AOIs listed in the right pane. They do *not* hide shapes on the map — every AOI in the workspace is always plotted. * The list pane carries its own **Search AOIs** input that filters the rows the pane renders. * The collapse toggle at the right edge of the top bar hides the list pane so the map takes the full page width. Click it again to bring the list back. Selecting an AOI from the list opens the same hovercard you would get by clicking the shape directly. ## Reference Frame AOI shapes are defined by **WGS84 geodetic** coordinates (latitude / longitude on the WGS84 ellipsoid) and rendered on a Mercator basemap. Coordinates surfaced in the hovercard, the geometry properties, and the per-event detail use the same frame. ## Related Pages * [Areas of Interest overview](/features/areas-of-interest/overview) — read and edit one AOI in depth, including the inline-edit affordances in the identity hero and the validity-window edit dialog in the geometry block. * [Create an AOI](/features/areas-of-interest/create-aoi) — the full reference for the Draw / Coordinate form / GeoJSON creation flows. * [Overflight events](/features/areas-of-interest/overflight-events) — the per-event detail panel and the recompute mechanics that sit behind every AOI's events forecast. * [GeoJSON file format](/file-formats/aoi-geojson) — accepted geometry types for AOIs created from a GeoJSON document. # Off-nadir Opportunities Source: https://docs.valar.space/features/areas-of-interest/off-nadir-opportunities Turn on off-nadir opportunities for an area of interest, and read the bounded / caveated / not assessable geometric assessment it adds to each one > For the complete documentation index, see [llms.txt](/llms.txt). An **off-nadir opportunity** is an overflight opportunity a payload reaches only by slewing away from **nadir** — straight down — rather than testing access with the payload pointed only directly overhead. Switch it on for an area of interest to see every opportunity the payload's declared off-nadir pointing limits allow, each carrying a geometric assessment of its own. **Route:** The **Include off-nadir opportunities** switch is in the **Edit AOI** dialog, opened via the pencil icon in the identity hero on the [AOI Overview](/features/areas-of-interest/overview) page (the reading it adds appears in the events surface on both [AOI Overview](/features/areas-of-interest/overview) and [Overflight Events](/features/areas-of-interest/overflight-events)). **This reading is geometric only.** A **bounded** or **caveated** assessment means that, purely as a matter of geometry, the area of interest falls within the payload's recorded pointing limits during the stretch of time reported. It is **not** a statement that the spacecraft can be commanded to point there, nor that it would be free to do so. Agility, attitude, power, thermal, and scheduling feasibility are all real constraints this reading does not model. VALAR states it on screen exactly this way: "This is a geometric bound on the look angle only. It does not account for agility, attitude, power, thermal or scheduling feasibility." ## Turning It On The **Include off-nadir opportunities** switch is set **per area of interest**, under **Status & validity** in the **Edit AOI** dialog. Off by default. Turning it on recomputes that area of interest's overflight forecast, adding every opportunity the payload can be pointed at — not only those directly overhead. With the switch off, the events surface is exactly what it is everywhere else in the product: no off-nadir reading, no **Access** control, and nothing to opt back out of. Once it's on, [Filtering by Access](/features/areas-of-interest/overflight-events#filtering-by-access) narrows the list to **All**, **Nadir**, or **Off-nadir only** — choosing **Nadir** reproduces the list exactly as it stood before you switched this on. ## The Assessment Selected opportunity's detail panel, showing the Off-nadir assessment, footprint sweep, profile cards, and solar readouts Every off-nadir opportunity carries a one-word assessment on the **remediability axis** — not how good the opportunity is, but what, if anything, you can do about the bound: | Assessment | What it means | What you can do | | - | - | - | | **Bounded** | The geometry is clean. Nothing narrows or blocks the bound. | Nothing — there is nothing to chase. | | **Caveated** | Something **irreducible** narrows the bound. Read the reason. | No action removes it — it is a property of the geometry itself, not a gap in the data. | | **Not assessable** | Something **fixable** stopped the bound from being placed at all. | Read the reason — it names the missing thing, so you can tell whether the fix is yours (supply the payload's pointing limits) or Valar's (classify those limits for release, or refresh the orbit). | The assessment reports validity and provenance only. It never reports how good the opportunity is for imaging, and it is never a verdict on whether the spacecraft can be tasked to point there — see the disclaimer above. Neither the **caveated** nor the **not assessable** glyph carries any colour or emphasis, and neither uses a warning or error style — deliberately so. A red or amber treatment would read as "cleared to task" or "do not task," a judgement this reading never makes. ## Vocabulary | Term | Meaning | | - | - | | **Nadir** | Straight down from the spacecraft to the ground — the payload's default pointing direction. | | **Off-nadir (look) angle** | How far the payload's boresight is pointed away from nadir to reach a target. | | **Slewing** | The payload pivoting its boresight away from nadir, toward a target it would otherwise miss. | | **Along-track / cross-track** | The two axes a payload's off-nadir pointing limits are declared against — along the spacecraft's direction of travel, and perpendicular to it. | | **Off-nadir pointing limits (the envelope)** | The payload's declared maximum slew in each direction — the bound this reading tests opportunities against. | | **Qualifying interval** | A contiguous stretch of time, within an opportunity, during which the area of interest genuinely falls inside the payload's enlarged (off-nadir) field of view. | | **Envelope window** | The outer span from the earliest to the latest qualifying interval — the widest bracket the opportunity could qualify within. | | **Time within limits** | The total duration actually inside the payload's pointing limits — the sum of the qualifying intervals, deliberately not the width of the envelope window, because that would count the gaps. | | **Nadir vs. off-nadir-only opportunity** | A **nadir** opportunity is one the payload can access without slewing at all. An **off-nadir-only** opportunity exists solely because the payload can be pointed off-nadir — it has no straight-down window of its own. | | **Declared slew axes** | Which axis, if any, an opportunity's off-nadir assessment relied on the payload's declared pointing limits for. Reads **Along-track**, **Cross-track**, **Along-track · Cross-track** (both, in that fixed order), or **None** — depending on which of the payload's declared pointing limits independently shaped the bound. Both axes are now checked independently, so either can be named alone or together. | ## States You Might See Alongside the assessment, an off-nadir opportunity can land in one of several states. Each names what to chase — never a generic failure: | State | What it means | What to chase | | - | - | - | | **Pointing limits on file, not yet cleared for release** | The payload's off-nadir pointing limits exist but haven't been classified for release yet. The envelope window, the qualifying intervals, and every timing on this opportunity are withheld entirely — never shown coarsened. | Valar — get the limits classified for release. | | **Orbit too old to place the bound** | The orbit this opportunity was assessed against is too old to place a trustworthy bound. | Refresh the orbit — a fresher [state vector](/features/state-vectors) resolves it. | | **Predates off-nadir assessment** | The opportunity was computed before off-nadir access existed for this area of interest. Its other values are unchanged — nothing about it has regressed. | Nothing to chase on the opportunity itself — recompute the area of interest to bring it current. | | **Composition not yet supported for this payload's aperture shape** | Composition isn't available for this payload's shape yet. The payload's declared pointing limits use a non-isotropic aperture (rectangular, elliptical, or polygon with unequal extents), and composing its two axes into one slew envelope isn't supported for that shape yet. | Nothing today — this is a capability gap, not missing or misclassified data. The payload's off-nadir limits are still saved; only the automatic envelope mint is deferred until Valar extends composition support to this aperture shape. | A GSD reading that falls outside its validated domain at this look angle is a related but separate state, documented under [Availability states](/features/areas-of-interest/overflight-events#availability-states) on the Overflight Events page. ## Related Pages * [Overflight events](/features/areas-of-interest/overflight-events) — the full opportunity list, the per-event detail panel, and the Off-nadir group's field-by-field reading. * [Areas of Interest overview](/features/areas-of-interest/overview) — the page hosting the Edit AOI dialog where the switch lives. * [State vectors](/features/state-vectors) — refresh an orbit that is too old to place the bound. # Overflight Events Source: https://docs.valar.space/features/areas-of-interest/overflight-events Read predicted spacecraft overflight events for an Area of Interest on a 7-day heatmap, select any opportunity for its full per-event detail, and trigger recomputes > For the complete documentation index, see [llms.txt](/llms.txt). An **opportunity** is a predicted access window during which a payload's field of view (FOV) footprint overlaps the AOI. Each opportunity is attributed to the specific payload whose FOV produced the access, shown alongside the spacecraft that carries it. The events surface lives at the bottom of the [AOI Overview](/features/areas-of-interest/overview) page; it visualises every opportunity in a 7-day window on a heatmap, and opens the selected opportunity's full detail in a panel beneath it. **Route:** Visible on the **Events** band of the [AOI Overview](/features/areas-of-interest/overview) page once you select an AOI. ## Payload Configuration Changes The forecast records the payload configuration used for each spacecraft. Adding, removing, or changing its field-of-view geometry or off-nadir pointing limits marks that spacecraft's stored opportunities as no longer current. The AOI shows **AOI changed since last computed** and the affected spacecraft is not counted or shown as an active opportunity until a recompute completes. Other spacecraft remain available. A payload name, mount position, or optics-only edit does not make the forecast stale. ## Events Surface Layout The events surface composes a header of filters plus the **Recompute** and **Provenance** actions, a 7×24 opportunity heatmap, and the selected opportunity's detail panel: | Element | Description | | - | - | | **Payload filter** | Multi-select dropdown. Selecting one or more payloads narrows the heatmap to those instruments. | | **Spacecraft filter** | Multi-select dropdown. Selecting one or more spacecraft narrows the heatmap to those vehicles. | | **Recompute** button | Refreshes the 7-day overflight schedule across every spacecraft in the workspace. | | **Provenance** button | Opens a dialog showing what the forecast was built from — the orbital state, attitude, payload, and configuration inputs recorded per spacecraft, each checked against that spacecraft's value today. See [Provenance](#provenance) below. | | **Include off-nadir opportunities** switch | Set per area of interest, in the **Edit AOI** dialog (open it with the pencil icon in the identity hero). Off by default. Surfaces opportunities the payload can be pointed at rather than only those directly overhead, and recomputes this area of interest's overflight forecast. See [Off-nadir Opportunities](/features/areas-of-interest/off-nadir-opportunities) for the full reading. | | **Access** control | Appears once off-nadir opportunities are switched on, beside **Provenance**. Filters the heatmap to **All**, **Nadir**, or **Off-nadir only**. Defaults to **All**. See [Filtering by Access](#filtering-by-access) below. | | **7×24 opportunity heatmap** | A density grid of the coming 7 days (rows) × 24 UTC hours (columns) — the darker a cell, the more opportunities start in that hour. Click a cell to scope the view to that day/hour and select an opportunity from it. | | **Detail panel** | Shows the selected opportunity's full per-event detail. See [Selecting an Opportunity](#selecting-an-opportunity) below for how a selection is made. | With off-nadir opportunities switched off, the events surface shows exactly what it shows today — no off-nadir reading, no **Access** control, and no placeholder for either. The switch's own on/off state is where that is expressed; no row anywhere carries a dash for being off. For an **Inactive** AOI, the **Recompute**, **Provenance**, **Payload**, and **Spacecraft** controls are absent rather than disabled. The guidance card reads **AOI is inactive** and `Reactivate this AOI to see upcoming overflights.` ## 7×24 Opportunity Heatmap The heatmap spans the `now…now+7d` window as a **density grid**: 7 rows, one per day, × 24 columns, one per UTC hour — 168 cells in total. Each row is labelled with its UTC date (e.g. `Jul 25`); each column represents one UTC hour of the day. A cell's **shade** reflects how many opportunities start in that hour — an hour with no opportunities renders as a plain, empty cell, and the shade darkens as the count rises toward the busiest hour in the current 7-day window. Click any non-empty cell to **scope** the view to just that day/hour bucket — the clicked cell highlights with a ring — and to select an opportunity from it (see [Selecting an Opportunity](#selecting-an-opportunity) below). A **Show all opportunities** control appears once a bucket is scoped; click it to clear the scope and return to the full 7-day window. The payload and spacecraft filters apply to the heatmap — narrowing either filter re-bins it to the matching opportunities. ## Selecting an Opportunity Clicking a heatmap cell scopes the view to that day/hour bucket and automatically selects the first opportunity in it, loading it into the detail panel below. When a bucket holds more than one opportunity, a compact preview list appears beneath the grid — one row per opportunity, each showing the spacecraft, the payload, and the UTC entry time — so you can pick a different one from the same bucket. Hovering an occupied cell shows the same preview rows in a tooltip, without needing to click first. Only one opportunity is selected at a time — picking another preview row, or clicking a different cell, swaps the selection. The **Show all opportunities** control (above) also clears the scope and reselects the very first opportunity across the full 7-day window. If your selected opportunity's window closes and drops out of the forecast, the surface selects the next opportunity in its place and notes **Your selected opportunity left the window — showing the next one instead.** The detail panel renders **beside** the heatmap on viewports wider than \~768 px and **beneath** it on narrower viewports. When a spacecraft filter is active, an `N of M shown` indicator appears beneath the heatmap so you always know how many opportunities the filter is hiding. ## Per-Event Detail Selected opportunity detail with the payload footprint, geometry profile cards, and solar conditions ### Off-nadir Once [off-nadir opportunities are switched on](#events-surface-layout) for this area of interest, the detail panel gains an **Off-nadir** group, reporting whether this opportunity's payload pointing falls inside the payload's declared off-nadir pointing limits — purely a statement about geometry, never a promise that the spacecraft can be tasked. See [Off-nadir Opportunities](/features/areas-of-interest/off-nadir-opportunities) for the full reading, including what each word in the assessment means for what you can do about it. | Field | Description | | - | - | | **Assessment** | The one-word geometric-bound reading, shown as **Geometry: bounded**, **Geometry: caveated**, or **Geometry: not assessable**. | | **Reason** | A one-sentence explanation, shown wherever the assessment carries one — most often for **caveated** and **not assessable**, naming what narrowed or blocked the bound. | | **Timeline** | A compact bar framing the opportunity across its envelope window, with the straight-down (nadir) window marked inside it when the opportunity has one, each qualifying interval drawn as its own segment, and the reported moment marked with a tick. | | **Envelope window** | The start and end of the widest span during which this opportunity could qualify at all. | | **Time within limits** | The total duration actually within the payload's pointing limits. Time within limits is the total of the qualifying intervals — deliberately not the width of the envelope window, because that would count the gaps. An em-dash when nothing qualifies. | | **Reported moment** | The instant the assessment itself was evaluated at (UTC). | | **Qualifying intervals** | Every qualifying interval within the envelope window, each listed with its own duration. | | **Imaging quality** | The modelled GSD reading, together with an explicit note of where across the area of interest it applies — see [Ground Sample Distance (GSD)](#ground-sample-distance-gsd) below. | | **Provenance** | A line giving the pointing-limits revision in force, when the assessment was made, and the age of the orbit it was assessed against. | This is a geometric bound on the look angle only. It does not account for agility, attitude, power, thermal or scheduling feasibility. An opportunity that predates off-nadir assessment shows **Geometry: unknown** with the reason "This opportunity predates off-nadir assessment." — every other value on the opportunity is unchanged from before off-nadir access shipped. When no off-nadir pointing limits are on file for this payload at all, the note **Off-nadir opportunities aren't available for this payload — no slew limits are on file.** sits above the opportunity list, which stays fully populated — never empty — with every row carrying the *not assessable* glyph. Neither the **caveated** nor the **not assessable** glyph carries any colour or emphasis — deliberately so. A red or amber treatment would read as "cleared to task" or "do not task," a judgement this reading never makes. ### Ground track At the top of the detail panel, a shared mini-map draws the spacecraft's **sub-satellite ground track** across the AOI for the selected opportunity — the path the spacecraft flies over the ground during the window, rendered as a densified curve in the spacecraft's workspace colour. The same map can show the payload footprint and sweep marker when those data are available. The track carries these map layers: | Element | Description | | - | - | | **Track curve** | The densified sub-satellite path across the AOI, drawn in the spacecraft's workspace colour. Where the track crosses the ±180° meridian it is split at the dateline so the curve never wraps horizontally across the map. | | **Direction-of-travel arrow** | An arrowhead at the exit end of the curve, oriented along the entry→exit ordering, so you can read which way the spacecraft is travelling at a glance. | Selecting an opportunity also adds a marker to the track, showing the spacecraft's current sub-satellite point — the same instant named by the footprint sweep's time readout in [Payload footprint](#payload-footprint) below. Drawn in the spacecraft's workspace colour, the marker moves along the track curve as the sweep plays, always landing exactly on the point the curve already draws for that instant. A track is not always available, and an unavailable track is a **neutral state** — never an error or a verdict on the opportunity. When the track cannot be drawn, the shared mini-map still renders the AOI without a track-specific warning. | State | What you see | | - | - | | **Available** | The densified track curve and direction arrow are drawn on the shared mini-map. | | **Unavailable** | The AOI remains drawn on the shared mini-map without a track-specific warning or severity treatment. | | **Grazing opportunity** | An opportunity that barely grazes the AOI is drawn neutrally, with the same track colour and direction cue as any other track. | While a fresh track is being fetched for a newly selected opportunity, the mini-map holds its prior render rather than locking the inspector behind a spinner — re-selecting an opportunity never blanks the panel. Selecting a different opportunity redraws exactly one track and re-frames the mini-map to fit the AOI together with the primary geometry, so the whole view stays in frame. ### Payload footprint On the same mini-map, the selected opportunity's FOV footprint is drawn over the AOI at the payload's actual pointing. Because the footprint reflects real off-nadir pointing rather than a directly-below assumption, it can appear displaced, stretched, or angled relative to the spacecraft's ground track — and a footprint pointed far enough off-nadir can be clipped where it would otherwise extend past the Earth's horizon. Opening an opportunity plays this view forward automatically: a **Play**/**Pause** control (keyboard-operable) and a UTC time readout beneath the map step through the opportunity's real, already-computed positions for each instant — never smoothed or guessed between them — and move the ground-track marker described above in step with it. If you have reduced motion enabled in your operating system, the sweep opens **paused** instead of playing automatically; press **Play** to move through it yourself. The footprint itself renders in one of four states: | State | What you see | | - | - | | **Full footprint** | A closed polygon with a solid outline and a light fill in the spacecraft's workspace colour, drawn under the AOI. | | **Partial footprint** | A closed polygon with a **dashed** outline and a lighter fill. A partial footprint can still fully cover a small AOI located away from the limb — the dashed outline means the boundary is not the true sensor edge everywhere, not that coverage is necessarily incomplete. | | **No footprint** | No footprint is drawn; the AOI remains shown on the shared map. | | **Not yet computed** | No footprint is drawn; the AOI remains shown on the shared map while the computation is pending. | The detail panel presents three profile cards for **Off-boresight**, **Slant range**, and **GSD**. Each card plots its value across the opportunity window and highlights the value nearest the current footprint-sweep time. The detail panel exposes these operator-facing fields: | Field | Description | | - | - | | **Header strip** | Entry time in `HH:MM UTC`, the spacecraft name, and `· payload name`. | | **Footprint sweep** | A UTC time readout for the current footprint position and a duration chip at the row's right end. The readout follows the opportunity window as you scrub it. | | **Sub-satellite** | The spacecraft's point directly below it at the current footprint-sweep time, expressed as latitude / longitude. | | **Off-boresight** | The payload's look angle across the opportunity profile, in degrees. | | **Slant range** | The spacecraft-to-target distance across the opportunity profile, in metres. | | **GSD** | The modelled ground sample distance across the opportunity profile, in metres. | | **Sun glint** | The closest sun-glint angle reached during the opportunity, in degrees, together with the UTC instant at which it occurs. | | **Blinding** | Whether the Sun or Moon enters the payload's field of view during the opportunity. A clear opportunity reads **Clear**. | | **Sun position** | The Sun's elevation and azimuth at the target reference point, in degrees. | | **Apparent solar time** | The true-Sun local time at the target reference point, shown as `HH:MM`. | | **Lighting** | The ground illumination band, with the UTC interval when that band begins and ends within the opportunity. | | **Computed / provenance** | The relative age and source of the forecast, with a link to the full provenance when available. | ### Geometry profile samples The opportunity detail also includes a **Geometry profile samples for this opportunity** table. It combines the sampled geometry and modelled-GSD values by UTC epoch: | Column | Contents | | - | - | | **Epoch** | The UTC instant of the sample. | | **Off-boresight (deg)** | The payload's off-boresight angle in degrees. | | **Slant range (m)** | The spacecraft-to-target distance in metres. | | **GSD (m)** | The modelled ground sample distance in metres. | The table preserves the sampled values at full precision rather than applying the shorter formatting used in the profile cards. When a channel has no value at an epoch, it shows an em-dash (`—`), so mid-pass gaps remain explicit. The raw precision and gaps are a presentation concern that can be considered as a separate product follow-up. ## Filtering by Payload The **Payload** filter appears beside the **Spacecraft** filter at the top of the events surface. Use it to narrow the list to events from one or more specific instruments: | Selection | Effect | | - | - | | No selection (default) | The heatmap shows events from all payloads on all spacecraft. | | One or more payloads selected | Only events attributed to the selected instruments are shown. | The payload filter's options are sourced from the instruments that actually contributed events to the current forecast — payloads that produced no access for this AOI are not listed. The filter resets whenever you switch between AOIs. ## Filtering by Access Once [off-nadir opportunities are switched on](#events-surface-layout) for this area of interest, an **Access** control appears beside **Provenance**. It narrows the list to exactly one of three options: | Option | Effect | | - | - | | **All** (default) | Every opportunity — nadir and off-nadir alike. | | **Nadir** | Only opportunities the payload reaches without slewing off nadir. Choosing **Nadir** reproduces the list exactly as it stood before off-nadir opportunities were switched on. | | **Off-nadir only** | Only opportunities that exist solely because the payload can be pointed off-nadir — every row here carries the **Off-nadir** tag. | ## Blinding A bright body — the **Sun** or the **Moon** — drifting into a payload's field of view during an overflight **blinds** that imaging window: the body's glare spoils the imagery the opportunity would otherwise capture. Every overflight opportunity carries a blinding verdict so you can see at a glance which opportunities are worth tasking and which are spoiled. Solar conditions for an example opportunity: Clear blinding status, Sun position, apparent solar time, and Night lighting band ### Blinding Indicator The detail panel carries a **blinding badge** beside the spacecraft name, naming the verdict directly — no hover needed: | Badge | Meaning | | - | - | | **Clear** (muted) | No bright body enters the payload's field of view during the opportunity — the window is **clear**. | | **Blinded (Sun)** (amber) | The Sun enters the payload's field of view during the opportunity — the window is **spoiled** for imaging. | | **Blinded (Moon)** (amber) | The Moon enters the payload's field of view during the opportunity. | | **Blinded (Sun, Moon)** (amber) | Both the Sun and the Moon enter the field of view during the opportunity. | A **Clear** opportunity is an imaging opportunity worth tasking; a **Blinded** opportunity is spoiled — the badge names the responsible body so you know what is spoiling the window. A body counts as blinding only if the payload can **actually see** it. A body whose direction falls inside the field of view but which is **hidden behind the Earth** is never flagged as blinding — only an un-occulted body the payload can see is counted. This keeps an opportunity from being marked spoiled by a Sun or Moon the Earth is blocking. ## Sun-Glint Angle **Sun-glint** is sunlight reflecting off the target the way light reflects off a mirror — strongest over water — straight back into the payload, washing the image out in a bright hotspot. It is distinct from [blinding](#blinding): with glint the Sun is **not** inside the field of view; its **reflection** off the ground is what reaches the payload. Every overflight opportunity reports a **sun-glint angle** beside its blinding indicator, so you can weigh both of the ways sunlight can spoil an opportunity. Off-boresight, slant range, GSD, and Sun glint profile cards; Sun glint is not applicable while the Sun is below the horizon ### What the angle means The sun-glint angle measures **how close the opportunity's viewing direction comes to the Sun's mirror-reflection direction off the target**, in **degrees**. A **smaller** value is **closer** to the mirror direction — `0°` means the payload is looking straight at the Sun's reflected image; larger values sit further from it. The reported value is the **closest approach reached over the whole opportunity** — the smallest angle anywhere in the imaged part of the AOI at any moment in the window. If any imaged part of the area lines up with the mirror direction at any point in the window, the opportunity reports that. Selecting the opportunity adds a **Sun glint** row to the detail panel, carrying the angle **together with the instant at which that closest approach occurs** (UTC, in the same format as the opportunity's Entry and Exit). That instant is its **own** value and identifies when the closest approach occurs. ### When no angle is shown An opportunity shows **no** sun-glint angle when the **Sun stayed below the target's horizon for the whole window** — with the Sun below the horizon there is no specular reflection to report, so the readout reads **Not applicable · Sun below the horizon** instead of a number. This is a **normal outcome of the geometry**, not a failure or missing data. An opportunity that is only **partly** in darkness still reports a value, for the sun-lit part of its window. ### VALAR reports it — you judge it The sun-glint angle is **information, not a verdict**. VALAR reports the geometry and **applies no threshold to it** — you apply whatever glint limit your mission holds. VALAR does **not** flag, rank, or filter opportunities by sun-glint, and it stores no glint threshold anywhere. Unlike the neighbouring blinding indicator — which marks an opportunity as spoiled — the glint angle never marks an opportunity at all; it reports the number and leaves the judgement to you. Two things to keep in mind when reading the angle: * **A small angle is not a severity score.** Real glint spreads out in a lobe *around* the mirror direction, and how wide that lobe is depends on how rough the surface is — over water, on the wind. So a value a few degrees away from `0°` does **not** mean "no glint", and a small angle is not a claim about how bright the glint will be. Read the number as *how close you are to the centre of the glint*, not *how bad it will be*. * **The calculation treats the target as flat.** That holds well over water, where the surface really is close to flat; over hilly or mountainous ground a slope tilts the effective mirror direction, so the angle is a **weaker guide** there. Lean on it less over relief than over open water. ## Sun at Target Selecting an overflight opportunity adds a **Sun at target** group to the [detail panel](#per-event-detail), reporting where the Sun sits in the sky **above the target on the ground** during the opportunity — the ground-lighting geometry of the opportunity. It is distinct from both the [blinding](#blinding) indicator and the [sun-glint angle](#sun-glint-angle): those describe the Sun relative to the payload, while **Sun at target** describes the Sun relative to the **ground you are imaging**. Solar conditions cards showing Sun elevation and azimuth, apparent solar time, and the lighting interval Every value is read at the opportunity's target reference point on the ground, so the Sun geometry describes the location being imaged. The group carries four scalar cards: | Readout | Description | | - | - | | **Sun position** | The card combines the Sun's elevation above the target's horizon (two decimals, e.g. `34.20°`) and bearing clockwise from local north (one decimal, e.g. `128.7°`). These are the Sun's values at the target reference point, not spacecraft pointing values. | | **Apparent solar time** | The apparent local solar time at the target, shown as `HH:MM` (24-hour, e.g. `12:13`). `12:00` is local solar noon — the moment the Sun is highest over the target. See [Reading the apparent solar time](#reading-the-apparent-solar-time) below. | | **Lighting** | The ground illumination band, followed by the UTC instants that band began and ended within the opportunity (see [Illumination bands](#illumination-bands) below). | ### Illumination bands The **Lighting** row names how lit the ground is, set by how far the Sun is above or below the target's horizon: | Band | Meaning | | - | - | | **Day** | The Sun is up — the ground is sunlit. | | **Civil twilight** | The Sun is just below the horizon; the brightest twilight. | | **Nautical twilight** | The Sun is further below the horizon; the horizon is still faintly discernible. | | **Astronomical twilight** | The faintest twilight, just before full darkness. | | **Night** | The Sun is far enough below the horizon that no twilight remains. | The **Day** boundary is the standard sunrise/sunset line, which allows for atmospheric refraction and the Sun's apparent size — so an **Elevation** a little below `0°` can still read **Day** while the Sun's upper edge is above the horizon. The band name is followed by the **UTC instants it began and ended** within the opportunity, in the same format as the opportunity's **Entry** and **Exit** — for example `Civil twilight 13 May 2026, 05:14:32 UTC – 13 May 2026, 05:41:07 UTC`. When the whole window sits inside one continuous band with no boundary crossing — a polar day or polar night — only the band name is shown, with no start–end range. If only one side of the range is known, the missing side reads **—**. ### At the poles At the poles the Sun has no meaningful compass bearing and no meaningful local solar time. There, the **Azimuth** and **Apparent solar time** rows read **—** (an em-dash) rather than a fabricated value; the **Elevation** and **Lighting** rows still report normally. ### Reading the apparent solar time The **Apparent solar time** is *apparent* (true-Sun) local time — the time the Sun itself keeps, carrying the equation of time — and is accurate to within the spacecraft's epoch (timing) uncertainty. Two things it is **not**: * It is **not clock time.** It does not match the target's civil time zone or UTC; it tracks the real Sun over that exact point on the ground. * It is **not the LTAN** — the *local time of the ascending node* — which is an orbit-level property of the spacecraft, not a reading taken on the ground. Read it as *where the Sun is in the target's day*, not as a wall clock or an orbit parameter. ### VALAR reports the lighting — you judge it The Sun-at-target geometry is **read-only reporting**, exactly like the neighbouring [sun-glint angle](#sun-glint-angle). VALAR reports the numbers and the band and applies **no** judgement to them: there is no sort, no filter, no threshold, no badge, and no colour on any of these values, and no illumination is ever flagged as good or bad. Every readout is plain text — you decide what lighting your mission needs. ## Ground Sample Distance (GSD) **Ground sample distance (GSD)** is the size on the ground that a single detector pixel spans — a practical measure of the finest detail an opportunity could resolve. A **smaller** GSD means **finer** detail. VALAR models the GSD for each opportunity from the imaging payload's optics — its **pixel pitch** and **focal length**, set on the [Spacecraft](/features/spacecraft-management#payloads-tab) page — together with the opportunity's viewing geometry, and reports it in the opportunity profile cards. The GSD reading is **information, not a verdict**. VALAR reports the modelled figure and applies no threshold to it — you weigh it against your mission's resolution needs. VALAR does **not** rank, filter, sort, or flag opportunities by GSD, and the reading never marks an opportunity. ### On the opportunity detail — the opportunity profile card Selecting an opportunity shows the modelled-GSD reading in its own profile card alongside off-boresight and slant range. For an available reading it shows: | Element | What it tells you | | - | - | | **Modelled GSD (major axis)** | The headline reading — the modelled GSD along the footprint's **major axis**, in metres. | | **Curve** | The modelled GSD plotted across the imaging window, with the time axis in UTC. | | **Selected value** | The GSD nearest the current map-slider epoch. | Each reading also carries an explicit note of *where across the area of interest* it applies — the point the reading was modelled from, not the area as a whole. ### Availability states A GSD reading is not always available — and an unavailable reading is a normal **state**, never an error. Whatever the state, the reading block keeps the same size, so nothing on the detail panel shifts when a reading lands. The six states: | State | What you see | | - | - | | **Available** | The full reading — headline, curve, finest and coarsest, both footprint dimensions, incidence angle, and provenance. | | **No payload optics** | **Add payload optics to model GSD** — the payload has neither optic set. | | **Only one optic set** | A prompt naming the missing optic — for example **Add the focal length optic to model GSD** — when only one of pixel pitch or focal length is set. | | **Outside the validated domain** | The reading still shows, but its coarsest value carries a trailing `+` and the note *Computed over samples with incidence ≤ 45°; the true maximum over the window is larger.* | | **Couldn't compute** | **No modelled-GSD curve for this opportunity.** — the model ran but produced no reading. | | **Outside its validated domain at this look angle** | On an off-nadir opportunity's **Imaging quality** reading (within the [Off-nadir](#off-nadir) group above): **GSD not shown — outside its validated domain at this look angle.** No number is displayed for this reading. | Every unavailable state renders as a plain, muted note in the space the reading would occupy — never in an error or warning style. To move an opportunity from **No payload optics** or **Only one optic set** to a full reading, set both the pixel pitch and the focal length on the payload — see [Payload optics](/features/spacecraft-management#payloads-tab) on the Spacecraft page. ## Filtering by Spacecraft The **Spacecraft** filter is a multi-select dropdown beside the **Payload** filter. Its options are spacecraft that contributed at least one event to the current forecast — vehicles that produced no event for this AOI are silently excluded. The filter resets whenever you switch between AOIs. When a spacecraft filter is active, an `N of M shown` indicator appears beneath the heatmap. ## The Recompute Action Click **Recompute** to refresh the 7-day overflight schedule for the AOI across every spacecraft in the workspace. The button shows a spinner while the recompute runs, and the heatmap and the detail panel are replaced by **Computing overflights…** for the duration of the run. The **Last computed** label refreshes on success. The control is absent for an **Inactive** AOI rather than disabled. The **Recompute** button is disabled when: * The AOI is **Out-of-window** (its validity window has not started yet or has already ended). * A recompute is already running. ### When the AOI Changes After a Recompute Overflight results describe the AOI as it stood when they were computed. Change what the forecast is computed from — replace the boundary, edit the geometry, or move the validity window — and those results no longer describe it. Rather than leave them on screen, the events surface **replaces** the heatmap and the detail panel with a named state, so you are never shown results computed for inputs that have since changed: | State | Recompute | What it tells you | | - | - | - | | **Computing overflights…** | Unavailable while it shows | `Updating for the new AOI.` A recompute you started on this page is running. | | **AOI changed since last computed** | Available | `Recompute to see overflights for the updated AOI.` The AOI changed after its last recompute, and a new one is owed. | Neither state annotates the results — the results are gone until a recompute covering the current AOI completes. **AOI changed since last computed** is not a local hint. It is derived from the AOI itself, so it survives a page reload and reads identically for a colleague who never saw your edit. An AOI that has never been computed shows **No overflights computed yet** instead — there are no earlier results to disown. See [Empty States](#empty-states) for the full priority order. ### Auto-Trigger on Edit Editing any of the following AOI fields triggers an automatic recompute when you commit the edit — you do not need to click **Recompute** afterwards: * **Geometry** edits (any vertex, disk centre or radius, multipolygon piece), and a whole-boundary replacement from a file. * **Validity window** changes (either bound, set or cleared). * Flipping the AOI **active toggle** in the identity hero (**Active** ↔ **Inactive**). * Flipping the **Include off-nadir opportunities** switch in the **Edit AOI** dialog, either direction. The switch surfaces opportunities the payload can be pointed at rather than only those directly overhead, and changing it recomputes this area of interest's overflight forecast. It is set per area of interest, so every opportunity in this AOI shares this AOI's setting. An edit that leaves the geometry exactly as it was is not a change: nothing is written and no recompute runs. Identity fields — name, description, tags, colour — do not trigger a recompute. Existing opportunities are unaffected by an identity-field-only edit. ### Timing Accuracy Event timing accuracy is **better than 1 second at day 1** of the forecast horizon. For spacecraft in LEO at altitudes below 500 km, the timing may drift up to a few seconds at day 7 because of atmospheric drag uncertainty. After a fresh orbit determination or a known manoeuvre, click **Recompute** again to anchor the schedule on the new ephemeris. ## Provenance Click **Provenance** to open a dialog that answers *what was this forecast built from?* — one block per spacecraft the forecast covers, each naming the spacecraft and listing the inputs recorded for it. The button is available once the AOI has a computed forecast. If an opportunity is selected, or the spacecraft filter is narrowed, the dialog narrows with it, so it always answers about the spacecraft you are already looking at. Provenance dialog for a spacecraft entry, showing all four recorded forecast inputs — Orbital state, Attitude, Payload, and Configuration — each reporting All current ### The Recorded Inputs Each spacecraft's block lists up to four inputs — whichever the forecast actually recorded for that spacecraft: | Input | What it reports | | - | - | | **Orbital state** | The orbit epoch the forecast propagated from, with its source (for example a public TLE or an orbit-determination solution) as a qualifier. | | **Attitude** | The attitude mode, or modes, in force for the spacecraft. | | **Payload** | The imaging payload's name together with its field-of-view geometry. | | **Configuration** | The spacecraft's body and panel geometry — dimensions, panel count, and drag coefficient. | Not every input is recorded for every forecast. When one is missing for a spacecraft, that spacecraft's block names it in a short footer rather than showing an empty or guessed row — so what you see is never presented as more complete than the data actually is. ### Used Beside Current Every recorded input is compared against the spacecraft's value right now, and VALAR computes that comparison for you — you never have to work out whether two values still match: | State | What you see | What it means | | - | - | - | | **Matches** | The value once, full width. | The input the forecast used is still the spacecraft's value today — the forecast rests on today's inputs. | | **Differs** | Two labelled values, **Used** and **Now**, side by side. | The spacecraft's value has moved since the forecast ran. **Used** names exactly what the forecast was built from; **Now** names the value that superseded it. | | **Unavailable** | The used value, with a muted note reading **No current value to compare — this spacecraft has no orbital data now.** | There is nothing to compare the recorded input against right now — a gap in today's data, not a claim that anything changed. | Each spacecraft's block also carries a roll-up so you can see which spacecraft needs a second look before reading a single row: | Roll-up | Meaning | | - | - | | **All current** | Every recorded input matches the spacecraft's value today. | | **Recorded inputs current** | Every recorded input matches — but at least one input was never recorded for this forecast, so this stops short of claiming everything is current. | | **`N` inputs changed** | At least one input differs from the spacecraft's value today. | | **`N` inputs unavailable** | At least one input has nothing to compare against today. | Provenance is read-only: opening the dialog computes nothing and changes nothing, and closing it returns you to the events surface exactly as you left it. ## When an orbit is stale or unusable A recompute draws each spacecraft's overflights from a **fresh** orbit. A spacecraft's [orbit age](/features/orbit-age#orbit-age) is measured from its latest [state vector](/features/state-vectors) — the position and velocity at an epoch provided through orbit determination, an [OPM](/file-formats/opm) import, or manual entry. As that age grows it crosses two levels in turn — the [degraded level](/features/orbit-age#degraded-level), then the [stale level](/features/orbit-age#stale-level) — and a recompute treats each spacecraft individually, so an aging or unusable orbit on one spacecraft never stops the rest of the forecast. Because you trigger the recompute yourself — by clicking **Recompute** or committing an edit — that press is itself the deliberate action. An aging or stale spacecraft is therefore surfaced as an **inline warning above the event list**, naming the spacecraft, rather than holding the forecast behind a confirmation. What each affected spacecraft does: | Orbit state | What the recompute does | | - | - | | **Fresh** (within both levels) | Returns its overflight events into the heatmap as normal. | | **Degraded** (past the [degraded level](/features/orbit-age#degraded-level)) | Computes its overflights from the platform-fetched public [TLE](/file-formats/tle) and returns events normally. The spacecraft is named in the [orbit-data-age footer](/features/orbit-age#the-orbit-data-age-footer) with a **Degraded** tag. | | **Stale** (past the [stale level](/features/orbit-age#stale-level)) | Is **left out** of the recompute rather than silently dropped: a named warning panel appears above the event list — reading **This spacecraft's orbit is stale**, with the orbit's age (`last determined N days ago`) and the level it crossed (`exceeds your N-day threshold`) — so you can see exactly which spacecraft was excluded. When the fallback orbit is itself stale, the panel adds **the public-TLE fallback is also stale**. Every fresh spacecraft in the same recompute still returns its events below. | | **No orbit data** | A spacecraft with no orbit data of any kind contributes no events — there is nothing to compute from. It is left out of the forecast while every other spacecraft computes normally. The remedy is to add tracking data on the [Spacecraft](/features/spacecraft-management) page. | Both `N` values are whole days — the spacecraft's actual orbit age and your configured stale level. To bring an excluded spacecraft back into the forecast, provide a fresher [state vector](/features/state-vectors) for it (or raise the stale level), then click **Recompute**. The stale and degraded levels are workspace-wide values set once in **Settings → Orbits → Orbit age** (stale level default `14 days`), the same values that govern the [Keplerian-elements plot](/features/orbit-elements-plots), the [ground-track map](/features/3d-ground-track), and ground-station passes together with AOI overflight. See [Orbit age](/features/orbit-age#stale-level) for the workspace-wide policy and the block message. Every spacecraft affected at either level is also named in the unified [orbit-data-age footer](/features/orbit-age#the-orbit-data-age-footer) at the bottom of the page — tagged **Degraded** at the degraded level, or **Blocked** once past the stale level — so the affected spacecraft read at a glance across the whole workspace, not only on this AOI. ## Empty States When the AOI or workspace is in a state that explains why no events are displayed, the events surface replaces the heatmap and detail panel with a guidance card. Only one card is shown at a time, and the priority order is: | State | Headline shown | When it appears | | - | - | - | | Recompute error | `Recompute failed — try again` | The most recent recompute rejected. The error clears the next time you click **Recompute**. | | Outside validity window | **Outside validity window** | The current time falls outside the AOI's validity bounds. | | AOI inactive | **AOI is inactive** | The AOI has been paused from the identity hero. The guidance card also reads `Reactivate this AOI to see upcoming overflights.` | | No payload-equipped spacecraft | **To see FOV access, configure a payload** | No spacecraft in the workspace has a payload configured. Add a payload to a spacecraft to generate FOV access events. | | Never computed | **No overflights computed yet** | The AOI has never had a recompute run. Click **Recompute** to generate the forecast. | | Recompute running | **Computing overflights…** | `Updating for the new AOI.` — a recompute you started on this page is in flight, and the heatmap and detail panel are replaced for its duration. | | AOI changed since last computed | **AOI changed since last computed** | `Recompute to see overflights for the updated AOI.` — the AOI changed after its last recompute, so the stored results no longer describe it. | | No FOV access in the window | **No FOV access in the next 7 days** | The recompute completed but no payload's field of view crosses this AOI in the next 7 days. Check spacecraft orbit data or recompute. | | Off-nadir only with no results | **No off-nadir-only opportunities in the next 7 days.** | Access is filtered to **Off-nadir only** and no opportunity qualifies. `Switch Access to All to see every opportunity.` | The spacecraft filter dropdown above still lists only vehicles that actually contributed at least one opportunity to the current forecast. ## Related Pages * [Areas of Interest overview](/features/areas-of-interest/overview) — the page that hosts the events surface, plus the identity hero and geometry block. * [Off-nadir Opportunities](/features/areas-of-interest/off-nadir-opportunities) — the per-AOI opt-in, the assessment vocabulary, and the geometric-bound disclaimer in full. * [AOI Map](/features/areas-of-interest/map) — the world map view, where each AOI's hovercard surfaces its next overflight and a compact 7-day timeline. * [Create an AOI](/features/areas-of-interest/create-aoi) — define an AOI and configure its lifecycle. * [GeoJSON file format](/file-formats/aoi-geojson) — accepted geometry types for AOIs created from a GeoJSON document. # Areas of Interest Source: https://docs.valar.space/features/areas-of-interest/overview Inspect an Area of Interest, edit its identity and geometry in place, and review its 7-day overflight forecast > For the complete documentation index, see [llms.txt](/llms.txt). An **Area of Interest (AOI)** is a workspace-level geographic region you persist alongside the spacecraft fleet. Every AOI is automatically evaluated against every spacecraft in the workspace, producing a 7-day forecast of predicted overflight opportunities on demand — there is no per-spacecraft binding step. The AOI Overview page is where you read one AOI in depth, edit its identity and geometry in place, and act on its overflight forecast. **Route:** `/aoi` Open the page via the **AOIs** entry in the sidebar. ## Page Layout AOI Overview page with the identity hero, geometry preview, properties column, and events section The Overview page is a three-band layout with the AOI list docked on the right and a shared topbar above: | Band | Contents | | - | - | | **Top bar** | Tags filter, status filter, **New AOI** button, **Cheatsheet** button, and a toggle that collapses the right-hand list pane. | | **Identity hero** | Colour swatch, AOI name, status pill, optional description, tag chips, an edit-mode toggle, and a kebab menu. | | **Geometry block** | Auto-zooming geometry preview on the left; geometry properties (validity window, type, detail, centroid) on the right. | | **Events section** | Visibility / payload / spacecraft filters, the **Include off-nadir opportunities** switch and **Access** control, **Recompute** button, last-computed timestamp, the opportunity heatmap, and the detail panel for whichever opportunity is currently selected. | The right-docked AOI list pane is shared with the [AOI Map](/features/areas-of-interest/map) page and is rendered identically on both routes. ## Right-Pane AOI List The AOI list pane is a vertical column on the right edge of the page. From top to bottom: | Control | Behaviour | | - | - | | **Search AOIs** | Local text filter — matches any AOI whose name contains the typed query (case-insensitive). | | **Filter by tag** | Multi-select dropdown in the top bar. Picks any subset of tags currently in use; rows must match every selected tag. | | **Filter by status** | Multi-select dropdown in the top bar with options **Active**, **Inactive**, and **Out of window**. | | **AOI rows** | Colour swatch, name, status icon (check for **Active**, slashed circle for **Inactive**, cross for **Out of window**), and a relative "next pass" label. | Clicking a row selects the AOI and updates the URL to `/aoi?selected=`. The URL parameter survives reloads and links — paste `/aoi?selected=` to deep-link straight to a specific AOI. If the value is empty or does not identify an available AOI, the page falls back to the first available AOI instead of leaving the page without a selection. When the search box plus the topbar filters narrow the list to zero rows, the pane renders **No AOIs match these filters** with a **Clear filters** link that resets every filter. When the workspace has no AOIs at all, the pane shows **No AOIs yet** with a **Create your first AOI** button that opens the creation method picker on the [AOI Map](/features/areas-of-interest/map) page. The collapse toggle in the top bar hides the list pane so the main content takes the full page width; click it again to bring the list back. ## Identity Hero — In-Place Editing The identity hero is the top band of the Overview page. By default every field renders as plain text — selection alone does not let you edit. Click the pen icon at the right edge of the hero to switch into edit mode. The pen icon is the only entry point to editing; switching to a different AOI in the list resets edit mode back off. In edit mode, each identity field becomes inline-editable: | Field | Edit affordance | | - | - | | **Colour swatch** | Click the swatch to open a 12-swatch palette popover. Pick a colour and the popover closes. The palette colours are Emerald, Teal, Sky, Blue, Indigo, Violet, Fuchsia, Rose, Red, Orange, Amber, and Lime. | | **Name** | Click the heading text to inline-edit. Up to 100 characters. **Enter** commits, **Escape** reverts. An empty name surfaces `Name is required` inline and blocks the save. | | **Description** | Click the description (or the *Add a description…* placeholder) to inline-edit. Up to 100 characters. A live `N/100` counter renders beneath the input. | | **Tags** | Click the tag row to edit. Type a tag and press **Enter** or `,` to commit it as a chip; **Backspace** on an empty input removes the last chip. Up to 20 tags, each ≤64 characters. Exceeding the cap surfaces `Up to 20 tags, each ≤64 characters` inline. | To the right of the pen icon, the kebab menu offers two actions, both enabled only when edit mode is on: | Action | Behaviour | | - | - | | **Set active / Set inactive** | Label flips with the current state. Setting **Inactive** pauses the AOI — no opportunities are generated. Setting **Active** re-enables forecasting. | | **Delete AOI** | Opens a confirmation dialog **Delete AOI** with the body `Are you sure you want to delete ""? This action cannot be undone.` Click **Delete** to confirm or **Cancel** to keep the AOI. After deletion, the page navigates to the next remaining AOI, or to the empty state if it was the only one. | The status pill in the hero shows the AOI's lifecycle state: | Status | Meaning | | - | - | | **Active** | Default state. Overflights compute when you click **Recompute** or change a geometry / lifecycle field. | | **Inactive** | The AOI is paused — no opportunities are generated until you set it active again. | | **Out-of-window** | Outside the AOI's validity window. Opportunities do not generate until the current time falls inside the window. | ## Geometry Block The geometry block is rendered as two columns. On the left, a 16:9 Mapbox preview auto-zooms to the AOI's bounding box and renders the shape in the AOI's chosen colour. On the right, a properties column lists the geometry's derived values. Polygon boundary preview on the AOI Overview page ### Geometry Preview The preview is a read-only map by default. Reference frame is **WGS84 geodetic** — every coordinate is latitude / longitude on the WGS84 ellipsoid. The camera fits the AOI's bounding box with consistent padding on every load, and reapplies when you switch between light and dark themes. When edit mode is on, an editor opens beneath the preview. You can adjust the geometry by: * Dragging a vertex, midpoint, or disk handle directly on the preview. * Editing the structured coordinates in the editor card (vertices for a polygon, centre + radius for a disk, per-piece vertices for a multipolygon). * Clicking **Replace from file…** in the editor's control row to swap the whole boundary for one read out of a file. Commits route through the same validation rules described on the [Create an AOI](/features/areas-of-interest/create-aoi) page; a successful edit triggers an automatic recompute. Switching the shape-type selector only changes which fields the editor shows — nothing is written until you edit a field and leave it. ### Replace the Boundary From a File When a corrected outline arrives as a file, you do not have to delete the AOI and recreate it. In edit mode, click **Replace from file…** in the editor's control row to open the **Replace boundary from a file** dialog and swap the boundary in place. Replace boundary from a file dialog, comparing the current boundary against the one read from the chosen file | Control | Behaviour | | - | - | | **Choose file** | Opens the file picker. The helper text beneath reads `Choose a .kml, .kmz, or .geojson file.` — those three extensions are what the dialog accepts. | | **Choose a different file** | Replaces **Choose file** once a file is selected. Picking another file discards the previous reading entirely, including any error it produced. | | **Current** / **From file** | Two side-by-side columns comparing the stored boundary against the incoming one on **Type**, **Detail**, and **Centroid** — the same three readouts the geometry properties column shows. Every value under **From file** reads `—` until a boundary has been read out of the chosen file. | | **Replace boundary** | Commits the incoming boundary. Stays disabled until a boundary has actually been read out of the chosen file. | | **Cancel** | Closes the dialog and writes nothing. | The line `The current boundary will be replaced. This can't be undone.` sits beneath the primary action. There is no boundary history and no undo, so keep the previous file if you may need to go back. Only the boundary changes. The AOI's name, description, tags, colour, active flag, and validity window are untouched by the replacement, and a successful replacement triggers an automatic recompute exactly as an in-place geometry edit does. The comparison answers "is this the right shape, in the right place?" — it is not an approval. The boundary is checked when it is saved, under the same rules that apply however the boundary arrived, so a file the dialog can read can still be refused. A refusal is shown inside the dialog with your chosen file still selected, so you can pick another without starting over; the dialog closes only once the replacement is saved. Accepted geometry, rejected geometry, and file-size limits are identical to the creation path — see [KML and KMZ files](/file-formats/kml) and the [GeoJSON file format](/file-formats/aoi-geojson). ### Geometry Properties The properties column lists derived values for the current geometry: | Field | Description | | - | - | | **Validity window** | `start UTC → end UTC` when both bounds are set, ` (UTC) — Open-ended` when only the start is set, `Open-ended — (UTC)` when only the end is set, or **Always active** when neither bound is set. | | **Type** | **Polygon**, **Disk**, or **Multipolygon**. | | **Detail** | A polygon's vertex count, a disk's radius in kilometres, or a multipolygon's piece count. | | **Centroid** | Mean latitude / longitude of every parsed coordinate, rounded to two decimals. | In edit mode, **Validity window** opens an edit dialog: * **Edit validity window** opens a modal with two independent date-time pickers, one per bound. Each bound has a **Set / Open-ended** switch — flip a switch to **Open-ended** to leave that side unbounded, or to **Set** to surface a MiniCalendar plus an `HH:MM` input. Leaving both sides Open-ended means the AOI is always active; setting only one means it is bounded on that side and open on the other. When both bounds are Set, the end must be strictly after the start — otherwise `Validity end must be after validity start` surfaces and **Save** is disabled. All times are UTC. **Type**, **Detail**, and **Centroid** are always read-only — they reflect what the geometry editor produces. ## Export a Boundary An area's boundary can be handed to another tool as a file. Open the area's own actions menu — the kebab beside the edit control in the identity hero — and choose **Export as GeoJSON** or **Export as KML**. The file downloads straight away, and nothing about the area changes. The area actions menu open on an exportable polygon area, showing Export as GeoJSON and Export as KML above Set inactive and Delete AOI | Format | File | Contract | | - | - | - | | **GeoJSON** | `aoi--.geojson` | An RFC 7946 `Feature`. See [GeoJSON file format](/file-formats/aoi-geojson#exporting-a-boundary). | | **KML** | `aoi--.kml` | One OGC KML `Placemark`. See [KML and KMZ files](/file-formats/kml#exporting-a-boundary). | The date in the filename is the UTC calendar date of the export. ### What the File Carries The file holds the **boundary only** — the outline, the area's name, description, and tags, and a small provenance block. It does not carry the area's overflight forecast, its validity window, its colour, or its active state. Each file also records how far its straight segments depart from the great-circle boundary VALAR computes overflights against. That figure is measured for each file individually and stays within 250 m for absolute latitude up to 89.5°. Both format pages document the bound and its limits in full. A file VALAR exports is not guaranteed to import back into VALAR. Export hands a boundary to another tool; it is not a way to move areas between workspaces. To change an area's boundary here, use **Replace from file…** in the geometry editor instead — see [Replace the Boundary From a File](#replace-the-boundary-from-a-file). ### When Export Is Unavailable Four kinds of area cannot be exported. Their menu entries stay visible but are not actionable, and the reason appears when you hover or focus the entry: | Reason | Message shown | | - | - | | **The area has no usable stored boundary** | `This area has no stored boundary to export. Re-save its geometry, then try again.` | | **The area is a circle** | `Circular areas can't be exported yet. Export supports polygon and multi-polygon areas.` | | **The area crosses the 180° meridian** | `This area crosses the 180° meridian, which export can't represent yet.` | | **The area encloses a pole** | `This area encloses a pole, which export can't represent yet.` | Exactly one reason is shown at a time, even when an area meets more than one. ## Events Section The events section is the bottom band of the page. It composes the visibility, payload, and spacecraft filters, the **Recompute** action, the opportunity heatmap, and the detail panel for whichever opportunity the heatmap currently has selected. ### Header Controls | Control | Description | | - | - | | **Payload filter** | Multi-select dropdown. Selecting one or more payloads narrows the heatmap to opportunities from those instruments. Appears beside the spacecraft filter. | | **Spacecraft filter** | Multi-select dropdown. Selecting one or more spacecraft narrows the heatmap to those vehicles' opportunities. | | **Include off-nadir opportunities** switch | Set per area of interest, in the **Edit AOI** dialog reached from the identity hero's pencil icon — not inline here. Off by default. Surfaces opportunities the payload can be pointed at rather than only those directly overhead, and recomputes this area of interest's overflight forecast. See [Off-nadir Opportunities](/features/areas-of-interest/off-nadir-opportunities). | | **Access** | Appears once off-nadir opportunities are switched on. Narrows the list to **All** (default), **Nadir**, or **Off-nadir only** — see [Filtering by Access](/features/areas-of-interest/overflight-events#filtering-by-access). | | **Recompute** | Refreshes the 7-day overflight schedule for the AOI across every spacecraft in the workspace. It is absent for an **Inactive** AOI, and disabled when the AOI is **Out-of-window** or while a recompute is already running. | | **Provenance** | Opens a dialog showing what the forecast was built from, per spacecraft. Available once the AOI has a computed forecast — see [Provenance](/features/areas-of-interest/overflight-events#provenance). | | **Last computed** | Relative timestamp of the last successful recompute, or **Never computed** before the first run. | ### Empty States When the AOI or workspace is in a state that explains why no opportunities are displayed, the events section surfaces a guidance card in place of the detail panel. Only one card is shown at a time, and the priority order is: For an **Inactive** AOI, the **Recompute**, **Provenance**, **Payload**, and **Spacecraft** controls are absent rather than disabled. The guidance card reads **AOI is inactive** and `Reactivate this AOI to see upcoming overflights.` | State | Headline shown | Why it shows | | - | - | - | | Recompute error | `Recompute failed — try again` | The most recent recompute rejected. The error clears the next time you click **Recompute**. | | Outside validity window | **Outside validity window** | The current time falls outside the AOI's validity bounds. | | AOI inactive | **AOI is inactive** | The AOI is paused. The guidance card also reads `Reactivate this AOI to see upcoming overflights.` | | No payload-equipped spacecraft | **To see FOV access, configure a payload** | No spacecraft in the workspace has a payload configured. Add a payload to a spacecraft to generate overflight opportunities for this AOI. | | Never computed | **No overflights computed yet** | The AOI has never had a recompute run. Click **Recompute** to generate the forecast. | | Recompute running | **Computing overflights…** | `Updating for the new AOI.` — a recompute you started on this page is in flight, replacing the detail panel for its duration. | | AOI changed since last computed | **AOI changed since last computed** | `Recompute to see overflights for the updated AOI.` — the AOI changed after the last recompute, so the stored results no longer describe it. | | No FOV access in the window | **No FOV access in the next 7 days** | The recompute completed but no payload's field of view crosses this AOI in the next 7 days. Check spacecraft orbit data or recompute. | | Off-nadir only with no results | **No off-nadir-only opportunities in the next 7 days.** | Access is filtered to **Off-nadir only** and no opportunity qualifies. `Switch Access to All to see every opportunity.` | ### Opportunity Heatmap The heatmap is a 7×24 density grid — 7 days (rows) by 24 UTC hours (columns) — shading each cell by how many opportunities start in that hour across the contributing spacecraft. It is both the **navigator and the selector**: clicking a cell scopes the view to that one-hour stretch and automatically selects the first opportunity in it, loading that opportunity's detail panel below. When a bucket holds more than one opportunity, a compact list of preview rows — spacecraft, payload, and UTC entry time — appears beneath the grid so you can pick a different one from the same bucket; hovering an occupied cell shows the same preview rows in a tooltip. A **Show all opportunities** control appears once a cell is scoped — click it to clear the scope and reselect the very first opportunity across the full default horizon (now through the next 7 days). The visibility, payload, and spacecraft filters all apply to the heatmap. See [Overflight Events](/features/areas-of-interest/overflight-events) for the full heatmap mechanics. ### Opportunity Detail Selecting an opportunity — by clicking a heatmap cell or one of its preview rows, as described above — opens its detail panel, showing: | Field | Description | | - | - | | **Header strip** | Entry time in `HH:MM UTC`, the spacecraft name, and `· payload name`. | | **Footprint sweep** | A UTC time readout for the current footprint position and a duration chip at the row's right end. The readout follows the opportunity window as you scrub it. | | **Sub-satellite** | The spacecraft's point directly below it at the current footprint-sweep time, expressed as latitude / longitude. | | **Off-boresight** | The payload's off-boresight angle across the opportunity profile, in degrees. | | **Slant range** | The spacecraft-to-target distance across the opportunity profile, in metres. | | **GSD** | The modelled ground sample distance across the opportunity profile, in metres. | | **Sun glint** | The closest sun-glint angle reached during the opportunity, in degrees, together with the UTC instant at which it occurs. | | **Blinding** | Whether the Sun or Moon enters the payload's field of view during the opportunity. A clear opportunity reads **Clear**. | | **Sun position** | The Sun's elevation and azimuth at the target reference point, in degrees. | | **Apparent solar time** | The true-Sun local time at the target reference point, shown as `HH:MM`. | | **Lighting** | The ground illumination band, with the UTC interval when that band begins and ends within the opportunity. | | **Computed / provenance** | The relative age and source of the forecast, with a link to the full provenance when available. | When a spacecraft filter is active, an `N of M shown` indicator appears beneath the heatmap so you always know how many opportunities the filter is hiding. ### Auto-Trigger on Edit Committing any of the following edits triggers an automatic recompute — you do not need to click **Recompute** afterwards: * Geometry edits (any vertex, disk centre or radius, multipolygon piece), and a whole-boundary replacement from a file. * Validity window changes. * Setting the AOI **Active** or **Inactive** from the kebab menu. * Flipping the **Include off-nadir opportunities** switch in the **Edit AOI** dialog, either direction. The switch surfaces opportunities the payload can be pointed at rather than only those directly overhead, and changing it recomputes this area of interest's overflight forecast. It is set per area of interest, so every opportunity in this AOI shares this AOI's setting. An edit that leaves the geometry exactly as it was is not a change: nothing is written and no recompute runs. Identity-only edits — name, description, tags, colour — do not trigger a recompute. Existing opportunities are unaffected by an identity-only edit. ## Workspace-Scoped Evaluation Every AOI is automatically evaluated against every spacecraft in the workspace. There is no AOI-to-spacecraft subscription step; the spacecraft filter is just a UI affordance on top of the full result set. ## 7-Day Forecast Horizon The forecast horizon is fixed at **7 days** from the instant you click **Recompute**. Configurable horizons are not yet available. Event timing is **better than 1 second at day 1** of the forecast. LEO spacecraft below 500 km may drift a few seconds at day 7 because of atmospheric drag uncertainty. After a fresh orbit determination or a known manoeuvre, click **Recompute** again to anchor the schedule on the new ephemeris. ## Related Pages * [AOI Map](/features/areas-of-interest/map) — view every AOI at once on a full-bleed world map and drive creation from the same surface. * [Create an AOI](/features/areas-of-interest/create-aoi) — define an AOI by drawing, by typing coordinates, or by pasting a [GeoJSON file](/file-formats/aoi-geojson). * [Overflight events](/features/areas-of-interest/overflight-events) — the heatmap's selection mechanics, per-opportunity detail, recompute mechanics, and the 7-day forecast horizon. * [Off-nadir Opportunities](/features/areas-of-interest/off-nadir-opportunities) — the per-AOI opt-in, the assessment vocabulary, and the geometric-bound disclaimer in full. * [GeoJSON file format](/file-formats/aoi-geojson) — the supported RFC 7946 subset accepted for AOI creation. * [KML and KMZ files](/file-formats/kml) — the geometry accepted from a `.kml` or `.kmz` file, when creating an AOI and when replacing its boundary. ## Booking overflights and inspecting past bookings Click **Book event** in a selected overflight inspector to save the opportunity in one step. The booking preserves the AOI shape, event details, ground track, payload footprints and playback frames, geometry and sun-glint plots, GSD information and provenance available at booking time. It requires no additional fields. Open **Booked events** in the top bar to switch between **Past** and **Upcoming** bookings. Select an event to inspect its saved information and replay its geometry. The **Saved at booking** timestamp identifies the preserved view. Recomputation, later AOI edits and removal of the original ephemeral event do not replace it. Only booked events are kept in this history. A booking saves an opportunity for reference; it does not command a spacecraft or arrange a provider contact. # AOI Timeline Source: https://docs.valar.space/features/areas-of-interest/timeline See every Area of Interest's spacecraft overflight opportunities on one shared timeline, grouped by AOI > For the complete documentation index, see [llms.txt](/llms.txt). The Timeline page shows every Area of Interest's spacecraft overflight opportunities at once, grouped by AOI, on a single shared 7-day horizon. Where the [Overview](/features/areas-of-interest/overview) page reads one AOI in depth, the Timeline page is the wide view — scan every AOI's activity side by side without switching between them. **Route:** `/aoi/timeline` Open it from the **Timeline** tab beside **Overview** and **Map**. When the combined [Operations Timeline](/features/timeline) is available, this entry opens its corresponding event layer, grouped by spacecraft. ## Page Layout The page is a full-height, full-width canvas: a sticky sidebar column on the left listing each AOI and spacecraft, and a horizontally-scrollable track on the right drawing every opportunity in time against a daily-tick axis. A **Now** marker crosses the track at the current instant, re-checking its position every 60 seconds. AOI Timeline page with the Azores group collapsed and the Spacecraft filter narrowed to one vehicle, showing every remaining AOI's opportunities on one shared horizon The shared top bar remains available while you scan the timeline: | Control | Behaviour | | - | - | | **Tags** | Filters the AOI groups by tag. | | **Status** | Filters the AOI groups by **Active**, **Inactive**, or **Out of window** status. | | **New AOI** | Opens the AOI creation method picker on the [AOI Map](/features/areas-of-interest/map) page. | | **Cheatsheet** | Opens the **Spacecraft Cheatsheet** for quick reference to orbital data and operations. | ## Every AOI at Once Each AOI renders as a collapsible group: a header row naming the AOI, followed by one row per spacecraft in the workspace. Click an AOI's header row to collapse or expand it — collapsing hides its spacecraft rows but keeps the header itself visible, so you can scan every AOI's name even with most of them collapsed. AOIs are listed alphabetically by name. An AOI outside its validity window still gets a header row, suffixed **— validity window expired**, with no spacecraft rows beneath it — it stays visible rather than disappearing, so you know it exists and why nothing is drawn for it. A spacecraft with no imaging payload configured is left out of every AOI's roster entirely — it can never produce an opportunity for any AOI, so it carries no row anywhere on this page. ## Reading a Spacecraft's Row Each spacecraft row shows the spacecraft's colour and name on the left. Click the name to open a small popover with: | Field | Description | | - | - | | **Basis** | The orbit source the row's opportunities were computed from. | | **Reach** | How far this spacecraft-AOI pair's forecast currently extends. | | **Count** | The spacecraft's opportunity count for this AOI, over the drawn horizon. | To the right, the spacecraft's opportunities are drawn as small marks positioned in time. Click a mark to open a popover with: | Field | Description | | - | - | | **Spacecraft** | The spacecraft's name. | | **AOI** | The name of the AOI this opportunity belongs to. | | **Entry** | The instant the opportunity enters (UTC). | A mark's popover open on the timeline, showing Spacecraft, AOI, and Entry for the selected opportunity A row that cannot show opportunities says exactly why, instead of just showing nothing: | Row State | What You See | What To Do | | - | - | - | | **Computed, with opportunities** | Live track with marks; count shown beside the spacecraft name | Nothing to do — this spacecraft contributes. Select a mark to inspect it. | | **Computed, no opportunities (drought)** | Live, un-struck track labelled `No opportunities in this span` | Nothing is wrong — this spacecraft genuinely flies nothing over the area in this stretch. Not an error, not a gap in the forecast. | | **Not computed** | Track struck out end to end, labelled `Not computed` | The area has never been evaluated for that spacecraft — run **Recompute** on the AOI's [Overview](/features/areas-of-interest/overview) page. | | **No orbital data available** | Struck-out track labelled `No orbital data available` | The spacecraft has no [state vector](/features/state-vectors) to propagate from — supply one. | | **Orbital data is too old** | Struck-out track labelled `Orbital data is too old` | Refresh the spacecraft's orbital data. | | **No public orbital data available** | Struck-out track labelled `No public orbital data available` | No catalogue orbit could be fetched for this spacecraft — supply orbital data directly. | | **Computation failed** | Struck-out track labelled `Computation failed` | The computation for that spacecraft-AOI pair errored — retry via **Recompute** on the AOI's Overview page. | | **Computation timed out** | Struck-out track labelled `Computation timed out` | The computation ran out of time for that spacecraft-AOI pair — retry via **Recompute** on the AOI's Overview page. | Past a row's own forecast reach, its track is struck out with the same diagonal-hatch treatment and labelled `Beyond computed coverage` — a spacecraft recomputed less recently than its neighbours simply reaches less far, without affecting any other row. Every row's opportunity count is normalised to the same drawn horizon, so two spacecraft are directly comparable regardless of which one was recomputed most recently. A spacecraft with no imaging payload configured never appears on this page at all — see [Every AOI at Once](#every-aoi-at-once) above. Every other exclusion reason still gets its own labelled row. ## Filtering Three filters narrow what the page draws, all in the shared top bar: | Filter | Behaviour | | - | - | | **Tags** | Multi-select. An AOI passes when it carries at least one selected tag. Shared with [Overview](/features/areas-of-interest/overview#right-pane-aoi-list) and [Map](/features/areas-of-interest/map). | | **Status** | Multi-select, options **Active**, **Inactive**, **Out of window**. An AOI passes when its status is in the selected set. Shared with Overview and Map. | | **Spacecraft** | Multi-select. Narrows every AOI's rows to the selected spacecraft. Options are every spacecraft that has a row anywhere on the timeline right now — every exclusion reason except no imaging payload configured (see [Every AOI at Once](#every-aoi-at-once) above) still contributes a row, and so still offers that spacecraft as a filter choice. | Every filter is an any-of match — leaving it empty is a no-op. Narrowing the Spacecraft filter to a spacecraft with no opportunities in a given AOI leaves that AOI's header row visible with nothing beneath it, the same way an out-of-window AOI does. ## Empty and Error States If the page can't load, it shows **Couldn't load overflight opportunities** with a **Retry** button in place of the canvas. While the AOI list itself is loading, the page shows a placeholder skeleton in the same row shape as the finished page. ## Related Pages * [Areas of Interest overview](/features/areas-of-interest/overview) — read one AOI in depth, edit its identity and geometry, and trigger a recompute. * [Overflight events](/features/areas-of-interest/overflight-events) — the coverage-state vocabulary this page's row states share with the Overview page's own per-opportunity detail. * [AOI Map](/features/areas-of-interest/map) — every AOI on one world map, with a hovercard summarising each one's next overflight. # Import & Export Attitude Ephemeris Source: https://docs.valar.space/features/attitude/ephemeris Import and export spacecraft attitude ephemeris data using AEM files > For the complete documentation index, see [llms.txt](/llms.txt). Use this page to bring an externally-computed attitude profile into VALAR, recover from a broken AEM import, or hand off a VALAR-computed attitude to a downstream tool. Both flows use the [AEM (Attitude Ephemeris Message)](/file-formats/aem) format — a CCSDS-standard ASCII file carrying time-ordered orientation samples for a spacecraft. **Route:** `/attitude/modes` For attitude mode concepts and the unified workspace catalog, see [Attitude Modes Overview](/features/attitude/overview). For how an imported AEM appears alongside other entries in the transition schedule, see [Schedule attitude transitions](/features/attitude/transitions). ## Importing an AEM File Click the **Import** button in the attitude modes page header to open the **Import AEM file** dialog. The dialog accepts `.aem` and `.txt` files up to **50 MB**. Drop a file directly onto the upload zone — labelled **Drag and drop an AEM file here or click to browse** — or click the zone to pick a file with the system file picker. Import AEM file dialog with drag-and-drop upload zone VALAR ingests CCSDS AEM files using the **quaternion** attitude type (`QUATERNION`, `QUATERNION/DERIVATIVE`, `QUATERNION/RATE`, `QUATERNION/ANGVEL`). Files using Euler angles or other attitude representations are rejected with a validation message (see below). On a successful import, every attitude sample window from the file is added to the spacecraft's transition schedule as a `CUSTOM` mode row, sequenced by the file's `START_TIME` and `STOP_TIME`. The new transitions appear in the transition table alongside any operator-scheduled mode transitions. When you next view the **Quaternions** tab during a window covered by this AEM file, the quaternion charts surface the file's `REF_FRAME_A` header verbatim in the [reference-frame indicator badge](/features/attitude/visualization#reference-frame-badge) — including free-form custom frames such as `ROLL_PITCH_YAW` that are preserved exactly as your source tool wrote them. Click **Learn more** on the badge to open the [reference frame catalog](/platform-overview/reference-frames). Before the file reaches the backend, the dialog rejects non-AEM extensions with the literal message **"Only .aem and .txt files are supported."** and oversized files with the size message documented in **AI-4004** below. All other rejections come from backend validation. ## AEM Import Validation Messages When the AEM file is rejected, the dialog surfaces an error message that describes why. Each backend error code carries a fixed user-facing message; some include `{...}` placeholders that the dialog substitutes at runtime, as detailed below the table. | Code | Message | Meaning | | - | - | - | | **AI-4001** | That file doesn't look like a valid CCSDS AEM. Check the file and try again. | The upload failed CCSDS AEM parsing. Re-export the file from the source tool and verify it conforms to the AEM v2 standard. | | **AI-4002** | Only quaternion AEM files are supported. | The file uses a non-quaternion `ATTITUDE_TYPE` (for example, `EULER_ANGLE`). Re-export it with `ATTITUDE_TYPE = QUATERNION`. | | **AI-4003** | The AEM file doesn't contain any attitude samples. | The file parsed but its data block is empty. Verify the source generated samples for the requested interval. | | **AI-4004** | The file is `{size}`, which exceeds the `{limit}` limit. | The upload is larger than the 50 MB cap. Shorten the time range or coarsen the sample rate, then re-import. | | **AI-4005** | This file overlaps with "`{filename}`" (`{start}` to `{end}`). | The new file's time window intersects an existing AEM import on this spacecraft. Remove or trim the conflicting import, then retry. | | **AI-4006** | This import would shadow `{count}` existing transition(s). | The new file's time window would override one or more existing scheduled transitions. Remove or reschedule those transitions, then retry. | | **AI-4040** | That AEM import no longer exists. | The AEM import you tried to act on was deleted in another tab or session. Refresh the page and try again. | | **AI-4041** | This spacecraft has no attitude configuration yet. | The spacecraft has no attitude configuration to attach the samples to. Configure attitude first, then re-import. | | **Generic fallback** | An unexpected error occurred. | The backend returned an error that doesn't match any documented code. Retry the upload; if it persists, contact support. | The parameterized messages above fill their placeholders at runtime: * For **AI-4004**, `{size}` is the uploaded file's size and `{limit}` is the maximum allowed size. Both values are formatted in the largest fitting unit — `B`, `KB`, `MB`, or `GB`. * For **AI-4005**, `{filename}` is the conflicting AEM file's name, and `{start}` and `{end}` are the conflicting file's time range in UTC. * For **AI-4006**, `{count}` is the number of existing transitions the new file would shadow. The wording uses `transition` when `{count}` is `1` and `transitions` otherwise. ## Recovering from a Broken AEM Import If a previously-imported AEM ends up unreachable — for example, the underlying file was removed or its storage location can no longer be served — VALAR replaces the affected attitude surface (such as the **Quaternions** tab) with a **Broken AEM import** empty state. The empty state names the failing import by its identifier and, when known, the original filename so you can pinpoint which upload is broken. Two recovery paths are available depending on whether you have write access to the spacecraft: * **With write access**, the empty state shows a destructive **Delete this import** button. Click it to open a confirmation dialog with the literal copy **Delete AEM import '`{filename}`'? This cannot be undone.** (or a filename-less variant when the original name is unknown). Confirm to remove the broken record. On success, the empty state clears and you can re-import a corrected AEM file using the **Import** button. If the delete itself fails, the page keeps the broken-import state mounted and surfaces the toast **Failed to delete import — please retry** so you can retry without losing context. * **Without write access**, the **Delete this import** button is replaced with a **Contact support** link. Use it to raise the cleanup with the support team — they will remove the broken import on your behalf. Deleting a broken AEM import permanently removes it from the spacecraft's transition schedule. There is no undo. If the original file is recoverable, save a local copy before deleting so you can re-import it later. ## Exporting Attitude Ephemeris The **Export** button opens the **Export attitude ephemeris** dialog, which generates a CCSDS AEM v2 file containing the spacecraft's computed attitude over a time window. The button sits in the page header next to **Import**, and is available from both the attitude **Modes** page and the attitude **Quaternions** page — the same dialog opens from either. Attitude Modes page with the Export button in the page header, next to Import and Modes library The button is enabled when both of the following are true: * The spacecraft has an attitude configuration (a default mode is set). * The spacecraft has at least one [state vector](/features/state-vectors) so attitude can be sampled against the orbit. If the spacecraft has no attitude configuration, the **Import** and **Export** buttons are not shown — the page displays an attitude setup prompt instead. If the spacecraft has an attitude configuration but no state vector, the **Export** button is rendered as disabled with a tooltip naming the missing piece. The dialog title carries a spacecraft selector dropdown so you can switch the target spacecraft from inside the dialog. Export attitude ephemeris dialog showing the Quaternions and Euler angles representation cards with per-card reference-frame selectors and the Euler rotation-sequence selector, above the Time Step slider and Start and End date pickers ### Representations and reference frames The dialog presents two **representation cards** — **Quaternions** and **Euler angles**. Tick a card to include that representation in the file; tick both to write a single file carrying one segment per representation. The default selection is **Quaternions** in **EME2000**, so leaving the cards untouched reproduces the classic single-quaternion export. | Representation | Reference frame | Rotation sequence | | - | - | - | | **Quaternions** (default) | `EME2000` (default), `ITRF2014`, or `LVLH_ROTATING` | — | | **Euler angles** | `EME2000` (default), `ITRF2014`, or `LVLH_ROTATING` | `ZYX` (default), `XYZ`, or `ZXY` | * The **Quaternions** card exposes **no** convention selector. CCSDS 504.0-B-2 mandates scalar-last quaternion ordering, so there is nothing to choose. * The **Euler angles** card writes the attitude as RPY (roll, pitch, yaw) angles and adds a **Rotation sequence** selector — `ZYX` (default), `XYZ`, or `ZXY`. * Each card has its own **Reference frame** selector — `EME2000`, `ITRF2014`, or `LVLH_ROTATING` — so a combined export can express each segment in a different frame. When a card's reference frame is set to `LVLH_ROTATING`, the dialog shows the notice **AEM is not self-contained in LVLH. Consumer must also fetch the companion OEM.** An LVLH attitude file is only meaningful alongside the orbit ephemeris it was expressed against — the [AEM reference](/file-formats/aem) describes the companion-OEM `COMMENT` block VALAR writes so the consumer can locate it. An `ITRF2014` reference frame uses the EOP 14 C04 Earth-orientation realization (EOP 14 C04 → ITRF2014). Consumers pinned to ITRF2020 should confirm compatibility before consuming the file — the two realizations agree only to the few-millimetre level. ### Time window and sampling | Field | Description | | - | - | | **Time Step** | A slider for the sampling interval between attitude samples in the file. Accepts values from `10` s to `300` s in 10-second steps. Default: `60` s. The current value (e.g., `"60 s"`) is shown to the right of the label. | | **Start Date (UTC)** | A `HH:MM` time input on the right of the row sets the time-of-day, and a 7-day MiniCalendar carousel below sets the date. Use the left/right chevrons to navigate the carousel one 7-day window at a time; click a day cell to select it. The currently-selected day is highlighted; the current day (when not selected) is rendered with a secondary background. | | **End Date (UTC)** | Same shape as **Start Date** — a time input plus a 7-day MiniCalendar carousel. The end must be strictly later than the start, and the total window must not exceed 7 days. | All timestamps are interpreted as UTC. ### Generating the file Click **Generate & Download** to produce the file. While VALAR computes the attitude over the requested window, the dialog displays a `Computing attitude ephemeris…` progress indicator. When the file is ready, your browser saves it locally and a confirmation toast — **Attitude ephemeris export ready** — appears. If the backend rejects the request, the dialog stays open with your inputs intact, displays the reason, and surfaces a matching toast so you can adjust the inputs and retry without re-entering data. The downloaded file is a CCSDS AEM v2 document. By default it carries scalar-last quaternion samples (`Q1 Q2 Q3 QC`); the reference frames and Euler sequence you choose are reflected in each segment's metadata. See the [AEM format reference](/file-formats/aem) for the full structure, including the two-segment layout written when you select both representations. ### Euler-angle singularities Euler angles are undefined at gimbal lock (pitch at ±90°), where a single rotation sequence cannot describe the orientation. If the chosen Euler sequence is singular at any sample in the requested window, the export is refused with a **400** response, error code **AE-4007**, and the dialog shows the alert **RPY sequence is singular at this timestamp** — with the offending timestamp and **two suggested alternative Euler conventions** offered as one-click buttons (for example, **Try `XYZ`** or **Try `ZXY`**). Pick a suggested sequence and run the export again. **Quaternion exports are never refused** — they have no singularity — so a file that includes the **Quaternions** card always contains that segment. *** Understand attitude modes, body axes, target types, and the unified workspace catalog Browse, create, edit, and delete modes in the workspace catalog Plan time-anchored mode switches and override the default Inspect quaternion and Euler angle plots over time AEM structure, quaternion ordering, reference frames, time systems, and a sample file # Attitude Modes Source: https://docs.valar.space/features/attitude/modes View, create, edit, and delete attitude modes in your workspace > For the complete documentation index, see [llms.txt](/llms.txt). Use this page to manage the attitude mode catalog from the operations dashboard. For an introduction to what an attitude mode is, what body axes mean, and how target types fit together, see [Attitude Modes Overview](/features/attitude/overview). **Route:** `/attitude/modes` ## Opening the Modes Library From the attitude modes page header, click **Modes library** to open the workspace catalog. The button sits on the right of the header, alongside **Import** and **Export**. Clicking it opens a wide modal overlay that fills most of your screen. Inside the overlay, the catalog is rendered as a master-detail editor. The list of modes runs down the left; selecting a mode opens its configuration on the right. ## Viewing the Catalog The catalog is a single flat list of every attitude mode defined in your workspace, sorted alphabetically by display name. The five pre-installed modes — Earth-pointing, Sun-pointing, Velocity-tracking, Inertial-pointing, and Free drift — appear inline with any modes you have created yourself. Pre-installed modes carry no badge or visual distinction — every mode in the catalog exposes the same Edit, Set as default, and Delete affordances. The `CUSTOM` placeholder that appears in attitude data imported from [AEM](/file-formats/aem) files is intentionally excluded from this library — those entries live on the [transition schedule](/features/attitude/transitions) instead and can only be added or removed by importing or removing the source `.aem` file. ## Creating a Mode Click **+ New** at the top of the library list to open the **Create attitude mode** form on the right. The dropdowns inside the form use the platform's internal target and axis identifiers. Match them to your physical setup using this table: | What you want the body axis to track | **Primary Target** dropdown value | Extra parameter | | - | - | - | | **The Sun** | `SUN_DIRECTION` | None | | **The Moon, Mars, Jupiter, Saturn, Venus, or Mercury** | `CELESTIAL_BODY` | Body picker (`MOON`, `MARS`, `JUPITER`, `SATURN`, `VENUS`, `MERCURY`) | | **Earth nadir** — the geodetic point directly below the spacecraft | `GEODETIC_NADIR` | None | | **A fixed direction on the celestial sphere** — a star, calibration source, or fixed beacon | `FIXED_INERTIAL` | Right ascension `0` to `359.999` degrees and declination `-90` to `90` degrees | | **A ground station** in your workspace | `GROUND_POINT` | Ground-station picker populated from your workspace's ground-station list | | **The spacecraft's velocity vector** | `VELOCITY_VECTOR` | None | | **The projection of velocity onto the ground track** | `GROUND_TRACK_VELOCITY` | None | | **The orbit's angular-momentum vector** | `ORBIT_ANGULAR_MOMENTUM` | None | See [Target Types](/features/attitude/overview#target-types) for the conceptual background. To create a mode: Type a name into **Display name**. This is the only required field and is limited to 100 characters; the form blocks submission above that limit. Use **Description** to record free-form notes about the mode (intent, mission rationale, references). Limited to 500 characters; leave it blank if you don't need it. Open the **Primary Target** dropdown and pick the value matching your row in the table above. If the target needs extra parameters — a celestial body, a ground station, or right ascension and declination — the form reveals those inputs below the dropdown. Choose which face of your spacecraft tracks the primary target. The **Primary Body axis** dropdown offers `PLUS_X`, `MINUS_X`, `PLUS_Y`, `MINUS_Y`, `PLUS_Z`, and `MINUS_Z`. See [Body Axes](/features/attitude/overview#body-axes) if you're unsure which face corresponds to each. The **Secondary Target** and **Secondary Body axis** controls work the same way and resolve the remaining rotational degree of freedom around the primary direction. The **Secondary Body axis** dropdown disables the axis letter you used for the primary: if your primary is `PLUS_X`, both `PLUS_X` and `MINUS_X` are unavailable for the secondary, so the form forces the two axes onto different physical dimensions. Click **Create**. On success the dialog closes and a confirmation toast appears: "Attitude mode created". The new mode is immediately visible in the library and in every mode picker in your workspace. ## Editing a Mode Every mode in the catalog is editable, including the five pre-installed modes. Pick a mode in the library list — the right panel becomes the **Edit attitude mode** form, pre-filled with the mode's current values. The fields and validation rules are identical to those described in [Creating a mode](#creating-a-mode). Click **Update** to save. The dialog closes and a confirmation toast appears: "Attitude mode updated". Editing a mode applies workspace-wide. Every spacecraft that references the mode — as its default, on a scheduled transition, or anywhere a mode picker uses it — picks up the new configuration on its next attitude calculation. You do not need to touch each spacecraft individually. ## Deleting a Mode Click **Delete** on the mode you want to remove. The confirmation dialog auto-selects one of three branches based on how the mode is currently used in your workspace. The dialog reads "This mode is not currently used by any spacecraft. This cannot be undone." The footer carries **Cancel** and a destructive **Delete** button. Click **Delete** to remove the mode. A confirmation toast appears: "Attitude mode deleted". The mode is removed from the workspace catalog and disappears from every mode picker. When the mode you want to delete is referenced by at least one upcoming scheduled transition, the dialog shows: * The affected transition count and spacecraft count, for example "This mode is used in 4 upcoming scheduled transitions across 2 spacecraft." * The follow-on statement that deleting will rewrite those transitions: "Deleting it will rewrite those transitions to each spacecraft's current default mode. This cannot be undone." * A table listing each affected transition: the spacecraft name, the transition time, and the default mode the transition will rewrite to. * A footer with **Cancel** and a destructive **Delete and rewrite transitions** button. Confirming the delete removes the mode from the catalog and rewrites every listed transition to the current default mode of its affected spacecraft. The transitions stay on the schedule with their original times — only the target mode changes. When the mode is configured as the default attitude mode on at least one spacecraft, the delete is blocked. The dialog shows: * The inline message: "This mode is set as the default attitude mode on the following spacecraft. Change the default elsewhere before deleting." * A list of the spacecraft using this mode as their default. * A footer with only a **Close** button — no Delete button is offered. Open each affected spacecraft's [transition schedule](/features/attitude/transitions), set a different mode as the default, then return to the library and retry the delete. ## Free Drift: Missing Required Inputs Free drift needs all three initial body angular-velocity components and the spacecraft's configured principal moments of inertia. Zero angular velocity is valid when explicitly supplied; a missing component is not zero. Those dynamics do not determine an absolute orientation. Propagation also needs a real orientation at the free-drift activation epoch. When a preceding active attitude interval supplies an attitude at the transition boundary, VALAR can use that handoff. It does not assume identity orientation or move the activation epoch to a clipped query start. An orientation-unavailable error (`AE-4016`) means that handoff/anchor is missing. Include the preceding supported attitude interval and actual transition boundary where available, or use a configured pointing mode or an imported [AEM ephemeris](/features/attitude/ephemeris). Do not expect an unanchored free-drift interval to become usable by entering inertia and body rates alone. Precise numerical attitude propagation also requires real spacecraft mass; an unavailable-mass error requests that input rather than using a generic satellite mass. ## Error States Three toasts surface when create, edit, or delete cannot complete. In every case the dialog stays open so you can retry without losing your edits. | Situation | Toast | What to do | | - | - | - | | **The mode was deleted by another session** while your dialog was open (404 race). | "This attitude mode no longer exists" | Close the dialog — the mode is gone from the catalog already. | | **Another session set the mode as a default** after your deletion-impact preview loaded (422 race). | "Cannot delete mode — it is the default for one or more spacecraft" | Close the dialog, reopen the library to refresh the impact preview, and either change the default on the affected spacecraft or pick a different mode to delete. | | **The server fails to save** the create, edit, or delete — HTTP 5xx, network outage, or a generic 422 payload error. | "Failed to save mode — please retry" | Your edits remain in the form — click the save button again to retry. | *** Concepts, body axes, target types, and the unified workspace catalog Plan time-anchored mode switches and override the default Exchange attitude ephemeris with external partners Inspect orientation over time on the operations dashboard ## Angle display When **Angle display** is available for your account, select a mode in **Modes library** and click **Edit angle display**. This changes how Euler angles are read, independently of the mode's pointing definition. It applies to every spacecraft using the mode in this organization and environment, including readouts of historical windows. Use separately named modes when spacecraft need different body-axis conventions. Choose an intrinsic Euler sequence: **XYZ (1-2-3)**, **XZY (1-3-2)**, **YXZ (2-1-3)**, **YZX (2-3-1)**, **ZXY (3-1-2)** or **ZYX (3-2-1)**. The axes remain right-handed; values are in degrees, with X, Y and Z also labelled roll, pitch and yaw. The zero reference is either **EME2000** or **Geometric zero**. For a geometric zero, choose a primary body direction and target, then a secondary body direction and target. The primary aligns exactly; the secondary fixes a plane around it, rather than requiring both targets to align exactly. Signed-axis shortcuts and arbitrary XYZ vectors support directions such as an oblique thruster. Vector magnitude does not matter; vectors must be nonzero and nonparallel. Targets include nadir, Sun, inertial velocity, ground-track velocity, orbit normal, a fixed inertial direction, a celestial body or a ground station. Supply the target's parameters when prompted. **Copy current pointing definition** copies the available axis/target definition into an independent display zero. Later pointing edits do not change that copy. Check it before saving. Click **Save angle display** to persist the settings. Free drift has its own display zero; it does not inherit the previous mode's display reference. Imported AEM windows use Standard EME2000 / 3-2-1. Angle-display edits do not change pointing, physical attitude, quaternion plots, the 3D view, maneuvers, forces or exported attitude. # Attitude Modes Overview Source: https://docs.valar.space/features/attitude/overview Understand attitude modes, body axes, target types, and the unified workspace catalog > For the complete documentation index, see [llms.txt](/llms.txt). Attitude is how your spacecraft is oriented in space at any given moment. The platform organizes orientation around **attitude modes** — named configurations that describe which way your spacecraft points and why. Use this page to understand what an attitude mode is, how body axes and targets fit together, and how the workspace catalog of modes feeds every spacecraft you operate. ## What Is an Attitude Mode An **attitude mode** is a named configuration that determines how your spacecraft orients itself relative to the world around it. Each mode answers two questions: which axis on your spacecraft is the primary pointing direction, and what target should that axis follow. Different mission phases demand different orientations: * **Imaging passes** require the camera-bearing face to point at the ground. * **Solar charging** requires the panels to face the Sun. * **Communication windows** require an antenna to track a ground station. * **Thermal management** requires a radiator to face cold space, away from the Sun or the Earth. * **Safe-mode recovery** requires the spacecraft to stop active control and let its dynamics settle. You assign one mode at a time to your spacecraft. As mission needs change, you switch modes — either by editing the default mode or by scheduling a transition for a specific time window. The platform handles the rest: computing the orientation, exposing it on plots and exports, and using it consistently across all downstream features. ## The Five Pre-Installed Modes Every workspace ships with five attitude modes already in the catalog, ready to use on day one. You can edit, rename, or delete any of them — they behave identically to modes you create yourself, with the same dialogs, the same fields, and the same delete confirmation. | Mode | What It Does | Canonical Use | | - | - | - | | **Earth-pointing** | Tracks the geodetic nadir — the point on Earth directly below | Imaging, ground observation, payload-down operations | | **Sun-pointing** | Tracks the Sun's direction in the sky | Solar power generation, Sun-relative thermal control | | **Velocity-tracking** | Tracks the orbital velocity vector — the direction of motion | Drag minimization, ram-direction sensors | | **Inertial-pointing** | Holds a fixed direction on the celestial sphere (right ascension and declination) | Targeting a star or other celestial source, instrument calibration | | **Free drift** | Disables active control and lets the spacecraft tumble under its dynamics | Safe-mode operations, orbital decay analysis | Each pre-installed mode is fully editable. You can rename Earth-pointing to "Imaging" if that matches your mission language, change which body axis it points with, or delete it entirely if your mission doesn't use it. ## Body Axes Your spacecraft has its own internal coordinate system, defined relative to its physical geometry. The platform refers to the six directions along that coordinate system as **body axes**: | Axis | Description | | - | - | | **+X** | Forward face along the spacecraft's X dimension | | **-X** | Aft face along the spacecraft's X dimension | | **+Y** | Top face along the spacecraft's Y dimension | | **-Y** | Bottom face along the spacecraft's Y dimension | | **+Z** | Front face along the spacecraft's Z dimension | | **-Z** | Rear face along the spacecraft's Z dimension | Body axes are anchored to the spacecraft itself — they rotate with it. When you say "point the **+X** body axis at the Sun," you are telling the platform: take the face of your spacecraft that corresponds to the +X direction, and keep it aimed at the Sun, no matter how the spacecraft moves through its orbit. The exact physical face each axis represents depends on how you described your spacecraft's geometry. The X, Y, and Z dimensions you entered when [creating your spacecraft](/getting-started/first-spacecraft) define the body frame the platform uses for every attitude calculation. If your camera sits on the +Z face and your antenna sits on the -Y face, you reference those faces using **+Z** and **-Y** when configuring modes. When you configure a mode, you choose: * A **primary body axis** — the face that must point at the primary target. * A **secondary body axis** — the face that resolves the remaining rotational degree of freedom by pointing at, or away from, a secondary target. Together, the primary and secondary axis assignments fully determine the orientation of your spacecraft. ## Target Types A target tells the platform what each chosen body axis should track. Targets fall into three families, each with its own behaviour over time. ### Celestial Body A celestial body is something whose position the platform computes from astronomical models. The available bodies include: * **Sun** — used by Sun-pointing modes, and by anything that needs solar reference. * **Moon** — useful for Moon-relative observation or Moon-aware thermal control. * **Earth nadir** — the geodetic point on Earth directly below your spacecraft, used by Earth-pointing modes. Celestial-body targets move continuously through the inertial frame, and the platform tracks them dynamically. Your chosen body axis stays locked on the target as the geometry evolves throughout the orbit. ### Ground Station A ground station is a fixed geographic point on Earth's surface — a real antenna site, a calibration target, or any location described by latitude and longitude. Ground stations don't move in the Earth-fixed frame, but they sweep through the inertial frame as the planet rotates. As your spacecraft moves through its orbit and the Earth rotates beneath it, the platform updates the geometry continuously so your chosen body axis stays aimed at the station. ### Fixed Inertial Direction A fixed inertial direction is a point on the celestial sphere identified by its **right ascension** and **declination** in degrees. Use this when you want to point at a star, a fixed beacon, a calibration source, or any direction that does not move with Earth, the Sun, or your spacecraft. The direction stays locked in the inertial frame; the platform handles the rotation needed to keep your chosen body axis aimed at that point as the spacecraft orbits. ### Which Modes Use Which Targets | Mode | Primary Target | | - | - | | **Earth-pointing** | Earth nadir (celestial body) | | **Sun-pointing** | Sun (celestial body) | | **Velocity-tracking** | Orbital velocity vector (a derived dynamic direction) | | **Inertial-pointing** | Fixed inertial direction (right ascension and declination) | | **Free drift** | None — no active control | ## The Workspace Catalog The platform maintains a single shared **attitude mode catalog** for each workspace. Every mode you see anywhere in the platform — whether you are editing a default mode, scheduling a transition, or browsing the modes list — comes from this one catalog. A few principles follow from that: * **Every mode is editable.** You can rename any mode, change its targets, change its body-axis assignments, or update its description. There is no protected subset. * **Every mode is deletable.** Any mode you no longer need can be removed using the same delete confirmation as any other. Deleting a mode that is currently active or scheduled will prompt you to choose a replacement first. * **Every mode is a full citizen.** The five pre-installed modes use the same dialog, the same fields, and the same affordances as the modes you create yourself. There are no badges, labels, colors, or icons that distinguish a pre-installed mode from one you authored. * **Every spacecraft draws from the same catalog.** When you assign a default mode or schedule a transition for any spacecraft in the workspace, the picker shows the same set of modes. Edits you make to a mode propagate everywhere the mode is referenced. This unified model means you can curate one canonical set of orientations for your operation and reuse them across your fleet, without duplicating configuration per spacecraft. ## Default Mode and Transitions Each spacecraft has exactly one **default attitude mode**. The default is the orientation the spacecraft holds whenever no scheduled transition is currently active — think of it as the fallback the spacecraft falls back to between operations. On top of the default, you can schedule **attitude transitions**: time-anchored switches that override the default for a specific window. A scheduled transition activates at its transition time and remains active until the next scheduled transition (or until you remove it, in which case the default resumes). The flow is simple: * **No transitions scheduled:** the spacecraft holds the default mode at all times. * **One transition scheduled at time T:** the spacecraft holds the default before T and switches to the scheduled mode at T. * **Multiple transitions:** the spacecraft switches at each transition time in order; the default fills any gap before the first transition. For details on scheduling, editing, and removing transitions, see [Schedule attitude transitions](/features/attitude/transitions). ## Effect on Force Modelling Configuring an attitude profile — a default mode plus any scheduled transitions — on a spacecraft that **also** has geometry configured automatically upgrades every numerically-propagated analysis for that spacecraft to attitude-dependent drag and SRP. Without an attitude profile the spacecraft remains on the isotropic model regardless of how detailed its geometry is. See [Force Model](/platform-overview/force-model) for the eligibility rule and the list of analyses affected. *** Browse, create, edit, and delete modes in the workspace catalog Plan time-anchored mode switches and override the default Exchange attitude ephemeris with external partners and tools Inspect orientation over time on the operations dashboard # Attitude Transitions Source: https://docs.valar.space/features/attitude/transitions Schedule and manage attitude mode transitions for your spacecraft > For the complete documentation index, see [llms.txt](/llms.txt). Use this page to schedule when your spacecraft switches between attitude modes, pick the **default mode** the spacecraft falls back to between transitions, and configure free-drift dynamics for an uncontrolled, torque-free orientation. For attitude mode concepts — what a mode is, body axes, target families, and the unified workspace catalog — see [Attitude modes overview](/features/attitude/overview). **Route:** `/attitude/modes` ## The Transition Schedule The **Transition Schedule** card lives in the main column of the attitude modes page, below the mode carousel and the Euler-angle plot. It lists every scheduled mode transition for the selected spacecraft in chronological order, alongside any CUSTOM-mode windows imported from AEM files. Each row shows: * The **target mode** the spacecraft will adopt at the transition time. CUSTOM rows (created by AEM imports) display **File Import** in place of a mode name, with a small badge naming the source `.aem` or `.txt` file. * The **scheduled time**, formatted as `MMM DD, HH:MM` in UTC (for example, `Apr 14, 08:56`). * An actions menu with **Edit** and **Delete** entries. CUSTOM rows handle these differently — see [CUSTOM Windows from AEM Imports](#custom-windows-from-aem-imports) below. By default the table hides past events and shows upcoming transitions only. Open the gear menu in the card header and tick **Show past events** to include scheduled times that have already elapsed. ### The right-hand modes panel The attitude modes page has a second column on the right that lists every attitude mode in your workspace catalog. The header carries a panel-toggle icon (the right-panel glyph next to the **Import** and **Export** buttons) — click it to hide or show the modes panel and reclaim screen space for the schedule and plots. ### Empty state When no transitions are scheduled and no AEM imports have been added, the **Transition Schedule** card replaces the row list with a centered **No transitions scheduled** message and a single **Add transition** button. Clicking the button opens the same scheduling dialog as the **Add transition** action in the card header. ## Scheduling a Transition Click **Add transition** in the **Transition Schedule** card header to open the **Add Transition** dialog. Every scheduled transition is time-anchored: it activates at a single UTC instant and remains active until the next transition (or until the schedule returns to the default mode). To schedule a transition: Type the time of day into the `HH:MM` input — the dialog auto-inserts the colon as you type. Then pick the date from the 7-day MiniCalendar carousel below the input. Use the left and right chevrons to navigate the carousel one week at a time. The carousel only allows dates between **today** and **today + 30 days**; days outside that window are disabled. Open the **Target mode** dropdown and pick any mode from the workspace catalog. CUSTOM is not selectable — CUSTOM windows can only be added via [AEM import](/features/attitude/ephemeris). If you pick **Free drift**, the dialog reveals an extra section for the torque-free dynamics needed to integrate the spacecraft's tumble. See [Free-Drift Dynamics](#free-drift-dynamics) below for the field reference. Click **Create**. The dialog closes on success and the new row appears in the **Transition Schedule** card, sorted by transition time. If the chosen time falls inside an existing AEM-imported CUSTOM window, the dialog stays open and surfaces an inline message naming the conflicting file and its time range — pick a different time, or delete the conflicting import first and retry. To change a previously scheduled transition, open the row's actions menu and click **Edit**. The dialog re-opens with the existing values pre-filled and a **Update** button in place of **Create**. CUSTOM rows do not expose **Edit** because their times are bound to the AEM import. ## The Default Mode Each spacecraft has exactly one **default attitude mode** — the orientation the spacecraft holds whenever no scheduled transition is active. The default is the fallback the schedule returns to between operations: * **No transitions scheduled:** the spacecraft holds the default mode at all times. * **One transition scheduled at time `T`:** the spacecraft holds the default before `T` and switches to the scheduled mode at `T`. * **Multiple transitions:** the spacecraft switches at each transition time in order; the default fills any gap before the first transition. You set and change the default from the **Attitude Modes** panel on the right of the page. Each mode card carries an actions menu — click **Set as default** on the mode you want to become the new fallback. The current default is marked with a **Default** badge. Selecting **Free drift** as default reveals the [free-drift dynamics form](#free-drift-dynamics) inline on the card. Setting the default mode rewrites which mode is active **between** scheduled transitions. It does not modify the rows in your transition schedule. ## CUSTOM Windows from AEM Imports When you import a CCSDS AEM file from the attitude modes page header, every attitude sample window in the file is added to the **Transition Schedule** card as a **CUSTOM** row. CUSTOM rows coexist with manually scheduled transitions and are sequenced into the same chronological list using the file's `START_TIME` and `STOP_TIME`. CUSTOM rows behave a little differently from manually scheduled transitions: * The mode column displays **File Import** with a file-name badge instead of a regular mode name. * The actions menu hides **Edit** — the time and duration of a CUSTOM window are fixed by the source AEM file. * Clicking **Delete import** on a CUSTOM row opens a confirmation dialog that warns the deletion will remove both the AEM import and its associated transitions. * New manually scheduled transitions cannot land inside an existing CUSTOM window. If the **Add Transition** dialog detects a collision, it surfaces an inline error naming the conflicting file. For the full AEM ingest flow, supported file types, validation messages, and the export counterpart, see [Import & Export Attitude Ephemeris](/features/attitude/ephemeris). ## Free-Drift Dynamics The **Free drift** mode disables active control and lets the spacecraft tumble under torque-free dynamics. Because two spacecraft running the same Free-drift mode have different inertias and different initial spin states, the physical inputs that drive the torque-free integration are configured **per spacecraft**, not per workspace mode. The free-drift form is rendered inline in two places, with identical fields: * Inside the **Add Transition** dialog, whenever you pick **Free drift** as the target mode of a scheduled transition. * Inside the **Attitude Modes** panel on the right of the page, when you select **Set as default** on the **Free drift** card. The form has three groups of three fields each: | Group | Fields | Unit | | - | - | - | | **Principal Moments of Inertia** | Ixx, Iyy, Izz | kg·m² | | **Inertia Axis Assignments** | Inertia axis Ixx, Inertia axis Iyy, Inertia axis Izz | Body axis (+X, -X, +Y, -Y, +Z, -Z) | | **Initial Angular Velocity** | ωx, ωy, ωz | rad/s | The three principal moments describe the spacecraft's resistance to rotation about its own inertia axes; the three axis assignments tell the platform which body face each principal moment is aligned with; the three initial angular velocity components seed the torque-free integration at the transition's start time. A footnote at the bottom of the form reads **Free drift is computed using torque-free dynamics**. All nine values are validated as you edit, and the **Create**, **Update**, or **Set as Default** button stays disabled until every input is valid. *** Understand attitude modes, body axes, target types, and the unified workspace catalog Browse, create, edit, and delete modes in the workspace catalog Exchange attitude ephemeris with external partners and tools Inspect quaternion and Euler angle plots over time ## Attitudes generated by operations When operation attitudes are enabled for your workspace, **Operation attitudes** in the attitude view lists approved maneuvers and booked station passes or AOI overflights. Each entry shows its source, interval, pointing and status. Choose the UTC date window to inspect upcoming or earlier operations. Select **Operation pointing** while booking, or use **Configure later**. In the saved booking, **Save pointing** updates the same operation. Maneuvers use their existing thrust pointing. KSAT reservations generate attitudes only after the provider confirms acceptance, using its confirmed interval. **Scheduled** means the pointing requirement can be applied during the operation. Afterward, the applicable manual/default attitude resumes. **Unresolved** means configuration is missing or an attitude conflict needs your attention. Conflicts do not block booking or approval and do not silently override the manual schedule. Overlapping operations remain unresolved until you edit or cancel the conflicting source. No slew feasibility is calculated by this scheduling integration. Follow an entry's source link to change it. Cancelling a local booking removes its generated attitude while retaining the saved inspector. Use the existing KSAT cancellation action for provider reservations; the attitude follows the confirmed provider result. Reversing maneuver approval removes the corresponding generated requirement. Generated entries are not independently editable manual transitions. # Attitude Visualization Source: https://docs.valar.space/features/attitude/visualization Read quaternion and Euler angle plots that show how your spacecraft was oriented over time > For the complete documentation index, see [llms.txt](/llms.txt). VALAR exposes spacecraft attitude through two complementary plots: * A **quaternion time series** on the dedicated **Quaternions** tab, showing the four quaternion components over a chosen time window. * A **roll / pitch / yaw Euler-angle plot** on the **Modes** tab, embedded alongside the mode schedule. Both plots are driven by the same underlying attitude profile — the orientation your spacecraft holds under its active mode and any scheduled transitions. This page explains how to read each one. For attitude concepts (modes, body axes, targets), see [Attitude modes overview](/features/attitude/overview). ## Quaternion plots on the Quaternions tab Open the Quaternions tab from the sidebar at **Attitude → Quaternions**, then pick a spacecraft from the spacecraft selector at the top. The page renders four stacked charts, one for each quaternion component: * **Q1**, **Q2**, **Q3** — the three vector components of the unit quaternion. * **Q4 (scalar)** — the scalar (real) component of the unit quaternion. A quaternion is a four-number description of a rotation. The four values are dimensionless and always lie between **-1 and 1**, so every chart shares the same fixed y-axis. The x-axis is time, labelled with the UTC date. ### Adjusting the time window The time-range pill at the top of the page controls how much history and forecast appear on each chart. The default is **24 h** — twelve hours of past attitude and twelve hours of forecast around the current moment. You can switch to **12 h** for a tighter view or **72 h** for a longer one. If no attitude data is available for the selected window, the charts render blank with no points. ### Reading discontinuities The quaternion `q` and its negation `-q` represent the same physical rotation, so the same attitude can be written in two equivalent ways. When the underlying samples flip sign between consecutive points, the chart draws a **brief gap** instead of an artificial jump from `+0.9` to `-0.9`. Gaps therefore mark sign transitions in the data, not gaps in coverage. Sign flips most often appear at mode-transition boundaries, because the active and the scheduled modes may produce quaternions with opposite signs even though they describe smoothly continuous orientations. ### What the plotted data reflects The plotted quaternions reflect your spacecraft's full attitude schedule: * When no transition is active, the plot follows the spacecraft's **default attitude mode**. * When a [scheduled transition](/features/attitude/transitions) is active, the plot follows the **scheduled mode** for the duration of its window. * After a transition ends, the plot returns to the default mode until the next transition. You do not need to overlay the transition schedule manually — it is already baked into the curve. ### Reference frame badge A reference-frame indicator badge appears next to the chart title on **all four** Q1 / Q2 / Q3 / Q4 cards, showing the frame the body-frame quaternions are expressed against (e.g., `LVLH-CCSDS` for an Earth-pointing mode, or a custom name carried verbatim from an [imported AEM file](/features/attitude/ephemeris) such as `ROLL_PITCH_YAW`). All four cards share the same badge value because the quaternion-profile endpoint carries a single top-level frame for the whole window. Hover the badge for the full frame name; click **Learn more** to open the [reference frame catalog](/platform-overview/reference-frames). ## Euler angle plot on the Modes tab For an operator-friendly view of the same attitude, open **Attitude → Modes**. The right side of the modes page shows a **Roll / Pitch / Yaw** chart that expresses the same attitude as three rotation angles instead of four quaternion components. * **Roll**, **Pitch**, **Yaw** are the rotation angles around the spacecraft's body axes, applied in the **ZYX (3-2-1)** sequence. * Values are in **degrees** and range from **-180 to 180**. The roll / pitch / yaw values are derived from the same underlying attitude profile as the quaternion charts. They are not a new piece of data — just a more human-readable presentation of the same orientation. ### Reference frame The chart subtitle reads **Body w\.r.t. *\* (ZYX / 3-2-1)**. The frame name identifies the reference the rotation is expressed against — for example, `Sun-aligned local frame`, `LVLH-CCSDS`, or `EME2000`. The frame depends on the active mode: a Sun-pointing mode reports angles against a Sun-aligned frame; an inertial mode reports against an inertial frame. For definitions of each frame, see [Reference frames](/platform-overview/reference-frames). A reference-frame indicator badge also appears next to the chart title, showing the same frame as a compact chip. The existing **Body w\.r.t. *\*** subtitle remains alongside the badge — the slight redundancy is intentional: the subtitle is the canonical sentence, the badge is the at-a-glance signal that mirrors what appears on every other plot in the product. Hover the badge for the full frame name; click **Learn more** to open the [reference frame catalog](/platform-overview/reference-frames). Roll / Pitch / Yaw chart with the LVLH-CCSDS frame badge next to the title and the Body w.r.t. LVLH-CCSDS (ZYX / 3-2-1) subtitle below ## Empty and unavailable states Two situations prevent the plots from rendering with data: ### No state vector If the spacecraft has no [state vector](/features/state-vectors), the entire Attitude section shows a **No state vector available** message with an **Add a state vector** button that takes you to the State Vectors page. Attitude cannot be computed without orbital state, so neither the Quaternions tab nor the Modes tab will render their charts until you add a state vector. ### No attitude configuration If the spacecraft has a state vector but no default attitude mode has been set, the Quaternions tab shows a **Configure modes** prompt that links to the Modes tab. The Modes tab in turn lets you pick a default mode and start scheduling transitions — see [Attitude modes overview](/features/attitude/overview). *** Understand attitude modes, body axes, target types, and the workspace catalog Browse, create, edit, and delete modes in the workspace catalog Plan time-anchored mode switches and override the default Exchange attitude ephemeris with external partners and tools ### Per-mode angle readouts When enabled for your account, the **Angle display** selector on the Modes tab offers **Standard (EME2000, 3-2-1)** and **Per-mode**. Each page entry starts in Standard; the view selection is temporary. Configure durable conventions in [Modes library → Angle display](/features/attitude/modes#angle-display). Per-mode covers the selected time window and uses each active mode's saved sequence and zero. Segment descriptions and sample tooltips identify the mode, sequence and zero reference. Missing settings use the labelled Standard default. Imported AEM segments are labelled **Standard — imported attitude**. Invalid saved settings are shown as unavailable until repaired. Lines break at mode boundaries, outer-angle branch wraps, Euler singularities and unavailable geometric references. A gap is an undefined or discontinuous readout, not a zero angle. The middle rotation lies in −90° to +90°; the outer rotations use −180° inclusive to +180° exclusive. Angles are not unwrapped across revolutions. Saving a mode's display settings refreshes affected Per-mode profiles. # Managing Maneuvers Source: https://docs.valar.space/features/burn-plan Create, inspect, edit, delete, import, and export stored spacecraft maneuver records. > For the complete documentation index, see [llms.txt](/llms.txt). The **Maneuvers** page manages stored burn records for your spacecraft. Each record has an editable name, optional purpose, a required reference frame (attitude mode), and one or more burn segments. You can create records manually or import them from OCM files, then read, edit, export, or delete them. Stored records do not certify execution, even when their epochs are in the past. Mission-forecast history therefore shows execution counts and consumed propellant as unavailable when only these generic records exist; forecast estimates and dated state-vector inventory remain separate. **Route:** `/maneuvers/burn-plan` ## Find a record Use the spacecraft and time-range filters to find maneuvers. Grouping by spacecraft keeps records together; the ungrouped view shows a flat list. Select a row to open its details. Checkboxes select records for bulk export or deletion. Rows show the maneuver name, identity/display identifier, spacecraft, timing, and available derived values. A conflict indicator marks overlapping records. A record outside the selected time range may still conflict with a visible one. ## Review records in Flight Plan When Flight Plan is available for your account, open a spacecraft's **Flight plan** and choose **Burn timeline**. Set the UTC period and optionally filter by phase or unassociated records. Imported records remain visible without a source plan. Select a burn to inspect the same complete record and permitted actions here. A linked burn also shows its source plan and saved phase revision. The phase's **Maneuver plans** and **Burns** sections let you review successive proposals and related records without leaving Flight Plan. Return controls keep that context; a burn link can open a record outside the timeline's current period. Use the standalone Maneuvers page for manual creation, import and bulk export or deletion. Presence in a timeline, plan approval or a past epoch does not confirm execution. In Flight Plan, **Execution & analysis** shows matching retained Orbit Determination (OD) estimates when you have orbit read permission. Each estimate names its producing OD result, epoch, production date and convergence. Use **Load more OD results** to inspect older history; a failed read can be retried without discarding loaded results. Different producing results remain separate, and editing the stored maneuver does not update historical estimates. Missing estimates stay unavailable. OD estimates alone do not confirm execution or measured propellant consumption. ## Create a record 1. Click **Create maneuver** in the toolbar. 2. Choose the spacecraft. The selected spacecraft is fixed once the record is created. 3. Enter a name. On creation, this becomes both the stable identity and initial display name. The exact identities `.` and `..` are not permitted because URL routing normalizes them. 4. Choose a **Record frame** and, optionally, a purpose of at most 63 characters. 5. Add at least one burn segment and supply its epoch, duration, thrust vector, ISP, and reference frame. Use **Add segment** or remove a segment as needed. 6. Click **Create maneuver** to save. If validation fails, correct the indicated fields and retry. Segment epochs use ISO-8601 timestamps. Durations and ISP use seconds and thrust uses newtons. Every segment needs a positive finite duration, nonzero finite thrust, and ISP between 50 and 10,000 seconds. Use physical values appropriate to your spacecraft and burn. Reference frames are explicit, with supported examples including `TNW`, `RTN`, `QSW`, and `RSW_ROTATING`; no frame is inferred. Acceleration, delta-V, and delta mass are read-only projections in the detail view and can be unavailable. The record and every segment must use equivalent frames, including their rotation convention. **Use record frame** copies your selected frame to that segment only; it does not transform thrust components. `RTN`, `QSW`, and `RSW_ROTATING` are equivalent here; `TNW` is a different frame. Select the correct frame for the values you are entering. See [supported frames](/file-formats/ocm#supported-reference-frames). A duplicate identity for the same spacecraft is rejected. Creation never updates a record that already exists. Creating a stored maneuver does not send a command to the spacecraft. ## Read complete details Select a record to see its current name, stable **Identity**, **Display ID**, **Spacecraft**, **Purpose**, **Reference frame**, and full burn-segment composition. The details panel retrieves the complete record, so edits start from the stored segments rather than a list summary. **Summary** shows total delta-V, signed delta mass, total burn duration, creation date, and start/end epochs. Burn duration excludes gaps between segments; the start-to-end span includes those gaps. **Performance** shows available recorded performance deviation, normalized performance, pointing azimuth/elevation, and estimated total delta-V. Normalized performance is relative to 100% nominal thrust; performance deviation is relative to 0% nominal deviation. Missing values are labelled **Unavailable**, including when the physical context needed for a projection is absent. A reported zero remains zero; a missing segment value is not treated as zero to produce a total. These values and past epochs do not establish that a stored maneuver was executed. | Action | Result | | - | - | | **Edit** | Open the record's name, metadata, and segment editor | | **Export** | Download an OCM file | | **Delete** | Open a confirmation before removing the record | Create, edit, and import controls require write permission. Deletion requires delete permission; reading and exporting require read permission. Contact your administrator if an action is missing. ## Edit a record 1. Open the record and click **Edit**. 2. Change its name, purpose, attitude mode, or burn segments. 3. Review the complete segment list, including any added or removed segments. 4. Click **Save changes**. The identity and spacecraft are shown as fixed fields. Renaming changes the display name only: links, API requests, and OCM `MAN_ID` still refer to the original identity. Start and end times derive from the segment epochs and durations. To change timing, edit those segment fields directly and review the resulting burn definition. Frames use selectors. A stored token outside the common suggestions remains visible as **retained** until explicitly changed. Saving still applies current frame validation. Changing the record frame does not automatically change segment frames or transform their thrust. Add/remove actions move keyboard focus to the new or remaining segment, and failed saves retain your entries with the error. ## Resolve conflicts New and edited records must not overlap another record on the same spacecraft. The check uses the entire enclosing interval from the maneuver's start to end, including gaps between segments. One record can end exactly when the next begins. Records for different spacecraft are independent. If saving fails, read the error and inspect the conflicting identities. Choose which record to edit or delete, then try again. VALAR does not automatically change other records to make room. Unsaved editor values remain available when a save fails. ### Inspect overlapping records List indicators and record details identify overlaps. Use the **Open** links in details to inspect conflicting records, including records outside the list's current time window. You can read, export, and delete these records. Every save must make the edited record non-overlapping, even when changing only its name or metadata. Resolve the conflict through an explicit segment edit or delete. Computation results retain their captured maneuver information; new computations use the current records. ## Delete records Click **Delete** in a record's details and confirm. To delete several records, select their checkboxes and use the bulk **Delete** action. Check the reported outcome for each action. Deletion removes live maneuver data and cannot be undone. Bulk deletion reports successful and failed counts separately. Successfully deleted records are removed from the selection; failed records stay selected with their error explanations so you can resolve the cause and retry those records. ## Import and export * **Import** adds records from `.ocm` or `.txt` CCSDS OCM files. Each file is atomic; duplicate identities and overlaps are rejected. See [Importing Maneuvers](/features/maneuver-import). * **Export** in a record's details downloads that record; toolbar export selects a spacecraft and date range. The bulk toolbar exports checked records. See [Exporting Maneuvers](/features/maneuver-export). * Programmatic clients use the [Maneuver API](/api-reference/maneuvers) for OCM import, OCM export and deletion. To correct a record, explicitly delete it and import the corrected OCM; these are separate operations, so a failed import leaves the record deleted. Historical records without a usable burn epoch show unavailable timing and remain inspectable by identity. They are not positioned at the current time or their creation date on a timeline. A mixed-frame historical export downloads as a preservation `.zip` rather than `.ocm`; preservation archives are not import requests. ## Timeline View A horizontal Gantt-style visualization of every burn for the selected spacecraft, with orbital events overlaid as bands and markers to give thruster timing the right context. **Route:** `/maneuvers/burn-plan/timeline` The timeline is anchored to a UTC time axis along the top. Each spacecraft row holds the stored burns within the current window, drawn as Gantt-style segments. Orbital events are overlaid above the burn rows as either shaded bands (entry-to-exit duration) or instantaneous markers (single-epoch events). ### Zoom Toggle Two zoom levels control how densely time is packed onto the horizontal axis. | Mode | Description | | - | - | | **Wide** | More pixels per hour, useful for inspecting individual burns and short-duration events | | **Compact** | Fewer pixels per hour, useful for scanning multi-day windows and long-arc revisit patterns | A **Now** button to the right of the zoom toggle scrolls the timeline to the current UTC instant. ### Orbital Events Four orbital event types overlay onto the timeline. Each renders either as a shaded band (covering an entry-to-exit interval) or as an instantaneous marker (a single-epoch crossing). | Event | Display | Description | | - | - | - | | **Eclipses** | Band | Shadow events. Distinguished into **Umbra** (full shadow) and **Penumbra** (partial shadow); each subtype renders as a band spanning entry-to-exit duration | | **South Atlantic Anomaly (SAA)** | Band | Geographic region of elevated radiation; band spans entry-to-exit duration | | **Apsis** | Marker | Periapsis and apoapsis crossings; rendered as instantaneous vertical markers | | **Nodes** | Marker | Ascending and descending node crossings; rendered as instantaneous vertical markers | ### Display Popover Click **Display** in the topbar's right-aligned controls (accessibility name **Display settings**) to open the **Orbital events** popover. Each toggle controls visibility for one event type on the timeline; flipping a toggle is reflected immediately on the visible bands and markers. | Toggle | State | Effect | | - | - | - | | **Eclipses** | On (default) | Show or hide umbra and penumbra bands | | **Apsis** | On (default) | Show or hide periapsis and apoapsis markers | | **Nodes** | On (default) | Show or hide ascending and descending node markers | | **SAA** | On (default) | Show or hide South Atlantic Anomaly bands | ### Schedule Export Dialog Click **Export** in the timeline topbar's right-aligned controls to open the **Export Schedule** dialog. The dialog generates a Spacecraft Schedule File ([`.ssf`](/file-formats/ssf)) listing every selected event over a chosen window. The same dialog is also accessible from the passes timeline at `/passes/timeline`. Export Schedule dialog #### Spacecraft A single-select dropdown listing every spacecraft in your tenant. The dialog defaults to the spacecraft already selected on the timeline. #### Date Range | Element | Description | | - | - | | **Start Date** | Calendar picker; selectable range covers 7 days before today through 7 days after today | | **End Date** | Calendar picker; cannot be earlier than **Start Date** and cannot exceed 7 days after **Start Date** | | **Time inputs** | `HH:MM` format, **UTC** for both Start and End | | **Maximum window** | 7 days | #### Include Five checkboxes determine what the exported `.ssf` file contains. All five are checked by default. With every checkbox unchecked the **Download** button is disabled and the dialog displays the validation message **Select at least one event type**. | Checkbox | State | What it includes | | - | - | - | | **Eclipses** | Checked (default) | Umbra and penumbra entry/exit events | | **Apsis** | Checked (default) | Periapsis and apoapsis crossings | | **Nodes** | Checked (default) | Ascending and descending node crossings | | **Ground Station Passes** | Checked (default) | Visibility windows for selected ground stations | | **South Atlantic Anomaly (SAA)** | Checked (default) | SAA entry/exit events | #### Ground Stations The **Ground Stations** card appears only when **Ground Station Passes** is checked. Use it to restrict the exported passes to specific ground stations. * Click the trigger button to open the picker. * Check the stations to include; leave the selection empty to include all configured stations. * The trigger label reads **All ground stations** when no stations are selected, or **N selected** when one or more are picked. The card's helper text reads **Select specific ground stations or leave empty to include all**. #### Footer | Button | Description | | - | - | | **Cancel** | Close the dialog without exporting | | **Download** | Generate and download the `.ssf` file. While the export is in flight, the button label changes to **Exporting...** | When you export a spacecraft that is running on the fallback (see [Orbit age](/features/orbit-age#degraded-level)), the generated `.ssf` includes that spacecraft's fallback orbital events and carries an in-file `COMMENT Orbital events derived from public TLE - indicative timing` note, so a downstream reader treats their exact timing as indicative. When no fresh orbit is available and the fallback cannot rescue the craft, the file retains the `COMMENT Orbital events unavailable - no fresh state vector` note it carries today. ## Related pages * [Maneuver Planner](/features/planner) — separate plan evaluation and approval workflows * [Importing Maneuvers](/features/maneuver-import) — add records from OCM files * [Exporting Maneuvers](/features/maneuver-export) — share stored records as OCM * [Maneuver API](/api-reference/maneuvers) — authentication, OCM import/export, deletion, and correction examples # CAM Optimization Source: https://docs.valar.space/features/cam-optimization Compute optimal collision avoidance maneuvers from conjunction events > For the complete documentation index, see [llms.txt](/llms.txt). CAM (Collision Avoidance Maneuver) Optimization helps you find the best avoidance maneuver for an active conjunction event. A guided 6-step wizard sweeps through a range of delta-V magnitudes and maneuver directions, filters the results, and lets you select an optimal candidate to create a maneuver plan. **Route:** Opened from the [Conjunction Classification](/features/conjunction-classification) page via the **CAM Optimization** button. ## Wizard Overview The CAM Optimization dialog is a 6-step wizard: | Step | Name | Purpose | | - | - | - | | 1 | Conjunction | Select the conjunction event and alert to analyze | | 2 | Constraints | Configure sweep parameters and thruster | | 3 | Time Filter | Restrict maneuver execution to specific time windows | | 4 | Direction Filter | Constrain maneuver directions using a directional cone | | 5 | Options | Review results and select a candidate | | 6 | Future Impact | Evaluate the selected candidate against other conjunctions | ## Step 1: Conjunction Select the conjunction event and alert data that will be used for the avoidance maneuver computation. CAM Optimization opening state when the selected spacecraft has no active conjunctions ### Spacecraft Selection The spacecraft is selected in the dialog header. Changing the spacecraft resets the conjunction selection. ### Conjunction Selection Use the dropdown to select an active conjunction (only conjunctions with a future TCA are shown). Conjunctions are sorted by TCA ascending, and the first one is selected automatically. Each entry shows the conjunction code with a risk shield icon. Once selected, the conjunction card displays the **TCA** (Time of Closest Approach) and the **Secondary Object** name. ### Alert Selection After selecting a conjunction, choose which alert (CDM) to use as the data source. Alerts are sorted by timestamp with the latest first, and the most recent alert is selected automatically. The alert card shows the **Criticality** level, **Miss Distance** (in meters), and **PoC** (Probability of Collision). Below the summary, the **Primary Object** and **Secondary Object** panels show the position vector, velocity vector, and position sigma in the RTN frame. ## Step 2: Constraints Configure the sweep parameters and thruster that control how candidate maneuvers are computed. ### Hard-Body Radii | Field | Description | Unit | | - | - | - | | **Primary HBR** | Hard body radius of the primary object | m | | **Secondary HBR** | Hard body radius of the secondary object | m | Hard-body radii are provided by the user. Information can sometimes be present as comments on the CDM file. ### Delta-V Range Define the range of velocity changes to sweep through. | Field | Description | Unit | | - | - | - | | **Min** | Minimum delta-V magnitude | m/s | | **Max** | Maximum delta-V magnitude | m/s | | **Step** | Increment between delta-V values | m/s | ### Angular Sweep Define the range of maneuver directions to sweep through. | Field | Description | Unit | | - | - | - | | **Start** | Starting sweep angle | deg | | **End** | Ending sweep angle | deg | | **Step** | Increment between angular values | deg | ### Thruster Selection Select which thruster to use for computing burn parameters. The thruster's specifications (thrust, ISP, max burn time, direction) are displayed for reference. ## Step 3: Time Filter Optionally restrict the maneuver execution time to specific windows between now and TCA. By default, no execution windows are defined and all maneuver times between now and TCA are considered. Click **Add Execution Window** to restrict the search to specific time ranges. Set the mode to **Inclusion** (maneuver epochs within defined windows) or **Exclusion** (maneuver epochs avoid defined windows). Each window defines a start and end time using date-time pickers bounded between now and TCA. Only maneuvers within these windows will be considered. You can add multiple windows, but they cannot overlap — overlapping windows are flagged with a validation error. This step is optional, you can proceed to the next step without adding any windows. ## Step 4: Direction Filter Optionally constrain maneuver directions using a directional cone in RTN (Radial-Tangential-Normal) space. Set the mode to **Inclusion** (only within the cone) or **Exclusion** (avoid the cone), then define the cone parameters. | Element | Description | | - | - | | **Mode** | None, Inclusion, or Exclusion | | **Axis R, T, N** | RTN components of the cone axis direction vector | | **Half-Angle** | Angular radius of the cone in degrees | | **3D Preview** | Interactive visualization of the directional cone | A reference-frame indicator badge appears next to the 3D Preview title showing `RTN` — the frame the cone axis components are expressed in. Hover the badge to see the full frame name and click **Learn more** to open the [reference frame catalog](/platform-overview/reference-frames) for the canonical definition. This step is optional, leave the mode set to **None** to skip direction filtering. **Running the computation:** Clicking **Next** at the end of Step 4 triggers the sweep-filter computation. The system evaluates all combinations of delta-V magnitudes and sweep angles, applies the configured time and direction filters, and advances to Step 5 with the results. ## Step 5: Options Review the sweep-filter results, select a candidate maneuver, and create the maneuver plan. The options shown correspond to the **Pareto frontier** of maneuver solutions. Only non-dominated candidates are displayed—each represents an optimal trade-off between Δv and collision risk (PoC). Solutions that are strictly worse (higher Δv and higher PoC) are filtered out. ### Scatter Plot The scatter plot displays all remaining candidates after filtering. The Y-axis always shows **Delta-V (m/s)**. Use the tabs above the chart to toggle the X-axis between **Miss Distance** (post-maneuver, linear scale) and **Collision Probability** (post-maneuver PoC, logarithmic scale). **Interactions:** * **Hover** a point to see a tooltip with candidate details (delta-V, miss distance, post-PoC) * **Click** a point to select it — the point turns green and grows larger ### Pipeline Statistics A summary line below the chart shows the filtering pipeline: > **N** total candidates → **X** Pareto filtered, **Y** time filtered, **Z** direction filtered → **M** remaining ### **Zero Remaining Candidates** If the pipeline returns zero remaining candidates, all feasible maneuvers were filtered out. This does not mean no maneuver exists, it means the current combination of constraints is too restrictive.\ To recover candidates, go back and try the following adjustments: * Widen the delta-V range in Step 2 * Edit execution windows in Step 3 * Increase the cone half-angle or remove the direction filter in Step 4. ### Selected Candidate Detail When a candidate is selected, the detail panel shows: | Field | Description | | - | - | | **Delta-V** | Velocity change magnitude in m/s | | **Maneuver Time** | Optimal time for the maneuver (UTC) | | **Direction RTN** | Normalized maneuver direction in RTN frame | | **Delta-V RTN** | Velocity change components \[R, T, N] in m/s | | **Miss Distance (pre)** | Miss distance before maneuver in meters | | **Miss Distance (post)** | Miss distance after maneuver in meters | | **PoC (pre)** | Probability of collision before maneuver | | **PoC (post)** | Probability of collision after maneuver | ### Plan Name and Description After selecting a candidate, fill in the plan details: | Element | Description | | - | - | | **Plan Name** | Required — minimum 3 characters, maximum 255 | | **Description** | Optional — maximum 2000 characters | ### Creating the Plan Click **Create Maneuver Plan** in the dialog footer to finalize. The system creates a maneuver plan linked to the conjunction event and the selected thruster. On success, the dialog closes and the new plan appears in the [Burn Plan](/features/burn-plan) page. ## Key Concepts For foundational concepts like delta-V, Probability of Collision (PoC), miss distance, and conjunctions, see [Core Concepts](/platform-overview/core-concepts). The following concepts are specific to CAM optimization: ### Sweep Angle The direction of the avoidance maneuver in the orbital plane, measured in degrees. The system sweeps through a range of angles to evaluate maneuver effectiveness in different directions. ### Pareto Filtering After computing all candidate maneuvers, the system applies Pareto filtering to identify the optimal frontier — candidates where no other option is better in both delta-V cost and collision risk reduction. This eliminates dominated solutions, leaving only the most efficient trade-offs. ## Related Pages * [Conjunction Classification](/features/conjunction-classification) — View and manage conjunction events and risk levels * [Conjunction Computation](/features/conjunction-computation) — Recompute conjunction assessments with your own state vectors * [Burn Plan](/features/burn-plan) — View and manage spacecraft maneuver plans # Conjunction Classification Source: https://docs.valar.space/features/conjunction-classification Monitor conjunction events and assess collision risk for your spacecraft > For the complete documentation index, see [llms.txt](/llms.txt). The Conjunction Classification page lets you monitor close approach events between your spacecraft and other space objects. View conjunction data, assess collision risk levels, and manage alerts from different originators. **Route:** `/conjunctions/current` or `/conjunctions/historical` ## Page Layout The page displays a details panel on the left and a scrollable conjunction list on the right. Two tabs at the top switch between views: * **Current** — Active conjunctions with upcoming TCA (Time of Closest Approach) * **Historical** — Past conjunction events for review Conjunction ## Filtering and Sorting ### Spacecraft Filter Use the spacecraft dropdown in the toolbar to show conjunctions for specific spacecraft only. Select one or more spacecraft, then click **Apply**. When no spacecraft are selected, all conjunctions are shown. ### Grouping Group conjunctions by: * **Spacecraft** — Groups by your primary spacecraft * **Criticality** — Groups by risk level (High, Medium, Low) * **None** — Flat list with no grouping ### Sorting Sort in **Ascending** (earliest TCA first) or **Descending** (latest TCA first) order. ## Conjunction List Each row in the list displays: * **Code** — Conjunction identifier * **Risk Shield** — Color-coded icon indicating criticality (red, yellow, or green) * **TCA** — Date and time of closest approach (hover for full UTC timestamp) * **Miss Distance** — Color-coded icon (hover for value in meters) * **PoC** — Color-coded icon (hover for Probability of Collision value) * **Spacecraft** — Colored satellite icon matching your spacecraft (hover for name) * **Last Updated** — Relative time since the conjunction was last updated (hover for full timestamp) Click any row to view its details in the left panel. ### Risk Levels Conjunctions are classified into three risk levels based on your configured thresholds (see [Settings](#settings)): | Level | Color | Meaning | | - | - | - | | **High** | Red | Immediate attention required | | **Medium** | Yellow | Monitor closely, may need action | | **Low** | Green | Within acceptable parameters | The classification workflow and risk thresholds apply equally to conjunctions from all providers (SpaceTrack and EU SST). Alerts from any source are processed and classified using the same criteria. ## Details Panel Selecting a conjunction opens its details on the left. The panel includes: ### Summary Key parameters at a glance: * **Criticality** — Risk level (High, Medium, Low) with color-coded shield * **Miss Distance** — Predicted closest approach in meters, with radial, along-track, and cross-track breakdown on hover * **PoC** — Probability of Collision in scientific notation * **TCA** — Time of Closest Approach with countdown timer ### Trend Analysis When multiple alerts exist for a conjunction, a chart shows how miss distance or PoC has evolved over time. Each data point is color-coded by its originator (e.g., CSpOC, ESA, Valar). ### Encounter Plane (B-Plane) For conjunctions with B-plane data, an interactive visualization shows the relative geometry at closest approach: * **Primary object** at the center with its covariance ellipse * **Secondary object** position relative to the primary * **Uncertainty boundaries** at 1σ, 2σ, and 3σ levels A reference-frame indicator badge appears next to the chart title showing `CCSDS encounter plane` — the frame the B-plane projection is computed in. Hover the badge for the full frame name; click **Learn more** to open the [reference frame catalog](/platform-overview/reference-frames). ### State Vectors Expandable sections display orbital state data for both objects, including position and velocity in Cartesian coordinates, position uncertainty in the RTN frame, and the reference frame used. ## Import Alerts Import alerts from CDM files: 1. Click **Import** in the toolbar 2. Select the target spacecraft 3. Drag and drop files or click to browse 4. Supported formats: `.cdm`, `.xml`, `.txt` ## Export Alerts Export a conjunction's alerts as CDM files: 1. Select a conjunction from the list 2. Click the **More** menu (**⋮**) in the details panel header 3. Select **Export Alerts** ## Delete Conjunction 1. Select the conjunction 2. Click the **More** menu (**⋮**) in the details panel header 3. Select **Delete** and confirm ## Settings Configure how conjunctions are classified via **Settings → Integrations → STM**. Conjunction Setting ### PoC Thresholds Set the Probability of Collision values that define each risk level: | Threshold | Description | Default | | - | - | - | | **High** | PoC at or above this value is classified as High | 1E-04 | | **Medium** | PoC at or above this value is classified as Medium | 1E-05 | Conjunctions below the Medium threshold are classified as Low risk. ### Miss Distance Thresholds Set the miss distance values that define each risk level. Lower distances indicate higher risk: | Threshold | Description | Default | | - | - | - | | **High** | Miss distances at or below this value are classified as High | 500 m | | **Medium** | Miss distances at or below this value are classified as Medium | 2000 m | Conjunctions above the Medium threshold are classified as Low risk. ### PoC Computation Method Select the algorithm used to calculate Probability of Collision: | Method | Description | | - | - | | **Alfano** | 2D integral method (default) | | **Foster** | Foster's approximation method | | **Patera** | Suited for elongated covariances | | **Chan** | Chan's analytical method | ### Editing Thresholds 1. Click the **Edit** icon next to a threshold section 2. Enter new values (scientific notation for PoC, meters for miss distance) 3. Click **Save** to apply This page also lets you configure credentials for external data providers (SpaceTrack, EU SST). See [Fetch Alerts — Provider Credentials](/features/fetch-alerts#provider-credentials) for details. Credentials are managed in **Settings → Integrations → STM**. Settings changes apply to all users in your organization. ## Related Pages * [Conjunction Computation](/features/conjunction-computation) — Compute conjunctions using your own state vectors * [Fetch Alerts](/features/fetch-alerts) — Download alerts from external space surveillance providers * [CDM Format](/file-formats/cdm) — Conjunction Data Message file format reference # Conjunction Computation Source: https://docs.valar.space/features/conjunction-computation Recompute conjunction assessments using your own state vectors > For the complete documentation index, see [llms.txt](/llms.txt). The platform can compute conjunction assessments using your spacecraft's internal state vectors instead of relying solely on externally provided data. ## Compute Conjunction Recompute the Probability of Collision (PoC) for an existing conjunction by combining your own spacecraft state vector with the secondary object data from the latest alert. The result is a new alert with "Valar" as the originator. ### Opening the Dialog From the [Conjunction Classification](/features/conjunction-classification) page, click the **Compute** button in the toolbar. Compute conjunction dialog with no active conjunctions for the selected spacecraft ### Configuration Start by selecting the **Spacecraft** and **Conjunction** to recompute. Only conjunctions with future TCAs are available. The dialog then shows two columns — one for the primary object and one for the secondary object. #### Primary Object (Left) 1. **State Vector** — Choose one of the spacecraft's state vectors from the last 30 days. The dialog shows the epoch and orbital elements for reference 2. **Hard Body Radius** — Set the spacecraft's collision radius in meters (0.1–1000 m) #### Secondary Object (Right) 1. **Alert** — Select which alert to use for the secondary object's state. The latest alert is selected by default 2. **Hard Body Radius** — Set the secondary object's collision radius in meters ### Running the Computation Click **Compute** once both sides are configured. The computation takes a few seconds. ### Results On success, a results card appears showing: * **ID** — Identifier for the newly created alert * **TCA** — Time of Closest Approach * **PoC** — Recomputed Probability of Collision * **Miss Distance** — Predicted closest distance in meters * **Relative Velocity** — Closing speed in m/s * **Mahalanobis Distance** — Statistical distance in sigma units * **Combined HBR** — Total hard body radius used * **Computation Method** — Algorithm used (configured in [Settings](/features/conjunction-classification#poc-computation-method)) The new alert is automatically saved and appears in the conjunction's trend analysis on the Classification page. ## Related Pages * [Conjunction Classification](/features/conjunction-classification) — View and manage conjunction events and risk levels * [Fetch Alerts](/features/fetch-alerts) — Download alerts from external space surveillance providers * [CDM Format](/file-formats/cdm) — Conjunction Data Message file format reference # Ephemeris Generation Source: https://docs.valar.space/features/ephemeris-generation Generate OEM files from state vectors for mission planning and data sharing > For the complete documentation index, see [llms.txt](/llms.txt). Generate OEM (Orbit Ephemeris Message) files from state vectors. OEM files contain predicted satellite positions over a specified time range, useful for mission planning, conjunction analysis, or sharing with external systems. **Access:** Click **Generate Ephemerides** on the State Vectors page top-right corner. ## Modal Overview The Generate Ephemerides modal guides you through four steps: Ephemerides Generation ## Step 1: State Vector Selection ### Select Spacecraft Choose a spacecraft from the dropdown. The list shows spacecraft names with colored satellite icons. ### Select State Vector After selecting a spacecraft, choose a state vector from the dropdown. Each option shows the state vector ID and epoch date/time. **Empty State:** If no state vectors are available for the selected spacecraft in the last 30 days, you can: * Click **Import State Vector** to open the import dialog * Click **Run Orbit Determination** to configure OD ### Include Covariance Data Toggle whether to include covariance matrix in the OEM file: | Option | Effect | | - | - | | **Yes** | Includes covariance matrix; enables covariance frame selection in Step 3 | | **No** | Excludes covariance data (default) | ## Step 2: Time Range Configuration ### Time Step Use the slider to set the interval between data points (1–60 minutes). * Smaller step = more data points, larger file * Larger step = fewer data points, smaller file ### Start Date & Time Select the start date from the 7-day calendar (use arrows to navigate weeks) and enter the start time in 24-hour UTC format (e.g., "08:30"). **Default:** 00:00 UTC ### End Date & Time Select the end date and enter the end time. **Default:** 23:59 UTC Dates are limited to ±30 days from the state vector epoch. Total duration cannot exceed 30 days. ## Step 3: Reference Frames ### Time System | Value | Description | | - | - | | **UTC** | Coordinated Universal Time (default) | | **TAI** | International Atomic Time | | **TT** | Terrestrial Time | | **TDB** | Barycentric Dynamical Time | | **TCG** | Geocentric Coordinate Time | | **TCB** | Barycentric Coordinate Time | | **GPS** | GPS Time | ### Ephemerides Reference Frame | Value | Description | | - | - | | **GCRF** | Geocentric Celestial Reference Frame (default) | | **EME2000** | Earth Mean Equator and Equinox of J2000 | | **ITRF** | International Terrestrial Reference Frame | | **TOD** | True of Date | | **MOD** | Mean of Date | | **TEME** | True Equator Mean Equinox | ### Covariance Reference Frame Only available when covariance is enabled in Step 1. | Value | Description | | - | - | | **RTN** | Radial-Tangential-Normal (default) | | **TNW** | Tangential-Normal-Out-of-plane | ## Step 4: Review & Generate Review your configuration before generating: **State Vector Card** * Spacecraft name * State Vector ID * Epoch date and time **Time Range Card** * Start and end date/time (UTC) * Time step in minutes * Calculated number of data points **Reference Frames Card** * Time system * Ephemerides frame * Covariance frame (if enabled) Click the **Edit** button (pencil icon) on any card to jump back to that step. ### Generate OEM Click **Generate OEM** to create and download the file. **Loading states:** 1. "Sending request to server..." 2. "Downloading file..." **On success:** * Toast notification: "OEM generated successfully" * File downloads automatically * Modal closes ## Navigation * **Step tabs**: Click any step name to jump directly to it * **Next**: Validates current step and proceeds * **Back**: Returns to previous step (hidden on Step 1) * **Cancel**: Closes modal without generating ## Error Handling | Error | Message | | - | - | | 422 (Validation) | Field-specific messages from server | | 400 (Bad Request) | "Please check your configuration" | | 404 (Not Found) | "The state vector may have been deleted" | | 500 (Server Error) | "An error occurred during OEM generation. Please try again." | ## Output **Format:** OEM (Orbit Ephemeris Message), CCSDS standard text format **Filename:** `oem_{stateVectorId}_{timestamp}.txt` ## Constraints | Constraint | Value | | - | - | | Date range from epoch | ±30 days | | Maximum duration | 30 days | | Minimum time step | 1 minute | | Maximum time step | 60 minutes | ## Related Pages * [State Vectors](/features/state-vectors): Manage orbit solutions and state vectors * [OEM Format](/file-formats/oem): OEM file format specification # Ephemeris Push Task Source: https://docs.valar.space/features/ephemeris-push-task Schedule automated ephemeris uploads to external space catalogs (Space-Track, EU-SST) > For the complete documentation index, see [llms.txt](/llms.txt). An **Ephemeris Push** task automatically generates a fresh orbit ephemeris (OEM) for each of your spacecraft and uploads it to one or more external space catalogs on a schedule — so you never have to export and upload ephemeris files by hand. **Route:** `/tasks` ## Overview Operators with a standing obligation to keep external catalogs supplied with current ephemeris — for example [Space-Track](https://www.space-track.org) or the EU Space Surveillance & Tracking (EU-SST) network — can configure one Ephemeris Push task and leave it running. On every scheduled run, Valar: 1. Generates a current CCSDS Orbit Ephemeris Message (OEM) for each configured spacecraft, and 2. Uploads it to each configured catalog. Each upload is tracked as an individual **delivery leg** (one per spacecraft-and-catalog pair), so you can see exactly what was delivered, what was skipped, and why. Use an Ephemeris Push task when you need external catalogs to stay current automatically, without manual exports or uploads. ## Prerequisites Before a spacecraft will be delivered on a run, it must meet a few conditions. Spacecraft that don't yet qualify are **skipped** (not failed) — the task keeps delivering for every other eligible spacecraft, and skipped spacecraft resume automatically once they qualify. * **A NORAD ID.** The spacecraft must have a NORAD catalog ID configured on its Spacecraft page. Without one it is skipped with `NO_NORAD_ID`. * **Current orbit data.** The spacecraft's orbit must be fresh enough to publish. Stale or degraded orbits are skipped (`ORBIT_STALE` / `ORBIT_DEGRADED`) until newer orbit data is available. Space-Track and EU-SST credentials are configured centrally by your administrator — you do not enter any catalog credentials when creating a task. ## Setting up a task Go to **Tasks** (`/tasks`) and select **Create Task**. In the task-type picker, select **Ephemeris Push**. Choose one or more spacecraft to push ephemeris for. A spacecraft with no NORAD ID shows a **No NORAD ID** warning — you can still include it, but it will be skipped on each run until a NORAD ID is assigned. Select one or more delivery targets: **Space-Track** and/or **EU-SST**. Enter a schedule interval using the shorthand grammar (`6h`, `12h`, `1d`, `1w`). The **minimum is 6 hours**; the **default is daily** (`1d`). An interval below 6 hours is rejected with the inline error *"Schedule interval must be at least 6 hours."* Review your spacecraft, catalogs, and cadence, then create the task. It begins running on the schedule you set. The task's overall run is reported as **succeeded** even when some spacecraft are skipped — a run only **fails** on a systemic fault (for example, a catalog is unreachable). Per-spacecraft skips never fail the run. ## Reading delivery-leg outcomes Open the delivery-legs view for any Ephemeris Push run to see one row per delivery leg. Legs are ordered by severity — failed first, then skipped, then delivered. Each leg carries a colour-coded **outcome badge**: | Code | Badge | Meaning | What to do | | - | - | - | - | | `SUCCEEDED` | Green | Ephemeris was uploaded to the catalog successfully. | Nothing — this delivery is complete. | | `NO_NORAD_ID` | Amber | The spacecraft has no NORAD ID, which Space-Track requires. | Add a NORAD ID on the spacecraft's Spacecraft page. Delivery resumes automatically. | | `ORBIT_STALE` | Amber | The orbit is too old to publish. | Refresh the orbit (run orbit determination or import a newer TLE) before the next run. | | `ORBIT_DEGRADED` | Amber | The orbit is in a degraded state. | Confirm the orbit is acceptable or refresh it before the next run. | | `HALTED` | Amber | Uploads to this catalog are currently halted by an administrator. | Contact support; deliveries resume when the halt is lifted. | | `OEM_GENERATION_FAILED` | Red | The ephemeris file could not be generated. | Check the spacecraft's orbit data quality; contact support if it persists. | | `UPLOAD_HTTP_ERROR` | Red | The catalog rejected the upload. | Contact support — this usually indicates a catalog-side or credential issue. | | `UPLOAD_IO_ERROR` | Red | A network error occurred during upload. | None — this is transient and is retried on the next scheduled run. | ## Scheduling notes * The **minimum** delivery cadence is **6 hours**; the **default** is **daily** (`1d`). * The task runs unattended on its schedule. A manual run is available from the task itself. * Skips are self-healing: a spacecraft skipped for a missing NORAD ID or a stale orbit resumes delivery on the first run after the underlying condition is resolved — no manual re-trigger needed. # Fetch Alerts Source: https://docs.valar.space/features/fetch-alerts Download alerts from external space surveillance providers > For the complete documentation index, see [llms.txt](/llms.txt). Fetch alerts from external space surveillance providers to keep your conjunction data up to date with the latest tracking information. Fetched alerts are automatically matched to existing conjunctions or used to create new ones. ## Opening the Dialog From the [Conjunction Classification](/features/conjunction-classification) page, click **Fetch** in the toolbar. Fetch Cdm ## Configuration 1. **Spacecraft** — Select which spacecraft to fetch alerts for 2. **Providers** — Select a source: | Provider | Requirement | Description | | - | - | - | | [SpaceTrack](https://www.space-track.org) | NORAD ID | US Space Command conjunction data | | [EU SST](https://www.eusst.eu) | COSPAR ID | European Space Surveillance & Tracking data | SpaceTrack is only available if the spacecraft has a NORAD ID configured. EU SST is only available if the spacecraft has a COSPAR ID configured. If the required identifier is missing, the provider appears disabled with a message explaining why. EU SST uses **COSPAR ID** for satellite identification, while SpaceTrack uses **NORAD ID**. Make sure your spacecraft has the correct identifier configured before fetching from each provider. ### Provider Credentials Each provider requires authentication credentials. Configure them in **Settings → Integrations → STM** before fetching for the first time. Once saved, credentials are used automatically. **SpaceTrack** requires: * **Username** — Your SpaceTrack account username * **Password** — Your SpaceTrack account password **EU SST** requires OAuth2 credentials: * **Client ID** — Your EU SST OAuth2 client identifier * **Client Secret** — Your EU SST OAuth2 client secret * **Username** — Your EU SST account username * **Password** — Your EU SST account password EU SST uses OAuth2 authentication (Client ID + Client Secret) in addition to username and password, unlike SpaceTrack which only requires username and password. You can obtain your OAuth2 credentials from the [EU SST portal](https://www.eusst.eu). You can update credentials at any time from the same settings page. When updating, leave the password or secret fields blank to keep the current values. ## Results After fetching, the dialog shows a summary: * **Alerts fetched** — Total alerts received from the provider * **New** — Alerts added to the system * **Already existed** — Alerts already in the system (skipped) * **Failed** — Alerts that could not be processed * **New conjunctions** — Conjunction events created from the fetched data * **Updated conjunctions** — Existing conjunctions updated with new alerts New conjunctions and alerts appear immediately on the Classification page. ## Related Pages * [Conjunction Classification](/features/conjunction-classification) — View and manage conjunction events and risk levels * [Conjunction Computation](/features/conjunction-computation) — Compute conjunctions using your own state vectors # Ground-Track Evidence Inspector Source: https://docs.valar.space/features/ground-track-evidence Inspect the fixed 15/1 ground-track reference, recorded evaluations, and canonical crossing/ground-track-error evidence for a modeled ground-track segment — read-only evidence, not campaign planning or command. > For the complete documentation index, see [llms.txt](/llms.txt). The Ground-Track Evidence Inspector is a read-only page for reviewing the fixed mission-level ground-track reference, the recorded evaluations run against it, and the canonical crossing and ground-track-error (GTE) evidence behind each evaluation. It exists to make that evidence understandable — including when it is refused, incomplete, or only good for diagnosis — without ever treating a modeled prediction as flown, observed truth. **Route:** `/orbits/ground-track/evidence?referenceId=&evaluationId=` This inspector is currently available only to **Valar Space team accounts** (email addresses on the `@valar.space` domain). It is not yet available more broadly to Operations users. If your account is outside that domain, the page renders nothing — see [Access](#access). ## Overview Everything on this page is recorded evidence, already computed and persisted elsewhere. The inspector never runs a calculation of its own, never edits the reference or an evaluation, and never authorizes, commands, or approves anything: * The **reference** is a fixed, immutable identity — the same `15/1` mission-level ground-track reference is reused, unchanged, by every routine replan against it. * An **evaluation** is one modeled trajectory segment checked against that reference. Every evaluation's evidence is explicitly labeled **predicted from a modeled trajectory segment** — it is not observed, post-burn verification. * A **crossing** is one point where the modeled ground track is checked against the reference, carrying either an authoritative signed ground-track-error (GTE) value or a typed reason why one could not be produced. ## Access The inspector is gated by a single Reflag flag, `ground-track-evidence-inspector`. Today that flag's audience rule restricts access to accounts on the `@valar.space` email domain — the Valar Space team, not the general Operations user base. There is no second flag, environment variable, or other setting that can unlock the page for anyone else. While your access is still being resolved, or once it resolves to denied, the page renders nothing at all — no partial layout, no placeholder, no flash of content. This is a deliberate default-deny: the inspector only ever shows evidence once access is confirmed. ## Reaching the inspector The inspector is not in the main navigation — you reach it through an exact link, not by browsing to it. Two URL parameters control what it shows: | Parameter | Required | What it selects | | - | - | - | | `referenceId` | Yes | The fixed ground-track reference whose evaluations you want to review. | | `evaluationId` | No | One specific recorded evaluation for that reference. | If `referenceId` is missing, the page shows only: > Open ground-track evidence from a campaign or an exact evaluation link. If `referenceId` is present but `evaluationId` is not, the page shows the reference identity and its evaluation history, and the evaluation-detail area shows the same message above — the inspector never guesses and silently opens the newest evaluation for you. Select an evaluation from the [history list](#recorded-evaluations) to see its detail, or follow a link that already includes both parameters. ## The fixed reference The reference header is the one piece of context that never changes, no matter which evaluation you have selected below it — the `15/1` reference is reused unchanged across every routine replan. It shows: | Field | What it shows | | - | - | | **Reference key** | The reference's identifying key, with a status badge — **Draft**, **Assured**, or **Revoked** — and its grid version (`15/1 grid `). | | **Revision** | The reference's revision number. | | **Reference digest** / **Grid digest** | Truncated SHA-256 identifiers for the reference and its grid; hover either to see the full value. | | **Created** | When the reference was created. | | **Assured** | When the reference was assured, or **Not yet assured**. | | **Reference interval** | The reference's validity interval. | If the reference itself cannot be read, the page shows one of the [error and access states](#loading-empty-and-error-states) below in place of this header. ## Recorded evaluations Below the reference header, a compact **Recorded evaluations** table lists every evaluation recorded against the current reference — for navigation and audit retrieval, never for starting a new evaluation. Each row shows the evaluation's modeled segment, when it was recorded, its outcome, its qualification, and a truncated digest; selecting a row's segment link opens that evaluation's detail below, setting `evaluationId` on the URL without leaving the page. If the reference has no recorded evaluations yet, this area shows: > No recorded evaluations for this reference. ## Evaluation detail and the predicted-vs-observed distinction Once an exact evaluation is selected, the detail area shows its outcome (**Recorded**, **Incomplete**, or **Refused**), its qualification/refusal disposition (below), and this persistent, unconditional label: > Predicted from modeled trajectory segment. Not observed post-burn verification. That label is shown for every evaluation regardless of its outcome or qualification — the inspector never lets a qualified or well-conditioned result read as flown truth. Alongside it, the detail area shows: | Field | What it shows | | - | - | | **Modeled segment** | The identifier of the modeled trajectory segment this evaluation checked. | | **Modeled interval** | The segment's start and end. | | **Recorded** | When the evaluation was recorded. | | **Qualification** | The evaluation's qualification state — **Qualified**, **Not qualified**, or **Indeterminate**. | | **Evaluation digest** / **Crossing-set digest** | Truncated SHA-256 identifiers for the evaluation and its full crossing set. | | **Source plan** / **Source replan** | The originating plan/replan identifiers, shown as truncated opaque values (or **Unavailable** when not recorded) — never a followable link, since the inspector does not expose a source system's own URLs. | ### Qualification and refusal states An evaluation's disposition is one of the following. These are the exact states the inspector distinguishes — none of them is a command, a permission, a compliance verdict, or a claim of flight truth; they describe only what the recorded evidence supports: | Disposition | What it means | | - | - | | **Qualified** | "This evaluation is qualified for its stated use." | | **Diagnosis-only** | "This evaluation is available for inspection but is not qualified for downstream use." | | **Expired** | The evaluation's qualification has expired. | | **Revoked** | The evaluation's qualification was revoked. | | **Invalid** | The evaluation's qualification is invalid. | | **Indeterminate** | Qualification could not be determined for this evaluation. | | **Refused** | The evaluation itself was refused; no qualification applies. | | **Incomplete** | The evaluation is incomplete; no qualification applies. | ## Canonical crossing evidence and ground-track error (GTE) For a **Recorded** evaluation, the inspector shows its canonical crossings — the audit source of record — as a chart and a table, both ordered by crossing ordinal. The chart is a bounded, already-paginated projection of the same crossings shown in the table; it never recalculates, fits, or interpolates a value the table does not already contain. Each crossing row shows its ordinal, its crossing epoch, a status, its signed GTE, its conditioning, and an expandable **Evidence** disclosure with the underlying candidate epoch, reference/modeled coordinates, phase and longitude diagnostics, and a raw-evidence digest. Phase and longitude values are always secondary diagnostics — they are never substituted for the GTE. The **signed GTE** — the ground-track error, in meters, positive on the left of the modeled direction of motion — is the authoritative metric, and it is shown only when the crossing's status is **Present**. For every other status, the cell instead shows: > No authoritative GTE for this crossing. alongside the typed reason for that status: | Status | Reason shown | | - | - | | **Present** | (the signed GTE value itself, e.g. `+12.500 m`) | | **No root** | "No root was found in this crossing's slot interval." | | **Ambiguous** | "More than one candidate root was found; the crossing cannot be uniquely identified." | | **Ill-conditioned** | "The crossing geometry is too ill-conditioned to trust a root." | | **Invalid context** | "The reference or evaluation context for this crossing is invalid." | | **Indeterminate** | "This crossing could not be evaluated." | The inspector never shows zero, a fit, a phase value, or a longitude value in place of a missing GTE — a non-**Present** status always shows the reason above instead of a scalar. If an evaluation has no canonical crossings recorded at all, this area shows: > No canonical crossing was recorded for this evaluation segment. ## Loading, empty, and error states Every region of the page — the reference header, the evaluation history, the evaluation detail, and the crossing evidence — resolves independently to one of these states: | State | What you see | | - | - | | **Loading** | A loading indicator reading "Loading recorded ground-track evidence…", with skeleton placeholders. | | **No exact target** | "Open ground-track evidence from a campaign or an exact evaluation link." — shown when `referenceId` or `evaluationId` is missing. | | **Empty** | "No recorded evaluations for this reference." (evaluation history) or "No canonical crossing was recorded for this evaluation segment." (crossings) — the reference/evaluation itself was found, it simply has nothing recorded yet. | | **Unavailable** | "This ground-track evidence isn't available." — shown when the reference or evaluation you asked for cannot be resolved for your account. | | **Read failure** | "Couldn't load recorded ground-track evidence. Try again." with a retry action — shown on an unexpected read failure. | If you change which evaluation is selected while a request for the previous one is still in flight, the inspector discards that stale response — it never lets an older evaluation's crossings appear under a newer selection. ## What this page does not do The inspector is read-only, end to end. Every action on the page is inspection, selecting a row, following provenance (a digest or source identifier shown for reference), or reading exported evidence — never any of the following: * No editing or reseeding the reference or an evaluation * No campaign, grid, or reference authoring * No submitting, planning, or scheduling a new evaluation * No maneuver planning, approval, or command * No declaring or recording compliance Qualification and diagnosis-only labels describe what the recorded evidence supports for downstream use — they are not a permission, an approval, or a flight-truth verdict, and nothing on this page can grant one. ## Evidence and certification status The evidence this page shows is backed by an additive numerical verification and release-certificate process that runs in CI against the platform's own persisted reference, evaluation, and crossing artifacts. That process establishes bounded numerical feasibility for the evidence you see — it is CI/evidence tooling, not a flight-readiness or command system, and it does not itself grant final release, campaign compliance, or observed post-burn verification. Where that certification remains non-final, the inspector's own qualification and refusal states (above) are the accurate, current description of what a given evaluation supports — this page never states a final qualification or release beyond what those recorded states already say. ## Related Pages * [Ground Track Visualization](/features/3d-ground-track): The interactive 2D/3D ground-track map this evidence's modeled reference relates to. * [Keplerian Elements](/features/orbit-elements-plots): Orbital-element time-series for the same spacecraft. * [State Vectors](/features/state-vectors): The precise orbital data a modeled trajectory segment is ultimately derived from. * [Orbit Determination](/features/orbit-determination): How VALAR produces the precise orbit data behind a modeled trajectory. # Exporting Maneuvers Source: https://docs.valar.space/features/maneuver-export Export stored maneuver records as CCSDS OCM files by identity or time range. > For the complete documentation index, see [llms.txt](/llms.txt). Export maneuver records from the **Maneuvers** page at `/maneuvers/burn-plan` for use in external tools. Exports contain the current stored burn data in CCSDS OCM format. ## Export one maneuver Select a record to open its details, then click **Export**. Consistent-frame records download as OCM; historical mixed-frame records use the preservation archive described below. The corresponding API operation is `GET /operations/maneuvers/export?spacecraftIds=...&maneuverIds=...`. Use the stable maneuver identity and its owning VALAR spacecraft ID. ## Export selected records Select records with the list checkboxes and use **Export as OCM** in the bulk actions toolbar. A consistent-frame maneuver downloads as OCM text; multiple selected maneuvers for one spacecraft download as a ZIP. Selections spanning spacecraft are exported separately per spacecraft. For one spacecraft, use `GET /operations/maneuvers/export?spacecraftIds=...&maneuverIds=BURN-001&maneuverIds=BURN-002`, with 1–100 unique maneuver IDs and no request body. Repeat `maneuverIds` for each identity; commas within a value are literal. URL-encode names and split large selections into smaller requests if necessary to stay within URI size limits. Omit time bounds when selecting IDs. ## Export by date range 1. Click **Export** in the maneuver list's toolbar. 2. Select the spacecraft and time range. 3. Download the OCM export. For automation, use `GET /operations/maneuvers/export` with `spacecraftIds`, `startDate`, and `endDate`. The API uses the exact ISO-8601 bounds supplied. For consistent-frame records, one spacecraft produces OCM text; multiple spacecraft produce a ZIP of OCM files. See the [API examples](/api-reference/maneuvers#import-and-export-ocm-files). ### Historical mixed-frame records A record whose segments use genuinely different frames produces a **preservation ZIP**, including when selecting a single identity or a single-spacecraft date range. The download uses `.zip` for an `application/zip` response; ordinary OCM responses use `.ocm`. A multi-record ZIP can contain nested preservation ZIPs alongside ordinary OCM files. Each preservation archive contains a manifest of the original record, metadata, segment frame spellings and part ranges, plus ordered frame-labelled OCM parts. The original identity appears once in each part. No stored identity, segment or thrust vector is rewritten to create the archive. **The preservation ZIP is not an import request**; VALAR rejects it on import. Use it to retain the original information, and use an explicit edit with consistent frames when correcting the live record. Ordinary whole-record OCM correction remains a separate workflow. ## File identity and metadata OCM `MAN_ID` is the stable maneuver identity, including after a name edit. Exports omit optional `MAN_BASIS` metadata. Records with conflicts are exportable, but an export is not a way to update them: importing an already stored identity is rejected. Use [Edit](/features/burn-plan#edit-a-record) to change an existing record. For supported fields and units, see [OCM](/file-formats/ocm). Creating an export does not command the spacecraft; follow your own downstream submission and uplink procedures. ## Missing required inputs Export requires the actual burn intervals and the physical quantities needed by the selected output. * Supply authoritative phase boundaries or actual burn duration. When elapsed time is derived from firing time, supply the duty ratio as well. * Correct reversed, nonpositive, or out-of-range sample intervals and regenerate the plan when its saved timing cannot be reconstructed. A terminal boundary sample does not create an extra burn; valid subsecond intervals remain subsecond. * Where delta-V or fuel is derived, provide the required mass, thrust, Isp, and consumption data. Missing values do not become zero delta-V or fuel. Use the error's named field to repair the source maneuver or recompute a supported plan, then retry export. These are VALAR calculation/export requirements, not universal requirements of every CCSDS file schema. # Importing Maneuvers Source: https://docs.valar.space/features/maneuver-import Add stored maneuver records from CCSDS OCM files and resolve import conflicts. > For the complete documentation index, see [llms.txt](/llms.txt). Use **Import** on the **Maneuvers** page at `/maneuvers/burn-plan` to add records produced by external tools. To create or edit a record manually, see [Managing Maneuvers](/features/burn-plan). ## Import OCM files 1. Open **Maneuvers** and click **Import**. 2. Choose the target spacecraft when needed. Otherwise, VALAR resolves it from file metadata. 3. Upload one or more CCSDS OCM files (`.ocm` or `.txt`). 4. Review any validation or spacecraft-resolution messages, then import. 5. Check each file's result. Successfully imported records appear in the maneuver list; adjust the spacecraft and time filters to find them. Import adds records without changing other records. Each file is atomic: if any record in a file fails, that file adds nothing. Other successful files remain saved. Retry only failed files after correcting their errors. ## File requirements * OCM KVN format (CCSDS 502.0-B-3), maximum **52 MB** per file and per complete multipart request. * At least one maneuver block with an identity and valid burn segments. * Nonzero thrust vector (`THR_X`, `THR_Y`, `THR_Z`), `THR_ISP` between **50 and 10,000 seconds**, and a physical properties block containing `WET_MASS`. * Valid epochs, positive segment durations, and supported reference frames. * Maneuver IDs without reserved characters (`! * ' ( ) ; : @ & = + $ , / ? # [ ]`). * Spacecraft metadata consistent with the target spacecraft. * No overlapping enclosing maneuver intervals within the file or with stored records on the same spacecraft. Adjacent intervals may touch at an endpoint. `MAN_BASIS` is optional format metadata. It is not a required classification and does not change import behavior. See [OCM import requirements](/file-formats/ocm#valar-import-requirements) for field, unit, reference-frame, and metadata details. ## Resolve duplicate identities and overlaps A file whose `MAN_ID` already exists for that spacecraft is rejected. In the application, open the record and select **Edit** to change it manually. Renaming a stored record changes its label, not its stable identity or exported `MAN_ID`. For an API correction, prepare corrected OCM, explicitly delete the stored record, then import the corrected file. See [Correct a stored maneuver](/api-reference/maneuvers#correct-a-stored-maneuver). These are separate operations: import does not overwrite a record, and a failed import does not undo the deletion. All import validation still applies. If an imported record overlaps an existing one, use the reported identities to inspect the conflict. Decide which record to edit or delete before retrying. VALAR does not remove or shorten existing records to make room. Conflicts can involve records outside the current list window. ## Automate imports Use `POST /operations/maneuvers/import`, repeating the multipart `files` part for multiple files. Supply the VALAR `spacecraftId` when the target needs to be explicit. See the [Maneuver API guide](/api-reference/maneuvers#import-and-export-ocm-files) for authentication, request examples, preview binding, and 200/207/error handling. ## Troubleshooting | Problem | How to resolve it | | - | - | | Empty, unsupported, or oversized file | Upload nonempty OCM KVN content within the 52 MB file and total request limits. | | Missing thrust, ISP, wet mass, or invalid duration | Supply the required physical fields and units. | | Unsupported reference frame | Use a [supported reference frame](/file-formats/ocm#supported-reference-frames). | | Ambiguous spacecraft | Select the intended spacecraft and retry that file. | | Spacecraft metadata mismatch | Correct file identifiers to agree with the intended spacecraft. | | Duplicate identity or stored-record overlap (`MANEUVER_CONFLICT`) | Read the conflicting records; edit or delete explicitly before retrying. | | Overlapping maneuver blocks within a file | Correct their time ranges; enclosing record intervals may touch but must not intersect. | | Stale preview (`IMPORT_STALE_PREVIEW`) | Inspect the updated file again, then retry with the new preview. | | Some files failed | Review every file result and retry only failures. | # Operations Map Source: https://docs.valar.space/features/map Explore spacecraft, ground stations, and areas of interest in one geographic workspace Open **Map** (`/map`) in the Operations sidebar to relate spacecraft trajectories, ground station sites, and areas of interest without changing workspaces. Map is in an internal rollout. It appears for enabled `@valar.space` accounts in Operations. Accounts outside the rollout retain Ground Track, Coverage Map, and AOI Map; direct `/map` access explains that Map is not enabled. ## Fleet and spacecraft focus Use the **Spacecraft** filter, select spacecraft, then **Apply**. **Clear** followed by **Apply** returns to the fleet. Selecting a spacecraft in the Map browser or on the map updates this same filter. * No selection shows the available fleet, including archived spacecraft. The filter lists active, selectable spacecraft, so its count can differ from the fleet count. * One selection enters **Spacecraft focus**, where you can inspect that spacecraft's computed passes. * Multiple selections show a filtered fleet. Station footprints require exactly one spacecraft. The browser reports how many objects match its filters. Spacecraft colours match their positions, paths, and charts. Open **Legend** for the spacecraft colour key and an explanation of the layers. ## Layers Open **Layers** to choose what the map displays. Layer visibility is independent of whether the browser is open. | Layer | Meaning | | - | - | | **Spacecraft positions** | Subsatellite points in 2D and spacecraft positions at physical altitude in 3D. | | **Ground tracks** | Optional trajectories. In 2D, dashed lines show the past and brighter lines emphasise the near future. | | **Ground station sites** | Station locations, available even without orbit or opportunity data. | | **AOI boundaries** | Saved areas of interest in their assigned colours. | | **Selected pass footprint** | The selected pass's approximate footprint, available only in spacecraft focus. | Positions, station sites, and AOI boundaries are enabled by default; ground tracks are optional. The footprint layer is enabled but draws nothing until you select one spacecraft and a pass with usable geometry. Saved preferences or a shared URL can change these defaults. The theme-aware monochrome basemap follows light/dark mode. There is no Monochrome / Colored control. The basemap provides geographic context; operational objects retain their colours. ## Map browser The floating **Map browser** has **Spacecraft**, **Stations**, and **AOIs** tabs, with counts, search, and compact scrollable lists. Stations and AOIs have status filters; AOIs also have a tag filter. In spacecraft focus, **With opportunities only** limits sites or AOIs to those with stored opportunities in the selected window. Leave it unchecked to discover objects without opportunities. Select a row to locate the object and open its details. **Back to list** preserves search and filters. **Clear filters** recovers from an empty filtered list; **Manage stations** and **New AOI** provide relevant next steps. **Hide browser** frees map space; **Show browser** restores it without changing layers. Station and spacecraft details list **Computed pass windows**. Select one spacecraft and a selectable pass to seek to its time and load its footprint. The browser shows loading, unavailable, or stale geometry and the representative altitude when a footprint is available. **Clear pass** removes the pass selection. The footprint is an approximation at a representative spacecraft altitude for that pass. It does not change with playback altitude. Fleet views never draw station footprints, and missing geometry has no fixed-altitude fallback. Contact windows come from computed pass results; crossing a displayed polygon does not establish contact. Opportunity warnings distinguish stale, incomplete, unavailable, and failed reads. **Retry** rereads stored results and reports the outcome; it does not launch a new computation. It is disabled while requests are running. Use **Open Passes timeline** to review station results. A dash does not prove that there are no opportunities. ## Views, navigation, and time **2D / 3D** preserve spacecraft selection and time context. **ECEF** is Earth-fixed; **ECI** is available in 3D. In ECI, a **GCRF** badge identifies the particular Earth-centered inertial frame used by the trajectory. Hover the badge for its explanation. Geographic station, AOI, and footprint overlays remain attached to Earth. **Reset view** releases tracking and recentres the camera while staying on Map and retaining spacecraft selection. The workspace **Home** breadcrumb navigates away; it is a separate action. **Charts** opens the trajectory charts. Use the time-range preset and past/future controls to choose the loaded interval. Playback supports forward/reverse, pause, seeking, reset to start, real-time sync, and speed selection. Paths show up to one hour behind and 24 hours ahead of the playhead, bounded by available orbit data. While a new window loads, the time display explains that it is waiting for trajectory data. Missing trajectory time is not a computed timestamp. See [Ground Track playback and coordinates](/features/3d-ground-track#timeline) for the shared timeline controls and data limits. Orbit-age warnings remain in the application footer. Their counts combine the Operations fleet and page-specific review and update with refreshed orbit data and selection. **View affected spacecraft** opens the drawer; **Escape** closes it. Escape also dismisses Layers and Legend. ## Create or import an AOI Choose **New AOI** to open the dedicated 2D creation workflow. Playback pauses while editing. Draw an area, enter coordinates, or import GeoJSON or KML/KMZ using the existing AOI tools. Finishing returns to Map and selects the created AOI; cancelling returns without creating one. Saved AOIs remain viewable in both 2D and 3D. **Details & edit** opens an AOI's management view. See [AOI creation and management](/features/areas-of-interest/map) for the supported shapes and import workflow. ## Share and restore a view Copy the browser URL to share the selection and controls. Layers, browser visibility, view, frame, and speed are also remembered locally. Explicit URL values take precedence over saved preferences. | Parameter | Value | | - | - | | `spacecraft` | Comma-separated spacecraft IDs; omitted means fleet. | | `layers` | Comma-separated `spacecraft`, `tracks`, `stations`, `aois`, `footprint`; an empty value hides all. | | `browse` | `spacecraft`, `station`, or `aoi`. | | `browser` | `hidden` collapses the browser. | | `object` | `spacecraft:`, `station:`, or `aoi:`. | | `pass` | A computed pass ID for the selected spacecraft and window. | | `epoch` | ISO UTC epoch to seek to, within the loaded trajectories. | | `mode` / `frame` | `2D` or `3D`; `ECEF` or `ECI` (3D only). | | `range` | `day`, `week`, or `month`; default `week`. | | `past` / `future` | Non-negative amounts within the preset limits; hours for `day`, days otherwise. | | `speed` | A supported playback multiplier, such as `300`. | | `new` | `method` opens AOI creation. | For accounts in the rollout, `/orbits/ground-track`, `/passes/coverage-map`, and `/aoi/map` open Map with their relevant context. Existing AOI selection and creation links remain supported. Pass tables, timelines, management screens, and focused inspectors remain available. # Viewing Measurements Source: https://docs.valar.space/features/measurements-data Visualize, filter, and manage measurement data > For the complete documentation index, see [llms.txt](/llms.txt). The Measurements page provides visualization and management tools for your measurement data. View measurements in interactive charts, filter by various criteria, and manage outlier status. **Route:** `/orbits/measurements/data` ## Page Layout The page uses a split-view design with a plot panel on the left and a table panel on the right: Measurements Data When measurements are selected, a floating action bar appears at the bottom: Measurements toolbar with spacecraft, time range, measurement type, sensor, and import controls ## Filtering ### Spacecraft Filter Filter measurements by spacecraft. Click to open a multi-select dropdown, check/uncheck spacecraft, and click **Apply** to confirm. ### Time Range Filter | Option | Label | Description | | - | - | - | | **day** | Today | From today at 00:00:00 UTC to now | | **week** | Last Week | Last 7 days from midnight | | **month** | Last Month | Last 30 days from midnight | The time filter offers preset ranges. **View imported measurements** can also open the exact UTC time span of an import; choose a preset to leave that span. ### Measurement Type Selector | Type | Description | Chart Display | | - | - | - | | **RANGE** | Distance measurements | Single chart: Range (m) | | **RADEC** | Sky coordinates | Two charts: RA (deg) + DEC (deg) | | **AZEL** | Pointing angles | Two charts: Azimuth (deg) + Elevation (deg) | | **PV** | Position & velocity | Six charts: X, Y, Z (m) + Vx, Vy, Vz (m/s) | | **DOPPLER** | Range-rate observations | Single chart: Range-rate (m/s) | All five measurement types appear as tabs with counts for the selected spacecraft and time range, including rejected measurements. Counts are independent of the sensor, file, and outlier filters. When opening the page, a type specified in the link takes priority. Otherwise, the page restores your last-used type if it has data, or selects a type that does. Manual selections stay selected even when empty. An empty type offers a **View \[type] measurements** action when another type has data; this action clears additional filters. After an import, **View imported measurements** opens the spacecraft, measurement type, and UTC time span of the stored data. This also reveals imports outside the current date range. ### Advanced Filters Click **More Filters** to expand additional filtering options. #### Outlier Status Tabs | Tab | Shows | Icon | | - | - | - | | **Accepted** | Only non-outlier (normal) measurements | Green checkmark | | **Rejected** | Only outlier measurements | Red X | | **All** | All measurements regardless of status | None | #### Sensors Filter Click **Sensors** to open a popover with all available sensors. Click sensors to toggle selection, then click **Apply** to filter. #### Files Filter Click **Files** to open a popover with all source files. Click files to toggle selection, then click **Apply** to filter. ## Grouping Click **Group By** to change how measurements are organized: | Option | Table Behavior | Chart Behavior | | - | - | - | | **Sensor** | Groups by sensor ID with collapsible headers | Colors points by sensor, shows legend | | **Spacecraft** | Groups by spacecraft name | Colors points by spacecraft | | **File** | Groups by source file name | Colors points by file | | **None** | Flat list (no grouping) | Single color, no legend | ### Group Header Actions When grouping is enabled, each group header provides: * **Chevron**: Click to expand/collapse the group * **Select All**: Select all measurements in the group (appears on hover) * **Clear**: Deselect all in group (appears when any are selected) ## Sorting Click the **↓ Epoch** / **↑ Epoch** button to toggle sort order: | State | Description | | - | - | | ↓ Epoch | Newest first (descending) | | ↑ Epoch | Oldest first (ascending) | ## Plot Panel ### Statistics Card Above the charts, a statistics card displays: * **Total**: Count of all measurements * **Accepted**: Count with green checkmark and percentage * **Rejected**: Count with red X and percentage ### Interacting with Data Points **Hover** over any scatter point to see a tooltip with: * Timestamp * Value * Sensor * Status (Accepted/Rejected) **Click** a data point to select it: * Point becomes highlighted * Tooltip stays visible with action buttons * Corresponding table row highlights and scrolls into view ### Accept/Reject from Plot Use the **Select points** icon button in the top-right corner of the chart to enable selection. Hover over or focus the button for instructions. Click observations or drag boxes around clusters. Boxes add to the selection; click a selected point again or hold **Alt** while dragging to remove points. Selection is shared between charts and table, and all components of the same measurement are selected together. Choose **Reject selected** or **Restore selected** to update the selected measurements in one batch. Both panes refresh after the update. Selection clears when you change the spacecraft, time span, measurement type or filters. Bulk chart actions become available after the full measurement dataset has loaded. Changes affect shared measurements used by future OD runs; saved orbit solutions are unchanged. Turn **Select points** off to inspect individual points. When a point is selected, the tooltip shows an action button: | Current Status | Button Shown | Action | | - | - | - | | Accepted | **Reject** | Marks as outlier | | Rejected | **Accept** | Removes outlier flag | ## Table Panel ### Row Information Each measurement row displays: | Element | Description | | - | - | | Checkbox | Click to select for bulk actions (appears on hover) | | Status Icon | ✓ green (accepted) or ✗ red (rejected) | | Values | Formatted by type (e.g., "RA 12.3456° DEC -45.6789°") | | Epoch | Timestamp in "Jan 15, 14:32:01" format | | More Menu | **⋮** button for additional actions (appears on hover) | ### Row Actions **Click a row** (not the checkbox) to focus it: * Row highlights with a colored ring * Corresponding point on chart highlights **Click the checkbox** to select for bulk actions: * Row enters selection state * Floating bulk actions bar appears ### Row Context Menu Click the **⋮** button on any row to access: | Action | Description | | - | - | | **Accept / Reject** | Toggle outlier status for this measurement | | **Accept File** | Mark ALL measurements in this file as accepted | | **Reject File** | Mark ALL measurements in this file as rejected | | **Delete File** | Delete ALL measurements from this file | ## Bulk Actions When one or more rows are selected, a floating toolbar appears at the bottom. ### Selection Count Shows the number of selected measurements out of total visible. ### Select All Selects all visible measurements (after filters are applied). ### Reject / Accept Actions | Option | Description | | - | - | | **Reject** | Mark selected measurements as outliers | | **Accept File** | Mark ALL measurements in selected files as accepted | | **Reject File** | Mark ALL measurements in selected files as rejected | ### Delete File Opens a confirmation dialog to delete ALL measurements from the selected file(s). **Delete File** removes all measurements from the source file(s), not just the selected rows. This action cannot be undone. ### Clear Deselects all currently selected rows. ## Cross-Component Synchronization The plot and table panels stay synchronized: | Action | Effect | | - | - | | Click point in plot | Row highlights and auto-scrolls into view | | Click row in table | Point highlights on chart | | Click away | Highlights clear in both panels | ## Color Coding ### Status Colors | Status | Color | Icon | | - | - | - | | Accepted | Green | ✓ | | Rejected/Outlier | Red | ✗ | ### Series Colors When grouping is enabled: * **Sensor grouping**: Each sensor gets a unique color * **Spacecraft grouping**: Uses spacecraft context colors * **File grouping**: Each file gets a unique color * **No grouping**: Single default color The legend displays below the chart, or as color dots in the filter buttons when **More Filters** is visible. ## Loading States While data is loading, the page displays skeleton placeholders: * **Table**: 8 skeleton rows with placeholder shapes matching the actual row layout * **Plot**: Loading indicator while chart data is prepared ## Chart Limitations The scatter plot is view-only with the following characteristics: | Feature | Supported | | - | - | | **Zoom** | No | | **Pan** | No | | **Hover tooltips** | Yes | | **Click to select** | Yes | | **Data sampling** | No (all points rendered) | Large datasets render all data points without sampling. For very large measurement sets, this may affect chart performance. ## Unresolved spacecraft references When you request measurements through the VALAR API and name spacecraft by reference — for example by NORAD id, COSPAR id, name, or [external key](/features/spacecraft-management#external-key) — the response includes an `unresolvedSpacecraftReferences` field alongside the results. This field is **always present**. When every reference you supplied resolved, it is an empty array. When one or more references could not be resolved, it lists them — and the results you received cover only the references that *did* resolve. A `200` response does not imply a complete result set. If you request data for five spacecraft and one reference is a typo, you receive measurements for the other four, and the fifth is named in `unresolvedSpacecraftReferences`. Always check this field rather than assuming the results cover every spacecraft you asked for. The list follows three rules: * **Duplicates are collapsed** — a reference you supplied more than once appears at most once. * **Your order is preserved** — the references appear in the order you supplied them. * **There is no positional correspondence** between this list and the `content` array — an entry's position here does not line up with any row in the results. For how a single-spacecraft operation reports the same unresolvable reference — a 404 rather than a 200 — see [Spacecraft Lookup](/features/spacecraft-lookup#when-a-reference-cannot-be-resolved). ## Related Pages * [Import measurements](/features/measurements-import): Upload TDM, OEM, and SP3 files * [Manage sensors](/features/tracking-sensors): Configure ground stations for tracking # Importing Measurements Source: https://docs.valar.space/features/measurements-import Upload measurements and ephemeris data > For the complete documentation index, see [llms.txt](/llms.txt). Import measurement and ephemeris files into VALAR using the Import dialog. Supported formats include TDM, OEM, and SP3. **Route:** `/orbits/measurements/data` ## Import Dialog On the measurements page, click the **Import** button in the top-right corner of the toolbar: Import Measurements The import dialog has three sections: ### 1. Configuration **Spacecraft Selection** * Select which spacecraft the measurements belong to * If you had a spacecraft selected on the page, it will be pre-selected **Format Selection** | Format | Description | File Extensions | | - | - | - | | **TDM** | CCSDS Tracking Data Message | `.tdm`, `.txt` | | **OEM** | CCSDS Orbit Ephemeris Messages | `.oem`, `.txt` | | **SP3** | Precise Ephemeris | `.sp3`, `.txt` | TDM and OEM use CCSDS standards; SP3 uses the IGS format. A standards-compliant file may still lack inputs required by VALAR's OD measurement importer. See the [TDM](/file-formats/tdm), [OEM](/file-formats/oem), and [SP3](/file-formats/sp3) pages for the importer-specific requirements. **Doppler (range-rate) observables** are a supported TDM measurement type. TDM blocks containing `DOPPLER_INSTANTANEOUS` rows require configured uncertainty and declared producer correction/convention information, as well as supported bands and integration intervals. See [Doppler (Range-Rate) Measurements](/file-formats/tdm#doppler-range-rate-measurements) for requirements and error remedies. ### 2. File Upload A drag-and-drop zone where you can: * Drag and drop files directly onto the zone * Click to browse and select files from your file system * Upload multiple files at once The file picker automatically filters by the selected format's extensions. **Upload Behavior:** * All selected files are uploaded in a single batch request * Files are processed concurrently on the server * Each file receives individual success/failure status * No explicit file size limit is enforced by the frontend ### 3. File Queue After adding files, they appear in a list showing: * File name * Status icon (idle, uploading, success, or error) * Progress bar during upload * Remove button to remove files before upload ## Validation ### Frontend Validation Before upload, the system checks: * **File extension**: Must match the selected format * **Queue not empty**: At least one file must be selected * **Upload state**: Cannot upload while another upload is in progress ### Backend Validation When you click **Import**, files are validated on the server: * **Format validation**: CCSDS TDM/OEM or IGS SP3 syntax, as applicable * **Data structure validation**: Required fields and proper data types * **Timestamp validation**: Valid ISO-8601 date formats * **Spacecraft association**: Data must be associable with a valid spacecraft ## Upload Outcomes ### Missing Required Inputs VALAR preserves valid supplied uncertainty. The baseline compatibility policies are below; workspaces with [configurable PVT uncertainty](#configurable-pvt-uncertainty) use spacecraft defaults or import overrides for missing OEM/SP3 uncertainty. | Input | What to supply before retrying | | - | - | | TDM angle/range uncertainty | Missing or wrong-length catalog arrays temporarily use the legacy assumptions: 2062 arc-seconds per component for RADEC/AZEL, or 1 m for RANGE. This includes existing sensors with null sigmas and the UI's legacy RANGE `[1,1]` array. Valid dimension-matched configured arrays are preserved; zero, negative or nonfinite components in a dimension-matched array still produce `TRK-4005`. Backend fallback use reports a `sigmas` warning in the import result and job summary. See [sensor uncertainty compatibility](/features/tracking-sensors#measurement-uncertainty-compatibility). | | TDM Doppler uncertainty | Supply one positive finite catalog sigma in m/s in the normalized observable convention. Missing, invalid or wrong-length Doppler uncertainty produces `TRK-4005`; no band default is supplied. | | OEM uncertainty | Missing covariance uses assumed one-sigma uncertainty of 100 m position and 0.1 m/s velocity per source-frame axis. The preview discloses the assumption and the import/job summary reports a `sigmas` substitution warning. Supplied covariance takes precedence at its matching epoch and must have valid supported axes and variances. | | SP3 velocity or uncertainty | Supply genuine paired P/V records and positive finite accuracy for every position/velocity component. P-only data are not measurements of zero velocity. See [SP3 import requirements](/file-formats/sp3#valar-measurement-import-requirements). | | Doppler processing information | Confirm the producer's SUM/MEAN convention for two-way data and declare the actual correction state. Do not choose a convention from the observation's magnitude or relabel uncorrected data as corrected. | Correct the named sensor or source-file input and retry the failed file. A catalog lookup outage requires restoring catalog access, not entering a replacement sigma. Initial TDM inspection checks syntax, identity, and epochs; uncertainty is checked during conversion before persistence, so inspection alone does not certify OD readiness. Without configurable PVT uncertainty, missing SP3 uncertainty rejects the file. Missing required Doppler uncertainty, invalid dimension-matched TDM sigma values, or invalid supplied OEM covariance rejects that file without persisting its observations. Missing angle/range uncertainty and missing OEM covariance use the compatibility assumptions described above. Other successful files in the batch remain successful. Doppler block-level rejections can instead preserve valid sibling blocks; review the per-file error details. Supplied zeros remain valid where physically meaningful, but a zero sigma is not a usable OD weight. Historical imported values are not automatically reclassified as missing merely because they equal a former default. Successful import with assumed uncertainty does not establish measured accuracy or qualify an OD solution. ### Configurable PVT uncertainty In your Operations workspace, open **Spacecraft → PVT measurement uncertainty**. Use the pencil icon at the top right to edit the shared defaults, then Save or Cancel in the same header. Every spacecraft starts with **100 m position / 0.1 m/s velocity**, expressed as positive, finite one-sigma values per source-frame axis. The same settings apply to supported PVT measurement imports, including **OEM and SP3**. The import dialog offers **Use spacecraft defaults** or **Override for this import** when uncertainty is missing. Supplied OEM covariance and individual SP3 component accuracies take precedence; only missing uncertainty uses the chosen values. Invalid supplied uncertainty still rejects the file. Review each file's values and affected observation counts. If shared defaults change before submission, use **Refresh defaults**. Import results retain the selected values and their source. Existing measurements and skipped duplicates keep their original uncertainty. Editing shared defaults requires spacecraft-write access; overrides require measurement-upload access. PVT uncertainty is available to authorized Operations users. Outside Operations, OEM retains its 100 m / 0.1 m/s compatibility assumption and SP3 still requires complete supplied component accuracy. The PV importer requires measured position and velocity; this setting does not make position-only SP3 or EP/EV records supported. ### Reading an import result Each file has its own result. A completed measurement import is not queued: its stored count is newly inserted measurements from this attempt; duplicates skipped were already present. A file with a warning was still processed. If counts or coverage are unavailable, the dialog says so instead of estimating from the filename. Coverage is based on persisted measurement epochs when available; it may include earlier imports of a file with the same name, and it is not the file's declared header range. Zero newly stored rows do not establish new coverage. Check the measurements table before retrying an unknown outcome. A missing-uncertainty warning names the affected `sigmas` field. For OEM, the result lists assumed 1σ position and velocity values and affected observations; for supported configurable PVT imports it also names the spacecraft and whether spacecraft defaults or import overrides were used. There is no post-import **Verify** control. Review the result before using these measurements in OD. If the source uncertainty should differ, correct the file before importing new observations. Editing settings or retrying does not change skipped duplicates or previously stored uncertainty. ### Mixed and failed batches The dialog stays open when a file has a warning or fails. Each file retains its own result, so a successful sibling is not retried. Fix the named input before retrying a failed file. If the request timed out or the response omitted a file receipt, its outcome is unknown; inspect stored observations before another attempt. A retry will not revise measurements that already exist. Share the visible reference and error code with support if the problem persists. Process and notification status should be read alongside the per-file receipt: warning substitutions remain warnings even when the job completed successfully. # Mission Analysis flight plans Source: https://docs.valar.space/features/mission-analysis-flight-plans Compose maintenance, inclination changes and Phasing, then review whole-plan propellant and achieved states. Mission Analysis evaluates an ordered flight plan using a frozen spacecraft configuration. Open **Trajectories**, choose a plan or create one, and work through **Assets → Initial orbit → Flight plan**. ## Add the maneuver requirements ### SMA maintenance Select **Add SMA maintenance** and provide: * Nominal **mean** semi-major axis and its maintained plus/minus tolerance, in km. * Maintenance duration in days, measured from the preceding phase's actual end. * A chemical or electric thruster belonging to the selected Mission Analysis spacecraft. * Phase propellant cap, propellant reserve, and maximum available duty fraction. * Sunlight-only eligibility and any UTC thrust blackouts that apply. The band must hold throughout the maintained interval. The search can use coast, refill or powered/coast behavior and can choose an endpoint anywhere permitted by the band. It does not force a return to nominal SMA. ### Inclination change Select **Add Inclination change** and enter the target mean inclination and plus/minus tolerance in degrees, maximum elapsed duration, propulsion and resource limits. This is a pure plane-change objective: it does not deliberately change altitude to make the maneuver cheaper. Natural orbital perturbations still act. These study models initially cover near-circular LEO. The result identifies the method and its applicability. If a requirement, resource limit or numerical check cannot be satisfied, the result explains the unsuccessful computation instead of treating the unfinished plan as a cheaper solution. ### Phasing Select **Add Phasing** to save a signed phase change or reference-offset objective, its fixed reference, completion window, terminal-orbit/drift requirements and actual device limits. Phasing uses finite propagation and preserves the achieved physical phase, epoch and remaining mass for following phases. Reopening restores the saved objective; changing an upstream phase does not silently move its reference. For a later signed-change phase entry, supply the continuous entry-history evidence when required. Slot offsets do not require a historical lap count. See [Phasing](/features/planner/phasing) for reference semantics, authoring and result review. ## Repair timing after an edit When reordering affects named completion events or waits, review the preview and choose **Apply to draft**. Removing an activity also lists the waits and activities that reference its completion. Dates and wait durations stay as authored. **Timing references need repair** lists missing or later events. Choose **Repair** to open that activity's timing fields, then select the configured initial state or an earlier activity under **After completion of**. You can instead explicitly remove the dependent activity. Saving is blocked while a reference is unresolved. After repair, **Save** or **Save & run** shows the original and chosen timing for review. **Keep editing** returns to your draft. A failed save retains your choices and explains the failure so you can retry or edit. Saved results continue to show the inputs from their original run. ## Propellant across the whole plan The objective is **total propellant consumed by the complete ordered flight plan**. An earlier phase may spend more when that saves greater consumption in a later phase using different propulsion. Every later phase inherits the achieved orbit, actual UTC epoch and remaining mass. Coast durations, phase order, selected thrusters, authored bands and explicit targets remain requirements. Reorder phases in the editor when you intend to change the mission; Disposal remains the final phase. **Save** stores the configuration. **Save & run** queues its evaluation. Editing is locked while the run is queued or running. Reopening restores the authored requirements, not the optimizer's selected policies. **Process Monitor** follows the actual evaluation: queued work has not started, and a running evaluation remains active until it reaches a terminal outcome. Successful dispatch to the worker is not a completed trajectory. If execution evidence is unavailable, the monitor says so rather than showing a success check. When recovery reports a lost or timed-out run as failed, review the reason before using **Save & run** to submit a new evaluation. ## Read the result **Whole-plan propellant search** shows the verified plan cost, a phase-local reference under the same mission requirements, savings, evaluation counts and the reason the search ended. Its phase table makes extra early spending and downstream savings visible. A verified feasible result is the best solution found by the recorded search—not proof of a global optimum. Open a phase to review its achieved mean orbit, maintained range, consumption, remaining propellant, required reserve, timing, method and assumptions. The requested configuration shown alongside evidence belongs to the run that produced it, even if the saved plan is subsequently edited. **Mission budget** aggregates recorded phase costs and remaining mass. Partial budgets identify unfinished phases; missing historical evidence is unavailable, not zero. Equivalent firing time is the full-thrust time corresponding to modeled propellant expenditure. It excludes waiting and coasts and is not the elapsed phase duration. Chemical impulses and averaged electric corrections are analysis models, not executable Operations burn schedules. # Mission workspaces Source: https://docs.valar.space/features/mission-workspaces Keep Mission Analysis and Operations work separate within one organization. Named workspace management is released by organization/account eligibility. If it is not available to you, your existing MA and OPS working contexts remain available with their original data and access. ## Select a workspace Use the existing workspace selector in the application header. Named workspaces show their **name and type**: Mission Analysis or Operations. You only see workspaces you are authorized to open. Switching opens that workspace's retained mission data and results; it does not move previously started calculations. Your choice is remembered separately for each organization and type. On the first entry into a type, its default workspace is targeted. A workspace link can carry `?workspace=` to select a specific workspace. If a remembered or linked workspace is unavailable, the application shows that access outcome and lets you choose another authorized workspace explicitly. It does not silently substitute a different workspace. ## Manage workspaces Organization administrators with access to this capability use **Settings → Organization → Workspaces** to create, rename, archive, restore and manage members. * Create a named workspace of an enabled type. It starts empty with no members; assign organization members explicitly afterward. * Rename without changing the workspace ID, mission data, membership or integration targets. `default` is an initial name, not a reserved name. * Archive only after running jobs finish and enabled operational schedules are disabled. Connected or leased operational integrations also identify work that must be resolved through their existing controls. The rejection identifies blockers. * Open archived contents read-only under your existing permissions. * Restore retained contents and membership. Disabled schedules and disconnected integrations are not enabled automatically. Each organization/type has a permanent default identity. Renaming or archiving that workspace does not appoint a replacement default. ## Target the customer API An existing integration that omits a workspace continues to target the permanent default for its MA/OPS type. A browser's selection does not change that target. To select another authorized workspace, supply the UUID in `X-Workspace-Id`: ```http theme={null} GET /operations/spacecraft HTTP/1.1 Authorization: Bearer X-Workspace-Id: ``` The header does not grant access. A wrong type, another organization, invalid ID or inaccessible workspace is rejected. API keys retain their own environment grant and need an explicit workspace grant for additional workspaces. The TypeScript SDK retains its existing method parameters. Supply the selector through the existing request options instead of adding a positional argument: ```typescript theme={null} await spacecraftApi.getSpacecraft({ id: spacecraftId }, { headers: { 'X-Workspace-Id': workspaceId }, }); ``` If a default is archived, authorized implicit reads still read its retained contents and writes are rejected. If default access is revoked, requests are denied. Neither condition redirects the integration to another workspace. ### Workspace administration endpoints These operations remain organization-admin authorized and release controlled: | Operation | Endpoint | | - | - | | List your authorized workspaces | `GET /workspaces/me` | | List the organization's workspace administration catalog | `GET /workspaces` | | Create an empty workspace | `POST /workspaces` with `environment` and `name` | | Rename | `PATCH /workspaces/{id}` with `name` | | Archive or restore | `PATCH /workspaces/{id}/lifecycle` with `archived: true` or `false` | | Read or replace membership | `GET` or `PUT /workspaces/{id}/members`; both use an object with `userIds` | | Grant or revoke an API key | `PUT /workspaces/{id}/api-keys` with `apiKeyId` and `grant` | Archive blockers return HTTP `409` in the standard error envelope; optional `details.blockers` identifies the running jobs or enabled schedules to resolve. Revoking a grant does not change the implicit default binding. Separate station sharing, copying, permanent deletion and type conversion are not supported by this workspace lifecycle. # Orbit age Source: https://docs.valar.space/features/orbit-age Learn what a spacecraft's orbit age is and how its two graded levels — the degraded level (lower-accuracy public-TLE fallback) and the stale level (a stale-orbit warning) — govern every orbit-dependent product and surface in one orbit-data-age footer. > For the complete documentation index, see [llms.txt](/llms.txt). Orbit age is how long it has been since a spacecraft's orbit was last updated. VALAR governs it with one workspace-wide policy that has **two graded levels**: the **degraded level**, where a spacecraft falls back to a lower-accuracy public-catalog orbit and the platform signals it, and the **stale level**, where the orbit is too old to trust and VALAR warns you on the products that depend on it. Both levels are measured from the same point — each spacecraft's latest [state vector](/features/state-vectors) — and you set them together in one place. Both levels surface in **one** signal: the [orbit-data-age footer](#the-orbit-data-age-footer) that sits at the bottom of every page, tagging each affected spacecraft as **Degraded** or **Blocked**. **Route:** **Settings → Orbits → Orbit age** (the orbit-data-age footer appears across every page of the operations workspace). ## Orbit age A spacecraft's **orbit age** is the time elapsed since its latest [state vector](/features/state-vectors) — the position and velocity at an epoch you provide through orbit determination, an OPM import, or manual entry. It is **now minus that latest state-vector epoch**, expressed in **whole days** (all times UTC). Orbit age is a single, workspace-wide measure: the same definition applies to every spacecraft in the operations workspace, so an "old" orbit means one consistent thing across your fleet. As a spacecraft's orbit ages, it crosses two thresholds in turn — first the **degraded level**, then the **stale level** — and each one changes how VALAR treats that spacecraft: | Level | Crossed when the orbit age exceeds… | What VALAR does | Default | | - | - | - | - | | **[Degraded level](#degraded-level)** | the degraded level you set | Falls back to a lower-accuracy public TLE and tags the spacecraft **Degraded** in the orbit-data-age footer | On | | **[Stale level](#stale-level)** | the stale level you set | Gates the orbit-dependent products behind a stale-orbit warning, explains why, and tags the spacecraft **Blocked** in the orbit-data-age footer | `14 days`, on | The two levels are ordered: the **degraded level must be at or below the stale level**, so a spacecraft falls back to a public orbit *before* it is ever flagged stale. You configure both — together with the block switch — in the **Orbit age** settings [below](#configuring-orbit-age). ## Degraded level The **degraded level** is the orbit age at which a spacecraft stops using its own now-old precise orbit and **falls back to a public TLE** — a [Two-Line Element set](/file-formats/tle) the platform fetches itself from the public catalog, located by the spacecraft's NORAD catalog ID. The spacecraft keeps planning and plotting, but on a lower-accuracy orbit, and the [orbit-data-age footer](#the-orbit-data-age-footer) names it with a **Degraded** tag, alongside any spacecraft tagged **Blocked** at the stale level. You never upload or paste a TLE; the platform retrieves it for you. The degraded level is **on by default** — a spacecraft that loses a fresh precise orbit automatically falls back to a public TLE, unless your workspace has deliberately turned degraded mode off (in which case such a spacecraft is governed only by the stale level). A spacecraft enters the degraded level automatically when either condition applies: | Condition | When a spacecraft enters the degraded level | | - | - | | **No state vector** | The spacecraft has no state vector at all. Always active while degraded mode is on. | | **Orbit age past the degraded level** | The spacecraft's orbit age is older than the **Degraded level** you set, in days (minimum `1 day`). | This is the lower-impact of the two levels: it keeps a product working, with a clear signal, rather than gating it behind a stale-orbit warning. What falls back to the public TLE — and which spacecraft the fallback cannot rescue — is detailed under [How each product behaves](#how-each-product-behaves). ### What "Lower Accuracy" Means A public TLE is a general-catalog orbit located by NORAD catalog ID, and it is less precise than an operator-provided state vector — so every result a spacecraft produces while it is at the degraded level is an approximation rather than a precise prediction. The platform never hides this: the [orbit-data-age footer](#the-orbit-data-age-footer) names every spacecraft currently running on a public TLE with a **Degraded** tag, and both the footer and the settings page describe that orbit as **lower accuracy**. Treat results for a degraded spacecraft as indicative, and restore a precise [state vector](/features/state-vectors) when you need full accuracy. ## Stale level The **stale level** is the orbit age at which VALAR considers a spacecraft's orbit too old to trust and **warns you** on the products that depend on it. The verdict is judged per spacecraft: a stale spacecraft is flagged while every fresher spacecraft in the same view still computes normally. The stale level has a default of `14 days`. Enforcement is controlled by the **Block orbit-dependent products on stale orbits** switch in the **Orbit age** settings, **on by default**. When it is on, a spacecraft whose orbit age is past the stale level has its orbit-dependent products gated or warned as described below; turning it off lets every product compute from an old orbit without the warning — the stale level still defines "stale", it is just no longer enforced. ### The Stale-Orbit Warning When a spacecraft's orbit is stale but still usable, VALAR does not refuse the product — it warns you, and lets you proceed. How the warning appears depends on the product: * On the **interactive** products — the **ground-station passes** timeline, the [Keplerian-elements plot](/features/orbit-elements-plots), and the [ground-track map](/features/3d-ground-track) — the result is held behind a **stale-orbit panel** with a **Compute anyway** button. The chart, timeline, or map is withheld until you press **Compute anyway**, which computes and renders the result on the stale orbit. Proceeding is a conscious choice, not a silent default. * On a **background recompute** — [AOI overflight](/features/areas-of-interest/overflight-events) — the events still compute, and the same stale-orbit panel appears **inline, above the result** as a warning rather than a gate. Triggering the recompute is itself the conscious act, so no separate button is needed. * On a **file export** — the [attitude AEM export](#attitude-profiles-&-export-on-the-fallback) and the [schedule export](/features/burn-plan#schedule-export-dialog) — there is no panel: the file downloads with an in-file `COMMENT` line noting the orbit's reduced confidence, so a reader of the file outside VALAR is not misled about its precision. Requesting the export is itself the conscious act. * The one exception is the **state-vector [OEM](/file-formats/oem) export**: VALAR refuses outright rather than warning, because an orbit-data export must never embed a stale orbit. Provide fresher tracking data to continue — this export never proceeds on acknowledgment. * A **degraded** (not stale) orbit on an interactive product is warned the same inline way, not gated — you keep the result, with the warning shown above it. The stale-orbit panel explains why the orbit is stale and what to do next: | Line | What it reads | | - | - | | **Reason** | **This spacecraft's orbit is stale** | | **Age** | `last determined N days ago` | | **Threshold** | `exceeds your N-day threshold` | | **Next action** | A situation-specific line — see the table below | | **Consequence** | `The risk of an inaccurate result is growing with the N-day age.` | | **Remedy** | **Update tracking data, or change the threshold in Settings** | Both `N` values are whole days — the spacecraft's actual orbit age and your configured stale level. The **Next action** line reflects which orbits the platform holds for the spacecraft: | Situation | Next-action line | | - | - | | **Precise orbit stale, public-TLE fallback fresh** | `Update tracking data to refresh the precise orbit, or proceed on the fresher public-TLE fallback.` | | **No precise orbit, public-TLE fallback fresh** | `Add a precise orbit determination, or proceed on the public-TLE fallback.` | | **Precise orbit and public-TLE fallback both stale** | `Both the precise orbit and the public-TLE fallback are stale — update tracking data before proceeding.` | | **Any other stale orbit** | `This orbit is stale — review the orbit data before proceeding.` | The remedy names the two ways to clear the warning: provide fresher tracking data (a new [state vector](/features/state-vectors)) for the spacecraft, or raise the stale level in Settings. When the orbit in use came from the public-TLE fallback rather than your own tracking data, the panel adds the line **the public-TLE fallback is also stale**, so you know that refreshing your own data is what clears it. ### When There Is No Usable Orbit Warning-and-proceeding only applies when there is an orbit to proceed on. When a spacecraft has **no usable orbit at all**, the product cannot be computed no matter what you acknowledge — so in place of a stale-orbit warning, the result is replaced by a **can't-compute panel**: | Situation | What the panel reads | | - | - | | **No usable orbit data** | **Can't compute — `{spacecraft}` has no usable orbit**, then `There is no usable orbit data for this spacecraft, so this product can't be computed. Add tracking data to continue.` | | **Numerically-invalid or decayed orbit** | **Can't compute — `{spacecraft}` has no usable orbit**, then `This orbit can't be computed — its state is no longer numerically valid.` | The panel names the spacecraft — or reads **This spacecraft** when it has no name — and carries an **Add orbit data** action that opens the [spacecraft page](/features/spacecraft-management) so you can supply an orbit. Because there is nothing to compute, **Compute anyway** is not offered here: acknowledging staleness never unlocks a spacecraft that has no usable orbit. A numerically-invalid or decayed orbit gets the same panel with its own message, so a physically impossible orbit is always explained plainly rather than surfacing a raw error. This verdict is consistent everywhere the spacecraft appears: the same classification that drives the panel tags the spacecraft **Blocked** in the [orbit-data-age footer](#the-orbit-data-age-footer) and **Stale** on its [cheatsheet](#orbit-age-on-the-cheatsheet), and it governs [maneuver planning](/features/planner#when-a-spacecraft-has-no-usable-orbit) too — creating a plan for a spacecraft with no usable orbit returns the same can't-compute response immediately, rather than accepting the request and producing nothing. ## The Orbit-Data-Age Footer Both levels of the orbit-age policy — the [degraded level](#degraded-level) and the [stale level](#stale-level) — surface in **one** signal: the orbit-data-age footer. Whenever any spacecraft in the workspace is affected at either level, a persistent footer sits at the bottom of every page of the operations workspace, spanning the full width beneath the sidebar and content. When **no** spacecraft is affected, no footer is shown. A spacecraft with **no state vector at all** — in a workspace where degraded mode is off, so it has no public-TLE fallback to stand in — now appears in this footer too, tagged **Blocked**, the same treatment as a stale orbit. It has no usable orbit of any kind; previously such a spacecraft was absent from the footer. ### The Collapsed Strip By default the footer is a single collapsed strip reading **Orbit data age — N spacecraft affected**, where `N` is the count of affected spacecraft. For a single spacecraft it reads **1 spacecraft affected**. The strip carries a **blocked-severity cue**: when one or more affected spacecraft are at the **Blocked** (stale) level, the strip switches to a higher-severity amber palette and shows an **N blocked** count, so "some are blocked" reads at a visibly higher severity than "all merely degraded". When every affected spacecraft is only **Degraded**, the strip uses the softer degraded-yellow palette and shows no blocked count. Orbit data age footer identifying spacecraft affected by the freshness policy ### The Drawer Select **View affected spacecraft** to open the **Orbit age warnings** drawer, described as **Spacecraft affected by orbit data age — degraded or blocked** — a grid showing **one card per affected spacecraft**. Each card carries: | Card element | What it shows | | - | - | | **Identity** | The spacecraft **name**, or its **NORAD ID** when it has no name — never a raw internal identifier. | | **Level tag** | A **Degraded** or **Blocked** tag, marking which level that spacecraft has crossed. | | **State vector** age | The age of the spacecraft's latest state vector in whole days, **colour-coded** — highlighted once it crosses the degraded threshold, and again once it crosses the stale threshold. | | **Public TLE** age | The age of the fetched public TLE in whole days, **colour-coded** — highlighted once it crosses the stale threshold. | A spacecraft that qualifies at **both** levels appears **once, at its most severe level — Blocked**; blocked spacecraft are ordered ahead of degraded ones, so a single spacecraft never reads as both "degraded" and "blocked". When an age is unavailable, the card shows **—** in place of the number, with a tooltip explaining why: | Readout | Tooltip | When it appears | | - | - | - | | **—** (state vector) | **No state vector available.** | The spacecraft has no state vector. | | **—** (public TLE) | **No public TLE available for the registered NORAD.** | No usable public TLE could be fetched for the spacecraft's NORAD ID. | The footer is the **workspace-wide** orbit-data-age signal. A complementary **per-spacecraft** status also appears on each spacecraft's [cheatsheet](#orbit-age-on-the-cheatsheet), described next; there is still no orbit-age status on the spacecraft page or in the spacecraft selector. ## Orbit Age on the Cheatsheet Every spacecraft's **cheatsheet** surfaces that spacecraft's own live orbit-age status, so the orbit-age signal sits right beside its orbit data, not only in the workspace-wide footer. The cheatsheet applies the same orbit-age policy as the footer — the [degraded level](#degraded-level) and the [stale level](#stale-level) — to the single spacecraft you are viewing, read fresh each time you open it, and pairs that status with both of the orbits the platform holds for the spacecraft. It is the per-spacecraft view of the same signal the [orbit-data-age footer](#the-orbit-data-age-footer) carries across the workspace. Orbit-age details explaining the degraded public-TLE fallback ### The Header Status Chip A colour-coded **status chip** sits in the cheatsheet **header**, beside the spacecraft selector at the top of the panel, showing the spacecraft's live orbit-age status: | Status | What it means | How the [footer](#the-orbit-data-age-footer) tags the same spacecraft | | - | - | - | | **Nominal** | A fresh precise orbit — the spacecraft's latest [state vector](/features/state-vectors) — is in use. | Not listed (the spacecraft is unaffected) | | **Degraded** | The spacecraft has fallen back to the lower-accuracy public [TLE](/file-formats/tle) at the [degraded level](#degraded-level). | **Degraded** | | **Stale** | The orbit is past the [stale level](#stale-level) and too old to trust — or the spacecraft has no usable orbit of any kind. | **Blocked** | Click or tap the **Orbit age** button to read the reason for the status. You can also focus the button with `Tab` and activate it with `Enter` or `Space`. Press `Esc` to close the details while keeping the cheatsheet open. If the status cannot be retrieved, the header shows **Status unavailable**; that is distinct from a **Stale** orbit. ### Own and Public TLE Tabs The cheatsheet's **Two-line element (TLE)** section shows the available orbital references on two tabs: | Tab | What it shows | | - | - | | **Own computed** | The TLE derived from the spacecraft's own precise orbit — its latest [state vector](/features/state-vectors). | | **Public** | The public-catalog TLE the platform fetched for the spacecraft, located by its NORAD catalog ID. | Each tab shows its source's two TLE lines, age, and epoch in UTC. The in-use indicator identifies the orbit source used by the spacecraft's products; browsing another tab does not change it. The in-use source is selected by default, or **Own computed** when no source is known. Once you choose a tab, it stays selected until you switch tabs or spacecraft. Click **Copy** to copy exactly the two lines in the displayed tab. **Copied** confirms success; **Retry copy** and an explanation appear if the clipboard is unavailable. On narrow screens, scroll the TLE horizontally to read its unwrapped lines. When a source has no TLE, its tab reads **No own TLE available** or **No public TLE available**. When neither source is available, the section shows **No TLE available**. Loading and retrieval failures are shown within the affected section so you can continue reading the other spacecraft data. ## Proactive orbit-age alerts The [orbit-data-age footer](#the-orbit-data-age-footer) and each spacecraft's [cheatsheet](#orbit-age-on-the-cheatsheet) show orbit-age status *when you look at them*. VALAR also **notifies you the moment a spacecraft's status changes**, so an orbit that ages into **Degraded** or **Stale** — or recovers — reaches you even when you are working on something else. The notification arrives in your **in-app notification inbox**; it is the proactive companion to the footer, which remains the live snapshot you pull up. ### What raises a notification A notification is raised whenever a spacecraft's orbit-age status changes from one level to another, in **either direction**: | Change | Examples | What you see | | - | - | - | | **Worsening** | **Nominal → Degraded**, **Degraded → Stale**, **Nominal → Stale** | A cautionary notification for a move to **Degraded**, and a higher-prominence one for a move to **Stale** | | **Recovery** | **Stale → Nominal**, **Degraded → Nominal**, **Stale → Degraded** | A positive notification confirming the orbit recovered | Each notification names the **spacecraft** and the **reason** its status changed — the same plain-language reason the footer and cheatsheet show — so you can triage it without leaving the inbox. The notification is **informational**: it is a signal, not a link, so there is no click-through — you act in your own time through the products and the footer. Delivery is **in-app only** — there is no email or Slack notification, and no new page. ### What does not raise a notification VALAR notifies you on a **change**, never on a standing condition, so your inbox is not flooded: * A spacecraft that **stays** at the same status raises **no** repeat notification — you are told once, when it changes, not again while it remains there. * The **first time** VALAR records a spacecraft's status — a newly onboarded spacecraft, for instance — it notes that starting status **silently** and notifies you only when the status later changes. * An **identical** change repeated on the **same day (UTC)** — a spacecraft that goes **Nominal → Stale**, recovers, then goes **Nominal → Stale** again the same day — raises one notification for that change that day. A *different* change, or the same change on a *later* day, always raises a new notification. A status change for a spacecraft in your workspace only ever notifies your own workspace. ## How each product behaves Orbit age governs every orbit-dependent product together, though not every product responds to the **stale level** the same way. At the **degraded level**, the products that support the public-TLE fallback keep working on the fetched orbit. At the **stale level**, most orbit-dependent products show the [stale-orbit warning](#the-stale-orbit-warning) above — a conscious-proceed gate on the interactive products and an inline warning on a background recompute — while a spacecraft with [no usable orbit](#when-there-is-no-usable-orbit) gets the can't-compute panel instead. A few products are exceptions: orbital events and attitude aren't gated by this policy at all, and conjunction/collision-avoidance maneuvers refuse outright rather than offering a warning. The table below states exactly how each product responds. A gated or warned spacecraft is named in the one [orbit-data-age footer](#the-orbit-data-age-footer) — tagged **Degraded** at the degraded level, **Blocked** at the stale level — so a single signal covers both. The warning governs the *result* of an affected product; the footer is the *workspace-wide* signal that lists every affected spacecraft. | Product | At the degraded level | At the stale level | | - | - | - | | **Ground-station passes** | Computes visibility windows from the public TLE | Held behind the stale-orbit panel; **Compute anyway** renders that spacecraft's passes | | **[Keplerian-elements plot](/features/orbit-elements-plots)** | Plots the orbital-element time-series from the public TLE | Held behind the stale-orbit panel; **Compute anyway** renders the element charts | | **[Ground-track map](/features/3d-ground-track)** | Draws the ground track and globe position from the public TLE | Held behind the stale-orbit panel; **Compute anyway** renders the map | | **[AOI overflight](/features/areas-of-interest/overflight-events)** | Computes overflight events from the public TLE | Events still compute, with the stale-orbit warning shown inline above them; fresher spacecraft in the same recompute are unaffected | | **[Orbital events](/features/burn-plan)** | Computes eclipse, apsis, node, and SAA crossings from the public TLE | Computes regardless — not gated by the stale-orbit policy; a separate propagation-window limit unrelated to orbit age governs how far the computation can run from the orbit's epoch | | **[Attitude profiles & export](/features/attitude/overview)** | Computes the pointing profile and quaternion charts from the public TLE | Computes regardless — not gated by the stale-orbit policy; the exported AEM file's `COMMENT` line notes the reduced confidence, exactly as it does on the public-TLE fallback | | **[Maneuver optimization](/features/planner)** | Initialize a plan from a chosen public TLE in the planner | **Create Plan** asks you to acknowledge before planning on a stale orbit — **Create anyway** proceeds | | **[Conjunction / collision-avoidance maneuvers](/features/cam-optimization)** | Optimizes candidate maneuvers from the public TLE | Refuses to create the maneuver plan — provide fresher tracking data to continue | Ground-station pass prediction (`/passes/timeline`) has no settings of its own — it follows this one workspace orbit-age policy, at both levels. Maneuver optimization's stale-orbit acknowledgment and its can't-compute response are documented in full on the [Planner](/features/planner#when-the-orbit-is-stale) page. The subsections below detail how each product behaves on the degraded-level public-TLE fallback. ### Ground-Station Passes on the Fallback Ground-station pass prediction is the first planning function that runs on the fallback. While a spacecraft is at the degraded level, the **Passes** timeline computes its visibility windows from the **public TLE** the platform fetched for it, instead of skipping the spacecraft as it would without a fresh precise orbit. The fallback passes render exactly like passes computed from a precise **state vector** — the same timeline bars, and the same hover details (spacecraft, ground station, AOS, LOS, and duration). No individual pass is marked as degraded. Pass prediction follows the workspace degraded level in both directions: a spacecraft whose orbit age is past the degraded level computes its passes on the public TLE, while a spacecraft within the degraded level computes on its precise state vector and is not sent to the fallback. Passes computed from the fallback book exactly like precise-orbit passes — a booked fallback pass appears in your booked-passes list and its details panel, indistinguishable from any other pass. With degraded mode enabled, the skipped-spacecraft notice lists only the spacecraft the fallback could not rescue: | Situation | Skip Reason | | - | - | | **No public TLE found** | "Couldn't retrieve a public TLE for NORAD — degraded mode unavailable for this spacecraft." | | **No state vector and no NORAD ID** | The spacecraft has no usable orbit — add orbit data on the [spacecraft page](/features/spacecraft-management); see [When There Is No Usable Orbit](#when-there-is-no-usable-orbit). | Degraded operation on the timeline is signalled solely by the unified [orbit-data-age footer](#the-orbit-data-age-footer) above, which tags the spacecraft **Degraded**; an individual fallback pass carries no separate marker. While degraded mode is **off**, nothing falls back to a public TLE: a spacecraft with no state vector is skipped with the usual "no state vector available" reason, and one whose orbit age is past the [stale level](#stale-level) shows the stale-orbit warning in place of its passes — and the footer tags that spacecraft **Blocked**. ### AOI Overflight on the Fallback Area-of-interest overflight planning also runs on the fallback. While a spacecraft is at the degraded level, VALAR computes its overflight events from the **public TLE** the platform fetched for it, instead of skipping the spacecraft as it would without a fresh precise orbit. A spacecraft located by a NORAD catalog ID alone — with no operator **state vector** — becomes overflight-plannable for its configured payloads. Fallback-computed overflight events render exactly like events computed from a precise state vector — the same per-payload rows, the same entry, exit, and peak times, and the same off-boresight and blinding detail — with no per-event marker that the orbit was a public TLE. An overflight recompute follows the workspace degraded level in both directions: a spacecraft whose orbit age is past the degraded level computes its overflights on the public TLE, while a spacecraft within the degraded level computes on its precise state vector and is not sent to the fallback. The fallback can't rescue a degraded spacecraft in two cases — when no public TLE can be retrieved for it, or when it has neither a state vector nor a NORAD ID. In either case the spacecraft contributes no overflight events; unlike the Passes timeline, AOI overflight shows no per-spacecraft notice on the page. The reasons are the same two above for ground-station passes: | Situation | Reason | | - | - | | **No public TLE found** | "Couldn't retrieve a public TLE for NORAD — degraded mode unavailable for this spacecraft." | | **No state vector and no NORAD ID** | The spacecraft has no usable orbit — add orbit data on the [spacecraft page](/features/spacecraft-management); see [When There Is No Usable Orbit](#when-there-is-no-usable-orbit). | Degraded operation for AOI overflight is signalled solely by the unified [orbit-data-age footer](#the-orbit-data-age-footer), which tags the spacecraft **Degraded**; no individual overflight event carries a separate marker. While degraded mode is **off**, nothing falls back to a public TLE: a spacecraft with no state vector contributes no events, and one whose orbit age is past the [stale level](#stale-level) shows the stale-orbit warning in the forecast — and the footer tags that spacecraft **Blocked**. ### Orbit Plots & Ground Track on the Fallback Orbit plotting is the everyday visualization that runs on the fallback. While a spacecraft is at the degraded level, both orbit-plot surfaces propagate it from the **public TLE** the platform fetched and plot the result, instead of skipping it as they would without a fresh precise orbit. The [**Ground Track**](/features/3d-ground-track) page computes its ground track, 2D/3D globe position, and latitude/longitude plots from that public TLE; the [**Keplerian Elements**](/features/orbit-elements-plots) page computes its six orbital-element time-series from the same fallback. A spacecraft located by a NORAD catalog ID alone — with no operator **state vector** — becomes plottable on both surfaces, and the fallback-propagated results render exactly like results computed from a precise state vector, with no per-result marker that the orbit was a public TLE. Both plot surfaces follow the workspace degraded level in both directions: a spacecraft whose orbit age is past the degraded level plots on the public TLE, while a spacecraft within the degraded level plots on its precise state vector and is not sent to the fallback. No per-track, per-position, or per-series source marker distinguishes a fallback plot from a precise one. Degraded operation on both surfaces is conveyed solely by the unified [orbit-data-age footer](#the-orbit-data-age-footer), which tags the spacecraft **Degraded** (or **Blocked** once past the stale level); an individual plot carries no separate indicator, deliberately. With degraded mode enabled, the skipped-spacecraft warning lists only the spacecraft the fallback could not rescue. The reasons are the same two above for ground-station passes: | Situation | Skip Reason | | - | - | | **No public TLE found** | "Couldn't retrieve a public TLE for NORAD — degraded mode unavailable for this spacecraft." | | **No state vector and no NORAD ID** | The spacecraft has no usable orbit — add orbit data on the [spacecraft page](/features/spacecraft-management); see [When There Is No Usable Orbit](#when-there-is-no-usable-orbit). | While degraded mode is **off**, nothing falls back to a public TLE: a spacecraft with no state vector cannot plot, and a spacecraft whose orbit age is past the [stale level](#stale-level) shows the stale-orbit warning in place of its plots. ### Orbital Events on the Fallback Orbital-event computation also runs on the fallback. While a spacecraft is at the degraded level, the **Burn Plan** timeline computes its eclipse, apsis, node, and South Atlantic Anomaly (SAA) crossings from the **public TLE** the platform fetched for it, instead of skipping the spacecraft as it would without a fresh precise orbit. The fallback events render exactly like events computed from a precise **state vector** — the same eclipse and SAA bands, the same apsis and node markers, and the same per-event-type toggles in the **Display** popover — with no per-event marker that the orbit was a public TLE. Because a public TLE is lower accuracy, treat the exact entry and exit timing of a degraded spacecraft's events as indicative. Orbital-event computation follows the workspace degraded level in both directions: a spacecraft whose orbit age is past the degraded level computes its orbital events on the public TLE, while a spacecraft within the degraded level computes on its precise state vector and is not sent to the fallback. A degraded spacecraft's fallback events flow into the exported schedule alongside precise-orbit events. When the events came from a public TLE, the exported [`.ssf`](/file-formats/ssf) file carries an in-file `COMMENT` line — `Orbital events derived from public TLE - indicative timing` — so a downstream reader of the file is not misled about their precision. Separately, whenever the spacecraft's orbit-age verdict is not nominal — a public-TLE fallback in use, **or** a stale precise orbit — the file also carries the line `Orbit age is non-nominal - schedule timing may be degraded`. A degraded (public-TLE) export normally carries **both** lines together; a stale precise orbit that never fell back to a public TLE carries only the second. A spacecraft on a fresh precise orbit carries neither line. See the [Schedule Export Dialog](/features/burn-plan#schedule-export-dialog) for the export controls. The fallback can't rescue a degraded spacecraft in two cases — when no public TLE can be retrieved for it, or when it has neither a state vector nor a NORAD ID. In either case the spacecraft contributes no orbital events, and the skipped-spacecraft notice names the reason. The reasons are the same two above for ground-station passes: | Situation | Reason | | - | - | | **No public TLE found** | "Couldn't retrieve a public TLE for NORAD — degraded mode unavailable for this spacecraft." | | **No state vector and no NORAD ID** | The spacecraft has no usable orbit — add orbit data on the [spacecraft page](/features/spacecraft-management); see [When There Is No Usable Orbit](#when-there-is-no-usable-orbit). | Degraded operation for orbital events is signalled solely by the unified [orbit-data-age footer](#the-orbit-data-age-footer), which tags the spacecraft **Degraded** (or **Blocked** once past the stale level); no individual event carries a separate marker. While degraded mode is **off**, orbital-event computation is unchanged — a spacecraft with no fresh precise orbit is skipped exactly as it is today, and nothing falls back to a public TLE. ### Attitude Profiles & Export on the Fallback Attitude profiles also run on the fallback. While a spacecraft is at the degraded level, the attitude pages — the pointing-mode configuration and the quaternion-profile charts — compute its orientation over time from the **public TLE** the platform fetched for it, instead of showing the **No state vector available** block that asks you to define a precise orbit first. The pointing profile and the quaternion-component charts render exactly as they do for a spacecraft with a precise **state vector**, with no per-result marker that the orbit was a public TLE. Every pointing mode runs on the public TLE; none is excluded. How much the lower-accuracy orbit matters depends on the mode family: | Mode Family | Pointing Modes | On the Fallback | | - | - | - | | **Orbit-relative** | Earth/nadir, velocity-tracking, ground-track, orbit-angular-momentum, ground-point | Carries a small pointing error, since orientation is derived from the spacecraft's position and velocity | | **Inertial / celestial** | Inertial-pointing, sun-pointing, celestial-body | Essentially unaffected — orientation barely depends on orbital position | | **Custom** | Interpolated from an imported AEM file | Unaffected — orientation comes from the imported file, not the orbit | | **Free drift** | Uncontrolled | Unaffected — no orbit-derived pointing | The orbit-relative modes are the only ones a public TLE perturbs, and only slightly — treat their pointing as indicative rather than precise, exactly as for any other degraded result. See [What "Lower Accuracy" Means](#what-lower-accuracy-means) for the general caveat; there is no separate per-mode accuracy read-out on the page. The **Export** action is enabled for a degraded spacecraft — it is no longer disabled with a **No state vector available** reason — so you can still hand off an attitude product for a spacecraft running on the public TLE. The exported [AEM](/file-formats/aem) file is generated from the fallback orbit, with the same window, step size, representation, reference-frame, and Euler-sequence options as a precise-orbit export. When the attitude was computed from a public TLE, the downloaded AEM file carries an in-file `COMMENT` line — `Attitude derived from public TLE - lower accuracy` — so a downstream reader of the file is not misled about its precision once it leaves the platform. The same line also appears when the attitude was computed from a **stale** precise orbit rather than a fresh one — it signals reduced confidence in the orbit generally, not specifically that a public TLE was used. For a spacecraft with a fresh precise orbit the exported file is unchanged and carries no such comment line. Because the attitude pages compute for the single spacecraft you are viewing, a spacecraft the fallback can't rescue is not dropped from a list — instead the page reports the reason inline, on both the profile and the export: | Situation | Message | | - | - | | **No state vector and no NORAD ID** | The spacecraft has no usable orbit — add orbit data on the [spacecraft page](/features/spacecraft-management); see [When There Is No Usable Orbit](#when-there-is-no-usable-orbit). | | **No public TLE found** | "Couldn't retrieve a public TLE for NORAD — degraded mode unavailable for this spacecraft." | | **Public TLE can't be propagated** | "The public TLE for NORAD could not be propagated — degraded mode unavailable for this spacecraft." | Degraded operation for attitude is signalled solely by the unified [orbit-data-age footer](#the-orbit-data-age-footer), which lists every affected spacecraft — tagging each **Degraded** or **Blocked** — so degraded attitude is never silent; no individual profile or chart carries a separate marker. While degraded mode is **off**, the attitude pages are unchanged — a spacecraft with no fresh precise orbit shows the **No state vector available** block, and nothing falls back to a public TLE. ## Configuring orbit age Open **Settings → Orbits → Orbit age**. One section sets both levels together, along with the block switch; the policy applies to every spacecraft in the operations workspace. The unified Orbit age settings section showing the Enable degraded mode switch, the Degraded level day field, the Stale level day field, and the Block orbit-dependent products on stale orbits switch | Control | Detail | | - | - | | **Enable degraded mode** | Master switch for the degraded level. On by default. | | **Degraded level** | A whole number of days — the orbit age at which a spacecraft falls back to a public TLE. Required while degraded mode is on; accepted range `1`–`3650 days`. | | **Stale level** | A whole number of days — the orbit age at which a spacecraft is flagged stale. Default `14 days`; accepted range `1`–`3650 days`. | | **Block orbit-dependent products on stale orbits** | Enforces the stale level across passes, plots, AOI overflight, orbital events, attitude, and maneuver optimization. On by default. | | **Scope** | Workspace-wide — one orbit-age policy for every spacecraft in the operations workspace. | | **Measured from** | Each spacecraft's latest state-vector epoch (all times UTC). | To change the levels, click the edit (pencil) control, enter the day counts, and click **Save**. A confirmation reads **Orbit-age policy saved**. Because the degraded level must sit at or below the stale level, saving a degraded level above the stale level is rejected inline with **Degraded level must be at or below the stale level.** ### Validation Messages When you save, each level checks your entry and shows one of these messages inline if it cannot be accepted: | Message | When it appears | | - | - | | **A staleness threshold is required** | A required level was left blank — the stale level, or the degraded level while degraded mode is on. | | **Enter a whole number of days** | The entry is not a whole number — for example a decimal or non-numeric text. | | **Enter a positive whole number of days** | The stale level is below the minimum of 1 day. | | **Enter a staleness threshold of 1 day or more** | The degraded level is below the minimum of 1 day. | | **Degraded level must be at or below the stale level.** | The degraded level is greater than the stale level. | | **Enter a value between 1 and 3650 days** | A level is outside the accepted range of 1 to 3650 days. | ### Turning degraded mode off If you turn **Enable degraded mode** off while spacecraft are currently degraded, VALAR asks you to confirm before the change takes effect. The confirmation is titled **Turn off degraded mode?** with the body: > N spacecraft will return to requiring a precise orbit and their planning functions will be blocked until a fresh state vector is provided. Continue? Click **Continue** to disable degraded mode, or **Cancel** to keep it on. When no spacecraft are currently degraded, the switch turns off without a confirmation. ## Related Pages * [State Vectors](/features/state-vectors): Provide and manage the precise orbital data whose epoch orbit age is measured against, and which the public-TLE fallback stands in for. * [Spacecraft Management](/features/spacecraft-management): Set a spacecraft's NORAD catalog ID so it can use the public-TLE fallback at the degraded level. * [Ground Track](/features/3d-ground-track): The ground-track map that runs on the fallback at the degraded level and shows the stale-orbit warning past the stale level. * [Keplerian Elements](/features/orbit-elements-plots): The orbital-element time-series that run on the fallback at the degraded level and show the stale-orbit warning past the stale level. * [Overflight Events](/features/areas-of-interest/overflight-events): AOI overflight runs on the fallback at the degraded level and warns inline past the stale level. * [Burn Plan Timeline](/features/burn-plan): Review and export the orbital events that run on the fallback at the degraded level. * [Attitude Profiles](/features/attitude/overview): Configure pointing modes and export the AEM attitude file that runs on the fallback at the degraded level. * [Planner](/features/planner): Maneuver optimization asks you to acknowledge a stale orbit, and can't compute for a spacecraft with no usable orbit. * [CAM Optimization](/features/cam-optimization): Optimize collision-avoidance maneuvers, refused outright on a stale orbit until you provide fresher tracking data. # Orbit Determination Source: https://docs.valar.space/features/orbit-determination Run orbit estimation, manage orbit solutions, and interpret OD results > For the complete documentation index, see [llms.txt](/llms.txt). Orbit Determination (OD) enables you to compute precise spacecraft orbits by processing tracking measurements. Configure estimation runs, review residuals, and manage the resulting orbit solutions through an intuitive wizard interface. **Route:** `/orbits/orbit-determination/solutions` ## Overview Orbit Determination uses tracking measurements (range, angles, position/velocity) to estimate spacecraft state vectors with associated uncertainties. The platform supports: * **Batch Least Squares** estimation from tracking measurements * **Maneuver estimation** for thrust scale and pointing calibration * **Residual analysis** for data quality assessment * **Maneuver-aware processing** where detected maneuvers during the measurement arc are either estimated or considered ### Refine an Orbit from its Residuals Beside a saved solution’s **Residuals**, choose **Refine orbit** to select and stage rejection or restoration of multiple measurements. Use the **Select points** icon button at the top right of the chart to enable box selection; hover over or focus it for instructions. Selection and pending edits carry across residual components. Historical residuals without a source measurement link cannot be selected. Choose **Apply and configure new run** to save those changes and open a new OD configuration. It starts from the solution’s saved state vector and exact measured time span. Original run settings are not stored, so review the initial state, measurements and maneuvers before launching. Saving outlier changes does not launch OD; cancelling the subsequent configuration does not undo those saved changes. The original solution and residuals remain unchanged. Refinement is available after all residuals load and requires a saved state vector and a valid measured time span. ## Page Layout The Solutions page uses a split-view design with a solution list on the right and a details panel on the left. Od Solutions ## Viewing Orbit Solutions ### Solution List The solution list displays orbit solutions with the following information: * **Solution ID:** Unique identifier * **Status:** Convergence indicator icon (green checkmark = converged, red X = failed, gray circle = unknown) * **Measurements:** Total measurement count used (hover for breakdown by type) * **Spacecraft:** Colored satellite icon matching the spacecraft's assigned color * **Created:** Creation date in short format (hover for full UTC timestamp) ### Filtering Solutions * **Spacecraft:** Filter by one or more spacecraft using the spacecraft filter bar (empty shows all) * **Time Range:** Filter by solution creation date * **Group:** Group solutions by spacecraft or show as flat list Solutions are paginated within each group (5 per page) with navigation controls. ### Details Panel Click a solution to view details in the left panel. Use the **Previous/Next** navigation buttons at the top of the panel to step through solutions without returning to the list. **Overview Section:** * Spacecraft name with colored icon * Creation date (UTC) * Reference frame (GCRF, EME2000, TEME, or ITRF) **State Vector Section:** * Epoch (UTC) * Mass (kg), or *"From state vector"* if mass was inherited * Toggle between **Keplerian** and **Cartesian** tabs: * *Keplerian:* Semi-major axis (km), Eccentricity, Inclination (°), RAAN (°), Arg. of periapsis (°), True anomaly (°) * *Cartesian:* Position X/Y/Z (km), Velocity X/Y/Z (km/s) **Residuals Section:** * Arc time span (start and end epochs) * Tabbed scatter plots by measurement type: * **Range:** Residuals in meters * **RA/Dec:** Right ascension and declination residuals in arcseconds * **Az/El:** Azimuth and elevation residuals in arcseconds * **PV:** Position (m) and velocity (m/s) residuals for X/Y/Z components * **Doppler:** Range-rate residuals in m/s * **Measurement count badge** on each tab showing how many measurements of that type were used * **Sensor legend** with dynamic color coding (up to 8 distinct sensor colors) * **Maneuver overlay toggle** (flame icon button): Show or hide vertical markers at maneuver epochs on the residual plots. This helps identify whether residual patterns correlate with propulsive events * **Reference frame indicator:** A small chip next to the chart title on the **PV** tab shows the frame the X/Y/Z position and Vx/Vy/Vz velocity residuals are expressed in (driven by the OD solution's stored reference frame, e.g., `GCRF`). The other residual tabs (Range, RA/Dec, Az/El, Doppler) are non-frame-bearing and intentionally show no badge. Hover the badge for the full frame name; click **Learn more** to open the [reference frame catalog](/platform-overview/reference-frames). **Maneuvers Section:** The maneuvers section shows how maneuvers during the measurement arc were handled. Maneuvers are split into two groups: * **Estimated** maneuvers: Full cards showing thrust estimation results for each maneuver that was selected for estimation: * **Normalized performance** — thrust scale as a percentage of nominal (100.0% = nominal thrust). Color-coded: green (95–105%), orange (90–110%), red (outside 10% deviation) * **Azimuth deviation** — pointing offset in degrees from nominal thrust direction * **Elevation deviation** — pointing offset in degrees from nominal thrust direction * **Execution epoch** — when the maneuver was executed (UTC) * Individual fields show *"N/A"* when only partially estimated * **Considered** maneuvers: Compact pills showing only the maneuver ID. These are maneuvers that occurred during the measurement arc but were **not** selected for thrust estimation. They are still accounted for in the orbit propagation (the OD process uses their nominal delta-V) but no thrust scale or pointing corrections are computed When no maneuvers were present during the arc, a *"No Maneuver Estimations"* empty state is displayed. **Activity Section:** Timeline showing when the solution was created. ## Running Orbit Estimation Click **New Orbit Determination** in the toolbar to open the configuration wizard. The wizard guides you through the following steps to configure and launch an orbit estimation. ### Step 1: Initial State Configure the starting point for orbit estimation: * **Source Type:** Choose between: * **Public TLE** — Automatically fetched from SpaceTrack using the spacecraft's NORAD ID. The TLE is displayed read-only once loaded. Requires a NORAD ID to be configured on the spacecraft * **State Vector** — Select an existing state vector from the system (last 30 days, sorted by epoch) * **Mass:** Spacecraft mass in kilograms. Choose between entering a manual override or inheriting mass from the selected state vector Depending on the source type, configure the TLE or state vector parameters. Orbit determination initial-state step with a public TLE and launch mass selected ### Step 2: Measurements Configure which measurements to use for estimation: * **Spacecraft:** Select the spacecraft (shown in wizard header) * **Time Range:** Configure the measurement arc using one of two modes: * **Rolling window:** Last N days from current time (default 7 days). Adjustable via slider from 6 hours to 10 days in 6-hour increments * **Custom range:** Select a specific end date via date picker (up to 90 days in the past) * **Measurement Types:** Select data types to include — RA/Dec, Az/El, Range, PV, Doppler. All available types are selected by default * **Data Sources:** Select specific sensors from available sources. Only shown when sensors are associated with the measurement data * **Distribution Chart:** Interactive chart visualizing measurement coverage, groupable by type or by sensor Orbit determination measurements step with type and time-range controls ### Step 3: Maneuvers Configure which maneuvers to include for thrust scale estimation during orbit determination. Three selection modes are available: * **All:** Estimate thrust scale for every maneuver detected in the measurement time range * **None:** Don't estimate any maneuvers (maneuvers are still considered with their nominal delta-V) * **Above ΔV:** Only estimate maneuvers with delta-V at or above a specified threshold (in m/s) The maneuver list shows all detected maneuvers during the measurement period, each displaying its ID code, delta-V value (m/s), and execution epoch (UTC). Selected maneuvers are highlighted; unselected ones appear dimmed. When enabled, the OD process estimates thrust scale corrections for selected maneuvers, improving orbit accuracy across propulsive events. Unselected maneuvers are still propagated using their nominal parameters. ### Step 4: Residuals Preview Preview residual behavior before running the full estimation. This step shows pre-computation residuals as scatter plots, grouped by measurement type. Use the **Select points** icon button in the top-right corner of the chart to enable selection. Hover over or focus the button for instructions. Click individual observations or drag boxes around clusters. Each box adds to the selection; click a selected point again or hold **Alt** while dragging to remove points. Selection carries across component tabs, and each measurement is counted once even when it appears in multiple components. Choose **Reject selected** or **Restore selected** to stage changes without recomputing. Pending changes remain highlighted on the existing plots. Continue reviewing other clusters, use **Undo** to reverse the last edit, or **Discard changes** to clear unsaved edits. When ready, choose **Apply and recompute** to save the batch and refresh the preview once. Apply or discard pending changes before moving to another wizard step. If recomputation fails after saving, retry the preview; saved measurement changes remain in effect. Outlier changes update shared measurements and affect future OD runs that use them. They do not modify previously saved solutions. The **Recompute** button is also available to refresh the preview after other configuration changes. Doppler residuals plotted by sensor for a completed orbit determination ### Step 5: Review Review all configuration settings before launching. The review page shows summary cards for: * **Initial State** — Source type (TLE or State Vector), source details, and mass * **Measurements** — Time span and selected measurement types * **Maneuvers** — Selected maneuver codes displayed as pills, or *"No maneuvers selected"* when none are chosen Each card has an **edit button** to jump back to that step and adjust settings. Click **Launch Orbit Determination** to start the process. ## Estimated Parameters and Force Model Regardless of which [force model](/platform-overview/force-model) the platform applies during propagation, orbit determination always estimates the same dynamic parameters: a scalar **drag coefficient (Cd)** and a scalar **reflectivity coefficient (Cr)**. Configuring an attitude profile on the spacecraft so that propagation runs in attitude-dependent mode does not add, remove, or rename estimated parameters. The OD setup, residual plots, and convergence reporting remain consistent; the estimated coefficients act as scaling factors over the underlying force model the propagator is using. ## Monitoring OD Progress After launching, the platform processes OD jobs asynchronously. You can navigate away and return later to view results. The solution will appear in the list once processing completes. Solution status is indicated by icons in the solution list: * **Green checkmark:** Converged successfully * **Red X:** Failed to converge * **Gray circle:** Unknown/processing ## Deleting Orbit Solutions From the details panel header, click the **⋮** menu and select **Delete Solution**. A confirmation dialog will appear before deletion. ## Related Pages * [State Vectors](/features/state-vectors): Manage orbit solutions, import solutions (OPM, SpaceX OPM formats), and export ephemeris (OEM format) * [Measurements Data](/features/measurements-data): View and manage tracking measurements * [Tracking Sensors](/features/tracking-sensors): Configure measurement sources * [Force Model](/platform-overview/force-model): How VALAR selects between isotropic and attitude-dependent drag/SRP # Keplerian Elements Source: https://docs.valar.space/features/orbit-elements-plots Visualizing orbital elements over time > For the complete documentation index, see [llms.txt](/llms.txt). The Keplerian Elements page displays time-series visualizations of the six classical orbital elements for your spacecraft. Each element is shown in its own chart card, and you can filter by spacecraft and reorder the cards to customize your view. **Route:** `/state-vectors/keplerian-elements` ## Page Layout Keplerian Element Plot ## Orbital Elements Displayed The page shows 6 Keplerian orbital elements in a 2-column grid: | Element | Symbol | Unit | Description | | - | - | - | - | | **Semi-major Axis** | a | km | Half the longest diameter of the orbital ellipse | | **Eccentricity** | e | - | Shape of the orbit (0 = circular, less than 1 = elliptical) | | **Inclination** | i | deg | Tilt of the orbit relative to Earth's equator | | **RAAN** | Ω | deg | Right Ascension of Ascending Node - where orbit crosses equator going north | | **Argument of Perigee** | ω | deg | Angle from ascending node to closest point to Earth | | **True Anomaly** | ν | deg | Current position of spacecraft along the orbit | ## Spacecraft Filter Filter which spacecraft are plotted on all charts. | Element | Description | | - | - | | **Location** | Top-left of page | | **Control** | Multi-select dropdown with badge | | **Default** | Shows all spacecraft when none selected | **Actions:** * Click to open popover dropdown * Check/uncheck spacecraft to display * Click **Apply** to confirm selection * Click **Clear All** to deselect all * Remove individual spacecraft via **X** button on badges **Effect:** * Filters which spacecraft are plotted on all charts * Each spacecraft shown as separate colored line * URL updates to persist selection ## Element Cards ### Card Structure Each orbital element is displayed in a card containing: Plot Card **Header Elements:** * **Element Name:** e.g., "Semi-major Axis" * **Unit:** e.g., "km" or "deg" * **Reference Frame Indicator:** A small chip showing the frame the element values are expressed in (e.g., `GCRF`). Hover for the full frame name; click **Learn more** to open the [reference frame catalog](/platform-overview/reference-frames). The badge appears on every element card on this page. * **Drag Handle:** Grip icon for reordering ### Chart Visualization Each chart displays: **X-Axis:** Time (UTC) * 5 evenly-spaced tick labels * Shows date/time labels **Y-Axis:** Element value * Auto-scaled to fit data * Formatted by element type: * Semi-major axis: Integer km values * Eccentricity: 4 decimal places * Angular elements: 2 decimal places with ° **Lines:** * One line per selected spacecraft * Color-coded by spacecraft * Smooth curve interpolation * No dots on data points (clean lines) ## Drag-and-Drop Reordering ### How to Reorder Cards Each card has a grip icon in the top-right corner. **To reorder:** 1. Hover over the drag handle - cursor changes to grab 2. Click and hold the drag handle 3. Drag the card to desired position 4. Release to drop **Visual Feedback:** * Dragged card shows preview overlay * Original position becomes semi-transparent (30% opacity) * "Chart hidden during reordering" message displays * Smooth animation when cards swap positions ### Keyboard Support * Use arrow keys to rearrange cards (when focused on drag handle) * Tab to navigate between drag handles ### Order Persistence * Your custom order is automatically saved to browser storage * Persists across page reloads and sessions * Stored with key `keplerian-elements-order` ### Default Order 1. Semi-major Axis 2. Eccentricity 3. Inclination 4. RAAN 5. Argument of Perigee 6. True Anomaly ## Chart Interactions ### Hover Tooltip Hover over any point on a chart line to see values: **Value Formatting:** * Semi-major Axis: Localized number with "km" (e.g., "7,012.34 km") * Eccentricity: 4 decimal places (e.g., "0.0012") * Angular elements: 2 decimal places with ° (e.g., "98.52°") ### Active Point Indicator When hovering: * Small filled circle appears at exact data point * Circle matches spacecraft color * White border for visibility ### Cursor Line * Dashed vertical line follows cursor * Helps align values across time axis ## Angular Element Handling For angular elements (Inclination, RAAN, Argument of Perigee, True Anomaly): **Discontinuity Handling:** * Charts automatically detect wrapping at 0°/360° boundaries * Line breaks at discontinuities to prevent unrealistic connections * Thresholds: * Inclination: 90° jump threshold * RAAN, Arg. of Perigee, True Anomaly: 180° jump threshold This ensures clean visualization without diagonal lines crossing the entire chart when angles wrap around. ## Data & Time Range ### Default Data Range | Direction | Range | | - | - | | **Past** | 1 day backward from current time | | **Future** | 1 day forward from current time | ### Data Resolution * Time step: 5 minutes (300 seconds) * Sufficient detail for orbital trends without overwhelming the charts ### Data Caching * Results cached per spacecraft/time range * Prevents redundant API calls when switching views ## When the orbit is stale or unusable The charts plot each spacecraft from a **fresh** orbit. A spacecraft's [orbit age](/features/orbit-age#orbit-age) is measured from its latest [state vector](/features/state-vectors) — the position and velocity at an epoch you provide through orbit determination, an [OPM](/file-formats/opm) import, or manual entry. As that age grows it crosses two levels in turn — the [degraded level](/features/orbit-age#degraded-level), then the [stale level](/features/orbit-age#stale-level) — and the page reacts differently at each. The charts normally compute the moment you open the page; on a stale orbit they wait for you to choose to proceed. What you see depends on the selected spacecraft's orbit age: | Orbit state | What the charts show | | - | - | | **Fresh** (within both levels) | The element charts plot normally — nothing extra. | | **Degraded** (past the [degraded level](/features/orbit-age#degraded-level)) | The charts plot from the platform-fetched public [TLE](/file-formats/tle), with an inline aging notice above them reading **This spacecraft's orbit is stale**, the orbit's age (`last determined N days ago`), and the level it crossed (`exceeds your N-day threshold`). When the fallback orbit is itself stale, the notice adds **the public-TLE fallback is also stale**. The charts still draw — the notice is a heads-up, not a block. | | **Stale** (past the [stale level](/features/orbit-age#stale-level)) | The charts are **held** until you choose to proceed. In place of the element charts, the page shows the same **This spacecraft's orbit is stale** panel — with the age and threshold lines — plus a **Compute anyway** button. Click **Compute anyway** to plot the element series from the stale orbit. | | **No usable orbit** | When a selected spacecraft has no orbit data of any kind to plot from, the charts are replaced by a panel reading **Can't compute — `{spacecraft}` has no usable orbit**, explaining that **There is no usable orbit data for this spacecraft, so this product can't be computed. Add tracking data to continue**, with an **Add orbit data** button that opens the [Spacecraft](/features/spacecraft-management) page. This is never shown as a raw error. | Both `N` values are whole days — the spacecraft's actual orbit age and your configured stale level. The stale and degraded levels are workspace-wide values set once in **Settings → Orbits → Orbit age** (stale level default `14 days`); the same values govern the [ground-track map](/features/3d-ground-track) and [AOI overflight](/features/areas-of-interest/overflight-events), so "stale" means one consistent thing across all three. See [Orbit age](/features/orbit-age#stale-level) for the workspace-wide policy and the block message. Every spacecraft affected at either level is also named in the unified [orbit-data-age footer](/features/orbit-age#the-orbit-data-age-footer) at the bottom of the page — tagged **Degraded** at the degraded level, or **Blocked** once past the stale level — so you can see which spacecraft are affected without inspecting each chart. ## Loading & Error States | State | Display | | - | - | | **Initial load** | Skeleton placeholders in each card | | **Data loading** | Skeleton animation while fetching | | **Switching spacecraft** | Brief loading state (500ms) | | **During drag** | "Chart hidden during reordering" message | | **No data** | "No data available" message with description | | **Error** | Red error message below the top bar | ## Color Coding Each spacecraft has a unique color that is consistent across: * Chart lines * Tooltip indicators (colored dots) * Spacecraft filter badges Colors are assigned from a predefined palette and retrieved from the spacecraft context. While there's no separate legend component, spacecraft colors are visible through selected spacecraft badges in the filter and tooltip color indicators when hovering on charts. ## Quick Reference | Category | Action | How To | | - | - | - | | Filter | Select spacecraft | Topbar dropdown | | Filter | Clear all selections | "Clear All" button in dropdown | | Filter | Remove single spacecraft | X button on badge | | View | See element values | Hover over chart | | Reorder | Move card | Drag grip handle | | Reorder | Keyboard reorder | Arrow keys on handle | | View | Compare spacecraft | Select multiple in filter | ## Understanding Keplerian Elements Keplerian elements are six parameters that uniquely define an orbit: 1. **Semi-major Axis (a):** Determines the size of the orbit 2. **Eccentricity (e):** Determines the shape (0=circle, 0-1=ellipse) 3. **Inclination (i):** Tilt relative to Earth's equator 4. **RAAN (Ω):** Orientation of where orbit crosses equator 5. **Argument of Perigee (ω):** Orientation of closest approach point 6. **True Anomaly (ν):** Current position along the orbit ### Why Track These Over Time? * **Detect orbital drift:** Semi-major axis changes indicate altitude changes * **Monitor stability:** Eccentricity variations show orbit shape changes * **Track precession:** RAAN and Argument of Perigee naturally precess * **Verify maneuvers:** Changes in elements after planned burns * **Predict decay:** Long-term trends in semi-major axis # Coverage Map Source: https://docs.valar.space/features/passes/coverage-map See every ground station's coverage footprint at a shared reference altitude on a single geographic map > For the complete documentation index, see [llms.txt](/llms.txt). The **Coverage Map** plots every ground station in your organization on a geographic map, each annotated with the coverage shape it can reach at a shared reference altitude. Use it to see ground-segment coverage spatially instead of reconstructing it mentally from a table of elevation and azimuth settings. **Route:** `/passes/coverage-map` Open the page via the **Coverage Map** tab in the Passes area's tab bar, alongside the existing **Table**, **Timeline**, and **Stations** tabs. ## What the Map Shows Every ground station in your organization appears as a marker at its configured latitude and longitude, plotted on the same full-bleed world map used elsewhere in the product. A docked list pane on the right mirrors the map, with one row per station. Coverage Map page with ground stations and coverage polygons plotted on the world basemap Click a station's marker on the map, or its row in the list pane, to open a hovercard with the station's name and its coverage status — either surface opens the identical hovercard, so it doesn't matter which one you use. Each station's marker reflects its coverage status: | Status | Marker Appearance | | - | - | | **Coverage available** | Solid marker, plus a filled coverage polygon showing the ground area the station can reach. | | **No coverage** | Same marker glyph and size, but outline-only — no fill, and no polygon. See [Reading the No-Coverage State](#reading-the-no-coverage-state) below. | The page is read-only — it visualizes stations, it does not create or edit them. See [Relation to the Stations Page](#relation-to-the-stations-page) below. ## Reference Altitude Every coverage polygon on the map is computed at a single shared reference altitude of **430 km**. A caption in the bottom-right corner of the map states this explicitly, reading `Coverage assumes a 430 km reference altitude.` One shared altitude is used instead of a different shape per spacecraft because a station's true reach depends on the altitude of whatever spacecraft is looking down at it — a station can see farther over the horizon for a spacecraft flying higher, and less far for one flying lower. Plotting a single, disclosed reference altitude gives every station a consistent, comparable coverage shape at a glance, rather than an exact-but-mission-specific shape that would need to be redrawn per spacecraft. ## Reading the No-Coverage State A station can end up with no usable coverage at the 430 km reference altitude — for example, when its configured azimuth limits and elevation mask combine to exclude every direction. When this happens, the station's marker still renders at the same glyph size as every other station, but outline-only, with no filled polygon around it. The marker itself is never hidden. A screenshot of a station in this state will be added here once one is available to capture. Opening the hovercard for a station in this state reads `No coverage at the 430 km reference altitude.` Don't confuse this with the page's loading state: while station data is still loading, the map and list pane show skeleton placeholders and no station markers render at all. A station rendered outline-only is a real station with a known, computed result of no coverage — not a station that hasn't loaded yet. ## Relation to the Stations Page The Coverage Map is a read-only geographic view of the ground stations already configured on the [Stations page](/features/passes/stations) — it adds no new station-management capability of its own. To add a station, or to change a station's location, elevation mask, or azimuth limits, use the Stations page; any change made there is reflected on the Coverage Map the next time it loads. # Elevation Masks Source: https://docs.valar.space/features/passes/elevation-masks How a ground station's surveyed horizon and its minimum elevation combine into the horizon actually used for passes > For the complete documentation index, see [llms.txt](/llms.txt). Every ground station sits inside a real landscape. Hills, masts, buildings, and the curve of the terrain block the sky unevenly — a station might see a spacecraft just a couple of degrees above the horizon to the north, and not until well into double digits to the south-east. An **elevation mask** is how you tell VALAR the actual shape of that skyline: the lowest elevation angle your station can use at each compass bearing, surveyed once and uploaded as a file. This is different from a station's **minimum elevation**, which is a single policy floor — a link-budget or regulatory limit you'd apply the same way in every direction, regardless of what is actually on the horizon. ## Why the Shape of the Horizon Matters A minimum elevation alone assumes a station has the same clear view in every direction. Real sites rarely do. If a ridge to the south blocks everything below 12 degrees but your station's minimum elevation is set to 5 degrees, a flat-minimum calculation reports contacts your antenna physically cannot make — the spacecraft is above the configured floor and behind the ridge at the same time. An elevation mask corrects this. Once your station has a surveyed horizon on file, passes are computed against the shape you actually have, not an idealized flat one. If this means a station reports fewer passes than it used to, that is the correction working as intended, not a loss of capability — those passes were never really there; the platform was simply not accounting for the terrain that always blocked them. ## How the Mask and the Minimum Elevation Combine A station's elevation mask and its minimum elevation are not alternatives where one silently wins. They combine at every compass bearing by taking **whichever is higher**. This combined value is the station's **applied horizon** — the actual threshold pass computation checks a spacecraft's elevation against. | At this bearing | Minimum elevation | Elevation mask | Applied horizon | | - | - | - | - | | Where terrain is taller than your floor | 5° | 12° | **12° — the terrain governs** | | Where terrain is lower than your floor | 10° | 3° | **10° — your policy floor governs** | Two things follow from this, and both are deliberate: * Your elevation mask can never **open up** access below your configured minimum elevation. If you intend a low surveyed value to take effect exactly as surveyed, your minimum elevation needs to be set at or below it. * Your minimum elevation can never **paper over** terrain your survey shows is blocking the sky. A ridge your survey says sits at 15 degrees stays at 15 degrees in the applied horizon, even if your minimum elevation is set to 0. The applied horizon is what every chart, preview, and pass computation on the platform uses — never a value recalculated independently by a different screen. See [Ground Stations](/features/passes/stations) for where to view a station's applied horizon and how to upload a survey. ## What Happens When a Pass Disappears If a pass you were used to seeing no longer appears after you upload a survey, that is expected: your station's real horizon — not the flat minimum elevation it used before — now governs that window, and the spacecraft never actually cleared your antenna's real sightline there. If instead a station reports no results at all where you expected some, check the [per-station outcomes on the Timeline](/features/passes/timeline) — that is a different situation from a single blocked pass, and the timeline tells you which one it is. ## Related Pages * [Passes Overview](/features/passes/overview) — how the Passes area's pages fit together. * [Ground Stations](/features/passes/stations) — upload an elevation mask and view a station's applied horizon. * [Timeline](/features/passes/timeline) — what each station's outcome on the timeline means. # Passes Overview Source: https://docs.valar.space/features/passes/overview Understand ground-station passes, coverage definitions, and how the Passes area's pages fit together > For the complete documentation index, see [llms.txt](/llms.txt). A **pass** is a period during which a spacecraft is above a ground station's applied horizon — a topocentric visibility window, not a guarantee of communication or mission readiness. The Passes area is where you configure the ground stations passes are computed against, and review the resulting coverage. **Route:** `/passes` Open the area via the **Passes** entry in the sidebar. Inside it, a shared tab bar switches between **Table**, **Timeline**, **Stations**, and **Coverage Map**. ## What Determines a Pass Whether a spacecraft counts as visible from a station at a given moment comes down to that station's **coverage definition** — either a single constant minimum elevation, or an elevation mask that varies by azimuth to describe an uneven local horizon. The station's coverage definition, evaluated by the server, is called its **applied horizon**; it is what pass computation actually checks against, not a value you calculate by hand. See [Elevation Masks](/features/passes/elevation-masks) for how the two combine. ## Pages in This Area | Page | What it's for | | - | - | | **[Elevation Masks](/features/passes/elevation-masks)** | Understand what an elevation mask is, why it matters, and how it combines with a station's minimum elevation into its applied horizon. | | **[Stations](/features/passes/stations)** | Create and edit the ground stations passes are computed against — location, reference frame, and coverage definition, with a coordinate minimap and a live applied-horizon preview. | | **[Timeline](/features/passes/timeline)** | Visualize computed passes per station, with a stated outcome for every station you asked about — including why a station shows nothing. | | **[Coverage Map](/features/passes/coverage-map)** | A read-only geographic view of every station's coverage footprint at a shared reference altitude, so you can compare ground-segment coverage spatially. | The **Table** tab lists computed passes themselves, alongside the other tabs in the same tab bar. ## Related Pages * [Elevation Masks](/features/passes/elevation-masks) — the concept behind a station's applied horizon. * [Ground Stations](/features/passes/stations) — the station-creation and editing flow, including the CSV format for uploading an elevation mask. * [Timeline](/features/passes/timeline) — per-station pass outcomes, including excluded and not-evaluated stations. * [Coverage Map](/features/passes/coverage-map) — see every station's coverage footprint on one map. # Ground Stations Source: https://docs.valar.space/features/passes/stations Manage ground stations and inspect their spacecraft pass geometry, coverage, and applied horizon The **Stations** page is where you manage the ground stations your organization tracks passes against. Each station has a fixed location and can retain up to ten named elevation masks. A mask uses either the station’s constant minimum elevation or an uploaded horizon profile. Choose one mask per station when configuring a pass calculation. **Route:** `/passes/stations` > For the complete documentation index, see [llms.txt](/llms.txt). Open the page via the **Stations** tab in the Passes area's tab bar, alongside the **Table**, **Timeline**, and **Coverage Map** tabs. ## Page Layout Ground Stations page showing the station list and a selected station overview The page is a two-pane layout. The main area shows the selected station's overview — its code, name, the subtitle **Ground station overview and current pass opportunities**, a row of pass summary cards (see [Station Status and Pass Summary](#station-status-and-pass-summary) below), and the station's applied horizon (see [Viewing a Station's Applied Horizon](#viewing-a-stations-applied-horizon) below). The right pane lists your stations. Search by name or code and filter by Active or Inactive status. Click a row to select it; the selection stays in the URL when you reload or share the page. Use the list toggle in the top bar to give the overview more room. On narrow screens, the station list stacks below the overview instead of forcing horizontal scrolling. Each row in the station list also carries a quick summary: every spacecraft with a recorded pass at that station appears as a pill with a satellite icon, and a field on the right names the spacecraft from the station's most recent pass — or reads **No passes** if it has none yet. A station with no associated spacecraft shows a dash instead of pills. Each row also states whether the station is **Active** or **Inactive** (see [Active and Inactive Stations](#active-and-inactive-stations) below). Spacecraft pills wrap beneath the station name so the summary fits within the list pane. Click **New Station** in the top-right corner to open the [ground-station creation modal](#creating-or-editing-a-ground-station). Selecting a station and opening its kebab menu (**⋮**) offers **Edit Station**, **Deactivate station** (or **Activate station**), and **Delete Station**. When your organization has no stations yet, the page shows **No ground stations configured** with an **Add Ground Station** button that opens the same modal. ## Optional RF-band and direction labels When optional mask labels are available to your account, open **Edit Station** or **Edit masks**, choose a mask, and enter **RF bands (optional)**. Separate custom labels with commas, for example `S, X`. **Link direction (optional)** accepts **Uplink**, **Downlink**, **Both**, or **Unspecified**. You can leave either field empty or clear it later. The same controls are available in Mission Analysis's station editor. Provider-owned masks remain read-only. Labels appear beside mask names in station details and calculation selectors. You still choose the mask explicitly; a label does not change visibility calculations or establish RF or regulatory suitability. Existing masks work without labels. Results retain the classification saved with their calculation, so later station edits do not relabel past work. Previously calculated results may have no classification. Seasonal validity is not inferred from these labels. ## Station Status and Pass Summary Beneath the selected station's name, a row of summary cards recaps the station at a glance: | Card | What it shows | | - | - | | **Status** | Whether the station is currently **Active** or **Inactive** (see [Active and Inactive Stations](#active-and-inactive-stations) below). | | **Next pass** | A live countdown to the station's next pass, reading `In 2h 15m 30s` style, **Now** once the pass time has arrived, or **—** when no next pass is scheduled. | | **Overflights · 7 days** / **Contact windows · 7 days** | Distinct overflights when that count is available; otherwise contact windows, within the same seven-day window as the heatmap. **—** means no count is available. When overflights are shown, a separate caption gives the number of contact windows. | The **Status** card is always present. The **Next pass** and seven-day count cards appear together with the station pass opportunities panel, and show a loading placeholder while their summary is being fetched. Several contact windows can belong to one overflight, so these counts are not interchangeable. ## Active and Inactive Stations Every station is either **Active** or **Inactive**. The station's **Status** card states which, and each row in the station list carries the same word — the state is always written out, never indicated by color alone. Active stations take part in pass computation as normal. An inactive station stays listed and selectable; it only stops contributing new pass work, so no new passes are computed for it. Passes it already has remain in place, and you can still select the station, edit it, and review its recorded passes. Deactivation is not deletion, and it asks for no confirmation. To deactivate a station, select it, open its kebab menu (**⋮**), and choose **Deactivate station**. The menu item reads **Deactivating...** while the change is in flight. Once the station is inactive, the same menu offers **Activate station**, which restores full participation in pass computation — no other changes are needed. ## Importing KSAT antennas For workspaces with KSAT enabled, an administrator can open **Settings → Integrations** and configure the KSAT account. Where the modal setup is available, choose **Connect** or **Manage**, select Test or Production, and verify a service API key. Map your VALAR spacecraft to their KSAT counterparts; **Add spacecraft mapping** lets you configure several mappings before saving, including inactive or archived VALAR spacecraft. Choose antennas from the list grouped by site, then save the mappings and antenna selection. A new account starts with no antennas selected. **Select all** is optional; saving an empty selection imports no stations. All mappings for the same KSAT account share the selected antennas. If a later mapping fails to save, the modal identifies how many succeeded so you can review and retry the remainder. Newly imported antennas appear as **Inactive** stations. VALAR retains KSAT's receive and transmit elevation masks separately; provider geometry and orbit readiness must be qualified before operational use. Importing or mapping an archived spacecraft does not activate it or establish booking readiness. Use **Manage** to review mappings and readiness or to disconnect. Disconnecting keeps station identities and history; disconnecting the account or its last spacecraft removes the saved key and deactivates imported antennas. Existing reservations remain in KSAT. Reconnect retained mappings by verifying the account and selecting the spacecraft to reconnect. Closing setup discards unsaved credentials and choices. ## Inspecting a Station Opportunity When a selected station has pass opportunities, the **Station pass opportunities** panel appears beside the antenna constraints. It shows a seven-day heatmap divided into 24-hour columns. An empty hour is labelled **No opportunities in this hour.** when the current result is known; if no current result exists, it is labelled **No current pass result is available.** When the result covers several spacecraft, the panel header carries an **AGGREGATE** badge, with a coverage line beneath it. The line reads **N of M spacecraft covered** — for example, **2 of 3 spacecraft covered** — followed by **· missing:** and the names of any spacecraft without opportunities, or **· complete coverage** when every requested spacecraft is covered. An empty panel distinguishes why it is empty. A genuinely empty seven-day window reads **No pass opportunities in this seven-day window.** When some covered spacecraft returned no opportunities, it reads **No pass opportunities returned for the covered spacecraft; this result is incomplete.** When the underlying spacecraft data is stale or the result is degraded, it reads **Opportunities are unavailable because the spacecraft data is stale; refresh and retry.** or **Opportunities are limited because the current result is degraded; refresh and retry.**, with a **Refresh** button — a stale or degraded result is not the same as an empty window. Click a populated hour to select that time bucket. The page shows a compact list of the passes in that hour. Each pass includes its UTC acquisition time, spacecraft name, and **CANDIDATE** or **BOOKED** disposition. Click a pass to open its read-only pass geometry below the station overview. The opportunity panel can also show the current result's state: | Status | What you see | | - | - | | **Current result** | The current pass result is available for inspection. | | **No current result** | No current result is available for the selected station and spacecraft. | | **No pass opportunities in this window** | The seven-day window was evaluated and contains no pass opportunities. | | **Stale current result** | The displayed result is older than the current result. | | **Partial current result** | A combined result covers some, but not all, of the requested spacecraft. | | **Degraded current result** | The result is available with reduced quality information. | ## Pass Geometry Inspector After you select an opportunity, the **Pass geometry** section appears below the station overview. It reads **Predicted geometry for the selected station opportunity** and keeps every panel tied to the same selected prediction epoch. | Panel | What you see and do | | - | - | | **Track map** | A window-only map with **Track** and **Station** markers. The map shows the predicted ground track and the station location; it is not a precise station-capability footprint. | | **Prediction playback** | A **Prediction epoch** slider, the selected UTC epoch, and a **Play** or **Pause** control. Moving the slider or starting playback changes the selected epoch. | | **Elevation profile** | Predicted elevation in degrees across the pass, with computed event markers and a line identifying the selected epoch. | | **Azimuth profile** | Predicted azimuth in degrees across the pass, with the same event markers and selected-epoch line. | | **Computed geometry markers** | Small marker dots on both profiles at the pass's event epochs — acquisition of signal, maximum elevation, and loss of signal. The computed causes behind each event are not displayed in this view. | | **Provenance** | Freshness and quality badges, sampling outcome, revision, digest, source, frame/datum, and sample count. | The selected epoch is synchronized across the map marker, both profiles, and the playback control. All displayed epochs and times use UTC. ## Pass Geometry States The inspector keeps loading, valid empty, restricted, invalid, and unavailable results distinct. It never shows partial track data or raw error details. | State | What you see | What it means | | - | - | - | | **Preparing geometry for this opportunity…** | A loading card under **Pass geometry**. | The selected opportunity's geometry is being prepared. No map, profiles, readout, or playback controls are shown yet. | | **No pass window is available.** | The empty-state message plus the provenance context. | The opportunity has no usable pass window, so no track or prediction controls are drawn. | | **Station geometry is restricted for your role.** | A restricted-state message with no geometry details. | The station's capability geometry is not exposed in this view. | | **Couldn't load pass geometry. Please try again.** | A failure message without raw service details. | A temporary or terminal service failure prevented the geometry from being displayed. Temporary failures are retried automatically within the active prediction window; no redrive control is shown for a terminal failure. | | **Pass geometry is unavailable for this opportunity.** | An unavailable-state message. | No usable geometry is available for the selected opportunity. | | **Pass geometry is unavailable because its data is invalid.** | An invalid-data message. | The returned geometry could not be interpreted safely, so it is not drawn. | When a displayed result is stale or degraded, the **Provenance** dialog shows the corresponding **STALE** or **DEGRADED** badge and the message **Geometry is informational and non-authoritative until the current result is refreshed.** Treat that geometry as review context rather than current authoritative coverage. For a legacy station with unrestricted azimuth and an unknown elevation mask, the coverage card shows a **Mask unknown** badge instead of a bounded-coverage figure — the inspector does not display a precise footprint for this state. ## Viewing a Station's Applied Horizon Selecting a station shows its **applied horizon** in the overview — the composed curve pass computation actually uses, alongside the raw survey behind it and your configured minimum elevation as a reference line. See [Elevation Masks](/features/passes/elevation-masks) for how these combine. The applied-horizon panel is rolling out gradually — until it reaches your account, the station overview shows the coverage chart without the rows described below. | Situation | What you see | | - | - | | **A surveyed elevation mask is on file** | Two curves: the applied horizon (dominant) and the raw survey behind it. Wherever the two coincide exactly, a note confirms it, so a single visible curve is never mistaken for a missing one. | | **No elevation mask is on file** | A single curve at your configured minimum elevation. | | **This station's stored horizon cannot be read** | **No horizon available for this station** — no chart is drawn, and no engine-applied curve can be shown until the survey is re-uploaded. | | **The station's details failed to load** | **Failed to load this station's horizon**, with a **Retry** button. | Beneath the chart, two rows describe the horizon in force: | Row | What it tells you | | - | - | | **Horizon in force** | The angle currently governing this station. If your minimum elevation is what's actually binding — the survey would have allowed lower access but your policy floor doesn't — this is called out explicitly rather than left for you to work out from the chart. | | **Horizon basis** | Where the applied horizon comes from: **Surveyed** (from an uploaded elevation mask), **Platform default** (no survey on file; a uniform horizon derived from your minimum elevation), or **Unspecified** (see note below). | **Unspecified** does not mean something is wrong with the station. It means the station was configured before VALAR began recording where a horizon comes from, so its provenance was never captured — not that a survey is missing or that the platform is guessing. A line beneath these rows may also state whether the horizon has been applied yet: for a station whose survey was just uploaded but hasn't yet been used in a pass computation, it reads **This horizon is on file but has not yet been applied to any pass computation.** Once it has been used, the same line instead reads **Horizon in force since \**. ## Creating or Editing a Ground Station New Ground Station modal showing the site-location column with a populated minimap, and the coverage-definition column in constant minimum elevation mode Creating or editing a station opens a single modal — **New Ground Station** or **Edit Ground Station** — with no next/back steps to move through. Every field for the station lives on one scrollable surface, arranged in two columns: **Site location** on the left and **Coverage definition** on the right. On narrower screens the two columns stack into one, so nothing here requires horizontal scrolling at any supported window size. ### Site Location | Field | Description | | - | - | | **Station name** | Free-text identifier for the station. | | **Latitude** | Geodetic latitude in degrees, `-90` to `90`. | | **Longitude** | Geodetic longitude in degrees, `-180` to `180`. | | **Altitude (m)** | Station altitude in meters. | | **Reference Frame** | Shown as a fixed `ITRF2020` badge next to the section heading — every station uses this frame; there is nothing to choose. | Below the coordinate fields is a compact 16:9 minimap that places a marker at the entered latitude and longitude as soon as both are valid. It is a location check only — it confirms the point on the globe you meant, not terrain suitability, antenna readiness, or coverage. | Situation | What you see | | - | - | | **Latitude and longitude are both valid** | A marker appears at the entered coordinates. | | **Coordinates are blank or incomplete** | No marker; the map reads **Enter the station coordinates**. | | **A coordinate is out of range** | No marker for that value; the field itself shows an inline error (see [Validation](#validation) below). | | **The map cannot load** (no token, or WebGL unsupported) | The frame reads **Map preview unavailable**; the coordinate fields stay usable regardless. | ### Coverage Definition The two coverage forms are alternatives, not two limits you combine — choose the one that describes this station's horizon and the modal shows only the fields that choice needs. The right column holds one exclusive choice between two coverage definitions: | Option | Description | | - | - | | **Constant minimum elevation** | One policy floor around the station — the same minimum elevation angle applies at every azimuth. | | **Elevation mask** | A surveyed horizon that changes by azimuth, supplied as a CSV file. | Switching between the two clears whatever you had entered for the other — a mask you uploaded does not reappear if you switch back to it after selecting constant minimum elevation, and vice versa. #### Constant Minimum Elevation Enter a single **Minimum elevation (degrees)** value between `0` and `90`. A new station starts at `10.0` degrees by default. #### Elevation Mask (CSV Upload) Choose a CSV file under **Elevation mask CSV**. Each row is one `azimuth,elevation` pair: ``` azimuth,elevation 0,10 90,15 180,12 270,8 ``` **Each row applies from its azimuth boundary until the next boundary** — a row does not describe a single point, it describes an interval. For example, `0,10` followed by `90,15` means 10 degrees applies from azimuth 0 up to (but not including) 90 degrees, where the 15-degree value takes over. The final interval wraps around from 360 degrees back to 0 degrees, so the last row's value also covers the gap back to the first row's azimuth. | Requirement | Detail | | - | - | | **Columns** | `azimuth,elevation`, in that order. | | **Header row** | Optional — a first row that contains the word "azimuth" is detected and skipped automatically. | | **Azimuth range** | `0°` up to (not including) `360°`. Any spacing between rows is accepted — the rows do not need to be evenly spaced. | | **Elevation range** | `0°` to `90°`, inclusive. | | **Repeated azimuth, same elevation** | Accepted — the repeat is redundant and simply collapses to one point. | | **Repeated azimuth, different elevation** | Rejected — an azimuth cannot carry two conflicting elevation values. | If a row fails validation, the upload is rejected with a message naming the offending row or azimuth, and whatever mask you had previously uploaded successfully stays in place — a bad file never clears a good one. Activating the upload without choosing a file first shows **Choose a CSV before it can be previewed**. ### Applied Horizon Preview New Ground Station modal in elevation mask mode, showing an uploaded CSV file and the resulting applied-horizon radar preview Below the coverage controls, a radar-style chart shows the **applied horizon** — the server-evaluated result of your coverage definition, redrawn shortly after you stop typing or a file finishes uploading. This is the same interpretation the platform uses to compute passes; you review the result rather than calculating it yourself. The minimum elevation value carries over as a floor beneath an elevation mask too: for any azimuth where the mask specifies a lower elevation than the current minimum-elevation value, the higher of the two is what the preview (and the saved station) actually applies. If you intend a mask value to take effect exactly as surveyed, make sure the minimum elevation is set at or below it. | Situation | What you see | | - | - | | **Nothing entered yet** | **Enter a coverage definition to preview the applied horizon.** | | **A value just changed and the new preview hasn't returned yet** | The previous chart dims and reads **Preview is out of date**. | | **The preview request is in flight** | A loading placeholder replaces the chart — no stale result is shown as current. | | **The server cannot evaluate the current draft** | **Horizon could not be evaluated**, with guidance to adjust the minimum elevation or the uploaded survey. Saving is blocked until this clears. | | **Constant minimum elevation, valid** | A uniform circle at the chosen elevation. | | **Elevation mask, valid** | A shape that varies by azimuth, reflecting the uploaded survey (composed with the minimum-elevation floor above). | | **Editing an existing station whose stored profile can't be interpreted** | **Applied horizon unavailable** — every other field on the station stays editable regardless. | ### Validation Every field is checked as you type; a required field only shows as missing after you attempt to save. | Field | Error shown | | - | - | | **Station name** | Enter a station name | | **Latitude** | Enter a latitude / Latitude must be between -90 and 90 degrees | | **Longitude** | Enter a longitude / Longitude must be between -180 and 180 degrees | | **Altitude (m)** | Enter an altitude / Altitude must be a number | | **Minimum elevation (degrees)** | Enter a minimum elevation / Minimum elevation must be between 0 and 90 degrees | If saving fails after every field validates, the modal stays open, every value you entered is preserved, and a banner explains what went wrong so you can retry without re-entering anything. Click **Cancel** to close without saving, or **Create station** (**Save changes** when editing) to save. The button reads **Saving...** while the request is in flight. ## Editing or Deleting a Station Select a station in the list, open its kebab menu (**⋮**), and choose **Edit Station** to reopen the same modal pre-filled with that station's values, or **Delete Station** to remove it. The same menu also offers **Deactivate station** (or **Activate station** on an inactive station) — see [Active and Inactive Stations](#active-and-inactive-stations). Deleting asks you to confirm first — **Are you sure you want to delete \? This action cannot be undone.** ## Related Pages * [Passes Overview](/features/passes/overview) — the Passes area's landing page and a map of where each Passes page fits. * [Elevation Masks](/features/passes/elevation-masks) — what a station's elevation mask is and how it combines with its minimum elevation. * [Sensors](/features/tracking-sensors) — managing the tracking sensor configurations alongside your ground stations. * [Timeline](/features/passes/timeline) — what each station's outcome on the timeline means, including what to do about it. * [Coverage Map](/features/passes/coverage-map) — a read-only geographic view of every station's coverage footprint at a shared reference altitude. ## Booking and past events The next upcoming pass is selected automatically when results are available. Use the **Spacecraft** filter to narrow opportunities, or select a populated heatmap hour and then a pass in that hour. Times use 24-hour UTC throughout the inspector. Click **Book event** in the selected pass inspector to save it in one step. No additional fields are required. The saved event includes the geometry, coverage, plots and provenance available in that inspector. Later recomputations do not replace this saved information. Open **Booked events** in the top bar to browse **Past** or **Upcoming** bookings. Select a booking to inspect it and replay its saved geometry. The timestamp labelled **Saved at booking** identifies when the information was preserved. Bookings remain available when the original computation is superseded. Older bookings are also listed. If a booking predates saved inspectors, its retained timing and measurements remain available, with a clear note that its original geometry and plots were not retained. A booking made from the Timeline saves the timing and measurements available there. The current inspector presents data freshness compactly. Select **provenance** below the map to open the same dialog presentation used by AOI, including revision identifiers, sampling details and the source record. The opportunity selector appears directly below **Pass geometry**. # Timeline Source: https://docs.valar.space/features/passes/timeline Read every requested station's pass outcome, including why a station shows nothing The **Timeline** shows the latest pass result for the spacecraft and ground stations you select. It combines a shared time axis with one lane per station, and keeps the result state visible while stored results refresh. **Route:** `/passes/timeline` > For the complete documentation index, see [llms.txt](/llms.txt). Open the page via the **Timeline** tab in the Passes area's tab bar, alongside the **Table**, **Stations**, and **Coverage Map** tabs. When the combined [Operations Timeline](/features/timeline) is available, this entry opens its corresponding event layer, grouped by spacecraft. ## Page Layout Use the toolbar to choose the spacecraft, time range, and ground stations included in the result. The time-range menu provides exact rolling windows: **Next 24h** (default), **Next 3 days**, and **Next 7 days**. Restored windows of another duration read **Custom range**; a window longer than seven days asks you to choose a supported range. Choose **Wide** or **Compact** to change the amount of horizontal detail on the time axis, or click **Export** to open the schedule-export dialog. The main pane shows the result state above the timeline. When a result is available, each requested station has a header row and its spacecraft pass rows beneath it. Click a station header to collapse or expand its rows. Click a pass bar to inspect its spacecraft, station, AOS, LOS, duration, and maximum elevation when that value is available. Focus a pass and use the Left and Right arrow keys to move through that row chronologically, including passes outside the visible window. Stations with incomplete stored coverage show the number of unavailable spacecraft. ## Lifecycle Result States The timeline reads stored results for the current selection. It does not start a pass calculation. An unavailable stored result is different from a successful result with no passes. Scheduled refreshes produce the stored evidence; Refresh and Retry only read it again. | Status | What you see | What it means | What to do | | - | - | - | - | | **Loading stored results** | A skeleton on first load, or a loading notice alongside booked passes. | The stored-result read is in progress. | Wait for the read to finish. | | **No stored result for this selection** | An explicit notice; booked passes remain visible separately. | Stored evidence does not cover this selection. This does not establish that there are no passes. | Adjust the range or filters, or use **Refresh stored results** to read again after scheduled results become available. | | **Current result** | Pass bars and station lanes are shown. | A completed result is available for the selected spacecraft, stations, and time range. | Read the bars and station outcomes. | | **No passes available** | The page or an evaluated station lane reads **No passes available**. | The selection was evaluated successfully and no visibility window was found. This is different from a failed calculation. | Nothing is required; adjust the filters or time range if you want to search elsewhere. | | **Current pass result is stale** | A status banner reads **Current pass result is stale. Refresh to update the timeline.** with **Retry**. | The displayed result is older than the current freshness policy. | Click **Retry** to request a fresh result. | | **Pass result is degraded** | A status banner reads **Pass result is degraded. Some station lanes may be unavailable.** with **Retry**. | The result is available, but one or more station outcomes could not be fully evaluated. | Read the affected station lane and retry after fixing the station configuration if needed. | | **Couldn’t refresh passes** | An alert reads **Couldn’t refresh passes. Showing the last current result.** with **Retry**. | A refresh failed, but the last completed result is still available and remains visible. | Click **Retry**; do not treat the preserved result as newly computed data. | | **Failed to load stored pass results** | An error notice offers **Refresh stored results**; booked passes remain visible. | The stored-result read failed. | Refresh the stored result. If the failure persists, contact support. | | **Couldn’t load booked passes** | An error notice offers **Retry booked passes**; stored candidates remain visible. | Booked status cannot currently be confirmed. Booking is disabled until the read succeeds. | Retry the booked-pass read. | **No passes available** is a completed, successful empty result. **Failed to load stored pass results** means the timeline could not obtain a usable result. The two states require different responses. ## Every Requested Station Gets a Lane Every station you select gets its own lane on the timeline — always, whether or not it has any passes to show. A lane is never dropped just because a station has nothing to report, because "nothing to report" is not one situation; it is three different ones, and the timeline tells you which: | Outcome | What the lane shows | What it means | What to do | | - | - | - | - | | **Evaluated, with passes** | The station's pass bars along the timeline. | The station was checked and has visibility windows in this range. | Nothing — read the passes as usual. | | **Evaluated, no passes** | A lane reading **No passes available**. | The station was fully checked against your selection and genuinely has nothing overhead in this window. | Nothing — this is a clear result, not a failure. | | **Excluded** | A muted lane and a notice with the station's explanation. | The station's configuration — most often its elevation mask — could not be evaluated, so no result could be computed for it. | Fix the station configuration, then click **Retry**. For an elevation-mask issue, use the [Stations](/features/passes/stations) page to re-upload the survey. | | **Not evaluated** | A muted lane reading **Couldn't evaluate this station**. | The computation did not reach a conclusion for this station. | Click **Retry**; contact support if it persists. | An excluded station's message describes the station's own configuration problem rather than a generic failure, so it names what to fix instead of just saying something went wrong. If the message doesn't make sense, re-check the station's elevation mask on the [Stations](/features/passes/stations) page. ## Computed and Booked Passes The timeline can show two kinds of pass bar: | Pass type | What you see | What you can do | | - | - | - | | **Computed candidate** | A newly calculated pass bar, shown separately from saved bookings. | Open the bar and click **Book** to save it as a pass. | | **Booked pass** | A saved pass with a **BOOKED** badge in its details. | Review its timing and geometry; it is already booked. | Computed candidates and booked passes can appear together. A **No passes available** result refers to the completed current calculation; it does not erase booked passes that are listed separately. ## Why This Distinction Matters An empty result, an excluded station, and a failed refresh require different actions. Because every requested station gets a lane and a stated outcome, a clear result and a station configuration problem never look the same. Because a failed refresh preserves the last current result, you can continue reading the previous result while deciding whether to retry. ## Related Pages * [Passes Overview](/features/passes/overview) — how the Passes area's pages fit together. * [Elevation Masks](/features/passes/elevation-masks) — what a station's elevation mask is and how it combines with its minimum elevation. * [Ground Stations](/features/passes/stations) — upload or replace a station's elevation-mask survey. # Planner Source: https://docs.valar.space/features/planner Create and manage orbital maintenance plans using optimization algorithms > For the complete documentation index, see [llms.txt](/llms.txt). The Planner allows you to create and manage orbital maintenance plans for your spacecraft. Using optimization algorithms, the Planner computes a sequence of maneuvers to keep a spacecraft within defined orbital parameters over a given time window. **Route:** `/maneuvers/planner` ## Flight-plan forecasts (internal rollout) In **Maneuvers → Flight plan**, saved phases have an automatic forecast. New suitable orbital data or changes to saved phase and spacecraft inputs trigger an update. The starting orbit follows the existing source-selection and orbit-age rules, including public fallback. Its original epoch remains visible. Each phase separates **Recorded so far** from the **Forecast · remaining phase**. The forecast shows expected completion, drift from the intended date, predicted consumption and exit orbit. Expand **Trajectory & assumptions** to inspect orbital parameters and epochs. Solid history and dashed predictions meet at the source-state boundary when compatible recorded mean-element data exists. You do not need to enter propellant inventory. Without a dated estimate, remaining fuel is unavailable and the nominal forecast assumes planned maneuvers can execute; it does not verify fuel sufficiency. Physical spacecraft inputs such as total mass and propulsion are still needed. Only explicitly recorded executions contribute to recorded progress; past or approved proposals are not proof of execution. The last completed forecast stays visible during updates, with outdated or failure status when applicable. **History and starting-state override** provides optional investigation runs. Forecasting does not approve burns or change saved phase dates. ## Supported Algorithms | Algorithm | Description | Status | | - | - | - | | [SMA Maintenance](/features/planner/sma-maintenance) | Maintain semi-major axis within a tolerance band | Available | | [Orbit Raise](/features/planner/orbit-raise) | Raise to a higher circular orbit, comparing a min-fuel and a fastest option | Available | | [Inclination Change](/features/planner/inclination-change) | Mean-targeted chemical/electric finite plans with a completion deadline | Internal rollout | | [Phasing](/features/planner/phasing) | Fixed-reference chemical/electric phase corrections with terminal-orbit and drift requirements | Available | ## Page Layout The Planner page has two main sections: a **details panel** on the left and a **plan list** on the right. Planner Page ### Toolbar The top bar contains: * **Spacecraft Filter** — multi-select dropdown to filter plans by spacecraft * **Group By** — group plans by Spacecraft, Status, Plan Type, or None * **Time Range** — bidirectional time filter (past and future plans) * **New Plan** — opens the plan creation wizard * **Toggle Panel** — show/hide the plan list ### Plan List The right panel lists all plans matching the current filters. Each row shows the plan reference (`PL-`), status icon, operator-entered name, spacecraft, plan type icon, and creation date. Ground-track control and orbit-raise evaluations reserve the same kind of reference before approval; the reference stays the same in the details panel and after approval. Older records without a reserved reference may show **Reference pending** instead of a truncated internal ID. Hover any element for a tooltip with details. Plans can be grouped by spacecraft, status, or plan type. Each group header shows the count and supports pagination (5 items per page) and collapse/expand. **Status icons:** | Icon | Status | Description | | - | - | - | | Magnifier (indigo) | **Evaluation** | Plan is under review | | Checkmark (green) | **Approved** | Plan has been approved for execution | | Cross (red) | **Rejected** | Plan has been rejected | Click a plan row to load its details in the left panel. ### If plan details cannot load The selected row stays highlighted. The details panel names the plan and explains the failed request. Choose **Retry** to load it again, reselect the same row, or select another plan. The previous plan's details are cleared while loading. Retry only reads the saved plan. If the server reports that verification is no longer valid, follow its recomputation instruction before review or approval; retrying does not bypass that restriction. ## Plan Creation Wizard ### Missing Required Inputs Before computing a plan, supply a complete initial state and its epoch, a finite positive mass from the selected source, and the selected spacecraft's actual propulsion inputs. A TLE supplies an orbit, not a wet mass. The planner does not replace missing thrust, Isp, mass, or force-model data with representative values. If validation names a missing input: 1. Check the selected state and mass source. For propellant budgets, also configure dry mass and verify that wet mass is not below dry mass. 2. Complete the selected thruster's positive thrust and Isp, and the area/coefficient inputs consumed by enabled forces. 3. For attitude-aware electric raising, complete the actual body/panel geometry and optics in [Spacecraft](/features/spacecraft-management#missing-required-inputs-for-calculations); a drag cross-section alone cannot define faceted geometry. 4. Retry the comparison or plan calculation. If approval reports an incompatible older snapshot, generate a new comparison with complete inputs rather than reusing the old approval evidence. Missing estimates remain unavailable; they do not mean zero delta-V or zero propellant. Complete finite-burn vectors include all three components, even when an axis is explicitly zero. Valid positive subsecond durations are preserved. Click **New Plan** to open the plan creation wizard. Most algorithms use the five-step flow below. [Phasing](/features/planner/phasing) uses **Overview → Phasing objective**, saving a reusable intent before computation. ### Step 1: Overview Configure the plan metadata and select the optimization algorithm. Planner Step1 Overview | Field | Description | Constraints | | - | - | - | | **Plan Name** | User-defined name | Required, max 30 characters | | **Description** | Optional notes about the plan | Optional | | **Spacecraft** | Target spacecraft for the maintenance plan | Required — must have at least one orbit solution | | **Thruster** | Propulsion unit for computing burns | Required — must be configured for the selected spacecraft | | **Maneuver Type** | Optimization algorithm to use | Select from supported algorithms | ### Step 2: Initial State Displays the spacecraft's **state** that will be used as the starting point for the optimization, which defaults to latest computed state vector. Users can select a different state vector if desired using the ID dropdown, or initialize the process with the latest **public TLE.** Planner Step2 Initial State ### Step 3: Time Range Define the time window over which the optimizer should plan maneuvers. Planner Step3 Time Range Set the **Start Date/Time** and **End Date/Time** in UTC. The end must be after the start. By default, the start is 3 hours from now and the duration is 3 days. Some algorithms may require a single **Target Date/Time**. ### Step 4: Algorithm Parameters This step varies by algorithm type. See the algorithm-specific documentation: * [SMA Maintenance — Step 4](/features/planner/sma-maintenance#step-4-sma-parameters) * [Orbit Raise — Step 4](/features/planner/orbit-raise#step-4-orbit-raise-parameters) * [Inclination Change](/features/planner/inclination-change) — Mean target, fuel, reserve, availability and finite-burn verification ### Step 5: Review Review the full plan configuration before submission. Planner Step5 Review The review shows all configured parameters in editable summary cards. Click **Create Plan** to submit. For complex plans, the computation may run asynchronously — a progress dialog tracks the job until completion. On success, the new plan appears in the plan list. ## Ground-track control review (internal rollout) Ground-track control results use **Overview → Analysis → Maneuvers**. Overview shows the saved **Action window**, full **Lookahead** and **Replan by** date, with action-window fuel and delta-V separated from future planning costs. These dates are explicitly reviewed during plan creation; one week and one month are not automatic defaults. The **Analysis** dropdown opens Ground-track error by default. You can also select the saved LTAN/LTDN error, **Semi-major axis (SMA)** or **Inclination**, and expand any plot. Every view describes the same saved planned orbit, including the future maneuvers assumed by the lookahead. The chart has one **Action window ends** divider; later coverage is labelled **Lookahead · planning only**. Only applicable saved limits are drawn. SMA uses km and inclination uses degrees. Both orbital channels are labelled **instantaneous (osculating) · GCRF**. Older results may not contain these orbital series; an unavailable channel does not replace them with today's orbit or prevent you from reviewing the saved ground-track/local-time result. **Maneuvers** contains the near-term action-window sequence. **Future maneuvers · planning only** is provisional and excluded from approval and booking. An empty near-term list can still be followed by future maneuvers. Select a near-term maneuver to inspect its saved timing, duration, direction, fuel and delta-V. An unsuccessful result explains why no valid plan was found. Open **Attempted solution · cannot be approved** to inspect any retained attempted maneuvers and candidate costs. These details are read-only. Missing historical details are shown as unavailable; they are never reconstructed or treated as an approved coast plan. ## When the Orbit Is Stale Maneuver optimization needs a **fresh** orbit to plan from. A spacecraft's [orbit age](/features/orbit-age#orbit-age) is measured from its latest [state vector](/features/state-vectors) — the position and velocity at an epoch you provide through orbit determination, an OPM import, or manual entry. When that age passes the workspace's configured [stale level](/features/orbit-age#stale-level), the orbit is **stale**. Because a maneuver is a higher-consequence action than a plot, a stale orbit does not silently block it and does not silently proceed — it asks you to **consciously acknowledge** the risk before the action completes. ### Acknowledging a stale orbit on create and approve The acknowledgment is a deliberate confirmation step, shown separately at the two points where a maneuver acts on the orbit — **creating** a plan and **approving** it for execution. | Action | Where it appears | What it asks | | - | - | - | | **Create a plan** | After you click **Create Plan** on the **Review** step | A confirmation titled **Orbit is stale — create on a stale orbit?**, stating that **This maneuver would be planned from a stale orbit, which may make the result inaccurate**, alongside the orbit's age (`last determined N days ago`) and the stale level it crossed (`exceeds your N-day threshold`). Choose **Create anyway** to proceed, or **Cancel** to stop. | | **Approve a plan** | When you select **Approve Plan** on a plan in **Evaluation** | A confirmation titled **Orbit is stale — approve on a stale orbit?**, stating that **Approving this plan will execute a maneuver computed from a stale orbit, which may be inaccurate**, with the same orbit age and stale-level lines. Choose **Approve anyway** to proceed, or **Cancel** to stop. | Both `N` values are whole days — the spacecraft's actual orbit age and your configured stale level. The acknowledgment is **per action**. Acknowledging at create does **not** carry over to approve: approving the plan asks you to confirm again. This is deliberate — approval is what authorizes the burn, so it always reconfirms the risk in its own right. Approval **re-checks orbit freshness at the moment you approve**, against the spacecraft's latest orbit at that time — not against the orbit the plan was created on. A plan created while the orbit was fresh can still raise the approve-time confirmation if the orbit has since aged past the stale level; conversely, refreshing the orbit before approval clears it. To avoid the prompt entirely, provide a newer [state vector](/features/state-vectors) for the spacecraft, or raise the stale level in **Settings → Orbits → Orbit age**. See [Orbit age](/features/orbit-age#stale-level) for the workspace-wide policy. ### When a spacecraft has no usable orbit A stale orbit can still be planned from once you acknowledge it. A spacecraft that has **no usable orbit at all** is different: there is nothing to plan from, so there is nothing to proceed on. Creating or approving a plan for such a spacecraft replaces the action with an in-place message — **Can't compute — `{spacecraft}` has no usable orbit** — explaining that **There is no usable orbit data for this spacecraft, so this product can't be computed. Add tracking data to continue**, with an **Add orbit data** button that takes you to the spacecraft page to add tracking data. This is never shown as a raw error; the remedy is to add orbit data, then create the plan. ## Plan Details Select a plan from the list to view its details in the left panel (visible in the [page screenshot above](#page-layout)). ### Header The header shows the plan name, plan type icon, and a more menu with actions: | Action | Description | | - | - | | **Export** | Download the plan as an OCM file | | **Delete** | Delete the plan with confirmation | ### Plan Information | Field | Description | | - | - | | **Spacecraft** | Target spacecraft (with colored icon) | | **Delta-V** | Total velocity change across all maneuvers (m/s) | | **Delta-Mass** | Total propellant consumed (auto-converts kg/g) | | **Duration** | Total burn time | | **Creation Date** | When the plan was created (UTC) | | **Execution Date** | Planned start time for the first maneuver (UTC) | | **Status** | Evaluation, Approved, or Rejected | ### Status Actions Plans in **Evaluation** status can be approved or rejected using the action buttons in the header: * **Evaluation** → **Approved** (plan is ready for execution) * **Evaluation** → **Rejected** (plan is discarded) ### Tabs **Analysis** — Algorithm-specific visualization showing how the computed maneuvers maintain the target orbital parameter. See [SMA Maintenance Analysis](/features/planner/sma-maintenance#analysis-tab) for details. **Burns** — Lists each individual maneuver in the plan: | Field | Description | | - | - | | **Epoch** | Maneuver start time (UTC) | | **Duration** | Burn length | | **Delta-V** | Velocity change components and magnitude (m/s) | | **Delta-Mass** | Propellant consumed | **Activity** — Timeline of plan events (creation, approval, rejection) with user attribution and timestamps. ## Related Pages * [SMA Maintenance](/features/planner/sma-maintenance) — SMA maintenance algorithm details * [Burn Plan](/features/burn-plan) — View and manage individual spacecraft maneuvers * [Orbit age](/features/orbit-age#stale-level) — The workspace-wide stale level behind the create- and approve-time acknowledgment * [Core Concepts](/platform-overview/core-concepts) — Foundational orbital mechanics concepts # Inclination Change Source: https://docs.valar.space/features/planner/inclination-change Plan chemical or electric inclination changes within an explicit deadline and propellant constraints The finite inclination planner is available through **Operations → Planner → New Plan** for enabled accounts. Its initial rollout is internal-only. Accounts without access retain their existing chemical inclination workflow. The Operations access check requires the planner to be deployed, the Operations environment, and the operator's release eligibility. It does not grant planning permissions: API authorization and spacecraft ownership remain separate checks. ## Configure a plan 1. Select the spacecraft, an available chemical or electric thruster, and **Inclination Change** in Overview. 2. Choose the initial orbit and mass source using the existing Initial State step. 3. Set the earliest start and **Completion deadline (UTC)**. The optimizer must complete within this interval; it cannot place a burn before the start. 4. Enter the **Target mean inclination (GCRF)** and its tolerance. Mean inclination removes the periodic variation present in instantaneous orbital elements. 5. Set the propellant cap, required reserve, maximum duty fraction, minimum coast between burns, sunlight restriction and any UTC blackout intervals. 6. Review the configuration and create the plan. Computation produces a proposal for the existing review/approval workflow. Blank maximum propellant uses the selected initial state's available propellant after dry mass and reserve. The selected device's uninterrupted-burn limit applies independently of duty and coast settings. Duty is measured over one initial orbital period. Blackouts include their start and exclude their end. The finite planner preserves the entered target's decimal precision in review and submission. Check the target together with its tolerance before creating the plan. Creation is asynchronous: the accepted request is not yet a computed proposal. The progress dialog follows that request's actual job outcome, including a useful failure message when computation cannot finish. If the finite capability becomes unavailable after a proposal was created, an owned, replay-verified historical plan can still be read for review. A new finite request or approval is refused with HTTP 422 and error code `FINITE_INCLINATION_UNAVAILABLE` (and stable code `maneuver.finite_inclination.unavailable`); neither request starts computation or posts operational burns. This is different from a 403 permission denial, a 404 for an unknown or inaccessible plan, and a planner job failing to find a feasible schedule. A failed replay verification still requires recomputation before review. The legacy chemical inclination workflow remains separate. ## Read the result **Inclination plan verification** shows the target and achieved mean inclination, instantaneous inclination, propellant, remaining reserve, firing time, elapsed time, deadline and actual achieved epoch. The search disclosure records the selected node-window policy, reference cost, evaluation count and assumptions. The context plot shows instantaneous inclination. Its periodic oscillations are not the mean-target achievement test. Firing time includes only thrust intervals; elapsed time includes waiting and coasting. Plan **ΔV** is the sum of positive burn costs in **m/s**, calculated from each verified burn's mass loss using the rocket equation. Burn components are signed in the saved RTN frame; burns in opposite directions do not cancel the plan's fuel cost. The total and individual displayed values are rounded independently. **Initial State** shows the source selection retained by the producing run, including an explicitly selected state vector (for example, SV-128), its mass-source policy, and the frozen epoch, frame and mass. A latest-state selection is labelled as the run-time policy, not resolved again from the spacecraft today. Older plans can retain physical inputs without their original source selection. They show **Not retained in this plan** for that selection, while the recorded epoch, frame and mass remain available. Recompute to record a new selection; this does not recover or rewrite the historical plan's missing provenance. The result is the best verified feasible schedule found within the reported search, not proof of a global optimum. An unfinished or unverified trajectory is not presented as a completed plan. Changing physical inputs or burn segments requires recomputing the plan so its verification remains associated with the actual saved schedule. ## Applicability The current method supports near-circular LEO: mean eccentricity at most 0.01, mean perigee at least 200 km, mean semi-major axis below 7378.137 km, and corrections up to 5°. It does not deliberately raise or lower the orbit to reduce plane-change cost. Natural perturbations continue to act. The model uses the frozen spacecraft's isotropic cross-sections and does not infer missing battery, thermal or slew-propellant behavior. Review the assumptions and the actual finite-burn sequence for the selected spacecraft. Existing approval and orbit-freshness requirements still apply; computation does not approve burns. See [Planner](/features/planner) for the shared workflow and [Burn Plan](/features/burn-plan) for reviewing individual operational maneuvers. # Orbit Raise Source: https://docs.valar.space/features/planner/orbit-raise Raise a spacecraft to a higher circular orbit and compare a min-fuel and a fastest option > For the complete documentation index, see [llms.txt](/llms.txt). Orbit Raise plans a low-thrust transfer that raises a spacecraft from its current orbit to a higher **circular** target altitude. The platform always computes **two options** for the same target — a **Min-fuel** option and a **Fastest** option — so you can weigh propellant against time before committing. You review both side by side and **approve** the one you want; the approved option becomes a normal maneuver plan in the existing approval and execution lifecycle. This page documents the Orbit-Raise-specific configuration and the two-option comparison. For the shared wizard steps (Overview, Initial State, Time Range, Review) and general Planner functionality, see the [Planner overview](/features/planner). **Route:** `/maneuvers/planner` ## Creating a raise In the Planner, click **New Plan**, and on the **Overview** step choose **Orbit Raise** as the **Maneuver Type**. The wizard's five steps are the same as every other plan (**Overview**, **Initial State**, **Time Range**, **Parameters**, **Review**); only the **Parameters** step is Orbit-Raise-specific, and there is no option picker — both options are always computed. * On **Initial State**, the raise starts from the spacecraft's latest computed state vector, or you can select a different [state vector](/features/state-vectors) or initialize from the latest **public TLE** — exactly as for other plans. * On **Time Range**, set the window (in UTC) within which the raise may run. ### Step 4: Orbit Raise Parameters Configure the circular target the raise should reach and the propellant it is allowed to spend. | Field | Description | Unit | Constraints | | - | - | - | - | | **Target altitude** | The circular altitude the raise should reach | km | Must be > 0 | | **Position tolerance** | How close to the target altitude the final orbit must settle | km | Must be > 0. Default: 2 km | | **Propellant available** | The spacecraft's available propellant (read-only) | kg | Read-out only — from the spacecraft's configuration | | **Max fuel to be used** | The most propellant this raise is allowed to spend | kg | Must be > 0 and **≤ Propellant available**. Defaults to the full available propellant | The **Max fuel to be used** value is a cap on the whole raise. It defaults to the full available propellant and cannot exceed it — if you lower it, both options are still computed, but a computed option is only **approvable** when it fits within the cap (see [Approving a raise](#approving-a-raise)). When you reach **Review** and click **Create Plan**, the raise launches and appears as a single plan in **Evaluation** while its two options are computed. ## Optional mean LTAN targeting When local-time targeting is enabled for your account, select **Target mean LTAN** inside **Orbit Raise**. It is currently an internal rollout for the existing chemical/electric near-circular LEO capability. Ordinary exact-target raises remain available when this option is off. Enter exactly three problem inputs: | Field | Meaning | | - | - | | **Target LTAN (HH:MM:SS)** | Mean ascending-node local solar time. Seconds and fractional seconds are retained; `10:30` is also accepted. | | **Minimum allowable mean SMA (km)** | Lower geocentric mean semi-major-axis limit throughout thrust and acquisition coast. | | **Maximum allowable mean SMA (km)** | Upper limit for the same complete phase. The maximum must exceed the minimum. | The acquisition tolerance is fixed, read-only **±1 second at full phase completion**. There is no second exact-altitude target, editable tolerance, drift limit or transfer-wide clock band in this compact form. SMA is measured from Earth's centre, not altitude above the surface. Both bounds must be finite and within the supported 6,498.137–8,378.137 km LEO range. Include the inherited initial mean SMA in the range: the planner will not widen it to admit an initially outside state. The planner selects an economical reachable arrival orbit within the bounds and accounts for accumulated LTAN change during both thrust and coast. It may stop thrusting before LTAN reaches the target and let a real final coast complete acquisition within the planning window. The ±1-second condition applies at the end of that coast, not throughout the transfer or at the last burn. Nonzero residual drift is allowed; this is acquisition, not ongoing maintenance. Configure the selected spacecraft's maneuver capabilities and complete physical inputs before computing. The review lists **Last burn ends**, **Full phase completion**, arrival local time/SMA, residual drift, interval margins and the numerical allowance. Min-fuel and Fastest compare only candidates meeting the same authored requirements. A bounded search that finds no qualified campaign is reported as unresolved, rather than proof that the mission is impossible. Unsupported hardware or missing evidence must be resolved before approval; requirements are never relaxed to make a cheaper plan pass. The same requirement fields are available in enabled Operations and Mission Analysis Orbit raise phases. A following phase inherits the achieved physical orbit, epoch and remaining mass at full phase completion. Review, saved phases and **Modify** retain the target, tolerance and SMA range. Historical extended requests use a labelled historical editor that preserves their separate LTAN/LTDN clocks, applicability, orbit limits and resource requirements. They are not silently converted to compact inputs or relabelled as new results. ## Comparing the two options Once both options are ready, the plan detail shows them side by side as an equal-weight **Min-fuel** / **Fastest** selector. Each option lists the same figures so you can compare them directly: | Figure | Description | | - | - | | **ΔMass** | Propellant this option would spend (kg) | | **Duration** | How long this option's raise takes | | **Propellant left** | Propellant remaining after the raise (available − ΔMass) | Select the option you prefer — the selected option is emphasized — and a single primary **Approve ** action (for example, **Approve Min-fuel**) commits it. While the two options are still computing, each shows its own progress (**Queued**, then **Computing**), and each settles to **Ready** or **Failed** independently — if one option fails, the other stays usable. Full velocity-change (Delta-V) figures appear on the approved plan's [Plan details](/features/planner#plan-details) once you approve an option. ### When the two options coincide For some raises the min-fuel and fastest solutions are the same. In that case the detail shows a single plan with a plain note that **Min-fuel** and **Fastest** coincide for this raise, and you approve that one plan — there is no separate comparison to make. ## Approving a raise Approving an option turns it into a definitive maneuver plan and moves it into the existing lifecycle as **Approved**, exactly like any other plan. From there the standard **Approve / Reject / Delete / Export** actions and [Plan details](/features/planner#plan-details) apply, and the option you did not approve is discarded. Approval runs a final propellant check. If the option you approve would spend more than the cap, or the propellant use cannot be validated, the raise is **not** saved and an inline message explains why: | Message | Meaning | | - | - | | **Exceeds the max fuel to be used — this raise would spend more propellant than the cap** | The option's propellant use is above the **Max fuel to be used** cap. Raise the cap (up to the available propellant) or choose a cheaper option, then approve again. | | **Couldn't validate the fuel use — please retry** | The propellant check could not complete. Approve again to retry. | ## When a raise can't reach the target If neither option can reach the target — for example, the window is too short or there is not enough propellant — the detail does not show a plan with a disabled Approve. Instead it shows a plain message that the target **Can't reach this target**, naming the limit that blocks it (propellant or time) and telling you to **modify the target, window, or max fuel and try again**. The panel offers two actions: * **Modify** — reopens the New-plan dialog so you can adjust the target, window, or **Max fuel to be used**. * **Discard** — dismisses the raise. ## Eligibility Some spacecraft cannot be raised — for example, one with no propulsion configured, or more than one thruster. When you configure a raise for such a spacecraft, the dialog shows an inline message that **This spacecraft can't be raised yet**, lists the specific reason(s), and blocks **Create Plan** until they are resolved. ## Related Pages * [Planner](/features/planner) — Planner overview, shared wizard steps, and plan details * [State Vectors](/features/state-vectors) — The initial state a raise starts from * [Burn Plan](/features/burn-plan) — View and manage individual spacecraft maneuvers * [Core Concepts](/platform-overview/core-concepts) — Foundational orbital mechanics concepts # Phasing Source: https://docs.valar.space/features/planner/phasing Save a fixed phase objective, compute finite chemical or electric corrections, and review orbit, drift and resource achievement. Phasing changes one spacecraft's position along its orbit relative to a saved reference. It accounts for the entry maneuver, drift, recovery and measurement coast together. The result must meet the phase target, terminal orbit and residual relative drift on the same assessed trajectory. ## Create and save an objective In **Operations → Planner → New Plan**, select a spacecraft and thruster, choose **Phasing**, review **Initial State** to choose the operational TLE/state vector and mass, then continue to **Phasing objective**. Operations Flight plans can also link a saved Phasing intent to a phase. In Mission Analysis, select **Add Phasing** in the existing Flight plan editor. Choose a reference mode: | Mode | Meaning | | - | - | | Signed change | A signed advance or delay relative to the anchored unmanoeuvred trajectory. Complete relative laps are retained: 390° is different from 30°. | | Reference offset | An offset from a versioned virtual or leader trajectory, modulo one revolution. The result identifies the selected direction and winding. | Positive phase is ahead in the direction of travel. It does not prescribe the first burn direction. The authoritative observable is mean phase in degrees, not true anomaly, ground-track longitude or three-dimensional separation. Supply the phase tolerance, earliest burn and latest completion, temporary orbital excursion limits, terminal mean-orbit tolerances, permitted plane mismatch, residual drift bound and measurement-coast duration. Distances identify their representation: mean SMA and osculating perigee/apogee radii are different requirements. The selected catalog device supplies thrust, Isp and its maximum continuous firing duration. Declare remaining ignitions, minimum command, timing precision, restart gaps, propellant cap/reserve, rolling duty, sunlight eligibility and blackouts. Prograde and retrograde settings declare the ability to track those RTN directions throughout a firing. Identify the source of these command limits; the editor does not infer mission values. **Save Phasing intent** retains the target and reference. Select it from **Saved Phasing intent** when reopening. Computation uses the saved revision shown in the panel; save edits before computing them. Expand **Saved reference state and resources** to inspect the frozen GCRF/UTC state, its source, mass, and selected propulsion. Changing the controlled-state selection for a later computation does not replace the saved reference. ## Keep the target when replanning A saved 10° correction with 4° already gained still targets 10°, leaving 6° to achieve. It does not request another 10° from the updated state. For a signed correction at a later entry epoch, provide continuous unwrapped phase history, the matching epoch and its evidence source. A wrapped state alone cannot prove completed relative laps, and a proposed burn is not evidence that it executed. Operations retains its existing future, whole-second planning-window requirement; history must be resolved to the selected planned-start state. Finite commands retain their finer declared timing precision. Select **Explicitly replace the saved reference** when revised intent should adopt a new anchor. A new correction or changed reference is explicit and versioned. Older proposals remain tied to their producing snapshots. ## References and terminal orbit The default is an unmanoeuvred reference from the resolved selected state. Mission Analysis uses its explicit analysis initial orbit and frozen assets. The controlled spacecraft always enters a composed phase with the preceding phase's achieved state, epoch and remaining mass. Advanced reference records use GCRF/UTC state data, source/version, model/data identity, coverage and maneuver assumptions. A leader ephemeris needs ordered knots, an interpolation-gap limit and declared thrust-free coverage of the measurement interval. Missing coverage is not extrapolated, and unknown future leader burns are not assumed. An unavailable saved model/data revision is reported rather than silently replaced. By default, the required terminal mean orbit follows the phase reference at arrival. A separate **Terminal orbit reference** can specify another return orbit. All authored phase, size/shape, plane and residual-drift requirements still apply together. ## Review the result The review shows the saved target, selected branch/winding, achieved phase and error, residual drift, terminal orbit residuals, propellant used, remaining propellant and required reserve. **Complete elapsed time** includes coasts and the measurement interval; **Total firing time** counts only actual firings. In the plan **Overview**, **ΔMass (spacecraft)** is signed (negative for fuel spent), while **Fuel consumed** is the positive amount spent. Both use kg for values at least 1 kg and g for smaller values, with three decimal places; these come from the producing Phasing run, not a rounded command aggregate. **Initial State** shows the selected source/display ID and mass source retained with that plan, alongside the run-frozen epoch, mass and saved reference source. The reference source identifies the target anchor; after replanning it may differ from the selected initial state. **Older-plan limitation:** plans computed before initial-state selection was retained can still show their frozen physical state and fuel evidence, but the selected source, mass source and State Vector display N/A when the original selection is absent. This update does not backfill that historical ID from the reference anchor, plan metadata or the spacecraft's current state. A new computation records its own selection; it cannot recover which record an older run selected. **Latest state vector (at run time)** means a retained latest-state selection policy, not a known record ID. N/A for a missing or unfinished result is not a measured zero; an actual zero is shown as 0.000 g. Use the aligned charts to inspect unwrapped phase or selected-branch error, mean SMA, mean eccentricity and osculating perigee/apogee. Firing boundaries and authored limits remain visible. Phase tolerance is an endpoint condition; excursion limits hold along the full trajectory. Outcomes distinguish unsupported input/capability, conflicting requirements, an unsuccessful bounded search and insufficient numerical qualification. A verified candidate can remain usable when further optimization reaches its budget. Minimum propellant is the objective, not a promise of a global optimum. Operations approval uses the retained finite commands through the existing review lifecycle. Changed or unqualified proposals cannot be approved/exported. A coast-only achievement creates no artificial burns. Mission Analysis results remain isolated and cannot be approved as operational proposals. Initial and terminal mean orbits cover near-circular Earth LEO through 2,000 km mean-SMA altitude and eccentricity 0.01. Temporary excursions have separate authored bounds and model-applicability checks. Numerical achievement is modeled evidence; it does not establish indefinite spacing, rendezvous or conjunction clearance. # SMA Maintenance Source: https://docs.valar.space/features/planner/sma-maintenance Maintain semi-major axis within a tolerance band using automated maneuver planning > For the complete documentation index, see [llms.txt](/llms.txt). SMA (Semi-Major Axis) Maintenance is a station-keeping algorithm that computes a sequence of maneuvers to keep a spacecraft's semi-major axis within a defined tolerance band. It corrects for natural orbital decay caused by atmospheric drag, gravitational perturbations, and other forces. This page documents the SMA-specific configuration. For the shared wizard steps (Overview, Initial State, Time Range, Review) and general Planner functionality, see the [Planner overview](/features/planner). ## SMA maintenance in Flight Plan When Flight Plan is available for your account, select a spacecraft and **Add phase**. Choose **SMA maintenance · Electric**, **Chemical** or **Osculating**, select its thruster, and enter **Reference SMA (km)** and **Allowed deviation (± km)**. Save the phase; reopen **Phase overview** to edit it. Timing belongs to the waypoints. The selected thruster supplies its existing physical limits. Choose **Compute maneuver plan** and supply an explicit UTC planning window. The request uses the saved phase revision and the existing operational starting orbit. Review progress or a reported failure, then open the resulting proposal under **Maneuver plans**. Review its retained inputs, planned burns, timing, consumption and **SMA Analysis**. Approve or reject using the existing permitted actions. Open approved burns under **Burns & analysis** to review the stored record and available [OD evidence](/features/burn-plan#review-records-in-flight-plan) in the same workspace. Later phase edits affect future computations; earlier proposals retain their original revision and inputs. Approval and elapsed dates do not confirm execution. This workflow uses the existing SMA maintenance algorithms and their parameter semantics. Standalone Planner configuration is described below. ## Step 4: SMA Parameters Configure the target semi-major axis and tolerance band for the maintenance algorithm. Planner Step4 Sma Parameters | Field | Description | Unit | Constraints | | - | - | - | - | | **Nominal SMA** | Target semi-major axis value | km | Must be > 6,371 km (Earth's radius). Auto-populated from the spacecraft's current orbit. Up to 3 decimal places. | | **Threshold SMA** | Tolerance band around the nominal value | km | Must be > 0. Default: 10 km. Up to 3 decimal places. | The optimizer will compute maneuvers to keep the semi-major axis within **Nominal ± Threshold** km. ### SMA Plot Below the input fields, a real-time plot shows the spacecraft's semi-major axis over the configured time range. The plot displays: * **Spacecraft SMA** — the osculating semi-major axis line * **Nominal line** — solid gray reference at the target value * **Threshold lines** — dashed red lines at upper and lower bounds * **Tolerance zone** — shaded area between the threshold lines The plot updates as you change the nominal and threshold values. A reference-frame indicator badge appears next to the plot title showing the inertial frame the semi-major axis is computed in (e.g., `GCRF`). Hover the badge for the full frame name; click **Learn more** to open the [reference frame catalog](/platform-overview/reference-frames). The badge also appears on the Inclination and Keplerian-element charts elsewhere in the SMA Maintenance planner views — they all share the same propagation frame. ### Auto-Population When a spacecraft is selected, the **Nominal SMA** field is automatically populated with the spacecraft's current semi-major axis value (extracted from the latest Keplerian elements). You can override this value manually if needed. ## Analysis Tab When viewing an SMA Maintenance plan in the details panel, the **Analysis** tab displays a chart showing how the computed maneuvers maintain the semi-major axis within the tolerance band (visible in the [Planner page screenshot](/features/planner#page-layout)). The chart shows: * **Osculating SMA** — the spacecraft's semi-major axis over the plan time range, including the effects of each computed maneuver * **Nominal reference** — solid line at the target SMA value * **Threshold bounds** — upper and lower bounds with shaded tolerance zone The Analysis chart carries the same [reference-frame indicator badge](#sma-plot) as the wizard-step preview — the propagated SMA is expressed against the same inertial frame. This visualization confirms that the optimizer successfully keeps the SMA within the defined tolerance band throughout the plan duration. ## Key Concepts ### Tolerance Band The range **\[Nominal SMA - Threshold, Nominal SMA + Threshold]** defines the acceptable operating window. When the spacecraft's SMA drifts toward a threshold boundary, the optimizer schedules a corrective maneuver to push it back toward the nominal value. ### Semi-Major Axis The semi-major axis defines the size of an orbit — it is half the longest diameter of the orbital ellipse. For a circular orbit, it equals the orbital radius. For more details, see [Core Concepts](/platform-overview/core-concepts). ## Related Pages * [Planner](/features/planner) — Planner overview, shared wizard steps, and plan details * [Burn Plan](/features/burn-plan) — View and manage individual spacecraft maneuvers * [Core Concepts](/platform-overview/core-concepts) — Foundational orbital mechanics concepts # Usage reporting Source: https://docs.valar.space/features/reporting-usage Review created events and saved bookings for AOI overflights and ground-station passes. Open **Reporting → Usage** in **Operations**. Select the last 7, 30, 90 or 365 UTC dates and optionally select spacecraft. Without a spacecraft filter, the report includes historical activity from archived spacecraft. ## Event activity The Events section shows separate totals and daily charts for: | Metric | What counts | | - | - | | AOI events created | Published AOI overflight forecast records | | AOI events booked | Saved AOI overflight bookings | | GS passes created | Published ground-station pass candidates | | GS passes booked | Saved ground-station pass bookings | Created events use their creation/publication date. Bookings use the date you saved them. Neither uses the scheduled date of the overflight or contact. A booking does not establish that an observation or contact was executed. AOI and ground-station reporting follow the same rules. Refreshing forecasts or deleting their source records does not subtract historical usage. Newly published replacement forecasts add creation activity, so these counts are not counts of unique physical encounters. Repeated requests for an existing booking and its archive copy do not add another booking. ## Reading historical coverage Each metric states whether its history covers the selected period. **Partial history** means the displayed total is a subtotal starting at the shown UTC time; earlier activity is unavailable. A partly tracked first day is marked **partial** in the chart. Dates before tracking began are not plotted as zero. **No activity** means tracking was available but recorded nothing for your selection. **History unavailable** means the report cannot establish activity for that period. A failed request shows a separate error and **Retry** action. # Delete a spacecraft Source: https://docs.valar.space/features/spacecraft-deletion Permanently delete an archived spacecraft — what it destroys, who can do it, and why it cannot be undone > For the complete documentation index, see [llms.txt](/llms.txt). Deleting a spacecraft is **permanent and terminal. There is no undo.** The spacecraft's data is destroyed and cannot be recovered — not by you, and not by VALAR support. Archiving is the reversible action; deletion is not. Delete a spacecraft only when you are certain it should cease to exist — for example, to clean up a duplicate craft created by mistake. **Route:** `/spacecraft` → **Danger Zone** ## Before you can delete: archive first A spacecraft must be **archived** before Delete becomes available. On an active spacecraft the Delete action is shown but disabled, with a note that the craft must be archived first. This is deliberate: it puts a reversible step (archiving, which you can undo with **Restore**) in front of an irreversible one. Archive the spacecraft from the [Danger Zone](/features/spacecraft-management#danger-zone) first; then return to delete it. ## Who can delete Deletion requires an authority that is **granted separately** from the authority to edit a spacecraft — being able to change a craft's configuration does not let you delete it. If you do not see a Delete action in the Danger Zone of an archived spacecraft, you do not hold that authority. Deletion is an **interactive, signed-in action only**. It is **not available to API keys or automated integrations** — a spacecraft can only be deleted by a person, from the app. ## The impact check: what you are consenting to Before you confirm, the deletion dialog shows you **how many records of each kind of data will be destroyed** with the spacecraft — its measurements, orbit solutions, residuals, state vectors, maneuvers, and every other kind of record attached to it — with a total. **Those counts are exactly what you are consenting to destroy:** what the dialog lists is what dies with the craft. If the spacecraft has no attached data — the ordinary case for a duplicate created by mistake — the dialog tells you so, and only the spacecraft record itself is removed. That is a normal outcome, not a warning. ## Confirming: type the spacecraft's ID To confirm, you type the spacecraft's **ID** — not its name. The dialog shows you the ID to type. The ID is used rather than the name because two spacecraft can share a **name** but never share an **ID**. Cleaning up a duplicate — two craft with the same name — is the exact case this feature exists for, and the name would confirm nothing. The Delete button stays disabled until what you type matches the spacecraft's ID exactly. ## What happens, and what survives Deletion is **synchronous**: it happens the moment you confirm, not on a background queue. When it completes, the spacecraft is gone from every list and selector, and you are returned to the spacecraft overview. The only thing that survives is an **internal audit record** VALAR keeps: who deleted the spacecraft, when, and how many records of each kind were destroyed. This is a record *that* the deletion happened — it is **not a copy of the data, and it cannot restore anything**. ## Where deletion works Deletion behaves identically in **Operations** and in **Mission Analysis**. Deleting acts only on the spacecraft in the environment you are currently working in. # Spacecraft Lookup Source: https://docs.valar.space/features/spacecraft-lookup Find a spacecraft by NORAD, COSPAR, name, or external key, then reference it by id everywhere else in the API > For the complete documentation index, see [llms.txt](/llms.txt). Every VALAR API endpoint that acts on a spacecraft identifies it by its VALAR `id` — a UUID assigned when the spacecraft is created. This page explains how to find that `id` from an identifier you already hold — a NORAD number, a COSPAR designator, a name, or your own external key — how to reference a spacecraft once you have its `id`, and the two errors you meet when a reference is wrong. ## Finding a spacecraft To resolve an identifier to a spacecraft `id`, call `GET /operations/spacecraft` with one or more lookup filters. Each filter matches a single spacecraft attribute, and the endpoint returns the spacecraft that match **every** filter you supply. | Filter | Matches | Matching rule | | - | - | - | | **`noradId`** | The spacecraft's NORAD catalog number | Exact string match. Not numerically normalised — leading zeros are significant. | | **`cosparId`** | The COSPAR international designator | Exact string match. | | **`name`** | The spacecraft's display name | Exact match, but **case-insensitive**. | | **`externalKey`** | Your caller-assigned [external key](/features/spacecraft-management#external-key) | Exact string match. | The filters combine with **AND** — supplying more than one narrows the result to spacecraft that match all of them at once. Supplying none returns your full spacecraft list. `name` is the only case-insensitive filter; `noradId`, `cosparId`, and `externalKey` are case-sensitive exact matches. For example, to resolve the NORAD id `25544` to a spacecraft: ``` GET /operations/spacecraft?noradId=25544 ``` The response is your standard paginated spacecraft list, filtered to the matches. Read the `id` of the returned spacecraft and use it for every subsequent call. ## Resolve once, then reference by id A lookup gives you the spacecraft's `id` — a UUID. Use that `id` for every other call that targets the spacecraft: fetching it, importing state vectors, planning maneuvers, and so on. Resolve once and reuse the `id`; you do not repeat the lookup on every request. ### Path parameters accept only a UUID Wherever an endpoint names a spacecraft `id` in its path — for example `GET /operations/spacecraft/{id}` — that path parameter accepts **only** a VALAR UUID. Supplying a NORAD id, a COSPAR id, or a spacecraft name in that position is a malformed request and returns **400**, not 404: ```json theme={null} { "status": 400, "error": "VALIDATION_ERROR", "message": "Invalid spacecraft ID format" } ``` A non-UUID in a spacecraft-`id` path is a **400** (a malformed request), not a **404** (a missing resource). If you hold a NORAD id, COSPAR id, name, or external key, resolve it to the `id` with the [lookup](#finding-a-spacecraft) above first, then call the id-keyed endpoint. ## When a reference cannot be resolved When you supply a spacecraft reference that VALAR cannot resolve to a spacecraft in your organization, the endpoint returns a uniform **404** body with three fixed fields: ```json theme={null} { "status": 404, "error": "SC-4040", "message": "Spacecraft with identifier 'PARTNER-SAT-001' not found" } ``` The `status` is always `404`, the `error` code is always `SC-4040`, and the `message` echoes back the reference you supplied — and nothing else. A reference that names a spacecraft in **another organization** returns exactly the same 404 as a reference that names **nothing at all**. The two are indistinguishable by design: VALAR never confirms the existence of anything outside your organization, so the response cannot be used to probe another organization's fleet. ### Operations versus multi-spacecraft reads The 404 above is how a single-spacecraft **operation** reports an unresolvable reference — the whole request fails. A **multi-spacecraft read** handles the same condition differently: rather than failing, it returns **200** and names each unresolvable reference in an `unresolvedSpacecraftReferences` array, returning the results for the references that did resolve. | Request kind | An unresolvable reference produces | | - | - | | **Single-spacecraft operation** (for example `GET /operations/spacecraft/{id}`) | **404** with the uniform body above — the request fails | | **Multi-spacecraft read** (`GET /operations/state-vectors`, `GET /operations/measurements`) | **200** — the reference is named in `unresolvedSpacecraftReferences`, and the rest of the results are returned | Same underlying condition, deliberately different contract. For the multi-spacecraft read behavior, see [State Vectors](/features/state-vectors#unresolved-spacecraft-references) and [Viewing Measurements](/features/measurements-data#unresolved-spacecraft-references). ## Related Pages * [Spacecraft](/features/spacecraft-management): Manage your fleet and assign the external key you can look a spacecraft up by. * [State Vectors](/features/state-vectors): Read orbit solutions, including the unresolved-reference report on multi-spacecraft requests. * [Viewing Measurements](/features/measurements-data): Read measurement data, including the unresolved-reference report on multi-spacecraft requests. * [API Keys](/features/api-keys): Create the keys that authenticate these API requests. # Spacecraft Source: https://docs.valar.space/features/spacecraft-management Configure and manage your satellite fleet — identifiers, mass, drag and SRP, geometry, and components > For the complete documentation index, see [llms.txt](/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` ## Catalogue identifiers In **Identifiers**, search the spacecraft catalogue by name, NORAD number or COSPAR designator and select your spacecraft. VALAR fills both catalogue identifiers; your display name remains editable. Catalogue selection does not require available orbital elements. For a planned spacecraft or one awaiting catalogue assignment, check **This spacecraft is not yet catalogued**. This disables lookup and leaves both identifiers empty. You can later edit Identifiers, uncheck the option and select the catalogue entry while retaining the spacecraft's configuration and history. Changes to an existing spacecraft take effect when you save. Existing spacecraft are linked automatically where their identifiers unambiguously match the catalogue during migration. Unresolved records keep their current identifiers and remain usable; missing identifiers alone do not mark them as not yet catalogued. Lookup shows the source catalogue's update time and indicates when freshness cannot be verified. VALAR checks for new publications hourly and retains the last valid catalogue during provider outages. ## 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. Spacecraft ## Page Header 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. | The header is read-only — lifecycle changes happen in the [Danger Zone](#danger-zone). ## 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. This selector lists your **full roster** — both active and archived spacecraft — so the Spacecraft page is the one place you can still reach an archived craft. Selecting an archived spacecraft shows an **Archived** badge in the [page header](#page-header); open it to review its configuration or [restore](#restoring-a-spacecraft) it. The Spacecraft page is the **only** place archived spacecraft remain selectable. Every other spacecraft picker and filter across the app — orbit determination, conjunctions, maneuver planning, ground track, reporting, plotting, and imports — lists **active spacecraft only**, in both the **OPERATIONS** and **MISSION\_ANALYSIS** environments. When a picker has no active spacecraft to offer, it reads **"No active spacecraft"**. ## 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 uses a single **Edit** control for the catalogue association, display name and colour. ## Identifiers Section The Identifiers strip carries four fields: | Field | Description | | - | - | | **Name** | The spacecraft's display name. Required. | | **NORAD ID** | Public catalogue reference, filled from your selection and read-only. | | **COSPAR ID** | International designator from the same catalogue entry, when available. Read-only. | | **Colour** | Colour used to identify this spacecraft throughout the app. | **Validation:** A blank or whitespace-only **Name** shows the message `"Name is required."` inline and blocks the save. New spacecraft also require a catalogue selection or an explicit **not yet catalogued** choice. ### NORAD catalog number The **NORAD ID** is the public catalogue number VALAR uses to fetch the spacecraft's orbit. Select it through the catalogue lookup. For spacecraft without an assignment, choose **This spacecraft is not yet catalogued**. Legacy API integrations can continue supplying numeric identifiers directly. The accepted range is **1–999999**; use the full number rather than an Alpha-5 representation such as `B1234`. Reserved analyst numbers (`70000`–`99999`) can remain on existing records but are not queried from CelesTrak. Six-digit objects can use GP mean elements from CelesTrak or Space-Track through VALAR's orbit workflows, even when the public orbit has no TLE text. TLE fitting and generation remain available subject to the [export format's catalog-number limits](/features/tle-generation#six-digit-catalog-numbers). Catalogue selection itself is possible even when no orbital elements are available. ## External key The **external key** is an optional identifier you assign to a spacecraft through the VALAR API, alongside its NORAD and COSPAR ids. It lets you reference a spacecraft by an identifier from your own systems — and, because you choose it, it works for a spacecraft that has no public catalog id yet. An external key is a string of **1 to 64 characters**, using letters, digits, and the characters `.` `_` `:` `-`. **Assigning the key.** You can set the external key while it is unset — when you register the spacecraft or on a later update. Each key must be unique within your organization: if another spacecraft in your organization already holds that key, the assignment is rejected with a **409** conflict. **The key is immutable once set.** Once a spacecraft has an external key, that key cannot change: * Supplying the **same** value again is accepted and changes nothing. * Supplying a **different** value, or **clearing** the key, is rejected with a **409** conflict (error code `SC-4094`) — *"The external key is immutable once set and cannot be changed or cleared."* Assign the external key deliberately — you cannot change or remove it later. Choose a value from your own systems that will stay stable for the life of the spacecraft. **Referencing a pre-launch spacecraft.** A spacecraft that has not launched yet often has no NORAD or COSPAR id to reference it by. Assign an external key when you register it, and you can then find and reference that spacecraft by the key immediately — see [Spacecraft Lookup](/features/spacecraft-lookup#finding-a-spacecraft). ## 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](/getting-started/first-spacecraft). 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² | The Mass card shows configuration only — current mass and propellant remaining are not displayed. **Inertia tensor display:** the matrix renders the three moments on the diagonal and a muted `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."` | The card surfaces these messages inline and stays in edit mode until you correct or clear all three moments. ### 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. ## Missing Required Inputs for Calculations A saved spacecraft record is not proof that every calculation has the physical inputs it needs. If a calculation names a missing mass, area, coefficient, or geometry field, edit the corresponding card, supply the spacecraft's actual value, save, and retry. * Numerical propagation requires a finite positive mass from the selected supported mass source. Dry mass is not a substitute for wet mass; a public TLE does not provide spacecraft mass. * Enabled drag/SRP models require their actual area and coefficient inputs. A force explicitly disabled by the selected profile does not need unused inputs. VALAR does not infer one area from another or manufacture a box from a scalar cross-section. * Faceted calculations require the selected body's dimensions and surface optics, plus the configured panels they consume. Complete those fields in **Advanced geometry**. * Propellant-budget calculations also need dry mass and a physically consistent wet/dry mass split; configure the selected thruster's positive thrust and Isp for burn calculations. Missing values remain unavailable rather than becoming zero-valued results. Preserve known zeros where the field permits them; do not enter a representative mass or coefficient solely to clear an error. ## 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](/getting-started/first-spacecraft). The section lays out a Bus card beside the 3D viewer, with a tabbed components area below. Bus editor showing regular-prism dimensions, axis, and surface optics ### 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 | A **Regular prism** bus replaces the box fields with the polygon-prism inputs: | 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`). | — | In read mode the diameter is shown with its measure, for example `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)** | — | Surface optics describe the per-facet optical coefficients consumed by the faceted radiation model when an [attitude profile](/features/attitude/overview) is configured. When no attitude profile is configured, the Bus card shows the inline note **"faceted forces apply once an attitude profile is configured"** for both box and regular-prism shapes, and the spacecraft remains on the isotropic model — using only the scalar **Drag coefficient** and **Coefficient** values from the Isotropic model card. ### 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. Panels tab showing two solar-array cards with mount axes, facing vectors, dimensions, and mount positions 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)**. | — | **Mount axis selector** — choose one of seven options: | 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. | **Validation** — a panel saves only when every field is valid: | 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` | While a custom mount axis is invalid the **Facing** readout shows `—` 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](/features/attitude/overview) 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-`. | Deleting a thruster prompts a confirmation before applying. #### 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). | | **Pixel pitch** | The imaging detector's pixel pitch, in micrometres (`µm`). Optional. | | **Focal length** | The optical focal length, in millimetres (`mm`). Optional. | | **Along-track off-nadir limit** | How far the payload may be pointed fore or aft along the ground track, in degrees. Optional. | | **Cross-track off-nadir limit** | How far the payload may be pointed left or right across the ground track, in degrees. Optional. | **Field-of-view fields by shape** — every angle is a half-angle measured from the boresight to the edge of the field of view: | 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. | **Payload optics.** The **Pixel pitch** (`µm`) and **Focal length** (`mm`) fields sit beside the field-of-view geometry and describe the imaging optics. Both are **optional** — a payload saves and stays fully valid with neither set, and they do not affect the field of view or access geometry. Set **both** together to model an opportunity's **ground sample distance (GSD)**: with both present, VALAR reports the modelled GSD on the [AOI overflight opportunities](/features/areas-of-interest/overflight-events#ground-sample-distance-gsd) page; with only one or neither set, that opportunity's GSD reading stays unavailable. Enter, edit, or clear either value like any other field — each takes a positive number, and clearing a value (leaving it blank) removes it, returning the opportunity's GSD reading to its unavailable state. **Off-nadir limits.** The **Along-track off-nadir limit** and **Cross-track off-nadir limit** fields sit beside the field-of-view geometry and describe how far the payload may be pointed away from nadir — along-track fore or aft along the ground track, cross-track left or right across it. Both are **optional** and **independent** — a payload may carry one without the other, or neither. Each angle is **measured at the spacecraft, from the direction to Earth's centre**; an operator holding a ground-side incidence angle must convert it to this spacecraft-frame angle before entering it. When set, a limit must be greater than 0 and at most 90 degrees — `0` is rejected rather than treated as "no limit", so leave a field empty to leave that axis unconstrained. With both fields left empty, pass forecasts for this payload assume **nadir pointing only**. Both the **Along-track off-nadir limit** and the **Cross-track off-nadir limit** drive real access: on any area of interest with [off-nadir opportunities](/features/areas-of-interest/off-nadir-opportunities) turned on, setting, editing, or clearing either one is reflected in that area of interest's opportunities within a few minutes — no other step required. A spacecraft holds up to **8** payloads. Once eight are configured, the **Add payload** button is disabled and hovering it shows a **Maximum 8 payloads** tooltip. Each payload's field of view is drawn live in the [3D viewer](#3d-viewer) as a translucent solid: oriented along its boresight axis, with its apex at the attachment position. A `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](/features/tracking-sensors), 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 two lifecycle actions — **Archive** and **Restore**: | Spacecraft state | Action | Effect | | - | - | - | | **Active** | **Archive** | Deactivate the spacecraft. Data is preserved; the spacecraft is removed from active lists and pickers. | | **Archived** | **Restore** | Reactivate the spacecraft. It returns to active lists, pickers, and generation. | | **Archived** | **Delete** | Permanently destroy the spacecraft and all of its data. Terminal and irreversible. | Every action opens a confirmation dialog before applying, and the configuration cards stay editable for an archived spacecraft — archiving does not lock them. The behavior is identical across the **OPERATIONS** and **MISSION\_ANALYSIS** environments. **Archive is reversible; delete is not.** Archiving hides a spacecraft and preserves its data, and you can bring it back with Restore. Deleting an archived spacecraft permanently destroys it and all of its data — there is no undo and no recovery. Delete appears only for operators who hold the separately-granted delete authority; if you do not see it, you do not hold it. See [Delete a spacecraft](/features/spacecraft-deletion) for the full flow. ### Archiving a spacecraft Click **Archive** on an active spacecraft. A dialog titled **Archive spacecraft** asks you to confirm — *"This will archive \[name]. You can restore it later."* — and archiving removes it from every picker and active list while preserving its data and history. If the spacecraft has scheduled tasks ([fetch-alerts or orbit-determination tasks](/features/task-automation)), archiving permanently deletes them, so the dialog advances to a second confirmation before removing anything: **Delete scheduled tasks?** — *"N scheduled task(s) will be permanently deleted. This can't be undone."* (**N** is the real number of scheduled tasks on the spacecraft.) Confirm with **Delete tasks and archive**, or **Cancel** to leave the spacecraft active with its tasks intact. A spacecraft with **no** scheduled tasks skips the second step — the single **Archive spacecraft** confirmation archives it directly, with no deletion warning. A task that targets **multiple** spacecraft is not deleted outright: only the archived spacecraft is removed from it, and the task keeps running for its remaining spacecraft. It is deleted only when the archived spacecraft was its last one. ### Restoring a spacecraft Select the archived spacecraft from the [top-left selector](#switching-spacecraft) — it still lists archived craft — and click **Restore** in its Danger Zone. A dialog titled **Restore spacecraft** asks you to confirm — *"This will restore \[name] and mark it Active."* Restoring returns the spacecraft to **Active**: it re-enters every picker and list, and [AOI-overflight](/features/areas-of-interest/overflight-events) and [degraded-mode](/features/orbit-age) generation resume automatically. Restoring does **not** re-create the scheduled tasks that were deleted when the spacecraft was archived. After a restore you'll see the notice *"Scheduled tasks removed on archive were not restored. Re-create any you need."* — re-create any [fetch-alerts or orbit-determination tasks](/features/task-automation) you still want, including the fetch-alerts task that drives [conjunction alerts](/features/fetch-alerts). ### Where an archived spacecraft appears Archiving hides a spacecraft as a *selectable option* everywhere except this Spacecraft page — it does **not** remove the spacecraft's historical records. | Surface | Archived spacecraft shown? | | - | - | | **Spacecraft page** selector | **Yes** — the selector lists the full roster (active + archived); the selected archived craft shows an **Archived** badge in the page header, and is restored from its Danger Zone. When every craft is archived, all of them remain listed here. | | Every other **picker / filter** (orbit determination, conjunctions, maneuver planning, ground track, reporting, plotting, imports) | **No** — pickers list active spacecraft only; an all-archived roster reads **"No active spacecraft"**. | | Record **lists and tables** (burn plans, conjunctions, orbit solutions, reports, task runs) | **Yes** — existing records for an archived spacecraft stay listed exactly as before; archiving suppresses new selections, not history. | ### Alerts after archiving An archived spacecraft generates no new alerts, but the alert sources stop — and resume — differently: | Alert source | On archive | On restore | | - | - | - | | [AOI-overflight](/features/areas-of-interest/overflight-events) | Skipped for the archived spacecraft | Resumes **automatically** | | [Degraded-mode (stale orbit)](/features/orbit-age) | Skipped for the archived spacecraft | Resumes **automatically** | | [Conjunction alerts](/features/fetch-alerts) | Stop immediately — the spacecraft's scheduled fetch-alerts task is deleted | Do **not** auto-resume — re-create the fetch-alerts task to resume them | Alerts generated before a spacecraft was archived remain visible — archiving suppresses future generation, it does not erase history. **Archive is reversible; delete is not.** Archiving hides a spacecraft and preserves its data, and you can bring it back with Restore. Deleting an archived spacecraft permanently destroys it and all of its data — there is no undo and no recovery. Delete appears only for operators who hold the separately-granted delete authority; if you do not see it, you do not hold it. See [Delete a spacecraft](/features/spacecraft-deletion) for the full flow. ## 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. Example: 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. | **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. Required fields are marked with an asterisk. 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; catalogue selection or “not yet catalogued” | Colour | | **Cannonball model** | Launch Mass, Drag area, SRP area, Drag coefficient, Reflectivity coefficient | Dry Mass | | **Advanced geometry** | Box X, Y, Z (on the Box shape) or Sides, Diameter, Height (on the Regular prism shape); Absorption; Specular reflection | Panels, Payloads | Supply physical coefficients from your spacecraft configuration. A displayed example or prior value is not evidence of a missing spacecraft property; do not rely on generic drag or reflectivity coefficients to make a calculation run. Colour is a display preference, independent of the physical model. **Required-field validation** runs through the same [Validation Feedback](#validation-feedback) surface as the detail page — submitting the form with a blank required field shows the per-field error inline (for example, `Name is required.`) and blocks the submit until every required field is filled. Each offending field shows its inline message — for example, `Absorption coefficient (α) is required` on the Advanced geometry section — and the page scrolls the first field with an error into view, so a blocked submit never hides its cause below the fold. 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](/getting-started/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](/platform-overview/force-model): How geometry and optical inputs drive attitude-dependent drag and SRP. * [Attitude Overview](/features/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](/features/burn-plan): Plan maneuvers using configured thrusters. * [State Vectors](/features/state-vectors): View orbit solutions for this spacecraft. * [Task Automation](/features/task-automation): Schedule the fetch-alerts and orbit-determination tasks that archiving deletes and a restore does not re-create. # State Vector Comparison Source: https://docs.valar.space/features/state-vector-comparison Compare two state vectors side-by-side, or check a single state vector's mean elements against a public TLE reference > For the complete documentation index, see [llms.txt](/llms.txt). State Vector Comparison lets you inspect two state vectors side-by-side across their orbital elements — both osculating and DSST mean — and cross-check a single state vector's mean elements against the public TLE reference propagated with SGP4. Operators use this view to verify that orbit determination has converged, investigate divergence between theories, and spot-check their solutions against an independent SGP4 reference. **Route:** `/state-vectors/data` ## Compare Button The **Compare** button lives in the state vectors page toolbar, next to **Generate Ephemerides** and **Import**. The button is enabled whenever the current view contains at least one state vector. When the list is empty, the button is disabled and a tooltip reads *No state vectors to compare*. Clicking **Compare** opens the comparison modal with two tabs: **Osculating Elements** and **Mean Elements**. The Osculating Elements tab compares two state vectors side-by-side, so you'll select two state vectors from the modal's dropdowns to populate the view. The Mean Elements tab pairs a single state vector against the public TLE reference, so one selection is enough there. ## Osculating Elements Tab The Osculating Elements tab compares two state vectors side-by-side using their osculating Keplerian elements. The modal header contains two spacecraft dropdowns — **Spacecraft A** and **Spacecraft B** — separated by the label **vs**. ### Selecting State Vectors Once a spacecraft is picked on either side, a state vector (SV) selector appears in the column header for that side. Choose an SV for **Spacecraft A** on the left and an SV for **Spacecraft B** on the right. Selecting the same SV in both slots is prevented — if you pick an SV in one side that is already selected on the other, the other slot is cleared automatically. ### Epoch Alignment When the two selected SVs have different epochs, SV-B is propagated to SV-A's epoch so both columns represent the same instant. The right-column epoch row shows the original SV-B label followed by a note that it was propagated: ```text theme={null} · propagated to ``` ### Elements Table | Element | Symbol | Unit | Precision | | - | - | - | - | | Semi-major axis | a | km | 4 decimals | | Eccentricity | e | — | 6 decimals | | Inclination | i | ° | 4 decimals | | RAAN | Ω | ° | 4 decimals | | Argument of periapsis | ω | ° | 4 decimals | | True anomaly | ν | ° | 4 decimals | | Epoch | — | UTC | — | The **Δ** column shows the signed element-level difference between SV-A and SV-B for each row. A directional arrow flags which side is greater at a glance — up arrow when SV-A is larger, down arrow when SV-A is smaller — and the numeric magnitude is shown next to it. ## Mean Elements Tab The Mean Elements tab compares a single state vector's **DSST mean elements** against the **public TLE reference** for the same spacecraft. Because only one SV is compared, the **Spacecraft B** selector is hidden on this tab and only the **Spacecraft A** / SV-A selector is shown. Compare Sv Mean SV-A uses DSST mean elements; TLE reference uses SGP4 mean elements. Differences reflect both orbital divergence and theory. ### Reference Data The TLE is fetched for the spacecraft's configured NORAD ID and propagated with SGP4 to SV-A's epoch so the two columns share a common instant. The epoch row shows both the TLE epoch and the propagation target: ```text theme={null} → propagated to ``` ### Elements Table The tab's table uses three columns — **SV-A (DSST)**, **Public TLE (SGP4)**, and **Δ** (SV-A − TLE) — for the same six Keplerian elements listed in the Osculating Elements table, with the same precision (eccentricity to 6 decimals, other elements to 4). ## Details Panel — Mean Tab Mean elements are also available directly in the state-vectors details panel on the right-hand side, without opening the comparison modal. The Coordinates section now has three tabs: | Tab | Contents | | - | - | | **Keplerian** | Osculating Keplerian elements (a, e, i, Ω, ω, ν) and reference frame | | **Cartesian** | Position and velocity components in the selected reference frame | | **Mean** | DSST mean Keplerian elements for the selected state vector | Details panel Coordinates section showing the three tabs Keplerian, Cartesian, and Mean, with the Mean tab active and displaying six DSST mean Keplerian elements The **Mean** tab shows the same six elements with their standard symbols and precision: | Element | Symbol | Unit | Precision | | - | - | - | - | | Semi-major axis | a | km | 3 decimals | | Eccentricity | e | — | 6 decimals | | Inclination | i | deg | 3 decimals | | RAAN | Ω | deg | 3 decimals | | Arg. of periapsis | ω | deg | 3 decimals | | True anomaly | ν | deg | 3 decimals | ## When the TLE column isn't available The Mean Elements tab depends on a public TLE for the spacecraft. When that reference is missing, the platform surfaces the reason in-place so you can act on it. ### Spacecraft has no NORAD ID If the spacecraft selected as Spacecraft A does not have a NORAD ID configured, the TLE column is replaced with an informational notice: Configure a NORAD ID in spacecraft settings to enable the public TLE reference. Once a NORAD ID is added on the spacecraft's settings page, reopen the modal to see the TLE column populated. ### Space-Track temporarily unavailable When the upstream Space-Track service is unreachable or returns an error, the TLE column surfaces a transient warning: TLE reference temporarily unavailable. Try again shortly. This is a system-wide condition, not tied to any specific state vector — retrying a few moments later is usually enough. ### DSST conversion failure DSST mean elements are derived per-state-vector. When the conversion fails for a particular SV, its mean-element cell is replaced with: Mean elements unavailable for this state vector. This message appears in both places that render mean elements: * In the details panel **Mean** tab — the whole cell is replaced. * In the Mean Elements comparison tab — the SV-A column's first row is replaced. The condition is specific to a single state vector, so other state vectors for the same spacecraft may still show mean elements normally. ## Related API endpoints Use `GET /operations/state-vectors/{id}` to read a state vector programmatically — the response includes a `meanElements` field, which is `null` when DSST conversion failed for that state vector. See the **API Reference** tab at the top of the docs for the full schema and authentication details. ## Related Pages * [State Vectors](/features/state-vectors): List, import, and manage state vectors * [Spacecraft Management](/features/spacecraft-management): Configure a spacecraft's NORAD ID * [TLE Format](/file-formats/tle): TLE file format specification # State Vectors Source: https://docs.valar.space/features/state-vectors View, import, and manage spacecraft state vectors and orbit solutions > For the complete documentation index, see [llms.txt](/llms.txt). The State Vectors page displays orbit solutions for your spacecraft, including position, velocity, and covariance data. Import state vectors from [OPM](/file-formats/opm) files, view orbital elements, and export data for external use. **Route:** `/state-vectors/data` ## Page Layout The page uses a split-view design with a state vector list on the left and a details panel on the right: State Vectors When state vectors are selected, a floating action bar appears at the bottom. ## Filtering ### Spacecraft Filter Filter state vectors by spacecraft. Click to open a multi-select dropdown, check/uncheck spacecraft, and click **Apply** to confirm. **Default:** Shows all spacecraft when none selected. ### Time Range Filter | Option | Description | | - | - | | **Today** | Since midnight UTC today | | **Last Week** | Since midnight UTC, 7 days ago (default) | | **Last Month** | Since midnight UTC, 30 days ago | | **All Time** | Everything retained on your workspace | ### Group By | Option | Effect | | - | - | | **Spacecraft** | Groups state vectors by spacecraft with collapsible headers and per-group pagination (default) | | **None** | Flat list with infinite scroll | ### Sort by Epoch Click the **Epoch Newest first** button to toggle sort order: | State | Description | | - | - | | **Newest first** | Most recent epoch at top (default) | | **Oldest first** | Oldest epoch at top | ## State Vector List ### Row Information Each row displays: | Element | Description | Format | | - | - | - | | Checkbox | Selection for bulk actions | Hover-reveal | | ID | State vector identifier | Truncated (full ID on hover) | | a | Semi-major axis | XXXX.X km | | e | Eccentricity | 0.XXXX | | i | Inclination | XX.XX° | | Ω | RAAN | XX.XX° | | ω | Arg. of periapsis | XX.XX° | | ν | True anomaly | XX.XX° | | Mass | Spacecraft mass | XXXX kg | | Position σ | Position uncertainty (3D norm) | XX.XX m | | Spacecraft | Spacecraft name | Colored badge | | Epoch | State vector epoch | Mon DD format | ### Row Selection * **Click row**: Selects state vector for details panel * **Click checkbox**: Adds to bulk selection for bulk actions ## Grouped View When grouped by spacecraft, each group has a collapsible header: | Element | Action | | - | - | | **Chevron (▼/▶)** | Collapse/expand group | | **Group Name** | Spacecraft name | | **Count** | Total state vectors in group | | **◀ / ▶** | Navigate pages within group | ### Group Selection When items are selected within a group: * **Select All**: Select all items in current page of this group * **Clear**: Deselect all items in this group ## Details Panel Click a state vector row to view its details in the right panel. ### Header Shows the full state vector ID with a **⋮** menu button. ### More Menu Actions | Action | Description | | - | - | | **Download OPM** | Export single state vector as OPM file | | **Delete State Vector** | Delete this state vector (opens confirmation) | ### Metadata Section | Field | Description | | - | - | | **Spacecraft** | Name with colored satellite icon | | **Mass** | In kilograms (kg) | | **Originator** | Organization that created the solution (from imported OPM file, not editable) | | **Creation Date** | When imported/created (UTC) | | **Epoch** | State vector reference time (UTC) | ### Coordinates Section Toggle between **Keplerian** and **Cartesian** tabs. **Keplerian Tab:** | Element | Symbol | Unit | | - | - | - | | Semi-major axis | a | km | | Eccentricity | e | — | | Inclination | i | deg | | RAAN | Ω | deg | | Arg. of periapsis | ω | deg | | True anomaly | ν | deg | | Reference Frame | — | e.g., GCRF | **Cartesian Tab:** | Element | Unit | | - | - | | Position X, Y, Z | km | | Velocity X, Y, Z | km/s | | Reference Frame | e.g., GCRF | ### Covariance Section Only shown if covariance data exists in the state vector. The Position σ column in the list view also only appears for state vectors with covariance data. | Field | Unit | | - | - | | Position X, Y, Z σ | m (scientific notation) | | Velocity X, Y, Z σ | m/s | | Covariance Reference Frame | RTN or XYZ | Click **View Full Matrix** to open a modal with the complete 6×6 covariance matrix. ## Importing State Vectors Click **Import** in the toolbar to open the import dialog. State Vector Import ### Configuration **Format Selection:** | Format | Description | | - | - | | **OPM (CCSDS Standard)** | Standard CCSDS Orbit Parameter Message. VALAR matches the spacecraft automatically from the file's `OBJECT_ID` or `OBJECT_NAME`. | | **SpaceX OPM** | SpaceX second-stage OPM variant. You select the target spacecraft. | **Spacecraft Selection:** Shown only for **SpaceX OPM** — choose which spacecraft the state vector belongs to. For **OPM (CCSDS Standard)**, VALAR resolves the spacecraft from the file, so no selector appears. ### File Upload Drag and drop files onto the upload zone, or click to browse. Accepted files: `.txt`, `.opm` ### Upload Outcomes * **Success:** Toast notification, dialog closes, data refreshes * **Partial Success:** Warning toast with count (e.g., "Imported 1 of 2 orbit solutions") * **Error:** Red alert with the error code and message. See [OPM Import Error Modes](/file-formats/opm#import-error-modes) for the common errors and how to resolve them. ## Generating Ephemerides Click **Generate Ephemerides** in the toolbar to open the OEM Export wizard. This multi-step wizard creates ephemeris files from your state vectors. ### Wizard Steps | Step | Name | Description | | - | - | - | | 1 | **State Vector** | Select which state vector to use as the initial condition | | 2 | **Time Range** | Configure propagation start/end times and step size | | 3 | **Reference Frames** | Select output reference frame(s) | | 4 | **Review & Generate** | Review settings and generate the OEM file | For detailed documentation of each step, see [Ephemeris Generation](/features/ephemeris-generation). ## Exporting State Vectors ### Single Export From the details panel, click **⋮** → **Download OPM** to download a single state vector as an OPM file. ### Bulk Export Select multiple state vectors using checkboxes, then click **Export as OPM** in the floating toolbar. | Selection | Output | | - | - | | Single state vector | Downloads single `.opm` file | | Multiple (same spacecraft) | Downloads single `.opm` file | | Multiple spacecraft | Downloads `.zip` with separate OPM files | ## Deleting State Vectors ### Single Delete From the details panel, click **⋮** → **Delete State Vector**. Confirmation dialog: Delete State Vector ### Bulk Delete Select multiple state vectors, then click **Delete** in the floating toolbar. **Outcomes:** * **Full success:** "Successfully deleted X orbit solution(s)" * **Partial success:** "Partially successful: X deleted, Y failed" * **Full failure:** "Failed to delete any orbit solutions" ## Bulk Actions Toolbar Appears when one or more state vectors are selected via checkboxes. | Button | Action | | - | - | | **X selected** | Shows selection count | | **Select All** | Selects all visible state vectors | | **Export as OPM** | Exports selected as OPM file(s) or ZIP | | **Delete** | Opens bulk delete confirmation | | **Clear** | Deselects all rows | ## Unresolved spacecraft references When you request state vectors through the VALAR API and name spacecraft by reference — for example by NORAD id, COSPAR id, name, or [external key](/features/spacecraft-management#external-key) — the response includes an `unresolvedSpacecraftReferences` field alongside the results. This field is **always present**. When every reference you supplied resolved, it is an empty array. When one or more references could not be resolved, it lists them — and the results you received cover only the references that *did* resolve. A `200` response does not imply a complete result set. If you request data for five spacecraft and one reference is a typo, you receive state vectors for the other four, and the fifth is named in `unresolvedSpacecraftReferences`. Always check this field rather than assuming the results cover every spacecraft you asked for. The list follows three rules: * **Duplicates are collapsed** — a reference you supplied more than once appears at most once. * **Your order is preserved** — the references appear in the order you supplied them. * **There is no positional correspondence** between this list and the `content` array — an entry's position here does not line up with any row in the results. For how a single-spacecraft operation reports the same unresolvable reference — a 404 rather than a 200 — see [Spacecraft Lookup](/features/spacecraft-lookup#when-a-reference-cannot-be-resolved). ## Related Pages * [Generate OEM](/features/ephemeris-generation): Generate ephemeris files from state vectors * [Generate TLE](/features/tle-generation): Access TLE data via the cheatsheet * [OPM Format](/file-formats/opm): OPM file format specification # Task Automation Source: https://docs.valar.space/features/task-automation Create, schedule, and trigger automated tasks for orbit determination and alert fetching > For the complete documentation index, see [llms.txt](/llms.txt). Task Automation lets you save operational workflows as reusable tasks with optional scheduling. Configure orbit determination runs or alert fetches once, then execute them on demand or on a recurring schedule. **Route:** `/tasks` ## Task Dashboard The Tasks page displays all configured tasks in a responsive grid layout. Each task appears as a card showing its configuration, automation status, and last run. The site header shows two tabs next to the breadcrumbs: **Tasks** (this page) and **Runs** (the centralized run history at `/tasks/runs`). Each tab keeps its own filter state across switches. Task Dashboard ### Filtering Tasks Two filters are available in the toolbar: * **Spacecraft filter:** Show only tasks associated with specific spacecraft * **Automation status filter:** Filter by automation state: | Status | Description | | - | - | | **Active** | Task has a schedule and is enabled | | **Paused** | Task has a schedule but is currently disabled | | **None** | Task has no schedule (manual trigger only) | Both filters persist in the URL, so you can bookmark or share filtered views. ### Task Cards Each task card displays: * **Task name** — The display name you assigned when creating the task * **Spacecraft** — Which spacecraft the task is configured for * **Type** — The task type (Orbit Determination or Fetch Alerts) * **Automation section** — Schedule details, last run time with status, and a live countdown to the next scheduled run For automated tasks, a status badge indicates whether the task is **Active** or **Paused**. For event-triggered tasks, the **Schedule** row reads `Event: New measurements` and the **Next Run** tile is replaced with an **Event-driven** tile naming the configured event. Hover the tile to see when the event fires. ### Task Actions Click the **⋮** menu on any task card to access: | Action | Description | | - | - | | **Run now** | Execute the task immediately regardless of its schedule | | **Configure** | Open the task configuration dialog to modify settings | | **Enable/Disable** | Toggle the task's automation on or off | | **Delete** | Permanently remove the task (requires confirmation) | ## Creating a Task Click **Create Task** in the toolbar to open the task type picker. Task Type Picker Choose one of the available task types: | Task Type | Description | | - | - | | **Orbit Determination** | Configure and run an orbit determination process for a spacecraft | | **Alert Fetching** | Fetch conjunction alerts from external space tracking providers | After selecting a type, the corresponding configuration dialog opens. ### Orbit Determination Tasks The Orbit Determination dialog is a multi-step wizard. When creating a task, you first choose between **Run now** (execute immediately) or **Save as task** (save the configuration for reuse) using the mode selector in the dialog header. Orbit Determination Configuration The wizard steps are: 1. **Initial State** — Select the orbit source (Public TLE or State Vector) and configure spacecraft mass 2. **Measurements** — Define the measurement arc (rolling window or custom range), select measurement types (RA/Dec, Az/El, Range, PV), and choose data sources 3. **Maneuvers** — Select which maneuvers to estimate thrust scale for (All, None, or Above ΔV threshold) 4. **Residuals** — Preview residual behavior before launching 5. **Review** — Verify all settings before saving or running 6. **Automation** — Configure the task name and schedule (only shown when saving as a task) For a detailed guide on each configuration step, see [Orbit Determination](/features/orbit-determination). ### Alert Fetching Tasks The Alert Fetching dialog is a single-screen modal. Use the mode selector in the header to switch between **Run** mode (execute immediately) and **Task** mode (save as a reusable task). Alert Fetching Configuration Configure the following: * **Spacecraft** — Select which spacecraft to fetch alerts for (chosen from the header dropdown) * **Providers** — Select one or more data sources: | Provider | Requirement | Description | | - | - | - | | [SpaceTrack](https://www.space-track.org) | NORAD ID | US Space Command conjunction data | | [EU SST](https://www.eusst.eu) | COSPAR ID | European Space Surveillance & Tracking data | Provider credentials must be configured in **Settings → Integrations → STM** before first use. When in Task mode, the automation configuration appears below the provider selection, allowing you to name the task and set a schedule. For more details on alert fetching and results, see [Fetch Alerts](/features/fetch-alerts). ## Scheduling & Automation When saving a task, you configure its name and schedule in the automation section. Automation Configuration ### Task Name Enter a descriptive name for your task. This name appears on the task card in the dashboard and in notifications. ### Schedule Type Choose how the task should be triggered: | Schedule Type | Description | | - | - | | **None** | Manual trigger only — run the task on demand from the dashboard | | **Interval** | Run at a fixed interval (e.g., every 6 hours) | | **Cron** | Run on a custom schedule defined by a cron expression | | **Event** | Run automatically when a configured event arrives (available for **Orbit Determination** tasks) | ### Interval Scheduling Enter an interval using a number followed by a time unit: | Format | Example | Description | | - | - | - | | `Nm` | `30m` | Every 30 minutes | | `Nh` | `6h` | Every 6 hours | | `Nd` | `1d` | Every day | | `Nw` | `1w` | Every week | ### Cron Scheduling Enter a 6-field cron expression in the format: ``` seconds minutes hours day month weekday ``` **Examples:** | Expression | Description | | - | - | | `0 0 */6 * * *` | Every 6 hours | | `0 0 0 * * *` | Daily at midnight | | `0 0 0 * * 0` | Every Sunday at midnight | | `0 30 8 * * 1-5` | Weekdays at 8:30 AM | ### Event Scheduling Event scheduling fires the task automatically when a matching event occurs — no schedule polling and no operator action required. The **Event** tab is available on **Orbit Determination** tasks; on other task types the tab appears disabled with the message *"No event triggers are supported for this task type yet."*. The supported event is **New measurements**, which fires after a measurement batch is committed for any of the task's spacecraft. Each spacecraft in the batch is evaluated independently, so a single batch may start runs for some spacecraft and skip others. #### Event Trigger Configuration Configure these fields in the Event tab to control which batches start a run: | Field | Description | Default | | - | - | - | | **Event** | The event that fires this task. **New measurements** is the available event. | New measurements | | **Measurement Types** | Restrict to batches containing at least one measurement of these types: **Range**, **RA/DEC**, **AZ/EL**, or **Position+Velocity**. | Any measurement type | | **Sensors** | Restrict to batches containing at least one measurement from these sensors. Choose from the spacecraft's available sensors. | Any sensor | | **Minimum Count** | Require the batch to contain at least this many measurements for the spacecraft. Range: `1`–`10000`. | `1` | | **Debounce Window** | Suppress further runs for the same spacecraft until this duration has elapsed since the last run. Format: `Nm`, `Nh`, `Nd`, or `Nw` (e.g., `30m`, `6h`, `1d`). | No debounce | When all filters are at their defaults, every matching batch fires the task for every spacecraft in its list. The dialog displays a warning when no filters are set. When you save a **new** task with an event trigger, a confirmation dialog appears: *"Event trigger enabled. Runs will start from the next matching measurement batch; existing data will not be reprocessed."*. Editing an existing event-triggered task does not show this dialog. #### Switching Between Trigger Types Switching tabs between **None**, **Interval**, **Cron**, and **Event** discards the current trigger configuration. When the active tab has unsaved values, a confirmation dialog appears: *"Changing trigger type will discard your current trigger settings. Continue?"*. Click **Cancel** to keep the current settings or **Continue** to switch tabs and clear them. For a detailed guide on Orbit Determination configuration that runs on each event, see [Orbit Determination](/features/orbit-determination). To learn more about measurement types and sensors that can be used as filters, see [Measurement Types](/platform-overview/measurement-types) and [Tracking Sensors](/features/tracking-sensors). ## Managing Tasks ### Running a Task To execute a task immediately, click **⋮ → Run now** on the task card. The task runs with its saved configuration regardless of its schedule. A confirmation toast appears when the task starts. ### Enabling and Disabling Toggle a task's automation using **⋮ → Enable** or **⋮ → Disable**. When disabled, the task retains its schedule configuration but will not run automatically. You can still run it manually. ### Editing a Task Click **⋮ → Configure** to reopen the task's configuration dialog in edit mode. All previously saved settings are loaded, and you can modify any parameter including the schedule. Changes are saved when you confirm the dialog. ### Deleting a Task Click **⋮ → Delete** to remove a task. A confirmation dialog appears before deletion. This action is permanent and cannot be undone. ## Task Runs Click the **Runs** tab in the site header to open `/tasks/runs`, a centralized list of every task execution across every spacecraft in your tenant. The page polls for new runs every 10 seconds. **Route:** `/tasks/runs` Task Runs list view ### Row Layout Each run renders as a single horizontal row separated from its neighbours by a thin divider. The fields read left-to-right: | Position | Field | Notes | | - | - | - | | Left | **Task name** | Bolded. Reads italic **Task deleted** when the originating task has been deleted. | | Left | **Status badge** | Shows the run outcome — see *Status Values* below. **Skipped** rows wrap the badge in a tooltip with the skip reason. | | Right | **Task type** | **Orbit determination** or **Fetch alerts**. | | Right | **Trigger source** | **Schedule**, **Event**, or **Manual**. | | Right | **Spacecraft** | A coloured chip with the spacecraft name (omitted for rows that aren't spacecraft-scoped). | | Right | **Started** | Compact start date (e.g. `Apr 29`). | | Right | **Duration** | Wall-clock runtime: `Xms` for sub-second runs, `Xs` under a minute, `Xm Ys` above. Empty for **Skipped** or **Queued** rows. | Rows are sorted newest-first by start time. ### Status Values | Status | Display | Meaning | | - | - | - | | **Success** | Green badge | The run completed successfully. | | **Failed** | Red badge | The run failed during execution. | | **Running** | Blue badge | The run is currently executing. | | **Timeout** | Red badge | The run exceeded its time budget. | | **Skipped** | Muted badge | An incoming event was evaluated but did not start a run. Hover the badge for the concise reason, or click the row for the full filter-evaluation breakdown. | | **Queued** | Outline badge | A prior run for the same spacecraft is still in progress; this row will start once that finishes. | ### Filtering Runs Six filter controls live in the page topbar. All filter state and the **Group by** value persist in the URL — any view is bookmarkable and shareable. | Filter | Type | Options | Default | | - | - | - | - | | **Status** | Multi-select | **Success**, **Failed**, **Running**, **Timeout**, **Skipped**, **Queued** | All | | **Trigger source** | Multi-select | **Schedule**, **Event**, **Manual** | All | | **Task type** | Multi-select | **Orbit determination**, **Fetch alerts** | All | | **Spacecraft** | Multi-select | The spacecraft visible to your tenant | All | | **Time range** | Single preset | **24h**, **Last Week**, **Last Month**, **All Time** | Last Week | | **Group by** | Single select | **None**, **Task type**, **Spacecraft** | None | Within a multi-select, runs matching any of the checked options are shown (logical OR). Filters across different dimensions combine with logical AND. Leaving a multi-select empty applies no filter on that dimension. ### Grouping Runs Choose a **Group by** value to organise the list into collapsible sections without changing what is queried: | Group by | Behaviour | | - | - | | **None** | Flat list, newest-first. (Default.) | | **Task type** | Rows are grouped under section headers per task type, with a count next to each header. | | **Spacecraft** | Rows are grouped under section headers per spacecraft, with a count next to each header. | Within each group, rows are still ordered newest-first. ### Row Actions Click any row to open the originating task's configuration dialog — either the **Orbit Determination** wizard or the **Alert Fetching** modal, depending on the task type. The dialog opens in edit mode pre-loaded with the task's current settings. Two exceptions: * **Skipped rows** open the filter-evaluation popover (see [Skip Reasons](#skip-reasons)) instead of the configuration dialog. * Rows whose task name reads **Task deleted** are not clickable — no dialog opens, no toast appears. ### Skip Reasons Hover the **Status** badge on a **Skipped** row to see the concise reason as a tooltip. Click the row to open a popover showing how each filter was evaluated against the incoming batch (with the actual measurement types, sensors, count, and debounce values that the batch produced). | Reason | Cause | | - | - | | **No matching measurement type** | The batch did not contain any of the configured measurement types. | | **No matching sensor** | The batch did not contain any data from the configured sensors. | | **Below minimum count (X of Y required)** | The batch contained fewer measurements for the spacecraft than the configured minimum. | | **Debounced — cooldown window active** | The debounce window from the previous run for this spacecraft has not yet elapsed. | ### Loading more runs Rows load incrementally as you scroll — there are no pagination controls. The page polls for new runs every 10 seconds; fresh rows appear at the top of the list. ## Related Pages * [Orbit Determination](/features/orbit-determination): Detailed guide to OD configuration and results * [Measurements Data](/features/measurements-data): Inspect the measurement batches that fire event-triggered tasks * [Tracking Sensors](/features/tracking-sensors): Configure sensors available as event-trigger filters * [Fetch Alerts](/features/fetch-alerts): Detailed guide to alert fetching and provider setup * [Conjunction Classification](/features/conjunction-classification): View and manage conjunction events # Operations Timeline Source: https://docs.valar.space/features/timeline Review each spacecraft’s contacts, opportunities, burns, and orbital events together When **Timeline** is available in your Operations sidebar, it brings the separate Passes, AOI and Burn Plan timelines into one view. Each spacecraft is a collapsible group with a shared UTC time axis. Stations and AOIs identify events within those groups. Choose **Spacecraft**, a **24-hour**, **3-day** or **7-day** window, and the event **Layers** you want to see. Use the arrow buttons to move through time, **Now** to start the window at the current instant, and **Compact / Wide** to change detail. The URL preserves spacecraft, layers and explicit time selections for reopening. Available layers are contacts, AOI opportunities, burns, eclipses, SAA crossings, apsis and nodes. Opening Timeline from Passes, AOIs or Burn Plan selects the corresponding layers. Those areas keep their original timeline when the combined view is unavailable. ## Read and inspect events * **Contacts:** dashed bars are computed candidates; solid bars are saved bookings. Select a candidate to inspect its timing and geometry, then **Book contact** when the required geometry is available. Saved bookings replace the matching candidate. * **AOI opportunities:** marks locate entry instants. Select one for its area, spacecraft, entry, exit and payload; **Open AOI** returns to the area workflow. * **Burns:** select a burn for its status, epoch, duration and delta-V, or **Open burn** to review it in Burn Plan. An unavailable duration is stated explicitly. * **Orbital events:** inspect bands or instant markers for the measurements recorded by the event source. Overlapping events occupy separate tracks inside their spacecraft's layer. **Export** opens the existing schedule exporter for the selected time window; its supported event categories are unchanged. ## Coverage and unavailable results A layer's warning button opens its source notices. These distinguish stale contact results, missing station coverage, AOI computation failures, unavailable orbital data and time outside computed coverage. Shaded intervals indicate coverage gaps in the named source; another source may still have results there. **No events in this window** means the loaded layer has no events and no reported availability problem. A loading or failure notice is a different state. Failed contact refreshes keep the previous result visible and label it accordingly. **Refresh** retries the selected sources; it does not start an AOI recomputation or produce new stored pass evidence. Orbit-age restrictions still apply to computed contacts. **Show stored result** acknowledges an eligible stale-orbit restriction; saved bookings remain readable. # TLE Generation Source: https://docs.valar.space/features/tle-generation Generate Two-Line Element sets from state vectors > For the complete documentation index, see [llms.txt](/llms.txt). The spacecraft cheatsheet separates **Own computed** TLEs, fitted from your latest stored state vector, from **Public** catalogue data. Public orbital elements may be usable for propagation even when there are no TLE lines to copy. ## Accessing TLEs 1. Open the **cheatsheet** from the application header in **Operations**. 2. Select your spacecraft. 3. Open **Own computed** to view a fitted TLE, or **Public** to view available provider TLE text. 4. Use the copy button in that tab to copy the displayed two lines. The source marked as in use identifies the orbit-source category currently driving products. It does not mean both tabs contain the same orbit. ## How It Works | Aspect | Behavior | | - | - | | **State vector used for Own computed** | The latest eligible stored state by epoch: a manual/imported state or an accepted, converged orbit solution | | **Fitted TLE epoch** | The cheatsheet requests the current time; VALAR propagates the state to that epoch before fitting | | **Selection** | Selecting an older state vector elsewhere in the cheatsheet does not change the fitted-TLE request | | **Refresh** | Opening the cheatsheet or changing spacecraft requests fresh own-computed data | | **Public source** | Stored Space-Track or CelesTrak orbital data; optional TLE text retains its provider epoch | | **Unsupported TLE identifier** | Above `339999`, the cheatsheet explains the limit and skips fitted-TLE generation; other orbital data can still load | The fitted TLE's epoch is its output time, which can differ from the source state vector's epoch. The cheatsheet requests the current time; selecting an older state vector in its details does not select a different TLE epoch. If **Own computed** has no TLE, import a state vector or run orbit determination to provide one. Public GP elements without text remain usable for supported public-orbit workflows; their presence alone does not provide an own-computed TLE. ## Export through the Operations API Use [Generate a fitted TLE](/api-reference/state-vectors/generate-a-fitted-tle) in the **State Vectors** API reference: ```http theme={null} GET /operations/spacecraft/{spacecraftId}/tle?epoch=2026-09-22T12:00:00Z ``` This operation is available to customers with an authorized Operations API key. It requires the existing organization access and `read:ephemeris` permission; there is no separate internal-email or feature-rollout requirement. ### Authentication and inputs Use an [Operations API key](/features/api-keys) with access to the spacecraft's organization and the `read:ephemeris` permission. Send it as `Authorization: Bearer YOUR_API_KEY`. | Input | Required | Meaning | | - | - | - | | `spacecraftId` (path) | Yes | The canonical spacecraft `id` returned by `GET /operations/spacecraft`. Do not supply a name, NORAD number or COSPAR identifier. | | `epoch` (query) | Yes | The target epoch as an ISO-8601 instant with `Z` or an explicit timezone offset. There is no default epoch. | Set `VALAR_API_KEY` to your key and `SPACECRAFT_ID` to the canonical ID, then run: ```bash theme={null} curl --fail-with-body --get \ "https://api.valar.space/operations/spacecraft/${SPACECRAFT_ID}/tle" \ --header "Authorization: Bearer ${VALAR_API_KEY}" \ --header "Accept: text/plain, application/json" \ --data-urlencode "epoch=2026-09-22T12:00:00Z" ``` `--data-urlencode` also preserves the `+` in a positive timezone offset, such as `2026-09-22T14:00:00+02:00`. ### Result and prerequisites A successful response is **200**, `Content-Type: text/plain`: exactly two TLE lines separated by a newline, with no name line or JSON wrapper. The response is marked `Cache-Control: no-store`. Generation is synchronous and does not save a new resource or start a background job. The operation uses the existing **Own computed** generator: it selects the latest eligible stored state by epoch, propagates it to your requested epoch with the existing accurate force model and applicable maneuvers, then fits a single-state TLE. The request does not select a historical source state, accept raw state-vector input, or retrieve provider TLEs. It does not fall back to public catalogue data if an eligible stored state is missing. The spacecraft needs an eligible stored state and the mass, drag, radiation-pressure and geometry configuration required by its force model. The [catalogue-number limits](#six-digit-catalog-numbers) apply. When no NORAD ID is assigned, the existing generator uses the `99999` placeholder; it is not an assigned catalogue identity. An assigned ID above the supported limit is rejected, never replaced with that placeholder or truncated. The fitted TLE carries the requested output epoch, not necessarily the source state's epoch. This export makes no receiver-compatibility or orbit-accuracy guarantee. ### Failure responses Request, generation and API-key rejection failures use structured `application/json` errors rather than TLE text. Authentication can reject missing credentials or a malformed bearer token before API-key handling with an empty **401** body and a `WWW-Authenticate: Bearer` header. Always inspect the HTTP status before parsing either an error or TLE text. Success is `text/plain` only. If you set an `Accept` header, allow `text/plain` (for example, `text/plain, application/json` as above). An unsupported or malformed Accept header receives a structured JSON **406**, including when failure occurs before generation. | Status | Meaning / next step | | - | - | | **400** | Missing or invalid epoch, invalid source state, missing force-model configuration, unsupported catalogue ID, or propagation failure. Correct the reported input or configuration. | | **401** | Missing, invalid, expired or disabled API key. Check the key. | | **403** | Insufficient key grant, IP allowlist, environment access or `read:ephemeris` permission. Check authorization. | | **404** | Spacecraft is unknown or inaccessible (`SC-4040` with the supplied ID). Check the canonical ID from the spacecraft API; an all-zero UUID is not a spacecraft. | | **406** | Unsupported or malformed Accept header. Allow `text/plain` for the TLE success response. | | **422** | Existing spacecraft without eligible orbital state (`ORBITAL_STATE_NOT_FOUND`): upload ephemeris data or propagate from a TLE. Also returned for physically degenerate or numerically unrepresentable orbital input; review the source state. | | **500** | Unexpected generation failure. Contact VALAR with the error details. | ## TLE Format The generated TLE follows the standard NORAD two-line format: ``` 1 NNNNNC NNNNNAAA NNNNN.NNNNNNNN +.NNNNNNNN +NNNNN-N +NNNNN-N N NNNNN 2 NNNNN NNN.NNNN NNN.NNNN NNNNNNN NNN.NNNN NNN.NNNN NN.NNNNNNNNNNNNNN ``` For details on the TLE format and field definitions, see the [TLE Format](/file-formats/tle) documentation. ## Six-digit catalog numbers VALAR continues fitting and generating TLEs from state vectors. Public catalogue orbits can be stored as GP mean elements without TLE text; that does not remove TLE generation. * Catalog numbers through **99999** use the ordinary numeric TLE format. * **100000–339999** use Alpha-5 in the exported TLE's five-character satellite-number field. Confirm your ground-station software supports Alpha-5 before using these files for antenna pointing. * **340000–999999** cannot be represented in TLE/Alpha-5. The cheatsheet displays the format limit, and API TLE export rejects the request. Use an [OEM ephemeris](/features/ephemeris-generation) if your receiver accepts it. VALAR always keeps the full assigned numeric catalog number. Export never truncates it or substitutes a different satellite number. A spacecraft without an assigned NORAD ID retains the generator's `99999` placeholder. ## Related Pages * [Generate a fitted TLE](/api-reference/state-vectors/generate-a-fitted-tle): Operations API contract and request parameters * [State Vectors](/features/state-vectors): Manage orbit solutions and state vectors * [TLE Format](/file-formats/tle): TLE file format specification * [Generate OEM](/features/ephemeris-generation): Generate ephemeris files # Sensors Source: https://docs.valar.space/features/tracking-sensors Managing ground station and tracking sensor configurations > For the complete documentation index, see [llms.txt](/llms.txt). Ground sensors are required to track spacecraft and collect telemetry data. The Sensors page allows you to create, view, and delete sensor configurations that are used for processing tracking measurements. A tracking sensor is a fixed ground-based observer that watches spacecraft from the surface — not to be confused with an on-board spacecraft payload, which is a sensor carried by the spacecraft itself (see [Payloads](/features/spacecraft-management#payloads-tab) on the Spacecraft page). **Route:** `/orbits/measurements/sensors` ## Page Layout The sensors page has a split-panel design: Sensors When multiple sensors are selected, a floating action bar appears at the bottom. ## Viewing Sensors The sensor list (left panel) displays all ground sensors in your organization. Each row shows: * **Sensor ID** (e.g., "DSN-15") * **Latitude** (e.g., "35.43° N") * **Longitude** (e.g., "116.89° E") * **Altitude** (e.g., "1000 m") The first sensor is automatically selected when the page loads. ## Viewing Sensor Details Click any sensor row to view its details in the right panel: | Section | Field | Format | | - | - | - | | **Identity** | Sensor ID | Text (e.g., "DSN-15") | | **Location** | Latitude | XX.XXXX° N/S | | | Longitude | XX.XXXX° E/W | | | Altitude | XXXX m | | **Calibration** | Azimuth Bias | Scientific notation (e.g., "1.00e-03°") or "--" | | | Elevation Bias | Scientific notation or "--" | | | Downlink Delay | Seconds (e.g., "0.5 s") or "--" | ## Creating a Sensor Click **+ New Sensor** in the top-right corner to open the creation dialog. New Sensor ### Required Fields | Field | Description | Example | | - | - | - | | **ID** | Unique sensor identifier | DSN-15 | | **Latitude (deg)** | WGS84 latitude in decimal degrees | 35.4261 | | **Longitude (deg)** | WGS84 longitude in decimal degrees | 116.8895 | | **Height (m)** | Elevation above WGS84 ellipsoid | 1000 | ### Optional Fields (Calibration) | Field | Description | Default | Example | | - | - | - | - | | **Azimuth Bias (deg)** | Systematic azimuth error | Not set | 0.001 | | **Elevation Bias (deg)** | Systematic elevation error | Not set | 0.0005 | | **Downlink Delay (s)** | Signal propagation delay | 0 | 0.5 | ### Default Configuration When created, sensors are automatically configured with: | Setting | Default Value | | - | - | | Type | GROUND\_STATION | | Available | true | | Elevation Mask | 0° at all azimuths | | Measurement Types | AZEL and RANGE | ### Measurement Uncertainty Compatibility Sensor creation currently retains temporary legacy uncertainty assumptions so that the normal create-sensor → import workflow continues to work: * UI-created AZEL measurements use **1 arc-second per component**. * RANGE imports use **1 m** when the sensor carries the legacy two-entry sigma array. * Existing sensors with absent or null sigmas can still import: AZEL/RADEC use **2062 arc-seconds per component**, and RANGE uses **1 m**. These same fallbacks apply when the configured array has the wrong number of components. * Valid dimension-matched configured values take precedence: two positive finite values in arc-seconds for AZEL/RADEC, or one positive finite value in meters for RANGE. These defaults are assumed uncertainty, not measured sensor accuracy. Backend fallback use produces a `sigmas` warning in the import result and job summary. Values already supplied by sensor creation are not independently identified as assumptions on each imported row. The sensor dialog does not expose noise-sigma inputs, and the current PATCH API changes only the two-way Doppler convention; calibrated noise values must be supplied through sensor creation via the API. The creation defaults also retain downlink-delay driver sigma **0.002 s** and angular-bias driver sigma **0.1** in the driver's existing units when those drivers are generated. Driver uncertainty is separate from measurement noise. No existing sensor configuration is rewritten during import. ### Sensor Types The platform supports two sensor types: | Type | Description | UI Support | | - | - | - | | **GROUND\_STATION** | Ground-based tracking station | Yes (default) | | **TELESCOPE** | Optical telescope | API only | Only GROUND\_STATION sensors can be created through the UI. TELESCOPE sensors must be configured via the API. ### Outcomes * **Success:** Toast notification "Sensor ID created", sensor list refreshes * **Error:** Toast with error message from API ## Deleting a Sensor ### Single Delete 1. Select a sensor by clicking it 2. Click the **⋮** (three-dot menu) in the details panel header 3. Click **Delete Sensor** A confirmation dialog appears: Sensor Delete **Outcomes:** * **Success:** Toast "Deleted sensor ID", list updates, next sensor auto-selected * **404 Error:** Toast "Sensor 'ID' could not be deleted. It does not exist" * **Other Error:** Toast "Something went wrong deleting sensor ID", list refreshes ### Bulk Delete 1. Select multiple sensors using checkboxes (checkboxes appear on hover) 2. A floating action bar appears at the bottom 3. Click **Delete** | Button | Action | | - | - | | **X selected** | Shows selection count | | **Select All** | Selects all visible sensors | | **Delete** | Opens bulk delete confirmation | | **Clear** | Clears all selections | **Outcomes:** * **Success:** Toast "count sensor(s) deleted successfully", list updates * **Partial Failure:** Toast "Failed to delete some sensors", list refreshes * Selections are cleared after operation ## Important Limitations **No Edit Functionality:** Sensors cannot be modified after creation. To change a sensor's configuration, you must delete and recreate it. | Limitation | Description | | - | - | | **Fixed Measurement Types** | All sensors are created with AZEL and RANGE. Cannot be customized in UI. | | **Elevation Mask** | Default 0° at all azimuths. Custom masks require API configuration. | | **Organization Scope** | Sensors are scoped to your organization. | | **Irreversible Deletion** | Both single and bulk delete operations are permanent. | | **Sensor Type** | Only GROUND\_STATION available in UI. TELESCOPE requires API. | ## Doppler Ingestion Configuration Each sensor may declare a per-sensor `twoWayDopplerConvention` field that tells the TDM ingestion pipeline how to interpret two-way `DOPPLER_INSTANTANEOUS` observables produced by that sensor. The two valid CCSDS conventions (MEAN and SUM) differ by a factor of two and are not distinguishable from the keyword alone — declaring the convention explicitly avoids a 100% bias in the observable. | Setting | Behaviour | | - | - | | **MEAN** | Observable is the arithmetic mean of uplink and downlink instantaneous rates (DSN convention). | | **SUM** | Observable is `d/dt` of round-trip range; halved at ingest to normalise to MEAN. | | **UNDECLARED** | Two-way ingestion rejects at every magnitude; confirm and configure the producer's SUM or MEAN convention. | DOPPLER requires one finite positive catalog sigma in m/s in the normalized observable convention. The importer does not supply Doppler band defaults. The temporary angle/range compatibility policy above does not apply to Doppler. Missing station latitude, longitude, or ellipsoid height must also be supplied; explicit zero coordinates are valid. See [Doppler (Range-Rate) Measurements](/file-formats/tdm#doppler-range-rate-measurements) for the producer-convention, correction, required-uncertainty, and error contracts. ## Related Pages * [Import measurements](/features/measurements-import): Upload TDM, OEM, and SP3 files * [View measurements](/features/measurements-data): Filter and manage measurement data by sensor * [TDM file format](/file-formats/tdm#doppler-range-rate-measurements): Doppler observable contract, required uncertainty, and error codes # AEM (Attitude Ephemeris Message) Source: https://docs.valar.space/file-formats/aem Working with CCSDS Attitude Ephemeris Message format in VALAR > For the complete documentation index, see [llms.txt](/llms.txt). The Attitude Ephemeris Message (AEM) is a standardized ASCII text format for exchanging spacecraft attitude data over time. AEM is the attitude-data sibling of [OEM](/file-formats/oem): where OEM carries time-ordered position and velocity, AEM carries time-ordered orientation samples (quaternions or Euler angles) so receiving systems can reconstruct how a spacecraft was pointed throughout an interval. ## CCSDS 504.0-B-2 Conformance VALAR reads and writes AEM at **CCSDS 504.0-B-2** — every file the exporter produces carries `CCSDS_AEM_VERS = 2.0`. Two keywords that older B-1 files used to carry, `ATTITUDE_DIR` and `QUATERNION_TYPE`, are **no longer emitted** under B-2, because the standard now fixes the conventions they used to declare: * **Rotation direction** is implicit in the `REF_FRAME_A` → `REF_FRAME_B` ordering — every sample rotates a vector from `REF_FRAME_A` into `REF_FRAME_B`, so a separate `ATTITUDE_DIR` keyword is redundant. * **Quaternion component order** is mandated **scalar-last** (`Q1 Q2 Q3 QC`) by B-2, so the `QUATERNION_TYPE` indicator is redundant. If you consume a VALAR-exported AEM, read the rotation direction from the frame ordering and assume scalar-last quaternions — do not expect `ATTITUDE_DIR` or `QUATERNION_TYPE` to be present. ## Key Components An AEM file contains several distinct sections: * **Header**: File-level metadata including format version, creation date, and originator information * **Metadata**: Attitude context information such as object identification, the two reference frames involved, time system, attitude representation, and time bounds * **Attitude Data**: Time-ordered attitude samples (quaternions or Euler angles) at specific epochs, optionally including angular rates ## Critical Fields ### Metadata Section * **OBJECT\_NAME / OBJECT\_ID**: Spacecraft identification * **REF\_FRAME\_A**: First reference frame in the rotation — the frame attitude is measured *from* (typically the inertial frame, e.g., EME2000) * **REF\_FRAME\_B**: Second reference frame in the rotation — the frame attitude is measured *to* (typically the spacecraft body frame, e.g., SC\_BODY\_1) * **TIME\_SYSTEM**: Time system used for all epochs in the file (e.g., UTC, TAI) * **START\_TIME / STOP\_TIME**: Temporal bounds of the attitude ephemeris * **USEABLE\_START\_TIME / USEABLE\_STOP\_TIME**: Subset of the bounds within which interpolation is valid * **ATTITUDE\_TYPE**: Attitude representation in the data block (e.g., `QUATERNION`, `QUATERNION/DERIVATIVE`, `QUATERNION/RATE`, `EULER_ANGLE`) * **EULER\_ROT\_SEQ**: For `EULER_ANGLE` data, the rotation-axis sequence the angles follow (e.g., `ZYX`) * **INTERPOLATION**: Method for interpolating attitude between samples (e.g., Lagrange, Hermite) * **INTERPOLATION\_DEGREE**: Polynomial degree for interpolation ### Attitude Data Format Each line contains an epoch followed by the attitude sample. For quaternion data, the line layout is: `Epoch Q1 Q2 Q3 QC` Where `QC` is the scalar (real) component and `Q1`, `Q2`, `Q3` are the vector components. When angular rates accompany the quaternion (`QUATERNION/RATE` or `QUATERNION/DERIVATIVE`), three additional values are appended per line. ## Attitude Representations AEM supports several attitude representations selected via the `ATTITUDE_TYPE` field. VALAR accepts the quaternion family on import: `QUATERNION`, `QUATERNION/DERIVATIVE`, `QUATERNION/RATE`, and `QUATERNION/ANGVEL`. On export, VALAR writes `QUATERNION`, `EULER_ANGLE`, or both. ### Quaternion Component Order A quaternion has four components: a scalar (real) part and a three-element vector part. Two ordering conventions exist in the wild: * **Scalar-first**: `QC, Q1, Q2, Q3` — the scalar is the first value on each data line * **Scalar-last**: `Q1, Q2, Q3, QC` — the scalar is the last value on each data line CCSDS 504.0-B-2 mandates **scalar-last** ordering, and VALAR reads and writes scalar-last quaternions. Because the order is fixed by the standard, B-2 files do not carry the legacy `QUATERNION_TYPE` indicator. When importing a third-party AEM file, confirm the producing system uses scalar-last ordering. A scalar-first file parsed as scalar-last will yield rotations that are silently wrong rather than producing a parse error. ### Euler Angle Sequences When `ATTITUDE_TYPE = EULER_ANGLE`, each data line carries three rotation angles — roll, pitch, yaw — instead of four quaternion components, and the metadata field `EULER_ROT_SEQ` declares which axis sequence the angles follow. VALAR writes the sequence in **letter form**, and the exporter offers three: | `EULER_ROT_SEQ` | Rotation order | Notes | | - | - | - | | **ZYX** (default) | Z, then Y, then X | Yaw-pitch-roll — the default export sequence | | **XYZ** | X, then Y, then Z | Roll-pitch-yaw axis order | | **ZXY** | Z, then X, then Y | | The rotation order is non-commutative — applying the same three angles under a different sequence produces a different orientation, so a consumer must read `EULER_ROT_SEQ` before interpreting the angles. Euler angles are also undefined at gimbal lock (pitch at ±90°); when the chosen sequence is singular over the requested window, VALAR refuses the export rather than writing ambiguous angles. See [Exporting Attitude Ephemeris](/features/attitude/ephemeris) for the export-side behaviour. ## Reference Frame Conventions AEM expresses attitude as a rotation between two named frames, **REF\_FRAME\_A** and **REF\_FRAME\_B**. Under CCSDS 504.0-B-2 the direction is implicit in the ordering: every sample rotates a vector from `REF_FRAME_A` into `REF_FRAME_B`. * **REF\_FRAME\_A** is the frame the attitude is measured *from* — typically an inertial reference frame. VALAR exports offer `EME2000` (Earth Mean Equator and Equinox of J2000), `ITRF2014`, and `LVLH_ROTATING` (the local orbital frame). CCSDS-standard inertial labels such as `GCRF` and `ICRF` may also appear in imported files. * **REF\_FRAME\_B** is the frame the attitude is measured *to* — typically the spacecraft body frame. Body frames are named by mission convention; CCSDS allows local labels such as `SC_BODY_1`, `INSTRUMENT`, or any frame defined elsewhere in the metadata. Because direction follows the `REF_FRAME_A` → `REF_FRAME_B` ordering, there is no separate direction keyword to cross-check — reversing the two frames inverts the meaning of every sample in the file. ### LVLH Files and the Companion OEM When `REF_FRAME_A` is `LVLH_ROTATING`, the attitude is expressed against the spacecraft's Local-Vertical/Local-Horizontal frame, which is defined by the orbit itself. Such a file is not self-contained — it cannot be interpreted without the matching orbit ephemeris. VALAR therefore writes two `COMMENT` lines into the segment metadata pointing at the companion [OEM](/file-formats/oem): ``` COMMENT Companion OEM filename: _orbit-ephemeris__.txt COMMENT Companion OEM reference epoch: ``` The spacecraft name has every non-alphanumeric character replaced with `_`, and each timestamp has its colons and dots replaced with `-` (so `2026-06-01T00:00:00Z` becomes `2026-06-01T00-00-00Z`); the reference epoch is the segment's start instant. Fetch the named OEM and use its reference epoch to reconstruct the LVLH frame before consuming the attitude samples. ## Time System Conventions The `TIME_SYSTEM` field declares the time scale that every epoch in the metadata and data sections is expressed in. AEM accepts several time scales; the most commonly seen are: * **UTC**: Coordinated Universal Time. Subject to leap seconds. * **TAI**: International Atomic Time. Continuous, no leap seconds. * **GPS**: GPS time. Continuous, offset from TAI by a fixed 19 seconds. * **TDB**: Barycentric Dynamical Time. Used in deep-space and planetary applications. All times in VALAR are stored and displayed in UTC; an AEM file using a different time system is converted to UTC on import. Complete definition of the AEM standard on [CCSDS 504.0-B-2](https://ccsds.org/Pubs/504x0b2.pdf) guidelines. ## Sample AEM File Here is a sample AEM file in KVN format with quaternion attitude data: ``` CCSDS_AEM_VERS = 2.0 CREATION_DATE = 2024-06-15T08:30:00.000 ORIGINATOR = VALAR META_START OBJECT_NAME = SPACECRAFT-1 OBJECT_ID = 2023-001A CENTER_NAME = EARTH REF_FRAME_A = EME2000 REF_FRAME_B = SC_BODY_1 TIME_SYSTEM = UTC START_TIME = 2024-06-15T00:00:00.000 STOP_TIME = 2024-06-15T00:05:00.000 USEABLE_START_TIME = 2024-06-15T00:00:00.000 USEABLE_STOP_TIME = 2024-06-15T00:05:00.000 ATTITUDE_TYPE = QUATERNION INTERPOLATION = LAGRANGE INTERPOLATION_DEGREE = 7 META_STOP COMMENT Attitude rotates EME2000 (REF_FRAME_A) into SC_BODY_1 (REF_FRAME_B) COMMENT Quaternion components ordered scalar-last (Q1, Q2, Q3, QC) DATA_START 2024-06-15T00:00:00.000 0.0000000 0.0000000 0.0000000 1.0000000 2024-06-15T00:01:00.000 0.0004999 0.0000000 0.0000000 0.9999999 2024-06-15T00:02:00.000 0.0009999 0.0000000 0.0000000 0.9999995 2024-06-15T00:03:00.000 0.0014999 0.0000000 0.0000000 0.9999989 2024-06-15T00:04:00.000 0.0019998 0.0000000 0.0000000 0.9999980 2024-06-15T00:05:00.000 0.0024998 0.0000000 0.0000000 0.9999969 DATA_STOP ``` ## Euler-Angle and Two-Segment Files When the export includes the **Euler angles** representation, the segment sets `ATTITUDE_TYPE = EULER_ANGLE` and adds `EULER_ROT_SEQ` (for example, `ZYX`) to its metadata; each data line then carries three angles — roll, pitch, yaw — in place of the four quaternion components. Selecting **both** representations writes a single AEM with two segments — the `QUATERNION` segment first, then the `EULER_ANGLE` segment — each with its own metadata block and reference frame: ``` CCSDS_AEM_VERS = 2.0 CREATION_DATE = 2024-06-15T08:30:00.000 ORIGINATOR = VALAR META_START OBJECT_NAME = SPACECRAFT-1 REF_FRAME_A = EME2000 REF_FRAME_B = SC_BODY_1 ATTITUDE_TYPE = QUATERNION META_STOP DATA_START 2024-06-15T00:00:00.000 0.0000000 0.0000000 0.0000000 1.0000000 DATA_STOP META_START OBJECT_NAME = SPACECRAFT-1 REF_FRAME_A = EME2000 REF_FRAME_B = SC_BODY_1 ATTITUDE_TYPE = EULER_ANGLE EULER_ROT_SEQ = ZYX META_STOP DATA_START 2024-06-15T00:00:00.000 0.0000000 0.0000000 0.0000000 DATA_STOP ``` Each segment declares its own `REF_FRAME_A`, so a combined file can, for example, carry the quaternion segment in `EME2000` and the Euler-angle segment in `LVLH_ROTATING`. ## Common Use Cases * **Importing externally-computed attitudes**: Load attitude profiles produced by an external GNC tool, attitude-determination pipeline, or partner mission control system into VALAR for downstream analysis and visualisation. * **Exporting VALAR-computed attitudes**: Hand off an attitude profile generated in VALAR to ground-segment tools, payload planners, or contractors that consume CCSDS-standard inputs. * **Mission coordination**: Exchange the planned or reconstructed attitude history between organisations (operator, payload provider, ground stations) using a vendor-neutral interchange format. * **Cross-checking attitude solutions**: Compare attitude profiles from different sources by importing each as a separate AEM and inspecting the resulting orientation timelines side by side. ## Using AEM in VALAR AEM files are imported and exported through the spacecraft attitude ephemeris workflow. See [Attitude Ephemeris](/features/attitude/ephemeris) for the full operational reference, including the import dialog, validation messages surfaced when a file is rejected, the export dialog, and recovery steps for imports that left the spacecraft in a broken state. # AOI GeoJSON Subset Source: https://docs.valar.space/file-formats/aoi-geojson The RFC 7946 GeoJSON subset Areas of Interest accept on import, and the GeoJSON VALAR writes when you export a boundary > For the complete documentation index, see [llms.txt](/llms.txt). When you create an Area of Interest by pasting or uploading GeoJSON (see the [GeoJSON paste/upload tab](/features/areas-of-interest/create-aoi#geojson-pasteupload) in the AOI creation drawer), VALAR accepts a deliberately narrow subset of [RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946). This page catalogues what is accepted, what is rejected, what transformations are applied on ingest, and a worked example you can paste verbatim. The page covers both directions. Everything up to [Exporting a Boundary](#exporting-a-boundary) is the **import** contract — the GeoJSON VALAR accepts from you. That final section is the **export** contract — the GeoJSON VALAR produces from an area you already track. The two are deliberately different, and the export section says where and why. ## Supported Types VALAR accepts these top-level GeoJSON objects: | Type | Constraints | | - | - | | **Polygon** | Exterior ring only (no holes). Vertex count must be in `[3, 500]` distinct vertices. | | **MultiPolygon** | Between 2 and 50 disjoint single-ring pieces. Each piece must itself satisfy the Polygon rules. | | **Feature** | A Feature wrapper around either of the above geometries. The Feature's geometry is unwrapped on ingest. | | **FeatureCollection** | A FeatureCollection containing exactly one Feature, whose geometry is one of the above. The wrapper is unwrapped on ingest. | ## Rejected Types VALAR rejects every other RFC 7946 type, and refuses any document that declares a coordinate reference system other than WGS 84. The document is checked in your browser as you paste or select it, so a rejection appears immediately and nothing is sent: | Input | Result | | - | - | | Polygon with one or more interior rings (holes) | Rejected — remove the interior ring, or split the area into separate Polygons | | `GeometryCollection` | Rejected | | `Point` or `MultiPoint` | Rejected | | `LineString` or `MultiLineString` | Rejected | | `FeatureCollection` of zero or more than one feature | Rejected — unwrap the single Feature you want, or paste its geometry directly | | A `crs` member declaring a coordinate reference system other than WGS 84 | Rejected — re-export the file in WGS 84 from the tool that produced it | Most rejections in this table show the same helper line beneath the textarea: `GeoJSON must be a Polygon, Disk, or MultiPolygon`. Two are exceptions, and each carries its own helper line, because in both cases the document really is a Polygon and the general line would send you looking for a type problem you do not have. A Polygon carrying a hole shows `Polygons with holes are not supported`. A document declaring a non-WGS-84 reference system shows `This file declares a coordinate reference system other than WGS 84 — re-export it in WGS 84`. **Save** stays disabled until the document parses to one of the supported types. RFC 7946 mandates WGS 84 (longitude, latitude in decimal degrees) and removed the `crs` member entirely, so a conformant file never carries one — VALAR accepts a document with no `crs` member, and one written `"crs": null`, exactly as before. Older tools may still stamp a `crs` on their output. Where that declaration names WGS 84 in any of its usual spellings (`EPSG:4326`, `CRS84`, `urn:ogc:def:crs:OGC:1.3:CRS84`, and the other common forms) the file is accepted unchanged. Where it names anything else, the file is refused rather than reprojected: VALAR never transforms your coordinates, because the area it stores must be the area you supplied. This matters most for a system expressed in degrees — a different datum such as ED50, NAD27 or NAD83 produces values that look like plausible latitudes and longitudes, so without the declaration being read the area would be created silently offset from the ground you selected. Polygon and MultiPolygon contents are validated against the same geometry rules the structured-coordinate form enforces — see [Validation Errors](/features/areas-of-interest/create-aoi#validation-errors) for the full catalogue. ## Body Size Cap The pasted body or uploaded file must be at most **1 MB (1,000,000 bytes)**. A larger file is rejected with `GeoJSON file must be 1 MB or smaller`. Simplify the geometry (e.g. Douglas-Peucker reduction at a tolerance appropriate for your AOI) in a desktop GIS tool before retrying. ## Ingest Transformations VALAR applies the following deterministic transformations to the GeoJSON before persisting the AOI: | Transformation | Behaviour | | - | - | | **Strip 3rd coordinate** | If a coordinate pair carries an altitude (3rd value), it is dropped. AOIs are 2D Earth-surface regions. | | **Antimeridian crossing** | Polygons that cross the antimeridian are accepted directly as spherical polygons — no longitude-domain bookkeeping is required from the operator. | | **Feature unwrap** | A bare `Feature` is unwrapped to its inner geometry; a `FeatureCollection` of exactly one Feature is also unwrapped. | | **MultiPolygon-of-1 collapse** | A `MultiPolygon` with exactly one piece is collapsed to a plain `Polygon`. | | **Winding-order normalisation** | The exterior ring is normalised to counter-clockwise winding. Clockwise input is auto-rewound; the geometry's footprint is unchanged. | No extra vertices are inserted. The boundary VALAR stores has exactly the vertices you submitted, in the same order, so a boundary authored in another tool is stored exactly as that tool wrote it. That describes **import**. It says nothing about the files VALAR **exports** — those are densified and carry more positions than the stored boundary. See [Exporting a Boundary](#exporting-a-boundary). ## Rectangle and the Map Drawing Tool Rectangles drawn through the **Draw on map** tab are serialised to a 4-vertex Polygon on the client before submit — VALAR does not accept a bespoke `Rectangle` type. If you have a bounding box from an external source, hand-craft the corresponding closed Polygon. ## Worked Example — Tuscany Coast Below is a valid Polygon describing a small AOI covering the Tuscany coast near Livorno. It satisfies every rule documented above: a closed ring of 5 coordinate pairs (4 distinct + 1 closing repeat), no altitude component, no hole, no antimeridian crossing. ```json theme={null} { "type": "Polygon", "coordinates": [ [ [10.20, 43.80], [10.40, 43.80], [10.40, 43.60], [10.20, 43.60], [10.20, 43.80] ] ] } ``` Paste this block into the **GeoJSON paste/upload** tab of the AOI creation drawer, fill the rest of the [Create an AOI](/features/areas-of-interest/create-aoi) form, and **Save** — the AOI lands in the workspace and an automatic recompute follows. ## Worked Example — MultiPolygon A MultiPolygon must carry **at least 2** disjoint pieces: ```json theme={null} { "type": "MultiPolygon", "coordinates": [ [ [ [9.10, 45.50], [9.20, 45.50], [9.20, 45.40], [9.10, 45.40], [9.10, 45.50] ] ], [ [ [12.45, 41.95], [12.55, 41.95], [12.55, 41.85], [12.45, 41.85], [12.45, 41.95] ] ] ] } ``` Full specification of the GeoJSON encoding is in [RFC 7946 — The GeoJSON Format](https://datatracker.ietf.org/doc/html/rfc7946). VALAR's subset is documented above; anything outside the subset is rejected with one of the messages listed in the [Rejected Types](#rejected-types) table. ## Exporting a Boundary Everything above is the **import** contract — what VALAR accepts from you. This section is the **export** contract — what VALAR produces from an area you already track. Export runs from the area's own actions menu on the [Areas of Interest overview](/features/areas-of-interest/overview#export-a-boundary) page: choose **Export as GeoJSON** and the file downloads directly. It is named `aoi--.geojson`, where the date is the UTC calendar date of the export. ### What the File Contains The document is a single RFC 7946 `Feature`: | Element | Content | | - | - | | **`geometry`** | A `Polygon` for a single-piece area, or a `MultiPolygon` for a multi-piece one. Exterior rings only — no interior ring is ever written. | | **`coordinates`** | `[longitude, latitude]` positions in decimal degrees, WGS 84, rounded to 6 decimal places. No altitude component. Every ring is closed and wound counter-clockwise. | | **`properties.name`** | The area's name, or `null` when it has none. | | **`properties.description`** | The area's description, or `null` when it has none. | | **`properties.tags`** | The area's tags as an array of strings, or `[]` when it has none. | | **`properties.valar`** | The provenance block described below. | Nothing else is written. The file carries the boundary and the three identity fields above — never the area's validity window, colour, active flag, computed overflight events, or any workspace identifier. ### Accuracy of the Exported Boundary VALAR computes overflights against a boundary whose edges are **great-circle arcs**. GeoJSON has no arc primitive, so every edge in the file is a straight segment, and each one is subdivided until it tracks the arc closely. Exported area boundaries are densified so that every edge stays within 250 m on the ground of the great-circle boundary VALAR computes overflights against. This is a geometric bound only. It does not guarantee that a third-party tool re-evaluating access against the exported boundary reproduces VALAR's overflight results: whether a boundary deviation changes an access determination depends on the tasked sensor's footprint and slew geometry, which is not known when the area is exported. The 250 m bound holds for absolute latitude up to 89.5°. ### The `valar` Provenance Block `properties.valar` carries exactly six keys, in this order: | Key | Example | Meaning | | - | - | - | | **`producer`** | `"VALAR"` | The system that wrote the file. | | **`schemaVersion`** | `"1.0"` | Version of the file layout. It changes only when the structure changes in a way a consumer must react to. | | **`generatedAt`** | `"2026-07-22T14:03:11.482Z"` | The instant the file was written, ISO 8601, UTC. | | **`boundaryOnly`** | `true` | Always `true`. States that the file carries the boundary and nothing else — no overflight events and no forecast. | | **`maxDeviationM`** | `4.9` | The largest distance, in metres, between any segment written to the file and the great-circle edge it approximates. **Measured from the segments in this specific file** — it is not a fixed constant and not the 250 m bound, though it is always at or below that bound. | | **`deviationModel`** | `"great-circle-chord-sagitta"` | Names the quantity `maxDeviationM` measures, so a consumer does not have to infer it. | `boundaryOnly` sits immediately before `maxDeviationM` deliberately: the accuracy figure describes the boundary, and the file carries no overflight results for it to describe. ### An Exported File Is Not an Import File **A file VALAR exports is not guaranteed to import back into VALAR, and usually will not.** The two contracts are deliberately asymmetric, in both directions: | Asymmetry | Why the two differ | | - | - | | **Export writes more than import accepts** | Densification adds positions. An exported ring routinely carries far more than the 500 distinct vertices per ring the import route accepts, so re-importing it is refused on vertex count. No vertex ceiling is applied on export, because truncating the ring would emit a boundary that is not the one VALAR holds. | | **Import accepts more than export writes** | A circular area, an area crossing the 180° meridian, and an area enclosing a pole can each be created in VALAR, but none of them can be exported. See [Export a boundary](/features/areas-of-interest/overview#export-a-boundary) for the refusal reasons. | Export exists to hand a boundary to another tool — a GIS package, a planning system, your own pipeline — not to move areas between VALAR workspaces. To change an area's boundary inside VALAR, use **Replace from file…** on the [Areas of Interest overview](/features/areas-of-interest/overview#replace-the-boundary-from-a-file) page. ### Worked Example — An Exported File A small, mid-latitude polygon area exports to a document like this: ```json theme={null} { "type": "Feature", "geometry": { "type": "Polygon", "coordinates": [ [ [10.2, 43.6], [10.4, 43.6], [10.4, 43.8], [10.2, 43.8], [10.2, 43.6] ] ] }, "properties": { "name": "Tuscany Coast", "description": null, "tags": [], "valar": { "producer": "VALAR", "schemaVersion": "1.0", "generatedAt": "2026-07-22T14:03:11.482Z", "boundaryOnly": true, "maxDeviationM": 4.9, "deviationModel": "great-circle-chord-sagitta" } } } ``` This area's edges are short enough, and far enough from the poles, that none of them needed subdividing — so the exported ring holds the same positions the area was created with. A wider area, or one nearer a pole, carries many more positions than it was created with, and a correspondingly different `maxDeviationM`. ## Related Pages * [Create an AOI](/features/areas-of-interest/create-aoi) — full coverage of the creation drawer, including the **GeoJSON paste/upload** tab. * [Areas of Interest overview](/features/areas-of-interest/overview) — what an AOI is and how the page is laid out. * [Overflight events](/features/areas-of-interest/overflight-events) — read predicted overflights against the AOI you just created. # CDM (Conjunction Data Message) Source: https://docs.valar.space/file-formats/cdm Prepare and import complete CCSDS Conjunction Data Messages in VALAR The Conjunction Data Message (CDM) is a standardized format for communicating close-approach assessment data between spacecraft operators and tracking organizations. Use this page to prepare a complete `.cdm` file for the **Import** dialog on the conjunctions page and to check the required metadata, state vectors, and covariance terms before uploading. > For the complete documentation index, see [llms.txt](/llms.txt). ## Key Components | Component | Description | | - | - | | **Header** | Message metadata including format version, creation date, and originator information. | | **Relative metadata** | Conjunction information such as Time of Closest Approach (TCA), miss distance, relative speed, and collision probability. | | **Object metadata** | Identification, covariance method, maneuverability, and reference-frame information for both objects. | | **Object data** | A state vector and covariance matrix for each object. | ## Critical Fields | Field | Description | Unit | | - | - | - | | **TCA** | The UTC timestamp when the two objects are closest. | UTC | | **MISS\_DISTANCE** | Overall separation distance between objects at TCA. | m | | **COLLISION\_PROBABILITY** | Statistical probability of collision. | Dimensionless, from `0.0` to `1.0` | | **RELATIVE\_SPEED** | Magnitude of relative velocity. | m/s | | **Covariance terms** | The lower-triangular uncertainty matrix for each object. | See [Covariance Matrix](#covariance-matrix) | ## Object Data Requirements Each object block in an importable CDM must contain the following: | Requirement | What to Include | | - | - | | **Object identity** | `OBJECT_DESIGNATOR`, `OBJECT_NAME`, and `INTERNATIONAL_DESIGNATOR` when available. | | **State vector** | `X`, `Y`, `Z`, `X_DOT`, `Y_DOT`, and `Z_DOT`, with units in `km` and `km/s`. | | **Reference frame** | `REF_FRAME`, such as `EME2000`. | | **Covariance method** | `COVARIANCE_METHOD`, such as `CALCULATED`, when covariance data is provided. Include it for both objects. | | **Covariance matrix** | All 21 lower-triangular covariance terms for the object. Do not omit the position-velocity or velocity-velocity terms. | ## Covariance Matrix The covariance matrix has 21 independent lower-triangular terms for each object. Include every term in the following groups: | Matrix Block | Required Terms | Unit | | - | - | - | | **Position-position** | `CR_R`, `CT_R`, `CT_T`, `CN_R`, `CN_T`, `CN_N` | `m**2` | | **Position-velocity** | `CRDOT_R`, `CRDOT_T`, `CRDOT_N`, `CTDOT_R`, `CTDOT_T`, `CTDOT_N`, `CNDOT_R`, `CNDOT_T`, `CNDOT_N` | `m**2/s` | | **Velocity-velocity** | `CRDOT_RDOT`, `CTDOT_RDOT`, `CTDOT_TDOT`, `CNDOT_RDOT`, `CNDOT_TDOT`, `CNDOT_NDOT` | `m**2/s**2` | ## Common Use Cases * **Conjunction assessment**: Share close-approach predictions for collision-risk analysis. * **Collision avoidance**: Provide the state and uncertainty data used to evaluate a conjunction. * **STM exchange**: Transfer a conjunction prediction between a tracking provider and a spacecraft operator. See the complete [CCSDS 508.0-B-1 CDM standard](https://ccsds.org/Pubs/508x0b1e2c2.pdf) for the authoritative format definition. ## Worked Example The following KVN example is complete and can be used as a starting point. It includes `COVARIANCE_METHOD` and all 21 covariance terms for both objects. ```text theme={null} CCSDS_CDM_VERS = 1.0 CREATION_DATE = 2024-06-15T12:30:00.000 ORIGINATOR = SPACE-TRACK MESSAGE_FOR = ISS (ZARYA) MESSAGE_ID = SPACE-TRACK_CDM_001 COMMENT This is a complete example. All timestamps are UTC. TCA = 2024-06-20T14:30:45.500 MISS_DISTANCE = 847.5 [m] RELATIVE_SPEED = 14500.0 [m/s] RELATIVE_POSITION_R = 125.3 [m] RELATIVE_POSITION_T = -623.7 [m] RELATIVE_POSITION_N = 498.2 [m] RELATIVE_VELOCITY_R = -1.25 [m/s] RELATIVE_VELOCITY_T = 14499.5 [m/s] RELATIVE_VELOCITY_N = 0.85 [m/s] START_SCREEN_PERIOD = 2024-06-20T14:00:00.000 STOP_SCREEN_PERIOD = 2024-06-20T15:00:00.000 SCREEN_VOLUME_FRAME = RTN SCREEN_VOLUME_SHAPE = ELLIPSOID SCREEN_VOLUME_X = 50000.0 [m] SCREEN_VOLUME_Y = 50000.0 [m] SCREEN_VOLUME_Z = 50000.0 [m] SCREEN_ENTRY_TIME = 2024-06-20T14:29:30.000 SCREEN_EXIT_TIME = 2024-06-20T14:31:30.000 COLLISION_PROBABILITY = 5.678E-05 COLLISION_PROBABILITY_METHOD = FOSTER-1992 OBJECT = OBJECT1 OBJECT_DESIGNATOR = 25544 CATALOG_NAME = SATCAT OBJECT_NAME = ISS (ZARYA) INTERNATIONAL_DESIGNATOR = 1998-067A OBJECT_TYPE = PAYLOAD OPERATOR_CONTACT_POSITION = Flight Director OPERATOR_ORGANIZATION = NASA OPERATOR_PHONE = +1-281-483-0000 OPERATOR_EMAIL = flightdirector@nasa.gov EPHEMERIS_NAME = JSC EPHEMERIS COVARIANCE_METHOD = CALCULATED MANEUVERABLE = YES ORBIT_CENTER = EARTH REF_FRAME = EME2000 GRAVITY_MODEL = EGM-96: 36D 36O ATMOSPHERIC_MODEL = JACCHIA 70 DCA N_BODY_PERTURBATIONS = MOON,SUN SOLAR_RAD_PRESSURE = YES EARTH_TIDES = YES INTRACK_THRUST = NO COMMENT Object 1 State Vector X = 6778.137 [km] Y = 0.0 [km] Z = 0.0 [km] X_DOT = 0.0 [km/s] Y_DOT = 7.668 [km/s] Z_DOT = 0.0 [km/s] COMMENT Object 1 Covariance Matrix RTN CR_R = 4.142E+01 [m**2] CT_R = 5.461E+01 [m**2] CT_T = 2.345E+02 [m**2] CN_R = -3.456E+00 [m**2] CN_T = 1.234E+01 [m**2] CN_N = 9.876E+01 [m**2] CRDOT_R = -3.878E-02 [m**2/s] CRDOT_T = 5.213E-02 [m**2/s] CRDOT_N = -1.234E-03 [m**2/s] CRDOT_RDOT = 6.789E-05 [m**2/s**2] CTDOT_R = 5.678E-02 [m**2/s] CTDOT_T = -4.321E-02 [m**2/s] CTDOT_N = 2.345E-03 [m**2/s] CTDOT_RDOT = -1.234E-05 [m**2/s**2] CTDOT_TDOT = 8.765E-05 [m**2/s**2] CNDOT_R = 1.111E-03 [m**2/s] CNDOT_T = -2.222E-03 [m**2/s] CNDOT_N = 3.333E-03 [m**2/s] CNDOT_RDOT = 4.444E-06 [m**2/s**2] CNDOT_TDOT = -5.555E-06 [m**2/s**2] CNDOT_NDOT = 6.666E-06 [m**2/s**2] OBJECT = OBJECT2 OBJECT_DESIGNATOR = 43567 CATALOG_NAME = SATCAT OBJECT_NAME = COSMOS 2251 DEB INTERNATIONAL_DESIGNATOR = 2009-043FG OBJECT_TYPE = DEBRIS EPHEMERIS_NAME = NORAD TLE COVARIANCE_METHOD = CALCULATED MANEUVERABLE = N/A ORBIT_CENTER = EARTH REF_FRAME = EME2000 COMMENT Object 2 State Vector X = 6778.260 [km] Y = 0.125 [km] Z = -0.498 [km] X_DOT = 0.001 [km/s] Y_DOT = 7.669 [km/s] Z_DOT = -0.001 [km/s] COMMENT Object 2 Covariance Matrix RTN CR_R = 8.234E+02 [m**2] CT_R = 1.567E+02 [m**2] CT_T = 5.678E+03 [m**2] CN_R = -2.345E+01 [m**2] CN_T = 3.456E+02 [m**2] CN_N = 4.567E+02 [m**2] CRDOT_R = -7.890E-01 [m**2/s] CRDOT_T = 1.234E+00 [m**2/s] CRDOT_N = -5.678E-02 [m**2/s] CRDOT_RDOT = 9.012E-04 [m**2/s**2] CTDOT_R = 1.111E+00 [m**2/s] CTDOT_T = -2.222E+00 [m**2/s] CTDOT_N = 3.333E-01 [m**2/s] CTDOT_RDOT = -4.444E-04 [m**2/s**2] CTDOT_TDOT = 5.555E-03 [m**2/s**2] CNDOT_R = 6.666E-02 [m**2/s] CNDOT_T = -7.777E-02 [m**2/s] CNDOT_N = 8.888E-02 [m**2/s] CNDOT_RDOT = 9.999E-05 [m**2/s**2] CNDOT_TDOT = -1.111E-04 [m**2/s**2] CNDOT_NDOT = 2.222E-04 [m**2/s**2] ``` Save the example with the `.cdm` extension before uploading it. Replace the primary object's identifiers with a spacecraft registered in your VALAR fleet; otherwise the file can be structurally valid but cannot be linked to a spacecraft during import. ## Importing a CDM in VALAR 1. Open **Conjunctions** at `/conjunctions/current`. 2. Click **Import** to open the **Import Alerts** dialog. 3. Drag and drop one or more `.cdm` files into the upload area, or click **Drag and drop files here or click to browse**. 4. Confirm that the primary object in each file matches a registered spacecraft by NORAD ID or COSPAR ID. 5. Click **Import**. If the file is structurally incomplete, VALAR rejects it without importing a partial conjunction. Regenerate the CDM with complete metadata, state vectors, and covariance terms instead of filling missing uncertainty values with zeros. ## Differences Between CDM and Other Formats | Attribute | CDM | [OPM](/file-formats/opm) | [OEM](/file-formats/oem) | | - | - | - | - | | **Temporal Scope** | One conjunction event at a TCA. | One spacecraft state at one epoch. | A time-ordered trajectory. | | **Primary Content** | Two-object close-approach data, state vectors, and covariance. | One spacecraft state vector with optional elements and maneuvers. | Multiple spacecraft state vectors with optional covariance. | | **Primary Use** | Conjunction assessment and collision-risk analysis. | State-vector exchange and import. | Ephemeris exchange and propagation. | ## Related Pages * [Conjunction classification](/features/conjunction-classification): Review conjunction criticality and risk categories. * [Conjunction computation](/features/conjunction-computation): Compute conjunction events from spacecraft states. * [File format overview](/file-formats/overview): Compare the orbital and mission file formats supported by VALAR. # KML and KMZ Files Source: https://docs.valar.space/file-formats/kml The KML and KMZ geometry VALAR accepts when you create an Area of Interest or replace an existing area's boundary, and the KML VALAR writes when you export one > For the complete documentation index, see [llms.txt](/llms.txt). VALAR reads a single area out of a `.kml` or `.kmz` file and converts it to the same typed geometry the [GeoJSON](/file-formats/aoi-geojson) flow produces. You supply that file in one of two places: when you create an Area of Interest with the **KML** method (see the [KML upload](/features/areas-of-interest/create-aoi#kml) in the AOI creation dialog), or when you replace the boundary of an area you already track (see [Replace the boundary from a file](/features/areas-of-interest/overview#replace-the-boundary-from-a-file)). This page catalogues what geometry is accepted, what is silently dropped, the file-size limits, and what each error means — all of it identical on both paths. The page covers both directions. Everything up to [Exporting a Boundary](#exporting-a-boundary) is the **import** contract — the KML VALAR accepts from you. That final section is the **export** contract — the KML VALAR produces from an area you already track. The two are deliberately different, and the export section says where and why. KML is an [OGC standard](https://www.ogc.org/standard/kml/) originally created for Google Earth. A `.kmz` file is a ZIP archive containing a KML document — it is the default format Google Earth exports. ## Supported Geometry VALAR imports exactly **one area per file**. That area is either a single polygon or a set of polygons: | KML geometry | Result | | - | - | | **Polygon** | A single `` in one `` becomes a Polygon AOI. Its `` ring only — a polygon that also carries an `` ring is rejected, not trimmed. | | **MultiGeometry of Polygons** | A `` whose members are all `` becomes a MultiPolygon AOI (one AOI made of several disjoint pieces). | The imported polygons follow the same vertex and area rules the [GeoJSON subset](/file-formats/aoi-geojson) enforces — an exterior ring of 3 to 500 distinct vertices per piece, positive area, no self-intersection, and at most a hemisphere of extent. See the [Validation Errors](/features/areas-of-interest/create-aoi#validation-errors) catalogue for the full list. ## Rejected Geometry Anything that is not a single solid polygonal area is rejected before the area reaches the map: | Input | Why it is rejected | | - | - | | **Point** or **LineString** | AOIs are areas — a point or a line has no area to import. | | **A MultiGeometry mixing polygons with non-polygons** | Only all-polygon geometries convert to an AOI. | | **Multiple placemarks / multiple areas** | One area per file. Split a multi-area file and import each area separately. | | **A polygon with a hole (``)** | An AOI is a solid area with no cut-outs. Importing only the outer ring would cover ground you deliberately excluded, so the file is refused instead. | ## What Is Dropped on Import VALAR keeps only the area outline. The following are dropped without failing the import: | Dropped | Behaviour | | - | - | | **Altitude (3rd coordinate)** | If a coordinate carries a `,altitude` value, it is dropped. AOIs are 2D Earth-surface regions. | | **Name and styling** | The KML file's own placemark name, description, colour, and style are ignored. You name and colour the AOI in the creation form. | ## File Types and Size Limits | Constraint | Limit | | - | - | | **Accepted extensions** | `.kml` (plain KML) and `.kmz` (zipped KML — the Google Earth default export). | | **Maximum `.kmz` file size** | **5 MB** compressed. Larger archives are rejected before being read. | | **Maximum extracted KML size** | **1 MB** of KML text (the same cap as a pasted or uploaded GeoJSON body). This bound is enforced while the `.kmz` is unzipped, so a small archive that expands to a huge document is still rejected. | ## Replacing an Existing Boundary An area's boundary can be replaced from a file long after the area was created, from the **Replace from file…** control in the geometry editor on the [Areas of Interest overview](/features/areas-of-interest/overview#replace-the-boundary-from-a-file) page. The file is read exactly as it is on the creation path: | Rule | On the replace path | | - | - | | **Supported geometry** | Every shape in [Supported Geometry](#supported-geometry) is accepted identically — a single ``, or a `` whose members are all ``. | | **Rejected geometry** | Everything in [Rejected Geometry](#rejected-geometry) is refused identically — points, lines, mixed multi-geometries, multiple areas, and polygons carrying an `` hole. | | **What is dropped** | Altitude values, placemark names, and styling are dropped the same way. The area keeps the name, description, tags, and colour it already has. | | **File size** | Unchanged: **5 MB** compressed for a `.kmz`, and **1 MB** of extracted KML text. | A file holding more than one area is refused on **both** paths with the same message — `This KML file contains multiple areas — import a single area`. Split the file and supply a single area, whether you are creating the AOI or replacing its boundary. The replace dialog also accepts a `.geojson` file; see the [GeoJSON file format](/file-formats/aoi-geojson) page for that subset. ## Import Errors Each failure surfaces a single inline message — on the KML card when you are creating an area, and inside the replace dialog when you are replacing a boundary. No area is placed on the map until the file passes every check, and a refused replacement leaves the existing boundary untouched. | Message | Cause | Remediation | | - | - | - | | `The file could not be read as KML` | The file is not valid KML, or carries an XML `DOCTYPE` declaration. | Re-export the area as plain KML from your GIS tool. | | `The KML area must be a Polygon or set of Polygons` | The file's geometry is a point, a line, or a mix that is not all polygons. | Export the area as a polygon (or a set of polygons). | | `Polygons with holes are not supported` | A polygon in the file carries an `` ring. | Remove the inner ring, or split the area into solid pieces that leave the hole out, then re-export. | | `This KML file contains multiple areas — import a single area` | The file has more than one placemark / area. | Keep one area per file and import each separately. | | `No supported area (Polygon) was found in the KML` | The file (or `.kmz` archive) has no importable polygon inside. | Check that the file actually contains a polygon area. | | `The KML or KMZ file is too large to import` | The `.kmz` exceeds 5 MB, or the KML text exceeds 1 MB. | Simplify the geometry in a desktop GIS tool, then re-export. | | `This KML/KMZ file is encrypted and cannot be read` | The `.kmz` archive is password-protected. | Re-export an unencrypted `.kml` or `.kmz`. | ## Worked Example Below is a valid KML file describing a small AOI over the Tuscany coast near Livorno — one placemark, one polygon, a closed outer ring, no hole, no altitude. ```xml theme={null} Tuscany Coast 10.20,43.80 10.40,43.80 10.40,43.60 10.20,43.60 10.20,43.80 ``` Save this as `tuscany.kml`, pick **KML** in the AOI creation dialog, upload the file, fill in the rest of the [Create an AOI](/features/areas-of-interest/create-aoi) form, and **Save** — the AOI lands in the workspace and an automatic recompute follows. To try the `.kmz` path, zip the same file (Google Earth's **Save Place As… → .kmz** does this for you) and upload the archive instead. The same file also drives the replace path: open an existing area in edit mode, click **Replace from file…**, and choose it. ## Exporting a Boundary Everything above is the **import** contract — what VALAR accepts from you. This section is the **export** contract — what VALAR produces from an area you already track. Export runs from the area's own actions menu on the [Areas of Interest overview](/features/areas-of-interest/overview#export-a-boundary) page: choose **Export as KML** and the file downloads directly. It is named `aoi--.kml`, where the date is the UTC calendar date of the export. Export writes plain `.kml` only — there is no `.kmz` export, though both extensions are accepted on import. ### What the File Contains One `` holding one ``, whatever the area's shape: | Element | Content | | - | - | | **``** | The area's name, on both the `` and the ``. | | **``** | A fixed caveat, quoted below, so the limits travel with the file into whatever opens it. | | **``** | The area's description, its tags as a comma-separated list, and the six provenance values described below. | | **Geometry** | A single `` for a single-piece area, or one `` of `` elements for a multi-piece one. A multi-piece area is still one Placemark, so it stays one selectable feature. | | **``** | The exterior ring only. No `` is ever written — holes are not represented. | | **``** | Space-separated `longitude,latitude` pairs in decimal degrees, WGS 84, rounded to 6 decimal places. No altitude component. Every ring is closed and wound counter-clockwise. | | **``** | `clampToGround`, with `1`, so the boundary drapes over terrain instead of cutting through it. | No `