nvragnstdecember/TrafficPulse
GitHub: nvragnstdecember/TrafficPulse
TrafficPulse 是一个离线优先的交通违章推理研究项目，通过严格区分感知与违章推理、积累时序证据来确认违章行为，目前处于早期基础架构阶段。
Stars: 0 | Forks: 0
# TrafficPulse
**面向固定摄像头路侧视频的，证据优先、离线优先的交通违章推理。**
TrafficPulse 是一个面向研究的工程项目，它将交通违章视为一种*需要随着时间推移进行推理并有证据支持*的事物——
而绝不仅仅是单一的模型输出或单帧检测结果。其核心设计理念是严格区分**感知**（模型在单帧中看到的内容）和**违章推理**（根据轨迹积累的类型化观测，结合场景几何和明确的规则，仅在获得时序证据后予以确认，且可由人工审查）。本仓库是该系统的**基础层**：包含固定的数据契约、治理规范以及首批独立于检测器的推理组件——它并非一个已完成的检测器流水线。
## 项目状态
**早期阶段。基础架构 + 首批独立于检测器的推理切片已完成。** 目前尚未实现行为级的端到端违章系统。具体而言：
- **阶段 0-F（基础）：已完成** —— 类型化的领域契约、导出的 JSON schema、标签本体、数据集登记表 + 策略、场景配置 schema 以及架构/ADR 文档包均已就位并完成测试。
- **阶段 1（行为级，独立于检测器的切片）：进行中** —— 几何基元、合成轨迹生成器、通用规则引擎核心、逆行时序推理以及 PTS 精确的视频导入已经落地并完成单元测试。
- **尚未开始：** 检测器/追踪器集成以及任何基于真实视频的端到端路径（参见[路线图](#planned-capabilities--roadmap)）。
质量门禁均为通过状态：在当前代码树上运行了 `ruff`、`mypy --strict` 以及 **485 个通过的测试**，并配备了单环境 Linux CI 和原生 Windows 验证清单。
## TrafficPulse 致力于解决的问题
朴素的“AI 交通执法”往往将一次检测器的触发等同于应受处罚的违章行为。这在技术上是站不住脚的，也是不公平的。TrafficPulse 是一个学术毕业设计项目，其优化目标是**技术可防御性、可复现性、诚实评估，以及清晰区分已实现与计划中的能力**（参见 [`TRAFFICPULSE_MASTER_SPEC.md`](TRAFFICPULSE_MASTER_SPEC.md)）。
预期的长期范围是锁定六种违章类型 —— 未戴头盔、 triple riding 、闯红灯、逆行、违章停车以及（受可行性限制的）超速。其中，目前仅存在**逆行**的推理路径，并且仅针对*合成*轨迹。
## 架构概述
其持久的设计理念是类型化的、单向的数据流，其中**规则仅消费类型化观测**，这使得推理层可以在没有 GPU 或模型的情况下，根据日志进行确定性的重放（`docs/architecture-review.md` §14–§15）。
```
flowchart LR
V[Video ingestion
PTS-accurate] --> D[Detection] D --> T[Tracking] T --> A[Association] A --> O[Observations
typed per-frame facts] O --> R[Rule engine
FSM + accumulation] R --> E[Confirmed event] E --> EV[Evidence package] EV --> RC[Human review case] RC --> P[Simulated penalty] classDef done fill:#1f7a4d,stroke:#0d3,color:#fff; classDef todo fill:#555,stroke:#999,color:#fff,stroke-dasharray:4 3; class V,O,R,E done; class D,T,A,EV,RC,P todo; ``` *绿色 = 已实现（契约 + 独立于检测器的逻辑）。灰色/虚线 = 已定义契约，行为已计划。* 视频导入、观测契约、规则引擎和确认事件的生成目前已经存在；检测、追踪、关联、证据渲染、审查和惩罚模拟属于等待实现的契约。 项目文档支持的设计姿态： - **离线优先** —— 输入录制好的视频，输出事件；“实时”这一表述仅限于带有标签的近实时演示模式（ADR-003，`docs/architecture-review.md` §22）。 - **面向证据** —— 每一个被确认的事件都旨在能通过存储的证据和规则上下文进行解释（`docs/architecture-review.md` §19）。 - **确定性契约 + 显式的不确定性/弃权** —— 每一次未确认都是一条已记录、可统计的弃权行为；置信度是一个组件细分，在未进行过验证的情况下，绝不作为已校准的概率呈现（`docs/architecture-review.md` §13）。 ## 当前已实现的能力 以下所有内容均已在仓库中实现**并**被测试覆盖： | 能力 | 位置 | 备注 | |---|---|---| | 冻结的类型化领域契约 | `src/trafficpulse/contracts/` | 用于 Detection、TrackState、Association、所有 Observation 变体、ViolationHypothesis、ConfirmedEvent、EvidenceManifest、ReviewCase、SimulatedPenalty、共享 enums/primitives 的 pydantic 模型；已完成往返 + 验证测试 | | 确定性 JSON schema 导出 | `schemas/*.schema.json` | 契约的字节稳定导出 | | 标签本体 | `configs/ontology.yaml`, `docs/ontology.md` | 检测类别；头盔 4 标签方案 `{helmet, no_helmet, turban, uncertain}` 包含规则层映射（`turban → exempt`，`uncertain → abstain`）；已通过 schema 验证 | | 数据集登记表 + 策略 | `registry/`, `docs/dataset-policy.md`, `docs/evaluation-protocol.md` | 仅包含治理/元数据，每个条目都有明确的访问/许可证状态；**不下载任何数据集** | | 场景配置 + 稳定哈希 | `configs/scenes/`, `src/trafficpulse/contracts/scene.py` | 类型化的 `SceneConfig` + 确定性的 `scene_config_hash` (SHA-256) | | 几何基元 | `src/trafficpulse/geometry/` | 向量、线段、多边形 (P1-U1) | | 合成轨迹生成器 | `src/trafficpulse/synth/` | 带有已知事件标签的黄金轨迹 —— 无需模型，无需视频 (P1-U2) | | 通用规则引擎核心 | `src/trafficpulse/rules/engine.py`, `states.py` | 与违章无关的假设生命周期 FSM + 累积 + 弃权 (P1-U3) | | 逆行推理 | `src/trafficpulse/rules/wrong_way.py`, `observations/heading.py` | 持续矛盾 → `ConfirmedEvent`，仅在合成轨迹上进行过验证 (P1-U4) | | PTS 精确视频导入 | `src/trafficpulse/ingestion/video.py` | PyAV 后端；仅基于 PTS 的媒体相对时间戳（无虚构的 FPS 回退）；确定性帧标识 (P1-U5) | ## 计划实现的能力 / 路线图 由契约或设计定义，**尚未实现**： - **检测器集成** —— 仅限宽容性姿态，以 RT-DETR 为主要方向，位于 U2 `Detection` 契约之后 (ADR-001)。集成的限制门槛已解除，但目前尚无任何检测器代码。 - **追踪器集成** —— 位于追踪契约之后的 ByteTrack / OC-SORT。 - **真实视频端到端** —— 针对真实视频片段的逆行切片（目前仅限合成）；尚未处理任何真实录像。 - **剩余的五种违章** —— 未戴头盔（包含强制性的 CNN 与 ViT 实验）、 triple riding 、闯红灯、违章停车以及受可行性限制的超速。 - **ANPR、证据引擎 runtime 、观测写入器 (Parquet)、事件存储、隐私/脱敏、人工审查 UI、模拟惩罚工作流、分析 / 评估代码。** 不包含任何模型权重、数据集或训练流水线。 ## 仓库结构 ``` TrafficPulse/ ├── LICENSE # Apache-2.0 (project source code) ├── README.md ├── SECURITY.md ├── pyproject.toml # packaging, ruff/mypy/pytest config ├── TRAFFICPULSE_MASTER_SPEC.md # product/research specification ├── .github/workflows/ci.yml # single-env Linux quality gate ├── configs/ │ ├── ontology.yaml │ └── scenes/ # scene schema + synthetic example ├── registry/ # dataset registry schema + candidate entries │ ├── schema.yaml │ └── datasets/*.yaml ├── schemas/ # exported JSON schemas ├── docs/ │ ├── architecture-review.md # canonical architecture reference │ ├── architecture.md · phase-0-plan.md │ ├── ontology.md · dataset-policy.md · evaluation-protocol.md │ ├── scene-configuration.md · windows-verification.md │ └── adr/ADR-001..004.md ├── src/trafficpulse/ │ ├── contracts/ · geometry/ · synth/ │ ├── rules/ · observations/ · ingestion/ └── tests/ # contracts, geometry, synth, rules, # observations, ingestion, ontology, # registry, scenes, docs ``` 仅当单元需要时才会引入相应的包 —— 不存在投机性的脚手架代码。 ## 快速开始 要求 **Python ≥ 3.11**。 ``` # 1. 创建并激活虚拟环境 python -m venv .venv source .venv/bin/activate # Windows PowerShell: .\.venv\Scripts\Activate.ps1 # 2. 安装 package（可编辑模式）以及开发工具 python -m pip install --upgrade pip python -m pip install -e ".[dev]" # 3. 运行 quality gates ruff check . mypy src pytest -q # 4. 导入 / 版本 smoke check python -c "import trafficpulse; print(trafficpulse.__version__)" ``` 原生 Windows 验证步骤记录在 [`docs/windows-verification.md`](docs/windows-verification.md) 中。 ## 逆行垂直切片演示（离线） 一条离线、确定性的命令即可端到端运行第一个垂直切片 —— 一个录制好的视频片段 + 一个 `SceneConfig` → PTS 精确帧 → 真实的 RT-DETR 检测 → IoU 追踪 → 逆行推理 → 一个带有最小化 `EvidenceManifest` 的持久化 `ConfirmedEvent`。它需要可选的检测器扩展以及一个本地可用的 checkpoint （默认不下载任何内容）： ``` python -m pip install -e ".[dev,rtdetr]" # optional torch/transformers extra python -m trafficpulse.pipeline \ --clip path/to/clip.mp4 \ --scene configs/scenes/example-scene.yaml \ --output-dir runs --run-id demo-1 \ --checkpoint --device cpu \
--direction-id dir-north
```
它是**完全离线的**（传入 `--allow-download` 仅是为了让 `transformers` 获取 checkpoint），如果缺少视频片段 / 无效场景 / 缺少 checkpoint，它会快速失败并返回类型化消息，并且仅将内容写入 `--output-dir/` 下（已被 gitignored）。该运行会打印一份 JSON 报告（帧/轨迹/事件计数、检测器/追踪器引用、场景哈希），并且**不会**从单个视频片段中得出任何准确率声明。
COCO RT-DETR 不会在合成像素上触发车辆类别，因此真正的逆行事件需要一个**批准的真实视频片段**；整个路径（真实导入、真实追踪器、真实规则、真实持久化）在 `tests/pipeline/` 中的生成片段上通过注入检测进行了确定性验证，并且真实的 RT-DETR 推理通过选择启用的 `tests/pipeline/test_slice_e2e_rtdetr.py` 进行了端到端验证（将 `TRAFFICPULSE_E2E_MODEL` 设置为本地缓存的 checkpoint；默认情况下跳过）。
## 质量门禁 / 测试
- **Lint/格式化:** `ruff check .`
- **类型:** `mypy src` (严格模式)。
- **测试:** `pytest -q` (目前有 485 个通过的测试)。
- **CI:** [`.github/workflows/ci.yml`](.github/workflows/ci.yml) 在 Linux 上对每次推送到 `main` 的操作和每个 pull request 运行相同的三项检查。
每个源代码包都至少被一个测试所覆盖；ADR/架构不变量本身由 `tests/docs/test_adr_pack.py` 检查。
## 数据集与模型策略
- 本仓库**不下载或内置任何数据集**。 `registry/` 仅保存*治理元数据* —— 来源、访问状态、许可证状态、任务匹配度、划分/泄漏元数据 —— 以便在任何获取行为**之前**可以审查决策（`docs/dataset-policy.md`，`docs/evaluation-protocol.md`）。
- **不包含任何模型权重**。检测器/追踪器/OCR 的选择遵循仅宽容性姿态 (ADR-001)；权重和预训练数据条款会在任何使用或分发**之前，按 artifact** 进行审查。
- 防止泄漏（基于组的划分、全站点留出、仅针对验证集的阈值调优）在任何训练发生前已被冻结为策略。
## 许可证区分
TrafficPulse 特意保持了四个许可证问题的**独立性** —— 本项目的许可证并不扩展到以下任何一项：
| 范围 | 管辖方 |
|---|---|
| **TrafficPulse 源代码** | **Apache-2.0**（本仓库 —— 参见 [`LICENSE`](LICENSE)） |
| 检测器 / 框架组件 | 独立决定；遵循 **ADR-001** 下的仅宽容性姿态（尚未集成） |
| 数据集 | 独立决定，受 `registry/` 元数据 + `docs/dataset-policy.md` 以及每个数据集自身的条款约束 |
| 模型权重 / artifacts | 独立决定，受其各自的上游条款约束（按 artifact 审查） |
对本仓库采用 Apache-2.0 **并不意味着**重新授权数据集、模型权重或第三方代码，并且 ADR-001 依然专门针对检测器技术栈的许可证姿态 —— 而非项目本身的许可证。
## 研究与部署限制
- **这不是一个生产级执法系统。** 它是一个研究/学术毕业设计的基础。
- **被确认的事件并不等同于法律上的违规定性。** 在任何*模拟*的惩罚之前，人工审查是必须的设计步骤，并且所有的惩罚 artifacts 仅供模拟使用。
- **没有经过验证的真实世界准确率。** 尚未集成任何检测器或追踪器，未处理任何真实录像，且未声明任何准确率、吞吐量或事件级别的精确率/召回率指标。真实世界的准确率需要基于数据集的评估，而目前尚未开展此类评估。
- **逆行推理仅在合成轨迹上进行了验证。**
- 部署假设保持在当前项目范围内；特别是超速行驶受制于可行性，并且在经过校准的场景评估证明其合理性之前，排除在任何惩罚模拟之外（`docs/evaluation-protocol.md` §11）。
## 文档
- [`TRAFFICPULSE_MASTER_SPEC.md`](TRAFFICPULSE_MASTER_SPEC.md) — 产品/研究规范
- [`docs/architecture-review.md`](docs/architecture-review.md) — **权威的**架构与可行性参考
- [`docs/architecture.md`](docs/architecture.md) — 入门指南 + ADR 索引
- [`docs/phase-0-plan.md`](docs/phase-0-plan.md) — 阶段 0-F 基础计划
- [`docs/phase-1-plan.md`](docs/phase-1-plan.md) — 权威的阶段 1 单元计划（已完成 P1-U1…P1-U7；从 P1-U8 开始的前向关键路径）
- [`docs/ontology.md`](docs/ontology.md) · [`docs/dataset-policy.md`](docs/dataset-policy.md) · [`docs/evaluation-protocol.md`](docs/evaluation-protocol.md) · [`docs/scene-configuration.md`](
PTS-accurate] --> D[Detection] D --> T[Tracking] T --> A[Association] A --> O[Observations
typed per-frame facts] O --> R[Rule engine
FSM + accumulation] R --> E[Confirmed event] E --> EV[Evidence package] EV --> RC[Human review case] RC --> P[Simulated penalty] classDef done fill:#1f7a4d,stroke:#0d3,color:#fff; classDef todo fill:#555,stroke:#999,color:#fff,stroke-dasharray:4 3; class V,O,R,E done; class D,T,A,EV,RC,P todo; ``` *绿色 = 已实现（契约 + 独立于检测器的逻辑）。灰色/虚线 = 已定义契约，行为已计划。* 视频导入、观测契约、规则引擎和确认事件的生成目前已经存在；检测、追踪、关联、证据渲染、审查和惩罚模拟属于等待实现的契约。 项目文档支持的设计姿态： - **离线优先** —— 输入录制好的视频，输出事件；“实时”这一表述仅限于带有标签的近实时演示模式（ADR-003，`docs/architecture-review.md` §22）。 - **面向证据** —— 每一个被确认的事件都旨在能通过存储的证据和规则上下文进行解释（`docs/architecture-review.md` §19）。 - **确定性契约 + 显式的不确定性/弃权** —— 每一次未确认都是一条已记录、可统计的弃权行为；置信度是一个组件细分，在未进行过验证的情况下，绝不作为已校准的概率呈现（`docs/architecture-review.md` §13）。 ## 当前已实现的能力 以下所有内容均已在仓库中实现**并**被测试覆盖： | 能力 | 位置 | 备注 | |---|---|---| | 冻结的类型化领域契约 | `src/trafficpulse/contracts/` | 用于 Detection、TrackState、Association、所有 Observation 变体、ViolationHypothesis、ConfirmedEvent、EvidenceManifest、ReviewCase、SimulatedPenalty、共享 enums/primitives 的 pydantic 模型；已完成往返 + 验证测试 | | 确定性 JSON schema 导出 | `schemas/*.schema.json` | 契约的字节稳定导出 | | 标签本体 | `configs/ontology.yaml`, `docs/ontology.md` | 检测类别；头盔 4 标签方案 `{helmet, no_helmet, turban, uncertain}` 包含规则层映射（`turban → exempt`，`uncertain → abstain`）；已通过 schema 验证 | | 数据集登记表 + 策略 | `registry/`, `docs/dataset-policy.md`, `docs/evaluation-protocol.md` | 仅包含治理/元数据，每个条目都有明确的访问/许可证状态；**不下载任何数据集** | | 场景配置 + 稳定哈希 | `configs/scenes/`, `src/trafficpulse/contracts/scene.py` | 类型化的 `SceneConfig` + 确定性的 `scene_config_hash` (SHA-256) | | 几何基元 | `src/trafficpulse/geometry/` | 向量、线段、多边形 (P1-U1) | | 合成轨迹生成器 | `src/trafficpulse/synth/` | 带有已知事件标签的黄金轨迹 —— 无需模型，无需视频 (P1-U2) | | 通用规则引擎核心 | `src/trafficpulse/rules/engine.py`, `states.py` | 与违章无关的假设生命周期 FSM + 累积 + 弃权 (P1-U3) | | 逆行推理 | `src/trafficpulse/rules/wrong_way.py`, `observations/heading.py` | 持续矛盾 → `ConfirmedEvent`，仅在合成轨迹上进行过验证 (P1-U4) | | PTS 精确视频导入 | `src/trafficpulse/ingestion/video.py` | PyAV 后端；仅基于 PTS 的媒体相对时间戳（无虚构的 FPS 回退）；确定性帧标识 (P1-U5) | ## 计划实现的能力 / 路线图 由契约或设计定义，**尚未实现**： - **检测器集成** —— 仅限宽容性姿态，以 RT-DETR 为主要方向，位于 U2 `Detection` 契约之后 (ADR-001)。集成的限制门槛已解除，但目前尚无任何检测器代码。 - **追踪器集成** —— 位于追踪契约之后的 ByteTrack / OC-SORT。 - **真实视频端到端** —— 针对真实视频片段的逆行切片（目前仅限合成）；尚未处理任何真实录像。 - **剩余的五种违章** —— 未戴头盔（包含强制性的 CNN 与 ViT 实验）、 triple riding 、闯红灯、违章停车以及受可行性限制的超速。 - **ANPR、证据引擎 runtime 、观测写入器 (Parquet)、事件存储、隐私/脱敏、人工审查 UI、模拟惩罚工作流、分析 / 评估代码。** 不包含任何模型权重、数据集或训练流水线。 ## 仓库结构 ``` TrafficPulse/ ├── LICENSE # Apache-2.0 (project source code) ├── README.md ├── SECURITY.md ├── pyproject.toml # packaging, ruff/mypy/pytest config ├── TRAFFICPULSE_MASTER_SPEC.md # product/research specification ├── .github/workflows/ci.yml # single-env Linux quality gate ├── configs/ │ ├── ontology.yaml │ └── scenes/ # scene schema + synthetic example ├── registry/ # dataset registry schema + candidate entries │ ├── schema.yaml │ └── datasets/*.yaml ├── schemas/ # exported JSON schemas ├── docs/ │ ├── architecture-review.md # canonical architecture reference │ ├── architecture.md · phase-0-plan.md │ ├── ontology.md · dataset-policy.md · evaluation-protocol.md │ ├── scene-configuration.md · windows-verification.md │ └── adr/ADR-001..004.md ├── src/trafficpulse/ │ ├── contracts/ · geometry/ · synth/ │ ├── rules/ · observations/ · ingestion/ └── tests/ # contracts, geometry, synth, rules, # observations, ingestion, ontology, # registry, scenes, docs ``` 仅当单元需要时才会引入相应的包 —— 不存在投机性的脚手架代码。 ## 快速开始 要求 **Python ≥ 3.11**。 ``` # 1. 创建并激活虚拟环境 python -m venv .venv source .venv/bin/activate # Windows PowerShell: .\.venv\Scripts\Activate.ps1 # 2. 安装 package（可编辑模式）以及开发工具 python -m pip install --upgrade pip python -m pip install -e ".[dev]" # 3. 运行 quality gates ruff check . mypy src pytest -q # 4. 导入 / 版本 smoke check python -c "import trafficpulse; print(trafficpulse.__version__)" ``` 原生 Windows 验证步骤记录在 [`docs/windows-verification.md`](docs/windows-verification.md) 中。 ## 逆行垂直切片演示（离线） 一条离线、确定性的命令即可端到端运行第一个垂直切片 —— 一个录制好的视频片段 + 一个 `SceneConfig` → PTS 精确帧 → 真实的 RT-DETR 检测 → IoU 追踪 → 逆行推理 → 一个带有最小化 `EvidenceManifest` 的持久化 `ConfirmedEvent`。它需要可选的检测器扩展以及一个本地可用的 checkpoint （默认不下载任何内容）： ``` python -m pip install -e ".[dev,rtdetr]" # optional torch/transformers extra python -m trafficpulse.pipeline \ --clip path/to/clip.mp4 \ --scene configs/scenes/example-scene.yaml \ --output-dir runs --run-id demo-1 \ --checkpoint
标签：云计算, 交通违章检测, 人工智能, 安全规则引擎, 智能交通, 用户模式Hook绕过, 规则引擎, 视频分析, 计算机视觉, 逆向工具