# kassoulet/karios architecture

> Architecture diagram of the GitHub repository kassoulet/karios, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kassoulet/karios
- Repository: https://github.com/kassoulet/karios

## Overview

KARIOS is a Python tool and library for assessing geometric shifts between monitored and reference Earth-observation images. The principal workflow accepts images and optional masks or DEMs, loads and checks the rasters, performs feature matching, then computes accuracy statistics and produces graphical and HTML reports. The README also documents optional large-shift detection and altitude-based analysis. The graph follows the CLI/API and module references shown in the supplied excerpts and SOURCE INDEX; unsampled implementation details are represented only where documented.

Main entry points: [`karios/api/core.py`](https://github.com/kassoulet/karios/blob/develop/karios/api/core.py) (Processing API), [`karios/core/image.py`](https://github.com/kassoulet/karios/blob/develop/karios/core/image.py) (Raster access), [`karios/matcher/klt.py`](https://github.com/kassoulet/karios/blob/develop/karios/matcher/klt.py) (KLT matching), [`karios/cli/commands.py`](https://github.com/kassoulet/karios/blob/develop/karios/cli/commands.py) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and configuration"]
  node_cli["CLI commands<br/>[commands.py]"]
  node_api["Processing API<br/>[core.py]"]
  node_runtime_config["Runtime settings<br/>[config.py]"]
  node_processing_config["Processing settings<br/>[configuration.py]"]
end

subgraph group_processing["Raster and matching"]
  node_raster["Raster access<br/>[image.py]"]
  node_radiometry["Radiometry conversion<br/>[radiometry.py]"]
  node_global_align["Coarse alignment<br/>[global_align.py]"]
  node_klt["KLT matching<br/>[klt.py]"]
  node_coarse_fine["Coarse-to-fine matching<br/>[coarse_to_fine.py]"]
  node_large_offset["Large-shift detection<br/>[large_offset.py]"]
  node_zncc["ZNCC scoring<br/>[zncc_service.py]"]
  node_mutual_info["Mutual information"]
end

subgraph group_analysis["Accuracy analysis"]
  node_statistics["Accuracy statistics"]
  node_chip_service["Keypoint chips<br/>[chip_service.py]"]
end

subgraph group_reporting["Reports and products"]
  node_html_report["HTML report<br/>[html_report.py]"]
  node_product_generator["Product generation"]
  node_overview_plot["Error overview<br/>[overview_plot.py]"]
  node_coverage_plot["Point coverage<br/>[coverage_plot.py]"]
  node_shift_plots["Displacement plots"]
  node_altitude_plot["Altitude analysis"]
  node_ce_plot["Circular error plot"]
end

node_user(("Analyst"))

node_user -->|"runs analysis"| node_cli
node_cli -->|"invokes processing"| node_api
node_cli -->|"loads settings"| node_processing_config
node_api -->|"uses runtime settings"| node_runtime_config
node_api -->|"uses processing settings"| node_processing_config
node_api -->|"loads and checks rasters"| node_raster
node_api -->|"runs matching"| node_klt
node_api -->|"detects large shifts"| node_large_offset
node_api -->|"computes match scores"| node_zncc
node_api -->|"computes match scores"| node_mutual_info
node_api -->|"computes accuracy"| node_statistics
node_api -->|"generates keypoint chips"| node_chip_service
node_api -->|"generates report"| node_html_report
node_api -->|"generates products"| node_product_generator
node_api -->|"creates overview"| node_overview_plot
node_api -->|"creates coverage plot"| node_coverage_plot
node_api -->|"creates accuracy plot"| node_ce_plot
node_api -->|"creates displacement plots"| node_shift_plots
node_api -->|"creates altitude plot"| node_altitude_plot
node_klt -->|"uses tracker"| node_coarse_fine
node_klt -->|"converts image values"| node_radiometry
node_klt -->|"reads image data"| node_raster
node_global_align -->|"converts image values"| node_radiometry
node_global_align -->|"uses raster images"| node_raster
node_large_offset -->|"shifts image"| node_raster
node_zncc -->|"extracts image patches"| node_raster
node_mutual_info -->|"uses raster images"| node_raster
node_statistics -->|"uses analysis settings"| node_processing_config
node_ce_plot -->|"uses accuracy metrics"| node_statistics
node_coverage_plot -->|"uses image extent"| node_raster
node_overview_plot -->|"uses image data"| node_raster
node_shift_plots -->|"uses image data"| node_raster
node_altitude_plot -->|"uses image data"| node_raster
node_user -.->|"calls library directly"| node_api

click node_cli "https://github.com/kassoulet/karios/blob/develop/karios/cli/commands.py"
click node_api "https://github.com/kassoulet/karios/blob/develop/karios/api/core.py"
click node_runtime_config "https://github.com/kassoulet/karios/blob/develop/karios/api/config.py"
click node_processing_config "https://github.com/kassoulet/karios/blob/develop/karios/core/configuration.py"
click node_raster "https://github.com/kassoulet/karios/blob/develop/karios/core/image.py"
click node_radiometry "https://github.com/kassoulet/karios/blob/develop/karios/core/radiometry.py"
click node_global_align "https://github.com/kassoulet/karios/blob/develop/karios/matcher/global_align.py"
click node_klt "https://github.com/kassoulet/karios/blob/develop/karios/matcher/klt.py"
click node_coarse_fine "https://github.com/kassoulet/karios/blob/develop/karios/matcher/coarse_to_fine.py"
click node_large_offset "https://github.com/kassoulet/karios/blob/develop/karios/matcher/large_offset.py"
click node_zncc "https://github.com/kassoulet/karios/blob/develop/karios/matcher/zncc_service.py"
click node_mutual_info "https://github.com/kassoulet/karios/blob/develop/karios/matcher/mutual_info_service.py"
click node_statistics "https://github.com/kassoulet/karios/blob/develop/karios/accuracy_analysis/accuracy_statistics.py"
click node_chip_service "https://github.com/kassoulet/karios/blob/develop/karios/report/chip_service.py"
click node_html_report "https://github.com/kassoulet/karios/blob/develop/karios/report/html_report.py"
click node_product_generator "https://github.com/kassoulet/karios/blob/develop/karios/report/product_generator.py"
click node_overview_plot "https://github.com/kassoulet/karios/blob/develop/karios/report/overview_plot.py"
click node_coverage_plot "https://github.com/kassoulet/karios/blob/develop/karios/report/coverage_plot.py"
click node_shift_plots "https://github.com/kassoulet/karios/blob/develop/karios/report/shift_by_row_col_plot.py"
click node_altitude_plot "https://github.com/kassoulet/karios/blob/develop/karios/report/shift_by_alt_plot.py"
click node_ce_plot "https://github.com/kassoulet/karios/blob/develop/karios/report/circular_error_plot.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_api,node_runtime_config,node_processing_config toneBlue
class node_raster,node_radiometry,node_global_align,node_klt,node_coarse_fine,node_large_offset,node_zncc,node_mutual_info toneAmber
class node_statistics,node_chip_service toneMint
class node_html_report,node_product_generator,node_overview_plot,node_coverage_plot,node_shift_plots,node_altitude_plot,node_ce_plot toneRose
class node_user toneIndigo
```

## Components

### Entry and configuration

- [CLI commands](https://github.com/kassoulet/karios/blob/develop/karios/cli/commands.py): `karios/cli/commands.py`
- [Processing API](https://github.com/kassoulet/karios/blob/develop/karios/api/core.py): `karios/api/core.py`
- [Runtime settings](https://github.com/kassoulet/karios/blob/develop/karios/api/config.py): `karios/api/config.py`
- [Processing settings](https://github.com/kassoulet/karios/blob/develop/karios/core/configuration.py): `karios/core/configuration.py`

### Raster and matching

- [Raster access](https://github.com/kassoulet/karios/blob/develop/karios/core/image.py): `karios/core/image.py`
- [Radiometry conversion](https://github.com/kassoulet/karios/blob/develop/karios/core/radiometry.py): `karios/core/radiometry.py`
- [Coarse alignment](https://github.com/kassoulet/karios/blob/develop/karios/matcher/global_align.py): `karios/matcher/global_align.py`
- [KLT matching](https://github.com/kassoulet/karios/blob/develop/karios/matcher/klt.py): `karios/matcher/klt.py`
- [Coarse-to-fine matching](https://github.com/kassoulet/karios/blob/develop/karios/matcher/coarse_to_fine.py): `karios/matcher/coarse_to_fine.py`
- [Large-shift detection](https://github.com/kassoulet/karios/blob/develop/karios/matcher/large_offset.py): `karios/matcher/large_offset.py`
- [ZNCC scoring](https://github.com/kassoulet/karios/blob/develop/karios/matcher/zncc_service.py): `karios/matcher/zncc_service.py`
- [Mutual information](https://github.com/kassoulet/karios/blob/develop/karios/matcher/mutual_info_service.py): `karios/matcher/mutual_info_service.py`

### Accuracy analysis

- [Accuracy statistics](https://github.com/kassoulet/karios/blob/develop/karios/accuracy_analysis/accuracy_statistics.py): `karios/accuracy_analysis/accuracy_statistics.py`
- [Keypoint chips](https://github.com/kassoulet/karios/blob/develop/karios/report/chip_service.py): `karios/report/chip_service.py`

### Reports and products

- [HTML report](https://github.com/kassoulet/karios/blob/develop/karios/report/html_report.py): `karios/report/html_report.py`
- [Product generation](https://github.com/kassoulet/karios/blob/develop/karios/report/product_generator.py): `karios/report/product_generator.py`
- [Error overview](https://github.com/kassoulet/karios/blob/develop/karios/report/overview_plot.py): `karios/report/overview_plot.py`
- [Point coverage](https://github.com/kassoulet/karios/blob/develop/karios/report/coverage_plot.py): `karios/report/coverage_plot.py`
- [Displacement plots](https://github.com/kassoulet/karios/blob/develop/karios/report/shift_by_row_col_plot.py): `karios/report/shift_by_row_col_plot.py`
- [Altitude analysis](https://github.com/kassoulet/karios/blob/develop/karios/report/shift_by_alt_plot.py): `karios/report/shift_by_alt_plot.py`
- [Circular error plot](https://github.com/kassoulet/karios/blob/develop/karios/report/circular_error_plot.py): `karios/report/circular_error_plot.py`

### Other components

- **Analyst**

## Connections

- Analyst → CLI commands: runs analysis (evidence: `README.md`)
- CLI commands → Processing API: invokes processing (evidence: `karios/cli/commands.py`)
- CLI commands → Processing settings: loads settings (evidence: `karios/cli/commands.py`)
- Processing API → Runtime settings: uses runtime settings (evidence: `karios/api/core.py`)
- Processing API → Processing settings: uses processing settings (evidence: `karios/api/core.py`)
- Processing API → Raster access: loads and checks rasters (evidence: `karios/api/core.py`)
- Processing API → KLT matching: runs matching (evidence: `karios/api/core.py`)
- Processing API → Large-shift detection: detects large shifts (evidence: `karios/api/core.py`)
- Processing API → ZNCC scoring: computes match scores (evidence: `karios/api/core.py`)
- Processing API → Mutual information: computes match scores (evidence: `karios/api/core.py`)
- Processing API → Accuracy statistics: computes accuracy (evidence: `karios/api/core.py`)
- Processing API → Keypoint chips: generates keypoint chips (evidence: `karios/api/core.py`)
- Processing API → HTML report: generates report (evidence: `karios/api/core.py`)
- Processing API → Product generation: generates products (evidence: `karios/api/core.py`)
- Processing API → Error overview: creates overview (evidence: `karios/api/core.py`)
- Processing API → Point coverage: creates coverage plot (evidence: `karios/api/core.py`)
- Processing API → Circular error plot: creates accuracy plot (evidence: `karios/api/core.py`)
- Processing API → Displacement plots: creates displacement plots (evidence: `karios/api/core.py`)
- Processing API → Altitude analysis: creates altitude plot (evidence: `karios/api/core.py`)
- KLT matching → Coarse-to-fine matching: uses tracker (evidence: `karios/matcher/klt.py`)
- KLT matching → Radiometry conversion: converts image values (evidence: `karios/matcher/klt.py`)
- KLT matching → Raster access: reads image data (evidence: `karios/matcher/klt.py`)
- Coarse alignment → Radiometry conversion: converts image values (evidence: `karios/matcher/global_align.py`)
- Coarse alignment → Raster access: uses raster images (evidence: `karios/matcher/global_align.py`)
- Large-shift detection → Raster access: shifts image (evidence: `karios/matcher/large_offset.py`)
- ZNCC scoring → Raster access: extracts image patches (evidence: `karios/matcher/zncc_service.py`)
- Mutual information → Raster access: uses raster images (evidence: `karios/matcher/mutual_info_service.py`)
- Accuracy statistics → Processing settings: uses analysis settings (evidence: `karios/accuracy_analysis/accuracy_statistics.py`)
- Circular error plot → Accuracy statistics: uses accuracy metrics (evidence: `karios/report/circular_error_plot.py`)
- Point coverage → Raster access: uses image extent (evidence: `karios/report/coverage_plot.py`)
- Error overview → Raster access: uses image data (evidence: `karios/report/overview_plot.py`)
- Displacement plots → Raster access: uses image data (evidence: `karios/report/shift_by_row_col_plot.py`)
- Altitude analysis → Raster access: uses image data (evidence: `karios/report/shift_by_alt_plot.py`)
- Analyst → Processing API: calls library directly (evidence: `README.md`)
