# jugal-sac/ir-colorization-bah2026 architecture

> Architecture diagram of the GitHub repository jugal-sac/ir-colorization-bah2026, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jugal-sac/ir-colorization-bah2026
- Repository: https://github.com/jugal-sac/ir-colorization-bah2026

## Overview

1. **Repository purpose**
   - This repo is a baseline for the BAH 2026 challenge, focused on preparing aligned training data for two tasks: TIR super-resolution and TIR colorization.
   - It does not appear to contain the model training/inference code itself; instead it establishes the preprocessing and dataset-generation boundary.

2. **Top-level orchestration**
   - `driver.py` is the main entry point for the baseline pipeline.
   - Based on the README, it likely coordinates the full dataset-generation flow: locate input scenes, merge RGB bands, downscale imagery, extract aligned patches, and write outputs.

3. **Input data boundary**
   - The pipeline expects Landsat 9 products under `input/<folder_name>/` with four required files: `_B10.TIF`, `_B2.TIF`, `_B3.TIF`, `_B4.TIF`.
   - This is the key external data interface; all downstream processing assumes those band files are already present and correctly named.

4. **Band fusion / RGB assembly**
   - `scripts/merge_rgb.py` is the RGB construction stage.
   - Its role is to combine B2, B3, and B4 into a co-registered RGB raster, producing the optical reference used later for patch generation.

5. **Resolution transformation**
   - `scripts/downscale.py` handles creation of lower-resolution versions of the input rasters.
   - The README describes two scales used by the baseline: 100m and 200m derived from the 30m-resampled inputs, with 200m TIR serving as the SR input and 100m TIR as the SR target.

6. **Patch extraction**
   - `scripts/create_patches.py` is the dataset-splitting stage.
   - It extracts spatially aligned patches for two paired datasets:
     - 200m TIR → 100m TIR for super-resolution
     - 100m TIR → 100m RGB for colorization
   - Alignment is a core architectural constraint: the same top-left offsets are used across resolutions so the pairs remain co-registered.

7. **Download and data acquisition utilities**
   - `scripts/download.py` supports programmatic acquisition via Google Earth Engine.
   - `scripts/download_data.sh` is a convenience wrapper for fetching demo data, likely intended for quick local validation.
   - Together these form the ingestion layer before preprocessing begins.

8. **Output artifacts**
   - Generated data is written to `output/patches/`, with both `.npy` arrays and `.png` previews.
   - The `.npy` files are the training-ready artifacts because they preserve radiometric fidelity; the PNGs are only for inspection.
   - The checked-in `output/patches/demo/sample_006/` files show the expected structure of generated patch assets.

9. **Utility layer**
   - `utils/file_utils.py` likely centralizes path handling and file enumeration for band discovery and output organization.
   - `utils/logging_utils.py` likely provides consistent console/file logging across scripts.
   - `utils/visualization.py` likely supports preview generation and quality checks of patches and alignment.

10. **External tooling and runtime**
   - The repo is Python-based, with a Bash script for demo download.
   - The architecture is oriented around geospatial raster processing rather than a web or service stack.
   - The main technical dependencies are therefore raster I/O, NumPy array handling, and whatever geospatial libraries the scripts use internally for TIFF processing.

11. **System boundary for downstream ML**
   - The intended downstream model pipeline is external to this baseline.
   - The repo’s role is to produce the canonical paired datasets needed to train separate SR and colorization models, and later to accept inference inputs from a 200m TIR product and emit outputs into `output/model_outputs/`.

12. **Required inference output contract**
   - The README defines the final artifact layout expected by evaluators:
     - `output/model_outputs/tir_superresolved_100m/<product_id>.tif`
     - `output/model_outputs/colorized_tir_100m/<product_id>.tif`
   - For the colorized TIFF, channel order is fixed as Blue, Green, Red, which is an important architectural/output constraint for any model integration.

13. **Overall data flow**
   - Raw Landsat bands in `input/` are ingested by preprocessing scripts.
   - RGB is merged, TIR is downscaled, and aligned multi-resolution patches are exported.
   - Those patch datasets feed model development.
   - At inference time, the system is expected to reverse the dependency chain: take low-res TIR in, produce super-resolved TIR, then colorize it into RGB-form output.

Main entry points: [`scripts/create_patches.py`](https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/scripts/create_patches.py) (Create patches), [`scripts/downscale.py`](https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/scripts/downscale.py) (Downscale), [`driver.py`](https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/driver.py) (Driver), [`scripts/merge_rgb.py`](https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/scripts/merge_rgb.py) (Merge RGB)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_pipeline["Preprocessing pipeline"]
  node_n_driver["Driver<br/>orchestrator<br/>[driver.py]"]
  node_n_download["Earth Engine<br/>acquisition<br/>[download.py]"]
  node_n_download_sh["Demo fetch<br/>shell wrapper<br/>[download_data.sh]"]
  node_n_merge["Merge RGB<br/>band fusion<br/>[merge_rgb.py]"]
  node_n_downscale["Downscale<br/>resampling<br/>[downscale.py]"]
  node_n_patches["Create patches<br/>dataset builder<br/>[create_patches.py]"]
end

subgraph group_grp_support["Support layer"]
  node_n_input[("Landsat scene<br/>raw data")]
  node_n_file_utils["File utils<br/>path helpers<br/>[file_utils.py]"]
  node_n_log_utils["Logging<br/>[logging_utils.py]"]
  node_n_viz["Visualization<br/>preview helpers<br/>[visualization.py]"]
  node_n_demo_sample["Demo sample<br/>example output<br/>[tir_200m.npy]"]
  node_n_sr_input["SR input<br/>200m TIR<br/>[tir_200m.npy]"]
  node_n_sr_target["SR target<br/>100m TIR<br/>[tir_100m_512.npy]"]
  node_n_color_target["Color target<br/>100m RGB<br/>[rgb_100m_512.npy]"]
  node_n_model_outputs[("Model outputs<br/>inference contract")]
end

node_n_download -.->|"fetch"| node_n_input
node_n_download_sh -.->|"wraps"| node_n_download
node_n_driver -->|"orchestrates"| node_n_merge
node_n_driver -->|"orchestrates"| node_n_downscale
node_n_driver -->|"orchestrates"| node_n_patches
node_n_input -->|"B2/B3/B4"| node_n_merge
node_n_input -->|"B10"| node_n_downscale
node_n_merge -->|"produces"| node_n_color_target
node_n_downscale -->|"produces"| node_n_sr_input
node_n_downscale -->|"produces"| node_n_sr_target
node_n_patches -->|"pairs"| node_n_sr_input
node_n_patches -->|"pairs"| node_n_sr_target
node_n_patches -->|"pairs"| node_n_color_target
node_n_patches -->|"writes"| node_n_demo_sample
node_n_file_utils -.->|"paths"| node_n_merge
node_n_file_utils -.->|"paths"| node_n_downscale
node_n_file_utils -.->|"paths"| node_n_patches
node_n_log_utils -.->|"logs"| node_n_driver
node_n_viz -.->|"inspect"| node_n_patches
node_n_model_outputs -.->|"contract"| node_n_sr_target
node_n_model_outputs -.->|"contract"| node_n_color_target

click node_n_driver "https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/driver.py"
click node_n_download "https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/scripts/download.py"
click node_n_download_sh "https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/scripts/download_data.sh"
click node_n_merge "https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/scripts/merge_rgb.py"
click node_n_downscale "https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/scripts/downscale.py"
click node_n_patches "https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/scripts/create_patches.py"
click node_n_file_utils "https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/utils/file_utils.py"
click node_n_log_utils "https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/utils/logging_utils.py"
click node_n_viz "https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/utils/visualization.py"
click node_n_demo_sample "https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/output/patches/demo/sample_006/tir_200m.npy"
click node_n_sr_input "https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/output/patches/demo/sample_006/tir_200m.npy"
click node_n_sr_target "https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/output/patches/demo/sample_006/tir_100m_512.npy"
click node_n_color_target "https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/output/patches/demo/sample_006/rgb_100m_512.npy"

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_n_driver,node_n_download,node_n_download_sh,node_n_merge,node_n_downscale,node_n_patches toneBlue
class node_n_input,node_n_file_utils,node_n_log_utils,node_n_viz,node_n_demo_sample,node_n_sr_input,node_n_sr_target,node_n_color_target,node_n_model_outputs toneAmber
```

## Components

### Preprocessing pipeline

Scene ingestion, band fusion, resampling, and paired patch generation.

- [Driver](https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/driver.py): orchestrator · Main entry point coordinating the baseline preprocessing flow. · `driver.py`
- [Earth Engine](https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/scripts/download.py): acquisition · Programmatic scene download path backed by Google Earth Engine. · `scripts/download.py`
- [Demo fetch](https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/scripts/download_data.sh): shell wrapper · Convenience script for downloading demo data. · `scripts/download_data.sh`
- [Merge RGB](https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/scripts/merge_rgb.py): band fusion · Combines B2, B3, and B4 into a co-registered RGB raster. · `scripts/merge_rgb.py`
- [Downscale](https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/scripts/downscale.py): resampling · Creates multi-resolution thermal rasters used for super-resolution training. · `scripts/downscale.py`
- [Create patches](https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/scripts/create_patches.py): dataset builder · Extracts aligned paired patches for super-resolution and colorization. · `scripts/create_patches.py`

### Support layer

Shared utilities and reference artifacts used by the pipeline.

- **Landsat scene**: raw data · Input scene folder containing B10, B2, B3, and B4 TIFFs.
- [File utils](https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/utils/file_utils.py): path helpers · Centralized file discovery and output path handling. · `utils/file_utils.py`
- [Logging](https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/utils/logging_utils.py): logging helpers · Shared console and file logging utilities. · `utils/logging_utils.py`
- [Visualization](https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/utils/visualization.py): preview helpers · Patch preview and alignment inspection helpers. · `utils/visualization.py`
- [Demo sample](https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/output/patches/demo/sample_006/tir_200m.npy): example output · Checked-in example of the expected patch artifact layout. · `output/patches/demo/sample_006/tir_200m.npy`
- [SR input](https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/output/patches/demo/sample_006/tir_200m.npy): 200m TIR · Lower-resolution thermal input for super-resolution. · `output/patches/demo/sample_006/tir_200m.npy`
- [SR target](https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/output/patches/demo/sample_006/tir_100m_512.npy): 100m TIR · Aligned 100m thermal target used for super-resolution supervision. · `output/patches/demo/sample_006/tir_100m_512.npy`
- [Color target](https://github.com/jugal-sac/ir-colorization-bah2026/blob/main/output/patches/demo/sample_006/rgb_100m_512.npy): 100m RGB · Aligned RGB supervision target used for colorization. · `output/patches/demo/sample_006/rgb_100m_512.npy`
- **Model outputs**: inference contract · Expected output location for downstream evaluation artifacts.

## Connections

- Earth Engine → Landsat scene: fetch · Acquisition populates the expected scene folders.
- Demo fetch → Earth Engine: wraps · Shell helper invokes the download flow.
- Driver → Merge RGB: orchestrates · Coordinates RGB assembly in the preprocessing pipeline.
- Driver → Downscale: orchestrates · Coordinates thermal resampling.
- Driver → Create patches: orchestrates · Coordinates aligned patch extraction.
- Landsat scene → Merge RGB: B2/B3/B4 · RGB bands are read from each scene.
- Landsat scene → Downscale: B10 · Thermal band is the source for multi-scale TIR products.
- Merge RGB → Color target: produces · Builds the RGB reference used for colorization pairs.
- Downscale → SR input: produces · Builds the low-resolution thermal input.
- Downscale → SR target: produces · Builds the higher-resolution thermal supervision target.
- Create patches → SR input: pairs · Uses aligned low-resolution thermal patches.
- Create patches → SR target: pairs · Uses aligned 100m thermal targets.
- Create patches → Color target: pairs · Uses aligned RGB targets for colorization.
- Create patches → Demo sample: writes · Exports training-ready arrays and previews in the demo layout.
- File utils → Merge RGB: paths · Supports scene discovery and output naming.
- File utils → Downscale: paths · Supports raster enumeration and derived file naming.
- File utils → Create patches: paths · Supports patch directory organization.
- Logging → Driver: logs · Provides shared execution logging.
- Visualization → Create patches: inspect · Supports preview generation and alignment checks.
- Model outputs → SR target: contract · Downstream inference is expected to emit 100m super-resolved TIR here.
- Model outputs → Color target: contract · Downstream inference is expected to emit colorized TIR in fixed BGR channel order.