# catalog/operations/raster/rasterize.yaml

id: raster_rasterize
name: Rasterize
description: >
  Burn vector features into a raster grid. Each feature can contribute a
  constant value or a value read from a feature attribute. A reference raster
  defines the output grid (shape, CRS, transform). Useful for converting
  polygon-aggregated scores into a common raster grid for map algebra.
version: 1.0.0
category: raster
type: vector-to-raster
default_implementation: native

inputs:
  - name: features
    type: vector
    format: [geojson, gpkg, shp]
    description: Vector features to rasterize (polygons, lines, or points)
    required: true
  - name: reference
    type: raster
    format: geotiff
    description: >
      Reference raster that defines the output grid (shape, transform, CRS).
      Required unless shape, transform, and crs are provided via params.
    required: false

requires: {}  # structural — operates on any vector + reference raster

outputs:
  - name: rasterized
    type: raster
    format: cog
    dtype: float32
    description: Raster grid with burned-in feature values

params:
  attribute:
    type: string
    description: >
      Feature attribute to use as the burn value. If not specified, uses
      the constant `fill_value` for all features.
  fill_value:
    type: number
    default: 1.0
    description: >
      Constant value to burn for each feature (used when attribute is not set).
  background:
    type: number
    default: 0.0
    description: Value for pixels not covered by any feature.
  all_touched:
    type: boolean
    default: false
    description: >
      If true, all pixels touched by a geometry are burned (not just those
      whose center falls inside). Useful for thin line features.
  merge_alg:
    type: string
    default: replace
    enum: [replace, add]
    description: >
      How to combine values when multiple features overlap a pixel.
      'replace' uses the last feature's value; 'add' sums them.
  dtype:
    type: string
    default: float32
    enum: [float32, float64, int32, uint8]
    description: Output data type.

cache_policy:
  ttl_days: 30
  invalidate_on: [source_update, param_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:
  rust-wasm:
    handle_function: h_raster_rasterize
  js:
    function: raster_rasterize
  python:
    function: geo.raster.rasterize
    dispatch: folia/compute.py _BUILTIN_OP_MAP

display_hints:
  map:
    renderer: maplibre
    palette: viridis
    opacity: 0.8
  info:
    fields: [value]
    section: Rasterized

ui:
  icon: grid
  color: "#6366F1"