What is the Nx Witness API request to perform PTZ commands?
/api/ptz can be used to perform a PTZ read or write operation with 2 required parameters: camera ID and PTZ command.
Read the Camera Identifiers support article to see how you can obtain a camera ID. View the chart below to see a list of supported PTZ commands and their parameters.
PTZ Command | PTZ Command Description | Parameter (Valid Range) | Parameter Description |
ContinuousMovePtzCommand | Start a continuous PTZ move.To stop moving, set all parameters to 0. | xSpeed (-1.0 through +1.0) | |
ContinuousFocusPtzCommand | Start PTZ focus in/out. | speed (-1.0 through +1.0) | Direction and speed of the focus action. |
GetDevicePositionPtzCommand | Read the camera’s current position. Returns xPos, yPos, and zPos in the range defined by the camera. | ||
AbsoluteDeviceMovePtzCommand | Move the camera to an absolute position. When the camera reports its PTZ capabilities to Nx Witness Server during initialization, the range of Pos parameters is sent to Nx Witness Server. PTZ capabilities can not be read via API. | xPos (defined by camera) yPos (defined by camera) zPos (defined by camera) speed (0 through 1.0) | X-Axis movement Y-Axis movement Field of View (FOV) Movement speed |
GetLogicalPositionPtzCommand | Read the camera’s current position. Returns xPos and yPos in the range -180 through +180. Returns zPos in the range 0 through 180. | ||
AbsoluteLogicalMovePtzCommand | Move the camera to an absolute position. | xPos (-180 through +180) yPos (-180 through +180) zPos (0 through 180) speed (0 through 1.0) | X-Axis movement Y-Axis movement Field of View (FOV) Movement speed |
GetPresetsPtzCommand | Read the PTZ presets list. | ||
CreatePresetPtzCommand | Create a PTZ preset. | presetId presetName | Internal preset name Public preset name |
UpdatePresetPtzCommand | Update a PTZ preset display name. | presetId presetName | Internal preset name Public preset name |
RemovePresetPtzCommand | Update a PTZ preset display name. | presetId | Internal preset name |
ActivatePresetPtzCommand | Go to a PTZ preset. | presetId speed (0 through 1.0) | Internal preset name |
GetToursPtzCommand | Read the PTZ tours list. | ||
ActivateTourPtzCommand | Activate a PTZ tour. | tourId tourName | Internal tour name Public tour name |
How to perform a PTZ command via Nx Witness API?
- [Optional] Check if the camera supports PTZ functionality.
- Initiate the API request with Nx Witness Server. Parameters should be passed as a JSON object in the POST message body with content type "application/json".
- Enter your credentials to verify the API request and perform the PTZ command.
import requests
from requests.auth import HTTPBasicAuth, HTTPDigestAuth
import time
import urllib3
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
USERNAME = 'local account username'
PASSWORD = 'local account password'
SERVER_URL = 'server ip and port' # https://<server_ip>:<sever_port>
CAMERA_ID = '7f430fb3-b3f7-362b-7de5-4de46386c343'
ptz_dict = {'NoPtzCapabilities': 0, 'ContinuousPanCapability': 1, 'ContinuousTiltCapability': 2,
'ContinuousZoomCapability': 4,
'ContinuousFocusCapability': 8, 'ContinuousRotationCapability': 536870912, 'AbsolutePanCapability': 16,
'AbsoluteTiltCapability': 32, 'AbsoluteZoomCapability': 64, 'AbsoluteRotationCapability': 1073741824,
'RelativePanCapability': 1024, 'RelativeTiltCapability': 2048, 'RelativeZoomCapability': 16384,
'RelativeRotationCapability': 32768, 'RelativeFocusCapability': 8388608, 'ViewportPtzCapability': 128,
'FlipPtzCapability': 256, 'LimitsPtzCapability': 512, 'DevicePositioningPtzCapability': 4096,
'LogicalPositioningPtzCapability': 8192, 'PresetsPtzCapability': 65536, 'ToursPtzCapability': 131072,
'ActivityPtzCapability': 262144, 'HomePtzCapability': 524288, 'AsynchronousPtzCapability': 1048576,
'SynchronizedPtzCapability': 2097152, 'VirtualPtzCapability': 4194304, 'AuxiliaryPtzCapability': 16777216,
'NativePresetsPtzCapability': 134217728}
def check_status(response, verbose):
if response.status_code == requests.codes.ok:
if verbose:
print("Request successful\n{0}".format(response.text))
return True
print(response.url + " Request error {0}\n{1}".format(response.status_code, response.text))
return False
def request_api(url, uri, method, **kwargs):
server_url = f'{url}{uri}'
response = requests.request(
method,
server_url,
**kwargs
)
if not check_status(response, False):
exit(1)
if response.headers.get('Content-Type') == 'application/json':
return response.json()
else:
return response.content
def check_ptz_capability(ptz_value, ptz_capability):
return int(ptz_value) & ptz_dict[ptz_capability]
def main():
#STEP 1
camera_info = request_api(SERVER_URL, f'/ec2/getCamerasEx?id={CAMERA_ID}', 'GET',
auth=HTTPDigestAuth(USERNAME, PASSWORD), verify=False)
camera_info = camera_info[0]['addParams']
for item in camera_info:
if item['name'] == 'ptzCapabilities':
ptz_value = item['value']
break
else:
print("Cannot find information about camera's PTZ capabilities")
exit()
if check_ptz_capability(ptz_value, 'NoPtzCapabilities'):
print('Does not support PTZ')
exit()
#STEP 2-3
request_api(SERVER_URL, f'/api/ptz?cameraId={CAMERA_ID}&command=GetDevicePositionPtzCommand', 'GET',
auth=HTTPDigestAuth(USERNAME, PASSWORD), verify=False)
if check_ptz_capability(ptz_value, 'ContinuousPanCapability'):
request_api(SERVER_URL, f'/api/ptz?cameraId={CAMERA_ID}&command=ContinuousMovePtzCommand&xSpeed=1&ySpeed=0&zSpeed=0',
'GET', auth=HTTPDigestAuth(USERNAME, PASSWORD), verify=False)
time.sleep(1)
request_api(SERVER_URL, f'/api/ptz?cameraId={CAMERA_ID}&command=ContinuousMovePtzCommand&xSpeed=0&ySpeed=0&zSpeed=0',
'GET', auth=HTTPDigestAuth(USERNAME, PASSWORD), verify=False)
if check_ptz_capability(ptz_value, 'PresetsPtzCapability'):
request_api(SERVER_URL, f'/api/ptz?cameraId={CAMERA_ID}&command=ActivatePresetPtzCommand&presetId=1&speed=1.0',
'GET', auth=HTTPDigestAuth(USERNAME, PASSWORD), verify=False)
if __name__ == '__main__':
main()
Comments
0 comments
Article is closed for comments.