# mt-vision

**Repository Path**: taj5/mt-vision

## Basic Information

- **Project Name**: mt-vision
- **Description**: 包含设备（摄像头）接入、调度与批处理、推理与状态机、输出层共四层视频AI处理模块 
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-13
- **Last Updated**: 2026-07-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MT-Vision 多场景视觉调度框架

MT-Vision 是一个面向工业现场视频流的视觉调度框架。它负责把多路 RTSP / 本地视频接入系统，按场景组调度最新帧，调用分类、检测、分割或 VLM 后端推理，再把结果交给业务 `processor` 做状态判断、事件记录、Web 展示或 PLC 输出。

装车给料状态识别只是当前内置场景之一，不是框架边界。项目的核心目标是让不同视觉场景共享同一套采集、调度、推理、状态输出和运行监控能力。

## 核心能力

- 多路 RTSP / 本地视频接入，基于 FFmpeg 解码最新帧。
- 按 `scene_groups` 配置把摄像头划分到不同业务场景。
- 每个场景组可独立配置 backend、FPS、模型路径和 processor。
- 支持分类、检测、分割和 VLM 四类推理后端。
- 同一 backend 的不同场景可加载不同模型。
- 普通推理结果通过 processor 扩展业务逻辑。
- 内置摄像头 watchdog、事件缓冲、Web API、运行快照和 Modbus 输出能力。

## 系统定位

MT-Vision 不是单一算法脚本，也不是只服务装车场景的应用。它更接近一个运行时框架：

```text
视频源
  -> 设备接入层
  -> 最新帧缓存
  -> 场景组调度
  -> AI 后端推理
  -> 业务 processor
  -> Web / 事件 / PLC / 业务状态
```

框架负责稳定运行和调度，业务场景通过配置和 processor 接入。

## 架构概览

| 层级 | 主要职责 | 关键模块 |
| --- | --- | --- |
| 设备接入层 | 拉流、解码、维护最新帧、监控在线状态 | `device/` |
| 场景调度层 | 按场景组取帧、批处理、调用对应后端 | `scheduler/` |
| AI 推理层 | 分类、检测、分割、VLM 推理适配 | `ai/` |
| 业务处理层 | 状态机、几何计算、PLC 写入、快照输出 | `processor/` |
| 运行服务层 | 配置加载、应用装配、Web API、事件 | `app.py`、`web/`、`runtime/` |

### 数据流

```text
RTSP / 视频文件
      │
      ▼
FFmpegReader
      │
      ▼
Camera 最新帧缓存
      │
      ▼
SceneScheduler
      │
      ├── VideoScheduler(scene=feeding_line_a, backend=classification)
      │       └── ClassificationService -> feeding processor -> Modbus
      │
      ├── VideoScheduler(scene=scraper_a, backend=segment)
      │       └── YOLOSegmentationService -> scraper_skew processor -> Web 快照
      │
      └── VideoScheduler(scene=safety_vlm_a, backend=vlm)
              └── VLMService -> VLM 结果缓存 / Web 快照
```

## 场景组模型

显式配置 `[[scene_groups]]` 后，系统以场景组为调度单位。每个场景组包含：

- 一组摄像头。
- 一个 AI backend。
- 一个调度 FPS。
- 一个可选的场景专用模型路径。
- 一个 processor。

示例：

```toml
[[cameras]]
id = "cam01"
rtsp = "rtsp://user:password@192.168.1.10:554/Streaming/Channels/101"
register = 22160

[[cameras]]
id = "cam02"
source = "data/scraper.mp4"
register = 22161

[model]
classification_path = "models/feeding_cls.pt"
detection_path = "models/object_det.pt"
segmentation_path = "models/scraper_seg.pt"

[[scene_groups]]
id = "feeding_line_a"
backend = "classification"
fps = 2
cameras = ["cam01"]
model_path = "models/feeding_cls.pt"
processor = "feeding"

[[scene_groups]]
id = "scraper_a"
backend = "segment"
fps = 2
cameras = ["cam02"]
model_path = "models/scraper_seg.pt"
processor = "scraper_skew"
```

约束：

- 支持的 backend：`classification`、`detect`、`segment`、`vlm`。
- 每个摄像头必须且只能属于一个场景组。
- `processor` 未配置时，`classification` 默认使用 `feeding`，其他普通后端默认使用 `noop`。
- VLM 场景必须配置 `[vlm].enabled = true`。

## Processor 扩展点

`processor` 是业务场景的主要扩展点。它接收普通后端输出的 `InferenceResult`，然后执行场景自己的业务逻辑。

典型用途：

- 分类结果进入状态机，稳定后写 PLC。
- 检测框结果按位置、数量或类别转换为业务状态。
- 分割 mask 计算角度、面积、偏移量等几何指标。
- 将业务快照暴露给 Web API。
- 记录事件或告警。

内置 processor：

| 名称 | 适用场景 | 说明 |
| --- | --- | --- |
| `feeding` | 分类场景 | 内置装车/给料状态机，状态变化时写 Modbus。 |
| `noop` | 任意普通后端 | 不做业务后处理，只保留调度器最近推理结果。 |
| `scraper_skew` | 分割场景 | 基于 mask polygon 计算刮板偏斜角。 |

新增 processor 的详细步骤见 `docs/新增场景开发指南.md`。

## 运行方式

### 环境要求

- Python 3.12+
- uv
- FFmpeg 可执行文件
- 如需本地 YOLO 推理，需要匹配的 PyTorch / CUDA 环境
- 如需 PLC 输出，需要可访问的 Modbus TCP 设备

### 安装依赖

```bash
uv sync
```

### 使用默认配置运行

```bash
uv run mt-vision
```

### 使用外部 TOML 配置运行

```bash
uv run mt-vision --config config.local.toml
```

也可以按模块方式运行：

```bash
uv run python -m mt_vision --config config.local.toml
```

### 配置校验

```bash
uv run python -c "from mt_vision.config.settings import load_settings; load_settings('config.local.toml'); print('config ok')"
```

## Docker 运行

构建镜像：

```bash
docker build -t mt-vision .
```

运行：

```bash
docker run --rm \
  -v "$PWD/config.local.toml:/app/config.toml:ro" \
  -v "$PWD/logs:/app/logs" \
  -v "$PWD/models:/app/models:ro" \
  mt-vision
```

后台运行：

```bash
docker run -d \
  --name mt-vision \
  --restart always \
  -v "$PWD/config.local.toml:/app/config.toml:ro" \
  -v "$PWD/logs:/app/logs" \
  -v "$PWD/models:/app/models:ro" \
  mt-vision
```

容器默认读取 `/app/config.toml`，日志写入 `/app/logs/mt-vision.log`，同时输出到控制台。

## 项目结构

```text
src/mt_vision/
  ai/             # 分类、检测、分割、VLM 推理服务
  config/         # TOML 配置模型、默认配置、校验逻辑
  device/         # Camera、CameraManager、FFmpegReader、Watchdog
  modbus/         # Modbus TCP 输出封装
  processor/      # 业务后处理扩展点
  runtime/        # 运行事件等通用运行时能力
  scheduler/      # 场景调度、批处理、推理结果结构
  web/            # Web API / 运行快照服务
  app.py          # 应用装配入口
  cli.py          # 命令行入口
```

## 文档

- `docs/配置说明.md`：完整 TOML 配置字段说明。
- `docs/架构与调度说明.md`：当前架构、调度路径、边界和限制。
- `docs/新增场景开发指南.md`：如何新增场景、编写 processor、注册扩展。
- `docs/用户手册.md`：面向运行和使用的说明。

## 当前边界

- Backend 目前不是注册表扩展，新增 backend 需要改配置校验、应用装配和调度器分支。
- Processor 是注册表扩展，但需要在 `processor/__init__.py` 显式注册。
- VLM 当前走独立异步序列逻辑，不会调用普通 `processor.process()`。
- 每个摄像头只能属于一个场景组。
- 配置在启动时加载，当前没有热更新。

## 技术栈

- Python 3.12+
- FFmpeg
- FastAPI / Uvicorn
- Ultralytics YOLO
- PyTorch
- OpenAI-compatible VLM HTTP API
- Modbus TCP