# catalog/operations/raster/clip.yaml

id: raster_clip
name: Clip Raster
description: >
  Clip raster to a geometry or bounding box. Can use polygons, bounding boxes,
  or other vector geometries to extract a subset of the raster data.
version: 1.0.0
category: raster
type: raster-to-raster
default_implementation: native

inputs:
  - name: raster
    type: raster
    format: geotiff
    description: Input raster to clip
    required: true
  - name: geometry
    type: vector
    format: geojson
    description: >
      Clipping geometry as GeoJSON polygon, bounding box [min_lon, min_lat,
      max_lon, max_lat], or shapely geometry
    required: true

requires: {}  # structural — operates on any raster

outputs:
  - name: clipped
    type: raster
    format: cog
    description: Clipped raster

params:
  all_touched:
    type: boolean
    default: false
    description: >
      If true, include all pixels touched by geometry.
      If false, only pixels with center inside geometry.
  crop:
    type: boolean
    default: true
    description: >
      If true, crop output to geometry bounds.
      If false, maintain original extent with masked values outside.

granularity:
  min_resolution_m: 0.1
  max_resolution_m: 100000
  output_resolution: inherit
  requires_continuous: false
  suitable_aoi_km2:
    min: 0.001
    max: 1000000
  realtime_max_km2: 2000

execution:
  realtime_max_km2: 2000
  cost_per_km2: 0.0001
  time_per_km2_sec: 0.05
  memory_profile: low
  profile:
    cpu: low
    memory: low
    io: high
  scaling:
    model: linear
    parallelizable: true
    min_chunk_km2: 1

cache_policy:
  ttl_days: 30
  invalidate_on: [source_update, geometry_change]

# backends: audited 2026-08-14 (defect 50). A key means a runtime that DISPATCHES this op —
# folia-engine `dispatch_op` (products/sdk/folia-engine/src/lib.rs), a `registerOp`/OP_TABLE
# entry in packages/compute, `_BUILTIN_OP_MAP` in folia/compute.py, or a backend manifest
# (folia/backends/*/backend.yaml).
backends:
  js:
    function: raster_clip
  python:
    function: geo.raster.clip
    dispatch: folia/compute.py _BUILTIN_OP_MAP

display_hints:
  map:
    renderer: maplibre

ui:
  icon: crop
  color: "#FF6347"