@photivra/engine 2.0.0 → 2.1.0

package/dist/facade/simulate-capture.js

@@ -22,6 +22,8 @@
  * - optics: the environment `lensFieldMapping` (projection, radial / Brown–Conrady distortion), radial
  *   illumination vignetting as field throughput and a caller sampled lens PSF;
  * - motion: constant camera angular velocity and the electronic rolling-shutter exposure schedule.
+ * The 2.1 options are opt-in in the same way: `lens.diffraction`, `output.demosaic: "ahd"` and
+ * `sensor.antiAliasing` (a birefringent point-splitting low-pass filter in the sensor optical stack).
  * @see docs/QUICK_START.md
  */
 import { InvalidConfigurationError } from "../core/configuration-error.js";
@@ -47,7 +49,10 @@ import { createNativeRawDevelopmentTask } from "../capture/native-raw-developmen
 import { parseSdrRenderingProfile } from "../output/sdr-rendering.js";
 import { createPrintJpegTask } from "../output/print-jpeg.js";
 import { checkNativeRawIntegrity, prepareNativeRawDevelopment } from "../capture/native-raw-development.js";
-import { createRawPixelDeveloper } from "../capture/raw-development-kernel.js";
+import { createRawPixelDeveloper, normalizedRawSite, rawSiteSaturated } from "../capture/raw-development-kernel.js";
+import { createAhdDemosaicTask } from "../processing/demosaic.js";
+import { renderSdrRunInto } from "../output/native-capture-sdr.js";
+import { prepareSdrPixelTone } from "../output/sdr-rendering.js";
 import { BUILT_IN_BAYER_DEMOSAIC_MODEL_VERSION as BUILT_IN_DEMOSAIC_VERSION, createBuiltInBayerDemosaicProfiles } from "../sensor/raw-reconstruction.js";
 import { transformOrientedRasterPointToNative } from "../output/capture-geometry.js";
 import { resolveCaptureColorModel } from "../color/capture-color.js";
@@ -57,6 +62,10 @@ import { parseLensProjectionModel } from "../camera/lens-projection.js";
 import { prepareEnvironmentLensFieldMapping } from "../optics/sensor-environment-query.js";
 import { createRollingShutterCaptureExposureSchedule, resolveElectronicRollingShutterExposureSchedule } from "../sensor/readout-exposure-linkage.js";
 import { calculateCaptureExposureWindows } from "../sensor/exposure-window.js";
+import { calculateSensorSpectralQuadrature } from "../sensor/spectral-quadrature.js";
+import { createDiffractionLimitedPsfProfile } from "../optics/diffraction-psf-profile.js";
+import { createDiffractedPlanarProvider } from "./diffraction-provider.js";
+import { resolveAntiAliasingSpatialKernel } from "../sensor/optical-stack.js";
 import { multiplyMatrices } from "../color/colorimetry-math.js";
 import { prepareRgbGamutMapping } from "../color/gamut-mapping.js";
 import { serializeNativeRawDng } from "../capture/native-raw-dng.js";
@@ -65,6 +74,14 @@ import { resolveChartScene, CHART_SCENE_PRESETS } from "./chart-scenes.js";
 import { resolveCaptureIlluminant, calculateIlluminantIrradianceScale, buildPlanarSceneRadianceProvider, requireCallerScene, FACADE_SPECTRAL_RANGE_NANOMETERS, PHOTOPIC_MAXIMUM_LUMINOUS_EFFICACY_LM_PER_W } from "./scene-radiance.js";
 /** Version of how the facade builds requests. It changes whenever the same input would build a different request. */
 export const SIMULATE_CAPTURE_FACADE_VERSION = "1.0.0";
+/**
+ * Options reported in `diagnostics.options` (2.1), in this order, when they ran: the ones that change how much work
+ * a capture does. `motion.rotation` is a non-zero angular velocity; `sensor.temporalSampleCount` a count above 1.
+ */
+export const SIMULATE_CAPTURE_COST_OPTIONS = Object.freeze(["lens.pupilSampling", "lens.projection", "lens.distortion", "lens.vignetting", "lens.psf",
+    "lens.diffraction", "sensor.antiAliasing", "sensor.temporalSampleCount", "motion.rotation", "motion.shutter.rolling", "output.borderHandling.mirror",
+    "output.whiteBalance.auto", "output.demosaic.ahd", "output.highlightMode.reconstruct", "output.colorEncoding.wide-gamut", "output.gamutMapping.perceptual",
+    "output.format.jpeg", "output.format.png", "output.format.dng"]);
 const FACADE_EVIDENCE = Object.freeze([Object.freeze({ sourceOrigin: "photivra",
         sourceReference: "photivra:simulate-capture-facade", reuseStatus: "photivra-owned" })]);
 const DEFAULTS = Object.freeze({ camera: "professional", fNumber: 8, shutterSeconds: 1 / 125, iso: 100, compensationStops: 0,
@@ -90,11 +107,66 @@ export const SIMULATE_CAPTURE_DEFAULT_ILLUMINANCE_LUX = Math.PI * sosReferenceLu
     GREY_CARD_REFLECTANCE;
 /** Demosaic border, native sites per side. */
 const MARGIN = 1;
+/**
+ * AHD border, native sites per side: an AHD output pixel depends on sites up to 5 away (directional green ±2,
+ * colour differences ±1 of it, the homogeneity's 4-neighbours and its 3 × 3 sum), so a 5-site rendered margin keeps
+ * every output pixel off the plane's mirrored edge.
+ */
+const AHD_MARGIN = 5;
+/** Sites whose values enter an AHD output pixel (interpolation reach), for the saturated-pixel count. */
+const AHD_VALUE_REACH = 3;
+/** Anti-aliasing filter limits: split points, and the largest offset in sites (bounds the scene work and the convolution margin). */
+const AA_MAXIMUM_COMPONENTS = 16;
+const AA_MAXIMUM_OFFSET_SITES = 4;
+/** Default birefringent separation in sites: the two-spot MTF |cos(π·f·d)| then has its first zero at Nyquist, f = 1/(2·pitch). */
+const AA_DEFAULT_SEPARATION_SITES = 1;
+/** Parses `sensor.antiAliasing` into engine point-splitting components (offsets in µm, +x right, +y down). */
+function parseAntiAliasing(value, pitch) {
+    requireInputObject(value, "sensor.antiAliasing");
+    const kind = value.kind;
+    const separation = (record) => {
+        if (record.separationSites === undefined)
+            return AA_DEFAULT_SEPARATION_SITES;
+        const d = positive(record.separationSites, "sensor.antiAliasing.separationSites");
+        if (d > AA_MAXIMUM_OFFSET_SITES)
+            fail("sensor.antiAliasing.separationSites must be greater than 0 and at most " + AA_MAXIMUM_OFFSET_SITES + ".");
+        return d;
+    };
+    if (kind === "four-spot") {
+        const record = allowKeys(value, "sensor.antiAliasing", ["kind", "separationSites"]), d = separation(record), h = d * pitch / 2;
+        return { kind, separationSites: d, components: [[-h, -h], [h, -h], [-h, h], [h, h]].map(([x, y]) => ({ offsetMicrometers: { x: x, y: y }, normalizedWeight: 0.25 })) };
+    }
+    if (kind === "two-spot") {
+        const record = allowKeys(value, "sensor.antiAliasing", ["kind", "axis", "separationSites"]), d = separation(record), h = d * pitch / 2;
+        if (record.axis !== "horizontal" && record.axis !== "vertical")
+            fail("sensor.antiAliasing.axis must be horizontal or vertical.");
+        const axis = record.axis;
+        return { kind, axis, separationSites: d, components: [-h, h].map((o) => ({ offsetMicrometers: axis === "horizontal" ? { x: o, y: 0 } : { x: 0, y: o }, normalizedWeight: 0.5 })) };
+    }
+    if (kind === "point-splitting") {
+        const record = allowKeys(value, "sensor.antiAliasing", ["kind", "components"]);
+        if (!Array.isArray(record.components) || record.components.length === 0 || record.components.length > AA_MAXIMUM_COMPONENTS) {
+            fail("sensor.antiAliasing.components must be an array of 1 to " + AA_MAXIMUM_COMPONENTS + " components.");
+        }
+        // The engine's optical-stack parser checks shape, finiteness, positive weights and the unit sum (1e-12).
+        const kernel = resolveAntiAliasingSpatialKernel({ schemaVersion: "0.1.0", profileId: "facade-aa-check", evidence: FACADE_EVIDENCE,
+            effectiveAntiAliasingSpatialResponse: { kind: "normalized-point-splitting-kernel", evidence: FACADE_EVIDENCE, coordinateSystem: "native-sensor-physical",
+                scope: "field-wavelength-polarization-invariant-approximation", components: record.components } });
+        for (const c of kernel.components)
+            if (Math.max(Math.abs(c.offsetMicrometers.x), Math.abs(c.offsetMicrometers.y)) > AA_MAXIMUM_OFFSET_SITES * pitch) {
+                fail("sensor.antiAliasing.components offsets must lie within " + AA_MAXIMUM_OFFSET_SITES + " sites (" + AA_MAXIMUM_OFFSET_SITES * pitch + " µm) of the site centre.");
+            }
+        return { kind, components: kernel.components.map((c) => ({ offsetMicrometers: { ...c.offsetMicrometers }, normalizedWeight: c.normalizedWeight })) };
+    }
+    return fail("sensor.antiAliasing.kind must be four-spot, two-spot or point-splitting.");
+}
+/** Third dark ring of the Airy pattern in units of λ·N_w (j₁,₃/π, j₁,₃ = 10.1734681351): the default diffraction kernel reach. */
+const AIRY_THIRD_ZERO_PER_LAMBDA_N = 10.173468135062722 / Math.PI;
 /** Default temporal midpoints when the camera rotates (2.0 motion option). */
 const ROTATING_TEMPORAL_SAMPLE_COUNT = 8;
 const IDS = Object.freeze({ frame: "facade-frame", mode: "native-still", cfa: "photivra-generic-bayer", binding: "facade-native-cfa",
     sceneState: "facade-scene-state", scene: "facade-scene", provider: "facade-provider", lights: "facade-lights", materials: "facade-materials",
-    capture: "facade-capture", spectral: "facade-colorimetric-eqe", sampling: "facade-sampling", stack: "facade-no-aa",
+    capture: "facade-capture", spectral: "facade-colorimetric-eqe", sampling: "facade-sampling", stack: "facade-no-aa", stackAa: "facade-aa",
     stationarity: "facade-stationarity", operatingState: "facade-operating-state", dark: "facade-dark", completeness: "facade-completeness",
     chargeSampling: "facade-charge-sampling", capacity: "facade-capacity" });
 const CHANNELS = ["red", "green", "blue"];
@@ -112,6 +184,8 @@ const XYZ_TO_CAMERA = [[EQE_SCALE.red / EQE_SCALE.green, 0, 0], [0, 1, 0], [0, 0
 const DARK_CURRENT_ELECTRONS_PER_SECOND = 1;
 const OPERATING_TEMPERATURE_C = 20;
 function fail(message) { throw new InvalidConfigurationError(message); }
+/** Diagnostic clock for the 2.1 stage timings: `performance.now()` where the host has it. Never affects output. */
+function clockMs() { return globalThis.performance?.now() ?? Date.now(); }
 function positive(value, name) {
     if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
         fail(name + " must be a positive finite number.");
@@ -222,7 +296,7 @@ function pngColourEncoding(encoding) {
  * clipping, white balance, highlight mode and the camera→XYZ→linear-sRGB matrices are all the same. It
  * stops before tone mapping, gamut clipping and quantization. It reads the RAW without taking ownership.
  */
-async function developLinearSrgb(input, afterRow) {
+async function developLinearSrgb(input, afterRow, ahd) {
     const v = prepareNativeRawDevelopment(input), plan = v.plan, raw = input.raw, layout = plan.frame.colorSamplingProfile.layout;
     if (layout.kind !== "periodic-mosaic")
         fail("Development requires a periodic CFA.");
@@ -235,6 +309,8 @@ async function developLinearSrgb(input, afterRow) {
         const q = transformOrientedRasterPointToNative({ point: { x: v.crop.x + x + 0.5, y: v.crop.y + y + 0.5 }, nativeRaster: g.activeCapture.raster, orientation: plan.exposure.geometry.orientation });
         return { x: Math.floor(q.x) + active.x, y: Math.floor(q.y) + active.y };
     };
+    if (ahd)
+        return developAhd(v, raw, layout.repeatWidthSites, layout.repeatHeightSites, width, height, at, afterRow, ahd);
     for (let y = 0; y < height; y++) {
         const first = at(0, y), second = width > 1 ? at(1, y) : first;
         developer.developRun(first.x, first.y, second.x - first.x, second.y - first.y, width, row);
@@ -245,6 +321,56 @@ async function developLinearSrgb(input, afterRow) {
     return { rgb, highlight: { mode: v.highlightMode, saturatedPixelCount: c.saturatedPixelCount, whiteBalanceClippedSampleCount: c.whiteBalanceClippedSampleCount,
             reconstructedPixelCount: c.reconstructedPixelCount } };
 }
+/**
+ * AHD development (2.1): the same site normalization as the native development kernel (flagged or white-level sites
+ * are 1, others (code − black)/(white − black)) on the whole native raster, demosaiced by `createAhdDemosaicTask`
+ * (mirrored plane edges), then the native development's own colour operator (`developInto`: WB, highlight mode,
+ * camera → XYZ → linear sRGB) per output pixel. The AHD homogeneity metric sees white-balanced colour: its
+ * camera → XYZ matrix is the profile's matrix times the WB gains (the output values are not transformed by it).
+ * The mosaic is stored in float32, as the AHD task requires.
+ */
+async function developAhd(v, raw, repeatWidth, repeatHeight, width, height, at, afterRow, host) {
+    const native = v.plan.exposure.geometry.nativeRaster, W = native.pixelWidth, H = native.pixelHeight;
+    const source = { nativeWidth: W, repeatWidth, repeatHeight, codes: raw.codes, blackLevels: raw.blackLevels,
+        saturationFlags: raw.saturationFlags, whiteByPhase: raw.effectiveSaturationCodes };
+    const samples = new Float32Array(W * H), saturated = new Uint8Array(W * H);
+    for (let y = 0; y < H; y++)
+        for (let x = 0; x < W; x++) {
+            samples[y * W + x] = normalizedRawSite(source, x, y);
+            if (rawSiteSaturated(source, x, y))
+                saturated[y * W + x] = 1;
+        }
+    const intent = v.plan.exposure.whiteBalanceIntent, gains = intent ? [intent.channelGains.red, intent.channelGains.green, intent.channelGains.blue] : [1, 1, 1];
+    const m = v.color.normalizedCameraChannelsToXyz;
+    const cameraToXyz = [0, 1, 2].map((r) => [0, 1, 2].map((c) => m[r][c] * gains[c]));
+    const task = createAhdDemosaicTask({ plane: { width: W, height: H, captureModeId: v.plan.frame.modeId, colorSamplingProfile: v.plan.frame.colorSamplingProfile, samples },
+        channelRoles: { red: "red", green: "green", blue: "blue" }, cameraToXyz }, { yieldControl: async () => { await host.yieldControl(); host.checkAbort(); } });
+    const demosaicStarted = clockMs();
+    await task.run();
+    host.onDemosaicMs?.(clockMs() - demosaicStarted);
+    const demosaiced = task.takeOutput().data, rgb = new Float64Array(width * height * 3);
+    const counts = { saturatedPixelCount: 0, whiteBalanceClippedSampleCount: 0, reconstructedPixelCount: 0 };
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const p = at(x, y), i = p.y * W + p.x;
+            let clipped = false;
+            for (let dy = -AHD_VALUE_REACH; dy <= AHD_VALUE_REACH && !clipped; dy++)
+                for (let dx = -AHD_VALUE_REACH; dx <= AHD_VALUE_REACH; dx++) {
+                    const sx = p.x + dx, sy = p.y + dy;
+                    if (sx >= 0 && sy >= 0 && sx < W && sy < H && saturated[sy * W + sx] !== 0) {
+                        clipped = true;
+                        break;
+                    }
+                }
+            if (clipped)
+                counts.saturatedPixelCount++;
+            v.development.developInto(demosaiced[3 * i], demosaiced[3 * i + 1], demosaiced[3 * i + 2], rgb, (y * width + x) * 3, counts);
+        }
+        await afterRow(y + 1, height);
+    }
+    return { rgb, highlight: { mode: v.highlightMode, saturatedPixelCount: counts.saturatedPixelCount, whiteBalanceClippedSampleCount: counts.whiteBalanceClippedSampleCount,
+            reconstructedPixelCount: counts.reconstructedPixelCount } };
+}
 /** Linear sRGB/D65 → CIE XYZ (inverse of the development's XYZ → sRGB matrix) → linear target RGB/D65. */
 function linearSrgbToTarget(target) {
     return multiplyMatrices(resolveRgbColorSpace(target).value.xyzToRgb, resolveCaptureColorModel().cameraRgbToXyz);
@@ -327,7 +453,7 @@ export async function simulateCapture(options) {
         preset = parseCallerCameraPreset(cameraOption);
     const body = preset.body, lens = preset.lens;
     // Lens
-    const lensOptions = allowKeys(top.lens, "lens", ["focalLengthMm", "fNumber", "focusDistanceM", "pupilSampling", "projection", "distortion", "vignetting", "psf"]);
+    const lensOptions = allowKeys(top.lens, "lens", ["focalLengthMm", "fNumber", "focusDistanceM", "pupilSampling", "projection", "distortion", "vignetting", "psf", "diffraction"]);
     const focalDefault = lens.exposure.focalLengthMmRange.value.minimum;
     const focalLengthMm = positive(pick(lensOptions, "focalLengthMm", "lens.focalLengthMm", focalDefault, "The preset lens's focal length (the generic primes are 50 mm)."), "lens.focalLengthMm");
     const capabilities = resolveGenericEquipmentExposureCapabilities({ bodyProfile: body.exposure, lensProfile: lens.exposure, selectedFocalLengthMm: focalLengthMm });
@@ -383,6 +509,23 @@ export async function simulateCapture(options) {
             fail("lens.psf cannot be combined with lens.pupilSampling: geometric defocus would be counted twice.");
         lensPsf = p;
     }
+    // Diffraction (2.1): validated here, built once the f-number is resolved.
+    let diffractionRadiusOption;
+    if (lensOptions.diffraction !== undefined) {
+        const d = lensOptions.diffraction;
+        if (d === "circular-aperture")
+            diffractionRadiusOption = null;
+        else {
+            const record = allowKeys(d, "lens.diffraction", ["aperture", "kernelRadiusSamples"]);
+            if (record.aperture !== "circular-aperture")
+                fail("lens.diffraction must be \"circular-aperture\" or { aperture: \"circular-aperture\", kernelRadiusSamples }.");
+            diffractionRadiusOption = record.kernelRadiusSamples === undefined ? null : integerIn(record.kernelRadiusSamples, "lens.diffraction.kernelRadiusSamples", 0, 32);
+        }
+        if (lensPsf)
+            fail("lens.diffraction cannot be combined with lens.psf: diffraction would be counted twice.");
+        if (pupil)
+            fail("lens.diffraction cannot be combined with lens.pupilSampling: the environment contract does not mix a sampled PSF with pupil rays.");
+    }
     // Motion (2.0): constant camera rotation and the shutter type.
     const motionOptions = allowKeys(top.motion, "motion", ["angularVelocityRadPerSec", "shutter", "rollingShutterSkewSeconds"]);
     const angular = { pitch: 0, yaw: 0, roll: 0 };
@@ -403,6 +546,9 @@ export async function simulateCapture(options) {
     if (motionOptions.rollingShutterSkewSeconds !== undefined && shutterKind !== "rolling")
         fail("motion.rollingShutterSkewSeconds needs motion.shutter \"rolling\".");
     const rollingSkewOption = motionOptions.rollingShutterSkewSeconds === undefined ? undefined : positive(motionOptions.rollingShutterSkewSeconds, "motion.rollingShutterSkewSeconds");
+    // Diffraction runs as an object-space convolution when every PSF tap's source is another site centre seen
+    // through one linear map (still camera, rectilinear, no distortion or field throughput); otherwise per tap.
+    const diffractionObjectSpace = diffractionRadiusOption !== undefined && !rotating && !lensFieldMapping && !vignetting;
     // Output and sensor
     const outputOptions = allowKeys(top.output, "output", ["width", "height", "format", "toneCurve", "toneCurveParameters", "highlightMode", "whiteBalance", "jpegQuantizationStep",
         "colorEncoding", "bitDepth", "gamutMapping", "demosaic", "borderHandling", "dng"]);
@@ -451,7 +597,7 @@ export async function simulateCapture(options) {
     const jpegStep = format === "jpeg" ? integerIn(pick(outputOptions, "jpegQuantizationStep", "output.jpegQuantizationStep", DEFAULTS.jpegQuantizationStep, "Constant JPEG quantization step 2 (not a manufacturer quality scale)."), "output.jpegQuantizationStep", 1, 255) : undefined;
     if (format !== "jpeg" && outputOptions.jpegQuantizationStep !== undefined)
         fail("output.jpegQuantizationStep applies only to output.format \"jpeg\".");
-    const sensorOptions = allowKeys(top.sensor, "sensor", ["pixelPitchMicrometers", "spectralStepNanometers", "temporalSampleCount", "noiseSeed"]);
+    const sensorOptions = allowKeys(top.sensor, "sensor", ["pixelPitchMicrometers", "spectralStepNanometers", "temporalSampleCount", "noiseSeed", "antiAliasing"]);
     const pitch = positive(pick(sensorOptions, "pixelPitchMicrometers", "sensor.pixelPitchMicrometers", DEFAULTS.pixelPitchMicrometers, "6 µm pixels (about a 24 MP full-frame sensor). The simulated sensor is width × pitch wide, so small images are a central crop of a large sensor, not a downscaled full frame."), "sensor.pixelPitchMicrometers");
     if (pitch < 0.5 || pitch > 100)
         fail("sensor.pixelPitchMicrometers must be 0.5-100.");
@@ -461,21 +607,25 @@ export async function simulateCapture(options) {
     const temporalSampleCount = integerIn(rotating ? pick(sensorOptions, "temporalSampleCount", "sensor.temporalSampleCount", ROTATING_TEMPORAL_SAMPLE_COUNT, "Eight temporal midpoints across each site's exposure window sample the camera rotation (motion blur); raise it for long exposures or fast rotation.") :
         pick(sensorOptions, "temporalSampleCount", "sensor.temporalSampleCount", DEFAULTS.temporalSampleCount, "One temporal sample: the static scene and still camera make more samples unnecessary."), "sensor.temporalSampleCount", 1, 256);
     const noiseSeed = integerIn(pick(sensorOptions, "noiseSeed", "sensor.noiseSeed", DEFAULTS.noiseSeed, "Fixed noise seed 1 (deterministic output)."), "sensor.noiseSeed", 0, 0xffffffff);
+    const antiAliasing = sensorOptions.antiAliasing === undefined ? undefined : parseAntiAliasing(sensorOptions.antiAliasing, pitch);
     const colorSamplingProfile = { schemaVersion: "0.1.0", profileId: IDS.cfa, evidence: FACADE_EVIDENCE, coordinateSystem: "native-sensor-color-sampling-site-index",
         layout: { kind: "periodic-mosaic", repeatWidthSites: 2, repeatHeightSites: 2, siteChannelIds: ["red", "green", "green", "blue"], anchor: "native-sensor-top-left-site" } };
     // Demosaic (2.0): built-in Bayer kernels and border handling. Omitted, the 1.0 bilinear kernels and a
     // one-site rendered border are used unchanged.
     const demosaicOption = outputOptions.demosaic, borderOption = outputOptions.borderHandling;
-    if (demosaicOption !== undefined && demosaicOption !== "bilinear")
-        fail("output.demosaic must be bilinear.");
+    if (demosaicOption !== undefined && demosaicOption !== "bilinear" && demosaicOption !== "ahd")
+        fail("output.demosaic must be bilinear or ahd.");
+    const ahd = demosaicOption === "ahd";
     if (borderOption !== undefined && borderOption !== "margin" && borderOption !== "mirror")
         fail("output.borderHandling must be margin or mirror.");
     const builtInDemosaic = demosaicOption === undefined ? undefined : createBuiltInBayerDemosaicProfiles({ kernel: "bilinear",
         captureModeId: IDS.mode, colorSamplingProfile, channelRoles: { red: "red", green: "green", blue: "blue" } }).value;
     const mirrorBorder = borderOption === "mirror";
-    const margin = mirrorBorder ? 0 : builtInDemosaic ? builtInDemosaic.kernelReachSites : MARGIN;
+    const margin = mirrorBorder ? 0 : ahd ? AHD_MARGIN : builtInDemosaic ? builtInDemosaic.kernelReachSites : MARGIN;
     if (mirrorBorder && (width < 2 || height < 2))
         fail("output.borderHandling \"mirror\" needs an output of at least 2 × 2 pixels.");
+    if (ahd && mirrorBorder && (width < 3 || height < 3))
+        fail("output.demosaic \"ahd\" with mirror borders needs an output of at least 3 × 3 pixels.");
     // Geometry: the demosaic border (if any) on each side; output crop is the active area.
     const nativeWidth = width + 2 * margin, nativeHeight = height + 2 * margin;
     const imagingArea = { widthMm: nativeWidth * pitch / 1000, heightMm: nativeHeight * pitch / 1000 };
@@ -492,6 +642,8 @@ export async function simulateCapture(options) {
     else {
         if (demosaicOption === undefined)
             assume("output.demosaic", "default", "bilinear-rggb", "The 1.0 facade's bilinear RGGB kernels (explicit linear neighbourhood weights).");
+        else if (ahd)
+            assume("output.demosaic", "model", { method: "ahd-hirakawa-parks-2005", dependenceReachSites: AHD_MARGIN }, "Adaptive homogeneity-directed demosaicing (createAhdDemosaicTask, after Hirakawa & Parks, IEEE TIP 14(3), 2005): directional green, red/blue from colour differences, and per pixel the more homogeneous of the horizontal and vertical candidates in CIELAB (white-balanced camera colour); the paper's iterative median step is not applied. Non-linear; the mosaic is normalized and white-level clipped as in the native development and stored in float32, and the native development's colour operator follows. request.development keeps the built-in bilinear kernels, which validate the development but are not used for these pixels.");
         else
             assume("output.demosaic", "model", { kernel: builtInDemosaic.kernel, modelVersion: BUILT_IN_DEMOSAIC_VERSION, kernelReachSites: builtInDemosaic.kernelReachSites }, "Built-in bilinear Bayer kernels (createBuiltInBayerDemosaicProfiles): nearest same-channel averages.");
         if (borderOption === undefined)
@@ -505,7 +657,7 @@ export async function simulateCapture(options) {
     const psfTaps = lensPsf ? Math.max(1, ...(lensPsf.configuration.psf.profile.nodes ?? [])
         .map((node) => Number(node.kernel?.widthSamples) * Number(node.kernel?.heightSamples)).filter((taps) => Number.isSafeInteger(taps) && taps > 0)) : 1;
     const queriesPerSite = temporalSampleCount * (Math.ceil((FACADE_SPECTRAL_RANGE_NANOMETERS.maximum - FACADE_SPECTRAL_RANGE_NANOMETERS.minimum) / spectralStep) + 1) *
-        (pupil ? pupil.radialSamples * pupil.angularSamples : 1) * psfTaps;
+        (pupil ? pupil.radialSamples * pupil.angularSamples : 1) * psfTaps * (antiAliasing ? antiAliasing.components.length : 1);
     // Scene and illuminant
     // The scene is the one required input: the facade never guesses what is being photographed.
     if (top.scene === undefined)
@@ -634,7 +786,19 @@ export async function simulateCapture(options) {
     assume("sensor.capacityElectrons", "derived", capacityElectrons, "Physical charge capacity set to the body's largest declared pre-ADC saturation (its base-ISO saturation signal), so storage never clips before the declared readout white.");
     assume("sensor.darkCurrent", "model", { electronsPerSecond: DARK_CURRENT_ELECTRONS_PER_SECOND, temperatureC: OPERATING_TEMPERATURE_C }, "Synthetic uniform dark current of 1 e⁻/s per site at 20 °C (the tier presets declare none); dark shot noise follows from it.");
     assume("sensor.spectralResponse", "model", { kind: "colorimetric-cmf-eqe", peakScale: EQE_SCALE }, "Idealized colorimetric sensor: channel EQE = a·{x̄, ȳ, z̄}(λ)·555/λ (the engine's analytic CIE 1931 fit), so RAW channels are proportional to CIE XYZ (Luther–Ives) and the camera matrix is diagonal. Not a real camera's response; CMF air wavelengths are used as vacuum wavelengths (difference about 0.03 %).");
-    assume("sensor.fillFactor", "model", 1, "Square sensitive aperture equal to the pixel pitch; no microlens or anti-aliasing filter.");
+    if (!antiAliasing)
+        assume("sensor.fillFactor", "model", 1, "Square sensitive aperture equal to the pixel pitch; no microlens or anti-aliasing filter.");
+    else {
+        assume("sensor.fillFactor", "model", 1, "Square sensitive aperture equal to the pixel pitch; no microlens.");
+        assume("sensor.antiAliasing", "model", { kind: antiAliasing.kind, ...(antiAliasing.axis ? { axis: antiAliasing.axis } : {}),
+            ...(antiAliasing.separationSites === undefined ? {} : { separationSites: antiAliasing.separationSites, separationMicrometers: antiAliasing.separationSites * pitch }),
+            components: antiAliasing.components }, "Optical low-pass (anti-aliasing) filter as a normalized point-splitting kernel in the sensor optical stack (resolveAntiAliasingSpatialKernel): every site integrates the light that would " +
+            "otherwise land at its centre minus each offset, weighted. " + (antiAliasing.kind === "point-splitting" ? "Caller-declared components. " :
+            "This is the ideal birefringent " + (antiAliasing.kind === "four-spot" ? "two-plate (crossed) splitter: four equal spots at (±d/2, ±d/2), MTF |cos(π·f_x·d)·cos(π·f_y·d)|" :
+                "single-plate splitter: two equal spots at ±d/2 along the " + antiAliasing.axis + " axis, MTF |cos(π·f·d)|") + ", d = " + antiAliasing.separationSites + " site(s); first zero at f = 1/(2d). ") +
+            "Approximations: the split is the same at every wavelength, field point and polarization (birefringence dispersion and the thickness-dependent displacement are not modelled), the spots are exact points with equal weights for unpolarized light, " +
+            "and the filter's transmission, reflections and focus shift are not modelled. Not a measured filter; the tier presets declare none. The scene queries are multiplied by " + antiAliasing.components.length + ".");
+    }
     // Shutter (2.0): the electronic rolling-shutter schedule derived from the body's rolling readout declaration.
     let rollingSchedule;
     if (shutterKind === "rolling") {
@@ -655,7 +819,8 @@ export async function simulateCapture(options) {
         assume("motion.angularVelocityRadPerSec", "model", { ...angular }, "Constant camera angular velocity applied to every scene ray at each temporal midpoint of each site's exposure window (engine rotation convention, docs/SENSOR_ENVIRONMENT_QUERY.md); motion blur is the midpoint quadrature over sensor.temporalSampleCount samples.");
     if (lensPsf)
         assume("lens.psf", "model", { kind: "sampled-local" }, "Caller-supplied sampled lens PSF redistributes irradiance through the environment PSF quadrature; its evidence and limits are the caller's.");
-    else
+    // With lens.diffraction the PSF is recorded as lens.diffraction once its kernels are built.
+    else if (diffractionRadiusOption === undefined)
         assume("lens.psf", "model", "not-applied", "No lens PSF or diffraction blur is applied (point optics); the generic tiers' optical data are declared only at f/4.");
     assume("lens.transmission", "model", lens.matchedReference.transmission, "The tier lens's spectrally flat transmission is used at every f-number and focus in the lens capability; the tier declares it only at its f/4, 5 m reference state.");
     if (!vignetting && !lensFieldMapping)
@@ -753,10 +918,14 @@ export async function simulateCapture(options) {
         siteCenterLattice: { kind: "regular-rectangular-site-center-lattice", coordinateSystem: "native-sensor-physical", pitchXMicrometers: pitch, pitchYMicrometers: pitch,
             firstSiteCenterFromImagingAreaTopLeftMicrometers: { x: pitch / 2, y: pitch / 2 }, evidence },
         geometricSensitiveAperture: { kind: "uniform-axis-aligned-rectangle", widthMicrometers: pitch, heightMicrometers: pitch, centerOffsetFromSiteCenterMicrometers: { x: 0, y: 0 }, evidence } };
-    const opticalStackProfile = { schemaVersion: "0.1.0", profileId: IDS.stack, evidence, effectiveAntiAliasingSpatialResponse: { kind: "absent", evidence } };
+    const stackId = antiAliasing ? IDS.stackAa : IDS.stack;
+    const opticalStackProfile = antiAliasing ? { schemaVersion: "0.1.0", profileId: stackId, evidence, effectiveAntiAliasingSpatialResponse: {
+            kind: "normalized-point-splitting-kernel", evidence, coordinateSystem: "native-sensor-physical", scope: "field-wavelength-polarization-invariant-approximation",
+            components: antiAliasing.components
+        } } : { schemaVersion: "0.1.0", profileId: IDS.stack, evidence, effectiveAntiAliasingSpatialResponse: { kind: "absent", evidence } };
     const perChannel = Object.fromEntries(CHANNELS.map((channelId) => [channelId, {
             applicationProfile: { schemaVersion: "0.1.0", profileId: "facade-application-" + channelId, spectralResponseProfileId: IDS.spectral, colorSamplingProfileId: IDS.cfa, channelId,
-                samplingApertureProfileId: IDS.sampling, opticalStackProfileId: IDS.stack, evidence, incidentAreaBasis: { kind: "geometric-sensitive-aperture", areaSquareMicrometers: apertureArea },
+                samplingApertureProfileId: IDS.sampling, opticalStackProfileId: stackId, evidence, incidentAreaBasis: { kind: "geometric-sensitive-aperture", areaSquareMicrometers: apertureArea },
                 spatialResponseModel: { kind: "uniform-over-geometric-sensitive-aperture", scientificStatus: "approximation", evidence, limitation: "Uniform response over the square aperture." },
                 referenceConditionPolicy: { kind: "exact-match-required" } },
             operatingRangeProfile: { schemaVersion: "0.1.0", profileId: "facade-linearity-" + channelId, responseApplicationProfileId: "facade-application-" + channelId,
@@ -786,7 +955,8 @@ export async function simulateCapture(options) {
             outputQuantity: "outgoing-spectral-radiance", outputUnit: "W/m^2/sr/nm", scientificStatus: "approximation",
             uncertainty: { kind: "not-quantified", limitation: "Analytic planar scene." },
             fidelity: { spectral: "wavelength-resolved", material: "spectral-data", visibility: "resolved", directTransport: "approximation", indirectTransport: "not-modeled" },
-            wavelengthChangingTransportModeled: false, volumetricTransportModeled: false, polarizationModeled: false, evidence, limitations: ["Engine-authored planar chart or caller scene function."] }
+            wavelengthChangingTransportModeled: false, volumetricTransportModeled: false, polarizationModeled: false, evidence, limitations: ["Engine-authored planar chart or caller scene function.",
+                ...(diffractionObjectSpace ? ["Radiance is the scene radiance convolved with the lens diffraction PSF mapped onto the scene plane (object-space convolution, request.diffraction)."] : [])] }
     };
     const lensId = lens.exposure.profileId;
     const opticsProfile = { schemaVersion: "0.1.0", profileId: lensId + ":facade-transmission", profileVersion: SIMULATE_CAPTURE_FACADE_VERSION, lensProfileId: lensId,
@@ -805,11 +975,39 @@ export async function simulateCapture(options) {
     const fieldThroughput = vignetting ? { kind: "radial-illumination-vignetting", profile: vignetting, evidence,
         limitation: "Caller-declared radial relative illumination applied by the capture facade; not a measured lens." } :
         { kind: "unity", evidence, limitation: "No vignetting or field throughput loss applied by the facade." };
-    const psf = lensPsf ?? { kind: "not-applied", evidence, limitation: "No lens PSF (point optics)." };
-    const pupilRecord = pupil ? { kind: "ideal-uniform-circular-pupil", radialSampleCount: pupil.radialSamples, angularSampleCount: pupil.angularSamples, evidence,
-        limitation: "Ideal uniform circular pupil; finite ray sampling, no convergence claim." } : undefined;
     const spectralSamplingByChannel = Object.fromEntries(CHANNELS.map((channelId) => [channelId, { channelId, wavelengthBasis: "vacuum", wavelengthRangeNanometers: range,
             maximumSubintervalWidthNanometers: spectralStep }]));
+    // Diffraction (2.1): Airy kernels at the resolved f-number on the site pitch, one per spectral node of the sensor quadrature.
+    let diffraction, diffractionPsf;
+    if (diffractionRadiusOption !== undefined) {
+        const wavelengths = [...new Set(CHANNELS.flatMap((channelId) => calculateSensorSpectralQuadrature({ ...spectralSamplingByChannel[channelId], colorSamplingProfile,
+                spectralResponseProfile: spectralResponseProfiles[channelId] }).value.nodes.map((node) => node.wavelengthNanometers)))].sort((a, b) => a - b);
+        const lambdaN = wavelengths[wavelengths.length - 1] / 1000 * fNumber * imageDistanceMm / focalLengthMm;
+        // The environment resolves the PSF at each pre-filter source point, up to the largest split offset outside the imaging area.
+        const aaReachMm = antiAliasing ? Math.max(...antiAliasing.components.map((c) => Math.max(Math.abs(c.offsetMicrometers.x), Math.abs(c.offsetMicrometers.y)))) / 1000 : 0;
+        const kernelRadiusSamples = diffractionRadiusOption ?? Math.min(32, Math.max(1, Math.ceil(AIRY_THIRD_ZERO_PER_LAMBDA_N * lambdaN / pitch)));
+        diffraction = createDiffractionLimitedPsfProfile({ aperture: "circular", focalLengthMm, apertureFNumber: fNumber, focus: { kind: "finite", distanceM: focusDistanceM },
+            wavelengthsNm: wavelengths, samplePitchMicrometers: pitch, kernelRadiusSamples, fieldHalfExtentMm: aaReachMm === 0 ? { x: imagingArea.widthMm / 2, y: imagingArea.heightMm / 2 } :
+                { x: imagingArea.widthMm / 2 + aaReachMm, y: imagingArea.heightMm / 2 + aaReachMm },
+            profileId: "facade-diffraction-airy" }).value;
+        diffractionPsf = { kind: "sampled-local", configuration: { psf: { profile: diffraction.profile, focalLengthMm, focus: { kind: "finite", distanceM: focusDistanceM },
+                    apertureFNumber: fNumber, signedDefocusImagePlaneMicrometers: 0 }, psfWavelengthBasis: { value: "vacuum", evidence },
+                spatialModel: { kind: "destination-local-shift-invariant-approximation", evidence, limitation: "Diffraction-limited Airy PSF, the same at every field point." } } };
+        assume("lens.diffraction", "model", { model: diffraction.model, aperture: "circular-aperture", fNumber, workingFNumber: diffraction.workingFNumber,
+            kernelRadiusSamples, samplePitchMicrometers: pitch, maximumTruncatedEnergyFraction: diffraction.maximumTruncatedEnergyFraction,
+            truncatedEnergyByWavelength: diffraction.wavelengths.map((w) => ({ wavelengthNm: w.wavelengthNm, truncatedEnergyFraction: w.truncatedEnergyFraction })),
+            execution: diffractionObjectSpace ? "object-space-convolution" : "environment-psf-quadrature" }, "Scalar Fraunhofer diffraction of an ideal, aberration-free circular pupil (Airy pattern, createDiffractionLimitedPsfProfile) at the resolved f-number, in focus, with D = f/N and the thin-lens image distance (working f-number N·v/f). " +
+            "One kernel per spectral node, binned into site-sized cells over a " + (2 * kernelRadiusSamples + 1) + " × " + (2 * kernelRadiusSamples + 1) + " window" +
+            (diffractionRadiusOption === null ? " (reaching the third dark ring at the longest node)" : "") + "; the Airy tail energy outside it (listed per wavelength) is put back by unit-sum renormalization. " +
+            (diffractionObjectSpace ? "Applied as an object-space convolution: the scene radiance on the site lattice is convolved once per spectral node (calculateIrradianceConvolution) and the provider answers each site query with it, so the site inputs declare no PSF; this equals the per-tap environment PSF quadrature for this still, distortion-free planar scene (request.diffraction.psf). " :
+                "Applied through the environment PSF quadrature (one scene query per kernel tap), because camera rotation, a lens field mapping or vignetting moves the taps off the site lattice. ") +
+            "No defocus, aberration or pupil clipping; the sensor pixel aperture is still point-sampled at the site centre.");
+    }
+    const psf = lensPsf ?? (diffractionObjectSpace ? { kind: "not-applied", evidence,
+        limitation: "No environment PSF: lens diffraction is applied upstream by the scene provider as an object-space convolution (request.diffraction)." } : undefined) ??
+        diffractionPsf ?? { kind: "not-applied", evidence, limitation: "No lens PSF (point optics)." };
+    const pupilRecord = pupil ? { kind: "ideal-uniform-circular-pupil", radialSampleCount: pupil.radialSamples, angularSampleCount: pupil.angularSamples, evidence,
+        limitation: "Ideal uniform circular pupil; finite ray sampling, no convergence claim." } : undefined;
     const chargeSamplingProfile = { schemaVersion: "0.1.0", profileId: IDS.chargeSampling, completenessProfileId: IDS.completeness, scientificStatus: "approximation",
         photoShotNoiseModel: "poisson", darkShotNoiseModel: "poisson", additionalComponentPolicies: [], evidence, limitations: ["Poisson photo and dark shot noise."] };
     const channelAt = (x, y) => ["red", "green", "green", "blue"][(y % 2) * 2 + (x % 2)];
@@ -843,7 +1041,15 @@ export async function simulateCapture(options) {
     }
     const readTile = async (request) => ({ ...request, sites: Array.from({ length: request.width }, (_, j) => siteInput(request.y * nativeWidth + request.x + j)) });
     const yieldControl = createHostYield().yieldControl;
-    const perSite = queriesPerSite;
+    const perSite = queriesPerSite * (diffraction && psf === diffractionPsf ? (2 * diffraction.kernelRadiusSamples + 1) ** 2 : 1);
+    let diffractionMs = 0, demosaicMs, encodeMs;
+    const rawProvider = diffraction && diffractionObjectSpace ? createDiffractedPlanarProvider({ base: provider, psf: diffractionPsf.configuration.psf,
+        wavelengthsNm: diffraction.profile.axes.wavelengthNm, kernelRadius: diffraction.kernelRadiusSamples, nativeWidth, nativeHeight, outputWidth: width,
+        sitePitchMicrometers: pitch, distanceM: subjectDistanceM, metresPerFrameUnit, onConvolution: (ms) => { diffractionMs += ms; },
+        // The environment queries each site at its centre minus each split offset (sites, +x right, +y down).
+        ...(antiAliasing ? { queryOffsetsSites: antiAliasing.components.map((c) => ({ x: -c.offsetMicrometers.x / pitch, y: -c.offsetMicrometers.y / pitch })) } : {}) }) : provider;
+    if (antiAliasing && perSite > 100_000)
+        fail("sensor.antiAliasing with these options needs " + perSite + " scene queries per site; the environment admits at most 100000.");
     const evaluations = nativeWidth * nativeHeight * perSite;
     // The native task admits at most 100 000 radiance queries per tile.
     const tileWidth = Math.max(1, Math.min(256, Math.floor(100_000 / perSite)));
@@ -876,7 +1082,7 @@ export async function simulateCapture(options) {
     const rawTick = progress("raw", plan.tileCount);
     const rawTask = createNativeEnvironmentRawTask(environmentRaw, {
         readTile: async (request) => { const tile = await readTile(request); rawTick(); return tile; },
-        evaluateRadiance: provider.evaluateRadiance, ...(pupil ? { evaluateApertureRadiance: provider.evaluateApertureRadiance } : {}), yieldControl
+        evaluateRadiance: rawProvider.evaluateRadiance, ...(pupil ? { evaluateApertureRadiance: provider.evaluateApertureRadiance } : {}), yieldControl
     });
     await runTask(rawTask);
     let rawOutput = rawTask.takeOutput();
@@ -905,7 +1111,7 @@ export async function simulateCapture(options) {
         // retained optical stage, and is faster: retaining the optical stage takes the first pass off the lean executor.
         const wbTask = createNativeEnvironmentRawTask(finalRawInput, {
             readTile: async (request) => { const tile = await readTile(request); wbTick(); return tile; },
-            evaluateRadiance: provider.evaluateRadiance, ...(pupil ? { evaluateApertureRadiance: provider.evaluateApertureRadiance } : {}), yieldControl
+            evaluateRadiance: rawProvider.evaluateRadiance, ...(pupil ? { evaluateApertureRadiance: provider.evaluateApertureRadiance } : {}), yieldControl
         });
         await runTask(wbTask);
         rawOutput = wbTask.takeOutput();
@@ -924,7 +1130,9 @@ export async function simulateCapture(options) {
             return [channel, { conversionGainElectronsPerCode: resolved.regime.systemConversionGainElectronsPerCode.value / (resolved.regime.adc.digitalGain ?? 1),
                     readNoiseRmsElectrons: resolved.combinedReadNoiseRmsElectrons }];
         }));
+        const dngStarted = clockMs();
         dng = await serializeNativeRawDng({ raw: rawOutput.raw, colorProfile, noise, ...(dngCapturedAtUtc === undefined ? {} : { capturedAtUtc: dngCapturedAtUtc }) });
+        encodeMs = clockMs() - dngStarted;
         checkAbort();
         assume("output.dng", "model", { writer: "serializeNativeRawDng", schemaVersion: dng.schemaVersion, whiteLevel: dng.whiteLevel, blackLevels: dng.blackLevels,
             noiseProfile: dng.noiseProfile, unrepresentedSaturationFlagCount: dng.unrepresentedSaturationFlagCount }, "Lossless uncompressed 16-bit CFA DNG of exactly the packed native RAW codes: per-phase BlackLevel, WhiteLevel = smallest per-phase effective white, ActiveArea and DefaultCrop from the capture geometry, ColorMatrix1/ForwardMatrix1 from the facade's diagonal camera→XYZ profile (D65), AsShotNeutral from the white-balance intent, BaselineExposure 0, and NoiseProfile from each channel's readout regime (conversion gain ÷ digital gain, combined read noise; Poisson + Gaussian + quantization only). No linear master or developed image is declared; saturation flags below WhiteLevel are not representable and are counted.");
@@ -935,7 +1143,37 @@ export async function simulateCapture(options) {
         maximumRetainedPayloadBytes: plan.outputBytes + width * height * 3 * (rendering.bitDepth / 8) };
     let developed;
     let gamutMappingDiagnostics;
-    if (!linearPath) {
+    if (ahd) {
+        let lastYield = Date.now();
+        const linear = await developLinearSrgb({ ...development, raw: rawOutput.raw }, async (completed, total) => {
+            onProgress?.({ stage: "development", completedTileCount: completed, totalTileCount: total });
+            if (Date.now() - lastYield >= 8) {
+                await yieldControl();
+                checkAbort();
+                lastYield = Date.now();
+            }
+        }, { yieldControl: () => yieldControl(), checkAbort, onDemosaicMs: (ms) => { demosaicMs = ms; } });
+        if (!linearPath) {
+            // The native development's SDR kernel, row by row, on the AHD-developed linear sRGB.
+            const maximum = 2 ** rendering.bitDepth - 1, tone = prepareSdrPixelTone(rendering), scratch = new Float64Array(3);
+            const codes = rendering.bitDepth === 8 ? new Uint8Array(width * height * 3) : new Uint16Array(width * height * 3);
+            const counts = { negative: 0, above: 0, changed: 0, low: 0, high: 0, outOfGamut: false };
+            for (let y = 0; y < height; y++)
+                renderSdrRunInto(linear.rgb, y * width * 3, width, rendering, tone, 2 ** rendering.renderingExposureEv, maximum, codes, y * width * 3, scratch, counts);
+            developed = { raw: rawOutput.raw, integerSamples: codes, highlight: linear.highlight, diagnostics: { renderingNegativeSampleCount: counts.negative,
+                    renderingAboveReferenceSampleCount: counts.above, toneChangedSampleCount: counts.changed, gamutClippedLowSampleCount: counts.low,
+                    gamutClippedHighSampleCount: counts.high, captureSaturation: "consumed-in-raw-development" } };
+        }
+        else {
+            const mapping = perceptual ? prepareRgbGamutMapping({ colorSpace: colorEncoding, method: "cielab-hue-preserving-chroma-compression", kneeFraction: PERCEPTUAL_GAMUT_KNEE_FRACTION }) : undefined;
+            const encoded = encodeSdrFromLinear(linear.rgb, colorEncoding, pngBitDepth, mapping);
+            developed = { raw: rawOutput.raw, integerSamples: encoded.samples, highlight: linear.highlight, diagnostics: encoded.diagnostics };
+            if (mapping)
+                gamutMappingDiagnostics = { method: "cielab-hue-preserving-chroma-compression", kneeFraction: PERCEPTUAL_GAMUT_KNEE_FRACTION,
+                    adjustedPixelCount: encoded.adjustedPixelCount, lightnessClippedPixelCount: encoded.lightnessClippedPixelCount };
+        }
+    }
+    else if (!linearPath) {
         const devTask = createNativeRawDevelopmentTask({ ...development, raw: rawOutput.raw }, { yieldControl,
             onProgress: (p) => onProgress?.({ stage: "development", completedTileCount: p.completedTileCount, totalTileCount: p.totalTileCount }) });
         await runTask(devTask);
@@ -985,36 +1223,53 @@ export async function simulateCapture(options) {
                 return { ...request, samples: out };
             }, yieldControl
         });
+        const jpegEncodeStarted = clockMs();
         await runTask(jpegTask);
         jpeg = jpegTask.takeOutput().bytes;
+        encodeMs = clockMs() - jpegEncodeStarted;
         assume("output.jpeg", "model", { encoder: "photivra-print-jpeg", iccProfile: "photivra-srgb" }, "Baseline JPEG from the existing print JPEG encoder with an embedded sRGB ICC profile; the source digest covers a sample prefix, length and scene digest.");
     }
     const jpegMs = Date.now() - jpegStarted;
     let png;
     if (format === "png") {
+        const pngStarted = clockMs();
         png = serializePngImage({ width, height, bitDepth: pngBitDepth, samples: developed.integerSamples, colourEncoding: pngColourEncoding(colorEncoding) });
+        encodeMs = clockMs() - pngStarted;
         assume("output.png", "model", { encoder: "serializePngImage", bitDepth: pngBitDepth, colourEncoding: pngColourEncoding(colorEncoding) }, "Deterministic PNG (8/16-bit RGB, in-house zlib) with the colour encoding signalled in the file: the sRGB chunk for sRGB, otherwise a cICP chunk with ITU-T H.273 primaries/transfer code points. No mastering-display (mDCV) or content-light-level (cLLI) metadata is written.");
     }
+    const ranOptions = new Set([...(pupil ? ["lens.pupilSampling"] : []), ...(projection !== undefined ? ["lens.projection"] : []),
+        ...(distortion ? ["lens.distortion"] : []), ...(vignetting ? ["lens.vignetting"] : []), ...(lensPsf ? ["lens.psf"] : []),
+        ...(diffraction ? ["lens.diffraction"] : []), ...(antiAliasing ? ["sensor.antiAliasing"] : []),
+        ...(temporalSampleCount > 1 ? ["sensor.temporalSampleCount"] : []), ...(rotating ? ["motion.rotation"] : []),
+        ...(rollingSchedule ? ["motion.shutter.rolling"] : []), ...(mirrorBorder ? ["output.borderHandling.mirror"] : []),
+        ...(needsAuto ? ["output.whiteBalance.auto"] : []), ...(ahd ? ["output.demosaic.ahd"] : []),
+        ...(highlightMode === "reconstruct" ? ["output.highlightMode.reconstruct"] : []), ...(wideGamut ? ["output.colorEncoding.wide-gamut"] : []),
+        ...(perceptual ? ["output.gamutMapping.perceptual"] : []), ...(format === "jpeg" || format === "png" || format === "dng" ? ["output.format." + format] : [])]);
     return Object.freeze({
         facadeVersion: SIMULATE_CAPTURE_FACADE_VERSION, engineApiVersion: ENGINE_API_VERSION,
         image: { width, height, format, samples: developed.integerSamples, ...(jpeg ? { jpeg } : {}), ...(png ? { png, colorEncoding: colorEncoding } : {}), ...(dng ? { dng: dng.bytes } : {}) },
         raw: developed.raw, plan,
-        request: { environmentRaw: finalRawInput, siteInput, development, whiteBalanceState },
+        request: { environmentRaw: finalRawInput, siteInput, development, whiteBalanceState,
+            ...(diffraction ? { diffraction: { profile: diffraction, psf: diffractionPsf, execution: diffractionObjectSpace ? "object-space-convolution" : "environment-psf-quadrature" } } : {}) },
         exposure: { mode, settings: { fNumber, shutterSeconds, iso: resolvedIso }, ev100: Math.log2(fNumber ** 2 / shutterSeconds),
             meteredSceneLuminanceCdPerSquareMeter: meteredLuminance, resolution },
         scene: { sceneId: chart ? "chart:" + chart.preset : callerScene.sceneId, preset: scenePreset, parameters: chart ? chart.parameters : {},
             illuminant: { id: illuminant.id, description: illuminant.description, illuminanceLux }, distanceM: subjectDistanceM,
             framedWidthM: 2 * metresPerFrameUnit, framedHeightM: 2 * metresPerFrameUnit * aspect, sourceSha256 },
         diagnostics: { providerEvaluationCount, highlight: developed.highlight, rendering: developed.diagnostics, ...(gamutMappingDiagnostics ? { gamutMapping: gamutMappingDiagnostics } : {}),
-            timingsMs: { raw: rawMs, whiteBalance: wbMs, development: devMs, jpeg: jpegMs, total: Date.now() - started } },
+            timingsMs: { raw: rawMs, whiteBalance: wbMs, development: devMs, jpeg: jpegMs, total: Date.now() - started,
+                ...(diffraction && diffractionObjectSpace ? { diffraction: diffractionMs } : {}), ...(demosaicMs === undefined ? {} : { demosaic: demosaicMs }),
+                ...(encodeMs === undefined ? {} : { encode: encodeMs }) },
+            options: Object.freeze(SIMULATE_CAPTURE_COST_OPTIONS.filter((option) => ranOptions.has(option))) },
         provenance: { scientificStatus: "approximation", cameraPresetId: preset.presetId, cameraPresetVersion: preset.presetVersion,
             evidence: [...FACADE_EVIDENCE, ...preset.evidence],
             composedContracts: ["resolveGenericEquipmentExposureCapabilities", "meterRelativeExposure", "createExposureMeterTargetFromMeteringResult",
                 "resolve" + (mode === "manual" ? "Manual" : mode === "aperture-priority" ? "AperturePriority" : mode === "shutter-priority" ? "ShutterPriority" : "ProgramAuto") + "ExposureMode",
                 ...(rollingSchedule ? ["resolveElectronicRollingShutterExposureSchedule", "createRollingShutterCaptureExposureSchedule"] : []),
-                "resolveGenericIsoSignalChain", "createNativeEnvironmentRawTask", ...(needsAuto ? ["estimateAutoWhiteBalance"] : []),
-                ...(builtInDemosaic ? ["createBuiltInBayerDemosaicProfiles"] : []),
-                ...(linearPath ? ["native RAW development operator (linear, pre-clip)", "resolveRgbColorSpace", ...(perceptual ? ["prepareRgbGamutMapping"] : [])] : ["createNativeRawDevelopmentTask"]),
+                ...(diffraction ? ["createDiffractionLimitedPsfProfile", ...(diffractionObjectSpace ? ["resolveLensPsfConvolutionKernels", "calculateIrradianceConvolution"] : [])] : []),
+                ...(antiAliasing ? ["resolveAntiAliasingSpatialKernel"] : []), "resolveGenericIsoSignalChain", "createNativeEnvironmentRawTask", ...(needsAuto ? ["estimateAutoWhiteBalance"] : []),
+                ...(builtInDemosaic ? ["createBuiltInBayerDemosaicProfiles"] : []), ...(ahd ? ["createAhdDemosaicTask"] : []),
+                ...(ahd ? ["native RAW development operator (colour, after AHD)", ...(linearPath ? ["resolveRgbColorSpace", ...(perceptual ? ["prepareRgbGamutMapping"] : [])] : ["SDR rendering kernel"])] : linearPath ? ["native RAW development operator (linear, pre-clip)", "resolveRgbColorSpace", ...(perceptual ? ["prepareRgbGamutMapping"] : [])] : ["createNativeRawDevelopmentTask"]),
                 ...(jpeg ? ["createPrintJpegTask"] : []), ...(png ? ["serializePngImage"] : []), ...(dng ? ["resolveSensorReadoutRegime", "serializeNativeRawDng"] : [])],
             limitations: ["Educational approximation: synthetic tier sensor values, idealized colorimetric sensor, planar Lambertian scene and point optics; not a calibrated camera emulation.",
                 "Not offered by the facade: atmospheric haze and polarizers (the scene-radiance provider contract declares no volumetric transport or polarization), flash, video, HDR brackets and processing operators; compose those APIs directly."] },