APZmedia-Comfyui-LightDirection-estimation/docs/ire_shadow_analysis_guide.md

IRE Shadow Analysis Guide

Overview

This guide explains the new IRE (Institute of Radio Engineers) stops false color approach for shadow detection in sRGB/display-referred images. This method provides precise analysis of shadow characteristics including soft vs hard shadow transitions.

What is IRE Analysis?

IRE (Institute of Radio Engineers) is a standardized scale used in video and broadcast to measure luminance levels. The scale ranges from 0 IRE (pure black) to 100 IRE (pure white), with specific ranges corresponding to different exposure zones.

IRE Color Mapping for sRGB Images

IRE Range	Color	Description	Use Case
0-10 IRE	Purple/Blue	Deep shadows	Very dark areas, crushed blacks
10-20 IRE	Blue	Shadows	Main shadow areas
20-30 IRE	Cyan	Mid-shadows	Shadow transitions
30-50 IRE	Green	Low-midtones	Properly exposed areas
50-70 IRE	Yellow	Midtones	Well-lit areas
70-90 IRE	Orange	High-midtones	Bright areas
90-100 IRE	Red	Highlights	Very bright areas, potential clipping

Key Features

1. False Color Visualization

• Maps IRE values to distinct colors for easy visual analysis
• Helps identify exposure zones and shadow characteristics
• Provides immediate feedback on lighting distribution

2. Shadow Transition Analysis

• Analyzes gradient patterns in shadow areas
• Detects soft vs hard shadow transitions
• Measures transition smoothness using gradient magnitude

3. Soft vs Hard Shadow Classification

• Soft Shadows: Gradual transitions (low gradients)
• Hard Shadows: Abrupt transitions (high gradients)
• Provides quantitative ratios and qualitative descriptions

ComfyUI Nodes

IREShadowAnalyzer Node

Purpose: Analyze shadow characteristics using IRE false color approach

Inputs:

• image: sRGB image to analyze
• shadow_ire_threshold: IRE value below which pixels are considered shadows (default: 20.0)
• transition_sensitivity: Sensitivity for detecting shadow transitions (default: 0.1)
• analysis_mode: Analysis scope (full, shadows_only, transitions_only)

Outputs:

• false_color_ire: False color visualization of IRE values
• shadow_mask: Binary mask of shadow areas
• soft_shadow_mask: Areas with soft shadow transitions
• hard_shadow_mask: Areas with hard shadow transitions
• ire_legend: Color mapping legend
• shadow_character: Classification (Very Soft, Soft, Medium, Hard)
• transition_quality: Description of transition smoothness
• ire_range: IRE value range in the image
• shadow_coverage: Percentage of shadow coverage
• gradient_analysis: Description of gradient characteristics

IREShadowComparison Node

Purpose: Compare shadow characteristics between two images

Inputs:

• image_a, image_b: Images to compare
• shadow_ire_threshold: IRE threshold for shadow detection
• comparison_mode: Comparison visualization method

Outputs:

• ire_comparison: Side-by-side or difference visualization
• shadow_difference: Difference in shadow areas
• transition_comparison: Difference in transition characteristics
• Comparative statistics and classifications

EnhancedLightEstimator Node

Purpose: Combined analysis using both normal maps and IRE shadow analysis

Inputs:

• All inputs from NormalMapLightEstimator
• shadow_ire_threshold: IRE threshold for shadow detection
• transition_sensitivity: Transition analysis sensitivity
• ire_analysis_weight: Weight for IRE analysis in combined results (0.0-1.0)

Outputs:

• All outputs from NormalMapLightEstimator
• All outputs from IREShadowAnalyzer
• final_shadow_character: Combined shadow classification
• final_light_quality: Combined light quality assessment
• combined_confidence: Overall analysis confidence
• analysis_consistency: Consistency between normal map and IRE analysis

Usage Examples

Basic Shadow Analysis

# Initialize analyzer
analyzer = IREShadowAnalyzer(
    shadow_ire_threshold=20.0,
    transition_sensitivity=0.1
)

# Analyze image
results = analyzer.generate_ire_analysis_report(srgb_image)

# Extract shadow characteristics
shadow_character = results['shadow_classification']['shadow_character']
transition_quality = results['shadow_classification']['transition_quality']
soft_ratio = results['transition_analysis']['soft_shadow_ratio']

Shadow Transition Analysis

# Convert sRGB to IRE values
ire_values = analyzer.srgb_to_ire(srgb_image)

# Analyze transitions
transition_analysis = analyzer.analyze_shadow_transitions(ire_values)

# Classify shadow characteristics
classification = analyzer.classify_shadow_characteristics(transition_analysis)

False Color Visualization

# Create false color visualization
false_color = analyzer.create_false_color_visualization(ire_values)

# Create IRE legend
legend = analyzer.create_ire_legend()

Shadow Classification System

Shadow Character Classifications

Classification	Soft Ratio	Description
Very Soft	> 0.7	Predominantly gradual transitions
Soft	0.5 - 0.7	Mostly gradual transitions
Medium	0.3 - 0.5	Mixed transition types
Hard	< 0.3	Predominantly sharp transitions

Transition Quality Descriptions

Quality	Mean Gradient	Description
Very Gradual	< 5.0	Very smooth transitions
Gradual	5.0 - 15.0	Smooth transitions
Moderate	15.0 - 30.0	Moderate transitions
Sharp	30.0 - 50.0	Sharp transitions
Very Sharp	> 50.0	Very abrupt transitions

Best Practices

1. IRE Threshold Selection

• Low threshold (10-15 IRE): Detects only very dark shadows
• Medium threshold (15-25 IRE): Balanced shadow detection
• High threshold (25-35 IRE): Includes mid-tone shadows

2. Transition Sensitivity

• Low sensitivity (0.05-0.1): Detects only very obvious transitions
• Medium sensitivity (0.1-0.2): Balanced transition detection
• High sensitivity (0.2-0.5): Detects subtle transitions

3. Analysis Mode Selection

• Full: Complete analysis with all visualizations
• Shadows Only: Focus on shadow areas only
• Transitions Only: Focus on transition analysis

4. Combined Analysis

• Use EnhancedLightEstimator for comprehensive analysis
• Adjust ire_analysis_weight based on image characteristics
• Monitor analysis_consistency for result reliability

Troubleshooting

Common Issues

"No shadows detected"

• Lower the shadow_ire_threshold
• Check if image has sufficient contrast
• Verify image is in sRGB format

"Incorrect shadow classification"

• Adjust transition_sensitivity
• Check IRE value distribution
• Verify shadow areas are properly exposed

"Poor transition analysis"

• Increase image resolution
• Check for noise in shadow areas
• Adjust gradient analysis parameters

Performance Optimization

• Use appropriate image resolution (512x512 to 1024x1024 recommended)
• Process images in batches for efficiency
• Cache IRE color mappings for repeated analysis
• Use GPU acceleration when available

Technical Details

IRE Conversion Formula

# For sRGB display-referred images
ire_value = luma * 100.0

Gradient Analysis

# Sobel gradient calculation
grad_x = F.conv2d(ire_values, sobel_x_filter)
grad_y = F.conv2d(ire_values, sobel_y_filter)
gradient_magnitude = sqrt(grad_x² + grad_y²)

Shadow Classification

# Soft shadow detection
soft_shadow_mask = (gradient_magnitude < soft_threshold) & shadow_mask
soft_ratio = soft_shadow_mask.sum() / shadow_mask.sum()

Integration with Existing System

The IRE shadow analysis integrates seamlessly with the existing light estimation system:

1. Complementary Analysis: IRE analysis provides luminance-based insights while normal map analysis provides geometric insights
2. Combined Results: Enhanced estimator combines both approaches for comprehensive analysis
3. Consistency Checking: System can detect when analyses agree or disagree
4. Weighted Results: User can control the influence of each analysis method

This approach provides a robust, professional-grade shadow analysis system suitable for cinematography, photography, and computer graphics applications.