开发文档

海洋漂浮垃圾检测系统开发文档

1. 项目概述

1.1 项目背景

随着海洋开发利用及沿海经济发展，海洋漂浮垃圾问题日益严重。塑料袋、渔网、泡沫、油污等漂浮物不仅破坏海洋生态系统，还影响航道安全、海水摄像及景观环境。目前，漂浮垃圾监测主要依赖人工巡查与船载摄像，不仅耗费巨大人力资源，还难以实现 实时、连续、广域覆盖。借助海面图像与无人机、近岸监控平台，构建自动化漂浮垃圾识别系统，是推动智慧海洋环境治理的重要方向。

1.2 项目目标

构建一个能够自动识别、定位和分类海面漂浮垃圾的软件系统。系统根据图像/视频输入 [1]，能够自动检测漂浮垃圾并标注位置、进行垃圾分类，并提供可视化的界面和数据统计功能，为海洋环保部门提供有效的决策支持工具。

1.3 主要目标

1、支持图像/视频输入

2、能够自动检测漂浮垃圾并标注位置；

3、能够分类不同垃圾类型；

4、能够对检测结果实现可视化与数据统计；

5、性能评估与误差分析

1.4 技术栈

  • 后端：Python
  • 深度学习框架：PyTorch
  • 目标检测模型：YOLO11
  • 图像处理库：OpenCV
  • Web 框架：FastAPI
  • 前端界面：React
  • 数据可视化：Matplotlib
  • 数据存储：MySQL

2. 系统架构与模块设计

2.1 系统总体架构

系统采用前后端分离的 B/S 架构，便于部署和访问。

flowchart TD %% 节点定义 A[前端展示层 （Web UI）] B[后端服务层 （FastAPI Server）] C[核心算法层 （Detection Model）] D[数据存储层 （MySQL）] %% 连接关系 A <-->|HTTP/HTTPS| B B <-->|API调用| C B <-->|数据持久化| D

2.2 模块详细设计

模块一：数据输入与预处理模块

  • 功能：
    • load_image(image_path): 加载单张图片。
    • load_video(video_path): 加载视频文件，并逐帧读取。
    • preprocess(frame): 对输入的图像帧进行预处理，如尺寸缩放、归一化、通道转换等，使其符合模型输入要求。
  • 输入： 图片/视频文件路径、RTSP 流地址等。
  • 输出： 标准化后的图像张量。

模块二：目标检测与分类模块

  • 功能：
    • detect(tensor): 调用已训练好的深度学习模型进行前向推理。
    • postprocess(raw_output): 对模型的原始输出进行后处理，包括非极大值抑制（NMS）过滤重叠框、根据置信度阈值筛选有效检测结果。
  • 核心： 预训练的 YOLO11 模型。我们将在其基础上，使用海洋垃圾数据集进行微调。
  • 输出： 一个包含以下信息的列表：[class_id, class_name, confidence, x_min, y_min, x_max, y_max]

模块三：结果可视化模块

  • 功能：
    • draw_boxes(image, detections): 在原始图像上绘制边界框。
    • add_labels(image, detections): 在边界框上方添加类别标签和置信度。
  • 输出： 标注好的图像或视频帧。

模块四：数据统计与存储模块

  • 功能：
    • save_detection_record(detections, timestamp, source): 将一次检测的结果（垃圾数量、类型、位置）连同时间戳和数据源存入数据库。
    • generate_statistics(time_range): 根据时间范围生成统计信息，如各类垃圾的数量、趋势图、热力图等。
  • 数据库表设计：
    • detection_history(id, timestamp, source, total_count)
    • garbage_details(id, detection_id, class_name, confidence, bbox_coordinates)

模块五：Web 服务与 API 接口模块

  • 功能： 提供 RESTful API 供前端调用。
    • POST /api/upload-image: 上传图片并进行检测。
    • POST /api/upload-video: 上传视频文件并进行处理。
    • GET /api/stream: 获取实时视频流的检测结果（可能采用 WebSocket）。
    • GET /api/statistics: 获取统计数据和图表。
  • 技术： Flask/FastAPI 框架。

模块六：用户界面模块

  • 提供文件上传界面。
  • 显示检测结果流。
  • 展示历史检测数据和统计图表。
  • 提供模型性能评估报告的可视化。

3. 项目实施计划

3.1 整体项目规划

  • 规划与设计（1 周）：专注于需求细化、技术方案确定和文档撰写，为后续开发奠定坚实基础。
  • Alpha 阶段（3 周），本阶段的主要目的是构建一个初步可以运行的软件，初步完成前端、后端，并实现前后端的关联。项目评审和反思。
  • Beta 阶段（2 周），本阶段的主要目的是修改 Alpha 阶段已经初步可以运行软件中的错误，同时对软件中不完善的部分进行优化。项目评审和反思。

3.2 Alpha 阶段

Alpha 阶段核心目标：构建一个最小可行产品（MVP），实现图片/视频上传、垃圾检测、结果展示与数据存储的完整闭环。

第一周：核心算法与数据处理模块开发

本周目标

完成核心检测算法的本地实现，确保模型能准确识别并定位垃圾，同时完成数据库设计。

主要任务
  1. YOLO11 模型集成与调试
  2. 数据预处理与后处理函数开发
  3. 数据库设计与搭建
详细执行步骤
  • 任务 1：核心检测模块开发 (3 天)
    • 模型加载： 编写 load_model() 函数，加载预训练的 YOLO11 模型。
    • 数据预处理： 编写 preprocess(image) 函数，负责图像的尺寸缩放、归一化、通道转换（BGR to RGB）等，将其转换为模型所需的输入张量。
    • 模型推理： 编写 detect(tensor) 函数，调用模型进行前向传播，获得原始预测结果。
    • 后处理： 编写 postprocess(raw_output) 函数，对原始输出进行非极大值抑制（NMS）过滤，并根据置信度阈值筛选出最终的有效检测框。输出标准化的结果列表，每个元素包含 [class_id, class_name, confidence, x_min, y_min, x_max, y_max]。
    • 功能验证： 编写一个主脚本 main.py，输入本地图片路径，运行上述流程，并调用 draw_boxes() 函数将检测结果可视化，保存为新的图片，用于直观验证。
  • 任务 2：数据库设计与实现 (2 天)
    • 设计表结构： 基于模块设计文档，在 MySQL 中创建两张核心表：
      • detection_history(id, timestamp, source_type, source_path, total_count)
      • garbage_details(id, detection_id, class_name, confidence, bbox_json)
    • 编写数据库操作类： 创建 database.py，封装数据库连接、插入检测记录、查询统计信息等函数。
  • 任务 3：简单数据统计功能 (1 天)
    • 在 database.py 中实现 get_statistics() 函数，执行 SQL 查询，返回按垃圾类别分类的计数统计（JSON 格式）。
本周核心产出物
  1. 可运行的检测脚本： 输入图片路径，能在本地输出带检测框的图片和检测结果 JSON。
  2. 配置文件和数据库： 可灵活调整参数的 config.yaml 和创建完毕的数据库表。
  3. 数据库操作模块： 可实现数据存储和基本统计查询的 database.py。

第二周：后端 API 服务开发

本周目标

构建稳健的 FastAPI 后端服务，提供完整的 RESTful API，并实现图片和视频的异步处理逻辑。

主要任务
  1. Web 服务器搭建与基础 API 实现
  2. 图片上传与检测 API 的完整实现
  3. 视频异步处理功能实现
  4. API 接口文档编写
详细执行步骤
  • 任务 1：Web 服务器与图片检测 API (1.5 天)
    • 创建 FastAPI 应用实例，配置静态文件目录、最大文件上传大小等。
    • 实现 POST /api/upload-image 接口：
      • 接收前端上传的图片文件。
      • 调用第一周完成的检测模块进行处理。
      • 将检测结果存入数据库。
      • 将标注后的图片保存到服务器，并将图片 URL 和检测结果 JSON 一并返回给前端。
  • 任务 2：视频检测 API 与异步处理 (2 天)
    • 实现 POST /api/upload-video 接口。由于视频处理耗时，必须采用异步策略：
      • 接口接收到视频后，立即启动一个异步任务（如使用 Celery+Redis），并返回一个 task_id。
      • 异步任务负责逐帧读取视频，对每一帧调用检测模块，并将处理后的帧合成新视频或生成结果序列。
      • 提供 GET /api/task-status/<task_id> 接口，供前端查询任务进度和最终结果。
  • 任务 3：数据查询 API (0.5 天)
    • 实现 GET /api/statistics 接口，调用 database.py 中的统计函数，返回历史数据统计。
  • 任务 4：后端优化与文档化 (1 天)
    • 增强鲁棒性： 为所有 API 添加全面的异常处理（如文件类型校验、模型加载失败、数据库异常等）。
    • 生成 API 文档： 使用 Swagger 或 OpenAPI 规范自动生成交互式 API 文档，便于前端开发和测试。
    • 单元测试： 为核心的 API 接口编写单元测试。
本周核心产出物
  1. 功能完整的后端服务： 可独立运行，提供图片、视频检测和数据统计 API。
  2. 清晰的 API 文档： 前端开发者可根据文档进行对接。
  3. 异步视频处理机制： 确保系统在处理长视频时不会阻塞请求。

第三周：前端开发与集成联调

本周目标

开发用户友好的 React 前端界面，并与后端 API 完成集成联调，形成可演示的完整系统。

主要任务
  1. React 项目初始化与组件开发
  2. 前后端集成联调
  3. Alpha 版本系统测试与评审准备
详细执行步骤

  • 任务 1：前端项目搭建与基础组件开发 (2 天)

    • 使用 Create-React-App 初始化项目。
    • 组件设计：
      • FileUploader：支持拖拽/选择文件的上传组件。
      • ResultDisplay：标签页或分栏布局，用于并排显示原图和处理后的图，并以表格列出检测结果详情。
      • StatisticsChart：使用 ECharts 或 Chart.js 绘制统计图表，展示历史数据。
      • VideoTaskMonitor：用于视频上传后，轮询任务状态并显示进度条。

  • 任务 2：前后端集成联调 (1.5 天)

    • 配置前端代理，解决跨域问题。
    • 在前端组件中调用后端 API：
      • FileUploader 调用 /api/upload-image 或 /api/upload-video。
      • 上传后，ResultDisplay 组件展示返回的结果图片和检测列表。
      • 页面加载时，StatisticsChart 组件调用 /api/statistics 获取数据。
    • 联调检查清单： 对以下场景进行完整测试：
      • 上传 JPG/PNG 图片功能正常。
      • 上传 MP4 视频，能正确轮询状态并显示最终结果。
      • 统计图表能正确展示。

  • 任务 3：系统集成测试与优化 (1 天)

    • 进行端到端（E2E）测试，模拟用户完整操作流程。

    • 优化前端加载状态和用户提示，提升用户体验。

    • 整理并记录测试过程中发现的所有 Bug 和问题。

  • 任务 4：Alpha 评审准备 (0.5 天)

    • 编写《Alpha 版本说明文档》，包括功能列表、已知问题、部署指南。

    • 准备演示脚本，确保在评审会议上能稳定、流畅地展示核心功能。

本周核心产出物
  1. 可交互的前端界面： 用户可通过浏览器完成所有核心操作。
  2. 集成完毕的 MVP 系统： 前端、后端、数据库协同工作的完整系统。
  3. Alpha 版本测试报告与演示材料： 为评审和下一阶段规划提供依据。
Alpha 阶段最终产出

通过以上三周的工作，我们将得到一个包含以下功能的最小可行产品（MVP）：

  • 功能：支持图片和视频上传、自动垃圾检测与分类、结果可视化展示、基础数据统计。
  • 代码：结构清晰、文档完整、经过测试的代码仓库。
  • 文档：部署文档、API 文档、已知问题列表。
  • 基础：为 Beta 阶段的性能优化、功能增强和错误修复奠定了坚实基础。

3.3 Beta 阶段

Beta 阶段目标： 修复 Alpha 版本的缺陷，提升系统性能、可靠性和易用性。

第 4 周：问题修复与性能优化

  • 任务 9：修复 Alpha 阶段发现的 Bug (2 天)

    • 根据评审反馈和测试结果，集中修复前端、后端和算法模块的缺陷（如界面错误、API 异常、模型误检/漏检等）。

  • 任务 10：模型优化与调参 (1.5 天)

    • 基于收集的测试结果进行误差分析，重点解决常见的误检和漏检问题。
    • 尝试调整模型置信度阈值、NMS 参数等。
    • 如果时间和数据允许，进行模型微调。

  • 任务 11：系统性能与用户体验优化 (1.5 天) 后端优化：

    • 实现简单的缓存机制（如缓存模型加载），优化视频处理速度。
    • 前端优化： 增加加载状态提示，优化界面交互和响应速度。
    • 代码优化： 重构冗余代码，增加错误处理和日志记录。

  • 周目标： 系统稳定性和检测准确性得到显著提升。

第 5 周：高级功能与最终交付

  • 任务 12：增强可视化与报表功能 (1.5 天)

    • 丰富数据统计图表，如按时间趋势图、垃圾分布热力图等。
    • 开发检测结果导出功能（如导出为 CSV 或 PDF 报告）。

  • 任务 13：系统加固与最终测试 (2 天)

    • 进行安全加固（如文件上传类型检查、API 基础防护）。
    • 编写部署文档和用户使用说明。
    • 进行全面的系统验收测试，包括压力测试和兼容性测试。

  • 任务 14：项目总结与 Beta 评审 (1.5 天)

    • 整理最终版代码、文档和项目总结报告。
    • 准备最终演示，展示 Alpha 到 Beta 阶段的改进。
    • 进行项目复盘，总结技术难点、收获与未来展望。

  • 周目标： 交付一个稳定、可用、功能完善的 Beta 版本，完成项目总结。

4. 性能评估与误差分析

4.1 评估指标

  • 精度指标：
    • mAP@0.5： 交并比 IoU 阈值为 0.5 时的平均精度，是目标检测的核心指标。
    • Precision（精确率）： 检测出的垃圾中，真正是垃圾的比例。
    • Recall（召回率）： 所有真实的垃圾中，被成功检测出来的比例。
    • F1-Score: 精确率和召回率的调和平均数。
  • 速度指标：
    • FPS： 模型每秒处理的帧数，关乎系统实时性。

4.2 误差分析

  • 常见误差类型：
    • 误检： 将海浪、飞鸟、阴影等误判为垃圾。
    • 漏检： 小目标垃圾、半淹没垃圾、与背景颜色相近的垃圾未被检测出。
    • 分类错误： 垃圾类型识别错误，如将塑料瓶识别为木材。
  • 分析方法：
    • 在验证集上运行模型，手动检查置信度低、分类错误的样本。
    • 根据分析结果，有针对性地补充训练数据（特别是困难样本），或进行数据增强（如调整亮度、对比度、添加模糊等）。

  1. 输入由老师提供 ↩︎

posted @ 2025-12-01 21:31  OUC-喇叭花  阅读(0)  评论(0)    收藏  举报