README.md

---
language:
- en
license: other
tags:
- geospatial-ai
- satellite-imagery
- image-segmentation
- semantic-segmentation
- parcel-boundary-detection
- cadastral-mapping
- land-records
- pytorch
- unet
- hrnet
pipeline_tag: image-segmentation
library_name: pytorch
datasets:
- AdilMunawar/Zaraatdost
---

# AI Parcel Boundary Digitization Model

**Satellite Imagery → Boundary Probability Mask → Clean Parcel Linework → GIS-ready Polygons**

This model detects fine parcel and field boundary lines from high-resolution satellite imagery. It is designed for large-area geospatial workflows where an AOI boundary is provided as GeoJSON, imagery is processed in chunks, and the model generates boundary probability rasters that can be converted into binary masks and final parcel polygons through topology-aware post-processing.

Developed by **Adil Munawar**.

---

## Key Capabilities

- Detects thin parcel, field, and plot boundary evidence from satellite imagery.
- Produces floating-point boundary probability masks instead of only hard binary masks.
- Supports large AOI processing through chunked, resume-safe inference.
- Supports GPU-accelerated inference with mixed precision.
- Works with GeoTIFF, GeoJSON, Rasterio, GeoPandas, PyTorch, and Hugging Face checkpoints.
- Designed for downstream GIS post-processing such as skeletonization, gap repair, topology correction, and polygonization.

---

## Model Summary

```text
Task:              Parcel boundary segmentation
Input:             RGB satellite imagery patches
Patch size:        512 x 512
Encoder:           tu-hrnet_w48
Decoder:           U-Net
Output:            1-channel boundary logits
Activation:        Sigmoid for boundary probability
Primary output:    Probability mask GeoTIFF
Downstream output: Binary mask / repaired linework / parcel polygons
```

---

## Architecture

![Model Architecture](architecture.svg)

The model uses a **HRNet-W48 encoder** for multi-scale feature extraction and a **U-Net decoder** for dense boundary segmentation. The final 1-channel output is passed through a sigmoid function to create a boundary probability mask.

---

## Complete Geospatial Workflow

![Geospatial Workflow](workflow.svg)

The workflow starts from an AOI GeoJSON, builds georeferenced imagery mosaics per chunk, runs GPU inference, writes probability masks, converts probabilities to binary boundary rasters, and prepares outputs for topology-aware GIS post-processing.

---

## High-Performance Large-AOI Inference

![High Performance Pipeline](performance_pipeline.svg)

The advanced inference pipeline overlaps CPU, network, disk, and GPU stages. While the GPU processes the current chunk, the system can prefetch and build the next chunk mosaic in the background. Inside each chunk, CPU block preparation and GPU inference are also pipelined.

---

## Recommended Post-Processing

![Post Processing](postprocessing.svg)

The raw model output is a probability mask. Production polygon outputs require post-processing such as hysteresis thresholding, gap repair, skeletonization, spur removal, and polygonization.

---

## Training Objective

```text
Total Loss =
    0.30 * BCEWithLogitsLoss
  + 0.40 * DiceLoss
  + 0.20 * FocalLoss
  + 0.08 * Edge Loss
  + 0.02 * Continuity Loss
```

- **BCEWithLogitsLoss** improves pixel-level boundary classification.
- **DiceLoss** improves mask overlap.
- **FocalLoss** improves learning on sparse boundary pixels.
- **Edge Loss** preserves boundary sharpness.
- **Continuity Loss** discourages fragmented predictions.

---

## Reported Checkpoint Metrics

| Metric | Value |
|---|---:|
| Dice Score | `0.8449` |
| Best Dice | `0.8449` |
| Quality Score | `0.8829` |
| Best Quality | `0.8829` |

```text
Quality Score = 0.45 * Dice + 0.40 * Boundary F1 + 0.15 * Connectivity
```

---

## Recommended Inference Settings

```python
PATCH_SIZE = 512
OVERLAP = 256
STRIDE = PATCH_SIZE - OVERLAP
CHUNK_SIZE_M = 8000
PROCESS_BLOCK = 4096
GPU_BATCH = 128
WORKERS = 24
DOWNLOAD_BATCH_SIZE = 2000
USE_AMP = True
```

If RAM becomes unstable:

```python
CHUNK_SIZE_M = 6000
PROCESS_BLOCK = 2048
```

If CUDA out-of-memory occurs:

```python
GPU_BATCH = 64
```

If tile downloads are throttled:

```python
WORKERS = 12
```

---

## Expected Repository Files

```text
best.pth
last.pth
README.md
architecture.svg
workflow.svg
performance_pipeline.svg
postprocessing.svg
```

---

## Example PyTorch Loading

```python
import torch
import segmentation_models_pytorch as smp

ENCODER = "tu-hrnet_w48"
DEVICE = torch.device("cuda" if torch.cuda.is_available() else "cpu")

model = smp.Unet(
    encoder_name=ENCODER,
    encoder_weights=None,
    in_channels=3,
    classes=1,
    activation=None,
).to(DEVICE)

ckpt = torch.load("best.pth", map_location="cpu")
model.load_state_dict(ckpt["model"], strict=True)
model.eval()

with torch.no_grad():
    logits = model(image_tensor)
    probability = torch.sigmoid(logits)
```

---

## Input and Output Specification

```text
Input type: RGB satellite imagery
Patch size: 512 x 512
Channels: 3
Preprocessing: ImageNet normalization

Output type: 1-channel parcel boundary probability
Activation: Sigmoid
Range: 0.0 to 1.0
```

Common pipeline outputs:

```text
prediction_probability.tif
prediction_binary.tif
prediction_preview.png
status.json
run_summary.json
```

---

## Intended Use

This model is intended for geospatial AI research, parcel boundary digitization assistance, cadastral mapping support, land-record modernization workflows, human-in-the-loop GIS editing, and boundary probability generation for topology repair pipelines.

---

## Limitations

The model may struggle with blurry imagery, shadows, haze, clouds, seasonal vegetation changes, hidden boundaries, regions outside the training distribution, and legal cadastral boundaries that are not visually visible in imagery. The model does not determine land ownership and should not be used as a legal cadastral authority without expert review.

---

## Credit

Developed by **Adil Munawar**.

Suggested citation:

```text
Adil Munawar — AI Parcel Boundary Digitization using HRNet-W48 + U-Net
```