"""Prepare multi-layer clipped raster bundles for an AOI."""
from __future__ import annotations
import json
import shutil
import uuid
import zipfile
from collections.abc import Callable
from datetime import UTC, datetime
from pathlib import Path
from typing import Any
from fresh_hectaresbc import HectaresBC
from fresh_hectaresbc.clip import ClipError, clip_raster_to_aoi
from fresh_hectaresbc.femic_bridge import FemicBridgeError, resolve_aoi
DEFAULT_MAX_LAYERS = 6
DEFAULT_MAX_AREA_HA = 10_000_000.0
[docs]
class BundleError(RuntimeError):
"""Raised when an AOI bundle cannot be prepared safely."""
[docs]
class BundleCancelled(RuntimeError):
"""Raised when a bundle job is cancelled between clipping steps."""
ProgressCallback = Callable[[dict[str, Any]], None]
CancelCheck = Callable[[], bool]
def _progress(callback: ProgressCallback | None, payload: dict[str, Any]) -> None:
if callback is not None:
callback(payload)
def _bundle_id() -> str:
stamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
return f"{stamp}-{uuid.uuid4().hex[:8]}"
def _load_aoi_geojson(path: Path) -> dict[str, Any]:
try:
payload = json.loads(path.read_text(encoding="utf-8"))
except (OSError, json.JSONDecodeError) as exc:
raise BundleError(f"Could not read AOI GeoJSON {path}: {exc}") from exc
if payload.get("type") not in {"Feature", "FeatureCollection"}:
raise BundleError("AOI GeoJSON must be a Feature or FeatureCollection.")
return payload
def _aoi_metadata_from_file(path: Path, name: str | None) -> dict[str, Any]:
import geopandas as gpd # type: ignore[import-untyped]
aoi = gpd.read_file(path)
if aoi.empty:
raise BundleError("AOI GeoJSON contains no features.")
if aoi.crs is None:
aoi = aoi.set_crs("EPSG:4326")
aoi_3005 = aoi.to_crs("EPSG:3005")
aoi_wgs84 = aoi.to_crs("EPSG:4326")
bounds_3005 = aoi_3005.total_bounds
bounds_wgs84 = aoi_wgs84.total_bounds
area_ha = float(aoi_3005.geometry.area.sum() / 10_000.0)
return {
"name": name or "custom AOI",
"feature_count": int(len(aoi)),
"bbox_3005": [float(value) for value in bounds_3005],
"bbox_wgs84": [float(value) for value in bounds_wgs84],
"area_ha": area_ha,
}
def _sanitize_clip(result: Any, bundle_dir: Path, source_zip: str) -> dict[str, Any]:
relative = result.output_path.relative_to(bundle_dir).as_posix()
return {
"dataset_id": result.dataset_id,
"title": result.title,
"file": relative,
"source_zip": source_zip,
"raster_member": result.raster_member,
"crs": result.crs,
"width": result.width,
"height": result.height,
"source_width": result.source_width,
"source_height": result.source_height,
"bounds_wgs84": list(result.bounds_wgs84),
"dtype": result.dtype,
"nodata": result.nodata,
"bytes": result.output_bytes,
"source_resolution": result.source_resolution,
}
[docs]
def prepare_bundle(
*,
layer_ids: list[str],
output_root: str | Path,
aoi_query: str | None = None,
aoi_name: str | None = None,
aoi_geojson: str | Path | None = None,
archive_root: str | Path | None = None,
femic_src: str | Path | None = None,
max_layers: int = DEFAULT_MAX_LAYERS,
max_area_ha: float = DEFAULT_MAX_AREA_HA,
public_url: str | None = None,
progress_callback: ProgressCallback | None = None,
cancel_check: CancelCheck | None = None,
) -> dict[str, Any]:
"""Resolve an AOI, clip selected rasters, and write a downloadable ZIP."""
unique_layers = list(dict.fromkeys(str(layer).strip() for layer in layer_ids if layer))
if not unique_layers:
raise BundleError("Select at least one raster layer.")
if len(unique_layers) > max_layers:
raise BundleError(
f"Select at most {max_layers} layers per demo bundle; requested {len(unique_layers)}."
)
_progress(
progress_callback,
{
"stage": "resolving_aoi",
"layer_total": len(unique_layers),
"completed": 0,
"failed": 0,
},
)
hbc = HectaresBC()
records = {}
for dataset_id in unique_layers:
record = hbc.get(dataset_id)
if record is None:
raise BundleError(f"Unknown dataset ID {dataset_id!r}.")
records[dataset_id] = record
root = Path(output_root).expanduser().resolve()
root.mkdir(parents=True, exist_ok=True)
bundle_id = _bundle_id()
bundle_dir = root / bundle_id
layers_dir = bundle_dir / "layers"
layers_dir.mkdir(parents=True)
if bool(aoi_query) == bool(aoi_geojson):
raise BundleError("Provide exactly one of aoi_query or aoi_geojson.")
if aoi_query:
try:
aoi_payload = resolve_aoi(
aoi_query,
name=aoi_name,
output_dir=bundle_dir / "aoi",
femic_src=femic_src,
)
except FemicBridgeError as exc:
raise BundleError(str(exc)) from exc
if aoi_payload.get("status") != "ok":
return {
"status": aoi_payload.get("status", "needs_name"),
"bundle_id": bundle_id,
"aoi": aoi_payload,
"message": "The AOI query is ambiguous or incomplete; choose a candidate name.",
}
aoi_path = Path(aoi_payload["saved_geojson"])
shutil.copy2(aoi_path, bundle_dir / "aoi.geojson")
aoi_metadata = {
"name": aoi_payload["name"],
"query": aoi_payload["query"],
"feature_count": aoi_payload["feature_count"],
"bbox_3005": aoi_payload["bbox_3005"],
"bbox_wgs84": aoi_payload["bbox_wgs84"],
"area_ha": aoi_payload["area_ha"],
"labels": aoi_payload.get("labels", []),
"package_title": aoi_payload.get("package_title"),
"resource_name": aoi_payload.get("resource_name"),
}
else:
source_aoi = Path(aoi_geojson).expanduser().resolve()
payload = _load_aoi_geojson(source_aoi)
shutil.copy2(source_aoi, bundle_dir / "aoi.geojson")
aoi_metadata = _aoi_metadata_from_file(bundle_dir / "aoi.geojson", aoi_name)
aoi_metadata["query"] = None
aoi_metadata["labels"] = []
aoi_payload = {"status": "ok", **aoi_metadata}
if aoi_metadata["area_ha"] > max_area_ha:
raise BundleError(
f"AOI is {aoi_metadata['area_ha']:,.0f} ha; the demo limit is "
f"{max_area_ha:,.0f} ha."
)
clipped: list[dict[str, Any]] = []
failures: list[dict[str, str]] = []
_progress(
progress_callback,
{
"stage": "clipping",
"layer_total": len(unique_layers),
"layer_index": 0,
"completed": 0,
"failed": 0,
},
)
for index, dataset_id in enumerate(unique_layers, start=1):
if cancel_check is not None and cancel_check():
raise BundleCancelled("Bundle canceled.")
_progress(
progress_callback,
{
"stage": "clipping",
"layer_total": len(unique_layers),
"layer_index": index,
"current_layer": dataset_id,
"completed": len(clipped),
"failed": len(failures),
},
)
try:
result = clip_raster_to_aoi(
dataset_id,
bundle_dir / "aoi.geojson",
layers_dir,
archive_root=archive_root,
)
clipped.append(
_sanitize_clip(result, bundle_dir, records[dataset_id].source_zip_path)
)
except (ClipError, OSError, ValueError) as exc:
failures.append({"dataset_id": dataset_id, "error": str(exc)})
_progress(
progress_callback,
{
"stage": "clipping",
"layer_total": len(unique_layers),
"layer_index": index,
"current_layer": dataset_id,
"completed": len(clipped),
"failed": len(failures),
},
)
if cancel_check is not None and cancel_check():
raise BundleCancelled("Bundle canceled.")
_progress(
progress_callback,
{
"stage": "packaging",
"layer_total": len(unique_layers),
"completed": len(clipped),
"failed": len(failures),
},
)
manifest = {
"schema_version": 1,
"bundle_id": bundle_id,
"generated_utc": datetime.now(UTC).isoformat(),
"status": "complete" if not failures else ("partial" if clipped else "failed"),
"aoi": aoi_metadata,
"layers": clipped,
"failures": failures,
"limits": {
"max_layers": max_layers,
"max_area_ha": max_area_ha,
},
}
(bundle_dir / "manifest.json").write_text(
json.dumps(manifest, indent=2) + "\n", encoding="utf-8"
)
(bundle_dir / "README.txt").write_text(
"HectaresBC clipped raster bundle\n"
"===============================\n\n"
f"AOI: {aoi_metadata['name']}\n"
f"Area: {aoi_metadata['area_ha']:,.1f} ha\n"
f"Layers: {len(clipped)}\n\n"
"Each GeoTIFF in layers/ is clipped to aoi.geojson and preserves the\n"
"source raster CRS, dtype, and nodata value. See manifest.json for\n"
"source ZIP/member provenance and clipping metadata.\n",
encoding="utf-8",
)
zip_path = root / f"hectaresbc-bundle-{bundle_id}.zip"
with zipfile.ZipFile(zip_path, "w", compression=zipfile.ZIP_DEFLATED) as archive:
for path in sorted(bundle_dir.rglob("*")):
if path.is_file():
archive.write(path, path.relative_to(bundle_dir).as_posix())
base_url = (public_url or "").rstrip("/")
download_url = f"{base_url}/api/bundles/{bundle_id}/download"
return {
**manifest,
"bundle_id": bundle_id,
"bundle_dir": str(bundle_dir),
"zip_path": str(zip_path),
"zip_bytes": zip_path.stat().st_size,
"download_name": zip_path.name,
"download_url": download_url,
}