Darktable Basics: The Pipeline & Scene vs Display-Referred Explained

Watch the full tutorial

Why This Matters Before Anything Else

When you first open Darktable it can feel overwhelming — there are dozens of modules and it’s tempting to jump straight into colour grading or tone mapping. But if you skip understanding the pipeline and the difference between scene-referred and display-referred processing, you’ll hit frustrating, hard-to-diagnose problems later. This is the foundation.

Scene-Referred vs Display-Referred

Your camera captures an enormous range of data — information darker than pure black and brighter than pure white, far beyond what any screen can display. This full, uncompressed data is what we call scene-referred.

Your screen, however, can only show values between 0 (pure black) and 100 (pure white). To get from the scene-referred world to something displayable, you need a tone mapper — AgX, Sigmoid, or Filmic RGB. This is the transition to display-referred.

The key word here is compress, not clip. The tone mapper’s job is to fit the full range of scene data into the 0–100 display range without losing information. Clipping means losing data — a good tone mapper avoids that by compressing gracefully.

The Pipeline: Bottom to Top

Darktable processes modules in a specific order — from the bottom of the module list to the top. Each module has one input and one output, and they chain together. Every module also tells you exactly what kind of data it expects as input and what it outputs — look for the small helper indicator on each module.

A typical pipeline looks like this:

Scene-referred zone (bottom):

• White Balance
• Exposure
• Colour Calibration
• Colour Balance RGB
• (other scene-referred modules)

Transition:

• AgX / Sigmoid / Filmic RGB ← tone mapper

Display-referred zone (top):

• Local Contrast
• (other display-referred modules)

Why Module Order Is Critical

This is where many beginners (and experienced users) run into trouble. Colour Balance RGB must come before AgX — not after.

Here’s why: Colour Balance RGB works on shadow, midtone, and highlight mapping. If you place it after AgX, those tonal ranges have already been compressed and adjusted by the tone mapper — you’re working on wrong data. More visibly, placing Colour Balance RGB after AgX removes AgX’s protection of your whites and highlights, causing colour casts and weird tints in bright areas.

A simple test: move Colour Balance RGB after AgX and zoom into a white wall or bright neutral area. You’ll see an immediate colour cast appear. Move it back before AgX and it disappears.

Resetting Module Order

If your module order gets confused — through experimenting or importing settings — you can reset it:

1. Find the Module Order menu in Darktable
2. Apply the v5.0 RAW preset

This resets everything to the correct default order for RAW files. It’s the baseline Darktable recommends and the one that keeps scene-referred modules before the tone mapper and display-referred modules after.

The Key Difference from Lightroom

Lightroom doesn’t expose any of this — it handles pipeline order silently and doesn’t give you the flexibility to change it. That’s why you never had to think about it before. Darktable gives you full control, which means more creative power but also more responsibility to understand what you’re doing.

Once this clicks, everything else in Darktable becomes more logical. Module placement stops feeling arbitrary and starts making sense as a deliberate, principled workflow.

Quick Reference