在 Colab 环境中自定义 YOLO 输入尺寸并取消 Letterbox 填充，实战网球高速检测

以下是一篇文章范例，涵盖了如何在 Colab 环境安装并修改 YOLO，以实现自定义矩形尺寸输入 以及取消 Letterbox 填充 、采用强制拉伸等流程。你可以参考使用，适当进行修改或二次编辑即可。

在 Colab 环境中自定义 YOLO 输入尺寸并取消 Letterbox 填充，实战网球高速检测

1. 前言

在很多视觉项目里，我们需要让 YOLO 系列模型（不管是 YOLOv5、YOLOv8 还是本篇介绍的 thu-mig/yolov10）能够自定义输入尺寸 ，甚至想要取消 Letterbox 填充 （默认会有灰色边框），使网络直接使用任意分辨率（如 320×640、480×960）的图像进行推理。

在本文中，我将结合 Google Colab 进行示范，展示从环境搭建、源码修改到最终在网球高速场景下进行检测与目标分割的实践流程。适用于想要精简预处理（避免灰边）或想将模型输入适配到特殊设备（如机器人相机）的人群。

2. 环境准备

2.1 Colab 新建 Notebook

登录 Google Colab，新建一个 Python Notebook。
选择合适的 Runtime（建议 GPU 或 T4 GPU）。

2.2 安装依赖

在 Colab 中安装 supervision（一个多功能的视觉工具包）和 yolov10：

css 复制代码

!pip install -q supervision
!pip install -q git+https://github.com/thu-mig/yolov10.git

安装完成后，Python 环境就具备了基本的 YOLOv10 推理、处理图像的功能。但如果你想修改 yolov10 的源码 ，仅仅 pip install 不够，因为源代码安装后默认放在 /usr/local/lib/python3.*/dist-packages/yolov10，不便于直接修改。

3. 克隆 yolov10 并可编辑安装

为了方便我们自定义和修改 YOLOv10 源码，可以用下面步骤获取完整仓库并安装可编辑版本：

bash 复制代码

# 1. 克隆仓库
!git clone https://github.com/thu-mig/yolov10.git
%cd yolov10

# 2. 可编辑方式安装
!pip install -e .

这样，我们就在 /content/yolov10 目录下获得了 yolov10 的全部源码，所有修改都会实时生效。

4. 自定义预处理：取消 Letterbox + 强制拉伸

4.1 为什么要取消 Letterbox？

默认行为：YOLO 在推理前会进行「Letterbox」操作，即保持图像长宽比的同时缩放，剩余部分用灰色（默认 114,114,114）去填充。
弊端：有时我们不想要灰边，希望直接拉伸（或裁剪）到指定尺寸。比如机器人摄像头捕获的是 320×640 的图像，完全没必要填充成 640×640。
强制拉伸 ：直接将输入图像 resize 到指定分辨率（如 320×640），消除灰边，但会导致图像形变。

4.2 修改 `LetterBox` 类

打开刚才克隆下来的 /content/yolov10/ultralytics/data/augment.py（或实际所在位置），找到 LetterBox 类，做如下关键修改------只保留「强制拉伸」逻辑，去掉「padding」 相关操作。

示例修改后代码（示意）：

python 复制代码

import cv2
import numpy as np

class LetterBox:
    """Resize image to a given shape without adding padding (scaleFill=True)."""

    def __init__(self, new_shape=(640, 640), auto=False, scaleFill=True, scaleup=True, center=True, stride=32):
        self.new_shape = new_shape
        self.auto = auto
        self.scaleFill = scaleFill  # 改为 True，表示强制拉伸
        self.scaleup = scaleup
        self.stride = stride
        self.center = center

    def __call__(self, labels=None, image=None):
        if labels is None:
            labels = {}
        img = labels.get("img") if image is None else image
        shape = img.shape[:2]  # (h, w)

        # 如果 new_shape 是单个 int，则转成 (h, w)
        if isinstance(self.new_shape, int):
            self.new_shape = (self.new_shape, self.new_shape)
        target_h, target_w = self.new_shape

        # 强制拉伸
        # ratio = (缩放后的宽 / 原宽, 缩放后的高 / 原高)
        ratio = (target_w / shape[1], target_h / shape[0])
        # 用 OpenCV resize 实现无黑边拉伸
        img = cv2.resize(img, (target_w, target_h), interpolation=cv2.INTER_LINEAR)

        # 后面不再有 dw, dh 的填充，默认置 0
        dw, dh = 0, 0

        # 如果还有检测标签信息，需要更新 bbox 坐标
        if len(labels):
            labels = self._update_labels(labels, ratio, dw, dh)
            labels["img"] = img
            labels["resized_shape"] = (target_h, target_w)
            return labels
        else:
            return img

    def _update_labels(self, labels, ratio, padw, padh):
        # 更新 bbox 等
        labels["instances"].convert_bbox(format="xyxy")
        # 先反归一化
        orig_h, orig_w = labels["img"].shape[:2]
        labels["instances"].denormalize(orig_w, orig_h)

        # 按照 ratio 缩放
        labels["instances"].scale(*ratio)

        # 不做 padding
        # labels["instances"].add_padding(padw, padh) # 注释掉

        return labels

scaleFill=True：直接把图像拉伸到指定分辨率。
没有「自动补齐」也没有「填充」，因此灰边消失。
这样，你就能自定义任意长宽 ，如 (320, 640) 或 (480, 960)。

4.3 如何使用

在训练或推理脚本中，把默认的 LetterBox(new_shape=(640,640), scaleFill=False, ...) 改成上述自定义版本即可：

ini 复制代码

# 假设你有一个 transforms 列表
transforms = [
    LetterBox(new_shape=(320, 640), scaleFill=True),
    # ... 其他数据增强或预处理 ...
]

这样，模型在处理图像时就会直接拉伸到 320×640，不再有黑边。

5. 在网球检测/分割场景中的应用

当我们把这个自定义预处理集成进 YOLO 的检测或分割流程后，比如网球场景可能出现以下好处：

分辨率灵活
- 你可以让摄像头原生输出 320×640，直接输入模型，无需再做 Letterbox 填充。
- 如果想用更高分辨率（如 960×480），只需改一下 LetterBox(new_shape=(480, 960))。
坐标匹配简单
- 检测框、分割掩码会基于你实际指定的分辨率。后续你要做轨迹预测或机器人决策时，坐标体系更直接。
形变
- 不可避免地，若原图和目标尺寸比例不同，会有拉伸/挤压；需要确认这对检测精度或下游任务有没有影响。如果想保持纵横比，就还是需要 Letterbox（但那就会有填充边）。

部署到网球机器人时，一般是：

摄像头获取图像(分辨率可以自定义或由硬件决定)。
如果摄像头输出和训练时设置的分辨率不匹配，可以用 cv2.resize 拉伸到相同大小后再传给模型。
模型推理得到 bounding box 或分割掩码，都是在这「定死」的分辨率坐标系里。
后续可进行轨迹预测、机械臂击球或其他动作。

6. 常见问题

Q ：为什么 pip show yolov10 显示找不到包？
A ：因为你用的是 git+https://... 安装，Colab 的 pip show 有时无法检测这种直接源代码安装方式。更好的做法是克隆仓库+pip install -e .。
Q ：如何还原成默认 Letterbox？
A ：把 scaleFill=False，并启用「自动补齐」或「填充逻辑」即可。但这就会在图像边缘生成灰边。
Q ：拉伸后的目标会变形，会影响检测吗？
A：会有一定影响，特别在极端纵横比差异下，检测性能可能下降；不过在某些场景（如网球高速运动）中，可能更关注快速推理与分辨率统一，形变带来的影响可以通过数据集的相应增强和训练来部分弥补。
Q ：为什么我修改了 /content/yolov10/ultralytics/data/augment.py 但推理仍有黑边？
A ：需确保你实际运行的代码导入的是改过后的 LetterBox ，以及 Colab 环境使用的是可编辑版本。可以通过 print(LetterBox) 或 print(yolov10.__file__) 等方式检查。

7. 总结

本篇文章介绍了如何在 Colab 环境中：

安装并克隆 YOLOv10 源码，方便自定义修改；
删除默认 Letterbox 填充 ，实现强制拉伸 （scaleFill=True）到指定尺寸；
支持任意矩形输入 (如 320×640)并自动缩放 Bounding Box 和分割掩码；
在网球检测/分割这种需要更改纵横比、希望更好地匹配摄像头输出的场景下，能显著简化处理流程。

希望这篇文章能帮你在自定义分辨率、取消灰边的道路上少走弯路。如果对你有帮助，记得点个「赞」或关注哦~ 我也会继续分享更多计算机视觉与机器人相关的实战经验，敬请期待。

参考链接

thu-mig/yolov10 官方仓库

supervision 文档

opencv.org

完

在 Colab 环境中自定义 YOLO 输入尺寸并取消 Letterbox 填充，实战网球高速检测