# mds1024

**Repository Path**: jamesray0713/mds1024

## Basic Information

- **Project Name**: mds1024
- **Description**: Mangrove Detection System
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-19
- **Last Updated**: 2025-11-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# MDS - Mangrove Detection System

**🌴 红树林智能监测工具 🌴**

基于 YOLO 的高性能正射影像目标检测系统

[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/)
[![Ultralytics](https://img.shields.io/badge/Ultralytics-8.3.228-green.svg)](https://github.com/ultralytics/ultralytics)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20WSL2%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)]()

</div>

---

## 📖 项目简介

MDS (Mangrove Detection System) 是一个专业的红树林正射影像智能检测系统，提供从数据准备、模型训练到推理部署的完整工作流，可实现红树植株的识别与统计、密度计算、树种识别、冠幅计算等功能。

**🎯 完全跨平台支持** - 一套代码，在 Windows、WSL2、macOS、Ubuntu/Linux 上无缝运行！

### ✨ 主要特性

- 🚀 **交互式命令行** - 基于 questionary 和 rich 的现代化 CLI，操作简单直观
- 🖼️ **大图切片推理** - 支持 TIFF/GeoTIFF 大图自动切片，支持自适应切片尺寸计算
- 🎯 **高精度检测** - 基于 YOLO11/12 的 SOTA 模型，支持 SAHI 切片辅助推理
- 🔄 **完整训练流程** - 自动数据转换、切片、增强、训练、验证
- 🗺️ **矢量边界过滤** - 支持 SHP/KML 矢量边界，精确框定推理区域
- 🪟 **智能平台适配** - 自动检测运行环境，路径转换和并行优化全自动
- ⚡ **高性能并行** - 多平台并行拷贝加速（GNU Parallel/PowerShell/xargs/Python多线程）
- 📊 **实验追踪** - 集成 Comet.ml，记录训练过程和指标
- 🎨 **结果可视化** - 自动生成检测结果可视化图和统计报告

---

## 🚀 快速开始

### 🔧 环境要求

| 组件 | 要求 | 说明 |
|------|------|------|
| **操作系统** | Windows 10/11, WSL2, macOS, Ubuntu 20.04+ | 全平台支持 |
| **Python** | 3.12+ | 必需 |
| **GPU（可选）** | NVIDIA GPU + CUDA 11.8+ | 推荐用于加速 |
| **内存** | 8GB+ | 推荐16GB+ |

### 📥 安装

> **详细安装指南**: 参见 [INSTALL_GUIDE.md](docs/INSTALL_GUIDE.md)

#### 方法1: 快速安装（通用）

```bash
# 1. 克隆项目
git clone https://gitee.com/jamesray0713/mds1024.git
cd mds1024

# 2. 创建虚拟环境
python3.12 -m venv .venv

# 3. 激活虚拟环境
# Linux/macOS/WSL:
source .venv/bin/activate
# Windows:
.\.venv\Scripts\Activate.ps1

# 4. 安装PyTorch（根据你的平台选择）
# GPU版本（推荐）:
pip install torch==2.9.1 torchvision --index-url https://download.pytorch.org/whl/cu121
# CPU版本:
pip install torch==2.9.1 torchvision -i https://pypi.tuna.tsinghua.edu.cn/simple

# 非macOS
pip install gdal
# macos: 先装系统级gdal，再用pip装
brew install gdal   # 默认3.12.0
pip install gdal==3.12.0.post1

# 4. 安装依赖
pip install -r requirements.txt

# 6. 测试安装
python test_cross_platform.py
```

#### 方法2: 一键安装脚本（即将推出）

```bash
# Linux/macOS/WSL
bash install.sh

# Windows
.\install.ps1
```

### ✅ 验证安装

运行跨平台兼容性测试：
```bash
python test/test_cross_platform.py
```

**预期输出**：
- ✓ 平台检测成功
- ✓ 路径转换测试通过
- ✓ 并行拷贝测试通过
- ✓ 核心模块导入成功
- ✓ GPU可用（如果有NVIDIA GPU）

---

## 🎮 使用方法

### 1. 交互式界面（推荐）
```bash
python3 -m venv .venv
source .venv/bin/activate  # Linux/Mac
# 或
.venv\Scripts\activate  # Windows
```

3. **安装依赖**

使用 pip:
```bash
pip install -r requirements.txt
```

或使用 Poetry:
```bash
poetry install
```

---

## 💻 使用方法

### 交互式命令行 (推荐)

启动交互式界面，按提示操作：

```bash
python scripts/interactive_cli.py
```

功能菜单：
- 📷 **推理检测** - 对图像/TIFF 进行目标检测
- 🎓 **训练模型** - 训练自定义检测模型
- 📐 **切片尺寸测算** - 计算最优切片尺寸
- ⚙️ **配置管理** - 查看和修改配置

### 命令行直接调用

**推理检测：**
```bash
python scripts/infer_cli.py \
    --image_path /path/to/image \
    --model_path /path/to/model.pt \
    --output_dir ./results
```

**训练模型：**
```bash
python scripts/train_cli.py \
    --data_path /path/to/dataset \
    --epochs 100 \
    --imgsz 640
```

---

## 📁 系统架构

### 项目结构
```bash
mds1024/
├── config/                 # 配置文件
│   └── mangrove.yaml      # 主配置文件
├── core/                   # 核心模块
│   ├── config.py          # 配置管理
│   └── logger.py          # 日志管理
├── infer/                  # 推理模块
│   ├── predictor.py       # 主推理器
│   ├── tiff_slicer.py     # TIFF 切片
│   ├── adaptive_slice.py  # 自适应切片计算
│   └── postprocessor.py   # 后处理
├── train/                  # 训练模块
│   ├── trainer.py         # 训练器
│   ├── data_loader.py     # 数据加载
│   └── slicer.py          # 数据切片
├── task_classify/          # 分类子模块
│   └── mds_classifier/    # 红树林分类器
├── utils/                  # 工具函数
│   ├── path_utils.py      # 路径处理
│   ├── gis.py             # 地理信息处理
│   └── progress.py        # 进度条
├── scripts/                # 脚本入口
│   ├── interactive_cli.py # 交互式界面
│   ├── infer_cli.py       # 推理脚本
│   └── train_cli.py       # 训练脚本
├── requirements.txt        # 依赖列表
└── pyproject.toml         # Poetry 配置
```

### 缓存架构

缓存目录集中存放项目运行时所有的`中间产物`，如切割后待推理的图像、日志、需要生成而用户未主动指定路径的文件……  
当项目首次运行，它将创建于用户`家目录`.

```bash
~/.cache_MDS
├── submodule_cls                       # 子模块`task_classify`的缓存根目录
│   └── infer
├── datasets
│   ├── infer                           # 推理数据集缓存
│   │   ├── infer-pre                   # 推理前可能先切几十个小片，用于计算自适应的“裁剪尺寸”
│   │   └── infer-[date]-[task_name]
│   ├── train                           # 训练数据集缓存
│   │   ├── _sliced                     # 训练前可能切片。
│   │   └── train-[date]-[task_name]
│   │         ├── autosplit_train.txt
│   │         ├── autosplit_val.txt
│   │         ├── classes.txt
│   │         ├── data.yaml
│   │         ├── images/
│   │         ├── labels/
│   │         └── labels.cache
│   └── trouble/
├── draw/
├── logs
│   └── infer-[date]-[task_name].log
├── middleware
│   └── train                           # 训练过程产生的缓存
├── models_det
│   └── m03-yolo12x.pt
├── models_cls\
│   └── m03-yolo11l-7cls.pt     
├── results
│   ├── infer
│   │   └── infer-[date]-[task_name]/
│   └── train
│       └── train-[date]-[task_name]/
└── tmp_data                            # 重要的老文件，非必要别删
```

---

## ⚙️ 配置说明

主配置文件位于 `config/mangrove.yaml`，包含以下主要配置：

### 基础配置
```yaml
cache_dir: ~/.cache_MDS         # 缓存根目录
log_level: INFO                 # 日志级别
```

### 推理配置
```yaml
inference:
  model_path: auto              # 模型路径 (auto 自动下载 SOTA 模型)
  conf_threshold: 0.25          # 置信度阈值
  iou_threshold: 0.45           # NMS IoU 阈值
  slice:
    enable: true                # 是否启用切片推理
    slice_size: 640             # 切片尺寸
    overlap_ratio: 0.2          # 重叠比例
    cal_adaptive_slice:
      enable: false             # 是否启用自适应切片计算
```

### 训练配置
```yaml
training:
  epochs: 100
  batch_size: 16
  imgsz: 640
  optimizer: AdamW
  lr0: 0.001
```

### 自定义配置

通过交互式界面的 "配置管理" 功能可以查看和修改配置。

---

## 🎯 使用场景

### 场景 1: 大幅正射影像检测

```bash
# 启动交互式界面
python scripts/interactive_cli.py

# 选择: 推理检测
# 输入: D:\data\satellite\image.tif  (Windows路径自动转换)
# 启用: 自适应切片尺寸计算
# 结果: 自动保存至 ~/.cache_MDS/results/infer/
```

### 场景 2: 使用矢量边界精确检测

```bash
# 在交互界面中:
# - 选择推理检测
# - 输入图像路径
# - 启用矢量边界过滤
# - 输入 shp/kml 文件路径
# 系统将仅在矢量边界范围内进行检测
```

### 场景 3: 自定义切片尺寸

```bash
# 在推理高级选项中:
# - 不启用自适应切片
# - 选择自定义切片尺寸
# - 输入: 640,1280  (多尺度推理)
```

---

## 🔧 常见问题

### Q1: 如何切换 GPU/CPU？
在配置文件中修改 `device` 字段，或在训练/推理时通过参数指定。

### Q2: 支持哪些图像格式？
支持常见格式：JPG, PNG, BMP, TIFF, GeoTIFF 等。

### Q3: Windows 路径无法识别？
项目已支持自动转换 Windows 路径 (WSL环境)，直接粘贴 `D:\path\to\file` 即可。

### Q4: 内存不足怎么办？
- 减小 `batch_size`
- 减小 `slice_size`
- 关闭自适应切片计算

### Q5: 如何清理缓存？
手动删除 `~/.cache_MDS/datasets/infer/infer-pre` 和 `_sliced` 目录。

---

## 📊 性能优化建议

1. **GPU 加速**: 确保安装了 CUDA 和 cuDNN
2. **多尺度推理**: 使用自定义切片尺寸 (640,960,1280) 提高检测率
3. **自适应切片**: 对于不同分辨率的图像，启用自适应切片计算
4. **批量处理**: 将多张图像放在同一目录下批量推理
5. **SAHI 增强**: 对小目标密集场景效果显著

---

## 📝 开发路线图

- [x] 交互式命令行界面
- [x] TIFF 大图切片推理
- [x] 自适应切片尺寸计算
- [x] Windows 路径自动转换
- [x] 矢量边界过滤
- [ ] Web 界面支持
- [ ] Docker 容器化部署
- [ ] 模型自动优化工具
- [ ] 批量任务队列管理

---

## 👥 贡献者

**Guangzhou RenLan Tech.**

---

## 📄 许可证

MIT License

---

## 📧 联系方式

如有问题或建议，请通过以下方式联系：

- 📮 Email: hl1670704310@icloud.com
- 🐛 Issue: 在 GitHub 提交 Issue

---

<div align="center">

**Made with ❤️ by RenLan Tech**

⭐ 如果这个项目对你有帮助，请给个 Star！

</div>