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 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

Field Name	Type	Description
id	string	The zone id for this. Must be one of "z1", "z2", "z3", "z4" or "z5". This Zone Id is used in the Activity Filter Syntax. Must be unique within the zones for a given Accessory.
name	string	The user supplied name for the zone.
vertices	array of vertex objects	Each vertex is an object with keys x and y in floating point values.
color	string	Used in UI for visual continuity. Must be unique within the zones for a given Accessory. Uses the same values as Object Color.
interior	bool	true if this zone area the interior of the points. (Defaults to true, and can be left out.)
aspectRatio	string	(Optional) defaults to "16:9" if not present.

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.