# catalog/operations/analysis/h3_index.yaml

id: analysis_h3_index
name: H3 Hexagonal Index
description: >
  Index raster or vector data onto an H3 hexagonal grid. For a single raster,
  samples values at H3 cell centroids. For a stack of rasters with a shared
  grid, aggregates each raster into one column of a wide H3-indexed table
  (the publisher pattern — see `rasters` input). For vectors, assigns H3
  cell IDs to point or polygon features. Enables consistent spatial
  comparison across regions at configurable resolutions.
version: 1.1.0
domain: geo
category: analysis
type: raster-to-table

inputs:
  raster:
    type: raster
    description: Single raster to sample at H3 cell centroids
    required: false
  rasters:
    type: array
    items:
      type: raster
    description: >
      Stack of N rasters with shared grid (publisher mode). Each raster
      becomes one column in a wide H3-indexed output table. The pixel→H3
      lookup is computed once from the first raster and reused — so cost
      scales with N, not pixel count.
    required: false
  vectors:
    type: vector
    description: Vector features to assign H3 cell IDs
    required: false

# Structural: H3 indexing / aggregation works on any raster or vector.
# Output is H3-indexed tabular data, no specific concept. requires: omitted.

params:
  resolution:
    type: integer
    description: H3 resolution (0-15). Auto-detected from pixel size if null.
    required: false
    default: null
    min: 0
    max: 15
  stats:
    type: array
    description: >
      Aggregation statistics for single-raster mode. Applied to all pixels
      that fall within each H3 cell.
    required: false
    default: [mean]
  column_names:
    type: array
    items:
      type: string
    description: >
      Output column names for stack mode (one per `rasters` element). If
      omitted, names are derived from raster filenames.
    required: false
  aggregation:
    type: string
    description: >
      Stack-mode aggregation. "sum" for additive measurements (area, count,
      mass — values across pixels in a cell are summed); "mean" for intensive
      measurements (temperature, suitability index — values are averaged).
    enum: [sum, mean]
    default: sum
    required: false
  nodata_filter:
    type: string
    description: >
      Stack-mode source-value filter: "positive" (keep > 0; standard for area
      / count), "finite" (drop NaN + nodata sentinel), or "none" (pass
      through; caller has pre-cleaned).
    enum: [positive, finite, none]
    default: positive
    required: false

output:
  type: table
  description: >
    Single-raster mode → table with h3_cell_id + per-stat columns.
    Stack mode → wide table with h3_index (int64, sorted ascending) and
    one column per input raster, named per `column_names`.

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

display_hints:
  map:
    type: hexgrid
    palette: viridis
    title: H3 Index
  table:
    sort_by: value
    order: desc