# Tone Analysis Tools

This directory contains tools for photometric validation and tone response analysis of camera sensors using integrating sphere measurements with support for HDR and SRTX formats.

## Overview

The tone analysis tools compare real camera responses to simulated responses when exposed to calibrated integrating sphere illumination at different luminance levels. This is essential for validating camera sensor performance and calibrating tone response curves. The tools now support HDR processing with SRTX formats and enhanced tone mapping for very dark images.

## Tools

### 1. `tone_analysis_batch.py`
**Main tool for batch tone response analysis with HDR support**

Processes two folders of images (reference vs test) captured at different luminance levels and generates comprehensive tone response analysis. 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**: Automatic tone mapping for very dark HDR images during detection
- **Shared Detection Area**: Automatically detects disc area from all images in a folder and uses consistent area for all images
- **Robust Hough Detection**: Simplified to use proven Hough circles detection method
- **Automatic Luminance Parsing**: Extracts luminance values from filenames
- **Linear HDR Processing**: Proper handling of linear HDR data with gamma=1.0
- **Comprehensive Analysis**: Generates response curves, error analysis, and detailed statistics

#### Usage
```bash
python tone_analysis_batch.py --folder1 <reference_folder> --folder2 <test_folder> --output_folder <output_dir> --image_format <format>
```

#### Command Line Arguments
- `--folder1`: First folder containing reference images (default: `<HOME>/Documents/images/pma/hdr/sphere_tester`)
- `--folder2`: Second folder containing test images (default: `<HOME>/Documents/images/pma/hdr/sphere_sim`)
- `--output_folder`: Output directory for results and visualizations (default: `<HOME>/Documents/images/pma/hdr/output`)
- `--image_format`: Image format type (default: `srtx_f16`)
- `--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 for SRTX)
- `--gamma`: Gamma correction (default: 1.0 for linear HDR processing)
- `--bayer_pattern`: Bayer pattern for RAW files (RGGB, GRBG, GBRG, BGGR)
- `--cfa`: CFA pattern for SRTX formats (RGGB, GRBG, GBRG, BGGR)
- `--align_12`: 12-bit alignment for SRTX CPD format (lj, rj)
- `--show_plots`: Enable verbose output
- `--fallback_x`, `--fallback_y`, `--fallback_width`, `--fallback_height`: Fallback rectangular region (emergency only)

#### 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 (8-bit/16-bit)
- **exr**: OpenEXR HDR images
- **bin**: Binary image files (requires width/height)
- **raw**: RAW Bayer pattern images

#### HDR Processing Features
- **4-Channel Support**: Native support for RGBA/4-channel SRTX formats
- **Linear Processing**: Gamma=1.0 default for proper linear HDR handling
- **Tone Mapping for Detection**: Automatic tone mapping applied only during disc detection for very dark images (range ≤ 10.0)
- **KPI Preservation**: Original linear HDR values preserved for all KPI calculations
- **Enhanced Detection**: Gamma 0.5 tone mapping brightens dark HDR images for successful Hough circle detection

#### Filename Convention
Images must follow naming convention with luminance values:
- `01nits.srtx_f16` → 0.1 nits
- `1nits.srtx_f16` → 1.0 nits
- `10nits.srtx_f16` → 10.0 nits
- `100nits.srtx_f16` → 100.0 nits
- `1knits.srtx_f16` → 1000.0 nits
- `0_1nits.srtx_f16` → 1.0 nits (underscore parsing)

#### Output Files
- `tone_response_comparison.jpg`: Response curve plots and error analysis
- `tone_calibration_report.csv`: Detailed statistics and calibration coefficients
- `*_detection_shared_detection.png`: Detection visualizations for each image
- `*_detection_individual_hough_detection.png`: Individual Hough detection results

#### Processing Flow
1. **File Pairing Check**: Validates correspondence between folders using luminance-based matching
2. **HDR Image Loading**: Proper loading of SRTX formats with 4-channel support
3. **Enhanced Detection**: Hough circles detection with tone mapping for very dark HDR images
4. **Shared Detection**: Finds disc area from all detectable images in each folder
5. **Pixel Extraction**: Extracts pixel values from disc region using original linear HDR data
6. **Response Analysis**: Fits power law curves and calculates error metrics
7. **Report Generation**: Creates comprehensive analysis report

### 2. `disc_detect.py`
**Utility for light disc detection testing**

Simple utility for testing disc detection algorithms on individual images, including HDR tone mapping.

## Detection Methods

The tone analysis uses **Hough Circle Detection** as the primary method:

**Hough Circle Detection with HDR Enhancement:**
- **HDR Tone Mapping**: For images with max ≤ 10.0, applies gamma 0.5 tone mapping to brighten for detection
- **Multiple Parameter Sets**: Tests various circle detection parameters
- **Comprehensive Validation**: Size, position, brightness, and boundary validation
- **Original Data Preservation**: Tone mapping only affects detection, not KPI processing

Each detection includes validation:
- Size validation (radius within expected range)
- Position validation (center within reasonable bounds)
- Brightness validation (center at/near maximum brightness)
- Boundary validation (disc within image bounds)

## Integrating Sphere Setup

### Hardware Requirements
- Integrating sphere output measured with PR650, a NIST traceable spectroradiometer
- Calibrated luminance levels: 0.1, 1, 10, 100, 1000 nits
- Camera under test positioned for consistent disc imaging
- Support for HDR capture modes and SRTX raw formats

### Image Requirements
- **Resolution**: 3840x2160 (4K) for SRTX formats
- **Format**: SRTX F16 (recommended for HDR), SRTX CPD, or PNG
- **Channels**: 4-channel support for SRTX formats
- **Dynamic Range**: Linear HDR processing with gamma=1.0
- **Consistent positioning** across all luminance levels
- **Clear disc visibility** in center region

## Error Handling

### HDR Processing
- **Low Signal Detection**: Automatic tone mapping for images with max ≤ 10.0
- **Channel Mismatch**: Clear error messages for incorrect channel count
- **File Size Validation**: Proper validation for SRTX format dimensions
- **Linear Processing**: Preserved throughout KPI calculations

### Shared Detection Area
- If no image in a folder can be detected → **RuntimeError** with clear message
- If some images can't be detected → Uses shared area from successful detections
- Shared area calculated as median of all successful detections

### Validation Failures
- File pairing mismatches → Warning with detailed report
- Invalid luminance parsing → File skipped with warning
- Image loading failures → File skipped with error message

## Example Usage

```bash
# SRTX F16 HDR files (recommended)
python tone_analysis_batch.py \
  --folder1 <HOME>/Documents/images/pma/hdr/sphere_tester \
  --folder2 <HOME>/Documents/images/pma/hdr/sphere_sim \
  --output_folder <HOME>/Documents/images/pma/hdr/output \
  --image_format srtx_f16 \
  --channels 4 \
  --gamma 1.0

# SRTX CPD companded files
python tone_analysis_batch.py \
  --folder1 sphere_reference \
  --folder2 camera_test \
  --output_folder results \
  --image_format srtx_cpd \
  --width 3840 \
  --height 2160 \
  --channels 4 \
  --gamma 1.0 \
  --cfa RGGB \
  --align_12 lj

# Legacy PNG files
python tone_analysis_batch.py \
  --folder1 sphere_reference \
  --folder2 camera_test \
  --output_folder results \
  --image_format png \
  --gamma 2.2

# BIN files with custom dimensions
python tone_analysis_batch.py \
  --folder1 raw_images \
  --folder2 processed_images \
  --output_folder analysis_results \
  --image_format bin \
  --width 3840 \
  --height 2160 \
  --data_type float16 \
  --channels 4 \
  --gamma 1.0
```

## Calibration Report

The generated CSV report includes:
- **Gamma coefficients**: Power law curve fitting parameters
- **R² values**: Goodness of fit metrics
- **Error percentages**: Relative error at each luminance level
- **Pixel statistics**: Min/max/std/median/SNR/CV for each luminance
- **RGB values**: Individual channel responses
- **HDR metrics**: Linear processing statistics

## Troubleshooting

### Common Issues
1. **No disc detected in HDR**: Very dark images automatically get tone mapping
2. **File size mismatch**: Check channel count (SRTX uses 4 channels by default)
3. **File pairing errors**: Verify filename luminance parsing
4. **Detection failures**: Images may benefit from tone mapping enhancement

### HDR-Specific Solutions
- **Dark HDR images**: Tool automatically applies tone mapping for detection
- **Channel count**: Use `--channels 4` for SRTX formats
- **Linear processing**: Keep `--gamma 1.0` for proper HDR handling
- **File dimensions**: Ensure width/height match actual SRTX file dimensions

### Legacy Solutions
- Use higher luminance test images for initial detection
- Verify integrating sphere positioning and calibration
- Check image file integrity and format
- Ensure consistent camera settings across luminance levels

## Dependencies
- numpy
- cv2 (OpenCV)
- matplotlib
- pandas
- scipy
- sklearn
- pathlib 
- cuisim_util (for SRTX format support) 