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:

FeatureRawTherapeeDemosaicingMulti-algorithm (AMAZE, IGT, etc.)SharpeningRL Deconvolution (Richardson-Lucy)Noise ReductionIWT / astronomy denoiseLens Correctionlensfun autoColor ManagementProPhoto internal pipelineCamera MatchingAuto-Matched Curve (~50 cameras)Output QualityProfessional

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:

bash

# 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)#

bash

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

bash

# 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

OptionDescriptionDefaultparams_jsonGrading parameters JSONrequired--raw-dirRAW files directory (only needed for relative paths)from config--uniform-dirApply first param set to ALL files in directory—--outputOutput directoryfrom config--qualityJPEG quality (1-100)95--workersParallel workersauto (max 8)--overwriteOverwrite existing filesoff--dry-runPreview onlyoff--pp3-onlyOnly generate PP3 files, don't renderoff--pp3-outputDirectory for PP3-only output./pp3/``--fast-exportUse RT fast export mode (skip heavy modules)off--lens-corrEnable/disable lens correctionfrom config--auto-matchEnable/disable Auto-Matched Camera Curvefrom 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 ...