PTZ Device API Discussion

[glikely]

PTZ Controls defines a public API that can be used by other plugins to either control PTZ Devices, or to implement new PTZ protocols that can be controled from the PTZ Controls dock.

The API specification is found here: PTZ Device API

This is a call to interested plugin authors. Please review the API and comment. The API is not locked down yet, so changes can be made.

[Trouffman]

At first (human) read it looks complete :).

For the state ( in preview or not) we had some discussion in DistroAV plugin, to send only the highest status, I think this the same approach here

Example:
If a source is in both preview and program, only program is sent. (/Set true).

Will look to implement in DistroAV as a POC.

[glikely]

The live and preview state bits are just bools. They can both be set when in both program and preview scenes. Not that it matters, "live" and "preview" state bits are really just front end UI state getting cached in the device where it doesn't need to be. I'm going to remove them. Ditto for the "locked" state bit.

Regarding tally, yes only one state is sent to the calendarcamera. If in preview: green. If in program: red. If in both: also red because program takes priority.

[glikely]

Will look to implement in DistroAV as a POC.

When you start prototyping, build obs-ptz from the main branch. All of the API is implemented, but I haven't included it in a release yet.

[vwout]

Defining behavior for preview and program is tricky indeed. I summarized it for my Visca Control script, see https://github.com/vwout/obs-visca-control#custom-command-action-execution-overview.

[glikely]

API has been updated to v0.2, refining the presets part of the API

[glikely]

The API has been updated to v0.6. Changes include adding a websockets binding, allowing controllers to address the current selected camera, and including real world coordinates (degrees, magnification, focus distance)

[vwout]

The API looks promising and covers quite some important features.

Some questions, that may have errors because I read the API quickly and not studied it for a day :)

• Most parameters like tilt, pan, zoom, focus, take a float ranging -1.0 .. 1.0; what is the associated range? The valued values for e.g. Visca vary from camera to camera model and are typically not retrievable via a Visca command. Is -1.0 / 1.0 the maximum theoretical value, or is it dynamically determined and can it be derived from the state key axes?
• Does the library handle sequencing of multiple actions; in other words: what happens when a Visca action is send to the library before the camera has ACK-ed or Completed the previous action?
• Zoom and focus are always combined with pan & tilt. In Visca these are separate independent commands. The API suggests these cannot be changed independently, also because all parameters seem to be non-nullable floats
• I suggest to make autofocus a dedicated API call rather than hiding this in 'state'
• Not all discovered features seem to have API actions to use the feature, like power on/off, tally control, whitebalance
• I'm missing calls for image control (shutter & diafragma, brightness and gain)
• Not all API calls are available on all protocols - I know Visca and not all commands (like retreiving the presets) are possible. Do you plan on creating a matrix what is technically supported (not including actual camera support)?

[glikely]

Thanks for taking a look. Good questions. Responses below

The API looks promising and covers quite some important features.

Some questions, that may have errors because I read the API quickly and not studied it for a day :)

• Most parameters like tilt, pan, zoom, focus, take a float ranging -1.0 .. 1.0; what is the associated range? The valued values for e.g. Visca vary from camera to camera model and are typically not retrievable via a Visca command. Is -1.0 / 1.0 the maximum theoretical value, or is it dynamically determined and can it be derived from the state key axes?

0.0..1.0 and -1.0..1.0 are normalized to the full range of the camera, whatever that camera actually provides. I'm following the lead of the ONVIF protocol here which does the same thing. The drivers handle mapping the normalized range to whatever the camera provides. e.g. the VISCA driver is configured with min/max visca steps. For mapping to real world coordinates, you are correct. The axes state key provides the details.

• Does the library handle sequencing of multiple actions; in other words: what happens when a Visca action is send to the library before the camera has ACK-ed or Completed the previous action?

Currently it is undefined for conflicting actions. e.g., sending a preset recall command and a move command at the same time it isn't clear what will happen. In PTZ Controls both commands will get sent to the camera, and the camera decides which takes precidence.

For drive commands sending multiple commands will just update the speed and direction, and the driver should coalesce multiple updates if they come too fast. That part isn't really defined in the API. The expectation is that backend drivers know how to manage the camera protocol, and will throttle if commands come too fast.

• Zoom and focus are always combined with pan & tilt. In Visca these are separate independent commands. The API suggests these cannot be changed independently, also because all parameters seem to be non-nullable floats

The can be changed independently. Each of the argument are optional. If the key (pan, tilt, zoom, focus) is present, then that axis should be changed. If a key is missing, then that axis is not changed. It can be clarified in the API that each of those keys are optional. The only exception is that pan and tilt are currently tied together, or at least they are in the PTZ Controls implementation. If pan is provided, then tilt will get updated too.

• I suggest to make autofocus a dedicated API call rather than hiding this in 'state'

I started with it as a separate api, but it looked just like a value setting. It seemed cleaner to have a generic api for setting values, whether it is autofocus state/mode, whitebalance mode, etc.

• Not all discovered features seem to have API actions to use the feature, like power on/off, tally control, whitebalance

ptz_request_state is intented to be the rollup API for changing camera state, which includes all of the above. Reading the document again I've missed documenting that detail.

• I'm missing calls for image control (shutter & diafragma, brightness and gain)

Like the above, ptz_request_state, ptz_get_state, ptz_state_changed is the rollup API for all of those parameters. The list of common state variables needs to be added to the doc.

• Not all API calls are available on all protocols - I know Visca and not all commands (like retreiving the presets) are possible. Do you plan on creating a matrix what is technically supported (not including actual camera support)?

Yes, the features state key lists the features supported by the protocol. A list of the features needs to be flushed out.