Feature/ramp

.github/workflows/k8s-integration.yml

@@ -34,6 +34,8 @@ jobs:
           enable-cache: true
 
       - uses: extractions/setup-just@v2
+        with:
+          just-version: "1.39.0"
 
       - uses: helm/kind-action@v1
         with:

.github/workflows/validate-stac.yml

@@ -36,6 +36,8 @@ jobs:
           enable-cache: true
       - name: Install just
         uses: extractions/setup-just@v2
+        with:
+          just-version: "1.39.0"
       - name: Install dependencies
         run: uv sync --group dev
       - name: Validate STAC items

.gitignore

@@ -225,11 +225,19 @@ implementation.md
 
 # data
 data/sample/predict/predictions
+data/sample/ramp_work
+data/sample/yolo_work
 stac_catalog
 
 # hatch-vcs generated version file
 fair/_version.py
 
+
+# runs
+runs/
+
+# weights
+yolov8s_v2-seg.pt
 # dev infra
 infra/dev/.port-forward.pids
 infra/dev/.pf-logs/

models/ramp/Dockerfile

@@ -0,0 +1,109 @@
+# syntax=docker/dockerfile:1.7
+
+# Base image: ghcr.io/hotosm/fair-utilities-ramp:gpu-latest (override BASE_IMAGE for CPU builds).
+# Build from the fAIr-models repo root:
+#   docker build -f models/ramp/Dockerfile --target test -t ramp:test .
+#   docker build -f models/ramp/Dockerfile --build-arg BASE_IMAGE=ghcr.io/hotosm/fair-utilities-ramp:gpu-latest --target test -t ramp:test .
+#   docker build -f models/ramp/Dockerfile --build-arg BASE_IMAGE=ghcr.io/hotosm/fair-utilities-ramp:cpu-latest --target test -t ramp:test .
+#   docker build -f models/ramp/Dockerfile --target runtime -t ramp:runtime .
+#   docker build -f models/ramp/Dockerfile --target inference -t ramp:inference .
+ARG BASE_IMAGE=ghcr.io/hotosm/fair-utilities-ramp:gpu-latest
+
+# ---------------------------------------------------------------------------
+# Builder stage: install model-pack deps into the base image venv
+# ---------------------------------------------------------------------------
+FROM ${BASE_IMAGE} AS builder
+
+ENV UV_LINK_MODE=copy
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
+
+WORKDIR /workspace
+
+COPY pyproject.toml README.md fair_zenml_patch.pth /tmp/fair-src/
+COPY fair /tmp/fair-src/fair
+
+# The fair-utilities-ramp image already provides hot_fair_utilities, ramp-fair,
+# segmentation_models, and TensorFlow under /app/.venv. Add the fAIr model-pack
+# deps (fair itself, STAC validation, fairpredictor, onnx tooling) into that
+# same venv so training, tests, and inference share one interpreter.
+RUN --mount=type=cache,target=/root/.cache/uv \
+    SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0 \
+    uv pip install --python /app/.venv/bin/python \
+    "pystac[validation]>=1.14.3" \
+    "universal-pathlib" \
+    "fairpredictor>=0.5.1" \
+    "onnx>=1.16" \
+    "tf2onnx>=1.16" \
+    /tmp/fair-src[k8s]
+
+# ---------------------------------------------------------------------------
+# Runtime stage: production image (no test deps)
+# ---------------------------------------------------------------------------
+FROM ${BASE_IMAGE} AS runtime
+
+WORKDIR /workspace
+
+ENV PATH="/app/.venv/bin:$PATH" \
+    MPLBACKEND=Agg \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    RAMP_HOME=/app \
+    SM_FRAMEWORK=tf.keras \
+    NVIDIA_VISIBLE_DEVICES=all \
+    NVIDIA_DRIVER_CAPABILITIES=compute,utility
+
+COPY --from=builder /app/.venv /app/.venv
+
+COPY models/ramp models/ramp
+COPY models/conftest.py models/conftest.py
+COPY models/test_integration.py models/test_integration.py
+
+ENTRYPOINT ["/app/.venv/bin/python"]
+
+# ---------------------------------------------------------------------------
+# Test stage: add pytest + ZenML server deps for step & integration tests
+# ---------------------------------------------------------------------------
+FROM runtime AS test
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+COPY --from=builder /tmp/fair-src /tmp/fair-src
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0 \
+    uv pip install --python /app/.venv/bin/python /tmp/fair-src[test]
+
+# ---------------------------------------------------------------------------
+# Inference builder stage: distroless-ready venv with serving deps
+# ---------------------------------------------------------------------------
+FROM ghcr.io/astral-sh/uv:bookworm-slim AS inference-builder
+ENV UV_PYTHON_INSTALL_DIR=/python UV_PYTHON_PREFERENCE=only-managed
+RUN uv python install 3.13
+WORKDIR /app
+COPY pyproject.toml README.md fair_zenml_patch.pth /tmp/fair-src/
+COPY fair /tmp/fair-src/fair
+RUN --mount=type=cache,target=/root/.cache/uv \
+    export SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0 && \
+    uv venv && uv pip install \
+    /tmp/fair-src[serve] \
+    rasterio \
+    pyproj \
+    numpy \
+    Pillow \
+    onnx \
+    onnxruntime
+COPY models/ramp/pipeline.py /app/models/ramp/pipeline.py
+
+# ---------------------------------------------------------------------------
+# Inference stage: distroless runtime for live serving
+# ---------------------------------------------------------------------------
+FROM gcr.io/distroless/python3-debian12:nonroot AS inference
+WORKDIR /app
+COPY --from=inference-builder /python /python
+COPY --from=inference-builder /app/.venv /app/.venv
+COPY --from=inference-builder /app/models /app/models
+ENV PATH="/app/.venv/bin:$PATH" PYTHONPATH=/app \
+    ZENML_CONFIG_PATH=/tmp/zenml
+EXPOSE 8080
+ENTRYPOINT ["/app/.venv/bin/python", "-m", "uvicorn"]
+CMD ["fair.serve.base:create_app", "--factory", "--host", "0.0.0.0", "--port", "8080"]

models/ramp/README.md

@@ -0,0 +1,60 @@
+# RAMP EfficientNetB0 + U-Net Building Segmentation
+
+Semantic segmentation model for building footprint extraction from RGB aerial imagery, derived from the RAMP (Replicable AI for Microplanning) project.
+
+## Architecture
+
+- **Model**: EfficientNetB0 encoder + U-Net decoder (`EffUnet`)
+- **Framework**: TensorFlow 2.15 / `tf.keras` (via `segmentation_models` with `SM_FRAMEWORK=tf.keras`)
+- **Task**: Semantic segmentation (sparse categorical crossentropy)
+- **Input**: RGB chips (256x256, float32, channels-last)
+- **Classes**: 4 (background=0, building=1, boundary=2, contact=3)
+
+The boundary (class 2) and contact (class 3) channels help the model cleanly separate adjacent buildings at inference time, even when they share a wall. The `predict()` helper collapses the 4-class softmax to a binary building mask before vectorization.
+
+## Pretrained Source
+
+Baseline RAMP weights (TensorFlow SavedModel) hosted by HOTOSM:
+
+- Checkpoint: `https://api-prod.fair.hotosm.org/api/v1/workspace/download/ramp/baseline.zip`
+- ONNX model: `https://api-prod.fair.hotosm.org/api/v1/workspace/download/ramp/ramp-v1.onnx`
+
+## Pipeline
+
+Training pipeline steps (ZenML) defined in `pipeline.py`:
+
+- `split_dataset` - preprocesses chips + labels into 4-class multimasks and produces a seeded random train/validation split via `hot_fair_utilities.split_training_2_validation`
+- `train_model` - fine-tunes RAMP on the split, returning the best SavedModel serialized as a zipped byte stream
+- `evaluate_model` - computes `fair:accuracy`, `fair:mean_iou` (building IoU), `fair:precision`, and `fair:recall` on the validation split
+- `export_onnx` - converts the trained SavedModel to an ONNX byte stream via `tf2onnx`
+
+Inference is served through `fair.serve.base`, which calls the module-level `predict(session, input_images, params) -> FeatureCollection`: each chip is preprocessed, run through an `onnxruntime` session, decoded to a binary building mask, and vectorized to georeferenced polygons.
+
+## Base Image
+
+Training, test, and inference Docker stages all build on
+`ghcr.io/hotosm/fair-utilities-ramp:cpu-latest` (or `:gpu-latest` via the
+`BASE_IMAGE` build arg), which provides TensorFlow, GDAL, `hot_fair_utilities`
+RAMP extras, and the RAMP runtime under `/app/.venv`.
+
+```bash
+# Build targets
+docker build -f models/ramp/Dockerfile --target runtime   -t ramp:runtime   .
+docker build -f models/ramp/Dockerfile --target test      -t ramp:test      .
+docker build -f models/ramp/Dockerfile --target inference -t ramp:inference .
+```
+
+## Limitations and Bias
+
+- Training data and baseline weights are derived from the RAMP corpus (primarily humanitarian-mapping contexts); performance on dense urban scenes with complex roof structures may be lower than on sparser rural settlements.
+- The model is sensitive to imagery with strong color casts, motion blur, or significant off-nadir angle; preprocess inputs to approximately nadir RGB at the target zoom before inference.
+- Binary building output from `predict()` discards the boundary/contact auxiliary classes after decoding; downstream polygonization may still merge neighbouring buildings that share a footprint edge.
+
+## Citation
+
+RAMP - Replicable AI for Microplanning. Upstream source: https://github.com/radiantearth/ramp-code
+
+## License
+
+- Model weights and code: Apache-2.0
+- Training data: ODbL-1.0 (OpenStreetMap-derived labels)