# catalog/operations/analysis/point_sample.yaml

id: analysis_point_sample
name: Point Sampling
description: >
  Returns the value of the pixel containing each input point. Pixel
  lookup — no interpolation. Matches QGIS Identify, GDAL gdallocationinfo,
  rasterio src.sample(), and GEE Image.sample() / Image.reduceRegion(point).
  This is what "sample at point" means in the geospatial idiom.

  For sub-pixel bilinear interpolation over a continuous field (DEM,
  temperature surface, etc.), use `analysis_point_interpolate` instead.
version: 1.0.0
category: analysis
type: raster-vector-to-table
default_implementation: native

inputs:
  - name: raster
    type: raster
    format: geotiff
    description: Input raster to sample
    required: true
  - name: points
    type: vector
    format: geojson
    geometry: Point
    description: Sample point locations
    required: true

# Structural: pixel lookup at points works on any raster. Output carries
# the source raster's concept; no concept declared here.

outputs:
  - name: sampled
    type: vector
    format: geojson
    geometry: Point
    description: Points with sampled raster values as properties

params:
  property_name:
    type: string
    default: value
    description: Name of the property to store sampled values

cache_policy:
  ttl_days: 30
  invalidate_on: [source_update, points_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:
    function: stats_ops::point_sample
    handle_function: h_point_sample
  js:
    function: analysis_point_sample
  python:
    function: geo.stats.sample
    dispatch: folia/compute.py _BUILTIN_OP_MAP

display_hints:
  map:
    renderer: maplibre
    type: circle
    paint:
      circle-radius: 5
      circle-color: "#FF1493"
  table:
    renderer: tanstack-table

ui:
  icon: crosshair
  color: "#FF1493"