color-grade

---

name: color-grade description: Generate .cube 3D LUTs for color correction in DaVinci Resolve and Adobe Premiere Pro. Fixes exposure, color casts, skin tones, and black levels. Use when the user needs color grading, LUT generation, or frame analysis for video footage. argument-hint: [lut-type] [output-path] allowed-tools: Read, Bash(ruby *), Bash(python3 *), Bash(ffmpeg *), Write, Glob, Grep

Color Grade AI

Generate targeted .cube 3D LUTs for color correction. Works with DaVinci Resolve and Adobe Premiere Pro.

Quick Start

# Generate a LUT (presets defined in presets.yml)
ruby generate_lut.rb <type> <output_path> [--strength=0.0-1.0]

# Analyze a frame for color stats
ruby analyze_frame.rb <image_path> <x1,y1,x2,y2> [label]

# Regenerate docs from presets.yml
ruby generate_docs.rb

Config-Driven Presets

All LUT types are defined in presets.yml. Each preset is a pipeline of ordered processing steps (exposure, black crush, skin correction, etc.). Adding a new LUT type means adding a YAML entry — no Ruby code changes needed.

Available LUT Types

Type	What it fixes
night_warm_fix	All-in-one for underexposed scenes with warm/red practicals. ~1 stop lift + skin hue shift + black crush. No desaturation — preserves vivid reds. Use with just AMIRA.
night_purple_fix	All-in-one for underexposed scenes with purple/magenta stage lighting. RGB rebalancing + ~2 stop lift + purple desat + skin hue shift + black crush. Preserves atmospheric purple while fixing skin.
yellow_fix	Warm amber/yellow cast from stage lighting. H=10-60, 55% desat.
red_skin_fix	Sunburnt/flushed red skin from warm practicals. Hue shift to peach, skin-only targeting.
overexposure_fix	Scene-wide ~1 stop reduction with highlight rolloff.
underexposure_fix	Scene-wide ~1.2 stop lift with shadow recovery.
black_crush	Crushes milky/lifted blacks below 12% to true black.
skin_highlight_fix	Subtle skin-only highlight rolloff above 70% luminance.

Workflow

1. Extract a frame: ffmpeg -i video.mov -ss 00:00:30 -frames:v 1 frame.png
2. Analyze regions: ruby analyze_frame.rb frame.png 1500,600,2000,900 skin
3. Generate appropriate LUT: ruby generate_lut.rb overexposure_fix output.cube
4. Apply in your NLE on an adjustment layer / node after your main conversion LUT

Applying LUTs

DaVinci Resolve: Add a serial node after your conversion LUT node. Right-click the node, select LUT, browse to the .cube file.

Adobe Premiere Pro: Add Lumetri Color effect on an adjustment layer. Go to Creative tab, click the Look dropdown, browse to the .cube file.

Stacking LUTs

LUTs can be stacked on separate adjustment layers / nodes. Common stacks:

Night scene with warm practicals (simplest):

1. Camera conversion LUT (e.g. AMIRA LogC to Rec.709)
2. Night Warm Fix (single LUT handles everything)

Night scene with purple stage lighting:

1. Camera conversion LUT (e.g. AMIRA LogC to Rec.709)
2. Night Purple Fix (single LUT handles everything)

Overexposed footage:

1. Camera conversion LUT
2. Overexposure Fix
3. Black Crush

Underexposed footage:

1. Camera conversion LUT
2. Underexposure Fix

Node Order (DaVinci Resolve)

Professional serial node chain:

1. White Balance
2. Exposure
3. Main Conversion LUT
4. General Color Adjustments
5. Color Saturation/Boost
6. Noise Reduction
7. Black Levels
8. Vignette
9. Sharpening

Color Science Notes

• Desaturating warm tones in HSL produces brown/sepia. Use hue shifting or RGB rebalancing instead.
• Skin tones occupy H=10-35, S=0.08-0.45, L=0.25-0.75. Use all three windows (hue + saturation + luminance) to isolate skin from light sources and colored objects.
• LUTs have no spatial awareness. They can't do noise reduction, sharpening, or distinguish adjacent pixels. Each pixel is transformed independently.
• 3D LUTs allow cross-channel operations. Unlike 1D LUTs, a 3D LUT can change the red output based on the green and blue input values.

Requirements

• Ruby 2.7+
• Python 3 with Pillow (for analyze_frame.rb)
• ffmpeg (for frame extraction)