SAM3 Image Workbench (Standalone Deploy)

This module extracts the SAM3 image annotation workflow into an independently deployable workbench.

What it includes

• Single-image upload and task management
• Batch image upload queue
• SAM3 auto segmentation
• Manual segmentation via:
  • text prompt
  • point click prompt
  • box prompt
  • combined text + geometric prompt
• Editable element list (save/delete)
• Overlay and id-map asset generation

Module layout

• Backend entry: backend/sam3_workbench_app.py
• Backend module: backend/sam3_workbench/
  • app_factory.py
  • routes.py
  • service.py
• Frontend: sam3_workbench_frontend/

Requirements

cd backend
pip install -r requirements_sam3_workbench.txt

You also need SAM3 runtime dependencies and checkpoint:

• sam3 code available under project root (./sam3)
• SAM3_CKPT environment variable pointing to checkpoint file
• PyTorch installed for your runtime (CUDA or CPU)

One-click start (for non-technical users)

Place these assets in the project first:

• SAM3 source code in ./sam3
• model checkpoint in ./models/sam3.pt (or set SAM3_CKPT)

Then run one command:

./start_sam3_workbench.command

What this script does automatically:

• creates/reuses ./.venv
• installs backend Python dependencies if missing
• installs PyTorch automatically if missing
• installs frontend npm dependencies if missing
• builds frontend static files if missing (if prebuilt dist exists, npm can be skipped)
• validates sam3 source and checkpoint path
• starts the standalone server on http://127.0.0.1:5060

Optional environment variables:

• SAM3_CKPT=/absolute/path/to/sam3.pt
• SAM3_WORKBENCH_PORT=5060
• SAM3_WORKBENCH_AUTO_OPEN=0 (disable auto browser open)
• SAM3_WORKBENCH_FORCE_PIP_INSTALL=1
• SAM3_WORKBENCH_FORCE_NPM_INSTALL=1
• SAM3_WORKBENCH_FORCE_FRONTEND_BUILD=1

中文使用方法

1. 启动

确保以下内容已就位：

• ./sam3 目录下有可用的 SAM3 代码
• 模型权重存在：./models/sam3.pt（或通过 SAM3_CKPT 指定绝对路径）

执行一键启动：

./start_sam3_workbench.command

浏览器打开：http://127.0.0.1:5060

2. 批量上传 + 自动切换下一张

1. 在左侧 Task Intake 选择多张图片上传。
2. 保持 auto-next 勾选。
3. 点击 Auto Segment 或进行手动分割后，系统会自动跳转到队列中的下一张图。

说明：

• 顶部和主视图会显示 Queue 信息。
• 右侧显示批处理进度条（当前张数/总张数 + 百分比）。

3. 左右双视图

• 左侧视图：原图（Original）
• 右侧视图：mask 覆盖图（Mask Overlay）

用途：

• 左侧用于观察原始细节；
• 右侧用于看分割结果和交互点选位置；
• 两侧并排可以快速判断“分割是否偏移、是否漏分”。

4. 点选交互：新增对象 / 扩张对象

在 Point 模式下：

1. 点击 New Object，在右侧 mask 面板点一下：会创建新 object。
2. 在 Elements 列表点击某个对象的 Use，将其设为当前对象。
3. 继续在右侧点选：会把新预测区域并入该对象，实现“扩张”。
4. 需要新目标时，再次点击 New Object，重复以上流程。

提示：

• 可以配合文本 prompt 使用（例如 pine tree / bridge）。
• 每次点选都会触发一次手动分割并更新 overlay。

理论效果与预期

预期提升

• 批处理效率提升：上传后连续处理，减少手动切图操作。
• 标注一致性提升：同一对象可多次点选扩张，避免重复新建碎片对象。
• 校验速度提升：左右双视图对照更容易发现误分/漏分。

可能出现的现象（正常）

• 点选扩张后，对象轮廓会“跳变”或出现局部突变：
  • 原因是每次点选都是一次新的 SAM3 推理，再与旧 mask 合并。
• 复杂纹理（树叶、云雾、水墨晕染）可能产生多个小片段：
  • 可通过继续点选扩张，或在 Elements 中手动整理标签。
• 批量任务中个别图片推理较慢：
  • 与分辨率、显存/CPU性能、模型负载有关。

效果边界

• 本工作台是“交互式分割提效工具”，不是完全自动的零误差标注器。
• 对于高度抽象、低对比或遮挡严重区域，仍建议人工多次点选修正。

Run in development (frontend + backend)

Terminal 1:

./scripts/start_sam3_workbench_backend.sh

Terminal 2:

./scripts/start_sam3_workbench_frontend.sh

Open: http://127.0.0.1:5175

Run as standalone single process

./scripts/start_sam3_workbench_standalone.sh

Open: http://127.0.0.1:5060

Backend environment variables

• SAM3_WORKBENCH_HOST (default 0.0.0.0)
• SAM3_WORKBENCH_PORT (default 5060)
• SAM3_WORKBENCH_OUTPUT_ROOT (default ./outputs_sam3)
• SAM3_WORKBENCH_UPLOAD_ROOT (default ./uploads_sam3)
• SAM3_WORKBENCH_STATIC_DIR (default ./sam3_workbench_frontend/dist)
• SAM3_CKPT (default ./models/sam3.pt)
• SAM3_WORKBENCH_ENABLE_CORS (default true)

API

• GET /api/sam3/health
• POST /api/sam3/upload
• POST /api/sam3/upload_batch
• GET /api/sam3/task/{task_id}
• POST /api/sam3/auto/{task_id}
• POST /api/sam3/manual/{task_id}
• PUT /api/sam3/elements/{task_id}
• DELETE /api/sam3/element/{task_id}/{element_id}
• GET /api/sam3/file/{task_id}/{relative_path}

Gunicorn deploy example

cd backend
pip install -r requirements_sam3_workbench.txt
SAM3_CKPT=/abs/path/to/sam3.pt \
SAM3_WORKBENCH_OUTPUT_ROOT=/data/sam3_outputs \
SAM3_WORKBENCH_UPLOAD_ROOT=/data/sam3_uploads \
gunicorn -w 2 -b 0.0.0.0:5060 sam3_workbench_app:app

Before deploying static frontend from backend:

./scripts/build_sam3_workbench_frontend.sh

Then set:

export SAM3_WORKBENCH_STATIC_DIR=/abs/path/to/sam3_workbench_frontend/dist