PTZ

PTZ service implementation.

`PTZ`

Bases: ONVIFService

PTZ service client.

Property	Details
First introduced	ONVIF Release 2.1 (June 2011) Split from Core 2.0
Binding name	`PTZBinding` (`ver20/ptz/wsdl/ptz.wsdl`)
Operations	ptz.wsdl
Specification	PTZ.xml

`GetServiceCapabilities()`

Returns the capabilities of the PTZ service.

The result is returned in a typed answer.

`GetConfigurations()`

Get all the existing PTZConfigurations from the device.

The default Position/Translation/Velocity Spaces are introduced to allow NVCs sending move requests without the need to specify a certain coordinate system.

The default Speeds are introduced to control the speed of move requests (absolute, relative, preset), where no explicit speed has been set.

The allowed pan and tilt range for Pan/Tilt Limits is defined by a two- dimensional space range that is mapped to a specific Absolute Pan/Tilt Position Space. At least one Pan/Tilt Position Space is required by the PTZNode to support Pan/Tilt limits. The limits apply to all supported absolute, relative and continuous Pan/Tilt movements. The limits shall be checked within the coordinate system for which the limits have been specified. That means that even if movements are specified in a different coordinate system, the requested movements shall be transformed to the coordinate system of the limits where the limits can be checked. When a relative or continuous movements is specified, which would leave the specified limits, the PTZ unit has to move along the specified limits. The Zoom Limits have to be interpreted accordingly.

`GetPresets(ProfileToken)`

Operation to request all PTZ presets for the PTZNode in the selected profile.

The operation is supported if there is support for at least on PTZ preset by the PTZNode.

`SetPreset(ProfileToken, PresetName=None, PresetToken=None)`

The SetPreset command saves the current device position parameters so that the device can move to the saved preset position through the GotoPreset operation.

In order to create a new preset, the SetPresetRequest contains no PresetToken. If creation is successful, the Response contains the PresetToken which uniquely identifies the Preset. An existing Preset can be overwritten by specifying the PresetToken of the corresponding Preset. In both cases (overwriting or creation) an optional PresetName can be specified. The operation fails if the PTZ device is moving during the SetPreset operation. The device MAY internally save additional states such as imaging properties in the PTZ Preset which then should be recalled in the GotoPreset operation.

`RemovePreset(ProfileToken, PresetToken)`

Operation to remove a PTZ preset for the Node in the selected profile.

The operation is supported if the PresetPosition capability exists for teh Node in the selected profile.

`GotoPreset(ProfileToken, PresetToken, Speed=None)`

Operation to go to a saved preset position for the PTZNode in the selected profile.

The operation is supported if there is support for at least on PTZ preset by the PTZNode.

`GetStatus(ProfileToken)`

Operation to request PTZ status for the Node in the selected profile.

`GetConfiguration(PTZConfigurationToken)`

Get a specific PTZconfiguration from the device, identified by its reference token or name.

The default Position/Translation/Velocity Spaces are introduced to allow NVCs sending move requests without the need to specify a certain coordinate system.

The default Speeds are introduced to control the speed of move requests (absolute, relative, preset), where no explicit speed has been set.

The allowed pan and tilt range for Pan/Tilt Limits is defined by a two- dimensional space range that is mapped to a specific Absolute Pan/Tilt Position Space. At least one Pan/Tilt Position Space is required by the PTZNode to support Pan/Tilt limits. The limits apply to all supported absolute, relative and continuous Pan/Tilt movements. The limits shall be checked within the coordinate system for which the limits have been specified. That means that even if movements are specified in a different coordinate system, the requested movements shall be transformed to the coordinate system of the limits where the limits can be checked. When a relative or continuous movements is specified, which would leave the specified limits, the PTZ unit has to move along the specified limits. The Zoom Limits have to be interpreted accordingly.

`GetNodes()`

Get the descriptions of the available PTZ Nodes.

A PTZ-capable device may have multiple PTZ Nodes. The PTZ Nodes may represent mechanical PTZ drivers, uploaded PTZ drivers or digital PTZ drivers. PTZ Nodes are the lowest level entities in the PTZ control API and reflect the supported PTZ capabilities. The PTZ Node is referenced either by its name or by its reference token.

`GetNode(NodeToken)`

Get a specific PTZ Node identified by a reference token or a name.

`SetConfiguration(PTZConfiguration, ForcePersistence)`

Set/update a existing PTZConfiguration on the device.

`GetConfigurationOptions(ConfigurationToken)`

List supported coordinate systems including their range limitations.

Therefore, the options MAY differ depending on whether the PTZ Configuration is assigned to a Profile containing a Video Source Configuration. In that case, the options may additionally contain coordinate systems referring to the image coordinate system described by the Video Source Configuration. If the PTZ Node supports continuous movements, it shall return a Timeout Range within which Timeouts are accepted by the PTZ Node.

`GotoHomePosition(ProfileToken, Speed=None)`

Operation to move the PTZ device to it's "home" position.

The operation is supported if the HomeSupported element in the PTZNode is true.

`SetHomePosition(ProfileToken)`

Operation to save current position as the home position.

The SetHomePosition command returns with a failure if the "home" position is fixed and cannot be overwritten. If the SetHomePosition is successful, it is possible to recall the Home Position with the GotoHomePosition command.

`ContinuousMove(ProfileToken, Velocity, Timeout=None)`

Operation for continuous Pan/Tilt and Zoom movements.

The operation is supported if the PTZNode supports at least one continuous Pan/Tilt or Zoom space. If the space argument is omitted, the default space set by the PTZConfiguration will be used.

`RelativeMove(ProfileToken, Translation, Speed=None)`

Operation for Relative Pan/Tilt and Zoom Move.

The operation is supported if the PTZNode supports at least one relative Pan/Tilt or Zoom space.

The speed argument is optional. If an x/y speed value is given it is up to the device to either use the x value as absolute resoluting speed vector or to map x and y to the component speed. If the speed argument is omitted, the default speed set by the PTZConfiguration will be used.

`AbsoluteMove(ProfileToken, Position, Speed=None)`

Operation to move pan,tilt or zoom to a absolute destination.

The speed argument is optional. If an x/y speed value is given it is up to the device to either use the x value as absolute resoluting speed vector or to map x and y to the component speed. If the speed argument is omitted, the default speed set by the PTZConfiguration will be used.

`GeoMove(ProfileToken, Target, Speed=None, AreaHeight=None, AreaWidth=None)`

Operation to move pan,tilt or zoom to point to a destination based on the geolocation of the target.

The speed argument is optional. If an x/y speed value is given it is up to the device to either use the x value as absolute resoluting speed vector or to map x and y to the component speed. If the speed argument is omitted, the default speed set by the PTZConfiguration will be used. The area height and area dwidth parameters are optional, they can be used independently and may be used by the device to automatically determine the best zoom level to show the target.

`Stop(ProfileToken, PanTilt=None, Zoom=None)`

Operation to stop ongoing pan, tilt and zoom movements of absolute relative and continuous type.

If no stop argument for pan, tilt or zoom is set, the device will stop all ongoing pan, tilt and zoom movements.

`SendAuxiliaryCommand(ProfileToken, AuxiliaryData)`

Operation to send auxiliary commands to the PTZ device mapped by the PTZNode in the selected profile.

The operation is supported if the AuxiliarySupported element of the PTZNode is true

`GetPresetTours(ProfileToken)`

Operation to request PTZ preset tours in the selected media profiles.

`GetPresetTour(ProfileToken, PresetTourToken)`

Operation to request a specific PTZ preset tour in the selected media profile.

`GetPresetTourOptions(ProfileToken, PresetTourToken=None)`

Operation to request available options to configure PTZ preset tour.

`CreatePresetTour(ProfileToken)`

Operation to create a preset tour for the selected media profile.

`ModifyPresetTour(ProfileToken, PresetTour)`

Operation to modify a preset tour for the selected media profile.

`OperatePresetTour(ProfileToken, PresetTourToken, Operation)`

Operation to perform specific operation on the preset tour in selected media profile.

`RemovePresetTour(ProfileToken, PresetTourToken)`

Operation to delete a specific preset tour from the media profile.

`GetCompatibleConfigurations(ProfileToken)`

Operation to get all available PTZConfigurations that can be added to the referenced media profile.

A device providing more than one PTZConfiguration or more than one VideoSourceConfiguration or which has any other resource interdependency between PTZConfiguration entities and other resources listable in a media profile should implement this operation. PTZConfiguration entities returned by this operation shall not fail on adding them to the referenced media profile.

`MoveAndStartTracking(ProfileToken, ObjectID, PresetToken=None, GeoLocation=None, TargetPosition=None, Speed=None)`

Operation to send an an atomic command to the device: move the camera to a wanted position and then delegate the PTZ control to the tracking algorithm.

An existing Speed argument overrides DefaultSpeed of the corresponding PTZ configuration during movement to the requested position. If spaces are referenced within the Speed argument, they shall be speed spaces supported by the PTZ node.

If the detection and the tracking are done in the same device, an ObjectID reference can be passed as an argument, in order to specify which object should be tracked.

The operation shall fail if the requested absolute position is not reachable.