企业官网建设流程全解析

简介：本资源是一套面向本科毕业设计与课程实践的Python深度学习项目，聚焦智慧城市背景下的垃圾分类自动化检测需求，适用于计算机、人工智能及环境工程等专业学生开展毕设开发或算法落地实践。压缩包共2000个文件，以1996个txt标注文件为主（含图像坐标与类别标签），辅以1个YOLOv8训练配置yaml、2个md说明文档及1份配套论文docx，整体229.28MB，结构完整覆盖数据集、模型配置、界面代码与技术文档。已有107人学习下载，体现较强的教学参考价值。用户可直接复现YOLOv8垃圾分类检测全流程：从MySQL数据库设计、PyQt5可视化界面（支持图像上传/摄像头实时检测/分类统计）、到C2f模块优化模型推理与94.2% mAP精度验证，同时获得可运行源码、SQL脚本及完整论文框架，显著降低毕设开发门槛与调试成本。

1. 这不是又一个调用API的Demo：它是一套能跑通“数据采集→模型训练→部署检测→结果存档”全链路的毕业设计闭环方案

你见过太多“用现成YOLOv5权重跑几张图就叫垃圾分类系统”的课设了——没有数据清洗逻辑、模型没重训、检测结果不落库、连垃圾类别都硬编码在if语句里。这套方案反其道而行：它从真实场景出发，强制要求你用手机拍300张带光照变化/遮挡/倾斜角度的垃圾照片，手动标注后生成VOC+YOLO双格式数据集；模型层不直接加载yolov5s.pt，而是基于COCO预训练权重做迁移学习，冻结Backbone前3个stage，只微调Head与Neck；检测服务不走Flask简易接口，而是封装成独立CLI工具，支持--input_dir批量推理、--save_txt输出标准YOLO格式坐标、--db_save自动写入MySQL的detection_log表（含时间戳、图片路径、置信度、类别ID）；最后附带一套可直接导入的SQL脚本，建好garbage_category（含4大类12子类）、detection_log、user_upload三张表，并预置分类映射关系。适合需要交完整文档、答辩能现场演示、且导师会查代码逻辑是否自洽的Python毕设/课程设计场景。

2. 总体架构设计：四层解耦结构与五个核心模块的职责边界

这套系统不是单个Python脚本堆砌而成，而是按“输入→处理→存储→输出→管理”五层物理隔离设计。每一层有明确输入输出契约，避免常见毕设中“所有逻辑挤在main.py里导致改一行崩全盘”的翻车现场。四层指：数据接入层（负责图像采集、格式校验、自动归档）、模型服务层（封装YOLO推理引擎，屏蔽PyTorch版本差异）、持久化层（MySQL事务写入+JSON日志双备份）、应用接口层（CLI命令行工具，非Web界面，降低部署复杂度）。五个模块对应具体实现单元：data_collector（含手机图转标准尺寸+去畸变）、yolo_trainer（支持v5/v7/v8切换的训练配置器）、detector_cli（主程序入口，参数驱动）、db_manager（连接池+防重复插入+字段校验）、report_generator（生成PDF检测报告，含热力图与分类统计）。这种结构让答辩时你能清晰回答“这个功能在哪实现？改需求时动哪块？”——而不是翻着2000行代码说“应该…大概…在这附近”。

2.1 数据接入层：为什么必须自己写采集脚本，而不是用OpenCV读文件夹？

很多同学直接cv2.imread('test.jpg')硬编码路径，导致答辩时导师问“如果用户上传新图片怎么办？”当场卡壳。本方案强制使用data_collector模块，它接收--source_type mobile或--source_type folder参数，动态适配不同来源：

• mobile模式下，调用adb shell screencap截取安卓设备屏幕（需开启USB调试），自动裁剪状态栏，保存为raw/20240520_142301_mobile.jpg；
• folder模式下，扫描指定目录，对每张图执行PIL.ImageOps.exif_transpose()修正旋转方向，再用cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8,8))做自适应直方图均衡化，解决手机拍摄常见的背光过暗问题。

关键代码如下（data_collector/collector.py）：

def preprocess_image(img_path: str, mode: str = "folder") -> np.ndarray: """统一预处理入口：修正EXIF方向 + 增强对比度 + 标准化尺寸""" img = Image.open(img_path) if mode == "mobile": # 移动端截图常含状态栏，裁剪顶部60px（实测主流安卓机型） img = img.crop((0, 60, img.width, img.height)) img = ImageOps.exif_transpose(img) # 修复横拍竖显问题 img_cv = cv2.cvtColor(np.array(img), cv2.COLOR_RGB2BGR) # CLAHE增强：clipLimit过大会产生噪点，2.0是血泪经验平衡点 clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8,8)) img_cv = cv2.cvtColor(img_cv, cv2.COLOR_BGR2LAB) img_cv[:,:,0] = clahe.apply(img_cv[:,:,0]) img_cv = cv2.cvtColor(img_cv, cv2.COLOR_LAB2BGR) # 统一缩放到640x640，保持长宽比并padding黑边（YOLO要求正方形输入） img_cv = letterbox(img_cv, new_shape=(640, 640))[0] return img_cv def letterbox(img: np.ndarray, new_shape=(640, 640), color=(0, 0, 0)) -> tuple: """YOLO标准letterbox：等比缩放+黑边填充，返回（处理后图, 缩放系数, (dw,dh)）""" shape = img.shape[:2] # original shape if isinstance(new_shape, int): new_shape = (new_shape, new_shape) r = min(new_shape[0] / shape[0], new_shape[1] / shape[1]) ratio = r, r new_unpad = int(round(shape[1] * r)), int(round(shape[0] * r)) dw, dh = new_shape[1] - new_unpad[0], new_shape[0] - new_unpad[1] dw /= 2 dh /= 2 if shape[::-1] != new_unpad: img = cv2.resize(img, new_unpad, interpolation=cv2.INTER_LINEAR) top, bottom = int(round(dh - 0.1)), int(round(dh + 0.1)) left, right = int(round(dw - 0.1)), int(round(dw + 0.1)) img = cv2.copyMakeBorder(img, top, bottom, left, right, cv2.BORDER_CONSTANT, value=color) return img, ratio, (dw, dh)

提示：letterbox函数必须手写，不能依赖torchvision.transforms.Resize——后者会拉伸变形，YOLO对坐标精度敏感，拉伸后bbox回归会系统性偏移。我们实测过，用Resize(640)代替letterbox，mAP下降12.7%。

2.2 模型服务层：如何让YOLOv5/v7/v8共存而不互相污染？

毕设最常踩的坑是“pip install yolov5 yolov7 yolov8”导致版本冲突。本方案采用模型工厂模式：每个YOLO版本封装为独立类，通过抽象基类BaseDetector约束接口，运行时由--model_version v5参数动态加载。目录结构强制隔离：

yolo_models/ ├── v5/ │ ├── models/ # 官方yolov5 repo的models/目录（仅保留common.py、yolo.py） │ ├── utils/ # 仅保留general.py、torch_utils.py │ └── weights/ # 存放yolov5s.pt, custom_train_v5.pt ├── v7/ │ ├── models/ │ └── weights/ └── v8/ ├── ultralytics/ # 完整ultralytics包（v8.0.200） └── weights/

核心加载逻辑（yolo_models/factory.py）：

from abc import ABC, abstractmethod from typing import List, Dict, Any class BaseDetector(ABC): @abstractmethod def load_model(self, weights_path: str) -> Any: pass @abstractmethod def predict(self, image: np.ndarray) -> List[Dict]: pass class YOLOv5Detector(BaseDetector): def __init__(self): # 动态添加v5路径到sys.path，避免全局安装 sys.path.insert(0, str(Path(__file__).parent / "v5")) from models.yolo import Model from utils.general import non_max_suppression self.Model = Model self.non_max_suppression = non_max_suppression def load_model(self, weights_path: str): # 加载v5权重，强制map_location='cpu'避免GPU环境依赖 ckpt = torch.load(weights_path, map_location='cpu') self.model = self.Model(cfg=ckpt['model'].yaml).to('cpu') self.model.load_state_dict(ckpt['model'].float().state_dict()) self.model.eval() return self.model def get_detector(version: str) -> BaseDetector: """工厂函数：根据version字符串返回对应检测器实例""" if version == "v5": return YOLOv5Detector() elif version == "v7": return YOLOv7Detector() # 同理实现 elif version == "v8": return YOLOv8Detector() # 使用ultralytics官方API else: raise ValueError(f"Unsupported version: {version}")

这样设计的好处是：答辩时导师问“换v8怎么改？”，你直接指向factory.py第32行elif version == "v8"，说明“只需在此处注入新类，其他模块完全不用动”。而不会出现“我删了v5重装v8，结果整个项目报错”的玄学现场。

2.3 持久化层：为什么MySQL比SQLite更适合毕设答辩演示？

学生常用SQLite，但答辩时导师可能要求“查一下昨天检测的塑料瓶数量”，而SQLite不支持并发写入，多开几个CLI窗口就报database is locked。本方案强制使用MySQL，并内置连接池与事务回滚机制。db_manager模块核心逻辑：

• 表结构严格遵循垃圾分类国标（GB/T 19095-2019），garbage_category表含id,name,parent_id,code（如0101代表“可回收物-废纸”）；
• detection_log表设计为id,image_path,category_id,confidence,bbox_x1,bbox_y1,bbox_x2,bbox_y2,detect_time,model_version，其中bbox_*字段类型为DECIMAL(5,2)，避免浮点数精度丢失；
• 写入时用INSERT IGNORE INTO防止重复图片路径插入，同时触发ON DUPLICATE KEY UPDATE更新最高置信度。

关键SQL脚本（sql/create_tables.sql）节选：

-- 垃圾类别主表：支持四级分类（大类→中类→小类→明细） CREATE TABLE IF NOT EXISTS garbage_category ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(50) NOT NULL COMMENT '分类名称，如"废纸"', parent_id INT DEFAULT NULL COMMENT '上级分类ID，NULL表示顶级', code VARCHAR(10) NOT NULL UNIQUE COMMENT '国标编码，如"0101"', level TINYINT NOT NULL COMMENT '层级：1=大类，2=中类，3=小类，4=明细', created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, INDEX idx_parent (parent_id), INDEX idx_code (code) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; -- 检测日志表：每次检测生成一条记录，支持按时间/类别/置信度查询 CREATE TABLE IF NOT EXISTS detection_log ( id BIGINT PRIMARY KEY AUTO_INCREMENT, image_path VARCHAR(255) NOT NULL COMMENT '原始图片绝对路径', category_id INT NOT NULL COMMENT '关联garbage_category.id', confidence DECIMAL(4,3) NOT NULL COMMENT '置信度，0.000~1.000', bbox_x1 DECIMAL(5,2) NOT NULL COMMENT '归一化坐标，左上角x', bbox_y1 DECIMAL(5,2) NOT NULL COMMENT '归一化坐标，左上角y', bbox_x2 DECIMAL(5,2) NOT NULL COMMENT '归一化坐标，右下角x', bbox_y2 DECIMAL(5,2) NOT NULL COMMENT '归一化坐标，右下角y', detect_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, model_version VARCHAR(10) NOT NULL COMMENT '使用的YOLO版本，如"v5"', created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, INDEX idx_image (image_path), INDEX idx_category (category_id), INDEX idx_time (detect_time), INDEX idx_confidence (confidence), FOREIGN KEY (category_id) REFERENCES garbage_category(id) ON DELETE CASCADE ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

注意：bbox_*字段必须用DECIMAL(5,2)而非FLOAT！我们曾因用FLOAT导致坐标计算误差，在生成热力图时出现0.5像素偏移，答辩演示时框出的垃圾边缘明显“虚焦”。

3. 模型训练实战：从零开始训练YOLOv5s的完整流程与超参避坑指南

训练不是python train.py --data data.yaml --weights yolov5s.pt一行命令完事。本方案提供可复现的全流程：数据准备→配置生成→训练监控→权重导出→效果验证。重点解决毕设中最易被忽略的三个致命点：数据泄露（验证集混入训练图）、标签错误（txt文件坐标超出1.0）、过拟合（mAP涨但val_loss不降）。所有操作均在yolo_trainer模块中封装为可复用函数，避免答辩时被问“你训练用了多少epoch？学习率怎么设的？”答不上来。

3.1 数据准备：为什么必须用VOC+YOLO双格式，而不是只生成labels/？

YOLO官方要求labels/下为.txt文件，但毕设答辩常需展示“标注质量”，而.txt纯文本无法直观验证。本方案强制生成VOC格式（Annotations/下XML）与YOLO格式（labels/下TXT）双备份，并提供validate_labels.py脚本自动校验：

• 检查每张图对应的.txt文件是否存在，且行数等于XML中<object>数量；
• 解析.txt每行，验证x_center, y_center, width, height是否全在[0.0, 1.0]区间（超出则报错并定位文件）；
• 对比XML与TXT的类别名，确保garbage_category.code与names.txt索引严格一致（如names.txt第0行必须是0101对应“废纸”）。

校验脚本关键逻辑（yolo_trainer/validate_labels.py）：

def validate_yolo_labels(label_dir: Path, image_dir: Path, names_file: Path): """校验YOLO标签：坐标范围 + 文件存在性 + 类别映射""" with open(names_file) as f: names = [line.strip() for line in f.readlines()] for txt_path in label_dir.glob("*.txt"): img_name = txt_path.stem + ".jpg" img_path = image_dir / img_name if not img_path.exists(): print(f"⚠️ 警告：{txt_path} 对应图片 {img_name} 不存在") continue with open(txt_path) as f: lines = f.readlines() for i, line in enumerate(lines): parts = line.strip().split() if len(parts) != 5: print(f"❌ 错误：{txt_path} 第{i+1}行格式错误，应为5列：cls x y w h") continue try: cls, x, y, w, h = map(float, parts) if not (0 <= x <= 1 and 0 <= y <= 1 and 0 <= w <= 1 and 0 <= h <= 1): print(f"❌ 错误：{txt_path} 第{i+1}行坐标越界 x={x:.3f} y={y:.3f} w={w:.3f} h={h:.3f}") if cls >= len(names): print(f"❌ 错误：{txt_path} 第{i+1}行类别ID {int(cls)} 超出names.txt长度 {len(names)}") except ValueError: print(f"❌ 错误：{txt_path} 第{i+1}行含非数字字符") # 运行方式：python validate_labels.py --label_dir data/labels --image_dir data/images --names_file data/names.txt

血泪经验：某次训练前未运行此脚本，导致12张图的w值为1.003，训练时PyTorch报nan loss，debug耗时8小时。从此我养成立项即跑校验的习惯。

3.2 训练配置：如何设置超参才能让mAP稳定在75%以上？

毕设常见误区是盲目调高batch_size追求速度，结果显存爆满或梯度爆炸。本方案基于RTX 3060（12G）实测，给出稳健配置（data/hyp.yaml）：

lr0: 0.01 # 初始学习率，v5默认0.01，v7/v8需调至0.001 lrf: 0.1 # 最终学习率 = lr0 * lrf，线性衰减 momentum: 0.937 # SGD动量，过高易震荡，过低收敛慢 weight_decay: 0.0005 # L2正则，防止过拟合 warmup_epochs: 3.0 # 前3轮warmup，学习率从0线性升到lr0 warmup_momentum: 0.8 # warmup期间动量从0.8起始 box: 0.05 # box损失权重，过高会导致定位不准 cls: 0.5 # 分类损失权重，过低会使类别混淆 cls_pw: 1.0 # 分类交叉熵正样本权重 obj: 1.0 # obj损失权重 obj_pw: 1.0 # obj交叉熵正样本权重 iou_t: 0.20 # IOU阈值，用于生成正样本anchor anchor_t: 4.0 # anchor匹配阈值，过高导致正样本过少 fl_gamma: 0.0 # Focal Loss gamma，毕设不用Focal Loss hsv_h: 0.015 # HSV色相扰动，增强鲁棒性 hsv_s: 0.7 # HSV饱和度扰动，提升暗光识别 hsv_v: 0.4 # HSV明度扰动，应对背光场景 degrees: 0.0 # 旋转增强，毕设禁用（易使垃圾倒置） translate: 0.1 # 平移增强，防遮挡 scale: 0.5 # 缩放增强，应对远近差异 shear: 0.0 # 剪切增强，毕设禁用（扭曲垃圾形状） perspective: 0.0 # 透视变换，毕设禁用（失真严重） flipud: 0.0 # 上下翻转，禁用（垃圾无上下之分） fliplr: 0.5 # 左右翻转，启用（模拟手持角度） mosaic: 1.0 # 马赛克增强，必开！提升小目标检测 mixup: 0.1 # MixUp增强，0.1是平衡点，过高模糊边界 copy_paste: 0.0 # 复制粘贴增强，毕设禁用（易产生伪影）

玄学提示：mosaic: 1.0和mixup: 0.1组合是本方案mAP突破75%的关键。我们对比过：关掉mosaic，mAP跌至62.3%；mixup调到0.5，val_loss曲线剧烈震荡。记住：马赛克是你的后悔药，MixUp是你的稳定器。

3.3 训练监控：如何用TensorBoard看懂loss曲线是否健康？

很多同学只看最终mAP，却不知训练过程已埋雷。本方案强制要求每轮保存results.csv，并用plot_results.py生成三图合一曲线（train/box_loss,val/box_loss,metrics/mAP_0.5）。健康曲线特征：

• train/box_loss：平滑下降，无剧烈跳变（跳变说明batch异常）；
• val/box_loss：与train曲线平行下降，若val先降后升，说明过拟合；
• metrics/mAP_0.5：单调上升，若某轮突降>3%，立即检查该轮验证图是否混入训练集。

plot_results.py核心绘图逻辑：

def plot_results(file_path: str = "results.csv"): """绘制训练曲线：三子图共享x轴（epoch）""" results = pd.read_csv(file_path) epochs = results['epoch'].values fig, axes = plt.subplots(1, 3, figsize=(18, 5)) # 图1：box_loss axes[0].plot(epochs, results['train/box_loss'], label='Train', color='blue') axes[0].plot(epochs, results['val/box_loss'], label='Val', color='red', linestyle='--') axes[0].set_title('Box Loss') axes[0].set_xlabel('Epoch') axes[0].set_ylabel('Loss') axes[0].legend() axes[0].grid(True) # 图2：cls_loss axes[1].plot(epochs, results['train/cls_loss'], label='Train', color='green') axes[1].plot(epochs, results['val/cls_loss'], label='Val', color='orange', linestyle='--') axes[1].set_title('Class Loss') axes[1].set_xlabel('Epoch') axes[1].set_ylabel('Loss') axes[1].legend() axes[1].grid(True) # 图3：mAP axes[2].plot(epochs, results['metrics/mAP_0.5'], label='mAP@0.5', color='purple') axes[2].set_title('mAP@0.5') axes[2].set_xlabel('Epoch') axes[2].set_ylabel('mAP') axes[2].legend() axes[2].grid(True) plt.tight_layout() plt.savefig("train_curve.png", dpi=300, bbox_inches='tight') plt.show() # 运行后生成train_curve.png，答辩时直接展示这张图说明训练健康性

4. 系统集成与CLI工具开发：一个命令完成检测、存库、生成报告的全自动化流程

毕设答辩最怕“现场演示失败”。本方案将所有能力封装为detector_cli.py，支持--help查看完整参数，并内置异常捕获与友好提示。它不是简单调用model.predict()，而是构建了完整的业务流水线：图像预处理→模型推理→结果解析→数据库写入→PDF报告生成。每个环节失败都有明确错误码与恢复建议，杜绝“黑匣子”式崩溃。

4.1 CLI核心命令设计：为什么参数要细到--conf 0.45而不是写死0.5？

导师常问“置信度过滤怎么设的？”，若你答“代码里写死0.5”，会被质疑鲁棒性。本方案所有可调参数均暴露为CLI选项，强制你在README.md中记录实验对比（如--conf 0.3召回率高但误检多，--conf 0.6精度高但漏检多）。关键参数设计：

主程序入口（detector_cli.py）：

import argparse import sys from pathlib import Path from yolo_models.factory import get_detector from db_manager import DBManager from report_generator import generate_pdf_report from utils.logger import setup_logger def main(): parser = argparse.ArgumentParser(description="YOLO垃圾分类检测CLI工具") parser.add_argument("--input_dir", type=str, required=True, help="输入图片目录路径") parser.add_argument("--output_dir", type=str, default="runs/detect", help="输出目录") parser.add_argument("--model_version", type=str, default="v5", choices=["v5","v7","v8"], help="YOLO版本") parser.add_argument("--weights", type=str, default=None, help="自定义权重路径，为空则用默认") parser.add_argument("--conf", type=float, default=0.45, help="置信度阈值") parser.add_argument("--iou", type=float, default=0.5, help="NMS IOU阈值") parser.add_argument("--imgsz", type=int, default=640, help="输入尺寸") parser.add_argument("--device", type=str, default="cpu", help="设备，如'cpu'、'0'、'0,1'") parser.add_argument("--db_save", action="store_true", help="是否写入MySQL数据库") parser.add_argument("--save_txt", action="store_true", help="是否保存YOLO格式txt") parser.add_argument("--save_pdf", action="store_true", help="是否生成PDF报告") args = parser.parse_args() # 初始化日志 logger = setup_logger("detector_cli", f"{args.output_dir}/detect.log") logger.info(f"启动检测，参数：{vars(args)}") try: # 1. 加载模型 detector = get_detector(args.model_version) weights = args.weights or f"yolo_models/{args.model_version}/weights/best.pt" model = detector.load_model(weights) logger.info(f"模型加载成功：{weights}") # 2. 批量检测 results = detector.predict_batch( image_dir=args.input_dir, conf_thres=args.conf, iou_thres=args.iou, imgsz=args.imgsz, device=args.device ) # 3. 结果处理 output_dir = Path(args.output_dir) output_dir.mkdir(exist_ok=True) if args.save_txt: save_yolo_txt(results, output_dir / "labels") if args.db_save: db = DBManager() db.bulk_insert_detection(results) logger.info(f"写入数据库 {len(results)} 条记录") if args.save_pdf: generate_pdf_report(results, output_dir / "report.pdf") logger.info("PDF报告生成完成") logger.info("检测完成 ✅") except Exception as e: logger.error(f"检测失败 ❌：{str(e)}", exc_info=True) sys.exit(1) if __name__ == "__main__": main()

提示：exc_info=True确保异常堆栈写入日志，答辩时若出错，直接打开runs/detect/detect.log就能定位到第几行——比对着终端滚动日志找错误快10倍。

4.2 PDF报告生成：如何让导师一眼看懂检测效果？

答辩时不能只说“检测准确”，要可视化证明。本方案report_generator.py生成的PDF包含三页：

• 第1页：概览统计—— 饼图显示4大类占比（可回收/有害/厨余/其他），柱状图显示Top5子类数量；
• 第2页：典型检测图—— 自动选取置信度最高、最低、居中的各1张图，叠加检测框与类别标签；
• 第3页：详细日志表—— 表格列出每张图的图片名、检测类别、置信度、坐标、检测时间，支持Ctrl+F搜索。

生成逻辑（report_generator.py）：

def generate_pdf_report(detection_results: List[Dict], pdf_path: Path): """生成三页PDF报告""" doc = SimpleDocTemplate(str(pdf_path), pagesize=A4) styles = getSampleStyleSheet() story = [] # 第1页：统计图表 story.append(Paragraph("📊 检测结果统计", styles['Title'])) story.append(Spacer(1, 12)) # 分类统计（按garbage_category.code聚合） category_count = {} for r in detection_results: code = r['category_code'] # 如'0101' category_count[code] = category_count.get(code, 0) + 1 # 绘制饼图 pie_data = list(category_count.values()) pie_labels = [get_category_name(c) for c in category_count.keys()] # 从DB查名称 pie = Pie(width=400, height=400, data=pie_data, labels=pie_labels) drawing = Drawing(450, 450) drawing.add(pie) story.append(drawing) # 第2页：检测图示例 story.append(PageBreak()) story.append(Paragraph("🖼️ 典型检测效果", styles['Title'])) story.append(Spacer(1, 12)) # 取置信度最高/最低/中间的图 sorted_results = sorted(detection_results, key=lambda x: x['confidence']) examples = [sorted_results[-1], sorted_results[0], sorted_results[len(sorted_results)//2]] for i, r in enumerate(examples): img_with_box = draw_bbox_on_image(r['image_path'], r['bbox'], r['category_name'], r['confidence']) img_path = f"temp_example_{i}.png" cv2.imwrite(img_path, img_with_box) img = Image(img_path, width=400, height=300) story.append(img) story.append(Paragraph(f"图{i+1}：{r['category_name']}（置信度{r['confidence']:.3f}）", styles['Normal'])) story.append(Spacer(1, 12)) # 第3页：详细日志 story.append(PageBreak()) story.append(Paragraph("📋 详细检测日志", styles['Title'])) story.append(Spacer(1, 12)) # 构建表格数据 table_data = [['图片名', '类别', '置信度', '坐标(x1,y1,x2,y2)', '时间']] for r in detection_results: bbox_str = f"{r['bbox'][0]:.2f},{r['bbox'][1]:.2f},{r['bbox'][2]:.2f},{r['bbox'][3]:.2f}" table_data.append([ r['image_name'], r['category_name'], f"{r['confidence']:.3f}", bbox_str, r['detect_time'].strftime('%Y-%m-%d %H:%M:%S') ]) table = Table(table_data, colWidths=[120,100,80,150,120]) table.setStyle(TableStyle([ ('BACKGROUND', (0,0), (-1,0), colors.grey), ('TEXTCOLOR', (0,0), (-1,0), colors.whitesmoke), ('ALIGN', (0,0), (-1,-1), 'CENTER'), ('FONTNAME', (0,0), (-1,0), 'Helvetica-Bold'), ('FONTSIZE', (0,0), (-1,0), 10), ('BOTTOMPADDING', (0,0), (-1,0), 12), ('BACKGROUND', (0,1), (-1,-1), colors.beige), ('GRID', (0,0), (-1,-1), 1, colors.black) ])) story.append(table) doc.build(story)

注意：draw_bbox_on_image函数必须用cv2.rectangle而非plt.imshow，因为后者生成的图含坐标轴，答辩投影时显得业余。我们实测过，用cv2画框的图在教室投影仪上清晰度高30%。

5. 常见问题排查：毕设答辩前必须验证的5个致命陷阱

这5个问题占毕设答辩失败案例的73%。它们不报错，但会让检测结果“看起来不对”——比如框总偏右、同一张图两次检测结果不同、数据库里类别ID全是0。以下是现象、原因、解决方案的精准定位，按顺序逐条验证，10分钟内可排除90%隐形故障。

5.1 现象：检测框整体向右下方偏移10-20像素，且偏移量固定

原因：letterbox函数中dw, dh计算错误，或cv2.copyMakeBorder的top/bottom/left/right参数传反。YOLO输出的是归一化坐标（0~1），但letterbox填充的黑边未在反算时扣除，导致坐标映射到原图时基准点偏移。

解决：检查letterbox返回的(dw, dh)是否被正确用于坐标反算。在detector_cli.py中找到坐标转换段：

# ✅ 正确写法：必须用letterbox返回的(dw, dh)反推 x1 <p> <a href="https://download.csdn.net/download/caofeng891102/92189664" style="color:#ec7500;font-size:14px;"> 本文还有配套的精品资源，点击获取 </a> <img alt="menu-r.4af5f7ec.gif" src="https://csdnimg.cn/release/wenkucmsfe/public/img/menu-r.4af5f7ec.gif" style="width:16px;margin-left:4px;vertical-align:text-bottom;cursor:text;"> </p>