How jugal-sac/ir-colorization-bah2026 works
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: create_patches.py Create patches · downscale.py Downscale · driver.py Driver · merge_rgb.py Merge RGB
Components 15
Preprocessing pipeline
Scene ingestion, band fusion, resampling, and paired patch generation.
- Driver · Main entry point coordinating the baseline preprocessing flow.
driver.py - Earth Engine · Programmatic scene download path backed by Google Earth Engine.
scripts/download.py - Demo fetch · Convenience script for downloading demo data.
scripts/download_data.sh - Merge RGB · Combines B2, B3, and B4 into a co-registered RGB raster.
scripts/merge_rgb.py - Downscale · Creates multi-resolution thermal rasters used for super-resolution training.
scripts/downscale.py - Create patches · 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 · Input scene folder containing B10, B2, B3, and B4 TIFFs.
- File utils · Centralized file discovery and output path handling.
utils/file_utils.py - Logging · Shared console and file logging utilities.
utils/logging_utils.py - Visualization · Patch preview and alignment inspection helpers.
utils/visualization.py - Demo sample · Checked-in example of the expected patch artifact layout.
output/patches/demo/sample_006/tir_200m.npy - SR input · Lower-resolution thermal input for super-resolution.
output/patches/demo/sample_006/tir_200m.npy - SR target · Aligned 100m thermal target used for super-resolution supervision.
output/patches/demo/sample_006/tir_100m_512.npy - Color target · Aligned RGB supervision target used for colorization.
output/patches/demo/sample_006/rgb_100m_512.npy - Model outputs · Expected output location for downstream evaluation artifacts.
Connections 21
- 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.