# catalog/operations/utility/terrarium_encode.yaml

id: utility_terrarium_encode
name: Terrarium Encode
description: >
  Encode elevation data to Terrarium RGB format. Terrarium encoding stores
  elevation in RGB channels: elevation = (R * 256 + G + B / 256) - 32768.
  Supports optional precision optimization by zoom level for better compression.
version: 1.0.0
category: utility
type: array-to-array
default_implementation: native

inputs:
  - name: data
    type: array
    format: numpy
    dtype: float32
    description: Elevation data in meters
    required: true

requires: {}  # structural — encodes any float32 elevation array

outputs:
  - name: rgb
    type: array
    format: numpy
    dtype: uint8
    description: Terrarium-encoded RGB array (height, width, 3)

params:
  zoom:
    type: integer
    description: Tile zoom level (for precision optimization)
    min: 0
    max: 22
  precision_by_zoom:
    type: boolean
    default: true
    description: Apply zoom-dependent precision rounding for better compression

cache_policy:
  ttl_days: 365
  invalidate_on: []

# 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.encode_terrarium
    dispatch: folia/compute.py _BUILTIN_OP_MAP

display_hints:
  map:
    renderer: maplibre
    encoding: terrarium

ui:
  icon: code
  color: "#708090"