From f67d43a43f6c3e58922e3c2f457dd9caafebfc67 Mon Sep 17 00:00:00 2001
From: shuishen <1109946754@qq.com>
Date: Fri, 14 Aug 2026 14:20:22 +0800
Subject: [PATCH] feat:具体能力实现处理

---
 capabilities/15-trajectory-analysis/README.md |  122 +++++++++++++++++++++++++++++++++++++++-
 1 files changed, 118 insertions(+), 4 deletions(-)

diff --git a/capabilities/15-trajectory-analysis/README.md b/capabilities/15-trajectory-analysis/README.md
index 708e568..a206d9a 100644
--- a/capabilities/15-trajectory-analysis/README.md
+++ b/capabilities/15-trajectory-analysis/README.md
@@ -1,6 +1,120 @@
-# Trajectory Analysis
+# 轨迹分析与行为识别
 
-- 输入：带时间戳的无人机、车辆、人员或船舶轨迹。
-- 输出：偏航、越界、聚集、停留和轨迹类别。
-- 首个 Demo：规则检测加轨迹聚类。
+状态：首个 CPU Demo 已验证（2026-08-14）。
 
+## 能力边界
+
+当前 Demo 归为 **C（产品业务能力）**，不是 `geoai-py` 内置功能：
+
+- 产品实现用 GeoPandas、Shapely、PyProj 和 scikit-learn 完成轨迹度量、空间关系计算、DBSCAN 分组和规则判断。仅使用这些生态库、但没有实际调用 `geoai-py`，不能标为 B。
+- `geoai-py` 的准确角色是上游来源之一：其目标检测和地理结果导出可为跟踪系统提供观测，但 `geoai-py 0.42.0` 没有轨迹、目标跟踪或行为识别 API。本 Demo 运行时因此不安装或调用 `geoai-py`。
+
+未来若把 `geoai-py` 检测/导出、独立多目标跟踪器和本规则服务连成完整流水线，流水线可同时包含 A、B、C；当前已实现并验证的部分仍是 C。
+
+首版所称“行为识别”是可解释的时空规则，不是视频动作识别模型，也不负责把逐帧检测框关联成轨迹 ID。
+
+## Demo 契约
+
+输入是一个 `*.case.json` 清单，引用三类真实业务可导出的文件：
+
+1. 轨迹点 CSV：固定字段 `track_id,entity_type,timestamp,longitude,latitude`。
+2. 参考路线 GeoJSON：每条 `LineString` 带 `track_id`。
+3. 区域 GeoJSON：每个面带 `zone_id` 和 `zone_type`；首版识别 `restricted`。
+
+首版只接受带有效 CRS 的 WGS84 经纬度（`EPSG:4326`）。每条轨迹至少需要两个不同时间戳；同一轨迹的重复时间戳保留最后一条并在元数据中计数。
+
+仓库没有用户实测轨迹，因此 [generate_demo_inputs.py](./generate_demo_inputs.py) 会生成两组小型、可审计的合成代表样本：
+
+- `normal`：2 条连续移动且贴合参考路线的轨迹，预期无事件。
+- `difficult`：3 条乱序轨迹，含 1 条重复观测，以及可人工核对的停留、偏航、禁入区和双人聚集。
+
+生成数据位于 `shared/data/raw/15-trajectory-analysis/`，不会提交 Git。真实验证仍需用户提供同结构的脱敏轨迹。
+
+## 环境与运行
+
+```powershell
+# Python 3.12 隔离环境
+powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\setup.ps1 -Capability 15-trajectory-analysis
+
+$py = '.\.venvs\15-trajectory-analysis\Scripts\python.exe'
+
+# 第一次生成验收输入
+& $py .\capabilities\15-trajectory-analysis\generate_demo_inputs.py
+
+# 分析目录内的 normal.case.json 和 difficult.case.json
+& $py .\capabilities\15-trajectory-analysis\run_trajectory_analysis.py
+
+# 只分析一个用户清单；输出仍放在 <output>/<case_id>/
+& $py .\capabilities\15-trajectory-analysis\run_trajectory_analysis.py `
+  --input .\path\to\my.case.json `
+  --output .\shared\outputs\15-trajectory-analysis\my-run
+```
+
+脚本默认拒绝覆盖已有输入和结果。只有明确要替换此前运行时才传 `--overwrite`。
+
+## 规则与输出
+
+默认规则：
+
+| 事件 | 条件 |
+| --- | --- |
+| 停留 `stop` | 速度不高于 0.8 m/s，持续至少 60 秒 |
+| 偏航 `route_deviation` | 到参考路线距离大于 25 m，持续至少 20 秒 |
+| 禁入区 `restricted_zone` | 轨迹点落入 `restricted` 面 |
+| 聚集 `gathering` | 至少 2 条轨迹在 20 m 内，持续至少 30 秒 |
+
+清单可用 `thresholds` 对象覆盖上述阈值。相邻观测超过 60 秒时事件连续段会断开，避免把长时间数据缺失误算为持续行为。
+
+每个案例固定输出：
+
+| 文件 | 内容 |
+| --- | --- |
+| `trajectory_summary.csv` | 每条轨迹的时间、距离、速度、偏航比例、停留/禁入时长、聚类 ID 和行为标签 |
+| `events.json` | 固定事件字段、参与轨迹、起止时间、位置和规则细节 |
+| `trajectories.geojson` | WGS84 轨迹线及汇总属性 |
+| `events.geojson` | WGS84 事件点及事件属性 |
+| `analysis.png` | 轨迹、参考路线、区域和不同形状事件标记 |
+| `run_metadata.json` | Python/依赖版本、规则/模型、阈值、CPU、输入数、耗时、清洗数和限制 |
+
+DBSCAN 只对轨迹汇总特征做探索性分组；`cluster_id=-1` 表示没有足够相似轨迹形成簇，不代表异常已被确认。
+
+## 已测验收结果
+
+运行环境：Python 3.12.10、CPU；`pip check` 通过。目录级运行处理 2 个案例、5 条轨迹和 78 条去重后观测，总耗时约 2.8 秒。
+
+| 验收项 | 预期 | 实测 |
+| --- | --- | --- |
+| 正常样本 | 2 条轨迹，0 个事件 | 通过：2 条轨迹，0 个事件 |
+| 困难样本清洗 | 乱序可排序，删除 1 条重复时间观测 | 通过：删除 1 条 |
+| 困难样本行为 | 四类事件各至少 1 个 | 通过：停留、偏航、禁入区、聚集各 1 个 |
+| 失败处理 | 缺少必填 CSV 字段时退出码为 2，并指出字段 | 通过 |
+| 输出完整性 | 每个案例生成 6 个非空文件 | 通过 |
+| 视觉检查 | 正常/困难 PNG 非空，轨迹、区域和事件可区分 | 通过；两张图均为 1400 x 980 |
+
+自动验收：
+
+```powershell
+$py = '.\.venvs\15-trajectory-analysis\Scripts\python.exe'
+& $py -m unittest discover -s .\capabilities\15-trajectory-analysis\tests -v
+```
+
+## 许可证
+
+| 项目 | 当前记录 |
+| --- | --- |
+| `geoai-py 0.42.0` | MIT；仅为可选上游，本 Demo 环境未安装 |
+| pandas / GeoPandas / Shapely / scikit-learn | BSD 3-Clause 系列许可证 |
+| PyProj | MIT；同时需遵守其随附 PROJ 数据/组件许可 |
+| Matplotlib | Matplotlib License；随附字体等资产有各自许可证 |
+| Demo 数据 | 由本仓库脚本生成，无第三方数据集或模型权重 |
+| 预训练模型/权重 | 无 |
+
+以上是开发阶段记录，不等于已完成产品商用法务审查。
+
+## 已知限制与下一步
+
+- 合成样本只能验证程序逻辑，不能证明真实场景准确率；目前没有可报告的真实误报率和漏报率。
+- 聚集要求时间戳对齐，GPS 漂移、采样频率和轨迹断点会直接影响结果。
+- 偏航依赖可信参考路线；禁入区依赖有效区域数据；不同人员、车辆、船舶和无人机需要分别标定阈值。
+- 下一步应先选 1 个正常、1 个困难的脱敏实测轨迹，人工标注事件，再评估误报、漏报和阈值，而不是直接跑大目录。
+- 若输入来自无人机视频，还需在此能力之前引入独立的多目标跟踪器，并验证 ID 切换问题。

--
Gitblit v1.9.3