LUMERIX documentation

What it does

LUMERIX compares a reference frame with the current shot and calculates the correction that moves the shot toward the reference. It measures exposure, contrast, black level, white balance (temperature and tint), saturation, and the color balance of the shadows, midtones and highlights.

The analysis happens once, when you press a button. The result is stored in the plug-in's parameters, so playback and rendering never re-analyze anything. Everything runs on your computer.

The panel has two levels: MATCH holds the five values that make two shots belong together (exposure, temperature, tint, contrast, saturation), plus Match Strength and Show Original. ADVANCED, collapsed by default, holds the finer refinements: black level and per-zone (shadow/midtone/highlight) colour balance, plus skin and highlight protection. Apply fills in both levels; most shots only need to look at MATCH.

It is a deterministic algorithm built on robust statistics (medians and percentiles in linear light). It is not machine learning.

Quick start

1. Drag LUMERIX onto a node (Effects Library > OpenFX). Set Input Encoding to match your timeline (Rec.709 Gamma 2.4 for a standard SDR timeline).
2. Move the playhead to the shot you want to match TO and press Analyze Reference.
3. Move the playhead to the shot you want to fix and press Apply. The MATCH values fill in immediately; open ADVANCED if the shot needs finer per-zone colour balance or protection changes.
4. Adjust anything you like, set Match Strength, and use Show Original to compare.
5. Reset returns MATCH and ADVANCED to zero/default (the captured reference is kept).

Reference selection

Analyze Reference captures the frame under the playhead. In hosts that expose a second input named Reference, and when something is connected to it, that image is analyzed instead.

Only a small set of numbers (around twenty numbers: luminance percentiles, saturation, chroma statistics per tonal zone) is stored in the node and saved with your project. No image data is stored.

The reference is analyzed with the current Input Encoding. If you change the encoding afterwards, LUMERIX asks you to analyze the reference again, because the numbers would no longer be comparable.

Grading the reference first

Analyze Reference captures the image coming into the LUMERIX node, which is the result of every node before it. So you can grade the reference shot by hand in earlier nodes, place LUMERIX after them, and press Analyze Reference to capture that graded look.

LUMERIX's own sliders and any nodes after LUMERIX are not part of the capture. On the target shots, Apply then matches whatever difference is left after the earlier nodes.

If you copy the grade to other shots (for example with Batch Match below), the earlier grade nodes go with it, and Apply on each target matches the remaining differences.

Batch Match (many shots)

The installer adds a small companion script, LUMERIX Batch Match, to DaVinci Resolve. It copies the grade of one reference shot, including its LUMERIX node and the captured reference, to as many shots as you choose. It is written in Lua, so Python is not needed.

1. On the reference shot, set up your nodes with LUMERIX and press Analyze Reference.
2. Open Workspace > Scripts > LUMERIX Batch Match. It lists the shots on the current timeline with thumbnails.
3. Click the reference shot in the REFERENCE SHOT list.
4. Mark the target shots in the TARGET SHOTS list, or press Select All.
5. Tick "Replace the existing grade on the target shots" and press Copy Grade to Targets. The RESULTS list shows OK or FAILED for each shot.
6. Go to each target shot in the Color page and press Apply in LUMERIX.

Batch Match replaces the whole grade on the target shots, not only the LUMERIX node. Pressing Apply on each target is still a manual step, because Resolve's scripting interface cannot press buttons inside a plug-in.

Match (simple panel)

Pressing Apply fills these controls with the measured difference. You can change them by hand at any time. These are the only five values most shots need.

Input Encoding

All color maths run in linear light. Input Encoding tells the plug-in how your pixels are encoded: Linear, Rec.709 Gamma 2.4, sRGB or DaVinci Intermediate. Choose what matches your timeline; a wrong choice gives a wrong (but not damaging) result.

Color structure (in ADVANCED)

Black Level, Shadow Bias, Midtone Bias and Highlight Bias live in the collapsed ADVANCED section, since the five MATCH values already solve most shots. Shadow Bias, Midtone Bias and Highlight Bias add color balance to one tonal zone only. Each is a two-value control: X is temperature (+ warm), Y is tint (+ magenta), both in stops.

Zones are defined in stops relative to 18% grey, so they follow exposure: shadows fade out between -4 and -0.5 stops, highlights fade in between +0.5 and +3 stops, and the midtones are the remainder. The weights always sum to one.

How matching works

1. The frame is sampled on a regular grid (at most 384 by 384 samples) and converted to linear light.
2. Luminance percentiles (p1, p5, p25, p50, p75, p95, p99), peak, black level and saturation are measured. Chromaticity is measured as log2(R/G) and log2(B/G) with weighted medians per tonal zone; strongly saturated pixels count less because they are unlikely to be neutral.
3. Contrast is solved from the p5 to p95 spread, then exposure from the median, so that the two agree.
4. Temperature and tint come from the global chromaticity difference; the zone biases capture what is left in each zone.
5. Because white balance, contrast and saturation interact, the solution is refined in a closed loop: the candidate is rendered on a small copy of the target, re-analyzed, and the remaining difference is folded back (damped, up to eight times, keeping the best result).
6. For SDR footage the exposure is limited so the 99th percentile is not pushed into clipping. Corrections are limited on purpose (exposure ±3 stops, white balance ±0.6, zone bias ±0.3) to avoid violent color shifts.

Skin protection (in ADVANCED)

Skin is detected by hue. Each pixel is converted to Rec.709 Y'CbCr (perceptual, gamma 1/2.4) and compared with the skin-tone line of the vectorscope, at about 135 degrees in the Cb/Cr plane, with a luma window (not near black or white) and a chroma window (not grey, not extremely saturated).

Where a pixel looks like skin, its original chroma is kept and only its brightness follows the match. Skin Protection sets how strongly (0 is off, 1 is full).

This is a heuristic. Wood, sand or a warm wall of the same hue can be treated like skin. Lower Skin Protection if a correction is being held back in such areas.

Highlight protection (in ADVANCED)

Bright areas keep their original chroma (scaled to the corrected brightness), so highlights do not turn a different color when the match warms or cools the image. For display-referred encodings (Rec.709 Gamma 2.4 and sRGB) values pushed toward 1.0 are also rolled off softly instead of clipping.

For HDR, linear and log timelines, where values above 1.0 are valid, set Highlight Protection to 0 to switch the roll-off off.

Match strength, Show Original and Reset

Match Strength interpolates between the original (0) and the fully corrected image (1) in linear light. Show Original disables the effect while checked, for an instant before/after. Reset restores all analysis values, biases, protection values and strength to their defaults and keeps the captured reference.

Troubleshooting

• Nothing changes: open the LICENSE section. Without an active trial or license the plug-in passes the image through. Also check Match Strength and Show Original.
• "Analyze a reference frame first": press Analyze Reference on the reference shot before pressing Apply.
• "Different Input Encoding": press Analyze Reference again after changing Input Encoding.
• The result is too strong: lower Match Strength, or reduce the individual values. Very different shots are limited on purpose.
• Skin looks wrong: raise Skin Protection. Areas that are not skin look held back: lower it.
• Highlights look dull on HDR footage: set Highlight Protection to 0.

Performance

Rendering is a pure per-pixel function of the parameters: it does not analyze the frame and never talks to the network. It supports tiles and different render resolutions, and it is multi-threaded across all CPU cores. The analysis on Apply works on a reduced copy of the frame and takes a small fraction of a second.

Benchmarks are measured with the benchmark tool in the source repository (see docs/BENCHMARKS.md) and are not quoted here as marketing numbers.

On NVIDIA GPUs the plug-in can render through CUDA when the host provides GPU images. This is built in and matches the CPU output in automated tests, but it has not yet been verified inside DaVinci Resolve. Everywhere else the CPU path is used.

FAQ

Are my frames uploaded?

No. Analysis and rendering happen on your computer.

Does it use AI?

No. It is a deterministic algorithm.

Can I animate the controls?

Yes. The value controls are animatable. The captured reference is a fixed set of numbers.