Feature/ramp

[AbdelrahmanKatkat]

What does this PR do?

Adds / documents RAMP building-footprint segmentation (models/ramp): a 4‑class semantic building segmentation model (background, building, boundary, contact) built on an EfficientNetB0 encoder + U‑Net decoder. The fAIr serving path returns building GeoJSON polygons in EPSG:4326 derived from the predicted mask.

---

Summary

Field	Value
Task	Building footprint extraction
Input	3‑band RGB chips (OAM tiles / GeoTIFF)
Output	GeoJSON FeatureCollection of Polygon features in EPSG:4326, each with class and confidence
Model type	Semantic segmentation (4‑class mask → polygons)
Coverage	Global baseline + per‑area fine‑tuning on user-labelled chips
Use cases	Fast semantic mask baseline, coarse building inventory, AOI-specific fine-tuning experiments
License	Apache‑2.0

---

When to pick this model

• You want a fast semantic building segmentation baseline that can be fine-tuned on small AOIs.
• You can tolerate that dense/touching roofs may be merged because the model is semantic, not instance.

---

Intended use

Direct inference on OpenAerialMap tiles, and optional fine‑tuning on small downstream labelled sets (~100–200 chips) when local imagery differs from the baseline distribution.

Typical workflow

1. Provide a TMS URL + bounding box (or a directory of georeferenced RGB chips).
2. Run inference via the serving container (POST /predict) or the inference pipeline.
3. Receive EPSG:4326 polygons suitable for OSM / vector stores.

---

How to use

Live inference

POST /predict expects:

{
  "model_uri":  "https://huggingface.co/hotosm/ramp/resolve/83c77a7e5feb3af62e3604d7bb96c6c6e9ff1a96/ramp-v1.onnx",
  "image_uri":  "https://tiles.openaerialmap.org/.../{z}/{x}/{y}",
  "bbox":       [west, south, east, north],
  "zoom":       18,
  "params":     {"confidence_threshold": 0.5, "min_class_value": 1}
}

The server downloads tiles for the bbox, runs ONNX inference, and returns a GeoJSON FeatureCollection. Each feature has properties.class = 1 and properties.confidence.

---

Inference parameters

Catalog defaults from models/ramp/stac-item.json:

Parameter	Default	Meaning
confidence_threshold	0.5	Current serve path uses this as per-feature confidence
min_class_value	1	Building class id when collapsing the 4‑class mask to binary

---

Inputs and outputs

Input contract

A directory of RGB chips (.tif / .tiff / .png). The platform downloader (geomltoolkits.downloader.tms) produces this automatically from a TMS URL + bbox.

Output contract

A GeoJSON FeatureCollection in EPSG:4326. Each feature:

{
  "type": "Feature",
  "properties": {"class": 1, "confidence": 0.5},
  "geometry":   {"type": "Polygon", "coordinates": [...]}
}

---

Architecture

Component	Description
Encoder	EfficientNetB0
Decoder	U‑Net
Head	4‑class sparse categorical mask: bg / building / boundary / contact
Instance separation	Not native (semantic). Boundary/contact are present in labels but not currently used in serving decode.

---

Training labels (multimasks)

RAMP training uses polygon-derived multimasks with explicit separation channels:

Parameter	Value	Meaning
boundary_width	3 px	thickness of boundary ring
contact_spacing	8 px	spacing for “contact” points between neighboring buildings

---

Evaluation (Banepa, Nepal — polymetrics)

Truth: 2720 OSM building polygons (data/sample/test/osm/labels.geojson)
Metric: object-level matching (Hungarian) with IoU thresholds

Banepa @ IoU 0.5

Output	Source artifact	TP / FP / FN	Precision	Recall	F1@0.5
Zero-shot (base)	ci-artifacts/github_result_ramp/ramp-predictions-base.geojson	376 / 2419 / 2344	0.135	0.138	0.136
Per-area tuned (local ONNX serve output)	ci-artifacts/ramp-predictions.geojson	95 / 2654 / 2625	0.035	0.035	0.035
Baseline fairpredictor (TFLite + merged-mask postprocess)	ci-artifacts/ramp-predictions-fairpredictor.geojson	250 / 2145 / 2470	0.104	0.092	0.098

Banepa @ IoU 0.25

Output	TP / FP / FN	Precision	Recall	F1@0.25
Zero-shot (base)	1220 / 1575 / 1500	0.436	0.449	0.442
Per-area tuned (local ONNX serve output)	1275 / 1474 / 1445	0.464	0.469	0.466
Baseline fairpredictor	1064 / 1331 / 1656	0.444	0.391	0.416

Notes

• RAMP often produces visually plausible roof blobs that land in the IoU 0.25–0.5 band
• Because this is semantic segmentation, touching buildings can merge into one polygon (penalized heavily by object-level scoring).

---

Where it works best

• VHR RGB imagery (~30–50 cm GSD) where roof boundaries are visible.
• AOIs where a semantic mask baseline is acceptable and downstream cleanup is possible.

---

Where to use caution

• Dense urban with touching roofs: semantic blobs merge instances → F1@0.5 drops.
• If strict instance performance matters, use an instance model or add boundary/contact-aware splitting.

---

License & citation

• Apache‑2.0
• Upstream citation link in STAC: https://github.com/devglobalpartners/ramp-code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.27%. Comparing base (186a987) to head (6e4d2d3).

Additional details and impacted files

@@           Coverage Diff           @@
##           master      #39   +/-   ##
=======================================
  Coverage   97.27%   97.27%           
=======================================
  Files          44       44           
  Lines        3892     3893    +1     
=======================================
+ Hits         3786     3787    +1     
  Misses        106      106           

Flag	Coverage Δ
fair	96.21% <100.00%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.