ConveyorArmVision

基于 YOLOv8-seg 实例分割 + DeepSORT 多目标追踪的工业传送带视觉分拣系统。

项目结构

ConveyorArmVision/
├── main.py                     # 主入口：视频追踪推理
├── seg_model.py                # SegModel 类：YOLO 分割模型封装
├── tracker.py                  # DeepSORTTracker 类：DeepSORT 追踪器封装
│
├── config/
│   ├── config.py               # 集中配置（所有路径和参数）
│   ├── class_name.yaml         # 类别名称映射
│   └── __init__.py
│
├── log/
│   ├── logger.py               # 统一日志模块 setup_logger()
│   └── __init__.py
│
├── utils/
│   ├── serve/
│   │   ├── serve.py            # FastAPI 推理服务入口
│   │   ├── client.py           # API 客户端（视频流请求）
│   │   └── __init__.py
│   ├── train/                  # 训练脚本
│   ├── seg/                    # 分割模型静态推理
│   ├── detect/                 # 传统视觉方案（已弃用）
│   ├── make_txt/               # 标注格式转换
│   └── __init__.py
│
├── ultralytics/                # YOLO 官方工具包
├── deep_sort_pytorch/          # DeepSORT 追踪器
├── weights/                    # 模型权重
├── data/                       # 输入视频
├── output/                     # 输出视频
└── requirements.txt

代码设计规范

配置集中 + 顶层注入

所有路径和参数集中在 config/config.py，入口文件加载后以 dict 传入子模块。子模块不直接 import config。

# main.py — 顶层组装 config，注入子模块
seg_config = {
    "model_path": model_path,
    "class_names": class_names,
    "conf_threshold": CONF_THRESHOLD,
}
seg_model = SegModel(seg_config, logger)

子模块通过 config dict 接收，赋值给 self._config，内部使用 self._config["key"]。

命令行参数覆盖

所有 argparse 参数默认值为 None，使用 args.xxx or CONFIG_VALUE 兜底：

parser.add_argument('--yolo_weights', type=str, default=None)
args = parser.parse_args()
model_path = args.yolo_weights or YOLO_WEIGHTS  # 命令行优先，其次 config

日志统一

全项目共用 log/logger.py 的 setup_logger(name)，仅输出控制台，文件归档由 nohup 处理：

from log.logger import setup_logger
logger = setup_logger("main")
logger.info("加载模型: %s", model_path)

异常分层

子层抛异常（附加上下文），顶层统一记录完整堆栈：

# 子层 — 只抛不记
def match_contours(self, ...):
    try:
        ...
    except Exception as e:
        raise Exception("轮廓匹配失败") from e

# 顶层 — 唯一记录
if __name__ == "__main__":
    try:
        ...
    except Exception as e:
        logger.exception("流程失败: %s", e)
        sys.exit(1)

无路径污染

• 禁止 sys.path.append() / sys.path.insert()
• 所有脚本从项目根目录以 python -m 启动，保证 sys.path[0] 始终是根目录
• 标准 import 即可找到所有模块

运行方式

所有命令从项目根目录执行。

视频追踪

# 使用默认配置
python main.py

# 自定义参数
python main.py --yolo_weights weights/best.pt --video_path data/conveyor.mp4 --output_dir output

API 推理服务

python -m utils.serve.serve

启动后访问 http://127.0.0.1:8000，接口：

方法	路径	说明
GET	/	服务信息
GET	/health	健康检查
POST	/track	单帧追踪（返回检测结果）
POST	/track_multiple	单帧追踪（返回带标注的图像）

API 客户端（视频流请求）

python -m utils.serve.client --video_path data/conveyor.mp4 --route /track

配置项说明

配置项	默认值	说明
YOLO_WEIGHTS	weights/best.onnx	模型权重路径
CLASS_NAME_YAML	config/class_name.yaml	类别名称映射文件
CONF_THRESHOLD	0.5	检测置信度阈值
DEEP_SORT_CONFIG	deep_sort_pytorch/configs/deep_sort.yaml	DeepSORT 配置文件
VIDEO_PATH	data/conveyor.mp4	输入视频路径
OUTPUT_DIR	output	输出目录
API_HOST	0.0.0.0	API 服务监听地址
API_PORT	8000	API 服务端口
API_URL	http://127.0.0.1:8000	客户端默认请求地址
API_ROUTE	/track	客户端默认路由
API_TIMEOUT	30	客户端请求超时（秒）

修改 config/config.py 即可全局生效，也可通过命令行参数临时覆盖。