Photo Grader

Apply professional-grade color grading to camera photos via RawTherapee CLI, driven by JSON parameters.

Engine

RawTherapee CLI is the sole processing engine, providing:

Supported Formats

All RAW formats: NEF, CR2, CR3, ARW, RAF, ORF, RW2, DNG, PEF, SRW, 3FR, IIQ, X3F, etc.

Plus: JPEG (.jpg/.jpeg) and Apple HEIC/HEIF (.heic/.heif).

> Note: RAW files provide full 16-bit editing latitude for maximum quality. JPG/HEIC are 8-bit — grading range is more limited, exposure adjustments should be more conservative.

Dependencies

Declaration file: requirements.txt

Prefer venv: Before running scripts, activate the project-root virtual environment (e.g. .venv/). If it doesn't exist, create one first:

# Create venv and install dependencies (recommended)
python3 -m venv .venv
source .venv/bin/activate
pip install -r photo-grader/requirements.txt

# Or use the skill's setup script (checks + installs)
bash photo-grader/scripts/setup_deps.sh

# Before each session, activate venv
source .venv/bin/activate

RawTherapee CLI (Required)

# macOS
# Install RawTherapee from the official package, then copy the standalone
# rawtherapee-cli into a directory in PATH (for example ~/.local/bin).
rawtherapee-cli -h  # verify it prints "RawTherapee, version ..., command line"

# Debian / Ubuntu
sudo apt install rawtherapee-cli

# Fedora / RHEL
sudo dnf install RawTherapee

> macOS note: always verify with rawtherapee-cli -h. If it exits with 133 / SIGTRAP, macOS likely blocked it before startup. This is common when an agent installs RawTherapee via Homebrew and the user has not explicitly opened/authorized the app or CLI yet. A user-installed and authorized Homebrew CLI can work; otherwise use the official standalone rawtherapee-cli from the RawTherapee package.

Configuration

Copy config.example.toml to config.toml and edit to set your directories. See config.example.toml for all available options.

Usage

# With absolute paths in grading_params.json (--raw-dir not needed)
python3 scripts/grade.py grading_params.json --output ~/Photos/graded

# With relative filenames in params (needs --raw-dir)
python3 scripts/grade.py grading_params.json \
    --raw-dir ~/Photos/RAW --output ~/Photos/graded

# Full resolution
python3 scripts/grade.py grading_params.json --no-resize

# Uniform mode: apply one parameter set to ALL files in a directory
# (useful for timelapse or batch-processing with identical settings)
python3 scripts/grade.py grading_params.json \
    --uniform-dir ~/data/timelapse --output ~/data/output/graded

# Preview
python3 scripts/grade.py grading_params.json --dry-run

# Export PP3 only (for manual inspection or external use)
python3 scripts/grade.py grading_params.json --pp3-only --pp3-output ./pp3_files/

# Fast export mode (skip heavy modules for speed)
python3 scripts/grade.py grading_params.json --fast-export

# Control lens correction and camera matching
python3 scripts/grade.py grading_params.json --lens-corr
python3 scripts/grade.py grading_params.json --no-lens-corr
python3 scripts/grade.py grading_params.json --auto-match
python3 scripts/grade.py grading_params.json --no-auto-match

> Note: --uniform-dir ignores the file field in the JSON and applies the first parameter set to every supported photo in the directory. Useful for timelapse sequences where all frames share one grading preset.

Color Grading Features

All standard Lightroom parameters are supported with intelligent mapping:

Fully Supported

• ✅ Exposure (stop-based)
• ✅ Contrast
• ✅ Highlights / Shadows / Whites / Blacks
• ✅ White Balance (temperature/tint)
• ✅ Vibrance & Saturation
• ✅ Parametric Tone Curve
• ✅ HSL Per-channel Adjustments (8 channels)
• ✅ Three-Way Color Grading
• ✅ Sharpening (RL Deconvolution)
• ✅ Noise Reduction (IWT/astronomy)
• ✅ Vignette
• ✅ Film Grain

RawTherapee-Specific Features

• Auto-Matched Camera Profile: Matches in-camera JPEG tone for ~50 camera models
• Lens Correction: Automatic via lensfun database
• Fast Export Mode: Skip heavy modules for speed
• 16-bit Output: TIFF/PNG at 16-bit depth

Cross-Format Support

The find_raw_file() function intelligently matches filenames across camera brands and formats:

• Absolute path mode: If grading_params.json has "file": "/path/to/DSC_0001.NEF" and the file exists, it's used directly
• Absolute path fallback: If the absolute path doesn't exist, tries different extensions in the same directory
• Relative path mode: If "file": "DSC_0001.NEF", searches under --raw-dir by stem name
• Subdirectory prefix: If a RAW file is in a subdirectory under --raw-dir, the output filename gets a prefix: 001_DSC_0001_暖春丝滑.jpg

Stem-based matching works across formats:

• If grading_params.json says DSC_0001.NEF but the actual file is DSC_0001.CR2, it will still be found
• Also matches JPG and HEIC files: IMG_0001.HEIC or DSC_0001.JPG

Agent Integration

1. Check dependencies: bash scripts/setup_deps.sh
2. Ensure thumbnails: use photo-toolkit first
3. Get grading params: use photo_curator_prompt.md prompt with multimodal LLM
4. Run grading: python3 scripts/grade.py grading_params.json --raw-dir ... --output ...