> ## 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.

# Areas of Interest

> 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](https://docs.valar.space/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](https://mintcdn.com/valar-8bbb18b5/6vb3axcORVXT2Ny4/images/aoi-overview-craft-pass.png?fit=max\&auto=format\&n=6vb3axcORVXT2Ny4\&q=85\&s=cc76c8572e9964dc2d56a750421e7963)

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](https://docs.valar.space/features/areas-of-interest/map.md) 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=<id>`. The URL parameter survives reloads and links — paste `/aoi?selected=<id>` 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](https://docs.valar.space/features/areas-of-interest/map.md) 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 "<name>"? 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](https://mintcdn.com/valar-8bbb18b5/6vb3axcORVXT2Ny4/images/aoi-geometry-block-craft-pass.png?fit=max\&auto=format\&n=6vb3axcORVXT2Ny4\&q=85\&s=9663c789ffd12970353f3526a6f77eae)

### 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](https://docs.valar.space/features/areas-of-interest/create-aoi.md) 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](https://mintcdn.com/valar-8bbb18b5/6vb3axcORVXT2Ny4/images/aoi-replace-boundary-dialog.png?fit=max\&auto=format\&n=6vb3axcORVXT2Ny4\&q=85\&s=bbcf8cb7b8f7b94885163071f28fa4c3)

| 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.

> [!NOTE]
>
> 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](https://docs.valar.space/file-formats/kml.md) and the [GeoJSON file format](https://docs.valar.space/file-formats/aoi-geojson.md).

### 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, `<start> (UTC) — Open-ended` when only the start is set, `Open-ended — <end> (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](https://mintcdn.com/valar-8bbb18b5/6vb3axcORVXT2Ny4/images/aoi-actions-menu-export.png?fit=max\&auto=format\&n=6vb3axcORVXT2Ny4\&q=85\&s=7da126d1f51b6bb5a45e5d6db196c1ce)

| Format | File | Contract |
| - | - | - |
| **GeoJSON** | `aoi-<name>-<yyyymmdd>.geojson` | An RFC 7946 `Feature`. See [GeoJSON file format](https://docs.valar.space/file-formats/aoi-geojson.md#exporting-a-boundary). |
| **KML** | `aoi-<name>-<yyyymmdd>.kml` | One OGC KML `Placemark`. See [KML and KMZ files](https://docs.valar.space/file-formats/kml.md#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.

> [!NOTE]
>
> 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](https://docs.valar.space/features/areas-of-interest/off-nadir-opportunities.md). |
| **Access** | Appears once off-nadir opportunities are switched on. Narrows the list to **All** (default), **Nadir**, or **Off-nadir only** — see [Filtering by Access](https://docs.valar.space/features/areas-of-interest/overflight-events.md#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](https://docs.valar.space/features/areas-of-interest/overflight-events.md#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](https://docs.valar.space/features/areas-of-interest/overflight-events.md) 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](https://docs.valar.space/features/areas-of-interest/map.md) — view every AOI at once on a full-bleed world map and drive creation from the same surface.
* [Create an AOI](https://docs.valar.space/features/areas-of-interest/create-aoi.md) — define an AOI by drawing, by typing coordinates, or by pasting a [GeoJSON file](https://docs.valar.space/file-formats/aoi-geojson.md).
* [Overflight events](https://docs.valar.space/features/areas-of-interest/overflight-events.md) — the heatmap's selection mechanics, per-opportunity detail, recompute mechanics, and the 7-day forecast horizon.
* [Off-nadir Opportunities](https://docs.valar.space/features/areas-of-interest/off-nadir-opportunities.md) — the per-AOI opt-in, the assessment vocabulary, and the geometric-bound disclaimer in full.
* [GeoJSON file format](https://docs.valar.space/file-formats/aoi-geojson.md) — the supported RFC 7946 subset accepted for AOI creation.
* [KML and KMZ files](https://docs.valar.space/file-formats/kml.md) — 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.