VAPIX® version 3

View Area API

This document is copyright protected and is the property of Axis Communications AB and may not be copied,
reproduced or distributed in any way without the prior written consent of Axis Communications AB.

Copyright Notice
This document is copyright protected and is the property of Axis Communications AB and
may not be copied, reproduced or distributed in any way without the prior written
consent of Axis Communications AB.
©2008 Axis Communications AB. AXIS COMMUNICATIONS, AXIS, ETRAX, ARTPEC and
VAPIX are registered trademarks of Axis AB. All other company names and products are
trademarks or registered trademarks of their respective companies. We reserve the right
to introduce modifications without notice.

Terms of Use
The use of the AXIS VAPIX application programming interface (hereinafter referred
to as "the INTERFACE" as further specified below, is subject to the terms and
conditions of the License Agreement below. By using the INTERFACE and the written
specification of the INTERFACE (hereinafter referred to as “the INTERFACE
DESCRIPTION"), whether in whole or in part, you agree to be bound by the terms of
the License Agreement.

VAPIX LICENSE AGREEMENT

This is a legal agreement (the “License Agreement”) between you (either individual or an
entity) and Axis Communications AB (hereinafter referred to as “Axis”).
1. GRANT OF LICENSE
Axis hereby grants to you the right to use the INTERFACE and the INTERFACE
DESCRIPTION for the sole and limited purpose of creating, manufacturing and
developing a solution that integrates any unit or portion included in the product range
of Axis network cameras, Axis video servers, Axis video encoders and Axis video
decoders (as defined by Axis at its discretion) and to market, sell and distribute any
such solution.
2. COPYRIGHT
The INTERFACE and the INTERFACE DESCRIPTION are owned by Axis and are
protected by copyright laws and international treaty provisions. Any use of the
INTERFACE and/or the INTERFACE DESCRIPTION outside the limited purpose set
forth in Section 1 above is strictly prohibited.
3. NO REVERSE ENGINEERING
You may not reverse engineer, decompile, or disassemble the INTERFACE except to
the extent required to obtain interoperability with other independently created
computer programs as permitted by mandatory law.
4. TERMINATION
This License is effective until terminated. Your rights under this License will terminate
automatically without notice from Axis if you fail to comply with any term(s) of this
License. Upon the termination of this License, you shall cease all use and disposition
of the INTERFACE and/or THE INTERFACE DESCRIPTION whether for the purpose set
forth in Section 1 above or not.
5. GOVERNING LAW
This agreement shall be deemed performed in and shall be construed by the laws of
Sweden. All disputes in connection with this agreement shall be finally settled by
arbitration in accordance with the Rules of the Arbitration Institute of the Stockholm
Chamber of Commerce. The place of arbitration shall be Malmö, Sweden. The
language of the proceedings, documentation and the award shall be English.

VAPIX® View Area API 2

This document is copyright protected and is the property of Axis Communications AB and may not be copied,
reproduced or distributed in any way without the prior written consent of Axis Communications AB.

6. DISCLAIMER
6.1. THE INTERFACE AND THE INTERFACE DESCRIPTION ARE DELIVERED FREE OF
CHARGE AND “AS IS” WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK AS
TO THE USE, RESULTS AND PERFORMANCE OF THE INTERFACE AND THE
INTERFACE DESCRIPTION IS ASSUMED BY THE USER/YOU. AXIS DISCLAIMS ALL
WARRANTIES, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT AND PRODUCT LIABILITY,
OR ANY WARRANTY ARISING OUT OF ANY PROPOSAL, SPECIFICATION OR
SAMPLE WITH RESPECT TO THE INTERFACE AND THE INTERFACE DESCRIPTION.
6.2. YOU ARE YOURSELF RESPONSIBLE FOR EXAMINING WHETHER THE INTERFACE
AND THE INTERFACE DESCRIPTION ARE ENCUMBERED BY OR INFRINGES UPON
A RIGHT HELD BY A THIRD PARTY. AXIS, WHO HAS NOT UNDERTAKEN ANY
SUCH INVESTIGATIONS, HAS NO KNOWLEDGE OF NOR DOES AXIS ACCEPT ANY
LIABILITY FOR ANY SUCH ENCUMBRANCES OR INFRINGEMENTS.
6.3. YOU UNDERTAKE NOT TO PURSUE ANY CLAIMS WHATSOEVER AGAINST AXIS OR
ITS AFFILIATES RELATING TO OR EMANATING FROM THE INTERFACE AND THE
INTERFACE DESCRIPTION.
6.4. AXIS SHALL NOT BE LIABLE FOR LOSS OF DATA, LOSS OF PRODUCTION, LOSS
OF PROFIT, LOSS OF USE, LOSS OF CONTRACTS OR FOR ANY OTHER
CONSEQUENTIAL, ECONOMIC OR INDIRECT LOSS WHATSOEVER IN RESPECT OF
USE OR DISPOSITION OF THE INTERFACE AND THE INTERFACE DESCRIPTION.
6.5. AXIS TOTAL LIABILITY FOR ALL CLAIMS IN ACCORDANCE WITH THE USE OF THE
INTERFACE AND THE INTERFACE DESCRIPTION SHALL NOT EXCEED THE PRICE
PAID FOR THE INTERFACE AND THE INTERFACE DESCRIPTION.
6.6. YOU SHALL INDEMNIFY AND HOLD AXIS AND ITS AFFILIATES HARMLESS FROM
ANY CLAIMS WHATSOEVER FROM ANY THIRD PARTY AGAINST AXIS OR ITS
AFFILIATES RELATING TO OR EMANATING FROM YOUR USE OF THE INTERFACE
AND THE INTERFACE DESCRIPTION UNDER THIS LICENSE AGREEMENT. THE
FOREGOING INDEMNIFICATION INCLUDES BUT IS NOT LIMITED TO ANY AND
ALL DAMAGES, COSTS AND EXPENSES (INCLUDING REASONABLE ATTORNEYS’
FEES).
_____________________________

VAPIX® View Area API 3

This document is copyright protected and is the property of Axis Communications AB and may not be copied,
reproduced or distributed in any way without the prior written consent of Axis Communications AB.

Table of Contents
VAPIX LICENSE AGREEMENT .................................................................................. 2 
1  Overview ...................................................................................................... 5 
1.1  Description .............................................................................................. 5 
1.2  History ................................................................................................... 5 
2  Prerequisites ................................................................................................. 5 
2.1  Identification ........................................................................................... 5 
2.2  Dependencies .......................................................................................... 5 
3  Common Examples ......................................................................................... 6 
3.1  Check for view area support ...................................................................... 6 
3.2  Add a view area ....................................................................................... 6 
3.3  Request MJPEG video over HTTP ................................................................. 7 
3.4  Request video stream over RTSP ................................................................ 7 
4  Parameters ................................................................................................... 8 
4.1  Enable and Name ..................................................................................... 8 
4.1.1  [Image.I#] ....................................................................................... 8 
4.2  Privacy masking and motion detection ......................................................... 8 
4.2.1  [Image] ............................................................................................ 9 
4.2.2  [ImageSource] .................................................................................. 9 
4.3  PTZ ...................................................................................................... 10 
4.3.1  [PTZ.ImageSource.I0] ...................................................................... 10 
4.3.2  [PTZ.Various.V#] ............................................................................. 10 
5  HTTP API .................................................................................................... 11 
5.1  DPTZ control ......................................................................................... 11 
5.2  DPTZ configuration ................................................................................. 11 
5.3  Video streaming ..................................................................................... 12 
6  References .................................................................................................. 12 

VAPIX® View Area API 4

This document is copyright protected and is the property of Axis Communications AB and may not be copied,
reproduced or distributed in any way without the prior written consent of Axis Communications AB.

1 Overview
1.1 Description
View area support adds multiple digital PTZ view areas within a camera image that are
streamed and controlled separately, in much the same way that multiple cameras are
accessed and controlled in a multi-port video encoder with one IP address.
Each view area is a defined area within a mega-pixel image and has its own video
streaming configuration, PTZ configuration and home positions. These view areas are
controlled and accessed using the camera URL option.
A view area could be used, for example, where one megapixel camera monitors a large
area such as the front of a business at a relatively low resolution. But within the camera
image, one view area could be configured to monitor a particular part of the image such
as a cash register at much higher resolution to facilitate face recognition. Using view
areas saves bandwidth by concentrating the higher resolution monitoring to a much
smaller area of the entire camera image.

1.2 History
Version Date Comment

1.00 13-Apr-10 Initial version

2 Prerequisites
2.1 Identification
Properties: Properties.PTZ.PTZ=yes 1 , Properties.PTZ.DigitalPTZ=yes1,
Properties.Image.NbrOfViews=<positive integer> 2
Product category: Axis megapixel cameras
VAPIX version: 3

2.2 Dependencies
Parameter handling:
• The different view areas are enabled and locked using Parameter Management
defined in the HTTP API (VAPIX® version 3) (see 6 References).
• The camera URL option is used to identify the view areas.
Digital PTZ:
• The size and location of the view areas are controlled and configured using PTZ.
See the Parameter Specifications (VAPIX® version 2) for information about
parameters, descriptions and values.
• The camera URL option is used to identify the view areas.

1
PTZ is used to configure view areas, but it is not needed for viewing a view area if PTZ is not requested.
2
Properties.Image.NbrOfViews is the maximum number of view areas, each with its own image stream
configuration. It is the maximum camera URL option value when streaming video.

VAPIX® View Area API 5

This document is copyright protected and is the property of Axis Communications AB and may not be copied,
reproduced or distributed in any way without the prior written consent of Axis Communications AB.

Video streaming:
• The different view areas are streamed according to the RTSP API (VAPIX® version
3), and the Image and Video section in the HTTP API (VAPIX® version 3).
• Streaming configuration of the different view areas is done using the normal
image stream parameters.
• The camera URL option is used to identify the view areas.

3 Common Examples
3.1 Check for view area support
Example: See if the megapixel camera has view area support

http://<servername>/axis-cgi/param.cgi?action=list
&group=Properties.API.HTTP.Version,Properties.PTZ.PTZ,
Properties.PTZ.DigitalPTZ,Properties.Image.NbrOfViews

Response:

Properties.API.HTTP.Version=3
Properties.PTZ.PTZ=yes
Properties.PTZ.DigitalPTZ=yes
Properties.Image.NbrOfViews=8

3.2 Add a view area

Example: Add a view area, set its position and disable PTZ for that channel.
This is done in the following steps.
1. Enable the stream configuration for a camera. In this example we enable camera
3, which image stream configuration is found in Image.I2.

http://myserver/axis-cgi/admin/param.cgi?action=update&Image.I2.Enabled=yes

Response:

OK

2. Name the view area by assigning a name to the image stream configuration for
camera 3. The default name for camera 3, "View area 3", is here changed to 'My
area'.

http://myserver/axis-cgi/admin/param.cgi?action=update
&Image.I2.Name=My%20area

Response:

OK

3. Move camera 3 to the chosen pan/tilt/zoom position.

http://myserver/axis-cgi/com/ptz.cgi?camera=3&zoom=7000&pan=50&tilt=50

VAPIX® View Area API 6

This document is copyright protected and is the property of Axis Communications AB and may not be copied,
reproduced or distributed in any way without the prior written consent of Axis Communications AB.

4. Set the home position of camera 3. In this example it is named 'MyPreset'.

http://myserver/axis-cgi/com/ptzconfig.cgi?camera=3
&setserverpresetname=MyPreset&home=yes

5. Disable digital PTZ for camera 3 by locking it.

http://myserver/axis-cgi/admin/param.cgi?action=update
&PTZ.Various.V3.Locked=true

Response:

OK

3.3 Request MJPEG video over HTTP

Example: Request an MJPEG video stream of camera 3 over HTTP.

http://myserver/axis-cgi/mjpg/video.cgi?camera=3

For the complete API see the HTTP API (VAPIX® version 3) (see 6 References).

3.4 Request video stream over RTSP

Example: Request a video stream of camera 3 over RTSP.

PLAY rtsp://myserver/axis-media/media.amp?camera=3 RTSP/1.0

CSeq: 4
User-Agent: Axis AMC
Session: 12345678
Authorization: Basic cm9vdDpwYXNz

For a complete API see the RTSP API (VAPIX® version 3).

VAPIX® View Area API 7

This document is copyright protected and is the property of Axis Communications AB and may not be copied,
reproduced or distributed in any way without the prior written consent of Axis Communications AB.

4 Parameters
4.1 Enable and Name
4.1.1 [Image.I#]
Group range: 0-N*
Where N* = Image.NbrOfConfigs - 1

Parameter Default Valid Access Description

value values Control

Enabled no1 yes, no1 Read: Enable/disable the view area

admin, configured for this group.
operator,
When the view area is disabled, it is
viewer
neither possible to stream video nor
Write: perform PTZ operations.
admin1 ,
operator

Name View area String Read: Name of the view area configured for
<nbr> admin1 , this group.
operator,
The <nbr> starts from 1, e.g. "View
viewer
area 1" in Image.I0.Name.
Write:
admin,
operator

Note:
1
Image.I0 has default yes, and is read-only for all users.

4.2 Privacy masking and motion detection

Privacy masking
Privacy masking is defined for the whole image, and not for the defined positions of the
different view areas. This means that the configured coordinates are related to the
complete image. If a privacy mask is configured, that part of the image will be masked
out in all view areas whose PTZ positions are currently set to cover that part of the
image. For more information about privacy masking please see section 6 References.
The parameter configuration is done in Image.I0. Note that Image.I0 cannot be disabled
and has a fixed, read only value of yes. When configuring privacy masks, use a video
stream with the option 'overview=1' (see 5.3 Video streaming).
Motion detection:
Motion detection can be defined for the entire image so that if you zoom in to a different
part of the camera image, the motion detection window does not move to the new
image. For example, say that within the camera image you have configured a motion
detection window for the entrance to a building, but zoom in to a tree to left of the
building’s entrance. If motion detection is defined for the entire image, even if the
camera is used to zoom in on the tree to the left of the entrance, the motion detection
window does not move away from the building’s entrance.

VAPIX® View Area API 8

This document is copyright protected and is the property of Axis Communications AB and may not be copied,
reproduced or distributed in any way without the prior written consent of Axis Communications AB.

So, if motion detection is set up for the entire image, the configured coordinates are
related to the complete image. Also, use a video stream with the option 'overview=1'
(see 5.3). See section 6 References for further information about motion detection.
The parameters Image.MotionDetection and ImageSource.MotionDetection define how
motion detection operates. See below.

4.2.1 [Image]

Parameter Default Valid Access Description

value values Control

MotionDetection no yes, no Read: If set to yes, video motion detection

admin, windows are configured to follow one
operator or more view areas.

4.2.2 [ImageSource]

Parameter Default Valid Access Description

Value values Control

MotionDetection yes yes, no Read: If set to yes, video motion detection

admin, is configured for the entire image; it
operator does not follow one or more view
areas.
When configuring motion detection
windows, use a video stream with the
option 'overview=1' (see 5.3).

VAPIX® View Area API 9

This document is copyright protected and is the property of Axis Communications AB and may not be copied,
reproduced or distributed in any way without the prior written consent of Axis Communications AB.

4.3 PTZ
4.3.1 [PTZ.ImageSource.I0]

Parameter Default Valid Access Description

value values Control

PTZEnabled1 false true,false Read: admin, Turn a camera’s digital PTZ

operator, functionality on or off.
viewer
The default value is "false".
Write: admin,
operator

MaxZoom1 Product 100-1000 Read: admin, Maximum allowed zoom.2

dependent operator
Changing this parameter will
Write: admin, also result in limiting the
operator available resolutions.

Notes:
1
If you are using a VAPIX® 2 product, PTZEnabled and MaxZoom are found at
ImageSource.I0.DigitalPTZ.Enabled and ImageSource.I0.DigitalPTZ.MaxZoom
respectively.
2
To determine the value for MaxZoom, take the width of the largest resolution your
camera supports and divide it by the width of the resolution you want to use.
Then take that value and multiply it by 100.

For example, say that you want to be able to zoom in to 640x480, and the
maximum supported resolution for your camera is 1280x960. The value for
MaxZoom will be: 100(1280/640) = 200 (i.e. set value to 200). It will then be
possible to zoom in to an area that is 640x480, and the largest resolution to
stream will be 640x480.

4.3.2 [PTZ.Various.V#]
The # is replaced with a group number starting from one, e.g. PTZ.Limit.L1. Maximal
value must be >= minimal value.
Group range: 1-N*
(Where N = PTZ.NbrOfCameras)

Parameter Default Valid Access Description

value values Control

Locked true true,false Read: admin, Turn if the position is locked.

operator,
When the position is locked no
viewer
PTZ commands are accepted on
Write: admin that channel.
When starting up, the camera
will go to the home position, if
any.

VAPIX® View Area API 10

This document is copyright protected and is the property of Axis Communications AB and may not be copied,
reproduced or distributed in any way without the prior written consent of Axis Communications AB.

5 HTTP API
This section includes additional API's for view area support.

5.1 DPTZ control

The following additional parameters and values are supported when view area support is
included:

<parameter>=<value> Values Description

camera=<int> 1, ...1 Selects the camera. If omitted, the default camera

is used.
Note that if a camera is disabled or locked, no PTZ
actions are accepted on that camera.

Note:
1
Max number product dependent, defined by PTZ.NbrOfCameras.

5.2 DPTZ configuration

The following additional parameters and values are supported when view area support is
included:

<parameter>=<value> Values Description

camera=<int> 1, ...1 Selects the camera. If omitted, the default camera

is used.
Note that if a camera is disabled or locked, no PTZ
actions are accepted on that camera.

Note:
1
Max number product dependent, defined by PTZ.NbrOfCameras.

VAPIX® View Area API 11

This document is copyright protected and is the property of Axis Communications AB and may not be copied,
reproduced or distributed in any way without the prior written consent of Axis Communications AB.

5.3 Video streaming

The complete API for video streaming is defined in the RTSP API (VAPIX® version 3), and
the Image and Video section of the HTTP API (VAPIX® version 3).
The following additional parameters and values are supported when view area support is
included:

<parameter>=<value> Values Description

camera=<int> 1, ...1 Selects the camera. If omitted, the default camera

is used.
Note that it is only possible to get a video stream if
the camera is enabled.

overview=<int> 1, 0 Set to 1 to get the complete image from the image

source. Default 0, if omitted.
I.e. ignore digital PTZ movements and get the
complete image.

Note:
1
Max number product dependent, defined by Image.NbrOfConfigs .

6 References
All VAPIX® documentation is available at:
http://www.axis.com/techsup/cam_servers/dev/cam_http_api_index.php
HTTP API (VAPIX® Version 3)
RTSP API (VAPIX® Version 3)
Parameter Specification (VAPIX® Version 2)

VAPIX® View Area API 12