Region of Interest (ROI) API Guide#
Overview#
Region of interest (ROI) is a functional module in the Metropolis Occupancy Alerts that detects object presence in a defined region of interest and provides time series metrics, and alerts related to it.
ROI API Endpoints#
Analytics Web API is exposed via Ingress Controller.
The URL prefix is http://<INGRESS-HOST-IP>:<INGRESS-PORT>/emdx/.
Replace the INGRESS-HOST-IP with the Jetson device IP. Replace the INGRESS-PORT with 30080 or the last value defined in Ingress configuration.
ROI API Version v2#
The ROI API has a new major version v2 which is not backward compatible with earlier version. The previous version shipped with JPS 1.0 version is still supported in this release. However it is highly recommended to adopt/migrate to v2 version. The v2 version is provided under path /api/v2. Where the earlier version is still functional under /api.
Create ROI configuration#
HTTP POST
/api/v2/config/roi?sensorId=Amcrest_3
{ "deleteIfPresent": true, "rois": [ { "id": "checkout_1", "name": "Checkout Counter 1", "coordinates": [ { "x": 200, "y": 200 }, { "x": 600, "y": 200 }, { "x": 600, "y": 600 }, { "x": 200, "y": 600 } ] } ], "sensorId": "Amcrest_3" }
Mandatory query parameters#
sensorId
description: Sensor for which roi config needs to be inserted.
type: string
example: sensorId=Amcrest_3
coordinates
description: Array of the (x,y) coordinate of the each vertex of the region.
type: Array[Dict{x: int, y: int}]
example: {“x”: 323, “y”: 1067}
Optional query parameters#
deleteIfPresent
description: If true any existing roi timeseries data will be delete for this roi.
type: boolean
If not specified or false the roi timeseries data is retained.
Note: Need to set User-Type: Admin in the HTTP header of the HTTP POST request.
Error Response#
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
403: Authorization error. User-Type header missing. Must be present with Admin as value 500: Internal server error
Retrieve ROI counts histogram#
Histogram of count of people in ROI for a given time range and a specified fixed interval.
HTTP GET
/api/v2/metrics/occupancy/roi/histogram?sensorId=Amcrest_3&roiId=checkout_1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-31T01:00:00.000Z
Mandatory query parameters#
sensorId
description: Sensor for which ROI metrics need to be returned.
type: string
example: Amcrest_3
roiId
description: ID of ROI for which ROI metrics need to be returned.
type: string
example: checkout_1
fromTimestamp
description: lower bound of the timestamp for which roi count needs to be returned
type: UTC / GMT timestamp string
example: 2020-10-30T20:00:00.000Z
toTimestamp
description: Upper bound of timestamp for which roi count & alert needs to be returned.If Not specified defaults to UTC.NOW on the server
type: UTC / GMT timestamp string
example: 2020-10-30T20:05:00.000Z
Optional query parameters#
bucketSizeInSec
description : Requested time range (fromTimestamp - toTimestamp) fragmented into histogram of interval bucketSizeInSec seconds. Minimum value of 1sec. Maximum value of 864000 sec (1 day)
type: int
objectType
description: An optional objectTypes parameter used to breakdown counts by object type (e.g People, Vehicle,…)
type: string
Possible way to breakdown counts by object type is as follows
1) To return counts for only specific type of objects in addition to cumulative counts across all types of objects. objectTypes=People,Vehicle
2) To return counts for all object types in addition to cumulative counts across all types of objects. objectTypes=*
When objectTypes is not specified it returns only cumulative counts across all types of objects.
Error Response#
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
422: No ROI metrics found for the requested sensorId and time range 500: Internal server error
Example#
HTTP GET
/api/v2/metrics/occupancy/roi/histogram?sensorId=Amcrest_3&roiId=checkout_1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-30T20:05:00.000Z&bucketSizeInSec=1000
The 5 minutes time range is fragmented into histograms of 1 sec bucketSizeInSec.
Response#
{ "bucketSizeInSec": "1", "rois": [ { "id": "checkout_1", "histogram": [ { "end": "2020-01-26T19:16:30.000Z", "start": "2020-01-26T19:16:29.000Z", "objects": [ { "type": "Person", "avgCount": 1, "minCount": 0, "maxCount": 2 }, { "type": "Box", "avgCount": 1, "minCount": 1, "maxCount": 4 } ] }, { "end": "2020-01-26T19:16:29.000Z", "start": "2020-01-26T19:16:28.000Z", "objects": [ { "type": "Person", "avgCount": 1, "minCount": 0, "maxCount": 2 }, { "type": "Box", "avgCount": 1, "minCount": 1, "maxCount": 4 } ] } ] } ] }
Response body attributes#
rois[].id
description: Id of the ROI for which histogram counts are provided
type: string
rois[].histogram
description: Histogram of counts for each types of objects (e.g People, Vehicle,…) for a specific ROI
type: Array of object
Retrieve ROI total counts#
Total count of people inside the ROI for a given time range.
HTTP GET
/api/v2/metrics/occupancy/roi/count?sensorId=Amcrest_3&roiId=checkout_1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-31T01:00:00.000Z
Mandatory query parameters#
sensorId
description: Sensor for which ROI metrics need to be returned.
type: string
example: Amcrest_3
roiId
description: ID of ROI for which ROI metrics need to be returned.
type: string
example: checkout_1
fromTimestamp
description: lower bound of the timestamp for which roi count needs to be returned
type: UTC / GMT timestamp string
example: 2020-10-30T20:00:00.000Z
toTimestamp
description: Upper bound of timestamp for which roi count & alert needs to be returned.If Not specified defaults to UTC.NOW on the server
type: UTC / GMT timestamp string
example: 2020-10-30T20:05:00.000Z
Optional query parameters#
objectType
description: An optional objectTypes parameter used to breakdown counts by object type (e.g People, Vehicle,…)
type: string
Possible way to breakdown counts by object type is as follows
1) To return counts for only specific type of objects in addition to cumulative counts across all types of objects. objectType=People,Vehicle
2) To return counts for all object types in addition to cumulative counts across all types of objects. objectType=*
When objectType is not specified it returns only cumulative counts across all types of objects.
Error Response#
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
422: No ROI metrics found for the requested sensorId and time range 500: Internal server error
Example#
HTTP GET
/api/v2/metrics/occupancy/roi/count?sensorId=Amcrest_3&roiId=checkout_1&fromTimestamp=2020-10-30T20:00:00.000Z&toTimestamp=2020-10-30T20:05:00.000Z
Response#
{ "roiOccupancy": [ { "roiId": "checkout-1", "objects": [ { "type": "..", "averageCount": 2, "sumCount": 10 } ] }, { "roiId": "checkout-2", "objects": [ { "type": "..", "averageCount": 1, "sumCount": 5 } ] } ] }
Response body attributes#
roiOccupancy: An array of count items per ROI. Where each item contains the counts for a specific ROI (e.g “checkout-1”,”checkout-2”)
Following are the attributes for each item
roiId ID of the ROI for which counts are returned.
objects An array of counts items per object type.
Following are the attributes for each item
sumCount
description: Total unique count for a type of object (e.g People, Vehicle,…)
type: integer
averageCount
description: Average count for a type of object (e.g People, Vehicle,…)
type: integer
type
description: Object type (e.g People, Vehicle,…)
type: string.
Create ROI alert rule#
Three types of alert rules i.e. Occupancy, Occupancy threshold Switch and Increment are supported
Occupancy alert type#
Alert when countThreshold of people present in the ROI continuously for longer than timeInterval seconds
Example: Alert rule to raise an alert when 20 or more people are continously present in the ROI for more than 10 seconds.
HTTP POST
/api/v2/config/rule/alerts/roi
{ "sensorId": "Amcrest_1", "rules": [ { "ruleId": "d8f0484f-b464-4a92-a5a9-649a14160b53", "id": "checkout_1", "type": "roi", "ruleType": "occupancy", "name": "Overcrowding scenario rule", "timeInterval": 10, "countThreshold": 100 } ] }
Mandatory body parameters#
sensorId
description: Sensor for which ROI alert need to be defined.
type: string
example: Amcrest_1
rules
description: array of alert rules.
type: array
example:
{ "ruleId": "d8f0484f-b464-4a92-a5a9-649a14160b53", "id": "checkout_1", "type": "roi", "ruleType": "occupancy", "name": "Overcrowding scenario rule", "timeInterval": 10, "countThreshold": 100 }
Each alert rule consists of following parameters:
Mandatory rule parameters#
ruleId
description: Unique ID for this alert rule. This should be unique across all alert rules
type: string
example: UUID e.g cd2218f6-e4d2-4ad4-9b15-3396e4336064
id
description: refers to the id of the ROI which this alert rule applies to.
type: string
example: checkout_1
type
description: Type of analytics module this alert relates to. Fixed value ‘roi’
type: string
example: roi
ruleType
description: Type of alert rule. Fixed value ‘occupancy’
type: string
example: occupancy for defining and Occupancy type of alert rule
timeInterval
- description: time window, specified in seconds.
Duration for which the countThreshold needs to be satisified continously for the alert rule to be satisfied.
type: float
example: 10
countThreshold
description: Threshold of the count of people which needs to be present in ROI for this alert rule to be fulfilled.
type: int
example: 20
Optional rule parameters#
- name
description: User friendly name for the alert rule. For display purpose on the client side
type: string
example: “Over crowding scenario rule”
Note
You will need to set User-Type=Admin in the HTTP header of the HTTP POST request.
Error Response#
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
403: Authorization error. User-Type header missing. Must be present with Admin as value 500: Internal server error
Occupancy Threshold Switch Alert Type#
Alerts based on change of occupancy above or below countThreshold of people present in the ROI. Most simple use case is when ROI status changes from vacant (occupancy == 0) to occupied (occupancy >= 1). The inverse of this is when occupancy changes from occupied (occupancy >= 1) to vacant ( occupancy == 0).
HTTP POST
/api/v2/config/rule/alerts/roi
{ "sensorId": "Amcrest_1", "rules": [ { "ruleId": "ae511b25-a57d-483f-b4c5-c30e039cc375", "id": "checkout_1", "type": "roi", "ruleType": "occupancy_threshold_switch", "timeInterval": 1, "countThreshold": 1, "parameters": [ { "name":"time_interval_up", "value":1, }, { "name":"time_interval_down", "value":2, } ] } ] }
Mandatory body parameters#
sensorId
description: Sensor for which ROI alert needs to be configured
type: string
example: Amcrest_1
rules
description: array of alert rules.
type: array.
example:
{ "ruleId": "ae511b25-a57d-483f-b4c5-c30e039cc375", "id": "checkout_1", "type": "roi", "ruleType": "occupancy_threshold_switch", "timeInterval": 1, "countThreshold": 1, "parameters": [ { "name":"time_interval_up", "value":1, }, { "name":"time_interval_down", "value":2, } ] }
Each alert rule consists of following parameters:
Mandatory rule parameters#
ruleId
description: Unique ID for this alert rule. This should be unique across all alert rules
type: string
example: UUID e.g ae511b25-a57d-483f-b4c5-c30e039cc375
id
description: Refers to the id of the ROI to which this alert rule applies
type: string
example: checkout_1
type
description: Type of analytics module. Fixed value ‘roi’
type: string
example: roi
ruleType
description: Type of alert rule. Fixed value ‘occupancy_threshold_switch’
type: string
value: occupancy_threshold_switch
timeInterval
description: Time window. Specified in seconds. Indicate the duration for which the counts needs to above or below the threshold for the alert to be raised. It is used to deal jitters in occupancy counts and smoothen the publication of alerts in case of such jitters.
type: float
example: 1
countThreshold
description:
Number of counts threshold used to determine status
countThreshold of zero indicates alert to be raised when occupancy changes from zero to greater than zero. Inverse of this is when occupancy falls to zero from a positive number greater than zero then an alert is raised.
positive non-zero countThreshold (N) means we want to raise alert when occupancy exceeds N raise the UP alert (direction=up) while when the occupancy falls to N or below raise the DOWN (direction=down) alert.
type: int
example: 1
Optional rule parameters#
parameters
description: Rule specific parameters, specified as an array of name, value pairs.
type: array of name, value pairs
example: Following is the valid parameters supported by occupancy_threshold_switch alert type
parameters: [ { "name":"time_interval_up", "value":1, }, { "name":"time_interval_down", "value":2, } ]time_interval_up: The time interval for vacant to occupied state change time_interval_down: The time interval for occupied to vacant state change
name
description: User friendly name for the alert rule. For display purpose on the client side
type: string
example: “Over crowding scenario rule”
Note
You will need to set User-Type=Admin in the HTTP header of the HTTP POST request.
Error Response#
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
403: Authorization error. User-Type header missing. Must be present with Admin as value 500: Internal server error
Increment Alert Type#
Alerts based on countThreshold of people entered/exited in the ROI within timeInterval seconds.
HTTP POST
/api/v2/config/rule/alerts/roi
{ "sensorId": "Amcrest_1", "rules": [ { "ruleId": "fb298ea4-30aa-4085-b860-42e37c5bf8d1", "id": "checkout_1", "type": "roi", "ruleType": "increment", "timeInterval": 1, "countThreshold": 1, "direction": "entry" }, { "ruleId": "9c5632af-ba68-46bc-a997-858bdadc6856", "id": "checkout_1", "type": "roi", "ruleType": "increment", "timeInterval": 5, "countThreshold": 10, "direction": "exit" } ] }
Mandatory body parameters#
sensorId
description: Sensor for which ROI alert rule is to be configured.
type: string.
example: Amcrest_1
rules
description: array of alert rules.
type: array.
example:
{ "sensorId": "Amcrest_1", "rules": [ { "ruleId": "fb298ea4-30aa-4085-b860-42e37c5bf8d1", "id": "checkout_1", "type": "roi", "ruleType": "increment", "timeInterval": 1, "countThreshold": 1, "direction": "entry" }, { "ruleId": "9c5632af-ba68-46bc-a997-858bdadc6856", "id": "checkout_1", "type": "roi", "ruleType": "increment", "timeInterval": 5, "countThreshold": 10, "direction": "exit" } ] }
Each alert rule consists of following parameters:
Mandatory rule parameters#
ruleId
description: Unique ID for this alert rule. This should be unique across all alert rules
type: string
example: UUID e.g fb298ea4-30aa-4085-b860-42e37c5bf8d1
id
description: Refers to the id ROI to which this alert rule applied.
type: string
example: checkout_1
type
description: Type of analytics module. Fixed value ‘roi’
type: string
example: roi
ruleType
description: Type of alert rule. Fixed value ‘increment’
type: string
value: increment
timeInterval
description: Specified in seconds. Time interval during which the countThreshold number of people should enter (direction=enter) or exit (direction=exit) to ROI to satisfy the alert rule
type: float
example: 5
countThreshold
description: Threshold of number of people which should enter (direction=enter) or exit (direction=exit) with timeInterval to satisfy the alert rule.
type: int
example: 10
direction
description: Directionality for the alert rule. Does it rule refer to number of objects leaving ROI (exit) or entering ROI (entry)
type: string
enum: One of entry/exit
example: exit
Note
You will need to set User-Type=Admin in the HTTP header of the HTTP POST request.
Error Response#
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
403: Authorization error. User-Type header missing. Must be present with Admin as value 500: Internal server error
Delete ROI alert rule#
HTTP DELETE
/api/v2/config/rule/alerts/roi?sensorId=Amcrest_1&roiId=checkout_1&ruleId=fb298ea4-30aa-4085-b860-42e37c5bf8d1
Mandatory query parameters#
sensorId
description: Sensor for which ROI alert needs to be deleted.
type: string
example: sensorId=Amcrest_1
roiId
description: ‘id’ of the ROI for which alert rule needs to be deleted
type: string
example: id=checkout_1
ruleId
description: Unique ruleId of the Alert rule which is to be deleted
type: string
example: fb298ea4-30aa-4085-b860-42e37c5bf8d1
Note: You will need to set User-Type: Admin in the HTTP header of the HTTP DEL request.
Error Response#
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
403: Authorization error. User-Type header missing. Must be present with Admin as value 422: No alert rule present for the specified sensorId, roiId and ruleId 500: Internal server error
Retrieve ROI alerts#
Alerts can be retrieved using the family of APIs which has filtering for sensor, ROI, time ranges with optional support for pagination.
All ROI Alerts for a specific sensor for timerange.
HTTP GET
/api/v2/alerts/roi?sensorId=Amcrest_1&fromTimestamp=2021-09-16T06:06:00.000Z&toTimestamp=2021-09-16T06:07:00.000Z
Response#
{ "alerts": [ { "count": 10, "description": "10 people entered roi", "duration": 0.734, "endTimestamp": "2021-09-16T06:07:00.534Z", "id": "unique-alert-id", "ruleId": "fb298ea4-30aa-4085-b860-42e37c5bf8d1", "ruleType": "increment", "sensorId": "Amcrest_3", "startTimestamp": "2021-09-16T06:06:59.800Z", "type": "roi", "direction": "entry", "attributes": [ { "name": "roiId", "value": "checkout_1" }, { "name": "roiName", "value": "Checkout Counter" }, { "name": "objects", "value": [ { "id": "1186", "type": "Person" } ] } ] }, { "count": 10, "description": "more than 5 ppl continuously present in ROI for longer than 10 seconds", "duration": 10.734, "endTimestamp": "2021-09-16T06:07:00.534Z", "id": "unique-alert-id", "ruleId": "fb298ea4-30aa-4085-b860-42e37c5bf8d1", "ruleType": "occupancy", "sensorId": "Amcrest_3", "startTimestamp": "2021-09-16T06:06:59.800Z", "type": "roi", "attributes": [ { "name": "roiId", "value": "checkout_1" }, { "name": "roiName", "value": "Checkout Counter" }, { "name": "objects", "value": [ { "id": "1186", "type": "Person" } ] } ] }, { "count": 5, "description": "ROI occupancy count greater than 5", "duration": 10.734, "endTimestamp": "2021-09-16T06:07:00.534Z", "id": "unique-alert-id", "ruleId": "fb298ea4-30aa-4085-b860-42e37c5bf8d1", "ruleType": "occupancy_threshold_switch", "sensorId": "Amcrest_3", "startTimestamp": "2021-09-16T06:06:59.800Z", "type": "roi", "direction": "up", "attributes": [ { "name": "roiId", "value": "checkout_1" }, { "name": "roiName", "value": "Checkout Counter" } ] } ] }
Mandatory query parameters#
sensorId
description: Sensor for which ROI alerts need to be returned.
type: string
example: sensorId=Amcrest_1
fromTimestamp
description: lower bound of the timestamp for which ROI alert needs to be returned
type: UTC / GMT timestamp string
example: 2020-10-30T20:00:00.000Z
toTimestamp
description: Upper bound of timestamp for which ROI alert needs to be returned.If Not specified defaults to UTC. NOW on the server
type: UTC / GMT timestamp string
example: 2020-10-30T20:05:00.000Z
Optional query parameters#
limit
description: Max number of alerts to be returned
type: integer
It follows Time based simple pagination. Get 10 (limit) alerts which occurred b/w 2021-09-16T06:06:00.000Z (fromTimestamp) and 2021-09-16T06:07:00.000Z (endTimestamp). Criteria is that endTimestamp > fromTimestamp
Response body attributes#
Alerts of type increment and occupancy also has in it’s attributes section the list of objects which resulted in those alerts. Each object is represented by it’s id and type. e.g id=100, type=Person.
Error Response#
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
422: No ROI alerts found for the requested sensorId,roiId and time range 500: Internal server error
Example#
HTTP GET
/api/v2/alerts/roi?sensorId=Amcrest_1&fromTimestamp=2021-09-16T06:06:00.000Z&toTimestamp=2021-09-16T06:07:00.000Z&limit=10
Delete ROI configuration#
HTTP DELETE
/api/v2/config?roi?sensorId=Amcrest_1&roiId=checkout_1
Mandatory query parameters#
sensorId
description: Sensor for which ROI config needs to be deleted.
type: string
example: sensorId=Amcrest_1
roiId
description: ‘id’ of the ROI which is to be deleted.
type: string
example: roiId=checkout_1
Note
You will need to set User-Type: Admin in the HTTP header of the HTTP DELETE request.
Error Response#
Response body: See Error response body definition at the end of the page.
HTTP Status codes:
403: Authorization error. User-Type header missing. Must be present with Admin as value 422: No ROI configuration found for the specified sensorId and roiId 500: Internal server error
Error Response body#
Error response for all API is JSON object with following attributes.
{
"error": "#Detailed error string"
}