# Color Analysis Tools

This directory contains tools for color accuracy validation and analysis of camera sensors using ColorChecker targets with comprehensive HDR and SRTX format support.

## Overview

The color analysis tools evaluate camera color performance by analyzing ColorChecker target images and computing color accuracy metrics including Delta E (CIE2000), Delta C (chroma difference), and Delta H (hue difference). These metrics are essential for validating camera color reproduction and calibrating color processing pipelines. Enhanced with HDR processing capabilities, SRTX format support, and advanced tone mapping for raw image analysis.

## Tools

### 1. `kpi_colorchecker_batch.py`
**Main tool for batch ColorChecker KPI analysis with HDR support**

Processes pairs of ColorChecker images (reference and test) to compute comprehensive color accuracy metrics, SNR analysis, and generate detailed analysis reports. Enhanced with HDR processing capabilities and SRTX format support.

#### Features
- **HDR & SRTX Support**: Native support for SRTX F16/CPD formats with 4-channel processing
- **Enhanced Tone Mapping**: Gamma correction and CLAHE for raw/dark image ColorChecker detection
- **Dual Image Analysis**: Compares reference vs test ColorChecker images
- **Luminance-Based Pairing**: Intelligent file matching based on extracted luminance values
- **Comprehensive KPIs**: Delta E, Delta C, Delta H, and saturation metrics
- **SNR Analysis**: Signal-to-noise ratio computation for gray patches (patches 18-23)
- **Extensive Format Support**: PNG, EXR, BIN, RAW, SRTX, ISP, and DS formats
- **Smart Chromaticity Plots**: CIE 1931 xy diagrams with intelligent label positioning
- **Raw Data Processing**: Proper handling of raw sensor data without premature normalization
- **Batch Processing**: Processes multiple image pairs automatically
- **Detailed Reports**: CSV output with per-patch and summary statistics
- **Visual Analysis**: Combined plots, individual chromaticity plots, and SNR plots

#### Usage
```bash
python kpi_colorchecker_batch.py --reference_folder <ref_folder> --test_folder <test_folder> --output_folder <output_dir> --image_format <format>
```

#### Command Line Arguments

**Basic Arguments:**
- `--reference_folder`: Folder containing reference ColorChecker images (default: `<HOME>/Documents/images/color/raw/`)
- `--test_folder`: Folder containing test ColorChecker images (default: `<HOME>/Documents/images/color/raw/`)
- `--output_folder`: Output directory for results and plots (default: `<HOME>/Documents/images/color/raw/`)
- `--image_format`: Image format type (default: `srtx_f16`)
- `--show_plots`: Print plot file locations for manual viewing

**Image Format Arguments:**
- `--width`, `--height`: Image dimensions for BIN/SRTX files (default: 3840x2160)
- `--data_type`: Data type for BIN files (uint8, uint16, float16, float32)
- `--channels`: Number of channels for BIN/SRTX files (default: 4)
- `--bayer_pattern`: Bayer pattern for RAW files (RGGB, GRBG, GBRG, BGGR)

**SRTX Format Arguments:**
- `--gamma`: Gamma correction for SRTX formats (default: 1.0 for linear HDR)
- `--cfa`: CFA pattern for SRTX U32 format (RGGB, GRBG, GBRG, BGGR)
- `--align_12`: 12-bit alignment for companded format (lj, rj)
- `--l_factor`: Luminance factor for DS raw format (default: -1, auto)

#### Supported Image Formats
- **srtx_f16**: SRTX float16 format (default, optimized for HDR)
- **srtx_cpd**: SRTX companded format
- **srtx_u32**: SRTX uint32 format
- **png**: Standard PNG images
- **exr**: OpenEXR HDR images
- **bin**: Binary image files (requires width/height)
- **raw**: RAW Bayer pattern images
- **isp_ayuv**: ISP AYUV format
- **raw_u8**: RAW uint8 format
- **ds_raw**: Downsampled RAW format

#### HDR Processing Features
- **4-Channel Support**: Native support for RGBA/4-channel SRTX formats
- **Enhanced Tone Mapping**: Gamma correction (γ=2.2 for normal, γ=1.8 for dark images) + CLAHE for detection
- **Raw Data Preservation**: Original raw values preserved for all KPI calculations
- **Adaptive Processing**: Different tone mapping strategies based on image dynamic range
- **Debug Image Saving**: Saves tone-mapped images for detection analysis

#### Tone Mapping for Detection
- **Gamma Correction**: Applied to linear raw images for better ColorChecker detection
- **CLAHE Enhancement**: Contrast Limited Adaptive Histogram Equalization for very dark images (range ≤ 100)
- **Adaptive Thresholds**: Different gamma values based on image brightness
- **Detection Only**: Tone mapping only affects patch detection, not KPI computation

#### Output Files
- `colorchecker_kpi_analysis.png`: Combined KPI analysis plots (6 subplots)
- `colorchecker_kpi_summary.csv`: Summary statistics per image
- `colorchecker_kpi_detailed.csv`: Detailed per-patch statistics
- `chromaticity_error_<image>.jpg`: Individual chromaticity error plots
- `snr_gray_patches_<image>.png`: SNR analysis plots for gray patches
- `tone_mapped_<image>.png`: Debug images showing tone mapping results (for raw images)

#### Color Metrics
- **Delta E (CIE2000)**: Perceptual color difference
- **Delta C**: Chroma difference
- **Delta H**: Hue difference
- **Chromaticity Error**: CIE xy coordinate differences
- **SNR Analysis**: Signal-to-noise ratio for gray patches (RGB + Luminance)

#### SNR Analysis Features
- **Gray Patch Focus**: Analyzes patches 18-23 (gray scale patches)
- **Multi-Channel**: Computes SNR for R, G, B, and Luminance (Y) channels
- **Raw Data Handling**: Proper SNR calculation for raw sensor data ranges
- **Infinite SNR Handling**: Represents perfect signals (no noise) as 100 dB with "inf" labels
- **Comparative Analysis**: Side-by-side test vs reference SNR comparison
- **Visual Plots**: 4-subplot SNR analysis with trends, scatter plots, and statistics

#### Smart Chromaticity Labeling
- **Automatic Saturation Detection**: Determines which dataset (test or reference) is more saturated
- **Intelligent Positioning**: Places labels on more saturated coordinates to reduce crowding
- **Saturation Metrics**: Calculates distance from white point for optimal label placement

#### Luminance-Based File Pairing
- **Intelligent Matching**: Pairs files based on extracted luminance values from filenames
- **Format Flexibility**: Works with various file extensions (.png, .srtx_f16, .srtx_cpd, etc.)
- **Robust Parsing**: Handles complex filenames with multiple luminance formats
- **Validation Reports**: Detailed pairing analysis with missing file identification

### 2. `color_cui.py`
**ColorChecker User Interface for spectral color analysis**

Comprehensive ColorChecker analysis tool with spectral computations and advanced color metrics.

#### Features
- **Spectral Analysis**: Uses CIE standard observer and illuminant data
- **Camera Characterization**: Supports various camera spectral sensitivities
- **ColorChecker Extraction**: Automatic ColorChecker patch detection
- **Color Space Conversions**: XYZ, sRGB, and custom RGB color spaces
- **Noise Analysis**: Signal-to-noise ratio calculations

#### Key Functions
- `MCC.extract_mcc()`: Extracts ColorChecker patches from images
- `MCC.gen_metrics_color()`: Computes color accuracy metrics
- `MCC.gen_metrics_noise()`: Analyzes noise characteristics
- `MCC.mcc2rgb()`: Converts spectral data to RGB values

### 3. `color_checker.py`
**ColorChecker detection and metrics utilities**

Provides core functionality for ColorChecker patch detection and color metric computation.

#### Features
- **Automatic Detection**: Finds ColorChecker patches in images
- **Tone Mapping**: Reinhard tone mapping for HDR images
- **Gamma Adjustment**: Gamma correction utilities
- **Multi-format Support**: PNG and BIN file handling
- **Metrics Generation**: Color and noise statistics

#### Key Functions
- `cc_detect_stat()`: Main function for ColorChecker detection and analysis
- `reinhardHelper()`: Tone mapping for HDR images
- `adjust_gamma()`: Gamma correction

### 4. `bin.py`
**Binary file utilities**

Utilities for handling binary image files with various data types and formats.

## ColorChecker Target Requirements

### Physical Setup
- **Target**: Yanding backlit ColorChecker(24-patch)
- **Illumination**: Provided by LED panel with adjustable luminance and correlated color temperature

### Image Quality Requirements
- **Focus**: Sharp focus across entire ColorChecker target
- **Lighting**: Even illumination without shadows or hotspots
- **Positioning**: Target should be flat and perpendicular to camera
- **Exposure**: Proper exposure without clipping in any channel
- **HDR Capability**: Support for raw linear capture modes

## Color Spaces and Standards

### CIE Standards
- **Observer**: CIE 1931 2° Standard Observer
- **Illuminant**: D65 (daylight, 6500K)
- **Color Difference**: CIE2000 Delta E formula
- **Chromaticity**: CIE 1931 xy chromaticity coordinates

## Example Usage

```bash
# SRTX F16 HDR files (recommended)
python kpi_colorchecker_batch.py \
  --reference_folder <HOME>/Documents/images/color/raw/cc_tester \
  --test_folder <HOME>/Documents/images/color/raw/cc_sim \
  --output_folder <HOME>/Documents/images/color/raw/output \
  --image_format srtx_f16 \
  --channels 4 \
  --gamma 1.0

# SRTX CPD companded files
python kpi_colorchecker_batch.py \
  --reference_folder colorchecker_reference \
  --test_folder colorchecker_test \
  --output_folder analysis_results \
  --image_format srtx_cpd \
  --width 3840 \
  --height 2160 \
  --channels 4 \
  --gamma 1.0 \
  --cfa RGGB \
  --align_12 lj

# Legacy PNG files
python kpi_colorchecker_batch.py \
  --reference_folder reference_images \
  --test_folder test_images \
  --output_folder results \
  --image_format png \
  --gamma 2.2

# BIN files with specific dimensions
python kpi_colorchecker_batch.py \
  --reference_folder raw_colorchecker \
  --test_folder processed_colorchecker \
  --output_folder analysis_results \
  --image_format bin \
  --width 3840 \
  --height 2160 \
  --data_type uint16 \
  --channels 4 \
  --gamma 1.0

# RAW Bayer pattern files
python kpi_colorchecker_batch.py \
  --reference_folder raw_captures \
  --test_folder processed_raws \
  --output_folder results \
  --image_format raw \
  --bayer_pattern RGGB \
  --gamma 1.0

# EXR HDR files with enhanced processing
python kpi_colorchecker_batch.py \
  --reference_folder hdr_reference \
  --test_folder hdr_test \
  --output_folder results \
  --image_format exr \
  --gamma 1.0 \
  --show_plots
```

## Analysis Reports

### KPI Summary
The analysis generates comprehensive reports including:
- **Mean Delta E**: Average color difference across all patches
- **Max Delta E**: Maximum color difference (worst patch)
- **Delta C Statistics**: Chroma difference analysis
- **Delta H Statistics**: Hue difference analysis
- **Chromaticity Error**: Mean and maximum xy coordinate differences
- **SNR Metrics**: Gray patch signal-to-noise ratios
- **Processing Notes**: Tone mapping and enhancement details

### SNR Analysis
Detailed signal-to-noise analysis for gray patches:
- **Multi-Channel SNR**: R, G, B, and Luminance (Y) channels
- **Raw Data Support**: Proper calculation for raw sensor data ranges
- **Statistical Summary**: Mean, min, max SNR values
- **Infinite SNR Handling**: Perfect signals displayed as 100 dB
- **Comparative Analysis**: Test vs reference SNR comparison
- **Visual Trends**: SNR vs patch index and luminance relationships

### Per-Patch Analysis
Detailed statistics for each ColorChecker patch:
- Individual Delta E, Delta C, Delta H values
- RGB values for reference and test images
- Chromaticity coordinates (x, y)
- SNR values for gray patches (18-23)
- Patch identification and statistics

### Visual Analysis
Comprehensive visual analysis includes:
- **Combined Analysis Plot**: 6-subplot overview with all KPIs
- **Chromaticity Plots**: CIE 1931 xy diagrams with smart labeling
- **SNR Plots**: 4-subplot SNR analysis with trends and statistics
- **Color Difference Visualization**: Patch-by-patch comparison
- **Error Magnitude Representation**: Visual error distribution
- **Tone Mapping Debug**: Visual verification of detection enhancement

## ColorChecker Patches

The standard ColorChecker target contains 24 patches:

**Colored Patches (1-18):**
1. **Dark Skin** (Brown)
2. **Light Skin** (Flesh)
3. **Blue Sky**
4. **Foliage** (Green)
5. **Blue Flower**
6. **Bluish Green**
7. **Orange**
8. **Purplish Blue**
9. **Moderate Red**
10. **Purple**
11. **Yellow Green**
12. **Orange Yellow**
13. **Blue**
14. **Green**
15. **Red**
16. **Yellow**
17. **Magenta**
18. **Cyan**

**Gray Scale Patches (19-24) - Used for SNR Analysis:**
19. **White** (D65)
20. **Neutral 8** (Light Gray)
21. **Neutral 6.5** (Medium Gray)
22. **Neutral 5** (Dark Gray)
23. **Neutral 3.5** (Darker Gray)
24. **Black**

## Troubleshooting

### Common Issues
1. **ColorChecker not detected**: Check image quality, lighting, and tone mapping results
2. **High Delta E values**: Verify white balance and exposure
3. **Patch extraction failures**: Ensure target is flat and well-lit
4. **Format errors**: Verify file dimensions and data types
5. **Very dark images**: Tool automatically applies enhanced tone mapping

### HDR-Specific Solutions
- **Dark raw images**: Tool automatically applies gamma correction and CLAHE for detection
- **Channel count**: Use `--channels 4` for SRTX formats
- **Raw data range**: Tool preserves original range for KPI calculations
- **Detection enhancement**: Check tone mapped debug images for verification

### Legacy Solutions
- Use consistent lighting conditions
- Ensure proper ColorChecker positioning
- Check image resolution and focus quality
- Verify file format specifications
- Calibrate camera settings consistently
- For simulation data with perfect signals, expect infinite SNR (displayed as 100 dB)

### Format-Specific Tips
- **SRTX files**: Use appropriate dimensions (typically 3840x2160) and gamma=1.0
- **BIN files**: Always specify correct width, height, and data type
- **RAW files**: Ensure correct Bayer pattern specification
- **Perfect simulations**: Expect infinite SNR values for noise-free data

## Performance Targets

### Excellent Color Accuracy
- **Mean Delta E < 3.0**: Excellent color reproduction
- **Max Delta E < 6.0**: No severely inaccurate colors
- **Mean Delta C < 2.0**: Good chroma reproduction
- **Mean Chromaticity Error < 0.01**: Excellent chromaticity accuracy

### Good Color Accuracy
- **Mean Delta E < 5.0**: Acceptable color reproduction
- **Max Delta E < 10.0**: Tolerable worst-case colors
- **Mean Delta C < 4.0**: Acceptable chroma reproduction
- **Mean Chromaticity Error < 0.02**: Good chromaticity accuracy

### SNR Performance Guidelines
- **SNR > 40 dB**: Excellent signal quality
- **SNR 20-40 dB**: Good signal quality
- **SNR < 20 dB**: Poor signal quality (high noise)
- **Infinite SNR**: Perfect signal (simulation/processed data)

## Dependencies
- **colour-science**: CIE color computations and chromaticity diagrams
- **numpy**: Numerical computations and array operations
- **opencv-python**: Image processing and color space conversions
- **matplotlib**: Plotting and visualization
- **pandas**: Data analysis and CSV output
- **Pillow**: Image loading and basic processing
- **pathlib**: Modern path handling
- **json**: Configuration and metadata
- **image_utils**: Custom image loading utilities for SRTX formats
- **cuisim_util**: SRTX format support utilities

## References
- CIE 2000 Color Difference Formula
- X-Rite ColorChecker specifications
- CIE 1931 Standard Observer
- sRGB color space standard 
- Signal-to-Noise Ratio measurement standards 