# Optical Calibration Operation
#
# Convert satellite imagery from digital numbers (DN) to physical values
# like top-of-atmosphere reflectance. Essential preprocessing step.

id: imagery_optical_calibration
name: Optical Calibration
description: >
  Convert satellite imagery from digital numbers to physical values
  (radiance or reflectance). Required preprocessing for quantitative
  analysis, time series comparison, and multi-sensor fusion.
version: 1.0.0
category: imagery
type: raster-to-raster
default_implementation: otb

inputs:
  - name: image
    type: raster
    format: cog
    description: >
      Input satellite image with embedded calibration metadata.
      Supports Sentinel-2, Landsat, SPOT, Pleiades, and other sensors
      with standard metadata formats.
    required: true

# Sensor-agnostic: calibration works on any optical sensor with embedded
# calibration metadata. No specific bands or concepts required — the op
# rescales whatever bands are present.
requires: {}

outputs:
  - name: calibrated
    type: raster
    format: cog
    dtype: float32
    # concept: omitted — output is the same concept as the input (still
    # optical reflectance / radiance), just rescaled to physical units.
    description: >
      Calibrated image. Values depend on calibration level:
      - TOA reflectance: 0-1 (or 0-1000 if milli=true)
      - Radiance: sensor-specific units

params:
  level:
    type: enum
    enum: [toa, toc, radiance]
    default: toa
    description: >
      Calibration level:
      - toa: Top of atmosphere reflectance (default, most common)
      - toc: Top of canopy (surface reflectance, requires atmosphere model)
      - radiance: At-sensor radiance

  milli:
    type: boolean
    default: false
    description: >
      Output in milli-reflectance (0-1000 integer) instead of 0-1 float.
      Reduces file size while maintaining precision for most applications.

  clamp:
    type: boolean
    default: true
    description: Clamp output values to valid range (0-1 for reflectance)

  # Atmospheric correction parameters (for toc level)
  atmosphere_model:
    type: enum
    enum: [tropical, midlatitude_summer, midlatitude_winter, subarctic_summer, subarctic_winter, us_standard]
    default: us_standard
    description: Atmospheric model for TOC correction (toc level only)

  aerosol_model:
    type: enum
    enum: [continental, maritime, urban, desert]
    default: continental
    description: Aerosol model for TOC correction (toc level only)

  visibility:
    type: number
    default: 23.0
    description: Visibility in km for TOC correction (toc level only)
    min: 1.0
    max: 100.0

execution:
  realtime_max_km2: 500
  cost_per_km2: 0.001
  time_per_km2_sec: 0.3
  memory_profile: low

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

display_hints:
  map:
    renderer: maplibre
    palette: sequential

cache_policy:
  ttl_days: 90
  invalidate_on: [source_update]

examples:
  - name: Sentinel-2 TOA
    description: Convert Sentinel-2 L1C to TOA reflectance
    inputs:
      image: "S2A_L1C_T10SEG.tif"
    params:
      level: toa
      clamp: true

  - name: Landsat milli-reflectance
    description: Convert Landsat to milli-reflectance for efficient storage
    inputs:
      image: "LC08_L1TP.tif"
    params:
      level: toa
      milli: true