add SAM2 segmentation

.dockerignore

@@ -0,0 +1,41 @@
+.git
+.gitignore
+
+__pycache__/
+*.py[cod]
+
+.venv/
+venv/
+env/
+
+logs/
+*.log
+
+.cache/
+hf_cache/
+torch_cache/
+models/
+checkpoints/
+
+*.gpkg
+*.geojson
+*.tif
+*.tiff
+*.vrt
+*.aux.xml
+*.ovr
+*.dbf
+*.shp
+*.shx
+*.prj
+*.cpg
+*.qgz
+*.qgs
+
+downloaded_result_*.gpkg
+sam2_crop_*.tif
+sam2_result_*.gpkg
+sam2_crop_test.tif
+
+.DS_Store
+Thumbs.db

.gitignore

@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Environments
+.venv/
+venv/
+env/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+
+# Logs
+logs/
+*.log
+
+# Local env
+.env
+.env.*
+!.env.example
+
+# Hugging Face / model caches
+.cache/
+hf_cache/
+torch_cache/
+models/
+checkpoints/
+
+# Generated geospatial files
+*.gpkg
+*.geojson
+*.tif
+*.tiff
+*.vrt
+*.aux.xml
+*.ovr
+*.dbf
+*.shp
+*.shx
+*.prj
+*.cpg
+*.qgz
+*.qgs
+
+# Local test outputs
+downloaded_result_*.gpkg
+sam2_crop_*.tif
+sam2_result_*.gpkg
+sam2_crop_test.tif
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker
+*.tar

Dockerfile

@@ -0,0 +1,45 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    HF_HOME=/home/user/.cache/huggingface \
+    TORCH_HOME=/home/user/.cache/torch \
+    MPLCONFIGDIR=/tmp/matplotlib \
+    SAM2_BUILD_CUDA=0
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    build-essential \
+    curl \
+    libglib2.0-0 \
+    libgomp1 \
+    libgl1 \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN useradd -m -u 1000 user
+
+USER user
+
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH
+
+WORKDIR /home/user/app
+
+COPY --chown=user requirements.txt /home/user/app/requirements.txt
+
+RUN python -m pip install --upgrade pip setuptools wheel
+
+# CPU PyTorch for Hugging Face CPU Spaces.
+RUN python -m pip install \
+    torch==2.5.1 \
+    torchvision==0.20.1 \
+    --index-url https://download.pytorch.org/whl/cpu
+
+RUN python -m pip install -r requirements.txt
+
+COPY --chown=user . /home/user/app
+
+EXPOSE 7860
+
+CMD ["python", "main.py", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,11 +1,26 @@
 ---
-title: Geoglyph SAM2
-emoji: 🏢
-colorFrom: red
-colorTo: indigo
+title: GeoGlyph SAM2 API
+emoji: 🛰️
+colorFrom: pink
+colorTo: gray
 sdk: docker
+app_port: 7860
 pinned: false
-license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# GeoGlyph SAM2 API
+
+FastAPI backend for GeoGlyph SAM2.
+
+This Space receives a small georeferenced GeoTIFF crop, runs SAM2 on it, polygonizes the masks using the crop transform and CRS, and returns a GeoPackage.
+
+## Endpoints
+
+- `GET /health`
+- `POST /process`
+- `GET /status/{task_id}`
+- `GET /download/{task_id}`
+
+## Important
+
+The API does not receive the full orthomosaic. The QGIS plugin crops the ROI locally and uploads only the small crop GeoTIFF.

main.py

@@ -0,0 +1,129 @@
+# main.py
+# Application entrypoint — dual-mode: API server or CLI inference on a crop GeoTIFF.
+
+import argparse
+import json
+import logging
+import os
+import sys
+
+# Ensure the project root is on sys.path so `src` can be imported.
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from src.logger import setup_logging
+
+setup_logging()
+logger = logging.getLogger("boot")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="GeoGlyph SAM2 — API server and CLI for geoglyph detection.",
+    )
+
+    # ---------------------------------------------------------------------
+    # CLI mode
+    # ---------------------------------------------------------------------
+    parser.add_argument(
+        "--cli",
+        action="store_true",
+        help="Run a single inference from the command line instead of starting the API server.",
+    )
+
+    parser.add_argument(
+        "--crop",
+        type=str,
+        help="Path to a small georeferenced GeoTIFF crop. Required for --cli.",
+    )
+
+    parser.add_argument(
+        "--output",
+        type=str,
+        help="Output GeoPackage path. Required for --cli.",
+    )
+
+    parser.add_argument(
+        "--device",
+        type=str,
+        default=None,
+        choices=["cuda", "cpu"],
+        help="Inference device: cuda | cpu. Auto-detected by default.",
+    )
+
+    # ---------------------------------------------------------------------
+    # API mode
+    # ---------------------------------------------------------------------
+    parser.add_argument(
+        "--host",
+        type=str,
+        default="0.0.0.0",
+        help="API server host. Default: 0.0.0.0.",
+    )
+
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8000,
+        help="API server port. Default: 8000.",
+    )
+
+    args = parser.parse_args()
+
+    if args.cli:
+        if not args.crop or not args.output:
+            logger.error("--crop and --output are required in CLI mode.")
+            sys.exit(1)
+
+        from src.infer import run_geoglyph_sam2_on_crop
+
+        try:
+            logger.info(
+                "CLI inference  |  crop=%s  output=%s  device=%s",
+                args.crop,
+                args.output,
+                args.device,
+            )
+
+            result = run_geoglyph_sam2_on_crop(
+                crop_tif_path=args.crop,
+                output_gpkg=args.output,
+                device=args.device,
+            )
+
+            logger.info(
+                "CLI completed  |  n_masks=%d  output=%s",
+                result["n_masks"],
+                result["output_gpkg"],
+            )
+
+            print(json.dumps(result, indent=2))
+
+        except Exception as exc:
+            logger.error("CLI inference failed: %s", exc, exc_info=True)
+            sys.exit(1)
+
+    else:
+        import uvicorn
+
+        logger.info("Starting GeoGlyph SAM2 API on %s:%d", args.host, args.port)
+
+        uvicorn.run(
+            "src.api:app",
+            host=args.host,
+            port=args.port,
+            reload=False,
+        )
+
+
+if __name__ == "__main__":
+    main()
+
+
+"""
+python main.py --cli ^
+  --crop "C:\path\to\sam2_crop.tif" ^
+  --output "C:\path\to\sam2_result.gpkg" ^
+  --device cpu
+
+python main.py --host 0.0.0.0 --port 8000
+"""

requirements.txt

@@ -0,0 +1,23 @@
+# API
+fastapi==0.115.8
+uvicorn[standard]==0.34.0
+python-multipart==0.0.20
+requests==2.32.3
+
+# Numerical / image processing
+numpy==2.1.3
+opencv-python-headless==4.10.0.84
+Pillow==11.1.0
+
+# Geospatial stack
+rasterio==1.4.3
+geopandas==1.0.1
+shapely==2.0.6
+pyproj==3.7.0
+pyogrio==0.10.0
+
+# Hugging Face model download/cache
+huggingface_hub==0.28.1
+
+# SAM2
+git+https://github.com/facebookresearch/sam2.git

src/api.py

@@ -0,0 +1,493 @@
+# src/api.py
+# FastAPI application using an async task queue.
+#
+# Important:
+# The API does NOT receive the full orthomosaic.
+# It receives a small georeferenced crop GeoTIFF uploaded as multipart/form-data.
+
+import asyncio
+import logging
+import os
+import tempfile
+import time
+import uuid
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+from fastapi import (
+    FastAPI,
+    HTTPException,
+    status,
+    UploadFile,
+    File,
+    Form,
+)
+from fastapi.responses import FileResponse
+from starlette.background import BackgroundTask
+
+from src.infer import run_geoglyph_sam2_on_crop
+
+logger = logging.getLogger("api")
+
+
+# ---------------------------------------------------------------------------
+# Global state
+# ---------------------------------------------------------------------------
+
+RESULTS_DIR = Path(tempfile.gettempdir()) / "geoglyph_sam2_api"
+RESULTS_DIR.mkdir(parents=True, exist_ok=True)
+
+TASKS: Dict[str, Dict[str, Any]] = {}
+
+# Single queue. One worker means one SAM2 inference at a time.
+# This avoids GPU OOM when several users submit jobs.
+QUEUE: asyncio.Queue = asyncio.Queue(maxsize=20)
+
+
+# ---------------------------------------------------------------------------
+# Internal job object
+# ---------------------------------------------------------------------------
+
+@dataclass
+class InferenceJob:
+    crop_path: str
+    output_gpkg: str
+
+    device: Optional[str] = None
+
+    use_clahe: bool = True
+    clahe_clip: float = 4.0
+    clahe_grid: int = 6
+
+    sam2_points_per_side: int = 32
+    sam2_points_per_batch: int = 32
+    sam2_pred_iou_thresh: float = 0.35
+    sam2_stability_score_thresh: float = 0.65
+
+    filter_min_area_px: int = 1000
+    filter_max_area_frac: float = 0.20
+    filter_min_iou: float = 0.35
+    filter_min_stability: float = 0.65
+    filter_border_margin: int = 10
+
+    max_crop_side: int = 4096
+
+
+# ---------------------------------------------------------------------------
+# Worker
+# ---------------------------------------------------------------------------
+
+async def queue_worker():
+    """
+    Background worker.
+
+    It processes tasks sequentially to avoid GPU/CPU contention and GPU OOM.
+    Heavy SAM2 inference runs in a separate thread.
+    """
+
+    logger.info("Task queue worker started.")
+
+    while True:
+        try:
+            task_id, job = await QUEUE.get()
+
+        except asyncio.CancelledError:
+            logger.info("Task queue worker cancelled.")
+            break
+
+        except Exception as exc:
+            logger.error("Error retrieving task from queue: %s", exc, exc_info=True)
+            continue
+
+        try:
+            if task_id not in TASKS:
+                continue
+
+            TASKS[task_id]["status"] = "processing"
+            TASKS[task_id]["started_at"] = time.time()
+
+            logger.info("Worker started task_id=%s", task_id)
+
+            result = await asyncio.to_thread(
+                run_geoglyph_sam2_on_crop,
+                crop_tif_path=job.crop_path,
+                output_gpkg=job.output_gpkg,
+                device=job.device,
+                use_clahe=job.use_clahe,
+                clahe_clip=job.clahe_clip,
+                clahe_grid=job.clahe_grid,
+                sam2_points_per_side=job.sam2_points_per_side,
+                sam2_points_per_batch=job.sam2_points_per_batch,
+                sam2_pred_iou_thresh=job.sam2_pred_iou_thresh,
+                sam2_stability_score_thresh=job.sam2_stability_score_thresh,
+                filter_min_area_px=job.filter_min_area_px,
+                filter_max_area_frac=job.filter_max_area_frac,
+                filter_min_iou=job.filter_min_iou,
+                filter_min_stability=job.filter_min_stability,
+                filter_border_margin=job.filter_border_margin,
+                max_crop_side=job.max_crop_side,
+            )
+
+            TASKS[task_id].update(
+                {
+                    "status": "completed",
+                    "finished_at": time.time(),
+                    "n_masks": result["n_masks"],
+                    "output_exists": result["output_exists"],
+                    "result": result,
+                    "download_url": f"/download/{task_id}"
+                    if result["output_exists"]
+                    else None,
+                }
+            )
+
+            logger.info(
+                "Worker completed task_id=%s  n_masks=%d  output_exists=%s",
+                task_id,
+                result["n_masks"],
+                result["output_exists"],
+            )
+
+        except Exception as exc:
+            logger.error(
+                "Worker failed task_id=%s: %s",
+                task_id,
+                exc,
+                exc_info=True,
+            )
+
+            if task_id in TASKS:
+                TASKS[task_id].update(
+                    {
+                        "status": "failed",
+                        "finished_at": time.time(),
+                        "error": str(exc),
+                    }
+                )
+
+            try:
+                import torch
+
+                if torch.cuda.is_available():
+                    torch.cuda.empty_cache()
+                    logger.info("Cleared CUDA cache after task failure.")
+
+            except Exception:
+                pass
+
+        finally:
+            # Crop is no longer needed after processing.
+            try:
+                if os.path.exists(job.crop_path):
+                    os.remove(job.crop_path)
+                    logger.info("Deleted temporary crop for task_id=%s", task_id)
+            except Exception as exc:
+                logger.warning(
+                    "Could not delete temporary crop for task_id=%s: %s",
+                    task_id,
+                    exc,
+                )
+
+            QUEUE.task_done()
+
+
+# ---------------------------------------------------------------------------
+# Lifespan
+# ---------------------------------------------------------------------------
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    worker_task = asyncio.create_task(queue_worker())
+
+    yield
+
+    worker_task.cancel()
+
+    try:
+        await worker_task
+    except asyncio.CancelledError:
+        pass
+
+
+# ---------------------------------------------------------------------------
+# FastAPI app
+# ---------------------------------------------------------------------------
+
+app = FastAPI(
+    title="GeoGlyph SAM2 API",
+    description=(
+        "Backend API for geoglyph detection using SAM2. "
+        "Receives small georeferenced crop GeoTIFFs, not full orthomosaics."
+    ),
+    version="3.0.0",
+    lifespan=lifespan,
+)
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+@app.get("/health", status_code=status.HTTP_200_OK)
+async def health_check():
+    return {
+        "status": "ok",
+        "message": "GeoGlyph SAM2 API is running.",
+        "queue_size": QUEUE.qsize(),
+        "results_dir": str(RESULTS_DIR),
+    }
+
+
+@app.post("/process", status_code=status.HTTP_202_ACCEPTED)
+async def process_geoglyphs(
+    crop: UploadFile = File(...),
+    device: Optional[str] = Form(None),
+
+    use_clahe: bool = Form(True),
+    clahe_clip: float = Form(4.0),
+    clahe_grid: int = Form(6),
+
+    sam2_points_per_side: int = Form(32),
+    sam2_points_per_batch: int = Form(32),
+    sam2_pred_iou_thresh: float = Form(0.35),
+    sam2_stability_score_thresh: float = Form(0.65),
+
+    filter_min_area_px: int = Form(1000),
+    filter_max_area_frac: float = Form(0.20),
+    filter_min_iou: float = Form(0.35),
+    filter_min_stability: float = Form(0.65),
+    filter_border_margin: int = Form(10),
+
+    max_crop_side: int = Form(4096),
+):
+    """
+    Submit a SAM2 inference job.
+
+    The client uploads a georeferenced crop GeoTIFF.
+    The API never receives the original orthomosaic.
+    """
+
+    if QUEUE.full():
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail="Task queue is full. Try again later.",
+        )
+
+    if device not in {None, "cuda", "cpu"}:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid device. Expected 'cuda', 'cpu', or omitted.",
+        )
+
+    task_id = uuid.uuid4().hex[:12]
+
+    crop_path = RESULTS_DIR / f"{task_id}_crop.tif"
+    output_gpkg = RESULTS_DIR / f"{task_id}.gpkg"
+
+    try:
+        with open(crop_path, "wb") as f:
+            while True:
+                chunk = await crop.read(1024 * 1024)
+                if not chunk:
+                    break
+                f.write(chunk)
+
+        await crop.close()
+
+    except Exception as exc:
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail=f"Could not save uploaded crop: {exc}",
+        )
+
+    if not crop_path.is_file() or crop_path.stat().st_size == 0:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Uploaded crop is empty or could not be saved.",
+        )
+
+    job = InferenceJob(
+        crop_path=str(crop_path),
+        output_gpkg=str(output_gpkg),
+        device=device,
+        use_clahe=use_clahe,
+        clahe_clip=clahe_clip,
+        clahe_grid=clahe_grid,
+        sam2_points_per_side=sam2_points_per_side,
+        sam2_points_per_batch=sam2_points_per_batch,
+        sam2_pred_iou_thresh=sam2_pred_iou_thresh,
+        sam2_stability_score_thresh=sam2_stability_score_thresh,
+        filter_min_area_px=filter_min_area_px,
+        filter_max_area_frac=filter_max_area_frac,
+        filter_min_iou=filter_min_iou,
+        filter_min_stability=filter_min_stability,
+        filter_border_margin=filter_border_margin,
+        max_crop_side=max_crop_side,
+    )
+
+    TASKS[task_id] = {
+        "status": "pending",
+        "created_at": time.time(),
+        "original_filename": crop.filename,
+        "crop_path": str(crop_path),
+        "output_gpkg": str(output_gpkg),
+        "n_masks": None,
+        "output_exists": None,
+        "error": None,
+    }
+
+    await QUEUE.put((task_id, job))
+
+    logger.info(
+        "Enqueued task_id=%s  filename=%s  queue_size=%d",
+        task_id,
+        crop.filename,
+        QUEUE.qsize(),
+    )
+
+    return {
+        "task_id": task_id,
+        "status": "pending",
+        "queue_size": QUEUE.qsize(),
+    }
+
+
+@app.get("/status/{task_id}", status_code=status.HTTP_200_OK)
+async def get_status(task_id: str):
+    """
+    Check task status.
+
+    Possible statuses:
+    - pending
+    - processing
+    - completed
+    - failed
+    """
+
+    if task_id not in TASKS:
+        raise HTTPException(status_code=404, detail="Task not found")
+
+    task_info = TASKS[task_id]
+
+    if task_info["status"] == "pending":
+        pending_ids = [
+            tid
+            for tid, data in TASKS.items()
+            if data["status"] == "pending"
+        ]
+
+        try:
+            position = pending_ids.index(task_id) + 1
+        except ValueError:
+            position = 0
+
+        return {
+            "task_id": task_id,
+            "status": "pending",
+            "queue_position": position,
+        }
+
+    if task_info["status"] == "processing":
+        return {
+            "task_id": task_id,
+            "status": "processing",
+            "started_at": task_info.get("started_at"),
+        }
+
+    if task_info["status"] == "completed":
+        return {
+            "task_id": task_id,
+            "status": "completed",
+            "n_masks": task_info.get("n_masks"),
+            "output_exists": task_info.get("output_exists"),
+            "download_url": task_info.get("download_url"),
+            "result": task_info.get("result"),
+        }
+
+    if task_info["status"] == "failed":
+        return {
+            "task_id": task_id,
+            "status": "failed",
+            "error": task_info.get("error"),
+        }
+
+    return task_info
+
+
+def cleanup_task(task_id: str):
+    """
+    Delete generated files and remove task metadata.
+    Called after successful download.
+    """
+
+    task = TASKS.get(task_id, {})
+
+    paths_to_delete = [
+        task.get("output_gpkg"),
+        task.get("crop_path"),
+    ]
+
+    for path_str in paths_to_delete:
+        if not path_str:
+            continue
+
+        path = Path(path_str)
+
+        if path.exists():
+            try:
+                path.unlink()
+                logger.info("Deleted file for task_id=%s: %s", task_id, path)
+            except Exception as exc:
+                logger.warning(
+                    "Could not delete file for task_id=%s: %s",
+                    task_id,
+                    exc,
+                )
+
+    if task_id in TASKS:
+        del TASKS[task_id]
+
+
+@app.get("/download/{task_id}")
+async def download_result(task_id: str):
+    """
+    Download the generated GeoPackage.
+
+    The task is cleaned after transfer.
+    """
+
+    if task_id not in TASKS:
+        raise HTTPException(status_code=404, detail="Task not found")
+
+    task = TASKS[task_id]
+
+    if task["status"] != "completed":
+        raise HTTPException(
+            status_code=400,
+            detail="Task is not completed yet.",
+        )
+
+    if not task.get("output_exists"):
+        raise HTTPException(
+            status_code=404,
+            detail="Task completed but no GeoPackage was created. No masks passed the filters.",
+        )
+
+    gpkg_path = Path(task["output_gpkg"])
+
+    if not gpkg_path.is_file():
+        raise HTTPException(
+            status_code=404,
+            detail="Result file is missing.",
+        )
+
+    logger.info("Serving GPKG download  |  task_id=%s", task_id)
+
+    return FileResponse(
+        path=str(gpkg_path),
+        media_type="application/geopackage+sqlite3",
+        filename=f"sam2_result_{task_id}.gpkg",
+        background=BackgroundTask(cleanup_task, task_id),
+    )

src/infer.py

@@ -0,0 +1,439 @@
+# src/infer.py
+# SAM2 geoglyph inference pipeline using a georeferenced crop GeoTIFF.
+#
+# Important:
+# This file does NOT receive or open the full orthomosaic.
+# It only receives a small crop GeoTIFF containing:
+# - RGB pixels
+# - CRS
+# - affine transform
+
+from pathlib import Path
+import logging
+
+import numpy as np
+import torch
+import rasterio
+from rasterio.features import shapes
+import geopandas as gpd
+from shapely.geometry import shape
+
+from src.preprocess import preprocess
+
+logger = logging.getLogger("pipeline")
+
+
+# ---------------------------------------------------------------------------
+# Model cache
+# ---------------------------------------------------------------------------
+
+_MODEL_CACHE = {}
+
+
+# ---------------------------------------------------------------------------
+# Device handling
+# ---------------------------------------------------------------------------
+
+def resolve_device(device: str | None) -> str:
+    if device is None:
+        return "cuda" if torch.cuda.is_available() else "cpu"
+
+    device = device.lower().strip()
+
+    if device not in {"cuda", "cpu"}:
+        raise ValueError(f"Invalid device: {device}. Expected 'cuda' or 'cpu'.")
+
+    if device == "cuda" and not torch.cuda.is_available():
+        raise RuntimeError("CUDA was requested, but torch.cuda.is_available() is False.")
+
+    return device
+
+
+# ---------------------------------------------------------------------------
+# Model loading
+# ---------------------------------------------------------------------------
+
+def load_sam2_model(
+    device: str = "cuda",
+    points_per_side: int = 32,
+    points_per_batch: int = 32,
+    pred_iou_thresh: float = 0.35,
+    stability_score_thresh: float = 0.65,
+):
+    """
+    Load the SAM2 automatic mask generator from Hugging Face.
+
+    The model is cached by device and SAM2 hyperparameters so the API does not
+    reload the model for every task.
+    """
+
+    from sam2.automatic_mask_generator import SAM2AutomaticMaskGenerator
+
+    key = (
+        device,
+        points_per_side,
+        points_per_batch,
+        pred_iou_thresh,
+        stability_score_thresh,
+    )
+
+    if key in _MODEL_CACHE:
+        logger.info("Reusing cached SAM2 model  |  device=%s", device)
+        return _MODEL_CACHE[key]
+
+    logger.info(
+        "Loading SAM2 model  |  device=%s  PPS=%d  PPB=%d  IOU_thresh=%.2f  Stability_thresh=%.2f",
+        device,
+        points_per_side,
+        points_per_batch,
+        pred_iou_thresh,
+        stability_score_thresh,
+    )
+
+    mask_generator = SAM2AutomaticMaskGenerator.from_pretrained(
+        "facebook/sam2.1-hiera-large",
+        device=device,
+        points_per_side=points_per_side,
+        points_per_batch=points_per_batch,
+        crop_n_layers=0,
+        multimask_output=False,
+        use_m2m=False,
+        pred_iou_thresh=pred_iou_thresh,
+        stability_score_thresh=stability_score_thresh,
+    )
+
+    predictor = getattr(mask_generator, "predictor", None)
+    model = getattr(predictor, "model", None)
+
+    if model is not None:
+        actual_device = next(model.parameters()).device
+        logger.info("Actual SAM2 model device: %s", actual_device)
+
+        if device == "cpu" and actual_device.type != "cpu":
+            raise RuntimeError(
+                f"Expected SAM2 to run on CPU, but model is on {actual_device}."
+            )
+
+        if device == "cuda" and actual_device.type != "cuda":
+            raise RuntimeError(
+                f"Expected SAM2 to run on CUDA, but model is on {actual_device}."
+            )
+    else:
+        logger.warning("Could not inspect actual SAM2 model device.")
+
+    _MODEL_CACHE[key] = mask_generator
+    return mask_generator
+
+
+# ---------------------------------------------------------------------------
+# Crop GeoTIFF I/O
+# ---------------------------------------------------------------------------
+
+def read_georeferenced_crop(
+    crop_tif_path: str,
+    rgb_bands: tuple = (1, 2, 3),
+    max_crop_side: int = 4096,
+):
+    """
+    Read a small georeferenced GeoTIFF crop.
+
+    This function does NOT need access to the original orthomosaic.
+
+    The crop GeoTIFF must contain:
+    - RGB pixel data
+    - CRS
+    - affine transform
+
+    Returns:
+    - RGB uint8 image
+    - crop transform
+    - crop CRS
+    - crop metadata
+    """
+
+    crop_tif_path = str(crop_tif_path)
+
+    logger.info("Reading georeferenced crop: %s", crop_tif_path)
+
+    with rasterio.open(crop_tif_path) as src:
+        if src.crs is None:
+            raise ValueError("The crop GeoTIFF has no CRS.")
+
+        if src.transform is None:
+            raise ValueError("The crop GeoTIFF has no affine transform.")
+
+        if src.count < max(rgb_bands):
+            raise ValueError(
+                f"The crop has only {src.count} band(s), "
+                f"but rgb_bands={rgb_bands} was requested."
+            )
+
+        if src.width > max_crop_side or src.height > max_crop_side:
+            raise ValueError(
+                f"Crop too large: {src.width}x{src.height} px. "
+                f"Maximum allowed side is {max_crop_side} px."
+            )
+
+        arr = src.read(rgb_bands)
+
+        crop_transform = src.transform
+        crop_crs = src.crs
+        crop_bounds = src.bounds
+
+        metadata = {
+            "width": int(src.width),
+            "height": int(src.height),
+            "count": int(src.count),
+            "crs": str(src.crs),
+            "bounds": {
+                "left": float(crop_bounds.left),
+                "bottom": float(crop_bounds.bottom),
+                "right": float(crop_bounds.right),
+                "top": float(crop_bounds.top),
+            },
+        }
+
+    arr = np.transpose(arr, (1, 2, 0))
+    arr = np.nan_to_num(arr)
+
+    if arr.dtype != np.uint8:
+        logger.warning(
+            "Crop dtype is %s, converting to uint8 by clipping to [0, 255].",
+            arr.dtype,
+        )
+        arr = np.clip(arr, 0, 255).astype(np.uint8)
+
+    logger.info(
+        "Crop loaded  |  shape=%s  crs=%s",
+        arr.shape,
+        metadata["crs"],
+    )
+
+    return arr, crop_transform, crop_crs, metadata
+
+
+# ---------------------------------------------------------------------------
+# Mask → GeoDataFrame
+# ---------------------------------------------------------------------------
+
+def masks_to_geodataframe(
+    masks_data: list,
+    crop_transform,
+    crop_crs,
+    image_shape: tuple,
+    min_area_px: int = 1000,
+    max_area_frac: float = 0.20,
+    min_iou: float = 0.35,
+    min_stability: float = 0.65,
+    border_margin: int = 10,
+) -> gpd.GeoDataFrame:
+    """
+    Convert raw SAM2 masks to a filtered GeoDataFrame of polygons.
+
+    The important line is:
+
+        shapes(..., transform=crop_transform)
+
+    This converts mask pixel coordinates into real map coordinates using
+    the crop GeoTIFF georeference.
+    """
+
+    H, W = image_shape[:2]
+    max_area_px = int(H * W * max_area_frac)
+
+    logger.info(
+        "Filtering masks  |  area=[%d, %d] px  IOU>=%.2f  Stability>=%.2f  border_margin=%d",
+        min_area_px,
+        max_area_px,
+        min_iou,
+        min_stability,
+        border_margin,
+    )
+
+    records = []
+
+    for mask_id, m in enumerate(masks_data):
+        area_px = int(m["area"])
+
+        if area_px < min_area_px or area_px > max_area_px:
+            continue
+
+        if m["predicted_iou"] < min_iou:
+            continue
+
+        if m["stability_score"] < min_stability:
+            continue
+
+        mask_u8 = m["segmentation"].astype(np.uint8)
+
+        rows, cols = np.where(mask_u8)
+        if len(rows) == 0:
+            continue
+
+        touches_border = (
+            rows.min() < border_margin
+            or rows.max() > H - border_margin
+            or cols.min() < border_margin
+            or cols.max() > W - border_margin
+        )
+
+        if touches_border:
+            continue
+
+        for geom_dict, val in shapes(
+            mask_u8,
+            mask=mask_u8.astype(bool),
+            transform=crop_transform,
+        ):
+            if val != 1:
+                continue
+
+            geom = shape(geom_dict)
+
+            if geom.is_empty:
+                continue
+
+            records.append(
+                {
+                    "geometry": geom,
+                    "mask_id": mask_id,
+                    "predicted_iou": float(m["predicted_iou"]),
+                    "stability_score": float(m["stability_score"]),
+                    "area_px": area_px,
+                }
+            )
+
+    gdf = gpd.GeoDataFrame(records, geometry="geometry", crs=crop_crs)
+
+    logger.info("Retained %d mask geometries after filtering.", len(gdf))
+
+    return gdf
+
+
+# ---------------------------------------------------------------------------
+# Main orchestrator
+# ---------------------------------------------------------------------------
+
+def run_geoglyph_sam2_on_crop(
+    crop_tif_path: str,
+    output_gpkg: str,
+    layer_name: str = "sam2_geoglyph_detections",
+    device: str | None = None,
+    # Preprocessing
+    use_clahe: bool = True,
+    clahe_clip: float = 4.0,
+    clahe_grid: int = 6,
+    # SAM2 hyperparameters
+    sam2_points_per_side: int = 32,
+    sam2_points_per_batch: int = 32,
+    sam2_pred_iou_thresh: float = 0.35,
+    sam2_stability_score_thresh: float = 0.65,
+    # Postprocessing filters
+    filter_min_area_px: int = 1000,
+    filter_max_area_frac: float = 0.20,
+    filter_min_iou: float = 0.35,
+    filter_min_stability: float = 0.65,
+    filter_border_margin: int = 10,
+    # Safety
+    max_crop_side: int = 4096,
+) -> dict:
+    """
+    End-to-end geoglyph detection pipeline from a georeferenced crop.
+
+    This function does NOT receive:
+    - original orthomosaic path
+    - bbox
+    - bbox CRS
+
+    It only receives a small crop GeoTIFF with CRS and transform.
+    """
+
+    device = resolve_device(device)
+
+    logger.info("=" * 60)
+    logger.info("STARTING GEOGLYPH SAM2 INFERENCE ON CROP")
+    logger.info("=" * 60)
+    logger.info("Input crop: %s", crop_tif_path)
+    logger.info("Output GPKG: %s", output_gpkg)
+    logger.info("Requested device: %s", device)
+
+    crop_tif_path = str(crop_tif_path)
+    output_gpkg = Path(output_gpkg)
+
+    arr_raw, crop_transform, crop_crs, crop_metadata = read_georeferenced_crop(
+        crop_tif_path=crop_tif_path,
+        max_crop_side=max_crop_side,
+    )
+
+    if use_clahe:
+        logger.info(
+            "Applying CLAHE  |  clip=%.1f  grid=%d",
+            clahe_clip,
+            clahe_grid,
+        )
+
+    arr_processed = preprocess(
+        arr_raw,
+        use_clahe=use_clahe,
+        clip=clahe_clip,
+        grid=clahe_grid,
+    )
+
+    mask_generator = load_sam2_model(
+        device=device,
+        points_per_side=sam2_points_per_side,
+        points_per_batch=sam2_points_per_batch,
+        pred_iou_thresh=sam2_pred_iou_thresh,
+        stability_score_thresh=sam2_stability_score_thresh,
+    )
+
+    logger.info("Generating masks...")
+    with torch.inference_mode():
+        masks_data = mask_generator.generate(arr_processed)
+
+    logger.info("SAM2 generated %d raw masks.", len(masks_data))
+
+    gdf = masks_to_geodataframe(
+        masks_data=masks_data,
+        crop_transform=crop_transform,
+        crop_crs=crop_crs,
+        image_shape=arr_processed.shape,
+        min_area_px=filter_min_area_px,
+        max_area_frac=filter_max_area_frac,
+        min_iou=filter_min_iou,
+        min_stability=filter_min_stability,
+        border_margin=filter_border_margin,
+    )
+
+    if len(gdf) > 0:
+        gdf["source_crop"] = crop_tif_path
+        gdf["input_mode"] = "georeferenced_crop"
+        gdf["crop_width"] = crop_metadata["width"]
+        gdf["crop_height"] = crop_metadata["height"]
+        gdf["crop_crs"] = crop_metadata["crs"]
+
+        logger.info(
+            "Exporting %d geometries → %s  layer=%s",
+            len(gdf),
+            output_gpkg,
+            layer_name,
+        )
+
+        gdf.to_file(output_gpkg, layer=layer_name, driver="GPKG")
+        output_exists = True
+    else:
+        logger.warning("No geometries to export after filtering.")
+        output_exists = False
+
+    logger.info("=" * 60)
+    logger.info("INFERENCE COMPLETED")
+    logger.info("=" * 60)
+
+    return {
+        "output_gpkg": str(output_gpkg),
+        "layer_name": layer_name,
+        "n_masks": len(gdf),
+        "input_mode": "georeferenced_crop",
+        "crop": crop_metadata,
+        "output_exists": output_exists,
+    }

src/logger.py

@@ -0,0 +1,88 @@
+# src/logger.py
+# Structured logging configuration.
+
+import logging
+import logging.config
+import os
+
+
+def setup_logging():
+    logs_dir = os.path.join(
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+        "logs",
+    )
+
+    os.makedirs(logs_dir, exist_ok=True)
+
+    LOG_FORMAT = "%(asctime)s | %(name)-8s | %(levelname)-7s | %(message)s"
+    DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+    logging_config = {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "formatters": {
+            "standard": {
+                "format": LOG_FORMAT,
+                "datefmt": DATE_FORMAT,
+            },
+        },
+        "handlers": {
+            "console": {
+                "class": "logging.StreamHandler",
+                "level": "INFO",
+                "formatter": "standard",
+                # Use stderr so stdout can stay clean for JSON in CLI mode.
+                "stream": "ext://sys.stderr",
+            },
+            "file_boot": {
+                "class": "logging.handlers.RotatingFileHandler",
+                "level": "INFO",
+                "formatter": "standard",
+                "filename": os.path.join(logs_dir, "boot.log"),
+                "maxBytes": 10_485_760,
+                "backupCount": 3,
+                "encoding": "utf8",
+            },
+            "file_api": {
+                "class": "logging.handlers.RotatingFileHandler",
+                "level": "INFO",
+                "formatter": "standard",
+                "filename": os.path.join(logs_dir, "api.log"),
+                "maxBytes": 10_485_760,
+                "backupCount": 3,
+                "encoding": "utf8",
+            },
+            "file_pipeline": {
+                "class": "logging.handlers.RotatingFileHandler",
+                "level": "INFO",
+                "formatter": "standard",
+                "filename": os.path.join(logs_dir, "pipeline.log"),
+                "maxBytes": 10_485_760,
+                "backupCount": 3,
+                "encoding": "utf8",
+            },
+        },
+        "loggers": {
+            "boot": {
+                "level": "INFO",
+                "handlers": ["console", "file_boot"],
+                "propagate": False,
+            },
+            "api": {
+                "level": "INFO",
+                "handlers": ["console", "file_api"],
+                "propagate": False,
+            },
+            "pipeline": {
+                "level": "INFO",
+                "handlers": ["console", "file_pipeline"],
+                "propagate": False,
+            },
+        },
+        "root": {
+            "level": "INFO",
+            "handlers": ["console"],
+        },
+    }
+
+    logging.config.dictConfig(logging_config)

src/preprocess.py

@@ -0,0 +1,50 @@
+# src/preprocess.py
+# Image preprocessing utilities.
+
+import cv2
+import numpy as np
+
+
+def apply_clahe(
+    img_rgb: np.ndarray,
+    clip_limit: float = 4.0,
+    grid_size: int = 6,
+) -> np.ndarray:
+    """
+    Apply CLAHE on the L channel of the LAB colour space.
+
+    Flow:
+    RGB → LAB → enhance L channel → RGB
+    """
+
+    clahe = cv2.createCLAHE(
+        clipLimit=clip_limit,
+        tileGridSize=(grid_size, grid_size),
+    )
+
+    lab = cv2.cvtColor(img_rgb, cv2.COLOR_RGB2LAB)
+    lab[:, :, 0] = clahe.apply(lab[:, :, 0])
+
+    return cv2.cvtColor(lab, cv2.COLOR_LAB2RGB)
+
+
+def preprocess(
+    img_rgb: np.ndarray,
+    use_clahe: bool = True,
+    clip: float = 4.0,
+    grid: int = 6,
+) -> np.ndarray:
+    """
+    Run preprocessing on an RGB uint8 array.
+    """
+
+    out = img_rgb.copy()
+
+    if use_clahe:
+        out = apply_clahe(
+            out,
+            clip_limit=clip,
+            grid_size=grid,
+        )
+
+    return out

test_queue.py

@@ -0,0 +1,150 @@
+# test_queue.py
+# Simulate several geologists submitting crop GeoTIFF jobs concurrently.
+
+import os
+import threading
+import time
+
+import requests
+
+URL = "http://localhost:8000"
+
+# Use a real georeferenced crop GeoTIFF here.
+# For example, one generated by your QGIS plugin:
+# C:\Users\juan_\AppData\Local\Temp\sam2_crop_XXXXXXXXXX.tif
+CROP_PATH = os.path.abspath("sam2_crop_test.tif")
+
+
+def geologist_client(geologist_id: int):
+    print(f"[Geólogo {geologist_id}] Enviando crop GeoTIFF al servidor...")
+
+    if not os.path.isfile(CROP_PATH):
+        print(f"[Geólogo {geologist_id}] No existe el crop: {CROP_PATH}")
+        return
+
+    try:
+        with open(CROP_PATH, "rb") as f:
+            files = {
+                "crop": (
+                    os.path.basename(CROP_PATH),
+                    f,
+                    "image/tiff",
+                )
+            }
+
+            data = {
+                "device": "cpu",
+                "use_clahe": "true",
+                "clahe_clip": "4.0",
+                "clahe_grid": "6",
+                "sam2_points_per_side": "32",
+                "sam2_points_per_batch": "32",
+                "sam2_pred_iou_thresh": "0.35",
+                "sam2_stability_score_thresh": "0.65",
+                "filter_min_area_px": "1000",
+                "filter_max_area_frac": "0.20",
+                "filter_min_iou": "0.35",
+                "filter_min_stability": "0.65",
+                "filter_border_margin": "10",
+                "max_crop_side": "4096",
+            }
+
+            resp = requests.post(
+                f"{URL}/process",
+                files=files,
+                data=data,
+            )
+
+            resp.raise_for_status()
+
+    except Exception as e:
+        print(f"[Geólogo {geologist_id}] Error enviando tarea: {e}")
+        return
+
+    data = resp.json()
+    task_id = data["task_id"]
+
+    print(f"[Geólogo {geologist_id}] Tarea aceptada. ID: {task_id}")
+
+    last_status = None
+
+    while True:
+        try:
+            status_resp = requests.get(f"{URL}/status/{task_id}")
+            status_resp.raise_for_status()
+            s_data = status_resp.json()
+
+            status_value = s_data["status"]
+
+            if status_value == "pending":
+                pos = s_data.get("queue_position")
+                current_status = f"pending_pos_{pos}"
+
+                if current_status != last_status:
+                    print(
+                        f"[Geólogo {geologist_id}] Estado: En cola | Posición: {pos}"
+                    )
+                    last_status = current_status
+
+            elif status_value == "processing":
+                if last_status != "processing":
+                    print(
+                        f"[Geólogo {geologist_id}] Estado: Procesando inferencia SAM2..."
+                    )
+                    last_status = "processing"
+
+            elif status_value == "completed":
+                n_masks = s_data.get("n_masks")
+                output_exists = s_data.get("output_exists")
+                download_url = s_data.get("download_url")
+
+                print(
+                    f"[Geólogo {geologist_id}] COMPLETO | "
+                    f"n_masks={n_masks} | output_exists={output_exists}"
+                )
+
+                if output_exists and download_url:
+                    out_path = f"downloaded_result_{geologist_id}_{task_id}.gpkg"
+                    download_resp = requests.get(f"{URL}{download_url}")
+                    download_resp.raise_for_status()
+
+                    with open(out_path, "wb") as out:
+                        out.write(download_resp.content)
+
+                    print(
+                        f"[Geólogo {geologist_id}] Resultado descargado: {out_path}"
+                    )
+
+                break
+
+            elif status_value == "failed":
+                print(
+                    f"[Geólogo {geologist_id}] FALLÓ: {s_data.get('error')}"
+                )
+                break
+
+        except Exception as e:
+            print(f"[Geólogo {geologist_id}] Error consultando estado: {e}")
+            break
+
+        time.sleep(0.5)
+
+
+if __name__ == "__main__":
+    print("Iniciando prueba con 5 geólogos concurrentes...\n")
+
+    threads = []
+
+    for i in range(1, 6):
+        t = threading.Thread(
+            target=geologist_client,
+            args=(i,),
+        )
+
+        threads.append(t)
+        t.start()
+
+    for t in threads:
+        t.join()
+
+    print("\nPrueba finalizada.")