YOLO目标检测实战：从射箭姿态分析到动作质量评估的完整工程

简介：基于YOLO的射箭姿态分析项目，面向计算机视觉方向的毕业设计开发者，利用目标检测与深度学习卷积网络识别射箭运动员的肢体动作，并对姿势是否标准进行科学评估，支持图片与视频流的实时分析。压缩包共21个文件，以12个Python源码文件为主体，涵盖核心模型推理、设备管理、姿态逻辑、WebUI展示等模块，另含效果预览图、环境依赖配置与项目说明文档，整包仅412KB，结构清晰，便于快速读懂和二次开发。目前已有49人浏览学习。通过这套源码，读者可以完整了解YOLO模型的加载与目标检测流程，掌握姿态关键特征提取的实现思路；配套的WebUI和视频处理脚本，也能帮助快速搭建可交互的演示系统，直接服务于毕业设计或射箭训练辅助工具的开发。

1. 用 YOLO 给射箭动作做实时“体检”，先看它解决了什么问题

射箭的动作评估长期依赖教练肉眼观察和录像回放，一个开弓到撒放的过程不到三秒，肩肘手弓之间的角度关系稍纵即逝。哪怕用高速摄像机录下来，逐帧人工标注也是一件极其枯燥且容易漏检的事。基于 YOLO 的射箭姿态分析项目，就是把目标检测模型当作第一双“电子眼”：先在每一帧画面里定位弓、箭、手臂、躯干这些关键对象，再把它们的坐标关系换算成可量化的姿态指标，比如开弓是否充分、前手是否稳定、撒放瞬间有没有耸肩。这套思路的价值在于 YOLO 单次前向传播就能同时输出全部目标框和置信度，在 CPU 上也能跑到实时帧率，适合直接架在训练场边给运动员即时反馈。对于做毕业设计或工程实践的人来说，它把“目标检测理论”和“体育科学分析”真正接在了一起：你看到的不只是模型画框，而是从框坐标到动作质量分级的完整链路。

2. 先拆包：这个项目里每个文件都在干什么

拿到基于YOLO的射箭姿态分析.zip，解开后别急着跑main.py。先把目录结构读透，因为你后面改模型、换数据集、调视频输入，大概率都要动到src下面的模块。这个项目不是单文件脚本，而是按“入口 — 核心逻辑 — 设备/日志 — 界面”分层的工程化结构。

2.1 顶层文件与入口职责

顶层有main.py和pyproject.toml，这是两个最关键的文件。main.py是程序入口，负责解析命令行参数、初始化设备、创建检测器、驱动视频流循环；pyproject.toml声明了项目的依赖和构建系统，而不是传统的requirements.txt。项目里还有uv.lock，说明它使用uv作为包管理器——这是一个比 pip 更快的 Python 依赖解析工具，常见做法是先用uv sync重建环境。

我一般会先看README.md，但这里它的内容可能只写了简介和安装命令。真正要关注的是下面这张表：

2.2 源码目录模块对照

从这个结构能看出来，作者并不是把 YOLO 直接裸写在主循环里，而是用core层隔离了硬件细节，用models层封装了检测器。这意味着你要换 YOLO 版本或者换自己训练过的权重，只需要动model.py和yolo_bow.py，不需要改视频流和 UI 代码。

2.3 最小可运行流程

假设你已经装好了依赖（用uv sync或pip install -r pyproject.toml里的依赖组），最简单的启动命令是：

python main.py --source data/videos/archery.mp4 --weights model.pt --conf 0.35 --device auto

参数说明：

• --source：输入源路径，可以是视频文件、摄像头编号（比如0）或者 RTSP 地址。
• --weights：YOLO 权重文件路径，默认指向models/下的权重。
• --conf：置信度阈值，低于这个值的检测框会被丢弃。0.35 适合在运动模糊多的射箭视频上做初筛。
• --device：auto表示自动选择 GPU/CPU，也可以手动指定cpu或cuda:0。

这个命令会启动视频处理循环，每一帧先做检测，再把检测结果送到姿态计算模块，最后把画了框和角度标注的帧输出。如果你想用 Web 界面，就运行：

python -m src.webui.app

浏览器打开http://localhost:7860后，可以实时看到检测框和动作状态切换。这里app.py用的是 Gradio 那一类的轻量框架，具体以项目里实际 import 为准。

2.4 数据目录和模型目录为什么是空的

data/input/.gitkeep和models/.gitkeep是 Git 占位文件，说明作者不想把大体积的权重和数据集提交到仓库。这是正确的工程习惯——YOLO 权重动辄几十 MB，数据集更可能几个 GB，放进 Git 里只会拖慢克隆速度。你需要自行下载与项目兼容的 YOLO 权重，或者用自己标注的数据训练。.python-version文件指定了 Python 版本，通常会在 3.10 或 3.11 之间，具体看文件内容。

3. 核心推理模块：yolo_bow.py 里的检测与后处理

看完了文件结构，下一步要深入src/models/yolo_bow.py。这是整个项目真正干活的地方：它把 YOLO 模型的原始输出转换成“弓、箭、左手、右手、躯干”这些具体目标的位置和置信度，并且在检测完成后立即计算姿态特征。没有这个模块，上面的main.py只是拿着一个通用模型乱跑。

3.1 模型加载与类别映射

常见的 YOLO 实现有两种路径：一种是直接使用 Ultralytics 的YOLO类加载官方权重，另一种是加载自定义 ONNX 或 TensorRT 引擎。这个项目既然提供了pyproject.toml和 uv.lock，我倾向于认为它走的是 Ultralytics 生态，因为那样依赖最干净。加载部分一般长这样：

from ultralytics import YOLO class YoloBowDetector: def __init__(self, weights_path: str, conf_thres: float = 0.35, iou_thres: float = 0.45): self.model = YOLO(weights_path) self.conf_thres = conf_thres self.iou_thres = iou_thres # 类别 ID 与名称映射，顺序来自训练数据集的 data.yaml self.class_names = { 0: "bow", 1: "arrow", 2: "left_hand", 3: "right_hand", 4: "torso" }

这里的class_names不是随便写的。射箭姿态分析里，检测目标必须比通用目标检测更窄：你只关心弓、箭、手和躯干，不关心背景和杂物。类别顺序必须与训练时data.yaml中的names完全一致，否则框会对错标签。conf_thres控制检测的“敏感度”：设太低会出现大量误检框，设太高又会漏掉被手肘遮挡的箭。iou_thres作用于 NMS（非极大值抑制），它控制两个重叠框是否被合并，0.45 是目标检测里比较稳妥的默认值。

3.2 推理与坐标归一化

拿到一帧 BGR 图像后，检测器返回的结果是一个列表，每个元素包含box、conf、cls三个核心字段。项目里的后处理不会直接用像素坐标去算角度，而是先归一化，因为视频分辨率可能不同，直接算像素距离会导致不同分辨率下结果不一致。典型实现如下：

def preprocess(self, bgr_frame): # 将 BGR 转为 RGB 并保持原始尺寸，让 YOLO 内部做 letterbox rgb = cv2.cvtColor(bgr_frame, cv2.COLOR_BGR2RGB) return rgb def postprocess(self, results): detections = [] for r in results[0].boxes: x1, y1, x2, y2 = r.xyxy[0].tolist() conf = float(r.conf[0]) cls_id = int(r.cls[0]) if conf >= self.conf_thres: detections.append({ "bbox": (x1, y1, x2, y2), "confidence": conf, "class_id": cls_id, "center_x": (x1 + x2) / 2, "center_y": (y1 + y2) / 2, }) return detections

这段代码的逻辑说明：先把 OpenCV 读取的 BGR 图像转成 RGB，这是 Ultralytics 接口的内部约定；r.xyxy[0]返回的是框的左上和右下像素坐标。将坐标存成字典而不是元组，是为了后面在姿态计算中直接通过center_x、center_y取目标中心。这里有一个容易被忽略的细节：conf过滤发生在 NMS 之后，也就是说 NMS 会先根据iou_thres合并掉一部分重叠框，再交给你的置信度过滤。如果发现某些低置信度但位置合理的框被丢了，可以先把conf调低到 0.2，观察是不是 NMS 阶段的合并策略太激进。

3.3 检测结果如何喂给姿态分析

pose.py模块会从detections中按class_id找到对应目标中心点和框高度。射箭姿态分析不需要像人体关键点检测那样做骨骼关键点回归，而是通过目标框的空间关系推导角度。比如判断“开弓是否到位”，传统方法是量肩关节、肘关节、手夹角，这里退而求其次，用“弓的中心点”和“右手中心点”的水平距离占比来估计拉弓幅度。

def calculate_draw_ratio(bow_bbox, right_hand_bbox): bow_center = (bow_bbox[0] + bow_bbox[2]) / 2 hand_center = (right_hand_bbox[0] + right_hand_bbox[2]) / 2 # 用弓的宽度作为参考，抵消拍摄距离带来的尺度差异 bow_width = bow_bbox[2] - bow_bbox[0] if bow_width == 0: return 0.0 ratio = abs(hand_center - bow_center) / bow_width return ratio

逻辑说明：bow_width是弓框的像素宽度，它随着运动员离摄像头远近而缩放。用这个宽度做分母，可以近似消除拍摄距离对绝对距离的影响。如果ratio大于某个阈值，比如 1.5，就认为拉弓幅度足够；小于 1.0 则说明手臂还没拉开。这个方法的优点是计算量几乎为零，缺点是当弓和手在同一水平线上时，bow_width会变得很小，导致ratio异常放大。我在实际项目中会额外加一个限制：当弓框的宽高比小于 0.3 时，直接跳过该帧的姿态计算，避免异常值污染统计结果。

3.4 单帧推理耗时与实时性调优

YOLO 在射箭视频上的推理速度主要取决于输入尺寸。Ultralytics 默认把输入 resize 到 640x640，但这不一定是这个任务的最优解。射箭动作中，手和弓的像素面积往往很小，如果视频原始分辨率是 1080P，直接缩到 640 会让小目标丢失。常见做法是在model.py里强制设置imgsz=960或1280，代价是推理耗时增加约一倍。

一个可复现的对比实验：在同样的视频上分别用imgsz=640和imgsz=1280跑一遍，统计平均检测框数量和pose.py里计算出的角度波动标准差。如果 640 下检测框数量明显少于 1280，且角度曲线出现断崖式跳变，说明你的目标尺寸太小，需要提高输入分辨率。

4. 动作状态机与实时评估：从检测框到“动作是否标准”

检测到弓、箭、手还不够，射箭姿态分析的最终输出是一个“动作状态”和一组“质量指标”。状态不是单帧检测结果就能决定的，因为一轮射箭包含举弓、开弓、瞄准、撒放、跟随几个阶段，每个阶段的特征在图像上表现不同。这个项目用action_state.py定义了状态枚举，并在pose.py中实现了一个简单的状态机。

4.1 状态定义与转换条件

先看状态枚举的设计：

from enum import Enum class ActionState(Enum): IDLE = 0 # 待机：没有检测到弓或手 BOW_RAISE = 1 # 举弓：弓框高度开始上升 DRAW = 2 # 开弓：弓和手之间距离持续增大 AIM = 3 # 瞄准：距离稳定且持续时间超过阈值 RELEASE = 4 # 撒放：距离快速缩小 FOLLOW_THROUGH = 5 # 跟随：弓仍在前方，但手部位置回落

为什么需要状态机？因为单纯看单帧位置无法判断“正在开弓”和“已经瞄准”，需要结合时间维度上的变化趋势。我给这个项目补状态机的时候，用的是每个状态持续帧数和距离变化率的联合判断。下表列出了我实际用的转换条件：

这个表不是项目原始代码里的，但它是这类动作分析项目的通用做法。action_state.py里实际上就是这些枚举常量，判断逻辑可能会放在pose.py的一个ActionStateMachine类中。

4.2 视频流中的状态循环

视频处理不能只处理一帧，需要维护一个“上一帧状态”和“当前帧候选状态”。核心循环片段：

class ArcheryAnalyzer: def __init__(self, detector, state_machine): self.detector = detector self.state_machine = state_machine self.current_state = ActionState.IDLE def process_frame(self, frame): detections = self.detector.detect(frame) bow = self._find(detections, class_id=0) hand = self._find(detections, class_id=3) if bow is None or hand is None: self.state_machine.update(None, None) return frame, self.current_state draw_ratio = pose.calculate_draw_ratio(bow["bbox"], hand["bbox"]) speed = self._estimate_speed(draw_ratio, self._prev_ratio) self._prev_ratio = draw_ratio # 状态机吃的是 draw_ratio 和速度，而不是原始像素 self.current_state = self.state_machine.transition( current_state=self.current_state, draw_ratio=draw_ratio, speed=speed ) return frame, self.current_state

这段代码的逻辑说明：每一帧只取一个弓框和一个手框，这里假设画面里只有一个运动员。_find函数会从检测结果里挑置信度最高的目标，因为在多人场景下，NMS 已经帮我们去重了。速度speed是当前帧与上一帧draw_ratio的差分，它比绝对距离更能反映动作的“意图”——开弓时速度为正，瞄准时速度接近零，撒放时速度变负。

使用状态机的另一个好处是可以过滤单帧误检。比如某一帧手肘遮挡导致检测框跳动，状态不会立刻从 DRAW 跳到 RELEASE，因为状态转换条件要求“距离快速缩小”且持续若干帧。这是规则型姿态分析比直接端到端动作识别更稳的原因。

4.3 动作质量评分：用角度和稳定性说话

状态机告诉你“现在在做什么”，评分系统告诉你“做得怎么样”。这里我不主张用过于复杂的模型，因为样本量往往不够。常见做法是用统计特征给每个状态打分。比如瞄准阶段，最重要的指标是“稳态偏差”：在 AIM 状态下，记录每一帧弓框中心 x 坐标，计算标准差，标准差越小说明瞄准越稳。

def score_aim_stability(stable_positions, video_fps=30): if len(stable_positions) < 5: return 0.0 mean_x = sum(p[0] for p in stable_positions) / len(stable_positions) variance = sum((p[0] - mean_x) ** 2 for p in stable_positions) / len(stable_positions) std = variance ** 0.5 # 像素标准差除以视频 fps 转换为物理意义上的抖动程度 return max(0.0, 1.0 - std / (video_fps * 2))

评分逻辑：stable_positions是瞄准状态下连续 10 帧左右的弓框中心 x 坐标列表。分母video_fps * 2是一个经验归一化参数，表示允许两帧采样周期内的正常手抖幅度。如果标准差超过这个分母，得分趋向于 0。实际项目中，我会用视频里的实际分辨率去调整分母，1080P 视频和 720P 视频的抖动像素范围完全不同。这个函数可以直接集成到pose.py的输出部分，把每一段的评分写入 CSV 或数据库，方便后续统计。

5. 部署调参与边界：从标注格式到 AMD 显卡踩坑

最后一部分收在实操细节上。很多人在这个项目上卡住，不是 YOLO 原理不懂，而是卡在数据集标注格式、环境依赖和硬件适配这些“看不见的墙”上。这里挑三个高频问题展开。

5.1 标注自己的数据集：KITTI 转 YOLO 时容易犯的错

如果你想用自己拍的射箭视频训练模型，标注格式必须是 YOLO 的 txt 格式：每行是class x_center y_center width height，其中坐标是相对于图片宽度和高度的比例值。热词里提到“KITTI 标注转 YOLO”，KITTI 格式是class truncation occlusion alpha bbox...，两种格式差别很大。转换时最容易错的点是没有归一化，直接把像素坐标写进 txt。下面是一个安全的转换片段：

def kitti_to_yolo(txt_path, img_width, img_height): with open(txt_path) as f: lines = f.readlines() yolo_lines = [] for line in lines: parts = line.strip().split() cls = int(parts[0]) x1, y1, x2, y2 = map(float, parts[4:8]) x_center = ((x1 + x2) / 2) / img_width y_center = ((y1 + y2) / 2) / img_height w = (x2 - x1) / img_width h = (y2 - y1) / img_height # 防止边界越界，YOLO 训练时会裁掉越界目标 x_center = min(max(x_center, 0), 1) y_center = min(max(y_center, 0), 1) yolo_lines.append(f"{cls} {x_center:.6f} {y_center:.6f} {w:.6f} {h:.6f}") return yolo_lines

参数说明：parts[4:8]取的是 KITTI 标注中的bbox四个像素坐标。归一化后一定要做min(max())裁剪，因为弓箭目标在图像边缘时，框心可能会落在图片外部，导致训练时 Loss 异常。

5.2 用 AMD 显卡跑 YOLO 的依赖陷阱

热词里有“amd显卡跑yolo”，这是一个很现实的坑。Ultralytics 默认依赖 PyTorch，而 PyTorch 对 AMD GPU 的原生支持只有 ROCm 版本，Windows 上的 ROCm 支持又很差。如果你就是 AMD 卡，不要硬碰 PyTorch ROCm，两个替代方案：

• 方案 A：使用 CPU 推理。射箭姿态分析对延迟要求不算极端，640 输入在 i5 上大约 100ms/帧，配合状态机平滑，误差在可接受范围。
• 方案 B：导成 ONNX，用 ONNX Runtime 的 DirectML 执行提供程序跑在 AMD 显卡上。命令参考：

yolo export model=model.pt format=onnx dynamic=True python -c "import onnxruntime as ort; print(ort.get_available_providers())"

如果输出里有DmlExecutionProvider，说明 DirectML 可用。然后在model.py里加载 ONNX 而不是 .pt。这里要留意：导出的 ONNX 需要把conf和iou的阈值作为输入节点，否则你只能在外部做后处理。

5.3 验证姿态分析结果是否可信

跑通项目只是第一步，你要确保姿态分析结果不是“乱报”。最实用的验证方法是找 5 段不同水平的射箭视频，分别记录每段中状态机从 DRAW 到 RELEASE 的帧数，以及瞄准阶段的抖动标准差。然后对比这些指标与视频中运动员实际水平的正相关性。如果发现状态在瞄准期频繁误切到 RELEASE，优先检查两处：一是conf阈值低导致的误检框掺入了距离计算，二是状态机的“稳定帧数”参数设得太短。我一般会先在main.py里加一个--verbose参数，让它把每一帧的draw_ratio和状态输出到一个 CSV 文件，然后用 pandas 快速拉出状态转换点，逐帧回看视频确认。这个排查流程比盯着终端日志直观得多。

本文还有配套的精品资源，点击获取