On-screen directional indicator

Description

The On-screen directional indicator (OSDI) API makes it possible to set a user-defined name to a location or zone observed by a PTZ camera, e.g. names of buildings, streets or geographical directions. A zone is defined as a range of pan, tilt and zoom coordinates. This means that when the camera is positioned within these coordinates, it is also within the OSDI zone. By using the correct modifiers, the name of the zone can be displayed in the text overlay.

For more information about Text overlays and their modifiers, see Text overlay API.

Model

This API is parameter based and the zones are defined by creating parameter groups and setting their values. Deleting the parameter group will also remove its corresponding zones. A zone, in the context of this API, refers to an area between a pan and a tilt coordinate a 3 dimensional setting.

Identification

Product category: PTZ cameras
Parameter: PTZ.Locator.L#.MaxZones

Common examples

Define an OSDI zone

Use this example to identify which zone the camera is pointing at. This is prepared during the installation of the camera and dictates which zones the OSDI will be set to.

Detect if OSDI is supported

Check the number of supported OSDI zones for image source 1:

http://myserver/axis-cgi/param.cgi?action=list&group=root.PTZ.Locator.L0.MaxZones

If the parameter exists and its value is greater than 0, the OSDI setup will be displayed.

Create a zone

Create an OSDI zone parameter group:

http://myserver/axis-cgi/param.cgi?action=add&root.PTZ.Locator.L0.Zone.Z.Name=NewZone&root.PTZ.Locator.L0.Zone.Z.Pan=0.06%3A29.54&root.PTZ.Locator.L0.Zone.Z.Tilt=-44.99%3A-30.06&root.PTZ.Locator.L0.Zone.Z.Enabled=yes&group=root.PTZ.Locator.L0.Zone&template=ptzlocator

API specification

PTZ.Locator

The following parameters showcases the OSDI zone capabilities and how to best utilize them.

Security level to view the list: Viewer
Security level to update the list: Operator or N/A

PTZ.Locator.L#.<parameter>

The valid values for the index of image sources (L#) ranges from L0 to the number of image sources -1.

Parameter	Security level	Description
`MaxZones=<integer>`	`N/A`	Read-only parameter that indicates the maximum number of `Zone.Z#` parameter groups supported.

PTZ.Locator.L#.Zone

The methods explained in this group are used to configure the OSDI zone through parameter handling.

Security level to view the list: Viewer
Security level to update the list: Operator

PTZ.Locator.L#.Zone.Z#.<parameter>

The valid values for the index of image sources (L#) ranges from L0 to the number of image sources -1. The valid values for the index of zones (Z#) ranges from Z0 to MaxZones -1.

Parameter	Description
`Enabled=yes\|no`	Determines if the zone is currently used.
`Name=<string>`	Identifies the zone.
`Pan=<float>:<float>`	The pan coordinates, presented in degrees, for the zone.
`Tilt<float>:<float>`	The tilt coordinates, presented in degrees, for the zone.
`Zoom=<unsigned integer>:<unsigned integer>`	If set, this parameter will specify the zoom levels and when the zone should be considered active. If it is not set, the zoom level will not be taken into consideration for this zone.

For a description of valid ranges for Pan, Tilt and Zoom, see Pan/tilt/zoom API.