![]() |
Ansel 0.0
A darktable fork - bloat + design vision
|
Corrected against 9608e354ac on 2026-09-29. The audit before that found 5 claims in this file wrong of the tree and 6 stale. Two matter to anyone acting on it: the shipped $DEFAULT is medium bleach / V8, not low bleach, and the sigmoid's shoulder exponent is computed at runtime, not a fixed 7.8 — a fixed one was measured to sit on the JND ceiling and over-compress the top highlight stop. Re-measure before acting on a claim older than the code you are changing, and re-date this line when you do.
Status: implemented (CPU + OpenCL), shipped 2026-07; the design is closed. Code: src/iop/filmicrgb.c (filmic_agx*, filmic_agx_prepare_bracket, perceptual sigmoid curve type), data/kernels/filmic.cl (sigmoid evaluator + filmic_agx device function dispatched by the chroma kernel), tools/derive_filmic_agx_primaries.py (the fitting engine), tools/fit_agx_ladder.py (the offline orchestrator that fits and patches the whole variant ladder), tools/derive_filmic_default_curve.py (default-curve appearance match).
This report records what was taken from Blender/darktable AgX, what was changed and why, the objectives and compromises behind every shipped constant, the approaches that were tried and discarded, and the parameters that could be added later if real use demonstrates the need. It is the durable rationale: read it before touching this area, and before answering any "why doesn't this match AgX?" question.
Report map. §Vocabulary is the glossary. §Motivation covers why norm-based and per-channel tone mapping both fall short and why darktable AgX was not adopted. §Architecture and §The bracket document what shipped. §The colour-preservation slider and §The five variants are the two user-facing degrees of freedom. §Fitting methodology and §Findings consolidate what the derivation taught us; §Investigated and discarded records the dead ends. §The default curve and §Future parameters close the report.
The rest of this document uses these terms constantly. If you can read C but not color-science papers, read this first — every section below assumes it.
EV, dynamic range, mid-gray. Exposure values: a difference of 1 EV means twice or half the light. Mid-gray (~18% of a white diffuse surface) is the reference; "+4 EV" means 16× brighter than mid-gray. The dynamic range is the span between the darkest and brightest EV the curve maps to the display.
Tone curve, toe, shoulder, latitude, pivot. The S-shaped curve that compresses the scene's dynamic range into what a display can show. The middle straight-ish segment is the latitude; its slope is the contrast; the bend easing into black is the toe, the bend easing into white the shoulder; the pivot is where mid-gray sits.
Hardness ("gamma"). A power function \(y^p\) applied after the curve. It is required plumbing (display encoding), but it also darkens shadows a lot on its own — a recurring plot point below.
Primaries, working profile, gamut. The three "purest" red, green and blue a color space can express are its primaries; every color is a mix of them. The working profile (linear Rec2020 here) is the color space the pipeline computes in. The gamut is the set of colors a space or device can represent — picture a triangle in a 2D "map of all colors" (chromaticity diagram), with the primaries at the corners and white in the middle.
Per-channel vs norm-based tone mapping. Two ways to apply the curve. Per-channel: run R, G and B through the curve independently — colors near white converge and bleach (the "film look"), but hues also shift as a side effect. Norm-based: compute one brightness number per pixel (a "norm"), run only that through the curve, scale R, G, B by the result — colors stay exactly as they were, but perceived lightness and local contrast can look off. Neither is right; they are the two ends of a trade-off.
Chroma, hue, Ych. Chroma ≈ how far a color is from gray; hue ≈ which color it is (the angle on the color wheel). Ych is a coordinate system (from Richard Kirk / Filmlight) storing brightness (Y), chroma (c) and hue (h), designed so that equal hue-angle steps look like equal hue changes to a human — which plain RGB or HSV do not guarantee. When we "measure hue drift in degrees", it is in this system, so the degrees mean something perceptually.
Inset / outset matrices, the "bracket". The core AgX trick. Before the curve, a 3×3 matrix ("inset") nudges the working primaries toward white — imagine gently shrinking the gamut triangle and slightly twisting it. This makes the per-channel curve bleach saturated colors sooner and steers the hue shifts. After the curve, another matrix ("outset") expands everything back — in Ansel deliberately a bit more than the inset compressed (see the self-recovery finding in the slider section), so that valid diffuse colors get their saturation back while extreme highlights stay bleached.
Gamut mapping. The final safety net: if a pixel's color cannot exist on the display (out of gamut), reduce its chroma — at constant hue — until it fits. Filmic has done this since v6, against both the working and the export profile.
Monotone, C1. A monotone curve never goes back down — no wiggles, so brighter input is always brighter output (a curve that isn't monotone creates banding and hue inversions). C1 means value and slope are continuous at the segment joints — no kinks.
Least-squares vs minimax; "railing". Two ways to fit parameters. Least-squares minimizes the average error; minimax minimizes the worst single error. "Railing" is when an optimizer slams a parameter against its allowed limit — a smell that the objective doesn't actually constrain that parameter (several appearances below).
CIECAM16 J, appearance match, surround, veiling flare. CIECAM16 is a standard model predicting how bright/light something looks given the viewing conditions (J is its perceived-lightness output). An appearance match asks: what display luminance looks the same as this scene luminance, to an observer adapted to each? The surround (dim room vs daylight) changes the answer — this is why images need more contrast on a screen in a dim room. Veiling flare is stray light reflecting off the screen: it puts a floor under how dark anything can look, which decides how much shadow detail is even visible.
JND. Just-noticeable difference: the smallest change a human can see. Used as the yardstick for "is this transition too abrupt to be acceptable".
Conditioning. How much a matrix inversion amplifies small errors. A well-conditioned pair (small number, ~1–8 here) is numerically safe; a near-singular one turns rounding noise into visible artifacts.
Working in RGB makes lightness/brightness/luminance a by-product of the trichromatic signal, which binds all perceptual color attributes (hue, colorfulness, lightness/brightness) in non-trivial ways.
Color-science research on methods to reduce dynamic range from any given scene to what the display can render (tone-mapping), while preserving the perceptual color attributes unchanged, have produced so far only brittle and contextually-valid HDR color appearance models that are useless for any image-processing pipeline. In addition, these fail to account for Bezold-Brücke shift, Abney effect and Helmholtz-Kohlrausch effect.
Tone-mapping on individual RGB channels produces chroma/saturation and hue shifts as a by-product. While some saturation shifts and some hue shifts are deemed pleasing and desirable (highlights desaturation being seen as a "filmic" signature – more on that later), the tone-mapping core issue is in controlling how much of those shifts we let in for the amount of dynamic range compression we impose. As such, there is no control at all. The scene-referred workflow makes this issue a bit more manageable, by dealing with color before tone-mapping, which reduces a lot of oversaturation issues we had with display-referred. However, that doesn't solve the issue of hue shifts, that are still largely unpredictable.
While saturation is kind of reduceable to some arbitrary "intensity" or "vividness" of color, hues carry meaning and often give their name to colors, so they are semantic in nature. In addition, tonemapping RGB channels on portrait photography desaturates skin tones but also shifts them toward yellow/green, which might be ok and even flattering for Caucasian (white-skinned) people, because it might soften redness and blemishes, but it can be unflattering and uncalled for Arabian and Asian (olive-skinned) people. Beyond aesthetics, this is a racially-charged matter. Let's not reproduce Kodak racial biases when we can avoid it.
Then, what people associate with "film signature look" is often exaggerated. Movies shot on Technicolor, like Lawrence of Arabia, show deep blue skies at rather high luminance, that are properly impossible to get with the forced-desaturation of independent RGB channels tone-mapping:

So the bleached highlights look is only one possible film look among others, and there is no reason to trap every photographer into this look, especially if it is going to be justified by a misinformed call to tradition. Moreover, there is no reason why all highlights should be bleached if they otherwise fit within the display colour gamut. Just because film couldn't render those colours is no justification for digital to forfeit them too. What matters most is the smoothness of local color gradients, and giving creative options to artists.
Handling tone-mapping on individual RGB channels is therefore the guaranty to drive any exigeant colorist insane.
For this reason, filmic historically resorted to tone-mapping a single metric for each pixel : the norm of the RGB vector. Across this mapping, the RGB ratios (as the ratio between each RGB channel and the pixel norm) were preserved unchanged, which gave a radiometrically-accurate light spectrum mapping. The rationale was: given the impossibility of ensuring the constancy of visual colour attributes, for lack of proper science, at least light physics provided a predictable ground-truth we could hold onto. No approximation required, no broken colour model in the mix.
This method had the benefit of preserving deep blue skies, as well as sunset colors, which, combined with gamut-mapping, ensured we made the best use of all available display gamut while preserving the scene light information.
There were two problems though:
After 6 iterations of design, using different mapping strategies for tonality, hue and chroma, in 2023, for filmic v7, I resorted to a weighted (user-parametric) mix between the max RGB norm tone-mapping and the channel-wise (independant) mapping at constant hue. Those were the 2 opposites of the spectrum, from full color saturation (albeit with weird local contrast) to full bleaching. But the whole thing still happens at constant hue, which still makes some users unhappy about how their sunsets look.
Filmic got a lot of backlash among Darktable users when it came out (2018-2019), because it was "too complicated". Then in 2025 comes a port of Blender AgX that:
AgX is not that different from Filmic that it requires its own, different module: this only confuses users. But then, the whole feature split is a nonsense too: it is a pipeline within the pipeline, with fine-grained color controls that don't belong there since the feature split approach of the scene-referred workflow was "divide and conquer" (chromaticity handled apart from lightness) to better manage it, and the typical modules duplicated in AgX support masking and blending with several instances for better control in difficult situations.
So, AgX is yet another example of overengineering by committee, only leading to overwhelming users and newcomers for no valid reason, except "it was new and cool so we implemented it".
Read darktable/src/iop/agx.c and trace where its numbers come from. The "scene-referred default" primaries are:
Eight significant digits, cited to a LUT-generation script in a personal GitHub repository (EaryChow/AgX_LUT_Gen) and a 1000+ post forum thread. There is no objective function, no error metric, no derivation, and no regression harness anywhere in that lineage: the digits are precise because a script printed them, not because anything constrains them. That is precision theater — nobody, including their authors, can re-derive these numbers or say what they optimize. The outset values (0.290776401758f…) are equally unexplained, and Blender ships master_unrotation_ratio = 0 — the inset rotations are not undone after the curve, which bakes a permanent skew and midtone desaturation into a transform marketed as technical. The tone curve defaults are documented in their own comments as "about halfway between values required to match sigmoid'd scene-referred defaults and those used by its 'smooth' preset" — defaults defined by splitting the difference between two other sets of hand-tuned defaults. The "read exposure from metadata" feature computes black = (−8 + 0.5·exposure), white = (4 + 0.8·exposure): two linear regressions with unexplained coefficients. The curve's authoritative specification is a Desmos calculator link.
None of this is disqualifying for a creative preset — hand-tuned looks are legitimate. It is disqualifying for what AgX claims to be: a technically grounded view transform. Two claims deserve specific debunking:
The point of the Ansel port is not that our constants are different — it is that they are derivable. Replacing filmic's alleged suboptimality with AgX's constants would have swapped one un-re-derivable point solution for another, which is no progress at all. Instead, every shipped number has a committed derivation with a stated objective:
Where the AgX heritage values were right, the derivations recovered them — the safe toe power converges to 1.5 (their default), the soft preset lands on their gentle roll-off feel, filmic's contrast is confirmed — which is what independent validation looks like. Where they weren't, we know exactly why and in which viewing conditions. That is the difference between engineering and democracy-by-forum-thread.
Strip away the GUI and the branding, and one genuinely useful idea remains.
Run each RGB channel through the S-curve independently and something interesting happens in the shoulder: for a bright saturated pixel, the highest channel gets compressed hard while the lower ones catch up, so the three values converge — and equal RGB values are white. Highlights therefore bleach toward white automatically, and they bleach in proportion to how much they are being tonally compressed. The same happens in mirror at the toe: channels converge toward black. This coupling between tone compression and desaturation is what people recognize as the "film look", and it is exactly what norm-based tone mapping cannot do (a norm preserves the color ratios by construction, so a compressed highlight keeps its full saturation and reads as a flat colored patch).
The cost of per-channel is that the hues also shift while the channels converge, in directions dictated by where the primaries happen to sit — not by anything perceptual. AgX's real contribution is the inset/outset bracket around the curve: pull the primaries toward white before the curve (which controls how fast colors bleach and pre-steers which way hues drift), and expand back after. That is 6 meaningful numbers — a chroma compression and a rotation per primary — steering the whole behavior.
Everything else in AgX — the specific eight-decimal constants, the partial-only outset, the HSV hue mix, the built-in color grading block — is one particular hand-tuned point in that design space. The bracket is the method; the rest is somebody's taste frozen into code.
Curve type perceptual — a new value of dt_iop_filmicrgb_curve_type_t (the shadows/highlights control), selectable per side alongside the legacy hard/soft/safe, usable with any color science and the default for new edits. It replaces the polynomial toe/shoulder segment with a generalized sigmoid ( \(u/(1+u^p)^{1/p}\) — an S-shaped function whose exponent \(p\) sets how long it hugs the straight line before rolling off). Why it is better than the polynomials: it is monotone for any setting (polynomials can wiggle when the constraints get tight — that is what the orange warnings on the filmic graph were about), it passes exactly through the black and white endpoints, it joins the latitude without a kink (C1), and when the requested geometry is impossible (the straight line would have to bend backwards to reach the endpoint) it degrades into a clean power curve instead of a broken fit. Unlike the legacy types it has one exponent per side (not hard/soft/safe), and only the toe's is fixed — 1.5, from the CIECAM16-J appearance match with a local JND tolerance (see the default-curve section). The shoulder's is computed at runtime from the geometry, matching the latitude slope at the node (filmicrgb.c:3947, spline->M4[1] = sigmoid_slope * dx / dy), which gives q ≈ 1 for a low-DR studio curve and ≈ 2.5 for a 14 EV ETTR curve. The comment at filmicrgb.c:3835-3844 records why: highlights have no perceptual floor, the lightness match is indifferent to the shoulder power (its RMS is flat, so fitting it just rails against whatever bound it is given), and an earlier fixed 7.8/9.0 sat on the JND ceiling and over-compressed the top highlight stop. Shadows do have a perceptual floor, which is why the toe can be a constant and the shoulder cannot. Implementation detail: the sigmoid's runtime parameters travel in the unused slots of the internal spline coefficient vectors, so the OpenCL kernels needed no new arguments.
History note: this first shipped (for ~24h) mislabelled as a spline version v4 (2026) — wrong, because a spline version is the node geometry (how latitude/balance place the toe/shoulder nodes) while the sigmoid is the segment shape between them; they are orthogonal. It was moved to a curve type; the v4 spline-version enum value was removed and any history that stored it falls back to v3 node geometry silently — no migration was written, given the ~24 h exposure window.
The inset matrix M has a friendly interpretation: its three columns are simply the new, displaced primaries written as colors of the working space. (Multiply M by pure red (1,0,0)ᵀ and you get the first column — the slightly desaturated, slightly rotated red that the rendering space uses.) Reading the matrix that way makes every constraint easy to state:
| # | darktable/Blender AgX | Ansel v8 | Why |
|---|---|---|---|
| 1 | Separate agx module (33 params, 2 notebook pages, 2845 LoC) | Filmic color science value, adds 457 LoC | Same purpose as filmic (view transform); a second tone mapper splits users and duplicates the log/curve/picker scaffolding wholesale. |
| 2 | Base primaries selector (export/work/Rec2020/P3/AdobeRGB/sRGB) | Working profile, always | The base folds into the constants; "export profile" as a base made the render depend on an output setting while we already gamut-map to the export profile at the end. |
| 3 | Primaries displaced in CIE xy, rotations in xy radians | Displaced in Kirk/Filmlight Yrg chromaticity, rotations in Yrg angle | A degree of rotation then means the same perceptual hue shift for every primary (Yrg is fitted to even Munsell hue spacing); xy radians are perceptually uneven across the wheel. |
| 4 | Hand-tuned constants (Blender forum lineage), 12 user sliders + 2 master ratios + reverse toggle | Fixed anchors (per-primary inset + per-primary outset chroma & rotation, 12 params) fitted offline by tools/derive_filmic_agx_primaries.py; five preset variants (no/low/medium/high/extra bleach), no runtime bracket sliders | The sliders exist upstream so users can fit their own rendering space; the shipped configurations are what everyone uses. The residual empiricism moves into stated, reproducible objectives (per-hue perceptual targets) instead of thirty floats in a params struct. Per-primary insets are only safe because those targets pin every hue — under a scalar-average objective they let the fit game an unseen colour, so the earlier design held the inset uniform. |
| 5 | Outset partially restores purity (under-expansion: bakes midtone desaturation in), rotations not reversed by default (Blender), separately editable (darktable) | Outset over-expands per-primary (ratios > 1), jointly fitted with the inset, not editable | Fitted so valid diffuse colors (skin database + reflectances) recover their chroma through the bracket itself, with the output≤input chroma clamp trimming the excess per pixel. Blender's under-expansion bleaches midtones by construction — the exact opposite of what skin tones need; an exact inverse was tried and retired (see constraints). |
| 6 | Hue restore mix in HSV (device-space hue), default 60% | Shortest-arc hue mix in Kirk Ych, inside the existing gamut-mapping stage | HSV hue is not a perceptual quantity. Filmic already computes Ych per pixel and its gamut mapper reduces chroma at constant hue, so deciding the hue first in the same metric is both cheaper and coherent. The recovery is exact per pixel, not a first-order matrix approximation ("Abney compensation" limited only by the Yrg Munsell fit — weakest in deep blue-violet). |
| 7 | "Look" block: lift/slope/power/saturation + brightness | Dropped | Strict subset of Color Balance RGB (lift↔shadows lift/offset, slope↔gain+contrast, brightness↔power, saturation↔saturation global), computed there in a proper perceptual space with per-range masks. |
| 8 | Own log encoding fixed to 0.18 mid-gray, contrast renormalized to the 16.5 EV Blender range, gamma-compensated slope, auto_gamma | Filmic's existing log encoding, grey/DR params, contrast, auto_hardness | Identical math where it overlaps; the renormalizations only existed to keep Blender's slider values meaningful. Filmic's parameterization is authoritative here; no values were imported. |
| 9 | Own pivot/toe/shoulder curve machinery (13 params) | Filmic spline geometry + sigmoid as a new curve type ("perceptual") | The curve DoF map 1:1 onto existing filmic params (pivot↔grey, linear ratios↔latitude+balance, curve gamma↔hardness). The genuinely new DoF — the toe/shoulder roll-off shape — is not a user control: the toe is a fixed appearance-matched exponent (1.5) and the shoulder is a slope-matched power roll-off computed at runtime from the geometry (see the default-curve section). |
| 10 | Gamut compression hardcodes Rec2020 luminance coefficients | Generalized to the working profile's Y row | Works for any matrix working profile; identical result when working in Rec2020. |
| 11 | No output/export gamut mapping | Existing filmic Yrg gamut mapping runs after the bracket | dt AgX output can leave the export gamut freely; ours cannot. Strictly an improvement. |
| 12 | "Read exposure from metadata" heuristics (−8+0.5·exposure …) | Not ported | Magic constants; filmic's pickers and auto-tune cover the workflow. |
| 13 | dynamic_range_scaling | Not ported | Identical to filmic's existing security_factor. |
| 14 | Matrices rebuilt per process() call from params | Anchors are compile-time constants; the (cheap) bracket construction still runs in process() because the working profile is only known there | Same cost class (3×3 algebra per frame, not per pixel). |
| 15 | OpenCL kernel (agx.cl) | filmic_agx device function dispatched by the existing chroma kernel (4 extra args: inset/outset matrices, luma coefficients, recovery mix) | Reuses the shared Ych/gamut-mapping CL machinery instead of duplicating it in a standalone kernel. |
Known accepted cost of placing v8 in the color science enum (rather than a preserve_color value): an older Ansel build reading a v8 edit falls through every branch of its dispatch and produces an undefined output buffer for that image. Params/DB/styles remain structurally compatible (no migration, no introspection bump); only the render of v8-edits is undefined on old builds. The preserve_color placement would have degraded to a defined v7 render instead, but was rejected as semantically wrong (v8 replaces the whole color handling, exactly like v7 does).
Under v8, the old saturation slider becomes the one creative control of the rendering: film character on the left, color fidelity on the right. This section explains why it is designed that way — the answer came from a failed first attempt.
The first version had no way to recover color, and visual testing immediately flagged it: bright legitimate colors — sunsets, blue sky against orange clouds — washed out irrecoverably. The obvious suspect was the inset matrices (they exist to bleach things, after all), so we measured it: take a half-saturated blue, scale it so its brightness sits at +2.5 EV like a bright sky, run it through the pipeline. It keeps 18% of its chroma with the matrices — and also 18% with the matrices removed entirely. The matrices were innocent. The washing comes from the per-channel shoulder itself: for a blue pixel to be bright, its blue channel must be enormous (blue contributes almost nothing to luminance), which parks it deep in the shoulder where all channels converge. Orange, whose channels contribute more evenly, keeps 58% under the same test. So the insets kept their real job — taming clipped and out-of-gamut colors, where they demonstrably help — and the cure for washed sunsets became a recovery control instead.
The recovery has a pleasant mathematical property. Ych chroma is luminance-normalized (it measures "how colorful relative to how bright"), so taking the tone-mapped brightness and re-imposing the original chroma and hue on it reconstructs exactly what norm-based tone mapping would have produced, color-wise — while keeping the per-channel tonality. In other words, the slider's right end gives you norm-like color without norm-based tone mapping's flattened local contrast; its left end gives you the full film character. Any overshoot near display white is caught by the gamut mapper, so peak display brightness stays reachable.
The slider is hue-only: it recovers none, some or all of the per-channel hue drift and never touches chroma. With \(a = s/100 \in [-1, +1]\):
The three anchor points:
A short-lived earlier version also offered chroma recovery on the positive half ( \(\beta_\text{chroma} = \max(0, a)\), for speculars/jewelry). It was removed: mixing any original chroma back on top of the bracket's output kinks highlight gradients — the recovered value \(\beta\cdot c_\text{orig}\) fights the bracket's smooth bleach roll-off at the min(c_orig, bracket) clamp, and the visible seam in a bright colored gradient was worse than the muted highlight it rescued. Chroma fidelity of valid colors never needed the slider (it is in the bracket); recovering the chroma of strongly-compressed colors is better left to a downstream grading module, where it does not fight the tone map. (Also gone, from an even earlier design: the t strength multiplier that scaled the anchors up on the left half — it doubled the worst-case hue drift for no benefit once bleaching stopped being the point of that half.)
The purple-band failure mode (restored chroma landing on a drifted hue) is now closed by construction: there is no restored chroma at all, so a partially-recovered hue can never carry extra saturation onto a wrong angle.
The mix must be chroma-weighted (bug found in visual testing, 2026-07: a blue gradient swept from −10 to +15 EV turned magenta at the default slider position, while both slider extremes were fine). The first implementation blended the two hue angles as unit vectors and the two chromas separately. But a pixel fully converged by the curve leaves it with (near-)zero chroma and therefore no meaningful hue — exactly achromatic pixels even get a placeholder hue pointing at the red axis from pipe_RGB_to_Ych. The unit-vector blend weighted that placeholder as much as the pixel's real original hue (blue + red placeholder → magenta), and the chroma half of the recovery then restored half of the original chroma onto the wrong hue — a saturated magenta out of nowhere. Endpoints never showed it: at β = 0 the garbage hue carries no chroma (invisible), at β = 1 it is ignored entirely. The fix blends the chromaticity vectors, i.e. each hue enters the mix scaled by its own chroma: meaningless hues carry zero weight by construction, near-antipodal hues mix through gray instead of through the perpendicular hue, and the aligned-hue behavior (and both endpoints) are numerically unchanged. Validated in the harness: bright blue at +6…+15 EV keeps hue 235° through the mix instead of drifting to 256°.
And hue must recover before chroma (second half of the same bug, 2026-07: a fainter purple cast remained at the slider center after the vector-mix fix, still absent at both extremes). The residual mechanism is not a degenerate value but a property of any blend that couples hue and chroma recovery: the visible error is hue-drift × chroma, and the two are anti-correlated along the slider — at the character end the drift is maximal but the color is bleached away (pale, reads as the look); at the fidelity end the chroma is full but the drift is zero. Their product therefore peaks mid-slider. Measured on a true sRGB blue: the per-channel skew reaches +29.6° toward violet around +4…+6 EV while 34–84% of the chroma survives, and the coupled mix at the center left a +8…+11° violet cast on 0.27–0.37 chroma — a visible purple band. The fix split the two weights so they were never both partial-and-rising on a drifting color. (This whole class of bug was later made moot — §"The single runtime axis" — when chroma recovery was removed from the slider entirely: with no restored chroma at all, a partially-recovered hue can never carry extra saturation onto a wrong angle.) Diffuse colors are immune throughout regardless.
And the bracket must self-recover diffuse chroma (third finding, 2026-07: at −100% everything washed out, midtones included — olive skin tones bleached until they read as Caucasian, which is a racial-bias defect, not a style; see the limitations section). Root cause: the exact-inverse outset only returns what the curve did not converge, and with the 10%-latitude sigmoid the curve converges everywhere — the transparency theorem that justified the exact inverse had quietly become vacuous. The fix moves chroma fidelity off the slider and into the bracket: the outset is the inverse of a κ-scaled inset (κ = 1.51, same rotations), i.e. it over-expands, and the mandatory output≤input chroma clamp trims the excess to exactly 1.0 per pixel. The fitting questions this raised, with their measured answers (--fit-outset in the anchor script):
Status of the above. The κ scalar and the specific inset/outset rotation values in this subsection were the single-config precursor to the shipped variant ladder — one bracket fitted for one look. The production design instead fits one anchor — extra bleach — and bisects the interior against the settled bottom anchor, no bleach, which tools/fit_agx_ladder.py:10 states is not re-fit (--min-bleach --ab-pull 200) (see "The five variants" and "Fitting methodology and discarded approaches"); each variant now carries its own per-primary over-expanding outset. The findings carried over unchanged and are the durable lesson: the over-expanding outset plus the output≤input chroma clamp is what self-recovers diffuse chroma portably across dynamic ranges (the fitted target is an inequality — "reach the clamp" — and the clamp is the tone-adaptive, per-pixel stage), and a primary's rotation couples into every hue (the "whack-a-mole" that forces the fit to weigh skin, sunsets and blue-LED purple against one another). The script modes named above (--fit-outset, --minimax, --fit-priority) are retired, kept in the source only as history.
Is this "an Ych tone-mapping in disguise"? In the diffuse range the bracket is now deliberately near-neutral — which is the requirement, not a contradiction: grading happens before the tone mapper, so the tone mapper should touch valid colors as little as possible. What the RGB bracket still does that Ych operations cannot: it generates the roll-off into bleach as a smooth tristimulus process (dye bleaching is a tristimulus phenomenon, and perceptual-space chroma manipulation is exactly what produced the yellow-leaves/blue-sky fringe artifacts documented for the color equalizer — light mixes in RGB, not in Ych). The Ych machinery downstream is the governor: it measures, clamps and anchors, but never generates. Generator in RGB, governor in Ych — that division is the design.
v8 AgX ships as five colorscience variants — no bleach, low bleach, medium bleach, high bleach, extra bleach (enum V6…V10; the module $DEFAULT is medium bleach / V8, filmicrgb.c:265, whose $DESCRIPTION at :179 is "v8 (AgX, medium bleach)" — it was low bleach in an earlier draft of this document and in an earlier default). They share the entire pixel path and differ only by the bracket constants in filmic_agx_prepare_bracket. All five are points on a single axis that trades saturation for fidelity, from no bleach (maximum chroma retention, largest hue drift) to extra bleach (maximum hue and skin fidelity, most muted). The asymmetry that orders the axis: hue drift is recoverable downstream (the Ych "color preservation" governor restores it exactly) while lost chroma is not — so no bleach protects the irrecoverable quantity and spends the recoverable one, and extra bleach does the reverse.
The bracket is a per-primary inset followed by a per-primary, over-expanding outset (ratios > 1); all twelve bracket parameters are fitted. Per-primary insets were the lever the optimizer abused under the old scalar-average objective — it rails green and wrecks an unseen blue — so the earlier design held the inset uniform. They became safe once the objective pins every hue directly (per-hue apparent brightness, chroma and hue drift over the whole circle, plus a hard gamut guard), which leaves no unseen colour to game. The outset is sized so priority colours reach the output-chroma ≤ input-chroma clamp of the pixel path and are trimmed to exactly 1.0 per pixel — which is what makes one fixed bracket portable across dynamic ranges (verified 6.5–16 EV).
Both are computed in filmic's own working space, not a standard colour-difference formula, because the colours a tone mapper moves are far brighter and more saturated than the reflective samples CIE \(\Delta E\) was regressed on.
**Chroma-normalized Yrg \(\Delta E\) — "how far did this colour move".** Work in the Kirk/Filmlight Yrg chromaticity plane. Express the output relative to its input: chroma ratio \(c_r = \min(c_\text{out}/c_\text{in},\,1)\) and hue drift \(\Delta h\). Placing the input at \((1, 0)\) and the output at \((c_r\cos\Delta h,\; c_r\sin\Delta h)\), the distance between them is
\[\Delta E_\text{Yrg} = \sqrt{\left(c_r\cos\Delta h - 1\right)^2 + \left(c_r\sin\Delta h\right)^2}.\]
It folds chroma loss and hue drift into one number: \(\Delta E = 0\) for an unchanged colour, \(\approx 1\) for one bleached to grey ( \(c_r \to 0\)), up to \(2\) for a hue-flip at full chroma ( \(c_r = 1,\ \Delta h = \pi\)). Two properties make it the right tool here and CIE 1976/2000 the wrong one: it needs no absolute-chroma reference white (it is a relative move in a chromaticity plane, so it behaves on out-of-display-gamut brights), and it is chroma-weighted — a hue error on a near-grey colour contributes almost nothing ( \(c_r\sin\Delta h \to 0\) as chroma vanishes), matching perception, whereas \(\Delta E_{00}\)'s hue term does not vanish there. Subtracting the \((1,0)\) reference is essential: \(\sqrt{(c_r\cos\Delta h)^2+(c_r\sin\Delta h)^2}=c_r\) is merely the output's length, not a distance, and silently cancels the chroma term — an early version shipped exactly this bug.
Helmholtz–Kohlrausch apparent brightness — "how bright does this colour read". A saturated colour looks brighter than a grey of equal luminance; per-channel tone mapping changes that "extra glow" unevenly across hues, which is what makes an over-cooked red read self-luminous. We quantify it with the Nayatani (1997) VAC model. For a colour with CIELUV saturation \(s_{uv}\) and hue angle \(\theta\), the fractional brightness excess \(\Gamma - 1\) is
\[\Gamma - 1 = \bigl(0.0872\,K_{Br} - 0.1340\,q(\theta)\bigr)\,s_{uv},\]
\[q(\theta) = -0.01585 - 0.03017\cos\theta - 0.04556\cos 2\theta - 0.02667\cos 3\theta - 0.00295\cos 4\theta + 0.14592\sin\theta + 0.05084\sin 2\theta - 0.01944\sin 3\theta - 0.00776\sin 4\theta,\]
with $K_{Br} = 0.2717\,\dfrac{6.469 + 6.362\,L_a^{0.4495}}{6.469 + L_a^{0.4495}} \approx 1$ at the adapting luminance \(L_a = 63.66\ \text{cd/m}^2\). It is \(\approx 0\) for neutrals and yellow-greens and largest for saturated blue / red / magenta (measured at equal luminance: grey \(0.00\), green \(0.12\), red \(0.32\), blue \(0.43\)). A colour's apparent brightness is then \(Y\,\Gamma = Y\,(1 + (\Gamma-1))\), and H-K drift is the signed change \((\Gamma_\text{out}-1) - (\Gamma_\text{in}-1)\). Because \(\Gamma-1\) is a fractional boost it is luminance-independent, so targeting it constrains chroma+hue only. Keeping H-K drift near zero means the render preserves the scene's brightness balance between colours — no hue popping out or sinking relative to its neighbours.
tools/derive_filmic_agx_primaries.py --report, {avg / max} over the skin-tone database and the diffuse reflective/memory-colour hue circle (purity 0.3…0.9), each swept over tonal placements. Saturation drift is chroma loss ( \(1 - c_\text{out}/c_\text{in}\), post clamp); hue drift is the raw bracket drift before the Ych recovery slider mitigates it.
Skin tones
| variant | sat. drift avg/max | hue drift ° avg/max | \(\Delta E\) avg/max | H-K drift avg/max |
|---|---|---|---|---|
| no bleach | 0.0% / 0.0% | 10.5 / 15.4 | 0.18 / 0.27 | +0.030 / +0.081 |
| low bleach | 0.0% / 0.0% | 7.8 / 11.8 | 0.14 / 0.21 | +0.028 / +0.079 |
| medium bleach | 0.0% / 0.5% | 5.3 / 8.7 | 0.09 / 0.15 | +0.026 / +0.076 |
| high bleach | 0.1% / 3.9% | 2.8 / 5.8 | 0.05 / 0.10 | +0.023 / +0.071 |
| extra bleach | 1.0% / 7.1% | 1.1 / 3.4 | 0.02 / 0.08 | +0.021 / +0.064 |
Reflective colours
| variant | sat. drift avg/max | hue drift ° avg/max | \(\Delta E\) avg/max | H-K drift avg/max |
|---|---|---|---|---|
| no bleach | 5.0% / 58.9% | 5.0 / 23.1 | 0.12 / 0.61 | +0.031 / −0.260 |
| low bleach | 6.2% / 54.8% | 3.9 / 19.7 | 0.11 / 0.56 | +0.027 / −0.244 |
| medium bleach | 7.6% / 56.6% | 2.9 / 18.9 | 0.11 / 0.57 | +0.023 / −0.245 |
| high bleach | 8.9% / 58.9% | 2.1 / 18.3 | 0.11 / 0.60 | +0.020 / −0.248 |
| extra bleach | 10.1% / 62.1% | 1.7 / 17.4 | 0.12 / 0.65 | +0.016 / −0.255 |
Every column is monotone no→extra: hue drift and \(\Delta E\) fall, saturation drift rises. The high reflective max saturation drift (55–62%) is the intended bleach of near-clipping brights (flames, LEDs, speculars), the same order in all five. Reflective H-K drift turns negative at the max — the most saturated colours are slightly deflated, the opposite of the neon artifact. Skin hue drift is large in no bleach (10.5°) and tiny in extra (1.1°) by design: no bleach spends hue (recoverable) to protect skin chroma.
Per 12-hue reference circle (--diagnose), signed hue drift (°, pre-slider) and rendered output chroma — both monotone from no to extra, i.e. a stronger variant moves every hue the same way (one look at five strengths, not five looks):
| hue | hue drift no→extra (°) | rendered chroma no→extra |
|---|---|---|
| red | 5.5 → 3.8 → 2.3 → 0.7 → −0.8 | 0.163 → 0.158 → 0.154 → 0.148 → 0.143 |
| red-orange | 6.1 → 4.4 → 2.8 → 1.3 → −0.2 | 0.156 → 0.147 → 0.139 → 0.132 → 0.126 |
| orange | 4.5 → 3.5 → 2.6 → 1.7 → 0.7 | 0.212 → 0.199 → 0.187 → 0.175 → 0.165 |
| yellow-green | 1.2 → 0.9 → 0.6 → 0.3 → −0.1 | 0.277 → 0.263 → 0.251 → 0.239 → 0.226 |
| green | 3.2 → 2.3 → 1.5 → 0.7 → 0.0 | 0.159 → 0.153 → 0.148 → 0.143 → 0.137 |
| cyan | 7.8 → 5.4 → 3.1 → 0.7 → −1.5 | 0.126 → 0.121 → 0.116 → 0.111 → 0.106 |
| cyan-blue | 6.1 → 4.1 → 2.0 → −0.2 → −2.4 | 0.228 → 0.223 → 0.216 → 0.208 → 0.199 |
| blue | 1.5 → 1.4 → 1.2 → 1.0 → 0.8 | 0.246 → 0.242 → 0.237 → 0.230 → 0.223 |
| blue-magenta | −1.1 → −0.7 → −0.4 → −0.2 → −0.1 | 0.275 → 0.272 → 0.269 → 0.267 → 0.264 |
| magenta | 2.4 → 1.6 → 1.0 → 0.4 → −0.1 | 0.343 → 0.340 → 0.338 → 0.337 → 0.336 |
Two anchors are fitted directly against the priority set (skin database + reflective circle), each favouring a different quantity; the three interior variants are obtained by perceptual bisection, which is what guarantees a monotone ramp.
The apparent-brightness and chroma continuity constraints were the two findings that made the ladder perceptually even. Holding apparent brightness roughly constant across the axis makes bleaching read as pure desaturation at constant lightness, not as colours darkening or lighting up between variants; the uniform target is derived from data — the average of the H-K-neutral gray-equivalent floor ( \(\approx 0.336\)) and the scene-preserving ceiling ( \(\approx 0.379\)), i.e. \(\approx 0.357\) — not hand-tuned. Pinning chroma to the neighbour midpoint then guarantees the saturation itself steps evenly.
Regenerating. The whole ladder re-fits offline via the orchestrator, which runs the steps in dependency order and patches both SHIPPED_VARIANTS and the C case blocks:
Tunables live at the top of fit_agx_ladder.py (AB_STAB, AB_LEVEL, BLEACH_NUGDE) and in the --fit-bisect branch (W_AB, W_CH, W_HD). --diagnose prints the per-hue apparent-brightness, output-chroma and hue-drift ladders (each must be monotone) and is the acceptance test. Numeric constants are the source of truth in filmic_agx_prepare_bracket / SHIPPED_VARIANTS.
The production method is two directly-fitted anchors (no-bleach, extra-bleach) plus bisection of the interior, all driven by per-hue perceptual targets and orchestrated by tools/fit_agx_ladder.py (see "The five variants"). Several structural findings, and a trail of discarded objectives, lie behind that choice.
Structural findings (still load-bearing).
Why per-primary insets, and why the objective changed. The earlier objective was a scalar desaturation budget (--max-desat FRAC): minimize average hue drift at a stated average chroma loss. Against a scalar average, per-primary insets are dangerous — the optimizer rails one channel and wrecks an unseen colour — so that regime held the inset uniform and treated bleach depth as a knob rather than a fit target (bleach depth saturates with inset depth, so depth-based objectives just rail the insets, which is why the early ladder chose the insets rather than fitting them). The current objective pins every hue — per-hue apparent brightness, chroma and hue drift, plus the gamut guard and a chroma ceiling — which removes the "unseen colour" and makes the full 12-parameter per-primary fit both safe and necessary (there are now enough targets to justify the degrees of freedom).
Discarded fitting modes (kept in the script only as history, not live entry points). The derivation passed through, in order:
All were superseded by the current anchors + bisection ladder with per-hue targets. They remain in derive_filmic_agx_primaries.py as a record of what was tried and why it was dropped.
Maintenance. The anchors are only optimal for the curve they were fitted against. CURVE_DEFAULTS in the script must track the C $DEFAULTs; any change to the default curve requires re-running the whole ladder via python3.12 tools/fit_agx_ladder.py and a rebuild. Its STEPS table (fit_agx_ladder.py:40-49) has exactly four entries and that order is load-bearing: extra-bleach (--fit-extra-bleach) first, since it is the top anchor and everything else is bisected against it; then medium (--fit-bisect no-bleach extra-bleach), low (--fit-bisect no-bleach medium-bleach) and high (--fit-bisect medium-bleach extra-bleach). No bleach is not in the table — it is the settled bottom anchor and the script says so at :10. The script patches both sources. --diagnose is the acceptance test: the per-hue apparent-brightness, chroma and hue-drift ladders must each stay monotone. The sigmoid toe/shoulder exponents are derived separately by the default-curve harness (see "Deriving the default curve").
Question asked (2026-07): what if we trusted the matrices with hue entirely — no hue restoration at all — and let the slider recover only chroma? In other words: are the fitted rotations good enough to manage hue on their own? Measured answer, sweeping saturated colors across the exposure range:
Conclusion: shipping unanchored hue means accepting ~30° hue-category shifts in colorful shadows as part of the look. The coupled recovery (β restores chroma and hue together) offers the same character at the slider's left end while shrinking the worst case linearly as the slider moves right — ~16° at the default position.
Verdict: hue recovery is the production behaviour and chroma recovery is not user-controlled at all — this paragraph's "coupled chroma+hue recovery" overstates what shipped. agx_beta_hue (filmicrgb.c:387-390) is a hue-recovery mix and its own comment says "Chroma is NOT user-controlled: it follows the bracket's own outset recovery + clamp only, because mixing any original chroma back kinks highlight gradients"; filmicrgb.c:2556-2558 repeats it — the recovered value fights the bracket's smooth bleach roll-off at the min() clamp, "so it was removed". What was rejected here is what this study asked about: unanchored (hue-free) recovery, because ~30° hue-category shifts in colourful shadows are not an acceptable baseline. The temporary compile-time switch was deleted. (The rotation derivation this verdict refers to was --minimax, since superseded — the shipped anchors come from the per-hue anchors-plus-bisection ladder; see "Fitting methodology".)
The anchors were fitted against the default curve, but users reshape the curve on every image (dynamic range, latitude, contrast). How much does that mismatch matter, and should the matrices adapt to the user's actual curve? Two options were assessed:
Each of these requires bumping DT_MODULE_INTROSPECTION (new params members), which breaks the back-and-forth database compatibility contract — hence the bar is "users demonstrate a real limitation", not "would be nice".
The anchors are fitted against the default curve, which raised the obvious question: where does the default curve come from? Historically: taste. It is however a solvable problem, because a tone curve is secretly an answer to a physical question: "this patch of the scene had luminance X — what luminance should the display emit so that it __looks__ the same to the viewer?" The scene is bright and the viewer is adapted to daylight; the display is ~10× dimmer, sits in a dim room, and reflects some stray light. Those are known, stateable conditions, and CIECAM16 exists precisely to predict perceived lightness under given conditions. So tools/derive_filmic_default_curve.py computes, for every exposure level, the display luminance whose perceived lightness matches the scene's (scene: diffuse white ~1000 cd/m², average surround → display: 100 cd/m², dim surround, 0.1% veiling flare — see the flare finding below), then finds the filmic curve parameters that best reproduce that mapping. Two weights steer the fit: exposures where photographs actually hold detail count more, and a JND term forbids the curve from introducing perceptual transitions sharper than the ideal mapping itself has anywhere — that is what keeps the roll-offs from turning into visible cliffs. The Python curve model replicates the C geometry exactly, including the internal renormalizations of the contrast slider, so the fitted values are directly the module's user parameters.
A recurring measurement below is the shadow slope: how many stops the display output changes per stop of scene exposure, at a given point of the range. Slope 1 means shadow gradations are fully preserved; slope near 0 means whole stops of scene detail collapse into nothing on screen — that is what "crushed blacks" measures.
Results (2026-07), stable across scene 1000→5000 cd/m², display 100→200 cd/m² and JND weights 1–3: