Scene-Referred Workflow is the heart of modern darktable software and distinguishes it from programs like Lightroom or even older darktable versions.
1. The Basic Problem: Display-Referred (The Old Way)
In the past (and in many other programs), the image was forced into the screen’s color space (usually sRGB or AdobeRGB) very early in the processing chain (pixelpipe).
- The Problem: Camera sensors have a huge dynamic range (very bright to very dark). Screens have a small one.
- If you “compress” the image to the screen’s range too early (tone mapping), you lose the physical relationship to light. Bright highlights (sun, lamps) are simply cut off (clipped) at “white” (value 1.0 or 255).
- Operations like “increase exposure” or “blur” then often look artificial because the real light information is missing.
2. The Solution: Scene-Referred (The New Way)
In the scene-referred workflow, darktable treats pixel values as physical light values for as long as possible.
- Unlimited Space: There is no upper limit at “white”. A pixel can have the value 1.0 (white), but also 10.0 or 100.0 (much brighter than white, e.g., the sun).
- Physics: Modules like Exposure, Color Calibration, or AgX work linearly. This means if you double the exposure, the numerical value simply doubles. This corresponds exactly to what happens when you make the light brighter in reality.
- Late Tone Mapping: Only at the very end of the pixelpipe is the image “translated” for your monitor. This is done by modules like AgX. They take this huge dynamic range and elegantly compress it into the range your monitor can display.
Why is this important for you?
- HDR Handling: You can rescue highlights that would have simply burned out in the old workflow because the information “brighter than white” is preserved until AgX makes it visible again.
- More Natural Colors: Since colors are mixed physically correctly, there are fewer strange color shifts (e.g., a blue sky doesn’t suddenly turn gray or purple when darkened).
- Module Order: In darktable, the order is fixed (from bottom to top).
- Bottom (Raw): Physical corrections (Exposure, White Balance).
- Middle: Creative adjustments.
- Top: Tone Mapping (transformation to the screen) (AgX).
Important: Some modules like Watermark or Grain are display-referred and are applied after tone mapping. However, they have no influence on image quality.
Quick Guide for the Workflow
When you open a RAW image, darktable automatically does the following in modern scene-referred mode:
- Exposure: Raises the brightness so that the midtones (the main subject) are correctly exposed. Highlights are allowed to burn out (have values over 1.0).
- Color Calibration: Takes care of white balance (CAT).
- AgX: This is the “compressor”. It brings back the blown-out highlights (values > 1.0) and ensures that the black is crisp.
Your Job:
You only adjust the brightness of your main subject in the Exposure module. Ignore if the sky burns out. You fix that afterwards in the AgX (Tone Mapping) module.
In summary: Scene-Referred simulates real light until the very last moment, while Display-Referred pretends the image is already a finished photo on the monitor.
You can find more information in the official manual: scene-referred workflow
Questions about this topic? Discuss with us in the forum!
January 27, 2026
Hi Chris, thanks.
Just to clarify, my main observation was about the order in which the 3 modules listed here are automatically applied when opening a RAW image for the first time. It’s not:
1. Exposure
2. Color calibration
3. AgX
It’s instead
1. AgX
2. Color calibration
3. Exposure
Regarding my question (which should have had a question mark), I was asking confirmation that you can’t change parameters for a module which is not at the top of the stack. What happens instead if you try to do it, is that a new instance of that module is added on the top of the stack.
Is it correct?
The pixel pipeline (pixelpipe) is the technically defined sequence in which darktable calculates an image from RAW input to finished output.
Direction: Processing runs strictly from bottom to top. The RAW image starts at the bottom of the module list (not the history stack in the left panel), and each activated module adds a new processing layer on top of it.
Visual representation: The order of the modules in the right-hand panel (darkroom) corresponds exactly to the order in which they are calculated, bottom to top.
From: https://darktable.info/en/darkroom/in-depth/the-pixelpipe-and-module-sequence/
You can use any module (on the right-hand side) at any time, in any order. So you can easily use ‘Colour calibration’ first, then ‘Exposure’, and then ‘AGX’. The order in which these modules are displayed corresponds to darktable’s internal processing.
I understand the concept of History Stack and the bottom-up order. What I was trying to say, is that this article states that those 3 modules are automatically applied in a specific order:
> When you open a RAW image, darktable automatically does the following in modern scene-referred mode:
>
> Exposure: Raises the brightness so that the midtones (the main subject) are correctly exposed. Highlights are allowed to burn out (have values over 1.0).
> Color Calibration: Takes care of white balance (CAT).
> AgX: This is the “compressor”. It brings back the blown-out highlights (values > 1.0) and ensures that the black is crisp.
This is not what I see when I open a RAW image. The order is the inverse: AgX; Color Calibration; Exposure.
Then my question was: once these modules have been automatically applied upon opening the RAW and we follow the workflow described here, when we start modifying any parameters of the above mentioned modules, we are actually applying other instances of these modules, instead of changing the previous history of the stack. Is this correct?
Or is this guide suggesting that we should, for example, truncate the history just before AgX has been automatically applied, then apply AgX and manually tweak this module, and the same for Color Calibration and Exposure?
I believe it’s the former (we don’t alter the history, we apply new instances of the modules on top) and I think that this crystal clear.
I understand the concept of History Stack and the bottom-up order. What I was trying to say, is that this article states that those 3 modules are automatically applied in a specific order:
To be precise, it states that the three modules are added. They are also listed there in the correct order (as they are processed in Pixelpipe), from bottom to top: exposure, CC and AgX.
This is not what I see when I open a RAW image. The order is the inverse: AgX; Color Calibration; Exposure.
As the modules are processed from bottom to top, the display in DT is correct.
Then my question was: once these modules have been automatically applied upon opening the RAW and we follow the workflow described here, when we start modifying any parameters of the above mentioned modules, we are actually applying other instances of these modules, instead of changing the previous history of the stack. Is this correct?
No, we’ll use the existing modules. Especially with AgX, I’d advise against using another instance.
Or is this guide suggesting that we should, for example, truncate the history just before AgX has been automatically applied, then apply AgX and manually tweak this module, and the same for Color Calibration and Exposure?
There is no need to make any changes to the History Stack. It simply displays the steps you have taken. This includes the modules that are added automatically. It is merely a history; it has no effect on the image.
I believe it’s the former (we don’t alter the history, we apply new instances of the modules on top) and I think that this crystal clear.
That’s not quite right. Please have a look at our landing page, where we try to explain visually how the modules (layers) work in darktable.
Hi Chris, I have to apologise. I didn’t read carefully your first reply and didn’t get that the order in which modules are applied is on the **right hand side**. I kept thinking that the history stack on the left side was indicating that order, while instead it’s a history of all the edits, hence the reason why some modules appear to be applied twice even when I didn’t create any new instance: it is because the history stack is logging every tweak in the order they are made, so if I return to module 1 after having applied module 2, only to change a parameter in module 1, the history will put this change on top of the history stack. That’s actually really helpful to track every single change and roll back when needed.
Thanks again for your patience.
No problem at all, and there’s no need to apologise. You’re not the first person to have fallen into this ‘trap’.
Please get in touch if you have any further questions.
Best regards, Chris
When I open a RAW image, darktable automatically applies some modules which I can’t delete (“always-on”), then it applies, in order: white balance, highlight reconstruction, AgX, color calibration, exposure, orientation. That is, the order it’s reversed with respect to the one they are listed here.
Also, adjusting any parameter in Exposure or AgX actually means that we apply a new instance of these modules on top of the stack, am I right? It’s not possible to intervene on the modules automatically applied by Darktable.
Hallo Gius,
Please take a look at the following page:
https://darktable.info/en/getting-started/quick-start/darktable-first-steps/
… there are non-optional modules that are mandatory for viewing. These have a circle with a border.
You mean the History Stack in the left-hand menu.
https://darktable.info/en/darkroom/in-depth/history-stack/
The modules on the right are the ones that affect the image: AgX, Exposure, etc.
https://darktable.info/en/darkroom/in-depth/the-pixelpipe-and-module-sequence/
Just get in touch if you have any questions.
Best wishes, Chris