Tariqbaloch786/visionflow

# VisionFlow 一个十字路口的交通摄像头每天能捕捉到成千上万辆汽车。这些录像大多只是静静地躺在硬盘里。VisionFlow 将它们转化为你可以真正加以利用的数据：有多少车驶过、车速有多快、在哪里发生了拥堵。 它可以在任何安装了 Python 并拥有视频文件（或网络摄像头，或 RTSP 流）的地方运行。只需输入一条命令，就能输出带有标注的视频和记录每条轨迹的 CSV 文件。  *真实输出：在一段公开高速公路视频上使用 YOLOv8n + IoU tracker，峰值时同时追踪 8 个 ID，随着车辆驶过，线计数器不断更新。* ## 它的功能 通过一个配置文件将以下四项功能整合在一起： 1. **检测** — YOLOv8 负责挑出每一帧中的目标。 2. **追踪** — 一个基于 IoU 的小型追踪器为每个目标分配一个稳定的 ID，让你可以跨帧追踪它。 3. **分析** — 计数器监控你在图像上绘制的线条，单应性变换将像素转换为米从而得出 km/h 单位的速度，同时热力图会随时间积累动态信息。 4. **输出** — 带标注的视频、CSV 日志、可选的实时预览，以及用于生成图表的 Streamlit 仪表板。 其核心在于，分析模块与数据源是解耦的。同一套代码既能分析高速公路上的汽车，也能分析 Target 超市里的顾客，或是仓库里的叉车——只需更改 YOLO 权重和线条坐标即可。 ## 快速一览 带有稳定 ID 和计数线的追踪画面——这是南亚混合街道交通场景，包括自动人力车 (`Three-wheeler`)、卡车、轿车、两轮车和行人，均被单独分类：  显示整段视频中动态积累情况的热力图叠加。这些轨迹描绘了每一个被追踪的车辆和行人实际驶过或走过的路径：  实时 pipeline 输出的简短循环演示：  ## 快速上手 ``` git clone https://github.com/Tariqbaloch786/visionflow cd visionflow pip install -e ".[app,dev]" # （可选，推荐）fetch South Asian traffic detector 的权重 python scripts/download_models.py # 生成 starter config 并运行它 visionflow init-config my.yaml visionflow run --config my.yaml --source path/to/video.mp4 ``` 就这么简单。默认情况下，你会得到 `outputs/run.mp4`（带标注的视频）和 `outputs/tracks.csv`（每帧中的每条轨迹占一行）。 ### 针对南亚交通的检测（自动人力车等） 基于 COCO 数据集训练的 `yolov8n.pt` 并没有三轮车类别，因此自动人力车会根据角度被错误地分类为 `truck`、`car` 或 `motorcycle`。为了解决这个问题，示例配置使用了 **IISc 的 UVH-26**（YOLOv11-S，在印度交通数据上进行了 fine-tuning，包含 Three-wheeler 在内的 14 个类别）作为主要检测器，并运行原生的 `yolov8n.pt` 作为辅助检测器，仅用于识别 `person` 类别——这样你就能在同一条 pipeline 中获得准确的车辆类别*和*行人信息。 运行一次 `python scripts/download_models.py`，即可将 UVH-26 权重下载到 `models/uvh26.pt`。如果你想退回到仅使用 COCO，请删除配置中的 `secondary_detector:` 块，并将 `detector.weights` 指向 `yolov8n.pt`。 如果你更愿意使用 Docker： ``` docker build -t visionflow . docker run --rm -v $(pwd)/examples:/app/examples visionflow run -c examples/sample_config.yaml --no-show ``` ## 架构剖析 ``` ┌──────────────┐ video stream ─▶│ Detector │── boxes ─┐ │ (YOLOv8) │ │ └──────────────┘ ▼ ┌──────────────┐ │ Tracker │── tracks ─┐ │ (greedy IoU) │ │ └──────────────┘ ▼ ┌──────────────┐ │ Analytics │ │ - lines │ │ - speed │ │ - heatmap │ └──────────────┘ │ ▼ annotated video + CSV + dashboard ``` 每个阶段都是一个拥有简洁接口的类。想把 IoU tracker 换成 ByteTrack？替换一个文件即可。想添加新的分析模块？放入文件并在 pipeline 中调用它的 `update(tracks)` 即可。这些组件之间互不耦合。 ## 一段话讲透速度估算 你点击四个图像点，圈定一块已知面积的道路区域——比如一段 3.5 m × 12 m 的车道。VisionFlow 会计算出一个单应性矩阵，将像素映射到地面平面的米制坐标，将每条轨迹的质心投影到该平面上，并用世界空间的距离除以流逝的时间。一个短小的环形缓冲区用于平滑检测器的抖动。这是标准的单摄像头方法，对于交通研究来说效果足够好；其准确性取决于你校准的象限内道路实际的平整程度，以及你点击角点时的仔细程度。 ## 配置说明 所有设置都集中在一个 YAML 文件中。默认值非常合理；你真正必须设置的只有 `source` 和 `lines` 字段。 ``` source: "0" # webcam id, file path, or rtsp:// url detector: weights: yolov8n.pt conf: 0.30 classes: [2, 5, 7] # COCO ids: car, bus, truck tracker: iou_threshold: 0.30 max_age: 30 min_hits: 3 lines: - name: north start: [0, 400] end: [1280, 400] speed: enabled: true image_quad: - [560, 360] - [720, 360] - [900, 600] - [380, 600] world_size_m: [3.5, 12.0] fps: 30.0 heatmap: enabled: true decay: 0.92 output: video: outputs/run.mp4 csv: outputs/tracks.csv show: true ``` 运行 `visionflow init-config my.yaml`，你将获得一个预填好的入门文件，可以直接进行编辑。 ## 实际应用场景 同一套 pipeline，不同的业务领域——只需更改权重和区域设置： - **交通工程** — 按方向统计车流量、校园周边的超速研究、用于交通信号配时决策的拥堵热力图。 - **零售** — 入口客流量统计、用于比较店铺布局的停留时间热力图、排队长度预警。 - **仓库与堆场** — 叉车超速合规性检查（OSHA 规定上限为 8 mph）、月台吞吐量、人车冲突区域监控。 - **建筑工地** — PPE 及人员编制核查、设备利用率、周边访问控制。 - **野生动物与农业** — 鱼道计数、牲畜穿越监控、拖拉机在田间作业的覆盖范围。 - **体育** — 从转播或固定摄像机视角进行球员追踪和位置热力图分析。 面试推介只需一句话：*一套分析核心，无限业务可能——那些枯燥的部分（强类型配置、可插拔流程、测试、CI、Docker）正是保证其可移植性的关键*。 ## 运行仪表板 ``` streamlit run src/visionflow/app.py ``` 选择一个配置，点击 Run，看着画面流转进来。随着视频的播放，计数数据会实时更新。 ## 开发指南 ``` make dev # editable install with extras make test # 17 unit tests, runs in under a second make lint # ruff make type # mypy make docker # container build ``` CI 会在每次提交代码时，针对 Python 3.10、3.11 和 3.12 版本运行 lint、类型检查、测试套件以及 Docker 构建。 ## 局限性 我宁愿坦诚面对边缘情况，也不愿过度推销： - IoU tracker 没有外观模型。如果两辆车完全相互遮挡，ID 可能会互换。这对于稀疏的高速公路场景尚可，但不适合拥挤的人行横道。如果你有此需求，请替换为 ByteTrack 或 DeepSORT。 - 速度估算假设标定的象限位于平坦的地平面上。斜坡和崎岖的路面会导致估算产生偏差。 - 在 CPU 上运行 YOLOv8n 以 640 px 分辨率处理时大约只有 5 到 10 FPS。若要实现 HD 级别的实时处理，你需要一块 GPU，或者导出至 ONNX/TensorRT（已列入路线图）。 - Streamlit 仪表板仅支持单用户，并不适用于生产环境部署。它的存在只是为了让你能快速演示 pipeline。 ## 路线图 - ByteTrack 和 OC-SORT 作为即插即用的替代方案 - 用于相机标定的交互式四点选取工具 - 分析输出中按类别细分的统计 - 用于边缘部署的 ONNX / TensorRT 导出 - WebRTC 流式输出 ## 许可证 MIT。详情请见 [LICENSE](LICENSE)。

标签：CNCF毕业项目, Kubernetes, Python, YOLOv8, 交通分析, 多目标跟踪, 无后门, 计算机视觉, 请求拦截, 逆向工具