# Positioning API Reference The Positioning service uses two versioned (v1) contracts for PTZ cameras: - `PTZSample`, a protobuf message that carries the raw pan/tilt/zoom reading a camera reports over ONVIF. It is defined in `ptz.proto` in the protobuf package `scenescape.ptz.v1`. - `ptz_calibration`, a JSON object that defines how raw pan/tilt values map to the camera orientation relative to its home pose. Source files: - `docs/user-guide/api-docs/positioning/v1/ptz.proto` - `docs/user-guide/api-docs/positioning/v1/ptz_calibration.schema.json` ## MQTT Pose and Status Contracts | Topic | Publisher | QoS / retain | Payload | | --------------------------------------------- | ----------- | ----------------------------- | ---------------------------------------------------------------- | | `scenescape/positioning/pose/{source_id}` | Positioning | 0 / retained | `pose_context` from `controller/src/schema/metadata.schema.json` | | `scenescape/positioning/status/{resolver_id}` | Positioning | 0 / retained with offline LWT | `positioning_status` from the same schema | | `scenescape/cmd/camera/config/{camera_id}` | Manager | 1 / not retained | Calibration-version invalidation | `source_id` is the Manager camera UID. Raw PTZ samples stay in-process and are never published to MQTT. Each accepted sample produces one valid or invalid PoseContext whose sequence is the accepted sample sequence. Invalid samples rejected before acceptance produce no context, so a sequence gap is observable by consumers. Retained messages are not proof of freshness: consumers must apply `valid_until`, pose age, session, sequence, timestamp, calibration, frame, and dwell checks from the shared dwell contract. The production Positioning broker connection uses TLS 1.3 on the standard broker listener (port 1883) with the `positioning.auth` credentials. Positioning validates its sources against the single-owner `source_id -> resolver_id` manifest at startup, publishes only the matching status and assigned pose topics, and subscribes only to assigned camera configuration topics. Manager remains authoritative for camera-to-scene membership. Within v1, fields are only ever added. Existing fields keep their numbers, names, types, and meaning. ## PTZ Sample (Protobuf) ### Service `PTZPoseIngest` | RPC | Request | Response | | ----------------- | ----------- | -------------- | | `SubmitPTZSample` | `PTZSample` | `PTZSampleAck` | > **Note:** In v1, the ONVIF poller passes samples to the Positioning service > in-process. The `PTZPoseIngest` service is reserved for a future authenticated > external producer and is not exposed on the network. ### Message `PTZSample` | # | Field | Type | Description | | --- | -------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------ | | 1 | `camera_id` | `string` | Manager camera UID. | | 2 | `adapter_instance_id` | `string` | Identifies the poller instance. Changes on every poller restart. | | 3 | `sequence` | `uint64` | Monotonically increasing within one `adapter_instance_id`. | | 4 | `measured_at` | `google.protobuf.Timestamp` | Midpoint of the ONVIF request/response interval. | | 5 | `timestamp_uncertainty_ns` | `uint64` | Uncertainty of `measured_at`, at least half of the ONVIF request/response interval. | | 6 | `position` | `PTZPosition` | Raw position reported by the device. | | 7 | `reported_move_status` | `ReportedMoveStatus` | Move status reported by the device. Advisory only: the service derives the authoritative motion state. | ### Message `PTZPosition` Raw device-reported values in the ONVIF position space that the camera advertises. | # | Field | Type | Description | | --- | -------------------- | ----------------- | -------------------------------------------- | | 1 | `pan` | `double` | Raw pan position. | | 2 | `tilt` | `double` | Raw tilt position. | | 3 | `zoom` | `optional double` | Raw zoom position, if the camera reports it. | | 4 | `position_space_uri` | `string` | ONVIF position space URI. | | 5 | `pan_min` | `double` | Lower bound of the pan range. | | 6 | `pan_max` | `double` | Upper bound of the pan range. | | 7 | `tilt_min` | `double` | Lower bound of the tilt range. | | 8 | `tilt_max` | `double` | Upper bound of the tilt range. | ### Enum `ReportedMoveStatus` | Value | Name | | ----- | ---------------------------------- | | 0 | `REPORTED_MOVE_STATUS_UNSPECIFIED` | | 1 | `REPORTED_MOVE_STATUS_IDLE` | | 2 | `REPORTED_MOVE_STATUS_MOVING` | ### Message `PTZSampleAck` | # | Field | Type | Description | | --- | ------------------- | ----------------- | -------------------------------------------------------------------- | | 1 | `result` | `PTZSampleResult` | Outcome of the submission. | | 2 | `detail` | `string` | Human-readable detail, for example the reason a sample was rejected. | | 3 | `accepted_sequence` | `uint64` | Sequence number of the sample. | ### Enum `PTZSampleResult` | Value | Name | Meaning | | ----- | ---------------------------------- | --------------------------------------------------- | | 0 | `PTZ_SAMPLE_RESULT_UNSPECIFIED` | Not set. | | 1 | `PTZ_SAMPLE_RESULT_ACCEPTED` | The sample was accepted. | | 2 | `PTZ_SAMPLE_RESULT_DUPLICATE` | A sample with this `sequence` was already received. | | 3 | `PTZ_SAMPLE_RESULT_OUT_OF_ORDER` | `sequence` is older than the last accepted sample. | | 4 | `PTZ_SAMPLE_RESULT_UNKNOWN_CAMERA` | `camera_id` does not match a known camera. | | 5 | `PTZ_SAMPLE_RESULT_INVALID` | The sample failed validation. | ## PTZ Calibration (JSON) A `ptz_calibration` object is a per-camera model that converts raw ONVIF pan/tilt readings into an orientation relative to the camera's home pose. The home pose itself is stored in the Manager camera record. Unknown properties are rejected. ### Top-Level Fields | Field | Type | Required | Description | | ------------------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `parameterization_version` | string | Yes | Must be `"v1"`. | | `calibration_version` | string | Yes | Identifier of this calibration, 1 to 128 characters. | | `position_space` | object | Yes | ONVIF position space the calibration was measured in. See [Position Space](#position-space). | | `settle_angular_threshold_deg` | number | Yes | Angular change, in degrees, below which the camera is treated as settled. Must be > 0 and within the calibrated travel of each axis. | | `settle_interval_s` | number | Yes | Time, in seconds, the position must stay within the threshold to count as settled. Must be > 0. | | `composition_order` | array | Yes | Permutation of `"pan"`, `"home"`, and `"tilt"`. See [Orientation](#orientation). | | `axes` | object | Yes | Object with `pan` and `tilt` entries, each an [Axis](#axis) object. | | `quality` | object | Yes | Contains `reprojection_rms_px` (number, >= 0): reprojection RMS error of the calibration, in pixels. | | `provenance` | object | No | Measurement provenance: instrument and version, camera model and firmware, date, operator, and fitting script revision. | ### Understanding the Model Version Two different calibrations are used together: - The camera's **reference pose** (`pose_matrix`) describes its position and orientation in the scene at the recorded home pan/tilt. AprilTag or manual calibration establishes this pose. - The **PTZ movement model** (`ptz_calibration`) maps raw ONVIF readings to changes in orientation, including axis directions, angular scales, nonlinear corrections, and backlash. `calibration_version` labels the imported PTZ model. The operator or offline export tool chooses it; Manager stores it, and Positioning reads it and includes it in PoseContexts and diagnostic logs. It is not generated by Positioning, not a camera preset name, not an accuracy score, and not the time of the latest AprilTag calibration. For example, `camera-1-20261022T154646Z` could be a tool-generated export label; the timestamp naming convention has no API semantics. Use a new unique label when changing the model or its reference, and keep the associated dataset and provenance. Moving pan/tilt does not change this version. **Auto Calibrate > Save Camera** updates the static pose but does not automatically rebase the PTZ model or create a new model version. The saved pose must still correspond to the model's `home_position`. A camera's device-side home preset is not automatically linked to that reference. See [Keeping the Reference Consistent](./how-to-guides/calibrate-cameras/onboard-ptz-cameras.md#keeping-the-reference-consistent). ### Position Space | Field | Type | Required | Description | | ---------- | ------ | -------- | ---------------------------------------------- | | `uri` | string | Yes | ONVIF position space URI, 1 to 512 characters. | | `pan_min` | number | Yes | Lower bound of the pan range. | | `pan_max` | number | Yes | Upper bound of the pan range. | | `tilt_min` | number | Yes | Lower bound of the tilt range. | | `tilt_max` | number | Yes | Upper bound of the tilt range. | ### Axis All fields are required. | Field | Type | Description | | ----------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `axis` | array of 3 numbers | Rotation axis as a unit vector, expressed in `frame`. | | `frame` | string | `"world_home"`: scene frame with the head at home. `"camera_local"`: optical frame of the camera at home. | | `curve` | array of 2 to 8 numbers | Polynomial coefficients, in increasing power, that map the raw ONVIF position to degrees. Encodes both scale and sign; axis inversion is expressed only by negative coefficients, and there is no separate inversion flag. The constant term cancels out. | | `home_position` | number | Raw ONVIF position at the calibrated home pose. | | `approach_direction` | string | `"increasing"` or `"decreasing"`: direction of travel used to reach home during calibration. | | `backlash` | number or array | Total gear slack in degrees. Either one value (>= 0), or 1 to 64 `[position, degrees]` nodes interpolated linearly and held constant beyond the end nodes. | | `backlash_home_tolerance_deg` | number | When backlash state is unknown, for example after a restart, the service initializes it from `home_position` and `approach_direction` only if the reported position is within this many degrees of home. Must be > 0 and within the calibrated travel of the axis. | | `backlash_history_s` | number | How far back, in seconds, observed motion is kept to track backlash state. Must be > 0. | ### Orientation The camera orientation is the left-to-right product of rotations in `composition_order`. For example, `["pan", "home", "tilt"]` gives `R_pan · R_home · R_tilt`. The translation is the same as in the home pose. An axis whose `frame` is `world_home` must come before `home` in `composition_order`. An axis whose `frame` is `camera_local` must come after `home`. ### Additional Validation When a calibration is loaded, the service also checks these rules, which the JSON Schema cannot express: - All values are finite. - Each `axis` is a unit vector. - Each `*_min` value is less than the matching `*_max` value. - `home_position` is inside the axis range. - Each axis `frame` matches its place in `composition_order`. - `backlash` nodes have distinct positions. - `settle_angular_threshold_deg` and each `backlash_home_tolerance_deg` do not exceed the calibrated travel: the angular span of the axis `curve` over its `position_space` range. ### Manager Import Threshold Manager accepts a non-null `ptz_calibration` only when its `reprojection_rms_px` does not exceed `PTZ_CALIBRATION_RESIDUAL_THRESHOLD_PX`, a finite, positive maximum in pixels. The Manager image sets it to `12.0`, which is about 1 degree of pointing error at 3 m in a 1080p image. To override it, set the variable in the Compose project `.env` file or the environment used to launch Compose; for Helm, set `web.ptzCalibrationResidualThresholdPx`, or export `PTZ_CALIBRATION_RESIDUAL_THRESHOLD_PX` before `make -C kubernetes install`. If the configured value is empty, malformed, non-finite, zero, or negative, calibration imports and non-null calibration writes are rejected. ### Manager Validation Errors `POST` and `PUT /api/v1/camera/{uid}` and scene import validate `ptz_calibration` with the rules above and return `400` on the first violation. The error is a stable `: ` string; clients should match on it rather than on free text: ```json { "ptz_calibration": ["axes.pan.axis: not_unit_vector"] } ``` `` is the dotted field path; backlash nodes use an index, for example `axes.tilt.backlash[1]`. | Code | Meaning | | --------------------------- | --------------------------------------------------------------------------------- | | `not_object` | Value must be a JSON object. | | `required` | Required field is missing. | | `unknown_field` | Field is not part of the v1 schema. | | `unsupported_version` | `parameterization_version` is not `v1`. | | `not_string` | Value must be a string. | | `invalid_length` | String length is outside the allowed range. | | `not_number` | Value must be a number. Booleans are rejected. | | `not_finite` | Number is NaN or infinite. | | `negative` | Number must be >= 0. | | `not_positive` | Number must be > 0. | | `invalid_range` | `*_min` is not less than `*_max`. | | `invalid_composition_order` | `composition_order` is not a permutation of `pan`, `home`, and `tilt`. | | `not_array` | Value must be an array. | | `invalid_size` | Array has the wrong number of items. | | `not_unit_vector` | `axis` is not a unit vector. | | `invalid_choice` | Value is not one of the allowed strings. | | `frame_order_mismatch` | `frame` does not match the axis position in `composition_order`. | | `constant_curve` | All non-constant `curve` coefficients are zero. | | `out_of_range` | `home_position` is outside the position-space range. | | `invalid_node` | Backlash node is not a `[position, degrees]` pair. | | `duplicate_position` | Backlash node repeats a position. | | `exceeds_travel` | Angular parameter exceeds the calibrated travel. | | `threshold_not_configured` | `PTZ_CALIBRATION_RESIDUAL_THRESHOLD_PX` is unset or not a finite positive number. | | `exceeds_threshold` | `reprojection_rms_px` exceeds the configured import threshold. | ### Home Pose The Manager camera record also exposes the read-only `pose_matrix`: the 4x4 camera-to-scene home pose matrix (row-major, scale included) computed by Manager for both Euler and point-correspondence cameras. It is present only when the camera belongs to a scene and has a pose. Positioning uses `pose_matrix` as `R_home` and the home translation; it does not rebuild the pose from the Euler `rotation` field. ### Camera Configuration Invalidation After a camera save commits, Manager publishes to `scenescape/cmd/camera/config/{camera_id}` at QoS 1, not retained: ```json { "calibration_version": "cam1-2026-10-01" } ``` `calibration_version` is `null` when the camera has no calibration. Manager publishes on every committed camera save, including cameras without calibration and saves that change only the home pose or scene. Moving a camera to another scene clears its `transforms`, so the home pose must be calibrated again. A rolled-back save publishes nothing. The message only invalidates cached state; Positioning reloads the camera through the Manager REST API and does not treat the payload as configuration. To onboard a PTZ camera, follow [Onboard PTZ Cameras](./how-to-guides/calibrate-cameras/onboard-ptz-cameras.md). ### Example For a simpler, zero-backlash synthetic model, see [Ideal Camera Example](#ideal-camera-example). The following example includes nonzero backlash. ```json { "parameterization_version": "v1", "calibration_version": "cam1-2026-10-01", "position_space": { "uri": "http://www.onvif.org/ver10/tptz/PanTiltSpaces/PositionGenericSpace", "pan_min": -1.0, "pan_max": 1.0, "tilt_min": -1.0, "tilt_max": 1.0 }, "settle_angular_threshold_deg": 0.05, "settle_interval_s": 0.5, "composition_order": ["pan", "home", "tilt"], "axes": { "pan": { "axis": [0, 0, 1], "frame": "world_home", "curve": [0, 180], "home_position": 0.0, "approach_direction": "increasing", "backlash": 0.1, "backlash_home_tolerance_deg": 0.2, "backlash_history_s": 10 }, "tilt": { "axis": [1, 0, 0], "frame": "camera_local", "curve": [0, -45], "home_position": 0.0, "approach_direction": "decreasing", "backlash": [ [-1.0, 0.1], [1.0, 0.15] ], "backlash_home_tolerance_deg": 0.2, "backlash_history_s": 10 } }, "quality": { "reprojection_rms_px": 1.2 } } ``` ### Ideal Camera Example Download [ideal-camera.example.json](./api-docs/positioning/v1/ideal-camera.example.json) for a complete, schema-compatible `ptz_calibration` block for documentation or simulation. Import it as the `ptz_calibration` field, not as a complete camera record. The static reference pose remains a separate Manager camera field. This hypothetical camera has perfectly aligned axes, linear travel, no backlash, and no optical-center translation during pan/tilt: | Parameter | Assumption | | ------------------ | --------------------------------------------------------------------- | | Raw home | Pan `0`, tilt `0`, matching the separately calibrated static pose | | Raw position space | The example URI with both ranges `[-1, 1]` | | Pan curve | `[0, 180]`: 180 degrees per raw unit, positive rotation about scene Z | | Tilt curve | `[0, 90]`: 90 degrees per raw unit, positive rotation about camera X | | Axis correction | None: unit axes `[0, 0, 1]` and `[1, 0, 0]` | | Backlash | `0` on both axes | | Reprojection RMS | `0` for this synthetic example only, not a hardware measurement | For this model, pan `0.1` and tilt `0.2` give: ```text R_live = Rz(18 degrees) * R_home * Rx(18 degrees) t_live = t_home ``` The polynomial is `angle(p) = c0 + c1*p + c2*p^2 + ...` in degrees. For an ideal linear camera, the constant term and higher-order corrections can be zero, but **the linear scale must not be zero**. `[0, 0]` means no orientation change regardless of movement and is rejected as `constant_curve`. If verified raw readings are already degrees, `[0, 1]` is the identity mapping; use the device's actual URI and degree ranges instead of the normalized example. The URI alone does not establish units, scale, or sign. Do not copy these assumed scales or signs to real cameras without validation. Use the actual advertised position space, reference home, measured scale/sign, and held-out reprojection residual. Do not enter zero RMS to bypass calibration acceptance. Zero backlash also does not disable settling, freshness, clock, reference-home initialization, or consumer dwell gates. Required approach directions, home tolerances, history durations, and settling parameters remain present; the positive timing/tolerance values in this file are illustrative.