Documentation Index
Fetch the complete documentation index at: https://docs.valar.space/llms.txt
Use this file to discover all available pages before exploring further.
For the complete documentation index, see llms.txt.
An AOI overflight event is a predicted visibility window during which a spacecraft is above an AOI’s elevation threshold as seen from at least one point inside the AOI — the first-to-see / last-to-lose semantic. The events surface lives at the bottom of the AOI Overview page; it visualises every event in a 7-day window on a timeline and lists every event below the timeline.
Route: Visible on the Events band of the AOI Overview page once you select an AOI.
Events Surface Layout
The events surface composes four elements:
| Element | Description |
|---|
| Spacecraft filter | Dropdown defaulting to All spacecraft. Selecting one spacecraft narrows both the timeline and the list to that vehicle. |
| Recompute button | Refreshes the 7-day overflight schedule across every spacecraft in the workspace. |
| 7-day timeline | Per-spacecraft bars plotted across a now…now+7d axis. Bar position is the entry time, width is the pass duration, height scales with the peak elevation. |
| Column-less list | Each event renders as a row with embedded labels (no table columns). Click a row to expand its full per-event detail. |
7-Day Timeline
The timeline anchors at the current instant and spans 7 days. A row of day-tick labels lines the top axis. For every spacecraft that produces an event in the window, one row plots its passes:
- Bar position along the row marks the entry time.
- Bar width marks the pass duration.
- Bar height scales with the peak elevation — taller bars are higher passes.
The spacecraft filter applies to both the timeline rows and the list. Picking a specific spacecraft hides every other row on the timeline.
Column-Less Event List
The list renders each pass as a single row with embedded labels — not a table. From left to right: the spacecraft name, a Peak elevation badge in degrees, a Duration badge, and the entry time formatted relative to now (e.g. in 2h 30m, in 1d 4h). A chevron at the right edge signals expansion.
Clicking the row selects it for the per-event detail panel. Only one row is selected at a time — clicking another row swaps the selection; clicking the same row again deselects it. The detail panel renders beside the list on viewports wider than ~768 px (the two columns side-by-side fill the events band) and beneath the list on narrower viewports (the panel stacks under the selected row).
When the spacecraft filter is set to a single vehicle, an N of M shown indicator appears between the timeline and the list so you always know how many events the filter is hiding.
Per-Event Detail
The expanded detail exposes every operator-facing field on the event:
| Field | Description |
|---|
| Entry | The earliest instant any point in the AOI sees the spacecraft above the elevation threshold (UTC). |
| Peak | The instant of the maximum elevation in the pass (UTC). |
| Exit | The latest instant any point in the AOI still sees the spacecraft above the threshold (UTC). |
| Peak elevation | Maximum elevation angle in degrees observed during the event, taken from the AOI point that achieved the highest elevation at that instant. |
| Peak point | Geodetic latitude / longitude (WGS-84, °) of the AOI point that observed the peak elevation, rounded to two decimals. |
| Azimuth at peak | Azimuth angle in degrees from the peak point to the spacecraft at the peak instant, measured clockwise from local north. |
| Sub-satellite | Geodetic latitude / longitude (WGS-84, °) of the ground point directly below the spacecraft at the peak instant. |
| Sub-intervals | Count of disjoint visibility windows when the AOI shape produced more than one for the same pass. Surfaced only when the count is greater than 1. |
| Pieces | Per-piece peak point and peak elevation breakdown for multipolygon AOIs. Surfaced only when the AOI is a multipolygon. |
| Computed at | The instant the event was last refreshed (UTC). |
Filtering by Spacecraft
The spacecraft filter is a single dropdown at the top of the events surface. Its options are:
| Option | Effect |
|---|
| All spacecraft | Default. The timeline and list show every event from every contributing spacecraft. |
<Spacecraft name> | Only events from the selected vehicle are shown. The N of M shown indicator appears beneath the timeline so the filter weight is always visible. |
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; the timeline and the list keep the previously computed rows visible during the run. The Last computed label refreshes on success.
The Recompute button is disabled when:
- The AOI is Inactive (toggle it active again on the Overview page).
- The AOI is Out-of-window (its validity window has not started yet or has already ended).
- A recompute is already running.
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).
- Elevation threshold changes (the Min elevation field).
- Validity window changes (either bound, set or cleared).
- Flipping the AOI active toggle in the identity hero (Active ↔ Inactive).
Identity fields — name, description, tags, colour — do not trigger a recompute. Existing events stay in the list after 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.
Lifecycle Banners
When the AOI is in a state that explains why no events should be displayed, the events surface replaces the timeline and list with a banner. Only one banner is rendered at a time, and the cascade is:
| Banner | When it shows |
|---|
Recompute failed — try again | The most recent recompute rejected. The error clears the next time you click Recompute. |
AOI is outside its validity window. No events to display. | The current time falls outside the AOI’s validity bounds. |
AOI is inactive — no events to display. | The AOI has been paused from the identity hero. |
No overflights computed yet — click Recompute to generate the forecast | The AOI has never had a recompute run. |
No overflights in the next 7 days — try lowering the elevation threshold or check spacecraft orbit data | The recompute succeeded but produced no events for any spacecraft. |
Related Pages
- Areas of Interest overview — the page that hosts the events surface, plus the identity hero and geometry block.
- AOI Map — the world map view, where each AOI’s hovercard surfaces its next overflight and a compact 7-day timeline.
- Create an AOI — define an AOI and configure its lifecycle.
- GeoJSON file format — accepted geometry types for AOIs created from a GeoJSON document.
