Ultralytics ObjectCropper API 全面解析实现检测对象的实时裁剪与按帧持久化存储【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralyticsObjectCropper 是 Ultralytics Solutions 视觉方案包中的一个核心类它继承自BaseSolution面向把视频流或图像中每一个被检测到的目标按照边界框精确抠出并保存成独立图片这一任务。本文以ultralytics/solutions/object_cropper.py的 API 定义为主线结合其配置系统、调用入口与测试用例讲解裁剪目录管理、置信度/IoU 过滤、逐目标顺序编号保存等完整机制帮助你在自动化数据采集、数据集构建与聚焦分析等场景中直接落地这套能力。ObjectCropper 在 Ultralytics 中的定位在 Ultralytics Solutions 方案体系里ObjectCropper与ObjectBlurrer、ObjectCounter、Heatmap、AIGym等解决方案并列统一由 solutions/init.py 导出并注册在 Solutions 的 CLI 映射表中cfg/init.py 中crop: ObjectCropper。从 object_cropper.py 的类定义L10-L30可以看到其职责被明确描述为在实时视频流或图像中管理检测对象的裁剪基于检测到的边界框裁剪目标并将裁剪图保存到指定目录供后续分析或使用。与其它依赖目标跟踪model.track的 Solutions 不同ObjectCropper 走的是纯检测路径model.predict因此不需要跨帧维持 ID输出结果简单直接——这也是它特别适合逐帧抽帧 抠目标这类离线/在线批量任务的原因。该类的核心设计要点包括继承BaseSolution自动获得统一的SolutionConfig配置合并、日志器、profiler 计时与可调用对象机制solutions.py。通过类属性crop_dir记录裁剪输出目录crop_idx作为累计裁剪计数器iou/conf用于在推理时过滤检测框。提供唯一的对外处理入口process(im0)输入一张图像np.ndarray返回携带裁剪总数的SolutionResults对象。ObjectCropper 公开 API 速览下表归纳了参考文档中公开的类成员与说明出处为 object_cropper.py 的类 docstringL16-L24成员类型/返回说明crop_dir属性str裁剪对象图片的存放目录来源于配置项crop_dir默认cropped-detectionscrop_idx属性int累计裁剪对象数量计数器每裁剪一个目标自增 1iou属性float非极大值抑制NMS用的 IoU 阈值默认0.7conf属性float检测结果过滤的置信度阈值默认0.25__init__(**kwargs)构造器向父类透传关键字参数并读取crop_dir、iou、conf等配置process(im0)SolutionResults从输入图像中检测并裁剪对象逐张保存返回含total_crop_objects的结果对象类 docstring 给出的最小用法如下官方示例见 L25-L29cropper ObjectCropper() frame cv2.imread(frame.jpg) processed_results cropper.process(frame) print(fTotal cropped objects: {cropper.crop_idx})快速开始命令行与 Python 两种用法ObjectCropper同时暴露了 CLI 与 Python 两套入口。由于参考文档以 API 为主这里依据配套教程 guides/object-cropping.md 补充可直接运行的示例。CLI 方式# 直接裁剪未指定 source 时 Solutions CLI 会自动下载演示视频作为输入 yolo solutions crop # 传入自己的视频源 yolo solutions crop sourcepath/to/video.mp4 # 只裁剪指定的类别COCO 预训练模型下 0 代表人2 代表车 yolo solutions crop classes[0, 2]在 CLI 内部yolo solutions crop会被解析为实例化solutions.ObjectCropper(is_cliTrue, **overrides)随后逐帧调用solution(frame)cfg/init.py。值得注意的一个特殊分支crop 是唯一不写输出视频的 Solutions——代码中当solution_name ! crop时才初始化cv2.VideoWriter因为 ObjectCropper 的产出是裁剪图片而非标注视频。Python 方式import cv2 from ultralytics import solutions cap cv2.VideoCapture(path/to/video.mp4) assert cap.isOpened(), Error reading video file # 初始化对象裁剪器 cropper solutions.ObjectCropper( modelyolo26n.pt, # 用于目标检测的模型例如可换 yolo26x.pt classes[0, 2], # 只裁剪指定类别COCO 预训练下人、车 # conf0.5, # 提高置信度阈值只保留可靠检测 # crop_dircropped-detections, # 自定义裁剪保存目录 ) while cap.isOpened(): success, im0 cap.read() if not success: print(Video frame is empty or processing is complete.) break results cropper(im0) # 内部会调用 process()并附带耗时统计 # print(results) # 可通过 SolutionResults 查看输出 cap.release() cv2.destroyAllWindows()当未显式传入crop_dir时会使用默认值cropped-detections每张裁剪图都会被写入该目录文件名按顺序编号如crop_1.jpg、crop_2.jpg。这意味着无需额外编写任何落盘代码即可直接获得可检查、可继续喂给下游流程的裁剪数据集。构造流程与参数体系配置从哪来、默认值是什么ObjectCropper.__init__object_cropper.py会调用super().__init__(**kwargs)把全部关键字参数交给BaseSolution。BaseSolution初始化solutions.py的核心步骤包括通过SolutionConfig().update(**kwargs)生成统一的配置字典self.CFG并将结果记录到日志检查shapely2.0.0依赖若model为空则回退到默认模型yolo26n.pt并加载YOLO模型提取classes、show_conf、show_labels、device、iou、conf、max_det、imgsz等推理相关参数。随后 ObjectCropper 专属初始化做了三件事从CFG中取出crop_dir并用Path(crop_dir).mkdir(parentsTrue, exist_okTrue)立即创建目录保证后续写入不因目录缺失而失败检测到showTrue时发出告警showTrue is not supported for ObjectCropper; saving crops to {self.crop_dir}.并强制关闭窗口显示——因为本方案的产物是图片文件而非可视化窗口对应的showTrue分支测试见 tests/test_solutions.py初始化crop_idx 0并把iou、conf缓存在实例上。全部相关配置项与默认值配置中心的定义位于 config.py对 ObjectCropper 有直接影响的参数整理如下默认值同时被 solutions-args.md 文档宏引用参数类型默认值对 ObjectCropper 的作用crop_dirstrcropped-detections裁剪图片的输出目录构造时自动创建modelstrNone回退yolo26n.pt用于检测的模型权重路径classeslist[int]None只裁剪指定类别索引None表示全部类别conffloat0.25保留检测的最低置信度用于过滤误检ioufloat0.7NMS 的 IoU 阈值imgszint640送入模型的输入尺寸devicestrNone推理设备如cpu、0默认自动选择max_detint300单帧允许的最大检测数量quantizeint/strNone推理精度设置如 16 即 FP16替换旧half参数sourcestrNone仅 CLI 使用视频输入路径verboseboolTrue每帧打印类别计数与耗时日志showboolFalseObjectCropper 不支持置True会告警并强制关闭SolutionConfig.update()config.py会逐个校验关键字只有已声明的属性才能被覆盖否则抛出ValueError这一机制保证了传入参数不会被静默忽略同时它支持将旧版half参数自动迁移到quantize。process() 源码级拆解检测、过滤、裁剪的完整链路核心处理逻辑process(im0)object_cropper.py非常精炼但包含了一条完整的数据管线1. 推理阶段with self.profilers[0]: results self.model.predict( im0, classesself.classes, confself.conf, iouself.iou, deviceself.CFG[device], imgszself.CFG[imgsz], verboseFalse, )[0] self.clss results.boxes.cls.tolist() # required for logging only.推理被包裹在self.profilers[0]中计时结果交给BaseSolution.__call__汇总为predict耗时通过classes、conf、iou三个参数把配置中的过滤策略直接下发给predict实现类别过滤 置信度过滤 NMS 过滤的一站式执行verboseFalse使内部推理静默避免每帧刷屏self.clss仅用于后续逐帧日志统计各类别数量。2. 裁剪阶段for box in results.boxes: self.crop_idx 1 save_one_box( box.xyxy, im0, filePath(self.crop_dir) / fcrop_{self.crop_idx}.jpg, BGRTrue, )遍历当前帧全部检测框results.boxescrop_idx是跨帧累加的全局计数器因此即使视频后续帧目标更多或更少文件名也始终全局唯一、严格递增不会互相覆盖每个框调用save_one_box把框坐标box.xyxy、原图im0与目标路径传入BGRTrue表示按 OpenCV 的 BGR 顺序直接落盘这与cv2.VideoCapture读取的通道顺序一致。3. 结果返回阶段return SolutionResults(plot_imim0, total_crop_objectsself.crop_idx)返回的SolutionResults对象定义见 solutions.py携带两个关键信息plot_im原始输入帧ObjectCropper 不叠加任何可视化标注因此 CLI 分支无需写输出视频total_crop_objects到目前为止的累计裁剪总数可通过results.total_crop_objects直接读取。裁剪底层的实现细节save_one_box 都做了什么裁剪动作最终落在ultralytics.utils.plotting.save_one_boxplotting.py。理解它有助于你预测裁剪结果的边界行为格式转换与取整xyxy被转为xywh后先按gain放大并加pad像素再转回xyxy并取整b[:, 2:] * gain pad默认gain1.02、pad10即裁剪框四周会留出约 2% 外扩与 10 像素边距避免目标紧贴裁剪边界边界裁剪保护通过ops.clip_boxes(xyxy, im.shape)将越界坐标裁回图像范围保证靠近图像边缘的目标不会产生切片越界错误通道序处理BGRTrue时保持 BGR 顺序灰度图天然不受影响否则会做通道反转返回与保存两用saveTrue时写入磁盘同时始终返回裁剪后的crop数组。因此 ObjectCropper 生成的每张crop_N.jpg并不是严格的裸检测框而是带少量边距、经过边界保护的原图子块。调用时机的性能统计与逐帧日志虽然process()是逻辑入口但推荐用法是直接调用实例cropper(im0)因为BaseSolution.__call__solutions.py提供了两层附加价值耗时拆分通过两个独立的profiler计算出predict检测推理与solution方案自身逻辑各自耗时单位为毫秒写入results.speed字典verbose 日志当CFG[verbose]为True时逐帧输出帧号、输入分辨率、各类别检测数量以及推理速度例如形如Speed: xx.xms predict, x.xms solution per image...的信息。注意在__call__中ObjectCropper 类型会被识别为走predict而非track计时路径solutions.py这也再次印证了它不依赖跟踪链路。基于测试用例的可靠性验证仓库的解决方案测试套件 tests/test_solutions.py 对 ObjectCropper 覆盖了两个维度端到端视频流程L133-L140在参数化测试test_solution中以ObjectCroppersolutions.ObjectCropper配对使用crop_video演示视频、temp_crop_dir会映射成临时目录下的cropped-detections运行完整process_video验证其能从真实视频中稳定产出裁剪图片测试统一设置了imgsz320以控制 CI 推理成本构造告警覆盖L451-L453test_object_crop_with_show_True专门以showTrue实例化覆盖构造函数中不支持窗口显示并强制关闭的告警分支。这说明 API 文档所描述的行为目录写入、逐帧裁剪、show 告警均有自动化测试兜底可作为二次开发时校验自身集成的参照。使用建议与已知限制结合源码行为给出以下实操要点与边界说明构建数据集的理想拍档配合classes过滤 适度提高conf可以只把可靠目标落入磁盘配合逐帧读取视频即可在无人值守下把整段视频转换为目标子图集合供后续分类、检索、标注或模型训练使用。不要指望可视化输出ObjectCropper 不绘制标注框、不支持show也不在 CLI 下生成结果视频。若同时需要标注可视化建议改用predict/track模式或自行基于plot_im叠加标注。模型与设备选择模型默认yolo26n.pt可按精度需求换yolo26s.pt、yolo26x.pt等大批量处理时通过device0GPU与imgsz权衡吞吐。以上均为配置文件与 CLI 可覆盖项。参数合法性有兜底任何不在SolutionConfig中的关键字都会触发ValueError写错参数名不会静默失败。文件命名全局单调递增crop_idx从实例创建起累计若在长视频中意外中断并新建实例编号会从 1 重新开始可能与旧文件重名——建议为不同批次指定不同crop_dir。相关参考API 参考页面docs/en/reference/solutions/object_cropper.md配套实战教程docs/en/guides/object-cropping.md核心实现ultralytics/solutions/object_cropper.py基类与统一调用/结果对象ultralytics/solutions/solutions.py配置中心与默认值ultralytics/solutions/config.py裁剪落盘函数save_one_boxultralytics/utils/plotting.pyCLI 解决方案映射与执行分支ultralytics/cfg/init.py自动化测试tests/test_solutions.pySolutions 方案总览docs/en/solutions/index.md【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Ultralytics ObjectCropper API 全面解析：实现检测对象的实时裁剪与按帧持久化存储
Ultralytics ObjectCropper API 全面解析实现检测对象的实时裁剪与按帧持久化存储【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralyticsObjectCropper 是 Ultralytics Solutions 视觉方案包中的一个核心类它继承自BaseSolution面向把视频流或图像中每一个被检测到的目标按照边界框精确抠出并保存成独立图片这一任务。本文以ultralytics/solutions/object_cropper.py的 API 定义为主线结合其配置系统、调用入口与测试用例讲解裁剪目录管理、置信度/IoU 过滤、逐目标顺序编号保存等完整机制帮助你在自动化数据采集、数据集构建与聚焦分析等场景中直接落地这套能力。ObjectCropper 在 Ultralytics 中的定位在 Ultralytics Solutions 方案体系里ObjectCropper与ObjectBlurrer、ObjectCounter、Heatmap、AIGym等解决方案并列统一由 solutions/init.py 导出并注册在 Solutions 的 CLI 映射表中cfg/init.py 中crop: ObjectCropper。从 object_cropper.py 的类定义L10-L30可以看到其职责被明确描述为在实时视频流或图像中管理检测对象的裁剪基于检测到的边界框裁剪目标并将裁剪图保存到指定目录供后续分析或使用。与其它依赖目标跟踪model.track的 Solutions 不同ObjectCropper 走的是纯检测路径model.predict因此不需要跨帧维持 ID输出结果简单直接——这也是它特别适合逐帧抽帧 抠目标这类离线/在线批量任务的原因。该类的核心设计要点包括继承BaseSolution自动获得统一的SolutionConfig配置合并、日志器、profiler 计时与可调用对象机制solutions.py。通过类属性crop_dir记录裁剪输出目录crop_idx作为累计裁剪计数器iou/conf用于在推理时过滤检测框。提供唯一的对外处理入口process(im0)输入一张图像np.ndarray返回携带裁剪总数的SolutionResults对象。ObjectCropper 公开 API 速览下表归纳了参考文档中公开的类成员与说明出处为 object_cropper.py 的类 docstringL16-L24成员类型/返回说明crop_dir属性str裁剪对象图片的存放目录来源于配置项crop_dir默认cropped-detectionscrop_idx属性int累计裁剪对象数量计数器每裁剪一个目标自增 1iou属性float非极大值抑制NMS用的 IoU 阈值默认0.7conf属性float检测结果过滤的置信度阈值默认0.25__init__(**kwargs)构造器向父类透传关键字参数并读取crop_dir、iou、conf等配置process(im0)SolutionResults从输入图像中检测并裁剪对象逐张保存返回含total_crop_objects的结果对象类 docstring 给出的最小用法如下官方示例见 L25-L29cropper ObjectCropper() frame cv2.imread(frame.jpg) processed_results cropper.process(frame) print(fTotal cropped objects: {cropper.crop_idx})快速开始命令行与 Python 两种用法ObjectCropper同时暴露了 CLI 与 Python 两套入口。由于参考文档以 API 为主这里依据配套教程 guides/object-cropping.md 补充可直接运行的示例。CLI 方式# 直接裁剪未指定 source 时 Solutions CLI 会自动下载演示视频作为输入 yolo solutions crop # 传入自己的视频源 yolo solutions crop sourcepath/to/video.mp4 # 只裁剪指定的类别COCO 预训练模型下 0 代表人2 代表车 yolo solutions crop classes[0, 2]在 CLI 内部yolo solutions crop会被解析为实例化solutions.ObjectCropper(is_cliTrue, **overrides)随后逐帧调用solution(frame)cfg/init.py。值得注意的一个特殊分支crop 是唯一不写输出视频的 Solutions——代码中当solution_name ! crop时才初始化cv2.VideoWriter因为 ObjectCropper 的产出是裁剪图片而非标注视频。Python 方式import cv2 from ultralytics import solutions cap cv2.VideoCapture(path/to/video.mp4) assert cap.isOpened(), Error reading video file # 初始化对象裁剪器 cropper solutions.ObjectCropper( modelyolo26n.pt, # 用于目标检测的模型例如可换 yolo26x.pt classes[0, 2], # 只裁剪指定类别COCO 预训练下人、车 # conf0.5, # 提高置信度阈值只保留可靠检测 # crop_dircropped-detections, # 自定义裁剪保存目录 ) while cap.isOpened(): success, im0 cap.read() if not success: print(Video frame is empty or processing is complete.) break results cropper(im0) # 内部会调用 process()并附带耗时统计 # print(results) # 可通过 SolutionResults 查看输出 cap.release() cv2.destroyAllWindows()当未显式传入crop_dir时会使用默认值cropped-detections每张裁剪图都会被写入该目录文件名按顺序编号如crop_1.jpg、crop_2.jpg。这意味着无需额外编写任何落盘代码即可直接获得可检查、可继续喂给下游流程的裁剪数据集。构造流程与参数体系配置从哪来、默认值是什么ObjectCropper.__init__object_cropper.py会调用super().__init__(**kwargs)把全部关键字参数交给BaseSolution。BaseSolution初始化solutions.py的核心步骤包括通过SolutionConfig().update(**kwargs)生成统一的配置字典self.CFG并将结果记录到日志检查shapely2.0.0依赖若model为空则回退到默认模型yolo26n.pt并加载YOLO模型提取classes、show_conf、show_labels、device、iou、conf、max_det、imgsz等推理相关参数。随后 ObjectCropper 专属初始化做了三件事从CFG中取出crop_dir并用Path(crop_dir).mkdir(parentsTrue, exist_okTrue)立即创建目录保证后续写入不因目录缺失而失败检测到showTrue时发出告警showTrue is not supported for ObjectCropper; saving crops to {self.crop_dir}.并强制关闭窗口显示——因为本方案的产物是图片文件而非可视化窗口对应的showTrue分支测试见 tests/test_solutions.py初始化crop_idx 0并把iou、conf缓存在实例上。全部相关配置项与默认值配置中心的定义位于 config.py对 ObjectCropper 有直接影响的参数整理如下默认值同时被 solutions-args.md 文档宏引用参数类型默认值对 ObjectCropper 的作用crop_dirstrcropped-detections裁剪图片的输出目录构造时自动创建modelstrNone回退yolo26n.pt用于检测的模型权重路径classeslist[int]None只裁剪指定类别索引None表示全部类别conffloat0.25保留检测的最低置信度用于过滤误检ioufloat0.7NMS 的 IoU 阈值imgszint640送入模型的输入尺寸devicestrNone推理设备如cpu、0默认自动选择max_detint300单帧允许的最大检测数量quantizeint/strNone推理精度设置如 16 即 FP16替换旧half参数sourcestrNone仅 CLI 使用视频输入路径verboseboolTrue每帧打印类别计数与耗时日志showboolFalseObjectCropper 不支持置True会告警并强制关闭SolutionConfig.update()config.py会逐个校验关键字只有已声明的属性才能被覆盖否则抛出ValueError这一机制保证了传入参数不会被静默忽略同时它支持将旧版half参数自动迁移到quantize。process() 源码级拆解检测、过滤、裁剪的完整链路核心处理逻辑process(im0)object_cropper.py非常精炼但包含了一条完整的数据管线1. 推理阶段with self.profilers[0]: results self.model.predict( im0, classesself.classes, confself.conf, iouself.iou, deviceself.CFG[device], imgszself.CFG[imgsz], verboseFalse, )[0] self.clss results.boxes.cls.tolist() # required for logging only.推理被包裹在self.profilers[0]中计时结果交给BaseSolution.__call__汇总为predict耗时通过classes、conf、iou三个参数把配置中的过滤策略直接下发给predict实现类别过滤 置信度过滤 NMS 过滤的一站式执行verboseFalse使内部推理静默避免每帧刷屏self.clss仅用于后续逐帧日志统计各类别数量。2. 裁剪阶段for box in results.boxes: self.crop_idx 1 save_one_box( box.xyxy, im0, filePath(self.crop_dir) / fcrop_{self.crop_idx}.jpg, BGRTrue, )遍历当前帧全部检测框results.boxescrop_idx是跨帧累加的全局计数器因此即使视频后续帧目标更多或更少文件名也始终全局唯一、严格递增不会互相覆盖每个框调用save_one_box把框坐标box.xyxy、原图im0与目标路径传入BGRTrue表示按 OpenCV 的 BGR 顺序直接落盘这与cv2.VideoCapture读取的通道顺序一致。3. 结果返回阶段return SolutionResults(plot_imim0, total_crop_objectsself.crop_idx)返回的SolutionResults对象定义见 solutions.py携带两个关键信息plot_im原始输入帧ObjectCropper 不叠加任何可视化标注因此 CLI 分支无需写输出视频total_crop_objects到目前为止的累计裁剪总数可通过results.total_crop_objects直接读取。裁剪底层的实现细节save_one_box 都做了什么裁剪动作最终落在ultralytics.utils.plotting.save_one_boxplotting.py。理解它有助于你预测裁剪结果的边界行为格式转换与取整xyxy被转为xywh后先按gain放大并加pad像素再转回xyxy并取整b[:, 2:] * gain pad默认gain1.02、pad10即裁剪框四周会留出约 2% 外扩与 10 像素边距避免目标紧贴裁剪边界边界裁剪保护通过ops.clip_boxes(xyxy, im.shape)将越界坐标裁回图像范围保证靠近图像边缘的目标不会产生切片越界错误通道序处理BGRTrue时保持 BGR 顺序灰度图天然不受影响否则会做通道反转返回与保存两用saveTrue时写入磁盘同时始终返回裁剪后的crop数组。因此 ObjectCropper 生成的每张crop_N.jpg并不是严格的裸检测框而是带少量边距、经过边界保护的原图子块。调用时机的性能统计与逐帧日志虽然process()是逻辑入口但推荐用法是直接调用实例cropper(im0)因为BaseSolution.__call__solutions.py提供了两层附加价值耗时拆分通过两个独立的profiler计算出predict检测推理与solution方案自身逻辑各自耗时单位为毫秒写入results.speed字典verbose 日志当CFG[verbose]为True时逐帧输出帧号、输入分辨率、各类别检测数量以及推理速度例如形如Speed: xx.xms predict, x.xms solution per image...的信息。注意在__call__中ObjectCropper 类型会被识别为走predict而非track计时路径solutions.py这也再次印证了它不依赖跟踪链路。基于测试用例的可靠性验证仓库的解决方案测试套件 tests/test_solutions.py 对 ObjectCropper 覆盖了两个维度端到端视频流程L133-L140在参数化测试test_solution中以ObjectCroppersolutions.ObjectCropper配对使用crop_video演示视频、temp_crop_dir会映射成临时目录下的cropped-detections运行完整process_video验证其能从真实视频中稳定产出裁剪图片测试统一设置了imgsz320以控制 CI 推理成本构造告警覆盖L451-L453test_object_crop_with_show_True专门以showTrue实例化覆盖构造函数中不支持窗口显示并强制关闭的告警分支。这说明 API 文档所描述的行为目录写入、逐帧裁剪、show 告警均有自动化测试兜底可作为二次开发时校验自身集成的参照。使用建议与已知限制结合源码行为给出以下实操要点与边界说明构建数据集的理想拍档配合classes过滤 适度提高conf可以只把可靠目标落入磁盘配合逐帧读取视频即可在无人值守下把整段视频转换为目标子图集合供后续分类、检索、标注或模型训练使用。不要指望可视化输出ObjectCropper 不绘制标注框、不支持show也不在 CLI 下生成结果视频。若同时需要标注可视化建议改用predict/track模式或自行基于plot_im叠加标注。模型与设备选择模型默认yolo26n.pt可按精度需求换yolo26s.pt、yolo26x.pt等大批量处理时通过device0GPU与imgsz权衡吞吐。以上均为配置文件与 CLI 可覆盖项。参数合法性有兜底任何不在SolutionConfig中的关键字都会触发ValueError写错参数名不会静默失败。文件命名全局单调递增crop_idx从实例创建起累计若在长视频中意外中断并新建实例编号会从 1 重新开始可能与旧文件重名——建议为不同批次指定不同crop_dir。相关参考API 参考页面docs/en/reference/solutions/object_cropper.md配套实战教程docs/en/guides/object-cropping.md核心实现ultralytics/solutions/object_cropper.py基类与统一调用/结果对象ultralytics/solutions/solutions.py配置中心与默认值ultralytics/solutions/config.py裁剪落盘函数save_one_boxultralytics/utils/plotting.pyCLI 解决方案映射与执行分支ultralytics/cfg/init.py自动化测试tests/test_solutions.pySolutions 方案总览docs/en/solutions/index.md【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
深度解析：从参数配置到避坑指南)
