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 inptz.protoin the protobuf packagescenescape.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.protodocs/user-guide/api-docs/positioning/v1/ptz_calibration.schema.json
MQTT Pose and Status Contracts#
Topic |
Publisher |
QoS / retain |
Payload |
|---|---|---|---|
|
Positioning |
0 / retained |
|
|
Positioning |
0 / retained with offline LWT |
|
|
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 |
|---|---|---|
|
|
|
Note: In v1, the ONVIF poller passes samples to the Positioning service in-process. The
PTZPoseIngestservice is reserved for a future authenticated external producer and is not exposed on the network.
Message PTZSample#
# |
Field |
Type |
Description |
|---|---|---|---|
1 |
|
|
Manager camera UID. |
2 |
|
|
Identifies the poller instance. Changes on every poller restart. |
3 |
|
|
Monotonically increasing within one |
4 |
|
|
Midpoint of the ONVIF request/response interval. |
5 |
|
|
Uncertainty of |
6 |
|
|
Raw position reported by the device. |
7 |
|
|
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 |
|
|
Raw pan position. |
2 |
|
|
Raw tilt position. |
3 |
|
|
Raw zoom position, if the camera reports it. |
4 |
|
|
ONVIF position space URI. |
5 |
|
|
Lower bound of the pan range. |
6 |
|
|
Upper bound of the pan range. |
7 |
|
|
Lower bound of the tilt range. |
8 |
|
|
Upper bound of the tilt range. |
Enum ReportedMoveStatus#
Value |
Name |
|---|---|
0 |
|
1 |
|
2 |
|
Message PTZSampleAck#
# |
Field |
Type |
Description |
|---|---|---|---|
1 |
|
|
Outcome of the submission. |
2 |
|
|
Human-readable detail, for example the reason a sample was rejected. |
3 |
|
|
Sequence number of the sample. |
Enum PTZSampleResult#
Value |
Name |
Meaning |
|---|---|---|
0 |
|
Not set. |
1 |
|
The sample was accepted. |
2 |
|
A sample with this |
3 |
|
|
4 |
|
|
5 |
|
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 |
|---|---|---|---|
|
string |
Yes |
Must be |
|
string |
Yes |
Identifier of this calibration, 1 to 128 characters. |
|
object |
Yes |
ONVIF position space the calibration was measured in. See Position Space. |
|
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. |
|
number |
Yes |
Time, in seconds, the position must stay within the threshold to count as settled. Must be > 0. |
|
array |
Yes |
Permutation of |
|
object |
Yes |
Object with |
|
object |
Yes |
Contains |
|
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.
Position Space#
Field |
Type |
Required |
Description |
|---|---|---|---|
|
string |
Yes |
ONVIF position space URI, 1 to 512 characters. |
|
number |
Yes |
Lower bound of the pan range. |
|
number |
Yes |
Upper bound of the pan range. |
|
number |
Yes |
Lower bound of the tilt range. |
|
number |
Yes |
Upper bound of the tilt range. |
Axis#
All fields are required.
Field |
Type |
Description |
|---|---|---|
|
array of 3 numbers |
Rotation axis as a unit vector, expressed in |
|
string |
|
|
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. |
|
number |
Raw ONVIF position at the calibrated home pose. |
|
string |
|
|
number or array |
Total gear slack in degrees. Either one value (>= 0), or 1 to 64 |
|
number |
When backlash state is unknown, for example after a restart, the service initializes it from |
|
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
axisis a unit vector.Each
*_minvalue is less than the matching*_maxvalue.home_positionis inside the axis range.Each axis
framematches its place incomposition_order.backlashnodes have distinct positions.settle_angular_threshold_degand eachbacklash_home_tolerance_degdo not exceed the calibrated travel: the angular span of the axiscurveover itsposition_spacerange.
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
<path>: <code> string; clients should match on it rather than on free text:
{ "ptz_calibration": ["axes.pan.axis: not_unit_vector"] }
<path> is the dotted field path; backlash nodes use an index, for example
axes.tilt.backlash[1].
Code |
Meaning |
|---|---|
|
Value must be a JSON object. |
|
Required field is missing. |
|
Field is not part of the v1 schema. |
|
|
|
Value must be a string. |
|
String length is outside the allowed range. |
|
Value must be a number. Booleans are rejected. |
|
Number is NaN or infinite. |
|
Number must be >= 0. |
|
Number must be > 0. |
|
|
|
|
|
Value must be an array. |
|
Array has the wrong number of items. |
|
|
|
Value is not one of the allowed strings. |
|
|
|
All non-constant |
|
|
|
Backlash node is not a |
|
Backlash node repeats a position. |
|
Angular parameter exceeds the calibrated travel. |
|
|
|
|
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:
{ "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.
Example#
For a simpler, zero-backlash synthetic model, see Ideal Camera Example. The following example includes nonzero backlash.
{
"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
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 |
Raw position space |
The example URI with both ranges |
Pan curve |
|
Tilt curve |
|
Axis correction |
None: unit axes |
Backlash |
|
Reprojection RMS |
|
For this model, pan 0.1 and tilt 0.2 give:
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.