Get room layout zones information

📘

This feature is supported by HDL300, Dual HDL300, HDL410, and HDX systems.

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. There are two types of zones, camera zones and active zones.

Camera zones

Camera zones are only supported by HDL410 and HDX devices.

Defining camera 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 camera 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.

For HDL410 devices, a maximum of eight camera zones can be created in each room, and for HDX devices, a maximum of sixteen camera zones can be created in each room. Camera zones can be positioned outside of the configured room dimensions, however, the zones cannot overlap.

Active zones

Active zones are only supported by HDL300 and Dual HDL300 devices.

Defining an active zone allows you to only get audio pickup for remote participants in that particular zone. For example, the room could be configured such that only the audio surrounding a particular speaker is picked up for remote participants.

As the examples below depict, there can only be one active zone per room and the active zone must be attached to an audio component. One of the edges of the active zone is lined up with the audio component and the zone is centered on that edge.

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 audio component positions, zone positions and sound location data. Refer to the coordinate system diagram in the Start Device Data Stream endpoint. The origin is defined as the center back of the primary audio component.

When interpreting the zone position coordinates, (0,0) represents the center back of the primary audio component. Positive x values are in the east direction. Positive y values are in the north direction.

The primary audio component will always be oriented to be facing away from the south wall of the room layout.

What zone information is available?

Each zone has a type, an on or off status, a position (geometry), a label, and a unique ID.

Minimum role required: general

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

Overview

1. Use the Get Room Layout 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 Layout 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/layout.
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/layout \
     --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 for an HDL410 device indicates that:

1. There are two zones configured in the room, labeled: "Audience" and "Front of room" respectively.
2. Both zones are camera 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 center back of the primary audio component. 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": [
    {
      "type": "Switching",
      "on": true,
      "geometry": {
        "point1": {
          "x": -4118,
          "y": 17
        },
        "point2": {
          "x": 1674,
          "y": 9511
        }
      },
      "label": "Audience",
      "id": "1b642a7f-7c41-4bfa-bdc8-f8cd4b544b0f"
    },
    {
      "type": "Switching",
      "on": true,
      "geometry": {
        "point1": {
          "x": 1827,
          "y": 91
        },
        "point2": {
          "x": 10110,
          "y": 9396
        }
      },
      "label": "Front of room",
      "id": "16c8cf24-7955-4fb5-b90d-bf90b43bf0b9"
    }
  ]
}

The example response below for a Dual HDL300 device indicates that:

1. There is a zone configured of type "Active" attached to the second audio component ("AUDIO_BAR_1").
2. The active zone is on, so, only audio within the zone will get picked up.
3. The zone is a rectangle with coordinates (x: 3279, y: 4772) and (x: 8079, y: 7500), or in other words one point is 3,279 mm to the right and 4,772 mm in front and the opposing point is 8,079 mm to the right and 7,500 mm in front of the center back of the primary audio component.
4. The zone has a unique identifier of 34b2d5a0-918a-4842-99d0-7281c58160a7.

{
  "zones": [
    {
      "type": "Active",
      "activeZoneControl": {
        "attachedAudioComponentPositionId": "AUDIO_BAR_1"
      },
      "on": true,
      "geometry": {
        "point1": {
          "x": 3279,
          "y": 4772
        },
        "point2": {
          "x": 8079,
          "y": 7500
        }
      },
      "id": "34b2d5a0-918a-4842-99d0-7281c58160a7",
      "label": "Active zone"
    }
  ]
}

✅

Tutorial complete!

You now know how to get the room zone information.