SAMLabeler-MNN

description: 使用 MobileSAM + MNN + Qt 的轻量级语义分割与实例分割交互标注工具。

topics: [mobile-sam, mnn, qt, opencv, annotation-tool, semantic-segmentation, instance-segmentation]

基于 MobileSAM、MNN 与 Qt 的本地交互标注工具，面向语义分割和实例分割数据制作。

Demo

当前能力

• 文件夹级图片浏览，图像目录与标注目录相互独立。
• 多类别管理、自定义颜色及彩色 mask 叠加预览。
• 正点、负点和矩形框提示；同一实例可持续追加提示进行 refinement。
• 按类别顺序创建、确认、重新编辑和删除目标实例，实例 ID 在图片内保持稳定。
• 将模型 mask 转为 Polygon，支持拖动、插入和删除顶点，以及多外轮廓和孔洞。
• 缩放、平移、适应窗口和原始比例查看，交互坐标始终映射到原图。
• 保存并恢复类别、语义 mask、实例 mask、提示、decoder feedback 和 Polygon 状态。
• 保留独立于 Qt 的 C++/OpenCV/MNN 后端及原 OpenCV 交互示例。

依赖

• C++11 编译器、CMake 3.10+、Ninja（推荐）
• Qt 5.15（Core、Gui、Widgets）
• OpenCV 4（core、imgproc、imgcodecs、highgui）
• MNN 3.3.x 头文件与 libMNN.so
• MobileSAM vit_t encoder/decoder MNN 模型

构建

cmake -S . -B build-qt -G Ninja \
  -DMNN_ROOT=/path/to/MNN \
  -DMNN_LIBRARY=/path/to/MNN/build/libMNN.so
cmake --build build-qt
ctest --test-dir build-qt --output-on-failure

运行

从仓库根目录运行打包模型：

./build-qt/SAMLabeler-MNN

或显式指定模型：

./build-qt/SAMLabeler-MNN \
  /path/to/mobile_sam_encoder.mnn \
  /path/to/mobile_sam_decoder.mnn

Linux 构建会为 MNN 动态库目录设置 RUNPATH；迁移运行目录时也可设置 LD_LIBRARY_PATH。

基本流程

1. 分别选择图像文件夹和标注文件夹；支持 PNG、JPG/JPEG、BMP、TIF/TIFF。
2. 添加类别并设置颜色，选择正点、负点或矩形框提示目标。
3. 继续追加提示修正 mask；需要时切换到 Polygon 模式精调边界。
4. 点击“确认当前目标”锁定实例，并继续标注同类别的下一个目标。
5. 保存项目；未确认草稿会保留，但不会进入正式语义/实例 mask。

打包 decoder 固定支持 8 个 prompt 槽位：一个点占 1 个槽位，一个矩形框占 2 个 槽位。Ctrl + 滚轮缩放，鼠标中键拖动平移。

项目数据

<annotation-directory>/
├── project.json             # 项目清单与图片/实例映射
├── categories.json          # 类别 ID、名称与颜色
├── masks/*.png              # 16 位语义 mask：像素值为类别 ID
├── instances/*.png          # 16 位实例 mask：像素值为图片内实例 ID
├── instances/*.json         # 实例与类别映射
└── states/g<generation>/    # 可恢复的提示、feedback 与 Polygon 状态

每次保存创建新的 generation，并在状态写入完成后原子更新项目清单。旧版类别级项目 和 legacy categories.json + masks/ 目录可自动导入；正式导出仅包含人工确认的实例。

Roadmap（尚未实现）

• Pascal VOC 导入与导出。
• COCO 导入与导出。
• YOLO Segmentation 导入与导出。
• 其他常用数据集格式及格式转换工具。
• 更完整的快捷键、撤销/重做和批量工作流。

说明

• 当前模型契约针对静态 8 槽位 MobileSAM vit_t MNN 模型，默认使用 CPU、4 线程。
• 大图会缩放到模型输入尺寸推理，边界质量受模型、提示和图像内容影响，重要数据应 由人工检查并确认。
• 项目本身及第三方依赖分别遵循各自许可证；MobileSAM 模型权重的获取和使用也应 遵循其原始许可。仓库未明确授予的模型或数据权利不因本 README 而改变。