Skip to main content

Coordinate conversion API

Overview​

This API is based on the Device Configuration API framework. For guidance on how to use these APIs, please refer to Device Configuration APIs.

The VAPIX® Coordinate conversion API is used to query which coordinate spaces that a product has knowledge of, and to convert points located in one coordinate space to another.

Use cases​

Get the list of supported coordinate spaces​

The following example illustrates a request to a device that has a video channel (channel 1) and a radar channel (channel 2). The device supports conversion of points between the the two, in addition to device-centric Cartesian coordinates, and a geographical position.

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/coordinate-conversion-api/v1/spaces
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": [
        {
            "name": "geographicPosition"
        },
        {
            "name": "radarImage@2"
        },
        {
            "name": "cameraImage@1"
        },
        {
            "name": "deviceCentricCartesian"
        }
    ]
}

This additional example will illustrate a request to a device that supports conversion between multiple different cameraImage coordinate spaces. This is useful for products with multiple video channels. Unlike the previous example, this device has no knowledge of device-centric coordinates or its geographical position.

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/coordinate-conversion-api/v1/spaces
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": [
        {
            "name": "cameraImage@1"
        },
        {
            "name": "cameraImage@2"
        },
        {
            "name": "cameraImage@3"
        },
        {
            "name": "cameraImage@4"
        },
        {
            "name": "cameraImage@quad"
        }
    ]
}

Convert a set of points between coordinate spaces​

Trigger the convert action associated with the source coordinate space with a POST payload to convert a set of points between two coordinate spaces. The resulting points are delivered in the response. Depending on the two coordinate spaces and the input point, conversion can fail for one or more points. This is denoted in the output data by an empty list. An input point can also result in multiple output points.

The example below will illustrate a request that converts three points from the video image to spherical world coordinates.

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  "http://my-device/config/rest/coordinate-conversion-api/v1/spaces/cameraImage@1/convert" \
  --data '{
    "data": {
        "destination": "deviceCentricCartesian",
        "points": [
            [
                [
                    0.25,
                    0.25
                ]
            ],
            [
                [
                    0.05,
                    0.9
                ]
            ],
            [
                [
                    0.0675,
                    0.395
                ]
            ]
        ]
    }
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "points": [
            [
                [
                    -25.0,
                    50.3,
                    0.3
                ]
            ],
            [
                [
                    31.0,
                    33.1,
                    0.0
                ]
            ],
            []
        ]
    }
}

In this example, two of the points are successfully converted, while conversion failed for the third point. This can happen if the input point does not have a corresponding point in the desired coordinate space. For example, a pixel in a camera image that is located on the horizon or in the sky does not have a well-defined location in the world.

API definition​

Structure​

coordinate-conversion.v1 (Root Entity)
    ├── spaces (Entity Collection)
        ├── name (Property)
        ├── convert (Action)

Entities​

coordinate-conversion.v1​

  • Description: Root entity for the Coordinate Conversion API.
  • Type: Singleton
  • Operations
    • Get
  • Attributes
    • Dynamic Support: No
Properties​

This entity has no properties.

Actions​

This entity has no actions.

coordinate-conversion.v1.spaces​

  • Description: The collection of supported coordinate spaces.
  • Type: Collection (Key Property: name)
  • Operations
    • Get
  • Attributes
    • Dynamic Support: No
Properties​
name​
  • Description: The name of this coordinate space.
  • Datatype: string
  • Operations
    • Get (Permissions: admin, operator, viewer)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​
convert​

  • Description: Convert a set of points from this coordinate space to another.

  • Request Datatype: ConvertRequest

  • Response Datatype: ConvertResponse

  • Trigger Permissions: admin, operator, viewer

  • Attributes

    • Dynamic Support: No

Data Types​

ConvertRequest​

  • Description: Request object for the convert action.
  • Type: complex
  • Fields
    • destination
    • points
      • Description: The list of points to convert to the destination space and system.
      • Type: PointList
      • Nullable: No / Gettable: Yes

ConvertResponse​

  • Description: Response object for the convert action.
  • Type: complex
  • Fields
    • points
      • Description: The list of output points from a conversion request. Points which could not be converted are represented as an empty list.
      • Type: OutputPointList
      • Nullable: No / Gettable: Yes

CoordinateSpaceAndSystem​

  • Description: A string identifying a coordinate system defined inside a single instance of a coordinate space.
  • Type: string

OutputPointList​

  • Description: A list of output points that have been converted.
  • Type: array
  • Element type: PointList
  • Null Value: No

Point​

  • Description: Denotes a point with real coordinates in a coordinate space. The interpretation of the individual coordinate values of this point is dependent on the coordinate system used in that space.

  • Type: array

  • Element type: number

  • Null Value: No

  • Maximum item number: 12

PointList​

  • Description: A list of points.
  • Type: array
  • Element type: Point
  • Null Value: No
  • Maximum item number: 1000

coordinate_space_and_system​

This string describes a single instance of coordinate space, such as cameraImage. Coordinate spaces with multiple instances, such as cameras with multiple sensors, have the specific instance denoted by a suffix separated from the name with @, for example cameraImage@2. The suffix can be omitted if there is a unique instance of that coordinate space.

The following sections describe the coordinate spaces found in this API. A given device will not always recognize all coordinate spaces or support conversion between all of them. Query the spaces entity directly beneath the root entity to list which coordinate spaces a particular device is aware of.

deviceCentricCartesian​

The deviceCentricCartesian identifier describes a Cartesian coordinate system in world space. A point is defined as an array consisting of three elements: _x_ _y_ and _z_. This device originates from the right-handed Cartesian coordinate system, with the orientation of the three coordinate axes is defined by the "ONVIF™ Analytics Service Specification":

  • The positive _x_ axis points to the right as seen from the device.
  • The positive _y_ axis points away from the device.
  • The positive _z_ axis points upwards.
geographicPosition​

The geographicPosition identifier describes a geographical position on Earth. A point is defined as an array consisting of three elements: latitude, longitude and elevation.

The latitude and longitude specified in degrees as defined by the Global Positioning System (GPS) and WGS-84. Latitude is 0° at the equator and increases northwards. Longitude is 0° at the IERS reference meridian and increases eastwards. Elevation, if present, is specified in meters.

cameraImage​

The cameraImage identifier describes a point in the image from a video stream. The coordinate system used is normalized and resolution-independent and maps the visible image to the interval [0, 1] in both dimensions:

  • An _x_ value of 0 or 1 denotes the left or right edge of the image.
  • An _y_ value of 0 or 1 denotes the top or bottom edge of the image.

A coordinate outside the interval [0, 1] can still be valid, but will describe a position outside of the visible image.

radarImage​

The radarImage identifier describes a point in the image from a generated radar stream. The coordinate system is the same as the one described in cameraImage.