Parcelify

基于 SAM2 的实例掩膜后处理流水线：从 SAM2AutomaticMaskGenerator 输出的重叠实例掩膜出发，完成 去重叠、过滤/补洞、碎片合并、轮廓正交化，并可选 矢量化导出（GeoJSON/Shapefile）。

安装/环境

当前仓库未提供 pyproject.toml/setup.py，推荐以“源码方式”使用：把 src/ 加入 PYTHONPATH。

PowerShell 示例：

cd Parcelify
$env:PYTHONPATH = "$(Get-Location)\src"
python -c "import parcelify; print(parcelify.__all__ if hasattr(parcelify,'__all__') else 'ok')"

依赖由代码直接导入决定，常用包括：numpy, opencv-python, torch, matplotlib。如需矢量化，额外需要：geopandas, shapely。

目录说明

• checkpoints/: SAM2 权重（仓库内已有 sam2.1_hiera_tiny.pt）
• configs/: SAM2 配置（例如 configs/sam2.1/sam2.1_hiera_t.yaml）
• src/parcelify/: 后处理流水线组件
• src/sam2/: SAM2 推理所需代码（供 SAMMaskEngine 调用）

最小用法（端到端流水线）

下面示例展示从一张 RGB 图片得到最终规则化掩膜，并可选导出 GeoJSON/Shapefile。

import numpy as np
from PIL import Image

from parcelify import (
    SAMMaskEngine,
    MaskOverlapResolver,
    MaskRefiner,
    ParcelMerger,
    MaskRegularizer,
    MaskVectorizer,
)

# 1) 读入 RGB 图像 (H, W, 3)
image_np = np.array(Image.open("your_image.png").convert("RGB"))

# 2) SAM2 自动提取实例掩膜: (N, H, W) uint8，0/1
engine = SAMMaskEngine(
    model_cfg="configs/sam2.1/sam2.1_hiera_t.yaml",
    checkpoint_path="checkpoints/sam2.1_hiera_tiny.pt",
    device="cuda",  # 没有 GPU 可改为 "cpu"
)
raw_masks = engine.extract(image_np, show_preview=False)

# 3) 重叠消解：把重叠实例变成互斥实例
resolver = MaskOverlapResolver(min_fragment_area=15, sort_reverse=True)
_, clean_masks = resolver.resolve(raw_masks, show_preview=False)

# 4) 掩膜净化：去小碎片/飞地，可选填洞
refiner = MaskRefiner(min_area=15, keep_largest_only=True, fill_holes=True)
refined_masks = refiner.refine(clean_masks, show_preview=False)

# 5) 碎片合并：把狭长碎块同化到相邻大块
merger = ParcelMerger(max_area=800, ratio_threshold=0.1)
merged_masks = merger.merge(refined_masks)

# 6) 轮廓正则化：平滑 + 正交化（含 45° 斜边容忍）
regularizer = MaskRegularizer(min_area=100, epsilon_ratio=0.01, tolerance_45=0.2)
final_masks = regularizer.regularize(merged_masks, out_npy_path="run/final_masks.npy", visualize=False)

# 7) 可选：矢量化导出（不传 transform 则按像素坐标输出）
vectorizer = MaskVectorizer(crs="EPSG:4326")
gdf = vectorizer.vectorize(
    masks=final_masks,
    transform=None,  # 或 (top_left_x, top_left_y, pixel_width, pixel_height)
    out_geojson="run/parcels.geojson",
    out_shp="run/parcels_shp/parcels.shp",
)
print(len(gdf))

组件速查

• SAMMaskEngine: SAM2 自动掩膜提取封装，输出 (N, H, W) 掩膜堆叠
• MaskOverlapResolver: 物理覆盖 + 连通域重标，得到 无重叠实例掩膜
• MaskRefiner: 面积过滤、去飞地、（可选）填洞
• ParcelMerger: 小碎片与宿主接触率判定并同化合并
• MaskRegularizer: Douglas–Peucker 简化 + 正交/45° 纠正，输出更规则的建筑/地块边界
• MaskVectorizer: 掩膜转 GeoDataFrame，可导出 GeoJSON/Shapefile