Cloud APIsLocal APIs
nureva.com

Get room zones information

Suggest Edits

📘

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 8 zones can be created in each room.


Zone type

There is currently only 1 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 2 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 zone position and room layout information. As shown in the image below, rooms are assumed to be rectangular, and each wall is identified by a cardinal direction: north, south, west and east.

When interpreting the zone position coordinates, the origin (0,0) is the southwest corner of the room. 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.


types An array of 1 or more strings defining the purpose of this zone. Presently, the only possible type of zone is 'Switching'. This indicates that this zone is intended to define support for camera switching within this room. It is not possible for the same type of zone to appear more than once within this array.
geometry Position of the zone defined by a set of coordinates where the southwest corner of the room is taken as the origin (0,0) of the coordinate system. All zones are rectangular or square with their bounding box defined by the point1 and point2 properties on opposite corners.
  • point1: The x and y location, in room coordinates, of one corner of the zones’ bounding box in in millimeters. point1 is the opposite corner to point2.
  • point2: The x and y location, in room coordinates, of one corner of the zones’ bounding box in in millimeters. point2 is the opposite corner to point1.
label The label given to the zone, defined by end users in Nureva Console
id A unique identifier

Overview

Use Get room zones information to get the room layout information.


Instructions

⚠️

Before you begin

Learn how to add your IP address or hostname and make a WebSocket connection to the configured IP and port of the server.

Step 1 - Send the request

  1. 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:
  2. Pass "v1/room/zones" in to the request property
  3. Fill in requestId and clientId according to the request format guide
  4. Send the request

The example request below will get the zone information.

{
  "request": "v1/room/zones",
  "requestId": "94486c98-fd25-458e-84ae-df5376fab299",
  "clientId": "test"
}

Step 2 - Parse the response

The example response below indicates that:

  1. There is 1 zone configured in the room.
  2. The zone is a camera switching zone as indicated by the "Switching" type.
  3. The zone is a rectangle covering from the origin (0,0) to 4,567 mm on the x axis and 7,294 mm on the y axis.
  4. The zone has a human readable label of "Front of room".
  5. The zone has a unique identifier of "4b674687-0c4d-4849-b0d6-e60608a53f1d".
{ 
  "request": "v1/room/zones",
  "requestId": "94486c98-fd25-458e-84ae-df5376fab299",
  "clientId": "test",
  "body": {
    "zones": [{    
      "types": ["Switching"],
      "geometry": { 
          "point1": {
            "x": 0,
            "y": 0,
          },
          "point2": {
            "x": 4567,
            "y": 7294,
          },
      },
      "label": "Front of room",
      "id": "4b674687-0c4d-4849-b0d6-e60608a53f1d",
    }]
  }
}

✅

Tutorial complete!

You now know how to get the room zone information.

Updated about 1 month ago