# computer_visualization_practice

**Repository Path**: xenogene/computer_visualization_practice

## Basic Information

- **Project Name**: computer_visualization_practice
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-20
- **Last Updated**: 2026-04-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Realtime CV Scene Narrator

一个面向计算机视觉课程的完整项目：从摄像头实时读取画面，使用深度学习与传统视觉算法联合分析场景，输出目标检测结果、运行日志、目标统计与实时文字描述。

## 1. 项目目标

- 实时检测摄像头中的物体（目标框、类别、置信度）
- 实时给出中文场景文字描述
- 提供 Web 可视化界面
- 侧边显示完整运行日志与目标累计统计
- 保留可扩展的高级能力（跟踪、事件分析、语义描述）

## 2. 技术栈（尽量新）

- Python 3.12+
- Ultralytics YOLO（默认 `yolo11n.pt`）
- OpenCV（图像处理与传统CV算法）
- Gradio（Web 界面与实时流）
- Transformers（零样本语义识别，用于扩展可描述信息）
- MediaPipe（手部关键点与手势识别）
- Pydantic（配置管理）
- Ruff + Black + Mypy + pre-commit（统一代码风格）

## 3. 核心能力

### 3.1 深度学习视觉能力

- YOLO 实时目标检测
- 检测结果可视化（bbox、label、confidence）
- 开放词汇检测（YOLO-World）：支持自定义类别词表，突破固定类别限制
- 扩展词表：学习/办公/日常/交通等更多类别（如 calculator、glasses、clock、car、bus、bicycle 等）

### 3.2 传统CV算法能力（非纯调用大模型）

- 运动检测：基于前后帧差分 `absdiff + threshold`
- 边缘密度估计：`Canny` 统计边缘占比
- 亮度估计：灰度均值归一化

### 3.3 多目标跟踪（轻量）

- 基于质心距离的在线跟踪（Centroid Tracker）
- 为同类目标分配相对稳定的 `track_id`

### 3.4 场景描述生成

- 根据检测结果与CV特征生成中文场景描述（位置、主体、动态、光照）
- 避免简单“标签罗列”，转为更自然的画面叙述
- 融合零样本语义识别，补充检测类别之外的场景信息
- 支持 `balanced`（简洁）/ `detailed`（详细）/ `paragraph`（段落化）模式

### 3.5 速度与准确率平衡策略

- 默认使用 `yolo11s.pt` 提升识别准确率
- 隔帧检测（默认每2帧检测1次）降低推理负载
- 支持实时调参：
  - 检测置信度阈值（准确率/召回平衡）
  - 检测间隔帧数（实时性/精度平衡）

### 3.6 高级事件功能

- 目标出现/消失事件检测（基于跟踪ID）
- 运行日志包含事件记录，便于课程展示“系统感知过程”
- ROI 区域入侵/离开事件检测（可视化 ROI 框）
- 事件自动导出到 `artifacts/events/*.csv`

### 3.7 工程化可视化

- 实时原始/处理画面并排展示
- 轨迹热力图叠加（展示高频活动区域）
- 右侧文本面板展示：
  - 场景描述
  - 场景故事摘要（周期更新）
  - 活动强度评分
  - 最近自动抓拍路径
  - 检测来源分析（base/open-vocab 新增与重复抑制）
  - 运行日志（推理耗时、运动强度、目标标签）
  - 目标出现/消失事件
  - 目标累计统计表

### 3.8 趣味增强功能

- 自动抓拍：当活动强度超过阈值时自动保存关键帧
- 场景故事：按固定帧间隔汇总最近叙述，形成连续故事
- 轨迹热力图：根据目标中心历史轨迹累计并衰减显示

### 3.9 高级问题识别

- 画面质量问题：光照不足、过曝、模糊
- 目标关系问题：遮挡风险（高IoU重叠）、画面拥挤（目标面积占比过高）
- 深度风险问题：使用深度估计模型判断“近景压迫”风险
- 输出形式：问题诊断摘要 + 风险指数 + 干预建议

### 3.10 手势输入与手势计算器

- 基于 MediaPipe Hands 识别手型与手势 token
- 支持单手数字输入：`0-9`
- 支持运算符输入：`+ - * /`
- 支持手势清除：`clear`
- 支持手势确认计算：`confirm`
- 自动稳定帧确认与冷却去抖，减少误触
- 实时输出：手势提示、表达式、计算结果

## 4. 项目结构

```text
computer_visualization_practice/
├── pyproject.toml
├── README.md
├── .pre-commit-config.yaml
├── src/
│   └── vibe_cv/
│       ├── __init__.py
│       ├── __main__.py
│       ├── config.py
│       ├── cv_features.py
│       ├── main.py
│       ├── gestures.py
│       ├── narration.py
│       ├── pipeline.py
│       ├── tracking.py
│       ├── types.py
│       └── ui.py
└── tests/
    └── test_narration.py
```

## 5. 快速开始

### 5.1 安装依赖（推荐 uv）

```bash
uv venv
uv pip install -e .
```

若需要开发工具：

```bash
uv pip install -e .[dev]
```

### 5.2 启动项目

```bash
uv run python -m vibe_cv
```

默认会启动在：

- Server bind: `http://0.0.0.0:7860`
- Browser访问: `http://127.0.0.1:7860`

打开后允许浏览器使用摄像头即可。

### 5.3 Docker Desktop（mac ARM，前后端统一托管）

本项目是 `Gradio` 单体应用，前端页面和后端推理服务在同一个进程中运行；
使用 Docker 时可统一托管为一个容器服务。

首次构建并启动：

```bash
docker compose up -d --build
```

查看运行日志：

```bash
docker compose logs -f vibe-cv
```

访问地址：

- `http://127.0.0.1:7860`

停止服务：

```bash
docker compose down
```

说明：

- `docker-compose.yml` 已指定 `platform: linux/arm64/v8`，适配 Apple Silicon。
- 模型缓存目录会挂载到宿主机 `${HOME}/.cache`，避免每次重下模型。
- 运行产物挂载到 `./artifacts`，便于直接在本地查看导出文件。

## 6. 使用说明

- 左侧：实时摄像头输入与处理后画面
- 右侧：
  - `描述模式`：`balanced` / `detailed` / `paragraph`
  - `检测置信度阈值`：提高可减少误检
  - `检测间隔帧数`：提高可提升流畅度
  - `实时场景描述`
  - `场景故事摘要（周期更新）`
  - `活动强度评分`
  - `最近自动抓拍路径`
  - `检测来源分析`
  - `问题诊断摘要`
  - `问题风险与建议`
  - `手势输入提示`
  - `手势表达式`
  - `手势计算结果`
  - `目标累计统计`
  - `运行日志`
  - `重置统计与日志`

## 7. 关键实现说明

### 7.1 推理流程

1. 从 WebCam 获取 RGB 帧
2. 转 BGR 后输入 YOLO 推理
3. 解析检测框并构建目标对象
4. 使用开放词汇模型补充自定义类别检测结果
5. 使用质心跟踪分配 `track_id`
6. 进行帧差、边缘、亮度分析
7. 检测目标出现/消失与 ROI 入侵事件并写入日志/CSV
8. 生成中文叙述文本
9. 绘制检测叠加层并更新日志/统计

### 7.3 扩展类别配置

在 `src/vibe_cv/config.py` 中可修改：

- `open_vocab_classes`：自定义可检测词表
- `open_vocab_enabled`：是否启用开放词汇检测
- `roi_*_ratio`：ROI 区域坐标比例
- `event_export_dir`：事件CSV导出目录
- `heatmap_*`：轨迹热力图显示参数
- `story_interval_frames`：故事摘要更新间隔
- `snapshot_*`：自动抓拍阈值和保存目录
- `issue_*`：问题识别阈值（模糊、遮挡、拥挤）
- `depth_*`：深度风险分析参数与模型
- `hand_*`：手势识别稳定帧、冷却帧、检测置信度等参数

### 7.4 新技术栈（Vision Foundation Model）

- 新增深度估计技术栈：`transformers depth-estimation`
- 默认模型：`Intel/dpt-hybrid-midas`
- 用途：实时估计前景深度分布，识别近景压迫风险
- 异常容错：模型加载失败时自动降级，不影响主检测链路

### 7.2 为什么这是“真实CV项目”

- 使用了主流深度学习检测模型（YOLO）
- 同时实现了经典计算机视觉算法（帧差法、Canny、灰度统计）
- 有明确的视频流处理、推理、跟踪、可视化与日志链路
- 并非仅调用 LLM 文本生成

## 8. 常见问题排查

- 摄像头打不开：检查浏览器权限、系统相机权限、是否被其他程序占用
- 首次运行模型下载较慢：网络正常时等待自动下载
- 帧率偏低：降低分辨率、关闭其他占用 GPU/CPU 程序
- M1/M2 Mac 若出现兼容问题：升级 `opencv-python` 与 `ultralytics` 到最新稳定版本

## 9. 课程展示建议

答辩时建议重点演示：

1. 同时检测多个物体并生成自然语言描述
2. 快速晃动摄像头时，日志中运动指标变化明显
3. 目标统计持续累积，重置按钮可清空
4. `balanced` 与 `detailed` 模式输出差异

## 10. 后续可选增强

- 替换为 ByteTrack/DeepSORT 提升跟踪稳健性
- 加入 ROI 越线/入侵事件检测
- 输出结构化事件日志（JSON/CSV）
- 接入 TTS 将文本描述实时播报
- 接入多模态模型做高层行为理解

## 11. 代码风格与质量

- 统一风格：Ruff + Black + Mypy
- 类型注解：核心模块全量类型标注
- 模块职责清晰：配置、CV特征、跟踪、叙述、管线、UI 分离