A Zone is user defined region comprised of three or more vertices. Users can define zones for the Notification API or the Search API. Each zone has a user defined name and color. The name can be used in notifications, whereas the color is purely for UI consistency across clients. A zone is specific to an AccessoryAccessory - A unique device within the system. An accessory can be any of type and is represented by a unique Accessory Id. An accessory is linked to an account via an accountId. Within this API, a singular Circle camera is an Accessory.. Zones are universal on the Accessory level, and all clients will see the same list of zones per Accessory. Zones are retrieved via Get Zones by Accessory Id and set via Set Zones by Accessory Id. A maximum of 5 user-defined zones are allowed.

There is a special system defined zone called the Remainder Zone.

Definition

attribute_name ::= "motionZones"

user_values ::= string
    "z1"
  | "z2"
  | "z3"
  | "z4"
  | "z5"
 
system_values ::= string
  "zR" Remainder Zone

Coordinate System

Each vertex is made up of two points, an X and a Y value. The coordinate system goes from 0 to 1.0 in each direction with (0,0) being the top left corner of the video frame, (1.0,1.0) being the bottom right, and (0.5,0.5) being the middle. X goes across the image, while Y goes down the image. Each point can be a full floating point value. Coordinate points are resolution independent and always use the full width as 1.0 and the full height as 1.0.

A zone is typically made up of four to eight vertices

Examples

{
 "id": "z1",
 "name": "Front Window",
 "vertices": [
  { "x": 0.25, "y": 0.25 },
  { "x": 0.75, "y": 0.25 },
  { "x": 0.75, "y": 0.75 },
  { "x": 0.25, "y": 0.75 }
 ],
 "color": "BU",
}

The example below shows a complex shaped zone.

{
 "id": "z2",
 "name": "Funny Clock",
 "vertices": [
  { "x": 0, "y": 0.5 },
  { "x": 0.125, "y": 0.25 },
  { "x": 0.375, "y": 0.25 },
  { "x": 0.5, "y": 0.5 },
  { "x": 0.375, "y": 0.75 },
  { "x": 0.125, "y": 0.75 },
 ],
 "color": "YE",
}

Remainder Zone

The Remainder Zone is a special system defined Zone which represents all of the space which is not contained within any of the zones defined by the user. The remainder zone has a system wide unique id found below. It can be used in the Activity Filter Syntax as part of the Get Activities by Accessory Id and Notification Events filtering. The Remainder Zone will not be listed in the results of Get Zones by Accessory Id nor can be it set in Set Zones by Accessory Id as it is system calculated.

In the image below, the light green area is the automatically computed Remainder Zone, since z1 and z2 are user defined zones.

In the image below, since there are no user-defined zones, the Remainder Zone is the entire image.