UNIVIP

Part 12 — Geospatial Extension

On this page

Maturity: Draft · Profiles: optional on S, C, N · Schema: univip.geospatial.v0.2 (../schemas/geospatial.schema.json)

12.1 Purpose

A camera's position is not the position of what it observes. This extension lets a device report where each payload is looking so that a client can draw a view cone and ground footprint on a map, place detected objects, correlate with fixed cameras and search recordings by area.

A device declares support in capabilities.geospatial = { "supported": true, "fields": [...] }.

12.2 Footprint block (in telemetry.payloads[].geospatial)

{
  "hfov_deg": 62.0,
  "vfov_deg": 37.0,
  "frame_center": { "latitude_deg": 12.9722, "longitude_deg": 77.5951, "altitude_msl_m": 920.0 },
  "slant_range_m": 113.0,
  "footprint": { "type": "Polygon", "coordinates": [[[77.5947, 12.9719], [77.5956, 12.9719], [77.5957, 12.9726], [77.5946, 12.9726], [77.5947, 12.9719]]] },
  "footprint_source": "TERRAIN_MODEL",
  "position_uncertainty_m": 2.5,
  "footprint_uncertainty_m": 12.0
}
Member Description
hfov_deg, vfov_deg Current field of view
frame_center Ground intersection of the optical axis (MISB ST 0601 tags 23–25)
slant_range_m Distance from camera to frame center (tag 21)
footprint GeoJSON Polygon of the image corners on the ground (tags 26–33), in the order top-left, top-right, bottom-right, bottom-left
footprint_source FLAT_EARTH (assumes ground at home altitude), TERRAIN_MODEL, RANGEFINDER
position_uncertainty_m, footprint_uncertainty_m 1-sigma estimates

Devices SHOULD compute the footprint; a client MAY compute it from position, gimbal EARTH orientation and FOV when absent, marking the result as client-estimated.

12.3 Target object (in vehicle.analytics.object.detected data)

{
  "target_id": "t-88",
  "class": "VEHICLE",
  "subclass": "car",
  "confidence": 0.91,
  "bbox": { "x_pct": 0.42, "y_pct": 0.55, "w_pct": 0.08, "h_pct": 0.06 },
  "geolocation": { "latitude_deg": 12.97205, "longitude_deg": 77.59508, "altitude_msl_m": 918.0 },
  "geolocation_uncertainty_m": 6.0,
  "velocity": { "course_deg": 270, "ground_speed_mps": 11.2 },
  "stream_id": "cam-1-main",
  "frame_time": "2026-10-15T10:35:12.480Z",
  "attributes": { "color": "white" }
}

class is open; standard values: PERSON, VEHICLE, BICYCLE, ANIMAL, VESSEL, AIRCRAFT, FIRE, SMOKE, UNKNOWN. bbox is normalized to the frame. Mapping to MISB ST 0903 VMTI is given in Annex A.

12.4 Client-side uses (Informative)

  • Live map: drone icon oriented by heading_deg, view cone from gimbal.yaw_deg (EARTH) and hfov_deg, footprint polygon.
  • Click-to-point: client sends camera.gimbal.point_at (Profile C) or vehicle.goto (Profile N) from a map click.
  • Recording search: index footprints per sample; query by polygon intersection.
  • Cross-camera correlation: match geolocation against fixed camera coverage polygons.

Generated from spec/12-geospatial-extension.md.