Pan/tilt/zoom API

Description

The PTZ API is used to configure and control the pan, tilt and zoom (PTZ) functionality in Axis network cameras and video encoders. PTZ functionality is available in most camera models. Cameras categorized as PTZ cameras have mechanical PTZ functionality while other cameras can have view areas with digital PTZ. Cameras and video encoders with serial ports can be connected to external devices, for example pan-tilt motors, that provide PTZ functionality. To control the external PTZ device, a PTZ driver must be uploaded.

For cameras with view areas and video encoders with multiple video channels, the PTZ functionality is configured and controlled for each view area or video channel (referred to as a camera in the API) separately.

The PTZ API consists of:

PTZ control API

Configure and control the PTZ functionality. See PTZ control API.

PTZ driver management API

Upload, remove, list, activate and deactivate PTZ drivers. See PTZ driver management API.

Queueing API

Configure and control the PTZ control queue. See Queuing API.

See also PTZ events and actions.

In addition to PTZ functionality, the API also includes parameters for IR cut filter (day and night functionality), backlight compensation, focus, brightness and iris.

PTZ parameter and CGI functionality

Each functionality (for example pan) uses Support parameters (see PTZ.Support) to check if the functionality is supported, uses Various parameters (see PTZ.Various) to check if functionality is enabled and to disable functionality, and use CGIs (see PTZ control) to control the functionality.

Definitions

TermDefinition
Digital PTZPTZ without moving parts. PTZ “movements” are done by dynamically changing crop section on the image sensor.
Mechanical PTZMechanical PTZ is driven by motors. The motors could either be integrated in the Axis product or the Axis product could be mounted on a external mechanical PT (PanTilt) device. It could also be an external PTZ camera connected to an encoder.
Panopsis technology

Panopsis technology is used by mechanical PTZ domes that in addition to the standard zoom lens have a Panopsis (fisheye) lens attached to the dome cover.

A product with Panopsis technology can be used in two modes. In Overview mode, the zoom lens is fully zoomed out and points straight down (-90 degrees tilt) looking through the Panopsis lens. This gives a 360-degree overview image. In Normal mode, the zoom lens avoids the Panopsis lens and the product works as a standard mechanical PTZ dome. Note that some PTZ commands cannot be used or do not have any effect in Overview mode.

Absolute movementMove to a specific coordinate position, for example “move to -45°”.
Relative movementMove a specific distance from the current position, for example “move left 15°”.
Continuous movementMove in a specific direction (until stopped), for example “move down”.
Auto-flipThe auto-flip functionality allows the camera to simulate a continuous pan beyond the mechanical stop, thereby enabling an operator to continuously follow an object.
Static PTZ driverA PTZ driver is built into the firmware and is always running. Typically used on domes and digital PTZ.
Uploadable PTZ driverA PTZ driver that can be uploaded and installed to a running Axis product.

Common examples

Check if PTZ is available.

//myserver/axis-cgi/param.cgi?action=list&group=Properties.PTZ.PTZ

Verify that PTZ is enabled on channel 1:

//myserver/axis-cgi/com/ptz.cgi?info=1&camera=1 

A successful response should look similar or the same to the response in Success for info=1.

Request information about which PTZ commands that are available for camera=1. For the response see example in section PTZ control.

//myserver/axis-cgi/com/ptz.cgi?info=1&camera=1

Pan camera=3 to the right, 10 degrees.

//myserver/axis-cgi/com/ptz.cgi?rpan=10&camera=3

Set a home position named "MyPreset" at the current location for the Axis product.

//myserver/axis-cgi/com/ptzconfig.cgi?setserverpresetname=MyPreset&home=yes

Enable PTZ on video channel number 3 on an Axis product with digital PTZ. For digital PTZ, PTZ.ImageSource.I0.PTZEnabled is controlling all video channel. Each video channel has a PTZ.Various.V#.Locked parameter.

//myserver/axis-cgi/param.cgi?PTZ.ImageSource.I0.PTZEnabled=yes&PTZ.Various.V3.Locked=false

Check if a product supports upload and installation of drivers.

//myserver/axis-cgi/param.cgi?action=list&group=Properties.PTZ.DriverManagement

Upload a driver with the driver file contents as HTTP POST data (see PTZ driver upload for details).

//myserver/axis-cgi/ptz/ptzuploader.cgi

A driver ID is returned in the HTTP response, for example 7.

<?xml version=1"1.0"?>
<root>
  <id>7</id>
</root>

Install the uploaded driver with ID 7 on video channel 3.

//myserver/axis-cgi/ptz/ptzupgrader.cgi?driverid=7&channel=3

PTZ control API

Description

There are two types of PTZ, mechanical PTZ and digital PTZ. Mechanical PTZ is driven by motors. The motors could either be integrated in the Axis product or the Axis product could be mounted on a external mechanical PT (PanTilt) device. It could also be an external PTZ camera connected to an encoder. For Axis products with digital PTZ it is possible to select only a part of the image by zooming in. The zoomed area can then be moved around using pan/tilt commands. Digital PTZ uses the same HTTP API as Axis products with mechanical PTZ, with some limitations.

The PTZ Control API consists of the following CGIs:

ptz.cgiControl the PTZ movement.
ptzconfig.cgiConfigure the PTZ functionality.
ptzqueue.cgiControl the PTZ control queuing mechanism.

Prerequisites

Identification

API Discovery

id=ptz-control

Property

Properties.API.HTTP.Version=3

Property

Properties.API.PTZ.Presets.Version=2.00 (The index for the preset that is the device's home position at start-up or when calling ptz.cgi?move=home)

Property

Properties.PTZ.PTZ=yes

Property

Properties.PTZ.DigitalPTZ=yes (Products with digital PTZ)

Property

Properties.Overview.Overview=yes (Products with Panopsis technology)

Property

Properties.Overview.MechanicalHybrid=yes (Products with Panopsis technology)

Property

Properties.PTZ.EmbeddedDrivers=yes(For when all previously uploadable ptz drivers are embedded in the camera firmware instead of externally published. This also means that it is not possible to upload any ptz drivers.)

Firmware

5.20 and later.

Parameters

PTZ

Various Pan tilt zoom parameters. All writable parameters may be directly modified.

PTZ
ParameterDefault valuesValid valuesAccess controlDescription
BoaProtPTZOperatorpasswordpassword
anonymous
admin: read, write
operator: read
viewer: read
password = Password is required to control PTZ units and to use control queue.
anonymous = Anybody on the network have access to PTZ units without having to log in.
CameraDefault11 ... n (1)admin: read, write
operator: read
viewer: read
The video channel used if the camera parameter is omitted in HTTP requests.
ResponseEncodingiso-8859–1iso-8859–1
utf-8
admin: read, write
operator: read
viewer: read
The character encoding that should be used for the plain-text responses of the preset queries.
NbrOfCamerasProduct specific1 ...admin: read
operator: read
Number of video channels.
NbrOfSerPortsProduct specific0 ...admin: read
operator: read
viewer: read
Number of serial ports.
  1. n = Number of video channels.

PTZ.ImageSource

This group contains a parameter for turning on/off PTZ functionality.

Toggling this parameter does not install/uninstall any driver.

PTZ.ImageSource.I#
ParameterDefault valuesValid valuesAccess controlDescription
PTZEnabledMechanical PTZ: true
Digital PTZ: false
true
false
admin: read, write
operator: read, write
viewer: read
Mechanical PTZ = Enable/disable the PTZ functionality of the video channel.

true = Enable the PTZ functionality of the video channel.
false = Disable the PTZ functionality of the video channel.

Digital PTZ = Enable/disable the PTZ functionality on the Axis product.

true = Enable the PTZ functionality on the Axis product.
false = Disable the PTZ functionality on the Axis product.

When this parameter is changed to false, the product returns to a default PTZ position (in contrast to the parameter PTZ.Various.V#.Locked, for which the position is locked when the parameter is set to true).
Note
For mechanical PTZ, the index # in PTZ.ImageSource.I# is the index of the video channel, starting on 0 for video channel 1. For digital PTZ, there is one group PTZ.ImageSource.I0, and the parameter PTZ.ImageSource.I0.PTZEnabled is used for enabling/disabling PTZ on all channels.

PTZ.PTZDriverStatuses

This group contains a parameter that informs about the current status of the drivers installed on the Axis product.

PTZ.PTZDriverStatuses
ParameterDefault valuesValid valuesAccess controlDescription
Driver#Status 0 ... 3admin: read
operator: read
viewer: read
The status of the driver installed on camera # , where # starts on 1 for video channel 1. The value should be interpreted as:

0 = No driver installed.
1 = Installation file invalid or incompatible.
2 = Driver malfunction.
3 = Driver installed.

PTZ.Support

The dynamic parameter group PTZ.Support.S# is updated when a driver is installed on a video channel. A parameter in the group has the value true if the corresponding capability is supported by the driver. The index # is the video channel number which starts from 1.

An absolute operation means moving to a certain position, a relative operation means moving relative to the current position. Arguments referred to apply to PTZ control.

PTZ.Support.S#
Parameter Default valuesValid valuesAccess controlDescription
AbsolutePanProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Absolute pan is supported by the driver.
false = Absolute pan is disabled/not supported.
RelativePanProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Relative pan is supported by the driver.(1)
false = Relative pan is disabled/not supported.
AbsoluteTiltProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Absolute tilt is supported by the driver.
false = Absolute tilt is disabled/not supported.
RelativeTiltProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Relative tilt is supported by the driver.(1)
false = Relative tilt is disabled/not supported.
AbsoluteZoomProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Absolute zoom is supported by the driver.(1)
false = Absolute zoom is disabled/not supported.
RelativeZoomProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Relative zoom is supported by the driver.(1)
false = Relative zoom is disabled/not supported.
DigitalZoomProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Digital zoom is supported (increases the upper limit of PTZ.Limit.L#.MaxZoom to 19999) by the driver.(1)
false = Digital zoom is disabled/not supported.
AreaZoomProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Area zoom is supported by the driver.(1)
false = Area zoom is disabled/not supported.
AbsoluteFocusProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Absolute focus is supported by the driver.(1)
false = Absolute focus is disabled/not supported.
RelativeFocusProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Relative focus is supported by the driver.(1)
false = Relative focus is disabled/not supported.
AutoFocusProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Autofocus is supported by the driver.
false = Autofocus is disabled/not supported.
AbsoluteIrisProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Absolute iris is supported by the driver.
false = Absolute iris is disabled/not supported.
RelativeIrisProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Relative iris is supported by the driver.
false = Relative iris is disabled/not supported.
AutoIrisProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Auto iris is supported by the driver.
false = Auto iris is disabled/not supported.
AbsoluteBrightnessProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Absolute brightness is supported by the driver.
false = Absolute brightness is disabled/not supported.
RelativeBrightnessProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Relative brightness is supported by the driver.
false = Relative brightness is disabled/not supported.
ContinuousPanProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Continuous pan is supported by the driver.
false = Continuous pan is disabled/not supported.
ContinuousTiltProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Continuous tilt is supported by the driver.
false = Continuous tilt is disabled/not supported.
ContinuousZoomProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Continuous zoom is supported by the driver.(1)
false = Continuous zoom is disabled/not supported.
ContinuousFocusProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Continuous focus is supported by the driver.(1)
false = Continuous focus is disabled/not supported.
ContinuousIrisProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Continuous iris is supported by the driver.
false = Continuous iris is disabled/not supported.
ContinuousBrightnessProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Continuous brightness is supported by the driver.
false = Continuous brightness is disabled/not supported.
AuxiliaryProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = CGI argument auxiliary (com/ptz.cgi?auxiliary=<string>)is supported by the driver.
false = CGI argument auxiliary is disabled/not supported.
ServerPresetProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Server presets are supported by the driver.
false = Server presets are disabled/not supported.
DevicePresetProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Device presets are supported by the driver.
false = Device preset are disabled/not supported.
SpeedCtlProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Speed control is supported by the driver.
false = Speed control is disabled/not supported.
IrCutFilterProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = IR cut filter is supported by the driver.
false = IR cut filter is disabled/not supported.
AutoIrCutFilterProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = The IR cut filter can be controlled automatically.
false = Automatic IR cut filter is disabled/not supported.
BacklightProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Backlight compensation is supported by the driver.
false = Backlight compensation is disabled/not supported.
OSDMenuProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = OSD menu is supported by the driver.
false = OSD menu is disabled/not supported.
ActionNotificationProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
Value is true if the PTZ driver can send messages to other internal applications when it starts or stops movements. Makes it possible to trigger events on arrival to a preset position.


true = Action notification is supported.
false = Action notification is disabled/not supported.
ProportionalSpeedProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
Value is true if the product supports proportional speed when using the command continuouspantiltmove, for example adjusting the movement speed in the image proportional to the zoom level used.(2)


true = Proportional speed is supported.
false = Proportional speed is disabled/not supported.
LensOffsetProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Lens offset is supported by the driver.
false = Lens offset is disabled/not supported.
  1. Products with Panopsis technology: Even if supported, functionality cannot be used in Overview mode.
  2. Proportional speed has the option to be disabled for individual continuous move commands For more information, see PTZ control.

PTZ.Limit

This dynamic group is updated when a driver is installed on a video channel. Index # is the video channel number, starting on 1. When it is possible to obtain the current position from the driver, for example the current pan position, it is possible to apply limit restrictions to the requested operation. For instance, if an absolute pan to position 150 is requested, but the upper limit is set to 140, the new pan position will be 140. This is the purpose of all but MinFieldAngle and MaxFieldAngle in this group. The purpose of those two parameters is to calibrate image centering.

PTZ.Limit.L#
ParameterDefault valuesValid values(1)Access controlDescription
MinPanProduct/driver dependent-180 ... 180admin: read, write
operator: read
viewer: read
Lower limit for pan position.
MaxPanProduct/driver dependent-180 ... 180admin: read, write
operator: read
viewer: read
Upper limit for pan position.
MinTiltProduct/driver dependent-180 ... 180admin: read, write
operator: read
viewer: read
Lower limit for tilt position.
MaxTiltProduct/driver dependent-180 ... 180admin: read, write
operator: read
viewer: read
Upper limit for tilt position.
MinZoomProduct/driver dependent1 ... 9999(2)admin: read, write
operator: read
viewer: read
Lower limit for zoom position.
MaxZoomProduct/driver dependent1 ... 9999(2)admin: read, write
operator: read
viewer: read
Upper limit for zoom position.
MinFocusProduct/driver dependent1 ... 9999admin: read, write
operator: read
viewer: read
Lower limit for focus position.
MaxFocusProduct/driver dependent1 ... 9999admin: read, write
operator: read
viewer: read
Upper limit for focus position.
MinIrisProduct/driver dependent1 ... 9999admin: read, write
operator: read
viewer: read
Lower limit for iris position.
MaxIrisProduct/driver dependent1 ... 9999admin: read, write
operator: read
viewer: read
Upper limit for iris position.
MinBrightnessProduct/driver dependent1 ... 9999admin: read, write
operator: read
viewer: read
Lower limit for brightness position.
MaxBrightnessProduct/driver dependent1 ... 9999admin: read, write
operator: read
viewer: read
Upper limit for brightness position.
MinFieldAngleProduct/driver dependent1 ... 1000admin: read, write
operator: read
viewer: read
Minimum field angle for the (zoom) lens, used to calibrate image centering.
MaxFieldAngle Product/driver dependent1 ... 1000admin: read, write
operator: read
viewer: read
Maximum field angle for the (zoom) lens, used to calibrate image centering.
  1. May be overridden by configuration file for driver. Maximal value must be ≥ minimal value.
  2. If digital zoom is supported (see PTZ.Support.S#.DigitalZoom in section PTZ.Support), MaxZoom can have values up to 19999.

PTZ.Various

The dynamic parameter group PTZ.Various.V# is updated when a driver is installed on a video channel. The index # is the video channel number which starts from 1.

The group consists of several different types of parameters for the video channel. To distinguish the parameter types, the group is presented as three different categories below.

The Enabled parameters determine if a specific feature can be controlled using ptz.cgi (see section PTZ control).

PTZ.Various.V#
Parameter Default valuesValid values(1)Access controlDescription
PanEnabledProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Pan is allowed.
false = Pan is not allowed.
TiltEnabledProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Tilt is allowed.
false = Tilt is not allowed.
ZoomEnabledProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Zoom is allowed.(2)
false = Zoom is not allowed.
FocusEnabledProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Focus is allowed.(2)
false = Focus is not allowed.
IrisEnabledProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Iris is allowed.
false = Iris is not allowed.
BrightnessEnabledProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Brightness is allowed.
false = Brightness is not allowed.
IrCutFilterEnabledProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = IR cut filter is allowed.
false = IR cut filter is not allowed.
BackLightEnabledProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Backlight compensation is allowed.
false = Backlight compensation is not allowed.
SpeedCtlEnabledProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Pan/tilt speed adjustment is allowed.
false = Pan/tilt speed adjustment is not allowed.
ProportionalSpeedEnabledProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Proportional speed is allowed. This function is adjusting the movement speed in the image proportional to the zoom level used.
false = Proportional speed is not allowed.
  1. Integer ranges may be overridden by configuration file for driver.
  2. Products with Panopsis technology: Cannot be used in Overview mode.

The default parameters set the default value for a specific function in the driver.

PTZ.Various.V#
Parameter Default valuesValid values(1)Access controlDescription
AutoFocusProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Autofocus is on by default.
false = Autofocus is off by default.
AutoIrisProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Autoiris is on by default.
false = Autoiris is off default.
IrCutFilterProduct/driver dependenton
off
auto(2)
admin: read, write
operator: read
viewer: read
on = Default value for IR cut filter is on, that is, the filter will block IR light (daytime use).
off = Default value for IR cut filter is off, that is, the filter allows IR light (nighttime use).
auto = Default value for IR cut filter is auto, that is, the filter automatically switches between on and off depending on the lighting conditions.
BackLightProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = Backlight compensation is on by default.
false = Backlight compensation is off by default.
  1. Integer ranges may be overridden by configuration file for driver.
  2. Only valid if PTZ.Support.S#.AutoIrCutFilter is true.

The various parameters have different types of functions.

PTZ.Various.V#
Parameter Default valuesValid values(1)Access controlDescription
CamIdProduct/driver dependentAn integeradmin: read, write
operator: read
viewer: read
Identifies an external PTZ device on a serial port, often set by a dip switch on the external device.
DeviceTypeProduct/driver dependentA string admin: read, write
operator: read
viewer: read
A driver for an external device may support several variants of the device. Select the matching device type for best compatibility.
LockedProduct/driver dependenttrue
false
admin: read, write
operator: read
viewer: read
true = The PTZ position is locked, that is, the position cannot be changed using PTZ commands.
false = The PTZ position is unlocked.
LensOffsetXProduct/driver dependent-9999 ... 9999admin: read, write
operator: read
viewer: read
X coordinate of sensor center to lens center vector. Unit is 1/10000 of the sensor width. Used by the areazoom argument. Only applicable if the driver supports lens offset.
LensOffsetYProduct/driver dependent-9999 ... 9999admin: read, write
operator: read
viewer: read
Y coordinate of sensor center to lens center vector. Unit is 1/10000 of the sensor height. Used by the areazoom argument. Only applicable if the driver supports lens offset.
ReturnToOverviewProduct/driver dependent0 ... 300admin: read, write
operator: read
viewer: read
Idle timeout; if there is no PTZ activity for this number of seconds, the video channel returns to its home position. The value 0 means that the idle timeout functionality is turned off.
MaxProportionalSpeedProduct/driver dependent1 ... 1000admin: read, write
operator: read
viewer: read
Set the maximum continuous movement speed in 1/100 of fields of view per second.

Example: 200 = Max 2.00 fields of view per second.
  1. Integer ranges may be overridden by configuration file for driver.

PTZ.UserBasic

This dynamic group is updated when a driver is installed on a video channel. Index # is the video channel number, starting on 1. The parameters in these groups are driver dependent and are hence not known in advance. They are described on the help pages that come with the driver installation.

ParameterDefault valuesValid valuesDescription
FlipPanfalsetrue
false
Controls if the relative pan operations are inverted.
true: The relative pan movements are inverted.
false: The relative pan movements are not inverted.
FlipTiltfalsetrue
false
Controls if the relative tilt operations are inverted.
true: The relative tilt movements are inverted.
false: The relative tilt movements are not inverted.

PTZ.UserAdv

This dynamic group is updated when a driver is installed on a video channel. Index # is the video channel number, starting on 1. The parameters in these groups are driver dependent and are hence not known in advance. Some of the parameters (described below) are supported by most drivers. For the rest of the parameters not described in this section please refer to the help pages that come with the driver installation.

The following parameter is supported by all products where PTZ.Support.SpeedCtl=true.

PTZ.UserAdv
ParameterDefault valuesValid valuesAccess controlDescription
MoveSpeed1001 ... 100admin: read, write
operator: read
viewer: read
Set the default move speed for absolute and relative pan/tilt movements. Can be overridden with the speed argument in the PTZ control HTTP API, see section PTZ control.

The following parameters are supported by most PTZ domes, however please note that some of the parameters are product specific.

PTZ.UserAdv
ParameterDefault valuesValid valuesAccess controlDescription
ImageFreezeoffoff
on
auto
admin: read, write
operator: read
viewer: read
Freeze the image while the Axis product is moving during a pan, tilt or zoom operation


off = Image freeze is turned off.
on = Freeze on all movements.
auto = Freeze only when going to presets.
AutoFliptruetrue
false
admin: read, write
operator: read
viewer: read
Simulate continuous pan movement in the same direction. See Definitions for further information.


true = Auto flip is enabled.
false = Auto flip is disabled.
MovePredictionfalsetrue
false
admin: read, write
operator: read
viewer: read
The Axis product attempts to predict the new position in the pan movement, after compensating for the slight delay while the Axis product changes direction after an auto flip.


true = Move prediction is enabled.
false = Move prediction is disabled.
AutoCalibrationtruetrue
false
admin: read, write
operator: read
viewer: read
Enable auto calibration which automatically resets the components of the camera, pan and tilt if a hardware error occurs.


true = Auto calibration is enabled.
false = Auto calibration is disabled.
DeviceStatuscam=ok,pan=ok,tilt=okcomponent=status
[,component=status...]
admin: read, write
operator: read
viewer: read
Shows the status of the camera(1) , pan and tilt hardware components. The values are shown as a comma separated list of component=status where statuscan be ok or error[code] where [code] is a 4 digit hexadecimal value.


cam = Status for the camera.
pan = Status for pan.
tilt = Status for tilt.
LastTestDateA string A string [date time year]admin: read, write
operator: read
viewer: read
Get the date and time for the most recent reset, manually or by AutoCalibration.
DeviceModVerProduct dependentmodel:[model_id], version:[version_nbr]admin: read, write
operator: read
viewer: read
Auto detected identifications of internal hardware component model and version. The values are presented as 4 digit hexadecimal values.


model = Internal hardware component for model.
version = Internal hardware component for version.
QuickZoomtruetrue
false
admin: read, write
operator: read
viewer: read
Controls if quick zoom should be turned on or off.
true: The camera zooms using quick zoom.
false: The camera zooms at normal speed using focus tracing.
TiltIlluminationtruetrue
false
admin: read, write
operator: read
viewer: read
Controls if the tilt angle may be used to dim the IR illumination if there is a risk of the IR light being reflected back into the camera.
true: The tilt angle may dim the IR illumination to avoid reflections.
false: The IR illumination is independent of the tilt angle.
OneShotAFfalsetrue
false
admin: read, write
operator: read
viewer: read
Controls if a new AutoFocus (AF) should be a one shot and only triggered after a PTZ movement.
true: A new AF search is only triggered when a pan/tilt/zoom movement has finished.
false: A new AF search is triggered whenever the scene changes, even when there is no PTZ movement.
CameraHousingConfigurationdefaultdefault
inverted
admin: read, write
operator: read
viewer: read
Stores information on how the camera housing is mounted on your PT unit. Please note that changing this parameter will automatically switch and invert the sign of the up and down parameters and change the valid tilt limit range for default: -90 to +45 and inverted: -45 to +90.
default: The camera housing is mounted upright on the PT unit.
inverted: The camera housing is mounted in reverse on the PT unit.
IlluminatorType[IL1|IL2]nonenone
ir
white
admin: read, write
operator: read
viewer: read
Gets set when any illuminator gets mounted on your PT unit which makes it controllable from the system.
none: No light has been mounted.
ir: An IR illuminator has been mounted. The IR lights can be turned on with the auxiliary command tt:LightIR|On and off with tt:LightIR|Off.
white: A white light illuminator has been mounted. The white lights can be turned on with the auxiliary command tt:LightWL|On and off with tt:LightWL|Off.
IRSynchCameraDayNightSwitchfalsetrue
false
admin: read, write
operator: read
viewer: read
Controls the on/off switch of any attached IR illuminators based on the day/night mode.
true: The IR illuminator will be turned on if the camera has gone into night mode and turned off in day mode.
false: The IR illuminator is independent of day/night mode
NozzlePositionfalsetrue
false
admin: read, write
operator: read
viewer: read
Stores the current PT position as the washing position in NozzlePresetData and enables the washer button on the live view page. The washer can also be triggered with the auxiliary command tt:WashingProcedure if the washer button is not available on your camera.
true: The current PT position is stored as the washing position in NozzlePresetData.
false: NozzlePresetData has not stored the washing position.
NozzlePresetDatapan=0.0:tilt=0.0pan=-180.0 ... 180.0:tilt=-90.0 ... 45.0admin: read, write
operator: read
viewer: read
Stores a string that holds the PT position of the washer nozzle.
WasherPumpPin11–4admin: read, write
operator: read
viewer: read
Selects the pin that the washer pump is connected to.
WasherPumpTime1010–60admin: read, write
operator: read
viewer: read
Specifies the duration of time in seconds that the pump should run during a washing procedure.
WasherWiperTime107–60admin: read, write
operator: read
viewer: read
Specifies the duration of time in seconds that the wiper should run during a washing procedure.
  1. Camera = Camera optics. For example zoom, focus and iris.

PTZ.Preset

The preset PTZ position configuration, that should be set using ptzconfig.cgi.

PTZ.Preset.P#
Parameter nameDefault valueValid valuesSecurity level (get/set)Description
NameHardware dependentA stringadmin: read, write
operator: read
viewer: read
Note: This parameter has been deprecated.
The name of the preset configuration.
ImageSourceHardware dependent0 (in products with 1 ImageSource, 0 ... 4 (in products with 4 ImageSource (4 inputs + Quad)).admin: read
operator: read
viewer: read
Note: This parameter has been deprecated.
The ImageSource.I# this Preset.P# configuration is connected to.
HomePosition0An unsigned integer.admin: read, write
operator: read
viewer: read
The Position.P# group number of the home position.
Note
The # is replaced with a group number starting from zero, e.g. PTZ.Preset.P0.

PTZ.Preset.P.Position

This group contains the parameters that describes the individual preset positions.

Note
This parameter group has been deprecated. Use the ptzconfig.cgi and ptz.cgi? query to manage the list of preset positions instead. As of version 2.00 of the PTZ preset API Properties.API.PTZ.Presets.Version=2.00 adding, updating and removing presets using param.cgi is no longer supported.

PTZ control

Control the pan, tilt and zoom behavior of a PTZ unit.

The PTZ control is device-dependent. For information about supported parameters and actual parameter values, check the specification of the Axis PTZ driver used. The following table is only an overview.

Access control

Viewer with access to PTZ controls.

Method

GET/POST

Syntax:
//<servername>/axis-cgi/com/ptz.cgi?<argument>=<value>[<argument>=<value>...]

With the following arguments and values:

Argument Valid valuesDescription
camera=<string>1 (default) ...(1)Selects the video channel. If omitted the default value camera=1 is used. This argument is only valid for Axis products with more than one video channel. That is cameras with multiple view areas and video encoders with multiple video channels.
Please note that camera=all is only valid for query=presetposcam, query=presetposcamdata and query=attributes.
whoami=<string>1Returns the name of the system-configured device driver.
center=<int>,<int><x>,<y>Center the camera on positions x,y where x,y are pixel coordinates in the client video stream.
areazoom=<int>,<int>,<int><x>,<y>,<z=>1>Centers on positions x,y (like the center command) and zooms by a factor of z/100. If z is more than 100 the image is zoomed in (for example; z=300 zooms in to 1/3 of the current field of view). If z is less than 100 the image is zoomed out (for example; z=50 zooms out to twice the current field of view).

Note: In some Axis products, the precision of areazoom can be strongly improved by calibrating the lens offset parameters.
imagewidth=<int>1, ...(1)Required in conjunction with center or areazoom if the image width displayed is different from the default size of the image, which is product-specific.
imageheight=<int>1, ...(1)Required in conjunction with center or areazoom if the image height is different from the default size of the image, which is product-specific.
move=<string>home
up
down
left
right
upleft
upright
downleft
downright
stop
Absolute:Moves the image 25 % of the image field width in the specified direction.
Relative: Moves the device approx. 50-90 degrees(2) in the specified direction.

home = Moves the image to the home position.
up = Moves the image up.
down = Moves the image down.
left = Moves the image to the left.
right = Moves the image to the right.
upleft = Moves the image up diagonal to the left.
upright = Moves the image up diagonal to the right.
downleft = Moves the image down diagonal to the left.
downright = Moves the image down diagonal to the right.
stop = Stops the pan/tilt movement.
pan=<float>-180.0 ... 180.0Pans the device to the specified absolute coordinates.(3)
tilt=<float>-180.0 ... 180.0Tilts the device to the specified absolute coordinates.(3)
zoom=<int>(4)1 ... 9999(5)Zooms the device n steps to the specified absolute position. A high value means zoom in, a low value means zoom out.(3)
focus=<int>(2)(4)1 ... 9999Moves focus n steps to the specified absolute position. A high value means focus far, a low value means focus near.
iris=<int>(4)1 ... 9999Moves iris n steps to the specified absolute position. A high value means open iris, a low value means close iris.
brightness=<int>(4)1 ... 9999Moves brightness n steps to the specified absolute position. A high value means brighter image, a low value means darker image.
rpan=<float>(6)-360.0 ... 360.0Pans the device n degrees relative to the current position.(3)
rtilt=<float>(6)-360.0 ... 360.0Tilts the device n degrees relative to the current position.(3)
rzoom=<int>(6)-9999 ... 9999(5)Zooms the device n steps relative to the current position. Positive values mean zoom in, negative values mean zoom out.
rfocus=<int>-9999 ... 9999Moves focus n steps relative to the current position. Positive values mean focus far, negative values mean focus near.
riris=<int>-9999 ... 9999Moves iris n steps relative to the current position. Positive values mean open iris, negative values mean close iris.
rbrightness=<int>-9999 ... 9999Moves brightness n steps relative to the current position. Positive values mean brighter image, negative values mean darker image.
autofocus=<string>on
off
Enable/disable auto focus.


on = Enables auto focus.
off = Disables auto focus.
autoiris=<string>on
off
Enable/disable auto iris.


on = Enable auto iris.
off = Disable auto iris.
continuouspantiltmove=<int>,<int>-100 ... 100,-100 ... 100Continuous pan/tilt motion.
Positive values mean right (pan) and up (tilt), negative values mean left (pan) and down (tilt). 0,0 means stop.(3)

Values as <pan speed>,<tilt speed>.
Optional arguments are: proportionalspeed=<string>, valid values: disabled(7)
continuouszoommove=<int>(6)-100 ... 100Continuous zoom motion. Positive values mean zoom in and negative values mean zoom out. 0 means stop.
continuousfocusmove=<int>-100 ... 100Continuous focus motion. Positive values mean focus far and negative values mean focus near. 0 means stop.
continuousirismove=<int>-100 ... 100Continuous iris motion. Positive values mean iris open and negative values mean iris close. 0 means stop.
continuousbrightnessmove=<int>-100 ... 100Continuous brightness motion. Positive values mean brighter image and negative values mean darker image. 0 means stop.
auxiliary=<string><function name>Activates/deactivates auxiliary functions of the device where <function name> is the name of the device specific function. Check in driver's documentation or in response to info=1 for information about <function name>.
gotoserverpresetname=<string><preset name>(8)Move to the position associated with the <preset name>.
gotoserverpresetno=<int>1, ...(8)Move to the position associated with the specified preset position number.
gotodevicepreset=<int><preset pos>(8)Bypasses the presetpos interface and tells the device to go directly to the preset position number <preset pos> stored in the device, where the <preset pos> is a device-specific preset position number. This may also be a device-specific special function.
speed=<int>1 ... 100Sets the move speed of pan and tilt.
imagerotation=<int>(1)0
90
180
270
If PTZ command refers to an image stream that is rotated differently than the current image setup, then the image stream rotation must be added to each command with this argument to allow the Axis product to compensate.


0 = Rotate the image 0 degrees.
90 = Rotate the image 90 degrees.
180 = Rotate the image 180 degrees.
270 = Rotate the image 270 degrees.
ircutfilter=<string>(1)auto(1)
on
off
Control the IR cut filter.

auto = Automatically switch between on and off depending on the lighting conditions.
on = Apply the filter, that is block IR light.
off = Remove the filter, that is allow IR light to reach the image sensor.
backlight=<string>on
off
Control the backlight compensation.

on = Bright mode.
off = Normal mode.
query=<string>limits
mode
position(2)
presetposall(9)
presetposcam(9)
presetposcamdata(9)
speed
auxiliary(1)
attributes(1)
Returns the current status.


limits = PTZ limits for the Axis product.
mode = Products with Panopsis technology: The current mode (overview or normal).
position = Values for current position.
presetposall = Current preset positions for all video channels. Optional arguments are:
  • format=<string>, valid values: json

presetposcam = Current preset positions for a video channel. Optional arguments are:
  • format=<string>, valid values: json

presetposcamdata = Returns the configured preset positions with position data measured in degrees. Optional arguments are:
  • format=<string>, valid values: json

speed = Values for pan/tilt speed.
auxiliary = Returns supported auxiliary commands. Optional arguments are:
  • format=<string>, valid values: json

attributes = Returns various PTZ attributes such as zoom, focus and speed-steps. Optional arguments are:
  • format=<string>, valid values: json

  • group=<string>, valid values: zoom, focus, speed, speeddry. All attributes will be returned if no group argument is given.

info=<int>1Returns a description of available PTZ commands.
  1. Product/release dependent. Check the product's release notes.
  2. Driver-specific.
  3. Products with Panopsis technology: If the product moves to a position where the Panopsis (fisheye) lens is visible, the product will go to Overview mode.
  4. Float input will be handled as int. No assumptions can be made on the correct rounding.
  5. If Support.S#.DigitalZoom is true, zoom ranges are 1 ... 19999 for zoom and -19999 ... 19999 for rzoom.
  6. Products with Panopsis technology: Does not have any effect in Overview mode.
  7. This option only affects proportional speed for individual commands and is only supported on mechanical PTZ domes when both Properties.PTZ.DigitalPTZ=no and Properties.PTZ.DriverManagement=no have been chosen ( API-version 1.1).
  8. Preset positions are configured using ptzconfig.cgi, see PTZ configuration.
  9. Character encoding for plain-text responses defined by the PTZ.ResponseEncoding parameter.

Example: Request information about available PTZ commands on video channel 3

//myserver/axis-cgi/com/ptz.cgi?info=1&camera=3

If PTZ is available the response may look like this:

Available commands
:
{camera=[n]}
whoami=yes
center=[x],[y]
  imagewidth=[n]
  imageheight=[n]
areazoom=[x],[y],[z]
  imagewidth=[n]
  imageheight=[n]
move={ home | up | down | left | right | upleft | upright | downleft | downright | stop }
pan=[abspos]
tilt=[abspos]
zoom=[n]
rpan=[offset]
rtilt=[offset]
rzoom=[offset]
continuouspantiltmove=[x-speed],[y-speed]
  proportionalspeed={ disabled }
continuouszoommove=[speed]
setserverpresetname=[name]
setserverpresetno=[n]
removeserverpresetname=[name]
removeserverpresetno=[n]
gotoserverpresetname=[name]
gotoserverpresetno=[n]
query={ position | limits | presetposcam | presetposall | status }
  format={ json }

Query=attributes response

The response is sectioned for each camera/channel number, with each section containing a list of attribute/data pairs. The data can be either a single value or an entire array of entries each containing one or more key/value pairs. Please note that supported attributes are product dependent. Also, the order of cameras/channels sections in the response may not be in the number order.

GroupAttributeData typeValid valuesDescription
speedspeedsAn array of entries containing the keys “value” and “speed”.Value: integer 1–100
Speed: integer ≥ 1 or float > 0.0.
Mapping between VAPIX pan/tilt speed values and the actual speed (degrees/sec).
focusminFocusAn array of entries containing the keys “value” and “distance”.Value: integer 1–100
Distance: integer ≥ 0.
Mapping between VAPIX focus limit values and the actual distance (centimeters).
zoommaxOpticalZoomMagSingle value.Integer ≥ 1 or float ≥ 1.0.The maximum optical magnification at tele zoom.
zoommaxDigitalZoomMagSingle value.Integer ≥ 1 or float ≥ 1.0.The maximum digital magnification at tele zoom.
zoomzoomStepsAn array of entries containing the keys “value”, “zoom” and the optional “visible”.Value: integer 1–19999
Zoom: integer ≥ 1 or float ≥ 1.0
Visible: boolean “true” or “false”
Mapping between VAPIX zoom positions and magnification. The optional “visible” key helps the GUI determine if the entry as an option for the zoom limit configuration should be shown or not. Default value is “true”.
zoomisOverviewSingle value.Boolean “true” or “false”If “true”, the camera on this channel is stationary and does not perform movements itself, instead acting as a proxy to control another channel to which movement commands are forwarded.

Query attribute response format - plain text

Attributes for camera [n]
<attribute a>=<array entry1>, <array entry2>,...
<attribute b>=<array entry1>, <array entry2>,...
<attribute c>=<single value>
Attributes for camera [m]
...

The attribute array entries are comma separated while the key/value pairs are separated by a | as shown below:

<key 1>=<value 1>|<key 2>=<value 2>|...|<key N>=<value N>

Example

Attributes for camera 1
speeds=value=1|speed=0.05,value=9|speed=0.16,value=14|speed=2,value=24|speed=2.1,value=40|speed=9,value=58|speed=28,value=80|speed=74,value=100|speed=150
maxOpticalZoomMag=30

Query attribute response format - json

{
  "Camera <n>": {
    "<attribute a>": [<arrary entry 1>, <array entry 2>],
    "<attribute b>": [<arrary entry 1>, <array entry 2>],
    "<attribute c>": "<single value>"
  },
  "Camera <m>": {
    ...
  }
}

The attribute array entries are json objects with one or more key/value pairs:

{
  "<key 1>": "<value 1>",
  "<key 2>": "<value 2>",
  ...,
  "<key N>": "<value N>"
}

Example

{
  "Camera 1": {
    "maxOpticalZoomMag": "30",
    "zoomSteps": [
      {
        "value": "1",
        "zoom": "1"
      },
      {
        "value": "3868",
        "zoom": "2"
      },
      {
        "value": "7736",
        "zoom": "3"
      },
      {
        "value": "9999",
        "zoom": "3.584961"
      }
    ]
  }
}

PTZ configuration

Set and configure PTZ preset positions and On screen display (OSD) control.

A server preset saved with name will also get a number and vice versa. You can use both setserverpresetname/removeserverpresetname and setserverpresetno/removeserverpresetno commands on the same preset.

Access control

admin

Method

GET/POST

//<servername>/axis-cgi/com/ptzconfig.cgi?<argument>=<value>[&<argument>=<value>...]

With the following arguments and values:

ArgumentValid valuesDescription
camera=<int>1 ...The video channel. If omitted, the default video channel is used.
osdmenu=<string>open
close
up
down
left
right
select
back
Commands to control the OSD menu in the external device. Note that support for different commands, and the behavior of the commands, are driver dependent.

open = Open.
close = Close.
up = Move up.
down = Move down.
left = Move to the left.
right = Move to the right.
select = Select.
back = Go back.
setserverpresetname=<string><preset name>(1)Associates the current position to <preset name> as a preset position in the Axis product.
setserverpresetno=<int>1, ...Saves the current position as a preset position number in the Axis product.
renameserverpresetno=<int>&newname=<string>1, ..., <preset name>(1)Set a new name for the specified preset position.
home=<string>yesMakes the current position the home position for the Axis product. Used with setserverpresetname or setserverpresetno.
removeserverpresetname=<string>(2)<preset name>(1)Removes the specified preset position associated with <preset name>.
removeserverpresetno=<int>(2)1 ...Removes the specified preset position.
setdevicepreset=<int><preset pos>Bypasses the presetpos interface and tells the device to save its current position as preset position <preset pos> directly in the device, where <preset pos> is a device-specific preset position number. This may also be a device-specific special function
  1. <preset name> is a string with a maximum of 31 characters. The following five characters are not allowed: "<>~:
  2. When a home preset is removed a new home preset will automatically be created.

Responses

Success for ptz.cgi

A successful response for ptz.cgi.

HTTP code

204 No content

Content-type

text/plain

Error for ptz.cgi

An error response for ptz.cgi.

HTTP code

200 OK

Content-type

text/plain

Error:
[message]

Success for info=1

If PTZ is available a successful response for info=1. The generated response values for this argument depends on what functions the Axis product supports and what functions that are enabled.

HTTP code

200 OK

Content-type

text/plain

Available commands
:
{camera=[n]}
whoami=yes
center=[x],[y]
  imagewidth=[n]
  imageheight=[n]
areazoom=[x],[y],[z]
  imagewidth=[n]
  imageheight=[n]
move={ home | up | down | left | right | upleft | upright | downleft |
downright | stop }
pan=[abspos]
tilt=[abspos]
zoom=[n]
focus=[n]
iris=[n]
brightness=[offset]
rpan=[offset]
rtilt=[offset]
rzoom=[offset]
rfocus=[offset]
riris=[offset]
rbrightness=[offset]
autofocus={ on | off }
autoiris={ on | off }
ircutfilter={ on | off | auto }
backlight={ on | off }
continuouspantiltmove=[x-speed],[y-speed]
continuouszoommove=[speed]
continuousfocusmove=[speed]
continuousirismove=[speed]
continuousbrightnessmove=[speed]
auxiliary=[function]
setserverpresetname=[name]
setserverpresetno=[n]
removeserverpresetname=[name]
removeserverpresetno=[n]
gotoserverpresetname=[name]
gotoserverpresetno=[n]
gotodevicepreset=[n]
speed=[n]
osdmenu=[cmd]
query={ speed | position | limits | presetposcam | presetposall }

Success for query=speed

If PTZ is available a successful response for query=speed. The generated response values for this argument depends on what functions the Axis product supports and what functions that are enabled.

HTTP code

200 OK

Content-type

text/plain

speed=[speed]

Success for query=position

If PTZ is available a successful response for query=position. The generated response values for this argument depends on what functions the Axis product supports and what functions that are enabled.

HTTP code

200 OK

Content-type

text/plain

pan=[abspos]
tilt=[abspos]
zoom=[n]
autofocus={ on | off }
autoiris={ on | off }

Success for query=limits

If PTZ is available a successful response for query=limits. The generated response values for this argument depends on what functions the Axis product supports and what functions that are enabled.

HTTP code

200 OK

Content-type

text/plain

MinPan=[abspos]
MaxPan=[abspos]
MinTilt=[abspos]
MaxTilt=[abspos]
MinZoom=[n]
MaxZoom=[n]
MinIris=[n]
MaxIris=[n]
MinFocus=[n]
MaxFocus=[n]
MinFieldAngle=[n]
MaxFieldAngle=[n]
MinBrightness=[offset]
MaxBrightness=[offset]

Success for query=presetposcam

If PTZ is available a successful response for query=presetposcam.

HTTP code

200 OK

Content-type

text/plain

Preset Positions for camera [n]
presetposno[n]=p[n]
presetposno1=Home

Success for query=presetposall

If PTZ is available on a multichannel product several cameras can be listed. A successful response for query=presetposall .

HTTP code

200 OK

Content-type

text/plain

Preset Positions for camera 1
presetposno[n]=p[n]
presetposno1=Home
 
Preset Positions for camera 2
presetposno[n]=p[n]
presetposno1=Home
...

Error for query=[invalid value]

An error response for an invalid value, query=[invalid value].

HTTP code

200 OK

Content-type

text/plain

Error:
query: unknown value: [invalid value]

Success for whoami=1

If PTZ is available a successful response for whoami=1.

HTTP code

200 OK

Content-type

text/plain

[Driver name]

Success for ptzconfig.cgi

A successful response for ptzconfig.cgi.

HTTP code

204 No content

Content-type

text/plain

Error for ptzconfig.cgi

An error response for ptzconfig.cgi.

HTTP code

200 OK

Content-type

text/plain

Error:
[message]

PTZ driver management API

Description

Axis products with serial ports can be connected to an external PTZ device, for example a pan-tilt motor, that provides PTZ functionality. To control the external PTZ device, a driver matching the external device must first be activated on the physical channels where the functionality is wanted.

Model

Only one external PTZ device driver may be activated at any given time. In addition, there can be zero or more static drivers active. The static drivers are permanently active and are used to control the internal hardware. Static drivers also operate in parallel with the external PTZ device driver and cannot be listed or manipulated using any Driver Management CGI.

All compatible external PTZ device drivers are included on the AXIS product’s firmware as of API version 1.1. Please note that when using firmware of earlier API versions that some drivers may be included in the AXIS product's firmware, but most drivers must be retrieved from Axis support and uploaded to the camera by the user before they can be activated

The PTZ driver management API consists of the following CGIs:

ptzuploader.cgiUpload drivers, remove uploaded drivers and list the uploaded drivers. See PTZ driver upload.

Please note that uploading and removing drivers are no longer necessary and will have no effect as of API version 1.1, as all compatible PTZ drivers will be embedded part of firmware. Because of this, the options to upload and remove drivers have been deprecated.

ptzupgrader.cgiActivate or deactivate a driver for a video channel. See PTZ driver activation/deactivation.

For information about serial ports, see Serial port API.

Identification

API version 1.0

API Discovery

id=ptz-driver-management version=1.0

Property

Properties.PTZ.DriverManagement=yes

Firmware

5.20 and later

Product category

Axis video products with serial ports.

API version 1.1

API Discovery

id=ptz-driver-management version=1.1

Property

Properties.PTZ.DriverManagement=yes

Property

Properties.PTZ.EmbeddedDrivers=yes

Firmware

10.12 and later

Product category

Axis video products with serial ports.

Use cases

List available PTZ drivers

This example should be used when you wish to list all PTZ drivers available for activation and which drivers are currently active. All available PTZ drivers have an ID used to activate/deactivate them.

1. List all PTZ drivers.

//<servername>/axis-cgi/ptz/ptzuploader.cgi?list=yes

2. Parse the HTTP response. The response will look like this if a Pelco driver is activated on channels 3 and 4:

Successful response example
<?xml version="1.0"?>
<root>
  <driverentry>
    <id>1</id>
    <driver>Pelco</driver>
    <driverversion>2.03</driverversion>
    <installed><ch>3</ch><ch>4</ch></installed>
  </driverentry>
</root>

Activate a PTZ driver

This example should be used when you wish to activate a PTZ driver and perform PTZ movements on your camera.

1. Activate a PTZ driver.

Activate a PTZ driver with ID 2 on the default video channel.

//<servername>/axis-cgi/ptz/ptzupgrader.cgi?driverid=2

Install a driver with ID 2 on video channel 3.

//<servername>/axis-cgi/ptz/ptzupgrader.cgi?driverid=2&channel=3

Install a driver with ID 1 on video channel 1 using automatic port finding. This option is deprecated as of API version 1.1.

//<servername>/axis-cgi/ptz/ptzupgrader.cgi?driverid=1&channel=1&auto=yes

2. Parse the HTTP response.

Successful response example
HTTP/1.1 200 OK

Deactivate a PTZ driver

This example should be used when you wish to deactivate a PTZ driver from a video channel.

1. Deactivate a PTZ driver.

//<servername>/axis-cgi/ptz/ptzupgrader.cgi?driverid=0&channel=1

2. Parse the HTTP response.

Successful response example
HTTP/1.1 200 OK

PTZ driver upload

This example should be used when you wish to upload a new PTZ driver.

Please note that this method is deprecated and will have no effect as of API version 1.1 and will no longer receive any updates.

1. Upload a driver.

//<servername>/axis-cgi/ptz/ptzuploader.cgi

The file content of the installation file, Phillips-1.0.ptz in this example, is provided in the HTTP body as POST data:

HTTP input parameters
POST /axis-cgi/ptz/ptzuploader.cgi HTTP/1.0
Content-Type: multipart/form-data; boundary=AaBo3x
Content-Length: 120486
 
--AaBo3x
Content-Disposition: form-data; name="Upload Driver"; filename="Philips-1.0.ptz"
Content-Type: application/octet-stream
 
<file content of Philips-1.0.ptz>
--AaBo3x--

2. Parse the HTTP response In this example, the driver ID 2 is returned.

Successful response example
<?xml version="1.0"?>
<root>
  <id>2</id>
</root>

Remove a PTZ driver

This example should be used when you wish to remove a PTZ driver from the Axis product in order to free space on your device.

Please note that this method is deprecated and will have no effect as of API version 1.1 and will no longer receive any updates.

1. Remove a PTZ driver.

//<servername>/axis-cgi/ptz/ptzuploader.cgi?removedriverid=5

This will remove the driver with ID 5 from the driver database and free up space on a device running API version 1.0. Using this method on devices running later API versions is ineffective. See

2. Parse the HTTP response.

Successful response example
HTTP/1.1 200 OK

API Specifications

PTZ driver listing

This CGI should be used for listing available drivers.

Request

Access control

admin

Method

GET/POST

Syntax:
//<servername>/axis-cgi/ptz/ptzuploader.cgi?<argument>=<value>

With the following arguments and values:

ArgumentValid valuesDescription
list=<string>no (default)
yes
yes: The Axis product lists the available drivers in the Axis product in an XML listing (see below).
no: The Axis product does not list the drivers.

Return value - Success

Uploading a new driver will return the following HTTP response:

<?xml version=1.0"?>
<root>
  <id>driverid</id>
</root>
ArgumentDescription
driveridThe driver ID.

Using list will return the driver listing in the following format:

<?xml version=1.0"?>
<root>
  <driverentry>
  <id>driverid</id>
  <driver>drivername</driver>
  <driverversion>driverversion</driverversion>
  <installed><ch>channel1</ch>ch>channel2</ch>...<ch>channeln</ch></installed>
  </driverentry>
  ...
</root>

Please note that there is one driverentry element for each available driver.

ArgumentDescription
driveridThe driver ID.
drivernameThe driver name.
driverversionThe driver version.
installedContains the number of a video channel where the driver is active. No <ch> on a video channel means that the channel has no active driver.

PTZ driver upload

This CGI is used for uploading drivers.

This CGI has been deprecated with the release of API version 1.1 and will no longer receive any updates. Uploading a driver with API version 1.1 or later will have no effect on the product.

Request

Access control

admin

Method

GET/POST

Syntax:
//<servername>/axis-cgi/ptz/ptzuploader.cgi

Driver upload is done a multipart/form-data in accordance with RFC 1867

Return value - Success

Uploading a new driver will return the following HTTP response:

<?xml version=1.0"?>
<root>
  <id>driverid</id>
</root>
ArgumentDescription
driveridThe driver ID of the uploaded driver.

Remove PTZ driver

This CGI is used for removing uploaded drivers.

This CGI has been deprecated with the release of API version 1.1 and will no longer receive any updates. Removing a driver with API version 1.1 or later will have no effect on the product.

Request

Access control

admin

Method

GET/POST

Syntax:
//<servername>/axis-cgi/ptz/ptzuploader.cgi?<argument>=<value>
ArgumentValid valuesDescription
removedriverid=<int><driverid>Removes the driver entry identified by <driverid>from the product. The <driverid> value was returned when the driver was installed, and can also be retrieved using list.

Return value - Success

Removing a new driver will return the following HTTP response:

<?xml version=1.0"?>
<root>
  <id>driverid</id>
</root>
ArgumentDescription
driveridThe driver ID of the removed driver.

PTZ driver activation/deactivation

This CGI is used for activating or deactivating a driver on a particular video channel. Drivers may have been previously uploaded, or may be included in the firmware of the product.

After activating a driver, the external device can be controlled using the Pan/tilt/zoom API and, if the driver supports it, Serial port API.

Request

Access control

admin

Method

GET/POST

Syntax:
//<servername>/axis-cgi/ptz/ptzupgrader.cgi?<argument>=<value>[&<argument>=<value>...]

With the following arguments and values:

Argument Valid valuesDescription
driverid=<int>0 (default) ... The driver ID. This ID has been returned from ptzuploader.cgi, or parsed from the XML returned from ptzuploader.cgi?list=yes.
The value 0 deactivates the currently active driver without installing another driver.
channel=<int>1 (default) ...Video channel where the driver should be installed. If an external PTZ device driver already is active for a channel, it will be deactivated when a new driver is activated.

root.PTZ.PTZDriverStatuses.Driver#Status

The parameters in this group are used when you wish to find out the statuses for PTZ drivers associated with the (serial) ports.

List security level

viewer

Syntax
PTZ.PTZDriverStatuses.Driver[video_channel]Status

Valid values for [video_channel] range from 1 to root.PTZ.NbrOfCameras.

ArgumentDescription
Driver[video_channel]Status=<integer>Holds the status of the driver active and can be interpreted as:
0: No driver is active or the driver is being activated/configured.
1: The installation file is invalid or incompatible.
2: The driver is malfunctioning.
3: The driver is active.

Backwards compatibility

ptzupdate.cgi

This deprecated CGI was used to upload and install drivers before the drivers became associated with video channels and not with ports.

Request

Security level

admin

Method

POST

Syntax
//<servername>/axis-cgi/com/ptzupdate.cgi?<argument>=<value>[&<argument>=<value>...]
ArgumentDescription
channel=<int>The channel where the driver should be activated. Defaults to 1 if not specified.
port=<int>Connects the video channel where the driver is active to the given port (by setting the parameter PTZ.CamPorts.Cam#Port). Providing the argument port will not deactivate other drivers connected to that port, because multiple video channels may be connected to the same port.
replacedriver=<string>Replaces the currently active driver called <driver name>, a name originating from the parameter group PTZ.PTZDrivers.Driver#, where # is the index number of the active driver. Please note that there is a possibility that more than driver with the same name might have been activated on products with more than one channel. Setting the replacedriver parameter will remove all drivers with that name from the driver database.

ptzadmin.cgi

This deprecated CGI was used to handle relations between drivers and ports before being replaced by either ptzupgrader.cgi or the parameter PTZ.CamPorts.Cam#Port, which should be directly updated in order to associate the video channel where a driver is active with a port.

Security level

admin

Method

POST

Syntax
//<servername>/axis-cgi/com/ptzadmin.cgi?<argument>=<value>[&<argument>=<value>...]
ArgumentDescription
port=<int>Selects the port that will be used as the value of the PTZ.CamPorts.Cam#Port parameter.
ptzdrivername=<string>Associates a driver name with a port. If the value is none the current driver (if any) is disassociated from the port. Please note that the <driver name> comes from the parameter group PTZ.PTZDrivers.Driver.

Queuing API

Description

The control queue is used to administrate the PTZ control in an environment where several users have PTZ control. A control blocking function lets one user at the time have PTZ control. The other users are put in the control queue. Once a user gained PTZ control PTZ requests can be sent as usual. The rules of the queue are based on what type of access control the user has. For example a user with admin access control will be prioritized over a user with viewer access control. To distinguish individuals using the same user account a cookie is sent the first time the user sends a PTZ request.

Prerequisites

Identification

Property

Properties.API.HTTP.Version=3

Firmware

5.20 and later.

Products with mechanical PTZ require:

Property

Properties.PTZ.PTZ=yes

Products with digital PTZ require:

Property

Properties.PTZ.DigitalPTZ=yes

Parameters

PTZ.Various

PTZ.Various.V#
Parameter Default valuesValid values(1)Access controlDescription
CtlQueueingProduct/driver dependenttrue
false
admin: read, write
operator: read, write
viewer: read
The parameter is true if control queuing is supported by the driver. If enabled, access to controlling the PTZ unit is limited to the client currently possessing the control.


true = Control queuing is allowed.
false = Control queuing is not allowed.
CtlQueueLimitProduct/driver dependent1 ... 100admin: read, write
operator: read, write
viewer: read
Set the maximal number of clients in a control queue.
CtlQueuePollTimeProduct/driver dependent5 ... 3600admin: read, write
operator: read, write
viewer: read
Set the maximum time in seconds between poll-requests, which an existing client in the control queue must send, to stay active in the queue.
  1. Integer ranges may be overridden by configuration file for driver.

PTZ.UserCtlQueue.U#

Parameters for the different users in the control queue. These parameters only have effect if the control queue is enabled (PTZ.Various.V#.CtlQueuing=true). In that case, cookies will be required for all calls to ptz.cgi.

PTZ.UserCtlQueue.U# The # is replaced with a group number starting from 0, for example PTZ.UserCtlQueue.U5.UserGroup.
Parameter Default valuesValid valuesAccess controlDescription
UserGroupUser group dependentAdministrator
Operator
Viewer
Event
Autotracking
Guardtour
Recordedtour
Usergroup
...
admin: read
operator: read

Name of the user group.

Guardtour = preset tour (guard tour)

Recordedtour = recorded tour (guard tour)

Autotracking = mechanical autotracking

UseCookieUser group dependentyes
no
admin: read, write
operator: read
If users from a user group shall be separated by using a cookie or by the user name.


yes = Cookies are used.
no = Cookies are not used.
PriorityUser group dependent1 ... 100admin: read, write
operator: read
The priority value. 1 is the highest value.
TimeoutTypeUser group dependenttimespan
activity
infinity
admin: read, write
operator: read
Set the timeout type to use.


timespan = The user possesses the PTZ control during the time defined by TimeoutTime.
activity = The user possesses the PTZ control during the time defined by TimeoutTime parameter. The TimeoutTime parameter is reset after every PTZ movement.
infinity = The user has infinite PTZ control.
TimeoutTimeUser group dependent1 ... 3600admin: read, write
operator: read
The time used for each TimeoutType. The value is ignored when TimeoutType is infinity.
  1. The # is replaced with a group number starting from 0, for example PTZ.UserCtlQueue.U5.UserGroup.

PTZ control queue

This CGI handles requests concerning the control queue. If the PTZ control queuing mechanism is enabled (PTZ.Various.V1.CtlQueueing=true) for a video channel, control of PTZ units is limited to the client currently possessing it.

Note
Cookies are enabled by default when enabling PTZ control queue.
Access control

viewer with access to PTZ controls

Method

GET/POST

Syntax:
//<servername>/axis-cgi/com/ptzqueue.cgi?<argument>=<value>[&<argument>=<value>...]

With the following arguments and values:

ArgumentValid valuesDescription
control=<string>request
drop
query
request = Requests PTZ control.
drop = Drops the PTZ control or leaves the queue.
query = Reports the current status for the client.

For possessing clients with no peers existing in the queue, request will reset the control timer. For all other clients, request will have the same effect as query.
camera=<int>1 ...(1)The video channel number. If omitted, the default channel is used.
  1. Product-dependent. Check the product's Release notes.

Request PTZ control for video channel 2.

//myserver/axis-cgi/com/ptzqueue.cgi?control=request&camera=2

Response

PTZ control queue response

The 200 OK response on success for request and query has a format that enables simple JavaScript parsing.

Success

HTTP code

200 OK

Body:
<a name="<pos>"</a><a name="<seconds>"</a><a name="<period>"></a>
  • <pos> can have a value from 0 to the maximum value of how many clients are allowed in the queue. This value is the given position in the queue. 0 means that the client is not in the queue, 1 means control is possessed. If the value is 0 the other values are undefined.

  • <seconds> is the estimated number of seconds remaining, that is for position 1 the remaining control time and for other positions, the time until position 1 is reached. If the value is -1 the time remaining to get control cannot be estimated. This means that a client in the queue has the TimeoutType set to infinity.

  • <period> is the recommended time in seconds when the client should send a new control=query requests. To stay active in the queue the client must regularly send the request control=query to the Axis product. An inactive client will automatically be removed from the queue.

Control requested.

HTTP code

200 OK

<a name="3"></a><a name="410"></a><a name="5"></a>

This means the client was assigned queue position 3. The expected number of seconds until control is possessed is 410 and the recommended time until the next request is 5 seconds.

Failure

On failure no anchor elements are provided but simply the error message in plain text.

HTTP code

200 OK

Content-type

text/plain

Error:
<error information>

Focus recall API

Description

The VAPIX® Focus recall API gives instant focus even in challenging light conditions when used for management of camera settings in PTZ zones. Focus recall uses memory zones which consist of a pan, tilt and/or zoom range where the specified camera settings should be applied. Zones can be added, listed and removed. Each zone is identified by a unique index. The settings in a zone is applied when the center coordinate of the camera is inside the PTZ area that is defined by the zone.

    Identification

    VAPIX® Focus recall is available if:

    Property

    Properties.MemoryZones.MemoryZones=yes


    Additional read-only properties available through param.cgi:

    Property

    Properties.MemoryZones.MaxNbrOfMemoryZones=X

    Property

    Properties.MemoryZones.Version=0.1

    API Discovery

    id=ptz-focus-recall


    Firmware: 6.25 and later.

    Product category: PTZ or Zoom cameras.

    Common examples

    Check if Focus recall is supported.

    Request:
    //<servername>/axis-cgi/param.cgi?action=list&group=Properties.MemoryZones.MemoryZones

    Response if memoryzones are supported:

    HTTP code

    200 OK

    Content-type

    text/plain

    Properties.MemoryZones.MemoryZones=yes

    Save current focus position as a memoryzone.

    Request:
    //<servername>/axis-cgi/memoryzones/add.cgi?focus=current

    Response:

    HTTP code

    200 OK

    Content-type

    application/json

    { "name":"memory_zone_1", "index":1 }

    Using a certain zoom range.

    Request:
    //<servername>/axis-cgi/memoryzones/add.cgi?focus=current&zoomrange=1111:3333

    Response:

    HTTP code

    200 OK

    Content-type

    application/json

    { "name":"memory_zone_1", "index":1 }

    Remove the current memory zone.

    Request:
    //<servername>/axis-cgi/memoryzones/remove.cgi

    Response:

    HTTP code

    200 OK

    Content-type

    application/json

    { "name":"memory_zone_1", "index":1 }

    Remove the memory zone having index 4

    Request:
    //<servername>/axis-cgi/memoryzones/remove.cgi?index=4
    Response:
    None

    Add memory zone

    Use memoryzones/add.cgi to add a memory zone.

    Request

    Access control

    admin, operator, viewer with PTZ control

    Method

    GET

    Syntax:
    //<servername>/axis-cgi/memoryzones/add.cgi?<argument>=<value>

    with the following arguments and values:

    ArgumentValid valuesDescription
    name=<string>

    string

    Name of the memory zone (UTF-8 encoded). Maximum length 32 characters. Optional

    polygon=<string>

    string

    Image related coordinates of the corners of the memory zone stored as float values in a string of coordinate pairs, <x1>,<y1>:<x2>,<y2>:<x3>,<y3>:<x4>,<y4>.

    Origo (0.0, 0.0) is in the middle of the image. X-coordinates have positive direction to the right. Y-coordinates have positive direction up.

    The coordinates of the image have coordinates (-1.0, -1.0), (1.0, -1.0), (1.0, 1.0) and (-1.0, 1.0).

    Coordinates less than -1.0 and greater than 1.0 are accepted to indicate points outside the image.

    All coordinates relate to the currently configured default rotation and mirroring settings for the channel. Optional.

    zoomrange=<string>

    string

    Zoom coordinates in VAPIX scale in format, <zoom_min>:<zoom_max>, defines the zoomrange where the memoryzone is valid. Valid range 1 - 19999. Default value "1:19999". Optional.

    camera=<integer>

    integer

    The index of the camera source to apply the request. Default is 1. This argument is not required when there is only one camera source in the product. Optional.

    focus=<string>

    string

    The focus configuration to be saved in the memory zone. Valid values are: 1 - 9999 | current VAPIX scale, 1 - 9999 for focus position, current to save the current focus position of the camera. Mandatory.

    Response

    Responses from memoryzones/add.cgi

    Success

    If the request is successful:
    HTTP code: 200 OK
    Content-Type: application/json
    Body:
    {"name" : "name",  "index" : index}

    HTTP Code: GeneralSuccess response is returned. See General success response.

    Error

    If an error occurred:
    HTTP code: 200 OK
    Content-Type: application/json
    Body:
    {"error": { "id":<error code>, "message":"<optional error message in English>" }}

    HTTP Code: GeneralError response is returned. See General error response.

    Remove memory zone

    Use memoryzones/remove.cgi to delete a memory zone.

    Request

    Access control

    admin, operator, viewer with PTZ control

    Method

    GET

    Syntax:
    //<servername>/axis-cgi/memoryzones/remove.cgi?<argument>=<value>

    with the following arguments and values:

    ArgumentValid valuesDescription
    index=<integer>

    integer

    The index of the memoryzone to apply the request. This argument is not required when removing all saved memoryzones. Optional

    camera=<integer>

    integer

    The index of the camera source to apply the request. Default is 1. This argument is not required when there is only one camera source in the product. Optional.

    removeall=<integer>

    integer

    _removeall=1_ will remove all configured zones. Optional.

    Response

    Responses from memoryzones/remove.cgi

    Success

    If the request is successful:
    HTTP code: 200 OK
    Content-Type: application/json
    Body:
    Empty

    HTTP code: GeneralSuccess response is returned. See General success response.

    Error

    If an error occurred:
    HTTP code: 200 OK
    Content-Type: application/json
    Body:
    {"error": { "id":<error code>, "message":"<optional error message in English>"}}

    HTTP code: GeneralErrorresponse is returned. See General error response.

    List memory zones

    Use memoryzones/list.cgi to list the memory zones.

    Request

    Access control

    admin, operator, viewer with PTZ control

    Method

    GET

    Syntax:
    //<servername>/axis-cgi/memoryzones/list.cgi?<argument>=<data>[&<argument>=<data>[&...]]

    with the following arguments and values:

    ArgumentValid valuesDescription
    camera=<integer>

    integer

    The index of the camera source to apply the request. Default is 1. This argument is not required when there is only one camera source in the product. Optional.

    query=list|current|view

    list

    current

    view

    List all memory zones in the camera.

    Query for the memory zone located at the current coordinate.

    Query details about memoryzones located inside the current view.

    Response

    Responses from memoryzones/list.cgi

    Success

    If the request is successful:
    HTTP code: 200 OK
    Content-Type: application/json

    Response for query=list if at least one zone has been added:

    Body:
    [{ "name" : "name", "index" : index, "ptpolygon" : "0.0,0.0:0.0,0.0:0.0,0.0:0.0,0.0", "zoomrange" : "0:0", "focus" : position},...]

    Response for query=list if there are no zones:

    Body:
    []

    Response for query=current if there is a zone at the current coordinates:

    Body:
    { "name" : "name", "index" : index }

    Response for query=current if there is no zone at the current coordinates:

    Body:
    {"name" : "", "index" : -1}

    Response for query=view if there is one or more zone within the current view:

    Body:
    [{ "name" : "name", "index" : index, "polygon" : "0,0:0,0:0,0:0,0", "ptpolygon" : "0.0,0.0:0.0,0.0:0.0,0.0:0.0,0.0", "zoomrange" : "0:0", "focus" : position}, ...]

    Response for query=view if there are no zones in the current view:

    Body:
    []

    HTTP code: GeneralSuccess response is returned. See General success response.

    Error

    If an error occurred:
    HTTP code: 200 OK
    Content-Type: application/json
    Body:
    { "error": { "id":<error code>, "message":"<optional error message in English>" }}

    HTTP code: GeneralError response is returned. See General error response.

    Goto memory zone

    Use memoryzones/goto.cgi to go to and focus on memory zone coordinates.

    Request

    Access control

    admin, operator, viewer with PTZ control

    Method

    GET

    Syntax:
    //<servername>/axis-cgi/memoryzones/goto.cgi?<argument>=<data>[&<argument>=<data>[&...]]

    with the following arguments and values:

    ArgumentValid valuesDescription
    camera=<integer>

    integer

    The index of the camera source to apply the request. Default is 1. This argument is not required when there is only one camera source in the product. Optional.

    index=<integer>

    integer

    Index of the memory zone. Mandatory.

    Response

    Responses from memoryzones/goto.cgi

    Success

    If the request is successful:
    HTTP code: 204 OK
    Content-Type: application/json
    Body:
    Empty

    HTTP code: GeneralSuccess response is returned. See General success response.

    Error

    If an error occurred:
    HTTP code: 200 OK
    Content-Type: application/json
    Body:
    { "error": { "id":<error code>, "message":"<optional error message in English>" }}

    HTTP code: GeneralError response is returned. See General error response.

    General success response

    General success response from Focus recall API.

    HTTP code

    : 200 OK

    Content-type

    : application/json

    Body:
    {
      "name" : "name",
      "index" : index
    }

    General error response

    General error response from Focus recall API.

    HTTP code

    : 200 OK

    Content-type

    : application/json

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <memoryzonesResponse SchemaVersion="1.0" xmlns:xsi="//www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="//www.axis.com/vapix/http_cgi/memoryzones.xsd">
      <GeneralError>
        <ErrorCode>[error code]</ErrorCode>
        <ErrorDescription>[description]</ErrorDescription>
      </GeneralError>
    </memoryzonesResponse>

    Supported elements, attributes and values:

    ElementDescription
    memoryzonesResponseContains the response.
    GeneralErrorError.
    ErrorCodeA numeric error code. See table below.
    ErrorDescriptionDescription of the error.
    Error codeDescriptionCGI
    501Other errorAll
    502Unknown memory zone commandAll
    503Unknown indexremove.cgi, list.cgi
    504List fulladd.cgi, goto.cgi
    505Name already definedadd.cgi
    506Name too longadd.cgi

    PTZ events and actions

    PTZ preset reached event

    The PTZ preset reached event is true when the camera stops at a preset position. Preset positions are defined for each video channel or view area. There is one event for each preset position. The Any event is true if the camera stops at any of the preset positions defined on that channel or view area.

    Note that Nice name can be changed.

    Topic

    Name

    tns1:PTZController/tnsaxis:PTZPresets/tnsaxis:Channel_X

    Type

    Stateful

    Nice name

    PTZ preset reached on channel X

    Source instance

    Nice name

    Preset token

    Type

    integer

    Name

    PresetToken

    ValueNice name
    -1Any
    1Home

    Note that Homeis the default and this can be changed.

    2User-defined name
    ......
    number of presets definedUser-defined name

    Data instance

    Nice name

    Preset reached

    Type

    boolean

    Name

    on_preset

    isPropertyState

    true

    PTZ moving event

    The PTZ movement event is true when the camera is moving due to a PTZ operation.

    The event can for example be used to prevent motion detection from being triggered while the camera moves due to a PTZ operation.

    Topic

    Name

    tns1:PTZController/tnsaxis:Move/tnsaxis:Channel_X

    Type

    Stateful

    Nice name

    PTZ movement on channel X

    Source instance

    Nice name

    PTZ channel

    Type

    integer

    Name

    PTZConfigurationToken

    ValueNice name
    XChannel X

    Data instance

    Nice name

    Moving

    Type

    boolean

    Name

    is_moving

    isPropertyState

    true

    PTZ ready event

    The PTZ ready event is true when the PTZ functionality is ready to be used. The event can for example be used to detect that PTZ is ready to use after restart or after a PTZ driver has been installed.

    For products with multiple view areas or multiple video channels, there is one event for each view area or video channel. The channel element in SourceInstance specifies the view area or video channel.

    Topic

    Name

    tns1:PTZController/tnsaxis:PTZReady

    Type

    Stateful

    Nice name

    PTZ ready

    Source instance

    Nice name

    Channel

    Type

    integer

    Name

    channel

    Data instance

    Nice name

    Ready

    Type

    boolean

    Name

    ready

    isPropertyState

    true

    PTZ control queue event

    The PTZ control queue event shows the user who is controlling the PTZ functionality.

    Topic

    Name

    tns1:PTZController/tnsaxis:ControlQueue

    Type

    Stateful

    Nice name

    PTZ control queue

    Source instance

    Nice name

    PTZ channel

    Type

    integer

    Name

    PTZConfigurationToken

    ValueNice name
    1Channel 1
    2Channel 2
    ......
    number of channelsChannel n

    Data instance

    Nice name

    Queue owner

    Type

    string

    Name

    queue_owner

    isPropertyState

    true

    Autotracking event

    The Autotracking event is true when autotracking is active.

    Topic

    Name

    tns1:PTZController/tnsaxis:AutoTracking

    Type

    Stateful

    Nice name

    Autotracking

    Source instance

    Nice name

    Channel

    Type

    integer

    Name

    channel

    The table below is valid for multichannel products. For single channel products, the channel is always 0.

    ValueNice name
    1
    2
    ...
    n = number of video channels

    Data instance

    Nice name

    Tracking motion

    Type

    boolean

    Name

    tracking

    isPropertyState

    true

    PTZ error event

    A PTZ error event tns1:PTZController/tnsaxis:PTZError is emitted if the PTZ functionality is malfunctioning.

    To retrieve the event declaration, use aev:GetEventInstances.

    Event declaration:
    <tns1:PTZController aev:NiceName="PTZController">
      <tnsaxis:PTZError wstop:topic="true" aev:NiceName="PTZ error">
        <aev:MessageInstance>
          <aev:SourceInstance>
            <aev:SimpleItemInstance aev:NiceName="Channel" Type="xsd:int" Name="channel">
            </aev:SimpleItemInstance>
          </aev:SourceInstance>
          <aev:DataInstance>
            <aev:SimpleItemInstance Type="xsd:string" Name="ptz_error">
            </aev:SimpleItemInstance>
          </aev:DataInstance>
        </aev:MessageInstance>
      </tnsaxis:PTZError>
    </tns1:PTZController>

    Go to PTZ preset action

    Use the Go to PTZ preset action to steer the camera view to a PTZ preset position. When the action is completed, the camera view will return to the home position.

    This action can be run as:

    • fixed action — stay at the preset position for a predefined time (defined by parameter home_timeout)

    • unlimited action — stay at the preset position as long as all event conditions are fulfilled.

    Action ID

    com.axis.action.fixed.goto.preset

    Action ID

    com.axis.action.unlimited.goto.preset

    ParameterValid valuesDescription
    channelUnsigned integerVideo channel
    preset_nameStringName of the PTZ preset to go to. Preset names can be retrieved from axis-cgi/com/ptz.cgi?query=presetposall
    home_timeoutUnsigned integer or -1Number of seconds to wait before returning to the home position.
    Use -1 if the camera view should not return to the home position.

    Autotracking action

    Use the autotracking action to start autotracking from a preset position. When the action is triggered, the camera moves to the preset position preset_name and starts autotracking from that position.

    The action can be run as

      The action can be run as

    • fixed action — continue autotracking until there are no moving objects

    • unlimited action — continue autotracking as long as all conditions are fulfilled

    The action can for example be used in an action rule triggered by a signal from an I/O port. Consider a PTZ camera monitoring a number of doors with door sensors connected to the camera’s I/O ports. When one of the doors is opened, the action rule is triggered and the camera moves to a preset position facing that door and starts follow a person or vehicle coming out of the door.

    Action ID

    com.axis.action.fixed.motiontracking

    Action ID

    com.axis.action.unlimited.motiontracking

    ParameterValid valuesDescription
    channelUnsigned integerThe video channel.
    goto_home_timeoutUnsigned integerFixed action: Number of seconds to wait before returning to the home position when tracking stops.
    preset_nameStringThe PTZ preset position from which tracking should start.

    Speed dry API

    Description

    The VAPIX® Speed dry API function enables the camera to shake so that water moves over the dome enabling the water to dry faster, thus clearing the camera’s view faster. Water drops from rain or washing equipment may prevent a clear camera view.

    Identification

    VAPIX® Speed dry is available if:

    Property

    Properties.API.HTTP.Version=3

    Property

    Properties.SpeedDry.SpeedDry=yes


    Firmware: 5.65 and later.

    Product category: PTZ cameras.

    Common examples

    Get speed dry capabilites

    Request:
    //<servername>/axis-cgi/speeddry/getcapabilities.cgi
    Response:
    operations/oneshot/@method xs:enum
    operations/oneshot/@runtime xs:integer
    operations/oneshot/@idletime sx:integer

    Initiate speed dry operation

    Request:
    //<servername>/axis-cgi/speeddry/oneshot.cgi
    Response:
    HTTP code:  200 OK
    Content-Type: text/plain

    Get speed dry

    Use ptz.cgi\auxiliary=speeddry executes a one-shot speed dry operation. After the operation has finished the server has an idle time of ~20 seconds, during which other speed dry requests are discarded.

    Request

    Access control

    admin, operator, viewer with PTZ control

    Method

    GET

    Syntax:
    //<servername>/axis-cgi/com/ptz.cgi?auxiliary=speeddry

    Response

    Responses from ptz.cgi?auxiliary=speeddry

    The response is always the same, there is no success or failure information.

    General success response

    General success response from the Speed dry API.

    HTTP code

    : 200 OK

    Content-type

    : application/json

    HTTP code

    : 204 No content

    Content-type

    : N/A

    General error response

    General error response from the Speed dry API.

    HTTP code

    : 200 OK

    Content-type

    : application/json

    HTTP code

    : 204 No content

    Content-type

    : N/A

    Body:
    <?xml version="1.0" encoding="utf-8"?>
    <speeddryResponse SchemaVersion="1.0" xmlns:xsi="//www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="//www.axis.com/vapix/http_cgi/speeddry.xsd">
      <GeneralError>
        <ErrorCode>[error code]</ErrorCode>
        <ErrorDescription>[description]</ErrorDescription>
      </GeneralError>
    </speeddryResponse>

    Supported elements, attributes and values:

    ElementDescription
    speeddryResponseContains the response.
    GeneralErrorError.
    ErrorCodeA numeric error code. See table below.
    ErrorDescriptionDescription of the error.
    Error codeDescriptionCGI
    204No content