Get room zones information

📘

Only HDL410 systems support this feature.

This tutorial shows how to get zone information for the room where Nureva® audio devices are located.

What is a zone?

A zone is an area within a room. Defining zones allows you to trigger events when sound is detected within a zone. For example, you can set up a meeting room system to select a particular camera angle when a particular zone is triggered.

How to configure zones in Nureva Console

The sound location data stream endpoint will return zone data when any zones are triggered. Learn more about triggered zones

In the example room below, the presenter stands at the front of the room while the audience comprises the remainder of the room. Employing zones in this room allows one camera to be focused on the presenter while a second camera points at the audience. During a meeting, the appropriate camera view can be selected based on whether sound is currently detected in the presenter zone versus in the audience zone.

Number of zones

A maximum of eight zones can be created in each room.

Zone type

There is currently only one type of zone available, called "Switching." This indicates that the zone is intended to define support for camera switching in the room. There are more zone types planned for the future.

Overlapping zones

Zones of the same type cannot overlap.

Zone position

All zones are rectangular. Zone position is defined by two points:

• point1 gives the (x, y) coordinate of one corner of the zone's bounding box, in millimeters
• point2 gives the (x, y) coordinate of the opposite corner of the zone's bounding box, in millimeters

The same coordinate system is used for both the zone position and the Start Sound Location Data Stream endpoint.

When interpreting the zone position coordinates, (0,0) represents the center of the microphone and speaker bar that is connected to the port labeled “1” on the connect module. Positive x values are in the east direction. Positive y values are in the north direction.

The microphone and speaker bar plugged into Port 1 on the connect module will always be situated on the south wall of the room layout.

What zone information is available?

Each zone has a type, a position (geometry), a label and a unique ID.

Minimum role required: general

The Get Room Zones Information endpoint can be accessed with the general role or any role of a higher level.

Overview

1. Use the Get Room Zones Information endpoint to get the current zones' configuration.
2. Check that the request was successful.

Instructions

Step 1 - Send a request to get the current zones' configuration

Use the Get Room Zones Information endpoint to a make a request to get the zone information for the room where the Nureva audio conferencing system is connected:

1. Set the path with the IP address of the Nureva device followed by /api/v1/room/zones.
2. Update the headers to include Authorization as key and the value being Nureva followed by the authParameters received from the login endpoint.
3. Update the headers to include Nureva-Client-Id as key and integration_app_name as the value.
4. Update the headers to include Nureva-Client-Version as key and 0.0.1 as the value.
5. Send the GET request. The code sample below is a request to retrieve the zone information for the room of the device with the IP address of 10.0.0.1.

curl --request GET \
     --url https://10.0.0.1/api/v1/room/zones \
     --header 'Authorization: Nureva Z2VuZXJhbDo=' \
     --header 'Nureva-Client-Id: integration_app_name' \
     --header 'Nureva-Client-Version: 0.0.1'

6. If the call is successful, an HTTP status code of 200 OK will be returned.

Step 2 - Parse the response

The example response below indicates that:

1. There are two zones configured in the room, labeled: "Audience" and "Front of room" respectively.
2. Both zones are camera switching zones as indicated by the "Switching" type.
3. The zone labeled: "Audience" is a rectangle with coordinates (x: -4118, y: 17) and (x: 1674, y: 9511), or in other words one point is 4,118 mm to the left and 17 mm in front and the opposing point is 1,674 mm to the right and 9,511 mm in front of the microphone and speaker bar connected to Port 1 of the connect module. Meanwhile, the zone labeled: "Front of room" is a rectangle with coordinates (1827, 91) and (10110, 9396).
4. The zone labeled "Audience" has a unique identifier of 1b642a7f-7c41-4bfa-bdc8-f8cd4b544b0f and the zone labeled "Front of room" has a unique identifier of 16c8cf24-7955-4fb5-b90d-bf90b43bf0b9.

{
  "zones": [
    {
      "types": ["Switching"],
      "geometry": {
        "point1": {
          "x": -4118,
          "y": 17
        },
        "point2": {
          "x": 1674,
          "y": 9511
        }
      },
      "label": "Audience",
      "id": "1b642a7f-7c41-4bfa-bdc8-f8cd4b544b0f"
    },
    {
      "types": ["Switching"],
      "geometry": {
        "point1": {
          "x": 1827,
          "y": 91
        },
        "point2": {
          "x": 10110,
          "y": 9396
        }
      },
      "label": "Front of room",
      "id": "16c8cf24-7955-4fb5-b90d-bf90b43bf0b9"
    }
  ]
}

✅

Tutorial complete!

You now know how to get the room zone information.