Chromascope for Lightroom Classic

Requirements: Adobe Lightroom Classic with SDK 15.0 support on macOS or Windows.

Option A: Download the release

1. Download the ZIP for your platform from the Download page.
2. Unzip the archive. You will find a chromascope.lrdevplugin folder.
3. Copy the entire folder to your Lightroom plugins directory:
   • macOS: ~/Library/Application Support/Adobe/Lightroom/Plugins/
   • Windows: %APPDATA%\Adobe\Lightroom\Plugins\
4. Open Lightroom Classic.
5. Go to File → Plug-in Manager.
6. Click Add and select the chromascope.lrdevplugin folder.
7. The plugin should appear as enabled in the list.

Option B: Build from source

git clone https://github.com/kevinkiklee/chromascope.git
cd chromascope
./scripts/setup.sh
npm run build:plugins

The built plugin is at plugins/lightroom/chromascope.lrdevplugin/. Copy it to your plugins directory and enable it via Plug-in Manager as described above.

What’s inside the plugin

The plugin folder contains Lua scripts and pre-compiled processor binaries for each platform:

chromascope.lrdevplugin/
  Info.lua                    Plugin metadata
  ChromaScopeDialog.lua       UI dialog
  ImagePipeline.lua           Render pipeline
  EditBridge.lua              Color corrections
  ShowChromascope.lua          Menu entry
  core/index.html             Core library
  bin/macos-arm64/processor   Apple Silicon binary
  bin/macos-x64/processor     Intel Mac binary
  bin/win-x64/processor.exe   Windows binary

With a photo selected in the Library or Develop module, open Chromascope from the menu:

Library → Plug-in Extras → Chromascope

A floating dialog window opens with the vectorscope display and all controls. The dialog stays open while you work — switch to the Develop module and adjust sliders, and the vectorscope updates in real time.

Close the dialog when you are done by clicking the close button or pressing Escape.

The Chromascope dialog is organized from top to bottom:

1. Vectorscope display — The main visualization area showing your image’s color distribution.
2. Color Scheme — Radio buttons to select a harmony overlay (None, Complementary, Split, Triadic, Tetradic, Analogous).
3. Overlay Color — Dropdown to change the color of harmony zone lines (Yellow, Cyan, Green, Magenta, Orange, White).
4. Rotation — Slider and numeric field (0–359°) to rotate the harmony overlay.
5. Density — Radio buttons to switch between Scatter and Bloom rendering modes.
6. Size — Dropdown to change the display size (Small 250px, Medium 500px, Large 700px).
7. Skin color indicator — Checkbox to toggle the skin tone reference line.

The vectorscope plots every pixel’s chrominance on a circular graph:

• Angle — represents hue. The standard positions are: Red at 0°, Yellow at 60°, Green at 120°, Cyan at 180°, Blue at 240°, Magenta at 300°.
• Distance from center — represents saturation. Center is neutral; rim is maximum saturation.

Graticule elements

• Grid rings at 25%, 50%, 75%, and 100% mark saturation levels.
• Crosshair marks the neutral center point.
• Degree markers every 30° around the rim with numeric labels.

What to look for

• Color casts: If the pixel cloud is offset from center, the image has a cast in that direction. Correct with White Balance or Tint.
• Saturation range: A tight cluster near center means muted colors. A spread toward the rim means vivid, saturated colors.
• Harmony alignment: With a scheme overlay active, see how much of your color falls within the harmony zones.

Two radio buttons in the Density section control how pixels are rendered:

Changing the density mode triggers a full re-render of the vectorscope.

The Color Scheme radio buttons activate harmony zone overlays on the vectorscope. Each zone is drawn as a colored line radiating from the center to the rim. The primary zone has an arrowhead to indicate the key color direction.

Rotation

Use the Rotation slider (0–359°) or type a value directly in the numeric field. All zones rotate together. This lets you experiment — spin the overlay until the zones align with your image’s dominant color clusters to evaluate the harmony.

Practical workflow

1. Select a scheme that matches your creative intent.
2. Rotate the overlay until the primary zone aligns with the dominant color.
3. Check how much color falls outside the zones.
4. Switch to the Develop module and use HSL, Split Toning, or Color Grading to push stray colors into the zones.
5. Watch the vectorscope update in real time as you drag the sliders.

Enable the Skin color indicator checkbox to display a reference line at 123° — the industry-standard angle for healthy skin tones in the YCbCr color space.

The line is drawn in your selected overlay color and fades as it approaches the rim.

How to use it: When editing portraits, check that your subject’s skin tones cluster near this line. If they drift, adjust the Hue sliders in the HSL panel (typically Red or Orange channels) to bring skin back toward the reference angle. All skin tones should sit near this angle regardless of ethnicity — the difference is distance from center (saturation), not the angle.

The vectorscope updates automatically as you edit. Two mechanisms work together:

Overlay changes

When you change the harmony scheme, rotation, overlay color, or density mode, the scope responds in two stages:

1. An instant preview re-renders at reduced resolution (128×128) for ~3ms feedback.
2. After 400ms of no further changes, a full-quality render at native size replaces the preview.

This keeps the UI responsive while dragging the rotation slider.

The Size dropdown offers three options:

Changing the size closes and reopens the dialog at the new dimensions. Your overlay settings (scheme, rotation, color) are preserved.

Larger sizes show more detail but render slightly slower. For rapid iteration with develop sliders, Medium is a good balance.

The Overlay Color dropdown changes the color of harmony zone lines and the skin tone reference line. Choose a color that contrasts well with your image’s dominant hues:

Unlike the Photoshop plugin (which renders the vectorscope in a WebView), the Lightroom Classic plugin uses an external Rust binary called processor. This is necessary because Lightroom’s Lua SDK does not support WebViews or direct pixel access.

The pipeline

1. Thumbnail export: Lightroom exports a 256×256 JPEG thumbnail of the current photo from the catalog.
2. Decode: The processor binary decodes the JPEG to raw RGB bytes, resizing to 128×128.
3. Render: The processor maps each pixel onto the vectorscope, applies the density mode, draws the graticule, harmony lines, and skin tone line, then outputs a JPEG.
4. Display: The Lua dialog displays the rendered JPEG using Lightroom’s f:picture component.

Frame alternation

The plugin writes to alternating file paths (scope_0.jpg and scope_1.jpg). This forces Lightroom to recognize each render as a new image and release the previous one from memory, preventing cache accumulation during long editing sessions.

Platform detection

The plugin automatically selects the correct binary for your platform. On macOS, it checks the CPU architecture (ARM for Apple Silicon, x64 for Intel). On Windows, it uses the x64 binary.