> ## Documentation Index
> Fetch the complete documentation index at: https://docs.generalrobotics.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Navigation data schemas

> Typed inputs and outputs for map-frame navigation over Nexus.

Import these shared classes from `grid_types`. Nexus reconstructs them on the
client; PointNav is not needed in the notebook. Attributes use Python names
below. Their `to_dict()` / `from_dict()` methods describe application-level
serialization; the Nexus wire envelope is handled by the SDK.

## Coordinates and units

All public `Waypoint`, `Path`, and `NavPose` XY values use the active map frame
in **metres**. Yaw is in **radians**, zero along map +X and positive toward +Y.
Do not send grid-cell indices, image pixels, GPS coordinates, or robot-relative
offsets. Public `Waypoint` has **no yaw field**; these examples cannot request
terminal heading through a Waypoint. Saved missions can carry heading data.

## Waypoint

| Field | Type | Default / meaning |
| - | - | - |
| `x`, `y` | `float` | Required map coordinates. |
| `name` | `str` | `""`; descriptive identifier. Does not create a saved waypoint. |
| `label` | `str` | `""`; semantic label. |
| `confidence` | `float` or `None` | `None`; current semantic search provides no per-match confidence. |

## Path

| Field | Type | Default / meaning |
| - | - | - |
| `waypoints` | `list[Waypoint]` | Required ordered sparse stops. Construction also accepts `(x, y)` pairs. |
| `route` | `list[Waypoint]` or `None` | `None` until planned; dense route through the stops. |
| `map_id` | `str` | `""`; set this to the map UUID to detect accidental map mismatch. |
| `name` | `str` | `""`; descriptive path name, not a persistence operation. |

Constructing a Path does not plan or move. `Path` entries cannot be semantic
strings; use `nav.plan(["kitchen", "hallway"])` for those. `Path.from_dict`
expects nested waypoint dictionaries. For example, this is an illustrative
sparse-path dictionary, not a robot command:

```json theme={null}
{
  "waypoints": [
    {"x": 4.0, "y": 1.5, "name": "inspection", "label": "", "confidence": null}
  ],
  "route": null,
  "map_id": "YOUR_MAP_UUID",
  "name": "Inspection stops"
}
```

Store `path.to_dict()` as JSON if useful, but rebuild a sparse Path from its
waypoints and plan it from the robot's new pose before reuse. No `save_path`
or `list_waypoints` method is provided by this remote workflow.

## NavPose

| Field | Type | Meaning |
| - | - | - |
| `x`, `y`, `yaw` | `float` | Required map-frame pose. |
| `quality` | `float` | Required localization quality; higher is better, not a calibrated probability or universal acceptance threshold. |
| `localized` | `bool` | Required flag indicating a valid localized estimate. |

`to_pose()` converts to a 3D `Pose` at `(x, y, 0)` with a yaw quaternion.
`pose()` reads the latest estimate; `localize()` waits for a fresh accepted fix.

## NavState and NavLocalizationState

| NavState field | Type | Default / meaning |
| - | - | - |
| `state` | `str` | Required: `cold`, `initializing`, `ready`, `running`, `stopping`, `stopped`, or `shutdown`. |
| `map_id` | `str` | `""` when no map is bound. |
| `localization` | `NavLocalizationState` or `None` | `None` without localization workers. |
| `mission_running` | `bool` | `False`; use this to poll completion. |
| `mission_id` | `str` | `""` before a run; otherwise the runtime run identifier. |

| NavLocalizationState field | Type | Default / meaning |
| - | - | - |
| `map_id`, `state` | `str` | Required map and localization state: `cold`, `warming`, `ready`, `degraded`, or `closed`. |
| `pose` | `NavPose` or `None` | `None` until available. |
| `quality` | `float` | `0.0`; quality of the localization estimate. |
| `fusion_decision` | `str` | `""`; diagnostic fusion decision. |
| `stamp` | `float` | `0.0`; pose timestamp in Unix seconds. |

Runtime readiness and mission success are different: `ready` means another
mission can be attempted, not that the preceding mission succeeded.

## MissionResult

Returned by **blocking** `run_mission` / `move_to`:

| Field | Type | Default / meaning |
| - | - | - |
| `run_id` | `str` | Required identifier for this execution. |
| `status` | `str` | Required terminal status: `succeeded`, `cancelled`, or `failed`. |
| `message` | `str` | `""`; exit reason or worker error. |
| `final_pose` | `NavPose` or `None` | `None` when unavailable; pose sampled when the result is collected. |

Require `result.status == "succeeded"` before continuing an arrival-dependent
task. `nav.result()` has a different, raw dictionary schema; see
[non-blocking completion](/navigation/api-reference#non-blocking-missions-and-completion).

## Catalog records

These are immutable metadata records; every field is required and a `str`.

| Record | Fields | Meaning |
| - | - | - |
| `NavMapInfo` | `map_id`, `name`, `status`, `updated_at` | Map-job ID, display name, build status, and server timestamp. Only `COMPLETED` maps are usable. |
| `NavPathInfo` | `path_id`, `map_id`, `name`, `created_at`, `updated_at` | Saved-path ID, owning map, name, and server timestamps. Does not contain waypoints or a route. |

Timestamps are server strings, not Python datetime objects. Pass `path_id` to
`run_mission` after starting the owning map. A catalog read does not select
a map, download a route, or start motion.

## Telemetry and log payloads

These diagnostic dictionaries are not shared data classes. Use the envelope
keys below and tolerate additional diagnostic keys from newer runtimes.

| Telemetry key | Type / meaning |
| - | - |
| `version` | Integer envelope version, currently 1. |
| `epoch` | Opaque string identifying the cache generation; reset the cursor to zero when it changes. |
| `sequence`, `since` | Nonnegative integer sequence cursors, not timestamps. |
| `t_ns` | Integer snapshot timestamp in nanoseconds. |
| `errors` | Integer count of telemetry errors/dropped data. |
| `log_id` | Opaque string identifying the current terminal log, or `None`. |
| `streams` | Mapping of stream names to entries with `sequence`, `data`, `t_ns`, `kind`, and `vis`. `data` is a NumPy array after Nexus decoding. |
| `status` | NavState fields plus `progress`, raw `result`, and `error` diagnostics. |

A log reply has `log_id` (string), `start`, `end`, `size` (integer byte
offsets/size), and `text` (UTF-8 string). Follow using `end` as the next offset;
read history using `start` as the next `before` cursor. Do not compute byte
cursors from Python string length.

See [viewer and diagnostics](/navigation/api-reference#viewer-and-diagnostics)
for call arguments. Stream internals and progress/event payloads are diagnostic,
not a stable replacement for `NavState` or the mission result contract.

## Configuration and policy schemas

[Configuration JSON Schema](/assets/navigation/navigation-config.schema.json)
describes the dictionary accepted as `cfg` at attach time. The
[configuration guide](/navigation/configuration) explains additional shape and
cross-field validation. [Polygon constraints](/navigation/configuration#polygon-constraints)
have a separate versioned schema passed per mission. Neither schema defines
agent tool names or bypasses the current runtime's validation.


## Related topics

- [Navigation telemetry and notebook logging](/cli/nav-telemetry.md)
- [Navigation API contract](/navigation/api-reference.md)
- [Configure navigation](/navigation/configuration.md)
- [Navigation through GRID CLI](/navigation/overview.md)
- [Configuration field reference](/navigation/config-reference.md)


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