# catalog/operations/utility/raster_to_pmtiles.yaml

id: utility_raster_to_pmtiles
name: Raster to PMTiles
description: >
  Convert raster data to PMTiles format for efficient web map serving.
  Generates web map tiles at multiple zoom levels with optional terrarium
  encoding for elevation data.
version: 1.0.0
category: utility
type: raster-to-tiles
default_implementation: native

inputs:
  - name: input_path
    type: raster
    format: geotiff
    description: Input raster file (COG or GeoTIFF)
    required: true

requires: {}  # structural — operates on any raster

outputs:
  - name: pmtiles
    type: tiles
    format: pmtiles
    description: PMTiles archive with generated tiles

params:
  min_zoom:
    type: integer
    default: 0
    description: Minimum zoom level
    min: 0
    max: 22
  max_zoom:
    type: integer
    default: 14
    description: Maximum zoom level
    min: 0
    max: 22
  encoding:
    type: enum
    default: auto
    enum: [auto, terrarium, rgb, rgba]
    description: >
      Tile encoding:
      - auto: detect from input (DEM -> terrarium, imagery -> rgb)
      - terrarium: RGB encoding for elevation data
      - rgb: standard RGB imagery
      - rgba: RGBA imagery with alpha
  format:
    type: enum
    default: webp
    enum: [webp, png, jpeg]
    description: Output tile image format
  resampling:
    type: enum
    default: bilinear
    enum: [nearest, bilinear, cubic, lanczos, average]
    description: Resampling method for tile generation
  tile_size:
    type: integer
    default: 512
    description: Tile size in pixels
    enum: [256, 512]
  precision_by_zoom:
    type: boolean
    default: true
    description: >
      For terrarium encoding, apply zoom-dependent precision rounding
      to improve compression (mapterhorn optimization)

cache_policy:
  ttl_days: 365
  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:
  python:
    function: geo.tiles.raster_to_pmtiles_sync
    dispatch: folia/compute.py _BUILTIN_OP_MAP

display_hints:
  map:
    renderer: maplibre
    source_type: pmtiles

ui:
  icon: grid
  color: "#00CED1"