from grdl.IO import SICDReader
from grdl.data_prep import ChipExtractor
from grdl.image_processing.sar import SublookDecomposition

# IO: load the image and metadata
with SICDReader('image.nitf') as reader:
    rows, cols = reader.get_shape()

    # data_prep: plan a center chip (handles boundary snapping)
    extractor = ChipExtractor(nrows=rows, ncols=cols)
    region = extractor.chip_at_point(rows // 2, cols // 2,
                                     row_width=2048, col_width=2048)

    # IO: read only the planned region
    chip = reader.read_chip(region.row_start, region.row_end,
                            region.col_start, region.col_end)

    # image_processing: decompose into sub-aperture looks
    sublook = SublookDecomposition(reader.metadata, num_looks=3)
    looks = sublook.decompose(chip)

from grdl.IO import BIOMASSL1Reader
from grdl.geolocation.sar.gcp import GCPGeolocation
import numpy as np

with BIOMASSL1Reader('path/to/BIO_S3_SCS__1S_...') as reader:
    print(f"Polarizations: {reader.metadata['polarizations']}")
    rows, cols = reader.get_shape()

    # Read HH channel (complex-valued)
    hh = reader.read_chip(0, rows, 0, cols, bands=[0])
    hh_db = 20 * np.log10(np.abs(hh) + 1e-10)

    # Pixel-to-geographic coordinate transform
    geo = GCPGeolocation(
        reader.metadata['gcps'], (rows, cols),
    )
    lat, lon, _ = geo.image_to_latlon(rows // 2, cols // 2)
    print(f"Center: ({lat:.6f}, {lon:.6f})")

from grdl.IO import BIOMASSCatalog

catalog = BIOMASSCatalog('/data/biomass')

# Search the MAAP STAC catalog
products = catalog.query_esa(
    bbox=(115.5, -31.5, 116.8, -30.5),
    product_type="S3_SCS__1S",
    max_results=10,
)

# Download a product (uses OAuth2 via ~/.config/geoint/credentials.json)
catalog.download_product(products[0]['id'], extract=True)
catalog.close()

from grdl.geolocation.sar.gcp import GCPGeolocation
from grdl.geolocation.sar.sicd import SICDGeolocation
from grdl.geolocation.eo.affine import AffineGeolocation
import numpy as np

# --- GCPGeolocation (BIOMASS SAR via Delaunay interpolation) ---
from grdl.IO import open_biomass

with open_biomass('path/to/product') as reader:
    geo = GCPGeolocation(
        reader.metadata['gcps'],
        (reader.metadata['rows'], reader.metadata['cols']),
    )

    # Single pixel — returns (3,) ndarray [lat, lon, h]; tuple unpacking works
    lat, lon, height = geo.image_to_latlon(500, 1000)

    # Batch of pixels — pass (N, 2) stacked array, returns (N, 3)
    pixels = np.array([[100, 400], [200, 500], [300, 600]])
    coords = geo.image_to_latlon(pixels)   # shape (3, 3) — each row is [lat, lon, h]

    # Inverse: geographic to pixel — scalar returns (2,) [row, col]
    row, col = geo.latlon_to_image(-31.05, 116.19)

# --- AffineGeolocation (geocoded rasters: GeoTIFF, SAR GRD, etc.) ---
geo = AffineGeolocation('scene.tif')
lat, lon, height = geo.image_to_latlon(100, 200)

# --- SICDGeolocation (SICD complex SAR imagery) ---
from grdl.IO.sar import SICDReader

with SICDReader('image.nitf') as reader:
    geo = SICDGeolocation(reader.metadata)
    lat, lon, height = geo.image_to_latlon(500, 1000)

from grdl.geolocation import create_geolocation, ChipGeolocation

# Auto-detect geolocation from any supported reader
geo = create_geolocation(reader)

# Wrap for a chip starting at (row_offset, col_offset)
chip_geo = ChipGeolocation(geo, row_offset=1000, col_offset=2000)
lat, lon, h = chip_geo.image_to_latlon(0, 0)  # maps to (1000, 2000) in full image

from grdl.geolocation.elevation import (
    DTEDElevation, GeoTIFFDEM, ConstantElevation, GeoidCorrection,
)

# DTED tiles (directory of .dt1/.dt2 files)
# Default is bicubic interpolation with cross-tile boundary stitching
dem = DTEDElevation('/data/dted/')

# GeoTIFF DEM (single file, bicubic default)
dem = GeoTIFFDEM('/data/srtm_30m.tif')

# Fixed-height fallback (e.g., sea-level for ocean scenes)
dem = ConstantElevation(height=0.0)

# EGM96 geoid undulation correction
geoid = GeoidCorrection('/data/egm96.tif')

# Pass DEM path to any Geolocation subclass (interpolation= sets DEM spline order)
geo = AffineGeolocation('scene.tif', dem_path='/data/srtm_30m.tif')
geo = SICDGeolocation(metadata, dem_path='/data/dted/', interpolation=1)  # bilinear

from grdl.IO import BIOMASSL1Reader
from grdl.image_processing import PauliDecomposition

with BIOMASSL1Reader('path/to/product') as reader:
    rows, cols = reader.get_shape()
    shh = reader.read_chip(0, rows, 0, cols, bands=[0])
    shv = reader.read_chip(0, rows, 0, cols, bands=[1])
    svh = reader.read_chip(0, rows, 0, cols, bands=[2])
    svv = reader.read_chip(0, rows, 0, cols, bands=[3])

pauli = PauliDecomposition()
components = pauli.decompose(shh, shv, svh, svv)

# Complex-valued components (phase preserved)
surface = components['surface']            # (S_HH + S_VV) / sqrt(2)
double_bounce = components['double_bounce']  # (S_HH - S_VV) / sqrt(2)
volume = components['volume']              # (S_HV + S_VH) / sqrt(2)

# Convert to display representations
db = pauli.to_db(components)          # Dict of dB arrays
rgb = pauli.to_rgb(components)        # (rows, cols, 3) float32 [0, 1]

from grdl.IO.sar import SICDReader
from grdl.image_processing import SublookDecomposition

with SICDReader('image.nitf') as reader:
    image = reader.read_full()                        # complex64

    # 3 azimuth sub-looks, 10% overlap, deweight original apodization
    sublook = SublookDecomposition(
        reader.metadata, num_looks=3, overlap=0.1, deweight=True,
    )
    looks = sublook.decompose(image)                  # (3, rows, cols) complex

    # Convert to display representations
    mag = sublook.to_magnitude(looks)                 # |z|
    db = sublook.to_db(looks)                         # 20*log10(|z|)
    pwr = sublook.to_power(looks)                     # |z|^2

    # GPU-accelerated path (optional, requires torch)
    import torch
    image_gpu = torch.from_numpy(image).cuda()
    looks_gpu = sublook.decompose(image_gpu)          # returns numpy

from grdl.IO.sar import SICDReader
from grdl.data_prep import ChipExtractor
from grdl.image_processing.sar import SublookDecomposition, CSIProcessor
from grdl.image_processing.sar.dominance import compute_dominance
import numpy as np

with SICDReader('image.nitf') as reader:
    meta = reader.metadata
    rows, cols = reader.get_shape()
    extractor = ChipExtractor(rows, cols)
    region = extractor.chip_at_point(rows // 2, cols // 2, 5000, 5000)
    chip = reader.read_chip(region.row_start, region.row_end,
                            region.col_start, region.col_end)

# Sub-aperture decomposition
sublook = SublookDecomposition(meta, num_looks=7, dimension='azimuth')
looks = sublook.decompose(chip)                  # (7, rows, cols) complex

# Dominance ratio: high values = single look dominates
dominance = compute_dominance(looks, window_size=7, dom_window=3)

# Threshold detections
det_mask = dominance > (np.mean(dominance) + 3.0 * np.std(dominance))

# CSI RGB composite
csi = CSIProcessor(meta, dimension='azimuth', normalization='log')
csi_rgb = csi.apply(chip)                        # (rows, cols, 3) float32 [0, 1]

from grdl.image_processing.detection.cfar import (
    CACFARDetector,   # Cell-Averaging
    GOCFARDetector,   # Greatest-Of
    SOCFARDetector,   # Smallest-Of
    OSCFARDetector,   # Ordered-Statistics
)

detector = CACFARDetector(
    guard_cells=2, background_cells=4, pfa=1e-6,
)
detection_set = detector.detect(image)

for det in detection_set:
    print(f"  {det.pixel_geometry.centroid}: conf={det.confidence:.2f}")

from grdl.interpolation import (
    LanczosInterpolator,      # Windowed sinc (Lanczos kernel)
    KaiserSincInterpolator,   # Kaiser-windowed sinc
    LagrangeInterpolator,     # Lagrange polynomial
    FarrowInterpolator,       # Farrow structure (variable delay)
    PolyphaseInterpolator,    # Polyphase FIR (efficient resampling)
    ThiranDelayFilter,        # Thiran IIR allpass (fractional delay)
)

# Resample a signal by rational factor P/Q
interp = PolyphaseInterpolator(up=4, down=3, num_taps=64)
resampled = interp.resample(signal)

# Fractional-sample delay
delay = ThiranDelayFilter(delay=0.3, order=4)
delayed = delay.apply(signal)

from grdl.image_processing.sar.image_formation import (
    PolarFormatAlgorithm,    # Spotlight PFA
    RangeDopplerAlgorithm,   # Stripmap RDA
    FastBackProjection,      # Time-domain backprojection (FFBP)
    StripmapPFA,             # Stripmap PFA (subaperture)
)

from grdl.IO.eo.nitf import EONITFReader
from grdl.geolocation.eo.rpc import RPCGeolocation
from grdl.geolocation.eo.rsm import RSMGeolocation

with EONITFReader('worldview.ntf') as reader:
    print(f"RPC: {reader.has_rpc}, RSM: {reader.has_rsm}")

    if reader.has_rpc:
        geo = RPCGeolocation.from_reader(reader)
        lat, lon, h = geo.image_to_latlon(2048, 2048, height=100.0)
        row, col = geo.latlon_to_image(lat, lon, h)

    if reader.has_rsm:
        geo = RSMGeolocation.from_reader(reader)
        lat, lon, h = geo.image_to_latlon(2048, 2048)

from grdl.IO.sar import SICDReader
from grdl.geolocation.sar.sicd import SICDGeolocation

with SICDReader('image.nitf') as reader:
    # Native backend (no sarpy dependency)
    geo = SICDGeolocation(reader.metadata, backend='native')
    lat, lon, h = geo.image_to_latlon(500, 1000)

    # With calibration adjustments
    import numpy as np
    geo = SICDGeolocation(
        reader.metadata,
        backend='native',
        range_bias=2.5,
        delta_arp=np.array([0.1, -0.2, 0.05]),
    )

from grdl.image_processing.ortho import orthorectify, GeographicGrid

# DEM belongs on the geolocation object — the orthorectifier
# maps coordinates *through* the geolocation, never queries DEM directly
geo.elevation = dem

# Recommended: orthorectify() function (keyword arguments, Pythonic)
result = orthorectify(
    geolocation=geo,
    reader=reader,
    interpolation='bilinear',
)
ortho = result.data                         # ndarray
result.save_geotiff('ortho.tif')            # georeferenced output

# With explicit grid and ENU coordinates
result = orthorectify(
    geolocation=geo,
    reader=reader,
    enu_grid=dict(pixel_size_m=1.0),
)

# Direct control: Orthorectifier for custom workflows
from grdl.image_processing.ortho import Orthorectifier

grid = GeographicGrid.from_geolocation(geo, pixel_size_lat=0.001,
                                       pixel_size_lon=0.001)
ortho = Orthorectifier(geo, grid, interpolation='nearest')
ortho.compute_mapping()
result = ortho.apply(image, nodata=np.nan)

from grdl.image_processing import Detection, DetectionSet, Geometry, OutputSchema, OutputField

# Define what your detector outputs
schema = OutputSchema([
    OutputField('confidence', 'float', 'Detection confidence [0, 1]'),
    OutputField('label', 'str', 'Target class label'),
])

# Create geo-registered detections
det = Detection(
    geometry=Geometry.point(row=500, col=300, lat=-31.05, lon=116.19),
    properties={'confidence': 0.92, 'label': 'vehicle'},
)
results = DetectionSet(output_schema=schema)
results.append(det)

# Export to GeoJSON FeatureCollection
geojson = results.to_geojson()

from grdl.image_processing import (
    ImageTransform, processor_version, processor_tags,
    ImageModality, ProcessorCategory,
)

@processor_version('1.0.0')
@processor_tags(
    modalities=[ImageModality.SAR, ImageModality.PAN],
    category=ProcessorCategory.FILTERS,
    description='Adaptive edge-preserving smoothing filter',
)
class MyFilter(ImageTransform):
    ...

from typing import Annotated
from grdl.image_processing import (
    ImageTransform, processor_version, processor_tags,
    Range, Options, Desc,
    ImageModality, ProcessorCategory,
)

@processor_version('1.0.0')
@processor_tags(modalities=[ImageModality.PAN], category=ProcessorCategory.FILTERS)
class AdaptiveFilter(ImageTransform):
    """Edge-preserving smoothing with tunable parameters."""

    sigma: Annotated[float, Range(min=0.1, max=100.0),
                     Desc('Gaussian kernel sigma')] = 2.0
    method: Annotated[str, Options('bilateral', 'guided'),
                      Desc('Filter algorithm')] = 'bilateral'
    iterations: Annotated[int, Range(min=1, max=20),
                          Desc('Number of filter passes')] = 1

    def apply(self, source, **kwargs):
        params = self._resolve_params(kwargs)
        sigma = params['sigma']
        method = params['method']
        iterations = params['iterations']
        # ... implementation

from grdl.IO import GeoTIFFReader
from grdl.data_prep import Tiler, ChipExtractor, Normalizer

# -- Point-centered chip extraction with IO reader --
with GeoTIFFReader('scene.tif') as reader:
    rows, cols = reader.get_shape()
    extractor = ChipExtractor(nrows=rows, ncols=cols)

    # Plan a 256x256 chip around a target (boundary-snapped)
    region = extractor.chip_at_point(500, 1000, row_width=256, col_width=256)

    # Read only the planned region from disk
    chip = reader.read_chip(region.row_start, region.row_end,
                            region.col_start, region.col_end)

# -- Whole-image tiling for batch processing --
with GeoTIFFReader('large_scene.tif') as reader:
    rows, cols = reader.get_shape()
    extractor = ChipExtractor(nrows=rows, ncols=cols)

    for region in extractor.chip_positions(row_width=512, col_width=512):
        chip = reader.read_chip(region.row_start, region.row_end,
                                region.col_start, region.col_end)
        # Process each chip...

# -- Stride-based overlapping tiles --
tiler = Tiler(nrows=1000, ncols=2000, tile_size=256, stride=128)
tile_regions = tiler.tile_positions()

# -- Normalize to [0, 1] range --
norm = Normalizer(method='minmax')
normalized = norm.normalize(image)

from grdl.image_processing import PauliDecomposition, SublookDecomposition

# Version
print(PauliDecomposition.__processor_version__)   # '0.1.0'

# Tags (modalities, category, description)
print(SublookDecomposition.__processor_tags__)
# {'modalities': (<ImageModality.SAR>,), 'category': None, ...}

# Tunable parameters (ParamSpec introspection)
for spec in SublookDecomposition.__param_specs__:
    print(f"  {spec.name}: {spec.param_type.__name__}, default={spec.default}")

# GPU compatibility flag
print(SublookDecomposition.__gpu_compatible__)     # False

from grdl.exceptions import GrdlError, ValidationError, ProcessorError, DependencyError

try:
    result = processor.apply(bad_input)
except ValidationError as e:
    print(f"Invalid input: {e}")
except ProcessorError as e:
    print(f"Processing failed: {e}")