Configuration Guide

Complete reference for DTUTMOConfig parameters and enums.

DTUTMOConfig Class

from dtutmo import DTUTMOConfig

config = DTUTMOConfig(
    # ... parameters ...
)

Observer Properties

observer_age

Observer age in years.

Type: float
Default: 24.0
Range: 18.0 to 80.0
Effects:
- Optical transfer function cutoff
- Glare scatter coefficient
- Pupil size dynamics

Example:

# Younger observer (sharper vision)
config = DTUTMOConfig(observer_age=25)

# Older observer (more blur, glare)
config = DTUTMOConfig(observer_age=60)

field_diameter

Visual field diameter in degrees.

Type: float
Default: 60.0
Range: 10.0 to 180.0
Effects:
- Glare PSF extent
- Local adaptation scales

Example:

# Standard viewing
config = DTUTMOConfig(field_diameter=60)

# Peripheral vision
config = DTUTMOConfig(field_diameter=120)

pixels_per_degree

Display resolution in pixels per degree of visual angle.

Type: float
Default: 45.0
Range: 30.0 to 60.0
Calculation: PPD = display_width_pixels / (2 * arctan(display_width_physical / (2 * viewing_distance))) * (180/π)

Example:

# HD display at typical viewing distance
config = DTUTMOConfig(pixels_per_degree=45)

# 4K display or closer viewing
config = DTUTMOConfig(pixels_per_degree=60)

Stage Toggles

use_otf

Enable optical transfer function (age-dependent blur).

Type: bool
Default: True
Disable for: Speed optimization, sharp output

# Standard (with optical blur)
config = DTUTMOConfig(use_otf=True)

# Disable for speed
config = DTUTMOConfig(use_otf=False)

use_glare

Enable CIE disability glare.

Type: bool
Default: True
Disable for: Speed optimization, scenes without bright sources

# Standard (with glare)
config = DTUTMOConfig(use_glare=True)

# Disable for speed or uniform scenes
config = DTUTMOConfig(use_glare=False)

use_bilateral

Enable bilateral base-detail separation.

Type: bool
Default: True
Disable for: Speed optimization, memory constraints

# Preserve fine details
config = DTUTMOConfig(use_bilateral=True)

# Disable for speed/memory
config = DTUTMOConfig(use_bilateral=False)

use_local_adapt

Enable local adaptation (Vangorp model).

Type: bool
Default: True
Disable for: Global adaptation only (not recommended)

# Local adaptation (recommended)
config = DTUTMOConfig(use_local_adapt=True)

# Global only (faster but lower quality)
config = DTUTMOConfig(use_local_adapt=False)

Color Appearance

use_cam

Color appearance model selection.

Type: CAMType enum
Default: CAMType.DTUCAM
Options:
- CAMType.DTUCAM - Physiologically-grounded, 0.001-100k cd/m²
- CAMType.XLRCAM - Psychophysically-validated, 0.01-16.9k cd/m²
- CAMType.CIECAM16 - CIE standard, 0.1-1k cd/m²
- CAMType.NONE - No CAM (fastest)

# Recommended
config = DTUTMOConfig(use_cam=CAMType.DTUCAM)

# HDR photography
config = DTUTMOConfig(use_cam=CAMType.XLRCAM)

# Standards compliance
config = DTUTMOConfig(use_cam=CAMType.CIECAM16)

# Speed critical
config = DTUTMOConfig(use_cam=CAMType.NONE)

viewing_condition

Viewing surround type.

Type: ViewingCondition enum
Default: ViewingCondition.AVERAGE
Options:
- DARK - <0.2 cd/m² (cinema)
- DIM - 0.2-20 cd/m² (home viewing)
- AVERAGE - >20 cd/m² (office)

Effects:

Adaptation degree (D)
Surround factor (F_s)

# Cinema/dark room
config = DTUTMOConfig(viewing_condition=ViewingCondition.DARK)

# Home theater
config = DTUTMOConfig(viewing_condition=ViewingCondition.DIM)

# Office/daylight
config = DTUTMOConfig(viewing_condition=ViewingCondition.AVERAGE)

Display Target

target_display

Display standard for output encoding.

Type: DisplayStandard enum
Default: DisplayStandard.REC_709
Options:
- REC_709 - sRGB, HDTV (100 cd/m²)
- REC_2020 - UHDTV (100 cd/m²)
- DCI_P3 - Digital cinema (48 cd/m²)
- REC_2100_PQ - HDR10 (10,000 cd/m²)
- REC_2100_HLG - HLG HDR (1,000 cd/m²)

# Standard display
config = DTUTMOConfig(target_display=DisplayStandard.REC_709)

# HDR10 display
config = DTUTMOConfig(target_display=DisplayStandard.REC_2100_PQ)

# HLG broadcast
config = DTUTMOConfig(target_display=DisplayStandard.REC_2100_HLG)

target_luminance

Target display peak luminance in cd/m².

Type: float
Default: 100.0
Range: 0.1 to 10000.0
Typical values:
- SDR: 100 cd/m²
- HDR: 300-1000 cd/m²
- HDR10: 1000-4000 cd/m²
- Cinema: 48 cd/m²
- Medical: 150-500 cd/m²

# Standard display
config = DTUTMOConfig(target_luminance=100.0)

# HDR consumer display
config = DTUTMOConfig(target_luminance=1000.0)

# Reference monitor
config = DTUTMOConfig(target_luminance=4000.0)

# Medical display
config = DTUTMOConfig(target_luminance=150.0)

Display Mapping

display_mapping

Display mapping strategy (Stage 12).

Type: DisplayMapping enum
Default: DisplayMapping.PRODUCTION_HYBRID
Options:
- LEGACY - Original v1.x method
- WHITEBOARD - Fast approximation
- FULL_INVERSE - Accurate inverse
- HYBRID - Basic hybrid
- PRODUCTION_HYBRID - Gradient-aware (recommended)

# Recommended
config = DTUTMOConfig(display_mapping=DisplayMapping.PRODUCTION_HYBRID)

# Speed critical
config = DTUTMOConfig(display_mapping=DisplayMapping.WHITEBOARD)

# Maximum accuracy
config = DTUTMOConfig(display_mapping=DisplayMapping.FULL_INVERSE)

See Display Mapping for detailed comparison.

gradient_threshold

Gradient threshold for hybrid blending.

Type: float
Default: 0.15
Range: 0.05 to 0.30
Applies to: PRODUCTION_HYBRID only

Effect:

Higher → More whiteboard (faster, slightly less accurate)
Lower → More full inverse (slower, more accurate)

# More aggressive (faster)
config = DTUTMOConfig(
    display_mapping=DisplayMapping.PRODUCTION_HYBRID,
    gradient_threshold=0.20
)

# Conservative (more accurate)
config = DTUTMOConfig(
    display_mapping=DisplayMapping.PRODUCTION_HYBRID,
    gradient_threshold=0.10
)

gradient_smoothing

Gradient map smoothing sigma.

Type: float
Default: 2.0
Range: 0.5 to 5.0
Applies to: PRODUCTION_HYBRID only

Effect:

Lower → Sharper transitions, possible artifacts
Higher → Smoother blending, may over-smooth

# Sharper transitions
config = DTUTMOConfig(
    display_mapping=DisplayMapping.PRODUCTION_HYBRID,
    gradient_smoothing=1.0
)

# Smoother blending
config = DTUTMOConfig(
    display_mapping=DisplayMapping.PRODUCTION_HYBRID,
    gradient_smoothing=3.0
)

Advanced Parameters

glare_model

Glare model type.

Type: str
Default: 'cie_general'
Options:
- 'cie_general' - CIE 180:2010 (recommended)
- 'cie_simplified' - Simplified CIE
- 'none' - No glare

config = DTUTMOConfig(glare_model='cie_general')

csf_model

Contrast sensitivity function model.

Type: str
Default: 'castle'
Options:
- 'castle' - CastleCSF (Ashraf 2024, recommended)
- 'barten' - Barten CSF
- 'movshon' - Movshon & Kiorpes

config = DTUTMOConfig(csf_model='castle')

cone_integration_time

Cone temporal integration time in seconds.

Type: float
Default: 0.01 (10 ms)
Range: 0.005 to 0.05
Effects: Temporal dynamics (future feature)

rod_integration_time

Rod temporal integration time in seconds.

Type: float
Default: 0.1 (100 ms)
Range: 0.05 to 0.2
Effects: Temporal dynamics (future feature)

Preset Configurations

Fast Preview

Optimized for speed:

fast_config = DTUTMOConfig(
    use_otf=False,
    use_glare=False,
    use_bilateral=False,
    use_cam=CAMType.NONE,
    display_mapping=DisplayMapping.WHITEBOARD,
)

tmo = CompleteDTUTMO(fast_config)

Performance: ~0.2s for 1080p

Production Quality

Balanced quality/performance:

production_config = DTUTMOConfig(
    observer_age=30,
    use_otf=True,
    use_glare=True,
    use_bilateral=True,
    use_cam=CAMType.DTUCAM,
    viewing_condition=ViewingCondition.AVERAGE,
    display_mapping=DisplayMapping.PRODUCTION_HYBRID,
    target_display=DisplayStandard.REC_709,
)

tmo = CompleteDTUTMO(production_config)

Performance: ~0.7s for 1080p

Maximum Quality

Research/validation quality:

research_config = DTUTMOConfig(
    observer_age=24,  # Standard observer
    use_otf=True,
    use_glare=True,
    use_bilateral=True,
    use_cam=CAMType.DTUCAM,
    viewing_condition=ViewingCondition.AVERAGE,
    display_mapping=DisplayMapping.FULL_INVERSE,
    target_display=DisplayStandard.REC_709,
)

tmo = CompleteDTUTMO(research_config)

Performance: ~2.1s for 1080p

HDR10 Output

For HDR displays:

hdr10_config = DTUTMOConfig(
    use_cam=CAMType.DTUCAM,
    viewing_condition=ViewingCondition.DIM,
    display_mapping=DisplayMapping.PRODUCTION_HYBRID,
    target_display=DisplayStandard.REC_2100_PQ,
    target_luminance=1000.0,  # HDR display peak
)

tmo = CompleteDTUTMO(hdr10_config)

Medical Imaging

Diagnostic accuracy:

medical_config = DTUTMOConfig(
    observer_age=45,  # Typical radiologist
    use_bilateral=True,  # Preserve fine details
    use_cam=CAMType.DTUCAM,  # Physiological accuracy
    viewing_condition=ViewingCondition.DIM,  # Reading room
    display_mapping=DisplayMapping.FULL_INVERSE,
    target_luminance=150.0,  # Medical display
)

tmo = CompleteDTUTMO(medical_config)

Configuration from File

Save Configuration

import json

config = DTUTMOConfig(
    observer_age=35,
    use_cam=CAMType.DTUCAM,
    target_display=DisplayStandard.REC_709,
)

# Convert to dict
config_dict = {
    'observer_age': config.observer_age,
    'use_cam': config.use_cam.value,
    'target_display': config.target_display.value,
    # ... other parameters
}

# Save to JSON
with open('config.json', 'w') as f:
    json.dump(config_dict, f, indent=2)

Load Configuration

import json
from dtutmo import DTUTMOConfig, CAMType, DisplayStandard

# Load from JSON
with open('config.json', 'r') as f:
    config_dict = json.load(f)

# Create config
config = DTUTMOConfig(
    observer_age=config_dict['observer_age'],
    use_cam=CAMType(config_dict['use_cam']),
    target_display=DisplayStandard(config_dict['target_display']),
    # ... other parameters
)

tmo = CompleteDTUTMO(config)

Enum Reference

CAMType

from dtutmo import CAMType

CAMType.NONE        # No CAM (fastest)
CAMType.DTUCAM      # Physiologically-grounded
CAMType.XLRCAM      # HDR psychophysics
CAMType.CIECAM16    # CIE standard

DisplayStandard

from dtutmo import DisplayStandard

DisplayStandard.REC_709       # sRGB, HDTV
DisplayStandard.REC_2020      # UHDTV
DisplayStandard.DCI_P3        # Digital cinema
DisplayStandard.REC_2100_PQ   # HDR10
DisplayStandard.REC_2100_HLG  # HLG HDR

ViewingCondition

from dtutmo import ViewingCondition

ViewingCondition.DARK     # <0.2 cd/m²
ViewingCondition.DIM      # 0.2-20 cd/m²
ViewingCondition.AVERAGE  # >20 cd/m²

DisplayMapping

from dtutmo import DisplayMapping

DisplayMapping.LEGACY              # v1.x compatibility
DisplayMapping.WHITEBOARD          # Fast approximation
DisplayMapping.FULL_INVERSE        # Accurate inverse
DisplayMapping.HYBRID              # Basic hybrid
DisplayMapping.PRODUCTION_HYBRID   # Gradient-aware (best)

Validation

Validate configuration before processing:

def validate_config(config: DTUTMOConfig) -> bool:
    """Validate configuration parameters"""
    
    # Check observer age
    if not (18 <= config.observer_age <= 80):
        raise ValueError(f"Observer age {config.observer_age} out of range [18, 80]")
    
    # Check field diameter
    if not (10 <= config.field_diameter <= 180):
        raise ValueError(f"Field diameter {config.field_diameter} out of range [10, 180]")
    
    # Check target luminance
    if not (0.1 <= config.target_luminance <= 10000):
        raise ValueError(f"Target luminance {config.target_luminance} out of range [0.1, 10000]")
    
    # Warn about inconsistent combinations
    if config.use_cam == CAMType.CIECAM16 and config.target_luminance > 1000:
        warnings.warn("CIECAM16 validated only up to 1000 cd/m². Consider DTUCAM or XLR-CAM.")
    
    return True

# Usage
config = DTUTMOConfig(observer_age=25)
validate_config(config)

Next Steps

Pipeline Stages - Understand what each parameter affects
Display Mapping - Display mapping strategies
Performance Optimization - Speed tuning
API Reference - Complete class documentation

Configuration Guide

Configuration Guide

DTUTMOConfig Class

Observer Properties

observer_age

field_diameter

pixels_per_degree

Stage Toggles

use_otf

use_glare

use_bilateral

use_local_adapt

Color Appearance

use_cam

viewing_condition

Display Target

target_display

target_luminance

Display Mapping

display_mapping

gradient_threshold

gradient_smoothing

Advanced Parameters

glare_model

csf_model

cone_integration_time

rod_integration_time

Preset Configurations

Fast Preview

Production Quality

Maximum Quality

HDR10 Output

Medical Imaging

Configuration from File

Save Configuration

Load Configuration

Enum Reference

CAMType

DisplayStandard

ViewingCondition

DisplayMapping

Validation

Next Steps

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally