Spatial Annotations

Define map elements such as waypoints that missions can reference

Spatial annotations define named locations on maps that can be referenced by missions, expressions, and other features. The most common use is defining waypoints—specific positions robots can navigate to.

When to Use

• Named waypoints: Define docking stations, pickup points, or delivery locations
• Mission integration: Reference waypoints by name in mission definitions instead of raw coordinates
• Custom metadata: Attach properties like zone, priority, or category to locations

Scope

Spatial annotations can only be defined for robot or tag scopes. For tags, it must be an existing location tag in the account.

# Location-level annotation
scope: tag/<accountId>/<locationTagId>

# Robot-level annotation
scope: robot/<accountId>/<robotId>

Spec Fields

Field	Type	Required	Description
frameId	string	Yes	Coordinate frame (typically "map").
label	string	Yes	Human-readable name.
type	string	Yes	Annotation type. Currently "waypoint" is supported.
data	object	No	Type-specific data (see below).
properties	object	No	Arbitrary key/value metadata.

Waypoint Data

For type: waypoint, the data object contains:

Field	Type	Description
x	number	X position in meters.
y	number	Y position in meters.
theta	number	Heading in radians.

Examples

Simple Waypoint

kind: SpatialAnnotation
apiVersion: v0.1
metadata:
  id: "dock-station-1"
  scope: tag/<accountId>/<locationTagId>
spec:
  frameId: "map"
  label: "Dock Station 1"
  type: "waypoint"
  data:
    x: 5.2
    y: -3.1
    theta: 1.57

Waypoint with Properties

kind: SpatialAnnotation
apiVersion: v0.1
metadata:
  id: "nw-picking-5"
  scope: tag/<accountId>/<locationTagId>
spec:
  frameId: "map"
  label: "Picking Station #5"
  type: "waypoint"
  data:
    x: -20.71
    y: -4.14
    theta: 1.57
  properties:
    zone: "northwest"
    priority: "high"
    stationType: "picking"

Multiple Waypoints for a Location

# Dock
kind: SpatialAnnotation
apiVersion: v0.1
metadata:
  id: "dock"
  scope: tag/<accountId>/warehouse-a
spec:
  frameId: "map"
  label: "Home Dock"
  type: "waypoint"
  data:
    x: 0.0
    y: 0.0
    theta: 0.0
---
# Loading bay
kind: SpatialAnnotation
apiVersion: v0.1
metadata:
  id: "loading-bay"
  scope: tag/<accountId>/warehouse-a
spec:
  frameId: "map"
  label: "Loading Bay"
  type: "waypoint"
  data:
    x: 15.5
    y: 8.2
    theta: 3.14
---
# Exit point
kind: SpatialAnnotation
apiVersion: v0.1
metadata:
  id: "exit"
  scope: tag/<accountId>/warehouse-a
spec:
  frameId: "map"
  label: "Exit Point"
  type: "waypoint"
  data:
    x: 25.0
    y: 0.0
    theta: 0.0

Using Waypoints in Missions

Reference waypoints by their id in mission definitions:

# In MissionDefinition
steps:
  - label: "Go to dock"
    waypoint: "dock"  # References SpatialAnnotation id
  - label: "Go to loading bay"
    waypoint: "loading-bay"

Related Documentation

• Mission Definitions — Use waypoints in mission steps
• Maps — Coordinate systems and frames