mikehaldas/IP-Camera-API

# Viewtron IP Camera API 服务器 一个 Python HTTP 服务器，用于接收和处理来自 Viewtron IP 摄像头和 NVR 的 HTTP Post 报警事件。 Viewtron IP 摄像头和 NVR 包含一个 HTTP API，供软件开发人员创建自定义应用程序、业务自动化和家庭自动化。AI 软件嵌入在 Viewtron AI 安防摄像头中——所有 AI 推理都在摄像头本身上进行，检测不需要云服务或外部服务器。当发生 AI 事件时，摄像头或 NVR 会向你的服务器的 webhook endpoint 发送带有 XML payload 的 HTTP Post。该服务器解析 XML、提取事件数据和图像、将事件记录到 CSV，并将快照图像保存到磁盘。 该服务器支持 **IP Camera 直接 (v1.x)** 和 **NVR 转发 (v2.0)** 两种报警格式。版本检测是自动完成的。 ## Viewtron API 开发者指南 **完整文档门户：** https://videos.cctvcamerapros.com/developer/ 基于 Docusaurus 构建的文档站点包含应用程序指南、API 参考、Python SDK 文档以及 Home Assistant 集成设置。所有页面也以 Markdown 格式提供在 [`docs/`](docs/) 目录中。 单文件参考：https://github.com/mikehaldas/IP-Camera-API/blob/main/docs/viewtron-api-guide.md ## 车牌识别 [](https://www.youtube.com/watch?v=aifIKamg-ls) Viewtron LPR 摄像头实时检测并读取车牌。服务器接收每次检测的车牌号码、车牌图像和概览快照。v1.x IPC 格式包含白名单/黑名单授权状态。v2.0 NVR 格式包含车辆属性识别：车牌颜色、车辆类型、颜色、品牌和型号。 | 来源 | smartType | 数据 | |--------|-----------|------| | IPC v1.x | `VEHICE` / `VEHICLE` | 车牌号码、车牌图像、概览、白名单/黑名单 | | NVR v2.0 | `vehicle` | 车牌号码、车牌颜色、车辆类型/颜色/品牌/型号、车牌截图、概览 | 在此处观看 Viewtron LPR 摄像头视频：https://videos.cctvcamerapros.com/tag/alpr-lpr-camera ## 人脸检测 [](https://www.youtube.com/watch?v=GZOLUuTFqcw) Viewtron 人脸检测摄像头捕捉面部图像并分析人脸属性。服务器接收每次检测的人脸截图图像和概览快照。v2.0 NVR 格式包含人脸属性分析：年龄、性别、眼镜和口罩检测。 | 来源 | smartType | 数据 | |--------|-----------|------| | IPC v1.x | `VFD` | 人脸截图、概览 | | NVR v2.0 | `videoFaceDetect` | 人脸截图、概览、年龄、性别、眼镜、口罩 | **注意：** 人脸识别（与人脸数据库进行匹配）不会通过 NVR HTTP Post 转发。NVR 仅发送人脸检测事件。人脸匹配 (`VFD_MATCH`) 可能只能通过直接连接 IP 摄像头使用。 观看更多人脸检测/人脸识别摄像头视频：https://videos.cctvcamerapros.com/tag/face-recognition-camera ## 周界安防 — 入侵与越界检测 [](https://www.youtube.com/watch?v=dDDJtFURR_o) | 来源 | smartType | 描述 | |--------|-----------|-------------| | IPC v1.x | `PEA` | 周界入侵和越界（通过 XML 结构区分） | | NVR v2.0 | `regionIntrusion` | 人员或车辆进入定义的区域 | | NVR v2.0 | `lineCrossing` | 人员或车辆跨越绊线 | 区域进入和区域离开检测也可通过 IPC 直接连接支持。 | 来源 | smartType | 描述 | |--------|-----------|-------------| | IPC v1.x | `AOIENTRY` | 物体进入定义的区域 | | IPC v1.x | `AOILEAVE` | 物体离开定义的区域 | 在此处观看 Viewtron 人体检测 AI 视频：https://videos.cctvcamerapros.com/tag/human-detection-ai 在此处观看 Viewtron 车辆/汽车检测 AI 视频：https://videos.cctvcamerapros.com/tag/car-detection-ai ## 物体计数 [](https://www.youtube.com/watch?v=1jlT4Nw145Q) Viewtron AI 摄像头可以统计跨越线条或进入区域的人员和车辆数量。服务器接收概览快照和每个被计数物体的截图图像。线计数使用绊线；区域计数使用多边形 zone。 | 来源 | smartType | 描述 | |--------|-----------|-------------| | NVR v2.0 | `targetCountingByLine` | 统计跨越定义线条的物体 | | NVR v2.0 | `targetCountingByArea` | 统计定义区域内的物体 | ## 视频元数据 — 全帧物体检测 Viewtron AI 摄像头可以在整个摄像头画面中执行连续的物体检测和跟踪。与基于报警的检测类型不同，视频元数据持续检测和分类场景中的所有人员和车辆。服务器接收概览快照和每个检测到的目标截图图像。 | 来源 | smartType | 描述 | |--------|-----------|-------------| | IPC v1.x | `VSD` | 全画面物体检测和跟踪 | | NVR v2.0 | `videoMetadata` | 全画面物体检测和跟踪 | ## 实时目标跟踪 (traject) 每个 post 包含目标的 bounding box 坐标、目标类型（人/汽车/摩托车），以及一个对于同一目标在所有 post 中保持一致的唯一目标 ID。跟踪开始时立即进行 post，并在目标离开该区域的 1 秒内停止。 | 来源 | 数据类型 | 描述 | |--------|-----------|-------------| | 仅限 IP Camera | `traject` | 连续的 bounding box、目标 ID、目标类型、速度、方向 | **何时使用 traject：** - **继电器/自动化控制** — 基于持续的人员存在而不是单一的报警触发来激活灯光、门或警报。Traject 提供无间断的实时存在信号，不同于基于报警轮询的方式（在目标仍然存在时会有 5-20 秒的间隔）。 - **停留时间分析** — 以亚秒级精度精确测量人员或车辆在区域内停留的时间。 - **实时位置跟踪** — 使用 bounding box 坐标（归一化为 0-10000 范围）跟踪目标在画面中的移动。 - **自定义报警逻辑** — 根据目标的位置、停留时间或移动方式构建规则，而不仅仅是它是否触发了某个区域。 ## Home Assistant 集成 **[viewtron-home-assistant](https://github.com/mikehaldas/viewtron-home-assistant)** — 将摄像头事件作为原生 HA sensor 提供。车库/大门自动化、车牌识别警报、车道灯光等。 ## 工作原理 1. 配置你的 IP 摄像头或 NVR，以将 HTTP Post 发送到该服务器的 IP 和端口 2. 服务器接收 XML 报警数据并自动检测格式版本（v1.x 或 v2.0） 3. 解析事件，解码并保存图像，以及创建 CSV 日志条目 4. 所有原始 XML post 都会保存到 `raw_posts/` 目录，用于调试和分析 **输出：** - `events.csv` — 包含报警类型、时间戳、车牌号码（LPR）、图像路径的事件日志 - `images/` — 保存的 JPEG 快照（概览和目标截图） - `raw_posts/` — 用于调试的原始 XML post ## XML 示例 使用这些内容来了解 XML 结构、测试你的解析器，或者在不需要物理摄像头的情况下构建你自己的服务器。 ``` # 直接向服务器 POST 一个示例进行测试 curl -X POST http://localhost:5002/API \ -H "Content-Type: application/xml" \ -d @examples/nvr-v2/vehicle-lpr.xml ``` 请参阅 [`examples/README.md`](examples/README.md) 获取完整的索引、关键格式差异以及坐标系文档。 ## 设置 **IP Camera 直连：** 在摄像头的 Web 界面的 AlarmServer 设置中配置 HTTP Post endpoint。 设置指南：https://videos.cctvcamerapros.com/support/topic/ip-camera-api-webbooks **NVR：** 在 NVR 的 AlarmServer 设置中配置 HTTP Post endpoint。连接到 NVR 的 PoE 端口的所有摄像头将自动转发其 AI 事件。 设置指南：https://videos.cctvcamerapros.com/support/topic/setup-nvr-api-webhooks **服务器安装：** 请参阅 [INSTALL.md](INSTALL.md)。已在 Ubuntu Linux 和 Raspberry Pi 上测试。 ## 文档 | 资源 | 描述 | |----------|-------------| | [API 开发者门户](https://videos.cctvcamerapros.com/developer/) | 包含应用程序指南和 API 参考的完整文档 | | [Python SDK](https://videos.cctvcamerapros.com/developer/docs/getting-started/python-sdk/) | `pip install viewtron` — 事件解析和摄像头控制 | | [Home Assistant 集成](https://videos.cctvcamerapros.com/developer/docs/integrations/home-assistant/) | 通过 MQTT 将摄像头 AI 事件作为原生 HA sensor 提供 | | [LPR 应用指南](https://videos.cctvcamerapros.com/developer/docs/applications/license-plate-recognition-camera-api/) | 车牌识别 webhook 格式和代码示例 | | [XML 示例](examples/) | 包含格式文档的所有报警类型的 XML payload 示例 | | [IP 摄像头设置指南](https://videos.cctvcamerapros.com/support/topic/ip-camera-api-webbooks) | 配置 IP 摄像头 HTTP Post webhook | | [NVR 设置指南](https://videos.cctvcamerapros.com/support/topic/setup-nvr-api-webhooks) | 配置 NVR HTTP Post webhook | ## 产品 - **所有 Viewtron 产品：** https://www.Viewtron.com - **AI 安防摄像头：** https://www.cctvcamerapros.com/AI-security-cameras-s/1512.htm - **LPR 摄像头：** https://www.cctvcamerapros.com/License-Plate-Recognition-Systems-s/1518.htm - **人脸识别摄像头：** https://www.cctvcamerapros.com/face-recognition-cameras-s/1761.htm - **IP Camera NVR：** https://www.cctvcamerapros.com/IP-Camera-NVRs-s/1472.htm ## 作者 由 CCTV Camera Pros 联合创始人 Mike Haldas 编写。 mike@cctvcamerapros.net

标签：HTTP服务器, IP摄像头, Python, Webhook, 力导向图, 无后门, 智能家居, 物联网, 车牌识别, 逆向工具