# catalog/operations/utility/pmtiles_merge.yaml

id: utility_pmtiles_merge
name: PMTiles Merge
description: >
  Merge multiple PMTiles cell files into a single file with overview tiles.
  Generates overview tiles at lower zoom levels by downsampling higher-zoom
  tiles. For terrain data, properly decodes elevation values before averaging.
version: 1.0.0
category: utility
type: tiles-to-tiles
default_implementation: native

inputs:
  - name: input_cells
    type: tiles[]
    format: pmtiles
    description: List of PMTiles cell files to merge
    required: true

requires: {}  # structural — operates on any tile archive

outputs:
  - name: merged
    type: tiles
    format: pmtiles
    description: Merged PMTiles file with all tiles and overviews

params:
  overview_min_zoom:
    type: integer
    default: 0
    description: Minimum zoom level for generated overviews
    min: 0
    max: 22
  overview_max_zoom:
    type: integer
    default: 9
    description: Maximum zoom level for generated overviews
    min: 0
    max: 22
  encoding:
    type: enum
    default: auto
    enum: [auto, terrarium, rgb]
    description: >
      Tile encoding type:
      - auto: detect from first tile
      - terrarium: elevation data (decode/encode properly)
      - rgb: standard imagery (resample directly)
  format:
    type: enum
    default: webp
    enum: [webp, png]
    description: Output tile format
  tile_size:
    type: integer
    default: 512
    description: Tile size in pixels
    enum: [256, 512]
  preserve_cell_tiles:
    type: boolean
    default: true
    description: Include original cell tiles in output

cache_policy:
  ttl_days: 365
  invalidate_on: [source_update]

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

display_hints:
  map:
    renderer: maplibre
    source_type: pmtiles

ui:
  icon: layers
  color: "#9932CC"