SenseMark

遥感影像高性能切片与全栈自动标注系统

---

项目简介

SenseMark 将 超大 GeoTIFF 滑动窗口切片、YOLOv8 AI 预标注、VOC/COCO 格式导出 集成进一个带 Web 管理界面的完整系统，专为遥感目标检测任务的前处理环节设计。

核心价值：解决「大图没法直接喂模型」和「手工标注太慢」两个痛点。

---

功能特性

• 滑动窗口切片 — 重叠窗口、多进程并行、自动空白过滤、单波段→3 通道、多数据类型归一化
• AI 预标注 — YOLOv8 目标检测推理，支持 CPU / CUDA GPU
• 多格式导出 — PASCAL VOC XML + MS COCO JSON
• Web 管理界面 — 项目 CRUD、图像注册、一键流水线执行、实时进度（SSE）、检测结果可视化
• 系统文件对话框 — 前后端联动，浏览器内拉起原生文件选择器
• REST API — FastAPI + SQLite，19 个端点
• 统一 CLI — pipeline 一键执行、分步命令、服务启动

---

快速开始

环境要求

• Python 3.10+
• 推荐 NVIDIA GPU（CUDA），CPU 也可运行

安装

git clone https://github.com/<你的用户名>/SenseMark.git
cd SenseMark

# 创建虚拟环境
python -m venv venv
source venv/Scripts/activate   # Windows
# source venv/bin/activate     # macOS / Linux

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

一行启动

python -m sensemark.main serve

打开 http://localhost:8000 ，在 Web 界面完成全部操作。

CLI 使用

# 一键流水线
python -m sensemark.main pipeline 影像.tif -o tiles/ -m yolov8n.pt

# 只切片
python -m sensemark.main slice 影像.tif -o tiles/ -s 512 --overlap 64

# 只标注
python -m sensemark.main annotate tiles/ -m yolov8n.pt -o detections.json

# 只转换
python -m sensemark.main convert detections.json

# 启动服务
python -m sensemark.main serve

---

项目结构

SenseMark/
├── sensemark/               # 后端 Python 包
│   ├── __init__.py
│   ├── slicer.py            # 滑动窗口切片引擎
│   ├── annotator.py         # YOLOv8 推理模块
│   ├── converter.py         # VOC / COCO 格式转换
│   ├── database.py          # SQLite 数据访问层
│   ├── api.py               # FastAPI 应用（19 个端点）
│   └── main.py              # CLI 统一入口
├── frontend/                # Web 前端
│   ├── index.html           # 单页应用
│   ├── js/
│   │   └── app.js           # 前端逻辑（SSE、可视化）
│   └── css/
│       └── style.css        # 样式
├── tests/                   # 测试（23 个，pytest）
├── docs/                    # 架构 & 技术栈文档
├── requirements.txt
├── .gitignore
└── README.md

---

API 端点

方法	路径	说明
GET	/	Web 管理界面
GET	/health	健康检查
GET	/system/info	CUDA / GPU 信息
POST	/projects	创建项目
GET	/projects	项目列表
GET	/projects/{id}	项目详情（含图像列表）
POST	/images	注册图像
GET	/images	图像列表
POST	/tile-tasks	创建切片任务
PUT	/tile-tasks/{id}/complete	完成切片任务
POST	/tile-tasks/{id}/tiles	批量添加瓦片
POST	/annotation-tasks	创建标注任务
PUT	/annotation-tasks/{id}/complete	完成标注任务
POST	/annotation-tasks/{id}/detections	批量添加检测结果
POST	/pipeline/run	同步流水线
POST	/pipeline/run-stream	SSE 实时流水线（Web 界面用）
POST	/api/file-picker	系统原生文件对话框
GET	/api/tile-image	提供瓦片 PNG
GET	/api/detections	读取检测结果 JSON

---

数据流

GeoTIFF 大图
  ──[slicer]──> 512×512 PNG 瓦片
  ──[annotator]──> YOLO 检测结果 (JSON)
  ──[converter]──> VOC XML + COCO JSON
  ──[api]──> SQLite 持久化 + Web SSE 进度 + Canvas 可视化

---

技术栈

层	技术	说明
后端框架	FastAPI + uvicorn	异步 REST API、SSE 流
AI 推理	ultralytics YOLOv8	PyTorch 后端、CUDA 加速
影像处理	rasterio	窗口读取、地理元数据处理
数据库	SQLite (WAL 模式)	零配置、外键级联
前端	原生 HTML/CSS/JS	零构建工具、零框架依赖
测试	pytest + httpx	23 个用例

详见 docs/TECH_STACK.md

---

推荐数据源

来源	分辨率	说明
OpenAerialMap	5-20 cm	免费高分航拍，最推荐
USGS EarthExplorer	1 m (NAIP)	美国农业影像
学校无人机	5-20 cm	最实际的来源

YOLOv8n 使用 COCO 预训练权重（地面视角），遥感俯视影像检测效果有限。建议使用高分航拍影像，或替换为遥感专用模型以获得更好的检测结果。

---

已知局限

• 模型适配：COCO 预训练 YOLO 对遥感目标检测效果有限，可替换 DOTA 等遥感数据集权重
• 大文件优化：10 GB+ 影像的内存管理可进一步改进
• 并发：当前为单用户设计，后台任务队列留待后续

---

License

MIT