区域 (ROI) API 指南#

概述#

感兴趣区域 (ROI) 是 Metropolis Occupancy Alerts 中的一个功能模块，用于检测定义的感兴趣区域中是否存在对象，并提供与其相关的时间序列指标和警报。

ROI API 端点#

分析 Web API 通过 Ingress 控制器公开。

URL 前缀为 http://<INGRESS-HOST-IP>:<INGRESS-PORT>/emdx/。

将 INGRESS-HOST-IP 替换为 Jetson 设备 IP。将 INGRESS-PORT 替换为 30080 或 Ingress 配置中定义的最后一个值。

ROI API 版本 v2#

ROI API 有一个新的主要版本 v2，它与早期版本不向后兼容。此版本仍然支持 JPS 1.0 版本附带的先前版本。但是，强烈建议采用/迁移到 v2 版本。v2 版本在路径 /api/v2 下提供。早期版本仍然在 /api 下运行。

创建 ROI 配置#

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

必需的查询参数#

sensorId

描述：需要插入 roi 配置的传感器。

类型：字符串

示例：sensorId=Amcrest_3

坐标

描述：区域每个顶点的 (x,y) 坐标数组。

类型：数组[字典{x: int, y: int}]

示例：{“x”: 323, “y”: 1067}

可选的查询参数#

deleteIfPresent

描述：如果为 true，则将删除此 roi 的任何现有 roi 时间序列数据。

类型：布尔值

如果未指定或为 false，则保留 roi 时间序列数据。

注意：需要在 HTTP POST 请求的 HTTP 标头中设置 User-Type: Admin。

错误响应#

响应正文：请参阅页面末尾的错误响应正文定义。

HTTP 状态代码

403：授权错误。缺少 User-Type 标头。必须存在且值为 Admin 500：内部服务器错误

检索 ROI 计数直方图#

给定时间范围和指定固定间隔的 ROI 中人数的计数直方图。

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

必需的查询参数#

sensorId

描述：需要返回 ROI 指标的传感器。

类型：字符串

示例：Amcrest_3

roiId

描述：需要返回 ROI 指标的 ROI 的 ID。

类型：字符串

示例：checkout_1

fromTimestamp

描述：需要返回 roi 计数的起始时间戳

类型：UTC / GMT 时间戳字符串

示例：2020-10-30T20:00:00.000Z

toTimestamp

描述：需要返回 roi 计数和警报的结束时间戳。如果未指定，则默认为服务器上的 UTC.NOW

类型：UTC / GMT 时间戳字符串

示例：2020-10-30T20:05:00.000Z

可选的查询参数#

bucketSizeInSec

描述：请求的时间范围（fromTimestamp - toTimestamp）被分成 interval bucketSizeInSec 秒的直方图。最小值为 1 秒。最大值为 864000 秒（1 天）

类型：整数

objectType

描述：可选的 objectTypes 参数，用于按对象类型（例如，人、车辆等）细分计数

类型：字符串

按对象类型细分计数的可能方法如下

1) 除了所有对象类型的累积计数外，仅返回特定对象类型的计数。objectTypes=People,Vehicle

2) 除了所有对象类型的累积计数外，返回所有对象类型的计数。objectTypes=*

当未指定 objectTypes 时，它仅返回所有对象类型的累积计数。

错误响应#

响应正文：请参阅页面末尾的错误响应正文定义。

HTTP 状态代码

422：未找到请求的 sensorId 和时间范围的 ROI 指标 500：内部服务器错误

示例#

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

5 分钟时间范围被分成 1 秒 bucketSizeInSec 的直方图。

响应#

{
   "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
                  }
               ]
            }
         ]
      }
   ]
}

响应正文属性#

rois[].id

描述：为其提供直方图计数的 ROI 的 ID

类型：字符串

rois[].histogram

描述：特定 ROI 的每种对象类型（例如，人、车辆等）的计数直方图

类型：对象数组

检索 ROI 总计数#

给定时间范围内 ROI 内的人总数。

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

必需的查询参数#

sensorId

描述：需要返回 ROI 指标的传感器。

类型：字符串

示例：Amcrest_3

roiId

描述：需要返回 ROI 指标的 ROI 的 ID。

类型：字符串

示例：checkout_1

fromTimestamp

描述：需要返回 roi 计数的起始时间戳

类型：UTC / GMT 时间戳字符串

示例：2020-10-30T20:00:00.000Z

toTimestamp

描述：需要返回 roi 计数和警报的结束时间戳。如果未指定，则默认为服务器上的 UTC.NOW

类型：UTC / GMT 时间戳字符串

示例：2020-10-30T20:05:00.000Z

可选的查询参数#

objectType

描述：可选的 objectTypes 参数，用于按对象类型（例如，人、车辆等）细分计数

类型：字符串

按对象类型细分计数的可能方法如下

1) 除了所有对象类型的累积计数外，仅返回特定对象类型的计数。objectType=People,Vehicle

2) 除了所有对象类型的累积计数外，返回所有对象类型的计数。objectType=*

当未指定 objectType 时，它仅返回所有对象类型的累积计数。

错误响应#

响应正文：请参阅页面末尾的错误响应正文定义。

HTTP 状态代码

422：未找到请求的 sensorId 和时间范围的 ROI 指标 500：内部服务器错误

示例#

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

响应#

{
   "roiOccupancy": [
      {
         "roiId": "checkout-1",
         "objects": [
            {
               "type": "..",
               "averageCount": 2,
               "sumCount": 10
            }
         ]
      },
      {
         "roiId": "checkout-2",
         "objects": [
            {
               "type": "..",
               "averageCount": 1,
               "sumCount": 5
            }
         ]
      }
   ]
}

响应正文属性#

roiOccupancy：每个 ROI 的计数项数组。其中每个项目包含特定 ROI（例如“checkout-1”、“checkout-2”）的计数

以下是每个项目的属性

roiId 返回计数的 ROI 的 ID。

objects 每个对象类型的计数项数组。

以下是每个项目的属性

sumCount

描述：类型对象（例如，人、车辆等）的总唯一计数

类型：整数

averageCount

描述：类型对象（例如，人、车辆等）的平均计数

类型：整数

type

描述：对象类型（例如，人、车辆等）

类型：字符串。

创建 ROI 警报规则#

支持三种类型的警报规则，即占用、占用阈值切换和增量

占用警报类型#

当 ROI 中存在的人数countThreshold 持续时间超过 timeInterval 秒时发出警报

示例：当 ROI 中持续存在 20 人或更多人超过 10 秒时发出警报的警报规则。

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

必需的正文参数#

sensorId

描述：需要定义 ROI 警报的传感器。

类型：字符串

示例：Amcrest_1

规则

描述：警报规则数组。

类型：数组

示例:

{
   "ruleId": "d8f0484f-b464-4a92-a5a9-649a14160b53",
   "id": "checkout_1",
   "type": "roi",
   "ruleType": "occupancy",
   "name": "Overcrowding scenario rule",
   "timeInterval": 10,
   "countThreshold": 100
}

每个警报规则由以下参数组成

必需的规则参数#

ruleId

描述：此警报规则的唯一 ID。这在所有警报规则中应该是唯一的

类型：字符串

示例：UUID，例如 cd2218f6-e4d2-4ad4-9b15-3396e4336064

id

描述：指此警报规则应用于的 ROI 的 id。

类型：字符串

示例：checkout_1

type

描述：此警报相关的分析模块类型。固定值“roi”

类型：字符串

示例：roi

ruleType

描述：警报规则类型。固定值“占用”

类型：字符串

示例：用于定义占用类型警报规则的占用

timeInterval

描述：时间窗口，以秒为单位指定。
countThreshold 需要持续满足的时间，以便满足警报规则。

类型：浮点数

示例: 10

countThreshold

描述：要满足此警报规则，ROI 中需要存在的人数阈值。

类型：整数

示例: 20

可选的规则参数#

name

描述：警报规则的用户友好名称。用于在客户端显示

类型：字符串

示例：“过度拥挤场景规则”

注意

您需要在 HTTP POST 请求的 HTTP 标头中设置 User-Type=Admin。

错误响应#

响应正文：请参阅页面末尾的错误响应正文定义。

HTTP 状态代码

403：授权错误。缺少 User-Type 标头。必须存在且值为 Admin 500：内部服务器错误

占用阈值切换警报类型#

基于 ROI 中存在的超过或低于人数 countThreshold 的占用率变化发出警报。最简单的用例是当 ROI 状态从空闲（占用率 == 0）变为占用（占用率 >= 1）时。反之亦然，当占用率从占用（占用率 >= 1）变为空闲（占用率 == 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,
            }
         ]
      }
   ]
}

必需的正文参数#

sensorId

描述：需要配置 ROI 警报的传感器

类型：字符串

示例：Amcrest_1

规则

描述：警报规则数组。

类型：数组。

示例:

{
   "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,
      }
   ]
}

每个警报规则由以下参数组成

必需的规则参数#

ruleId

描述：此警报规则的唯一 ID。这在所有警报规则中应该是唯一的

类型：字符串

示例：UUID，例如 ae511b25-a57d-483f-b4c5-c30e039cc375

id

描述：指此警报规则应用于的 ROI 的 id

类型：字符串

示例：checkout_1

type

描述：分析模块类型。固定值“roi”

类型：字符串

示例：roi

ruleType

描述：警报规则类型。固定值“occupancy_threshold_switch”

类型：字符串

值：occupancy_threshold_switch

timeInterval

描述：时间窗口。以秒为单位指定。指示计数需要高于或低于阈值多长时间才能发出警报。它用于处理占用计数中的抖动，并平滑此类抖动情况下的警报发布。

类型：浮点数

示例: 1

countThreshold

描述:

用于确定状态的计数阈值

计数阈值为零表示当占用率从零变为大于零时发出警报。反之亦然，当占用率从大于零的正数降至零时，会发出警报。

正的非零计数阈值 (N) 表示我们希望在占用率超过 N 时发出警报，发出 UP 警报（direction=up），而在占用率降至 N 或以下时，发出 DOWN 警报（direction=down）。

类型：整数

示例: 1

可选的规则参数#

参数

描述：规则特定参数，指定为名称、值对的数组。

类型：名称、值对的数组

示例：以下是 occupancy_threshold_switch 警报类型支持的有效参数
parameters: [
  {
     "name":"time_interval_up",
     "value":1,
  },
  {
     "name":"time_interval_down",
     "value":2,
  }
]
time_interval_up：从空闲状态变为占用状态的时间间隔 time_interval_down：从占用状态变为空闲状态的时间间隔

name

描述：警报规则的用户友好名称。用于在客户端显示

类型：字符串

示例：“过度拥挤场景规则”

注意

您需要在 HTTP POST 请求的 HTTP 标头中设置 User-Type=Admin。

错误响应#

响应正文：请参阅页面末尾的错误响应正文定义。

HTTP 状态代码

403：授权错误。缺少 User-Type 标头。必须存在且值为 Admin 500：内部服务器错误

增量警报类型#

基于 timeInterval 秒内进入/退出 ROI 的人数 countThreshold 发出警报。

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"
      }
   ]
}

必需的正文参数#

sensorId

描述：需要配置 ROI 警报规则的传感器。

类型：字符串。

示例：Amcrest_1

规则

描述：警报规则数组。

类型：数组。

示例:

{
   "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"
      }
   ]
}

每个警报规则由以下参数组成

必需的规则参数#

ruleId

描述：此警报规则的唯一 ID。这在所有警报规则中应该是唯一的

类型：字符串

示例：UUID，例如 fb298ea4-30aa-4085-b860-42e37c5bf8d1

id

描述：指此警报规则应用的 ROI 的 id。

类型：字符串

示例：checkout_1

type

描述：分析模块类型。固定值“roi”

类型：字符串

示例：roi

ruleType

描述：警报规则类型。固定值“增量”

类型：字符串

值：增量

timeInterval

描述：以秒为单位指定。countThreshold 人数应在 timeInterval 内进入（direction=enter）或退出（direction=exit）ROI 以满足警报规则的时间间隔

类型：浮点数

示例: 5

countThreshold

描述：应在 timeInterval 内进入（direction=enter）或退出（direction=exit）的阈值人数，以满足警报规则。

类型：整数

示例: 10

方向

描述：警报规则的方向性。规则是指离开 ROI（退出）或进入 ROI（进入）的对象数量吗

类型：字符串

枚举：entry/exit 之一

示例：exit

注意

您需要在 HTTP POST 请求的 HTTP 标头中设置 User-Type=Admin。

错误响应#

响应正文：请参阅页面末尾的错误响应正文定义。

HTTP 状态代码

403：授权错误。缺少 User-Type 标头。必须存在且值为 Admin 500：内部服务器错误

删除 ROI 警报规则#

HTTP DELETE

/api/v2/config/rule/alerts/roi?sensorId=Amcrest_1&roiId=checkout_1&ruleId=fb298ea4-30aa-4085-b860-42e37c5bf8d1

必需的查询参数#

sensorId

描述：需要删除 ROI 警报的传感器。

类型：字符串

示例：sensorId=Amcrest_1

roiId

描述：需要删除警报规则的 ROI 的“id”

类型：字符串

示例：id=checkout_1

ruleId

描述：要删除的警报规则的唯一 ruleId

类型：字符串

示例：fb298ea4-30aa-4085-b860-42e37c5bf8d1

注意：您需要在 HTTP DEL 请求的 HTTP 标头中设置 User-Type: Admin。

错误响应#

响应正文：请参阅页面末尾的错误响应正文定义。

HTTP 状态代码

403：授权错误。缺少 User-Type 标头。必须存在且值为 Admin 422：未找到指定 sensorId、roiId 和 ruleId 的警报规则 500：内部服务器错误

检索 ROI 警报#

可以使用 API 系列检索警报，该 API 系列具有针对传感器、ROI、时间范围的筛选，并可选地支持分页。

特定传感器在时间范围内的所有 ROI 警报。

HTTP GET

/api/v2/alerts/roi?sensorId=Amcrest_1&fromTimestamp=2021-09-16T06:06:00.000Z&toTimestamp=2021-09-16T06:07:00.000Z

响应#

{
  "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"
               }
            ]
        }
    ]
}

必需的查询参数#

sensorId

描述：需要返回 ROI 警报的传感器。

类型：字符串

示例：sensorId=Amcrest_1

fromTimestamp

描述：需要返回 ROI 警报的起始时间戳

类型：UTC / GMT 时间戳字符串

示例：2020-10-30T20:00:00.000Z

toTimestamp

描述：需要返回 ROI 警报的结束时间戳。如果未指定，则默认为服务器上的 UTC。NOW

类型：UTC / GMT 时间戳字符串

示例：2020-10-30T20:05:00.000Z

可选的查询参数#

limit

描述：要返回的最大警报数

类型：整数

它遵循基于时间的简单分页。获取 10 个（限制）在 2021-09-16T06:06:00.000Z (fromTimestamp) 和 2021-09-16T06:07:00.000Z (endTimestamp) 之间发生的警报。标准是 endTimestamp > fromTimestamp

响应正文属性#

增量和占用类型的警报在其属性部分中还包含导致这些警报的对象列表。每个对象都由其 ID 和类型表示。例如，id=100，type=Person。

错误响应#

响应正文：请参阅页面末尾的错误响应正文定义。

HTTP 状态代码

422：未找到请求的 sensorId、roiId 和时间范围的 ROI 警报 500：内部服务器错误

示例#

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

删除 ROI 配置#

HTTP DELETE

/api/v2/config?roi?sensorId=Amcrest_1&roiId=checkout_1

必需的查询参数#

sensorId

描述：需要删除 ROI 配置的传感器。

类型：字符串

示例：sensorId=Amcrest_1

roiId

描述：要删除的 ROI 的“id”。

类型：字符串

示例：roiId=checkout_1

注意

您需要在 HTTP DELETE 请求的 HTTP 标头中设置 User-Type: Admin。

错误响应#

响应正文：请参阅页面末尾的错误响应正文定义。

HTTP 状态代码

403：授权错误。缺少 User-Type 标头。必须存在且值为 Admin 422：未找到指定 sensorId 和 roiId 的 ROI 配置 500：内部服务器错误

错误响应正文#

所有 API 的错误响应都是具有以下属性的 JSON 对象。

{
   "error": "#Detailed error string"
}