Photo Grader

Apply professional-grade color grading to camera RAW/JPG/HEIC photos. Uses RawTherapee CLI as the sole processing engine. Driven by LLM-generated Lightroom-style parameters. Use when the user wants to: - Apply color grading / post-processing to camera RAW/JPG/HEIC files - Batch apply Lightroom-style adjustments (exposure, contrast, HSL, tone curve, etc.) - Process a set of photo files with AI-recommended color parameters - Export color-graded JPGs from RAW/JPG/HEIC files - Apply uniform grading to all files in a directory (timelapse / batch mode) - Generate RawTherapee PP3 sidecar files for manual inspection Triggers: User mentions color grading RAW files, applying Lightroom parameters, post-processing camera RAW photos, grading photos based on AI recommendations, or uniform grading for timelapse sequences. Dependencies: RawTherapee CLI: rawtherapee-cli in PATH (macOS; Homebrew works after user authorization, otherwise use official standalone CLI) / apt install rawtherapee-cli (Debian) Check: bash scripts/setup_deps.sh Workflow: 1. Use `photo-toolkit` to generate thumbnails 2. Use multimodal LLM with photo curator prompt to generate grading parameters 3. Save LLM's JSON output as `grading_params.json` 4. Run `grade.py` to batch-apply grading via RawTherapee ⚠️ IMPORTANT: Use photo_curator_prompt.md V3 (NOT v1/v2). V3 uses Lightroom-standard params with auto-mapping.

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

Engine

RawTherapee CLI is the sole processing engine, providing:

Feature	RawTherapee
Demosaicing	Multi-algorithm (AMAZE, IGT, etc.)
Sharpening	RL Deconvolution (Richardson-Lucy)
Noise Reduction	IWT / astronomy denoise
Lens Correction	lensfun auto
Color Management	ProPhoto internal pipeline
Camera Matching	Auto-Matched Curve (~50 cameras)
Output Quality	Professional

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

Option	Description	Default
params_json	Grading parameters JSON	required
--raw-dir	RAW files directory (only needed for relative paths)	from config
--uniform-dir	Apply first param set to ALL files in directory	—
--output	Output directory	from config
--quality	JPEG quality (1-100)	95
--workers	Parallel workers	auto (max 8)
--overwrite	Overwrite existing files	off
--dry-run	Preview only	off
--pp3-only	Only generate PP3 files, don't render	off
--pp3-output	Directory for PP3-only output	./pp3/
--fast-export	Use RT fast export mode (skip heavy modules)	off
--lens-corr	Enable/disable lens correction	from config
--auto-match	Enable/disable Auto-Matched Camera Curve	from config

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 ...