Finish an edit on the overlaid image before compositing whenever that edit sits after its composite module but is still required in the version you want to place. Move that image’s composite module later, complete the required work, and only then drag it onto the target. On the target image, finish as much major processing as practical before its composite module, because the overlay is brought in at 8-bit precision and substantial later adjustments may reveal banding. This is a workflow decision, not a rule that every module must precede composite.
Specific Decision And Steps
The official composite module documentation defines the handoff precisely: the target receives only the overlaid image’s pixelpipe up to that image’s own composite module. Modules below that point are not included. The module operates on linear RGB scene-referred data, but the imported overlay is limited to eight bits per pixel rather than darktable’s usual internal floating-point values.
Use this sequence:
- List the edits needed for the base image and the overlay separately. Mark each edit as required before or after the target composite, rather than assuming both images should have identical module order.
- On the overlay, identify any required module currently below its composite module. Move that composite module later, complete the required edit, and review the resulting overlay before placing it.
- On the target image, place major tone, color, and detail work before composite when it does not depend on seeing the combined image. Keep an operation after composite only when the combined result is needed to make that decision. For example, in this hypothetical workflow, you might defer a crop if you need to judge the combined framing first; this is an author-recommended choice, not a fixed order or behavior defined by the manual. Check the final composition and crop in the exported image.
- Drag the processed overlay from the filmstrip into the target module. Adjust opacity, rotation, scale, scale on, alignment, and the x and y offsets as needed.
- Inspect the combined result at a useful viewing scale. Check overlay edges and areas where transparency changes, along with gradients and color relationships between the two images.
- If a strong adjustment after composite produces visible bands, move more target processing above composite and reassess. The documentation specifically suggests moving composite after output color profile when banding appears; treat that as a targeted diagnostic, not a guaranteed cure. See the same module reference for the documented placement guidance.
An Original Handoff Worksheet
The following is an author-recommended worksheet for a hypothetical overlay, not a darktable guarantee or a reported software test. Assume a landscape base and a separately processed light texture. “Before” and “after” refer to each image’s own composite position.
| Item | Base image decision | Overlay image decision | Observation or next decision |
|---|---|---|---|
| Required edits | Exposure and color balance before target composite; in this hypothetical workflow, consider cropping after it only if judging the combined framing is necessary | Texture contrast and rotation preparation before overlay composite | Author-recommended decision, not a fixed order defined by the manual; check the final crop in the export |
| Position-sensitive edit | A gentle final contrast adjustment after composite only if the combined image needs it | A module left below overlay composite would be excluded | Move overlay composite below that module before dragging |
| 8-bit handoff check | Avoid planning a large posterization-like change after composite | Inspect smooth texture gradients after placement | If steps appear, move more target processing earlier and compare |
| Visual match | Check base highlights against texture density at 100% view | Check overlay edges, scale, and alignment | Correct opacity or placement before changing unrelated tone modules |
| Performance note | Keep heavy processing before composite where possible | Avoid many large edits on both images | If response becomes poor, simplify or relocate nonessential work |
The performance tradeoff is between independently completing each image, which can avoid repeatedly processing a large second image during target adjustments but may require revisiting the overlay, and retaining substantial processing on both images for decisions that need the composite view. The official documentation warns that processing two images with too many large edits can significantly degrade performance. Reserve post-composite work for decisions that actually depend on the combined image.
Limits And Next Steps After Failure
Banding is a risk from the 8-bit overlay handoff when major processing follows composite; it is not an automatic outcome. If smooth skies, fog, shadows, or other gradual transitions show steps, identify whether the cause is processing after composite. Move that processing earlier when it can be decided independently. If it must respond to the combined image, try a smaller adjustment and inspect the export at its intended size. This comparison is an author-recommended check, not a reported official test.
If the overlay looks wrong before placement, correct its own pixelpipe rather than trying to repair every mismatch on the target. If placement is wrong, use the composite controls instead of reprocessing color. If the target becomes slow, reduce simultaneous heavy edits; the documentation gives no fixed performance threshold.
Three Short Questions
Should every overlay edit be finished first?
No. Finish the edits that must be present in the overlay handoff. An edit that deliberately depends on the combined image can remain after the target composite, with the added banding risk considered.
Does moving composite change the source image file?
The documented behavior concerns the pixelpipe stage supplied to the target. Moving the module changes what the target receives; it does not imply that the overlay becomes a layered file or that later modules are automatically transferred.
Is moving composite after output color profile always the solution?
No. The manual recommends that placement when banding is seen, but it is a diagnostic placement suggestion. Inspect the actual gradients and compare the result after the change.
Sources and next step
This guide interprets public documentation and uses explicitly hypothetical acceptance examples, not application tests. Controls and availability can change; verify the cited manual against your installed version.
For work created in Imagild, carry the input requirements and acceptance checklist into the photo editor. The external software controls discussed above belong to their respective products.