# myCVStation

**Repository Path**: futurelei/my-cvstation

## Basic Information

- **Project Name**: myCVStation
- **Description**: 个人opencv5、MediaPipe、yolo等视觉算法模型工作台
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-15
- **Last Updated**: 2026-08-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CVStation · OpenCV 5 视觉算法工作站

基于 **OpenCV 5 + Go** 的视觉算法验证工作站:上传图片/视频或接入摄像头,
多算法并行处理,结果以可视化卡片 + 结构化指标呈现。

- 视觉后端:Go 语言,自研紧凑 CGO 绑定层(`internal/cvx`)直连 **OpenCV 5.0**(5.x 分支,含 contrib)
- 算法:目标追踪(MIL)、光流(Farneback)、线特征(EDLine/FLD)、角点(ORB)、
  人体检测(YOLOv8n)、人脸检测(YuNet)、姿态估计(OpenPose DNN)、
  **MediaPipe**(人脸网格/手势/姿态/整体/人像分割,Python 侧车)
- 前端:白色极简风格单页,无构建步骤;拖拽上传、Ctrl+V 粘贴、浏览器摄像头实时流
- 全流程国内镜像:apt(USTC/TUNA)、pip(TUNA)、Go(goproxy.cn)、OpenCV 源码(gitee)
- 部署:一键环境脚本、Docker、systemd、Linux/Windows 多架构构建工具

```mermaid
flowchart LR
    A[浏览器] -->|上传/粘贴/摄像头帧| B[Go HTTP + WebSocket]
    B --> C[internal/cvx · OpenCV 5]
    C --> D[算法处理器]
    D --> E[data/results 标注图/视频 + 指标 JSON]
    D -->|JPEG 帧| F[MediaPipe Python 侧车]
    F -->|标注图 + 指标| B
    B -->|卡片/实时流| A
```

## 目录结构

```
├── cmd/server/            # 服务入口(前端已嵌入二进制,单文件部署)
├── internal/
│   ├── cvx/               # CGO 绑定层: cvx.go + cvx.h + cvx.cpp(OpenCV 5)
│   ├── vision/            # 算法注册表 + 处理器(追踪/光流/线特征/ORB/人体/人脸/姿态/mediapipe)
│   ├── httpapi/           # REST API + WebSocket 实时流 + MJPEG 摄像头
│   ├── store/             # data/ 目录规范与文件管理
│   ├── webui/             # 前端源码(embed 进二进制)
│   └── config/            # 命令行/环境变量配置
├── vision_sidecar/        # MediaPipe Python 侧车(FastAPI,锁定 mediapipe 0.10.x)
├── scripts/               # 环境/模型/运行/构建工具
├── deploy/                # Docker、compose、systemd、交叉编译容器
└── data/                  # 上传与识别结果(见 data/README.md)
```

## 快速开始

```bash
# 1. 初始化环境(国内镜像,自动编译 OpenCV 5 到 /opt/opencv5,约 10-30 分钟)
./scripts/setup_env.sh
source /etc/profile.d/cvstation.sh

# 2. 下载算法模型(YuNet/SSD/OpenPose,带镜像回退)
./scripts/fetch_models.sh

# 3. 启动(mediapipe 侧车 + 工作站)
./scripts/run.sh

# 浏览器打开 http://127.0.0.1:8090
```

> 只跑 OpenCV 算法、不需要 MediaPipe 时:`./scripts/run.sh --no-sidecar`

## 界面与用法

上下布局,白色极简风格(无 emoji):

1. **算法选择**(上):按「OpenCV 5」/「MediaPipe」分组多选,勾选后可展开调参
   (ORB 角点数、FLD 最短线段、追踪初始区域、检测置信度等)。
2. **输入**(上):三个标签页
   - 图片/视频:拖拽到虚线区或 **Ctrl+V 粘贴**(图片),文件进入 `data/uploads/`,
     文件清单可多选、单条「处理」或删除;
   - 摄像头:浏览器 `getUserMedia` 采集,帧直传服务器,算法结果实时回流。
3. **结果**(下):每个任务一张卡片 —— 缩略图、状态/进度、每个算法的标注结果
   (图片可查看/下载,视频可在线播放)与指标(数量、均值、置信度、fps 等)。

实时摄像头会做背压(丢帧保最新),最多同时运行 `--realtime-max`(默认 6)个算法。

## HTTP API

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/api/health` | 服务/OpenCV/侧车状态 |
| GET | `/api/algorithms` | 算法注册表(含参数定义) |
| GET | `/api/files?kind=images\|videos` | 文件清单 |
| POST | `/api/upload?kind=images\|videos&name=x.jpg` | 上传(裸字节或 multipart) |
| DELETE | `/api/files?kind=…&name=…` | 删除上传 |
| GET | `/api/files/<data相对路径>` | 读取 data 下任意文件(越界拦截) |
| POST | `/api/jobs` | 创建任务 `{source:{rel,name}, algos:[…], params:{…}}` |
| GET | `/api/jobs` / `/api/jobs/{id}` | 任务列表/详情 |
| DELETE | `/api/jobs/{id}` | 删除任务 |
| GET | `/api/camera/mjpeg?device=0` | 服务端摄像头 MJPEG 流 |
| GET | `/api/camera/snapshot?device=0` | 单帧快照 |
| WS | `/api/ws` | 实时流:文本控制 + 二进制帧(协议见 internal/httpapi/ws.go) |

## 算法与 OpenCV 5 说明

- OpenCV 5.0 已移除 Haar `CascadeClassifier` 与 `HOGDescriptor`,本项目改用官方替代:
  人脸 → **YuNet DNN**(ONNX);人体 → **MobileNet-SSD**。
- 目标追踪:5.0 将追踪器移入主仓库 `video` 模块,保留 TrackerMIL(免模型)
  并新增 DaSiamRPN/Nano/ViT(DNN)。本工作站默认 MIL,无需下载模型。
- 线特征:经典 EDLine 未并入 OpenCV,官方合并实现为 `ximgproc::FastLineDetector`
  (同作者 EDLines 算法),卡片名标注「EDLine/FLD」。
- 姿态估计:MobileNet OpenPose(COCO 18 关节点,Caffe)。
- MediaPipe:独立 Python 侧车(锁定 0.10.21 legacy API),Go 通过 HTTP 调用,
  侧车返回标注图与指标。

模型缺失时对应算法会在任务卡片中给出明确错误提示(运行 `scripts/fetch_models.sh`)。

## 部署与多架构构建

```bash
# 原生构建(当前平台)
./scripts/build.sh native

# Linux 交叉编译: docker buildx 在目标架构容器内编译 OpenCV 5 + Go
./scripts/build.sh linux-arm64          # qemu 模拟,耗时较长
./scripts/build.sh linux-all            # amd64 + arm64
./scripts/build.sh dist                 # 查看 dist/ 产物

# Windows(需要 Windows 机器 + OpenCV 5):
#   powershell -File scripts/build-windows.ps1 -Arch amd64|arm64
```

`dist/<os>-<arch>/` 内含二进制(前端已嵌入)、mediapipe 侧车、运行脚本。
CGO + OpenCV 无法纯交叉编译:Linux 目标用容器内原生编译,Windows 目标原生构建
(脚本见 `scripts/build-windows.ps1`,详情见 `scripts/build.sh` 头部注释)。

Docker 部署:

```bash
./scripts/build.sh native
docker compose -f deploy/docker-compose.yml up -d --build
```

systemd 部署:复制 `deploy/systemd/cvstation.service` 到 `/etc/systemd/system/`,
按注释配置路径后 `systemctl enable --now cvstation`。

## 配置(命令行 / 环境变量)

| 参数 | 环境变量 | 默认 | 说明 |
|---|---|---|---|
| `--addr` | `CV_ADDR` | `:8090` | 监听地址 |
| `--data` | `CV_DATA` | `data` | 数据目录 |
| `--sidecar` | `CV_SIDECAR` | `http://127.0.0.1:8765` | MediaPipe 侧车地址(空=禁用) |
| `--camera` | `CV_CAMERA` | `0` | 默认摄像头索引 |
| `--max-upload-mb` | `CV_MAX_UPLOAD_MB` | `512` | 单文件上传上限 |
| `--max-video-sec` | `CV_MAX_VIDEO_SEC` | `120` | 视频处理时长上限(0=全片) |
| `--workers` | `CV_WORKERS` | `2` | 并行任务数 |
| `--realtime-max` | `CV_REALTIME_MAX` | `6` | 实时流算法上限 |

## 常见问题

- **编译报 pkg-config 找不到 opencv4**:执行 `source /etc/profile.d/cvstation.sh`,
  或 `export PKG_CONFIG_PATH=/opt/opencv5/lib/pkgconfig`。
- **运行报 libopencv_core.so.500 找不到**:`ldconfig` 已由 setup_env.sh 配置;
  手动环境执行 `export LD_LIBRARY_PATH=/opt/opencv5/lib:$LD_LIBRARY_PATH`。
- **模型下载失败**:`scripts/fetch_models.sh` 内置多镜像回退;若全部失败,
  按脚本末尾提示手动下载放入 `data/models/dnn/`。
- **MediaPipe 算法不可用**:侧车未启动,`./scripts/run.sh` 会一并启动;
  独立调试:`vision_sidecar/.venv/bin/python vision_sidecar/main.py`。

## License

MIT,见 [LICENSE](LICENSE)。OpenCV/MediaPipe 遵循其各自许可。