Feat/abdul/yolo

.gitignore

@@ -225,8 +225,16 @@ implementation.md
 
 # data
 data/sample/predict/predictions
+data/sample/ramp_work
+data/sample/yolo_work
 stac_catalog
 
+# runs
+runs/
+
+# weights
+yolov8s_v2-seg.pt
+
 # hatch-vcs generated version file
 fair/_version.py
 

models/yolo_v8_segmentation/Dockerfile

@@ -0,0 +1,84 @@
+# syntax=docker/dockerfile:1.7
+
+ARG BASE_IMAGE=ghcr.io/hotosm/fair-utilities-yolo:cpu-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-yolo image already provides `hot_fair_utilities` under
+# `/app/.venv`. Install torch, fAIr client libs, etc. into that same venv so
+# runtime and tests share one interpreter (do not use `--system` / /usr/local).
+RUN --mount=type=cache,target=/root/.cache/uv \
+    SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0 \
+    uv pip install --python /app/.venv/bin/python \
+    --extra-index-url https://download.pytorch.org/whl/cpu \
+    --index-strategy unsafe-best-match \
+    torch==2.10.0 \
+    "ultralytics>=8.4.0" \
+    rasterio \
+    pyproj \
+    onnx \
+    onnxscript \
+    "pystac[validation]>=1.14.3" \
+    "universal-pathlib" \
+    "fairpredictor>=0.5.1" \
+    /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
+
+COPY --from=builder /app/.venv /app/.venv
+
+COPY models/yolo_v8_segmentation models/yolo_v8_segmentation
+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
+# ---------------------------------------------------------------------------
+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 stage: runtime + serving deps for smoke/live API
+# ---------------------------------------------------------------------------
+FROM runtime AS inference
+
+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[serve]
+
+ENV PYTHONPATH=/workspace
+EXPOSE 8080
+CMD ["/app/.venv/bin/uvicorn", "fair.serve.base:create_app", "--factory", "--host", "0.0.0.0", "--port", "8080"]

models/yolo_v8_segmentation/Dockerfile.dockerignore

@@ -0,0 +1,9 @@
+# BuildKit uses <Dockerfile>.dockerignore automatically (no repo-level side effects)
+*
+!models/yolo_v8_segmentation/
+!models/conftest.py
+!models/test_integration.py
+!fair/
+!pyproject.toml
+!README.md
+!fair_zenml_patch.pth

models/yolo_v8_segmentation/README.md

@@ -0,0 +1,29 @@
+# YOLOv8 Building Footprint Segmentation
+
+## Overview
+
+YOLOv8 Building Footprint Segmentation is a base model for extracting building footprints from very high resolution RGB aerial imagery. The model is intended for fAIr finetuning workflows where users provide OpenAerialMap chips and matching vector labels, and the system produces polygon-ready outputs through the model's preprocessing and postprocessing entrypoints.
+
+## Architecture
+
+This model uses a YOLOv8 segmentation backbone with a single foreground class for buildings. Training and inference are orchestrated through the fAIr ZenML pipeline contract, while geospatial preprocessing and polygonization are delegated to the shared `hot_fair_utilities` stack. The model expects RGB chip tensors and returns building mask predictions that are postprocessed into GeoJSON building polygons.
+
+## Pretrained Source
+
+The pretrained initialization checkpoint is the YOLOv8 segmentation weight published through the HOT fAIr utilities repository. It is used as the base checkpoint for finetuning on user-provided datasets in the fAIr platform.
+
+## Limitations and Bias
+
+Performance is sensitive to image resolution, acquisition quality, and domain shift between training and inference regions. Dense urban settlements, informal settlements, heavy shadows, cloud cover, and occlusions may reduce recall and boundary quality. Geographic and annotation bias in source training data can propagate to outputs, especially in underrepresented building styles and roof materials. Predictions should therefore be reviewed before operational use in humanitarian mapping workflows.
+
+## Usage
+
+This model is designed to be used through fAIr training and inference pipelines rather than standalone scripts. During training, users provide dataset chip and label assets plus hyperparameter overrides, and the pipeline performs deterministic train/validation splitting, model training, evaluation, and ONNX export. During inference, users provide model URI and input imagery; the pipeline runs segmentation and postprocesses outputs into geospatial building polygons.
+
+## Citation
+
+If you use this model in downstream work, cite the Ultralytics YOLO family and the HOT fAIr model packaging workflow. The STAC item includes a `cite-as` link for model lineage reference.
+
+## License
+
+This model is distributed under the Apache-2.0 license, consistent with the STAC metadata for the model package and source code.