![]() |
Ansel 0.0
A darktable fork - bloat + design vision
|
Verified against 42eca0e8fe on 2026-09-29.
Three failure families, each found by measurement after plausible-but-wrong theories died — and the bench that judges them.
Each finding below is dated with the commit that established it. A finding is only as good as its hash: before acting on one older than the code you are changing, re-measure it — and re-date it here when you do. Where an earlier version of a claim was wrong, that is recorded rather than quietly corrected: how a claim was wrong is usually the more useful thing to know.
Established 2026-11-09 on top of 5c15b7c508. 282 Bayer and 11 X-Trans local raws read with LibRaw (rawpy 0.27, top-end counts per CFA site), and a probe in process() printing the same counts, and autoset() itself, on the module's real input in ansel-cli (rawspeed white and black points, white balance applied) for 305 raws: 282 Bayer, 16 X-Trans, 7 linear DNG.
The detection threshold a mode tests is factor · clip · processed_maximum[c] (factor 0.995 for harmonic and guided laplacians, 0.987 for colour inpainting; clip and LCh test the scalar clip · min(processed_maximum)). Autoset counts, per site of the colour filter period (2×2 Bayer, 6×6 X-Trans, the three channels of RGB input), the maximum and the photosites exactly on it. A site with at least DT_HL_MIN_CLIPPED_PIXELS (25) there is saturated, and the threshold goes DT_HL_AUTOSET_MARGIN (0.15 %) under the lowest saturated site's maximum. Each level becomes a clip through the active mode's own threshold at clip = 1 (_hl_count_thresholds()), so the value depends on the mode: switching mode afterwards moves the threshold by the ratio of the two factors. With no saturated site, the threshold only has to stay above the brightest photosite, which the default 1.0 does unless the data runs above the white point: clip = max(1, brightest).
Why each part:
On the 305 raws in harmonic mode autoset gives 0.9945 to 1.4356: below 1 only where a plateau is below the white point (the D3200 green site, the X-T5 and X-H1 blue sites), above 1 where rawspeed's white point is under the plateau (Canon bodies, the Z 6 at 1.063), and exactly 1 on the 143 frames with no plateau and nothing above the white point.
Not measured: DNGs whose embedded GainMap rawprepare applies spread a plateau over the gain, so no site piles up and autoset falls back to the brightest photosite.
Established 2026-10-24 against 2fadf8a366. GTX 1060 6 GB (driver 580.178.04), i7-3770K (8 threads), thumbnail pipes of a 51-image collection rendered from the raw, the desktop on the same card.
tiling_callback() gives harmonic the guided-laplacian budget, factor_cl = 2 + 3·4 + 6·4/DS_FACTOR = 20 times the single-channel input. Its comment said harmonic "allocates region buffers well under this envelope". That was wrong. On a 5208×3476 input (72.4 MB as one float plane, so 1.45 GB declared), Ansel's own vRAM accounting (-d opencl -d memory) went from 932 MB at the module's entry to 4.5–4.97 GB through the device middle: the module held at least 4.0 GB, about 2.8× what it declares.
The admission check (dt_opencl_image_fits_device_reason()) compares the declaration with used_available − memory_in_use, used_available being the device's memory minus its forced_headroom. OpenCL publishes nothing about what other processes hold on a discrete device, so the headroom is the only allowance for them. Here the desktop held 978 MiB before Ansel started, and the driver's context about 140 MiB more that Ansel does not count. nvidia-smi, sampled every 100 ms, read 5856 of 6063 usable MiB while the middle ran. The next 265 MB image did not fit, and the driver said so on its first use: copy_buffer_to_image returned -4 (CL_MEM_OBJECT_ALLOCATION_FAILURE), then "harmonic GPU middle failed (-4), using the host middle".
The host middle runs the reconstruction on the CPU at full sensor resolution: 43.8 to 74.2 s for one thumbnail, against 0.005 to 10 s on the device, for one or two images of the collection per run. It runs inside the pipe, which keeps the device and dt_pipeline_threadsafe_mutex() throughout, so every other thumbnail waits.
Raising the device's headroom does not prevent it. With forced_headroom at 900 and at 1500 MiB, the same image failed at the same copy (host middle 68.9 s and 72.7 s), and vRAM peaked at 5920 and 5947 MiB. The headroom lowers the budget the entry check reads; nothing checks the middle's allocations against it once the module is admitted.
Established 2026-10-25 against 2fadf8a366, with temporary prints around each region of _harmonic_reconstruct_cl() and _harmonic_reconstruct_regions(), and in the merge of _segment_clipped_regions(); same machine, collection and forced_headroom 900 MiB.
The working set follows one region's padded window, not the frame. _segment_clipped_regions() merges every pair of regions whose padded read boxes intersect, and rebuilds each group as the union of its members' bboxes, padded by the group's largest pad. A chain of small holes whose pads touch thus becomes one window over most of the frame:
| image (5208×3476) | regions after merge | largest window | members | clipped px in its bbox | largest member bbox |
|---|---|---|---|---|---|
| 18477 | 555 (of 2216) | 4749×3476, 16.5 Mpx (91 %) | 705 | 1.10 Mpx | 1.55 Mpx |
| 18977 | 403 (of 1571) | 4694×3469, 16.3 Mpx (90 %) | 617 | 1.00 Mpx | 1.48 Mpx |
Open: the declaration does not describe the device middle, and the merged window can be about 15 times the clipped area it reconstructs. Raising factor_cl to the measured working set would send the module to the CPU from the start on this card, at about the same cost. The region loop instead checks each big window against what the device has left and sends only an oversized one to the host (see "a window that does not fit the device takes the CPU offload" below). Merging less would shrink the window, but the merge exists to avoid seams between neighbouring fills, so it changes the result.
Found e4195dec51, 2026-08-05.
The "harmonic reconstruction leaves highlights magenta" complaint (MAC25640.RAF) survived three plausible-but-wrong theories (X-Trans phase mismatch, demosaic bleed, coefficient-fit slope error — each killed by measurement, per the retouch note's warning about reasoning from source alone). The actual mechanism, found by dumping the module's raw output and comparing per-channel means over clipped photosites against the per-channel clip thresholds:
Diagnostics that settle this class of bug in one pass: dump the module's raw output (ovoid) and bucket per-CFA-channel means by "own channel clipped" vs the per-channel clips[] — if the output means sit at the clip levels, the floors are authoring the color, not the solver.
Found c5c34c3ecb, 2026-08-20.
Third failure family, on a blown sky meeting a dark ridge (DSC_1267.NEF): a magenta rim hugging the mountain's edge. The cgrad stage's survivor-anchored reprojection deliberately skipped 1-clip pixels as "measured-correct where the fit spoke" — but the fit does not always speak. Where the sky dims toward an occluder it drags the guides, the colour-line prediction lands below the pixel's own saturation level, and fmaxf(pred, clip0) pins the channel AT the floor — the minimum compatible value, carrying the floor's chroma (i.e. the WB coefficients: magenta) instead of the material's. Measured: 96.5% of the 1-clip-G pixels 4–6 px from the rock, and 90.4% at 8–12 px, exit the whole chain still at their floor (median lift 1.000), against 27.9% far from it.
Such a pixel holds exactly what a partial multi-clip pixel holds — two measured channels plus a surround chromaticity — so it takes the same survivor-anchored reprojection. Ring profile (R+B)/2G by distance from the ridge: 1.032 / 1.046 / 1.030 → 1.004 / 1.005 / 1.007.
Two traps, both paid for in a full bench round each:
Never a hard threshold. The first version admitted pixels via est <= 1.03 * clip0. Every metric went flat and the render grew a NEW hard-edged pink region — the test printing its own contour along the boundary between mostly-floored and mostly-lifted pixels. It is now an inverted smoothstep on the lift (CF_AUTHORED_RAMP). The numbers alone would have shipped the bad version; only the picture caught it.
Anything that imports surround chroma MUST be gated on _hl_floor_gate(clips). Ungated, this regressed the whole unit-WB bench — pk1synth +140% RMSE, balls +26%, occluded +18% — because at unit WB every channel saturates at the same level, so a floored channel's chroma is NEUTRAL ≈ truth and reprojecting it replaces a correct value with a guess. This is the SECOND time this exact omission cost a bench round (the joint floor's first attempt, documented above, died the same way). Gated, the six unit-WB cases return bit-identical to baseline (A = 1.145 vs a ramp starting at 1.25 → gate exactly 0) while real raws (A ≈ 2–2.6) keep the full fix. Note the same function already consulted floor_gate to decide which pixels may vote — consulting it for the voters and not for the pixels being acted on is the shape of the mistake.
Found e4195dec51, 2026-08-05.
Second failure family, found on a blown sunrise laced with branches (Brandon Woods RW2): blotchy pink/lavender patches and branch-shaped chroma ghosting inside the reconstruction. Root cause chain, each link established by measurement (fit-plane dumps, per-clip-count chroma buckets against a bright-sky-only reference — the all-valid mean is contaminated by dark foreground and is the wrong reference):
Found against e83ba5865d, 2026-09-26, measured on an Apple M1 (macOS OpenCL 1.2).
double had three uses in this module's kernels, and only one is double precision: the sparse Cholesky factor and solves of highlights_sparse.cl (sparse_chol_*) and the second-member vector they consume (hl_pde_*, hl_aniso_*). The nine reduction kernels — the four stage-2 finalizers of highlights_harmonic.cl and the CG dot products of highlights_sparse.cl — accumulated in double and narrowed every result to float on the way out, so the double only ever bought the accuracy of the SUMMATION. They now sum in compensated single precision (data/kernels/compensated.h: a float2 of value + running error, Knuth two-sum, no multiply so -cl-mad-enable cannot contract it) and sit outside any fp64 guard: available on every device, the host twins agreeing to a float ulp rather than bit for bit. A new kernel header must be listed in BOTH clincludes[] (common/opencl.c, the kernel-cache checksum) and DT_OPENCL_EXTRA (data/kernels/CMakeLists.txt, the install); an omission in the first keeps serving yesterday's binaries, in the second the kernel does not build at all in a package.
Measured on Apple M1 (macOS OpenCL 1.2, no cl_khr_fp64 in CL_DEVICE_EXTENSIONS, CL_DEVICE_DOUBLE_FP_CONFIG = 0): the runtime DEFINES the cl_khr_fp64 preprocessor macro anyway. A #if defined(cl_khr_fp64) block therefore compiles, clBuildProgram succeeds, and every kernel that loads, stores or computes a double fails at clCreateKernel with -48 (CL_INVALID_KERNEL_NAME) — per kernel, not per program — the runtime logging UNSUPPORTED (log once): createKernel: newComputePipelineState failed once, for the first. A double that appears only in a signature is fine. The guard thus does not do on Apple what its comment said it does elsewhere, and the tell in a -d opencl log is a kernel INSIDE the guard that does not fail: hl_cg_beta_step named no double and was the one survivor of its block. When fp64 has to be selected, select it host-side from CL_DEVICE_DOUBLE_FP_CONFIG and pass a define the way -DNVIDIA_SM_20=1 is passed (opencl.c, into options AND options_md5) — never from the macro. ansel-cli takes -d through --core (ansel-cli in out --core -d opencl -d perf).
Found against e83ba5865d, 2026-09-26; the per-operation figures were measured on an Apple M1.
That is now how the eight solver kernels work. data/kernels/hl_real.h defines hl_real_t and hl_add/sub/mul/div/sqrt: native double when the host passed -DDT_DEVICE_FP64=1 (cl->dev[dev].fp64, from CL_DEVICE_DOUBLE_FP_CONFIG != 0, dt_opencl_device_has_fp64()), a float2 (hi, lo) double-float otherwise — Knuth two-sum, fma two-product, Newton division and square root, measured on the M1 at 5e-15..1.2e-14 relative per operation, i.e. ~46 bits. Both are 8 bytes (DT_HL_REAL_BYTES), so no device buffer changes size; a host double vector crosses through _sp_cl_upload_real() / _sp_cl_read_real() (math/sparse_cholesky_cl.h), which split and rejoin only where the device lacks fp64. A device with fp64 therefore runs the exact code it always ran. The precision budget that makes df32 acceptable is thin: the biharmonic systems are conditioned like h⁻⁴, about 3e8 at DT_HL_SPARSE_MAX (16384 unknowns), so ~45 bits are needed and df32 has ~46-47 — raising that cap without redoing the arithmetic silently loses digits on fp64-less devices only. HL_SPCL_TEST=1 is the parity check (GPU solver vs the CPU double twin on a 13-point biharmonic disc); it also runs from the CPU process_harmonic() when a device exists, because a run whose memory budget sends the module to the CPU never enters process_harmonic_cl() (an 8 GB Apple M1 when its free RAM is short, see the next section). Do not write a new .cl reduction in double for accuracy: compensated.h already covers that case in fp32.
Both headers rely on the compiler not reassociating: under -cl-unsafe-math-optimizations or -cl-fast-relaxed-math, clang folds the error term of a two-sum to 0.0 (measured with clang 23, see doc/opencl-math-accuracy.md, which also covers the migration of the per-device building key away from the pre-2026-08-18 default that carried them). hl_real.h takes its two-sum from compensated.h, so there is one copy. Under DT_DEVICE_FP64 it enables cl_khr_fp64, or cl_amd_fp64 where only that one is defined, as the old guard did — the host has then read real fp64 off the device, so the macros can be trusted. CI test-compiles highlights_sparse.cl a second time with -DDT_DEVICE_FP64=1 (data/kernels/CMakeLists.txt), since the native half is otherwise compiled only by users' drivers.
Measured 2026-09-26 to 2026-10-02 on six Apple Silicon Macs (8 to 36 GB), base e83ba5865d; the device field below added 2026-10-28 against 8e628de1c2; its vendor test measured on an M1 the same day, and on a tester's M4 Pro with clinfo (discussion #1466, comment 19248411).
dt_opencl_get_device_available() (common/opencl.c) bounds a host-unified device's working set by max_mem_alloc / 2, a proxy for Intel NEO's per-context aperture calibrated on a P630. Apple's OpenCL on Apple Silicon reports CL_DEVICE_MAX_MEM_ALLOC_SIZE as 3/16 of its global memory: 1024 of 5461 MB (8 GB M1), 2048 of 10923 (16 GB), 2557 of 13640 (18 GB), 3410 of 18186 (24 GB), 5391 of 28754 (36 GB). The clamp therefore made the budget about a sixteenth of the RAM: 512 MiB on the 8 GB M1, 1.7 GiB on a 24 GB M4 Pro (vRAM has 1704 MiB left in a master log, where highlights, demosaic and denoise went to the CPU). Do not assume max alloc is a fixed figure on Apple: it scales with the RAM.
The clamp is skipped where dt_opencl_device_t.aperture_clamp is unset, which dt_opencl_device_init() decides once: platform name AND device vendor both "Apple" (measured on an M1 and an M4 Pro: platform Apple, vendor Apple, vendor id 0x1027f00 on both; M2, M3 and M5 not checked yet — the DEVICE VENDOR line of the -d opencl log shows it). The platform alone would also take in Intel Macs, which publish the same "Apple" platform for GPUs whose vendor is "Intel Inc." or "AMD", and where nothing was measured. It is deliberately not keyed on the crash-attribution table (_gpu_runtimes[]): that table's module column must name a runtime's own object, and on macOS the only candidate, OpenCL.framework, is the loader every OpenCL call goes through. The same reasoning keeps OpenCL off by default for any build that can run on Intel (data/CMakeLists.txt).
Without the clamp the budget is the declared memory less the headroom, bounded by the RAM actually free. On the 8 GB M1 it read 1.2 to 2.1 GiB, and the harmonic reconstruction of a 24 Mpx raw (1734 MiB asked) ran on the GPU in most exports and on the CPU when free RAM was short; profiled denoise (3.5 to 3.8 GiB) stayed on the CPU. On the five 16 to 36 GB machines the whole pipeline ran on the GPU in every export. The self-tests are still called from the CPU entry point as well, for the runs that do not reach process_harmonic_cl().
Found e4195dec51, 2026-08-05.
Established 2026-10-25 against 2fadf8a366. GTX 1060 6 GB, driver 580.178.04.
hl_dome_blend reads refine[0] (the refine gate) on its first line, whatever the gate. _selfdome_stage_cl() (iop/highlights/core.c) allocated refine_dev only inside its floor_gate > 1e-6 block, so with near-equal per-channel clips (asymmetry under 1.25, _hl_floor_gate()) the kernel got a NULL buffer. Only regions whose padded window exceeds DT_HL_CL_CPU_REGION_PX take this device path, which is why only one region in hundreds hit it.
On NVIDIA the read is an MMU fault, not an error code: the kernel log records NVRM: Xid 31 … MMU Fault … faulted @ 0x0_00000000 … ACCESS_TYPE_READ at the second of the failure, the queue returns -5 (CL_OUT_OF_RESOURCES), and the context stays dead: every later kernel on the device fails with -5 and every module falls back to the CPU for the rest of the session (55 module runs on the GPU before it in one session, none of 337 after). An asynchronous queue does not say which kernel faulted; clFinish() after each enqueue named hl_dome_blend, and a check in dt_opencl_set_kernel_arg() found its argument 13 NULL.
The buffer is now allocated at gate 0 too and zeroed by hl_set_scalar, which takes the kernel's gate-0 path; the same defect aborted the process on radeonsi under rusticl. With it allocated and zeroed at gate 0, measured on the same 51-image session from an empty cache: no Xid, the 16.5 Mpx window of image 18477 reconstructed on the device in 23.1 s (70 s for the same kind of window on the CPU), all five harmonic images kept the device middle, and 376 module runs stayed on the GPU. nvidia-smi still peaked at 5960 of 6063 MiB.
When a pipe falls back to the CPU on -5 with no allocation failure in sight, look for an Xid in journalctl -k before suspecting memory.
Established 2026-10-25 against 2fadf8a366, with refine_dev allocated and zeroed at gate 0 (previous section).
A region on the device path holds about 64 floats per pixel of its padded window: 256.4 to 257.2 bytes per pixel on windows of 2.8, 16.3 and 16.5 Mpx (-d memory, peak over the region minus the accounting at its start), linear in the window. Nothing checks those allocations against the headroom once the module is admitted, so the region loop of _harmonic_reconstruct_cl() now asks dt_opencl_image_fits_device() for DT_HL_CL_REGION_FLOATS_PER_PX (65) floats per window pixel before a big region, and sends a window that does not fit to _region_cpu_offload_cl(), which needs 9 floats per pixel on the device. Only that window goes to the host; the other regions and the rest of the pipe stay on the device.
Measured on the same session from an empty cache. With forced_headroom at 2500 MiB, both 16 Mpx windows were sent to the CPU (harmonic region window 4749x3476 does not fit the device), the module took 76.1 s on image 18477, nvidia-smi peaked at 2398 MiB, and nothing failed. With 900 MiB both fit, stayed on the device (31.2 s on 18477, peak 5909 MiB), and 376 module runs were on the GPU.