SAM2 优先的全局语义分割

这个项目实现一个无文本 prompt 的全局分割 pipeline：

输入图像
  -> OneFormer 生成 dense panoptic map，作为全像素兜底和 fallback 语义标签
  -> Florence-2 dense region caption 生成 box + label
  -> 用 Florence box + OneFormer coarse region 采样点，prompt SAM2 生成语义引导 mask
  -> 可选：用 SAM2 点/框 prompt 对区域边界二次 refine
  -> 输出 dense panoptic id map、互斥 masks、语义 tag overlay

核心保证：panoptic_id.png 中每个像素都有且只有一个 segment id。当前更稳的主线是 sam2-amg-merge：SAM2 先生成全局 masks，再用类别无关的 graph merge 合并小碎片，最后用 Florence-2/OneFormer 标注语义。

安装

本机推荐：

conda activate vipe310
cd global_semantic_segmentation
pip install -r requirements.txt

干净环境：

conda create -n sam2global python=3.10 -y
conda activate sam2global
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
pip install -r requirements.txt

SAM2 运行时可能提示可选 _C 扩展不可用。这个 warning 不会阻断普通推理，SAM2 官方安装说明也说明多数场景可以忽略。

RAM++ 首次运行会下载 ram_plus_swin_large_14m.pth，权重约 3GB。网络不稳定时可以手动下载后用 --ram-plus-checkpoint /path/to/ram_plus_swin_large_14m.pth 指定。

Florence-2 首次运行会从 Hugging Face 下载模型。默认使用 microsoft/Florence-2-large；调试时可用 --florence2-model microsoft/Florence-2-base。

算力与分辨率

当前测试图统一缩放到最长边约 900px：

• street_midtown_900.jpg：675 x 900，约 60.8 万 像素。
• indoor_office_900.jpg：900 x 598，约 53.8 万 像素。
• electrical_substation_900.jpg：640 x 480，约 30.7 万 像素。

当前推荐配置：

OneFormer large
+ SAM2.1 small
+ CLIP ViT-B/32 用于 mask graph merge
+ Florence-2-base 用于 tag

单张 900px 级别图片建议预留 12GB - 18GB 显存；24GB 单卡足够。当前机器上建议使用空闲卡：

--device cuda:0

高质量配置：

SAM2.1 large
+ Florence-2-large
+ OneFormer large

建议预留 20GB - 24GB+。如果图像更大、AMG mask 更多或 Florence-2 检测更多，可能 OOM。

OOM 时按这个顺序降级：

Florence-2-large -> Florence-2-base
SAM2.1-large -> SAM2.1-small
降低 --amg-points-per-side
降低 --amg-max-masks
缩小输入图像到最长边 900-1200px

主用法

推荐：SAM2 全局 mask + CLIP 小碎片合并：

python sam2_global_panoptic.py \
  --image /path/to/image.jpg \
  --output outputs/amg_merge_example \
  --coarse-source sam2-amg-merge \
  --sam2-model facebook/sam2.1-hiera-small \
  --amg-points-per-side 8 \
  --amg-max-masks 50 \
  --merge-min-area 800 \
  --merge-force-min-area 100 \
  --florence2-model microsoft/Florence-2-base

备选：Florence-2 box 引导 SAM2：

python sam2_global_panoptic.py \
  --image /path/to/image.jpg \
  --output outputs/guided_example \
  --coarse-source florence2-guided-sam2 \
  --florence2-model microsoft/Florence-2-base

轻量 Florence-2 guided SAM2 测试：

python sam2_global_panoptic.py \
  --image /path/to/image.jpg \
  --output outputs/florence2_check \
  --coarse-source florence2-guided-sam2 \
  --sam2-model facebook/sam2.1-hiera-small \
  --florence2-model microsoft/Florence-2-base \
  --guided-max-detections 20 \
  --disable-sam-refine

快速检查 OneFormer 兜底链路：

python sam2_global_panoptic.py \
  --image /path/to/image.jpg \
  --output outputs/oneformer_check \
  --coarse-source oneformer \
  --tagger oneformer \
  --disable-sam-refine

轻量 SAM2 测试：

python sam2_global_panoptic.py \
  --image /path/to/image.jpg \
  --output outputs/sam2_small_check \
  --sam2-model facebook/sam2.1-hiera-small \
  --amg-points-per-side 8 \
  --amg-max-masks 20 \
  --max-refine-segments 2 \
  --tagger oneformer

输出文件

• panoptic_id.png：dense segment-id 图。每个像素都有非零 id。
• segments.json：每个最终 segment 的结构化结果，包含 id、semantic_tag、tag_source、area、bbox_xywh、mask_path、refined_by_sam2 等。
• masks/*.png：从 panoptic_id.png 导出的互斥二值 mask。
• overlay.png：原图上的彩色分割 overlay。
• semantic_overlay.png：原图上的彩色分割 overlay，并在可见区域绘制语义 tag。

关键参数

• --coarse-source sam2-amg-merge|florence2-guided-sam2|sam2-amg|oneformer：推荐先试 sam2-amg-merge。florence2-guided-sam2 用 Florence box 引导 SAM2；sam2-amg 是未合并的 SAM2 自动 mask proposal 路线；oneformer 只建议用于兜底或调试。
• --sam2-model：默认 facebook/sam2.1-hiera-large。调试时建议用 facebook/sam2.1-hiera-small。
• --amg-points-per-side：SAM2 全图网格点密度。越大 mask 越多、越慢。
• --amg-max-masks：限制 SAM2 mask 数量，便于调试。0 表示不限制。
• --merge-min-area：小于该面积的区域尝试按 graph merge 合并。
• --merge-force-min-area：极小区域强制合并到接触邻居，避免 1 像素碎片。
• --merge-clip-thresh / --merge-score-thresh：控制合并保守程度，越高越不容易合并。
• --merge-containment-thresh：小区域被大区域近似包含时的合并阈值。
• --merge-containment-area-ratio：限制 containment merge 只处理相对较小的区域。
• --max-refine-segments：限制二次 SAM2 点/框 refine 的 segment 数量。0 表示 refine 所有满足面积要求的区域。
• --tagger florence2|ram-plus|oneformer：默认 florence2。Florence-2 用整图 dense region caption 给 mask 匹配 tag；RAM++ 生成开放世界候选 tags；OneFormer 只用闭集 fallback tag。
• --florence2-model：默认 microsoft/Florence-2-large。调试时可用 microsoft/Florence-2-base。
• --florence2-task：默认 <DENSE_REGION_CAPTION>，也可用 <OD>。
• --guided-max-detections：限制 Florence-2 检测框数量，便于调试。0 表示不限制。
• --guided-min-region-area：guided 分支保留区域的最小面积。
• --tagger-apply candidates-only|replace-semantic-tag：默认 candidates-only，即 semantic_tag 仍使用 OneFormer，RAM++ 写入 open_world_tags。如果想强制用 RAM++ 第一候选覆盖语义图，设为 replace-semantic-tag。
• --ram-plus-checkpoint：RAM++ 权重路径。未提供时自动从 Hugging Face 下载。
• --tagger-min-area：小区域直接使用 OneFormer fallback tag，避免 RAM++ 对极小 crop 误判。
• --min-label-area：小于该面积的区域不在 semantic_overlay.png 上绘制文字，避免文字糊成一片。

CLIP Proposal Baseline

sam2_clip_segment.py 保留为对比基线：给定 label set，用 CLIP 给 SAM2 proposal mask 打标签。

python sam2_clip_segment.py \
  --image /path/to/image.jpg \
  --labels "person,car,road,tree,building,sky" \
  --output outputs/proposal_clip

这个 baseline 不保证全像素覆盖，只适合做 proposal tagging 对比。

当前限制

默认 semantic_tag 来自 Florence-2 dense region caption 与 mask 的匹配；匹配不到时保留 OneFormer majority vote fallback。RAM++ 仍可写入 open_world_tags，但它是 image-level tagger，对小/碎 masked crop 容易误判，不建议作为默认最终 tag。