Metadata-Version: 2.4
Name: parcelify
Version: 0.1.0
Summary: parcelify
Author: zpz
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: torch
Requires-Dist: tqdm
Requires-Dist: opencv-python
Requires-Dist: rasterio
Requires-Dist: geopandas
Dynamic: license-file

# Parcelify

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

## 安装/环境

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

PowerShell 示例：

```bash
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。

```python
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
