dtourolleandClaude Opus 5
c9305fd0e6
A test that cannot be run cannot be checked by running it, and a number copied out of a test run agrees with whatever the code did on the day. Each asserted kernel width, tolerance and overshoot bound now carries the arithmetic that produces it -- the shorter edge, the sigma, the truncation at two sigmas, and where the rounding falls -- so a reader can verify the expectation against the recipe without a GPU or a compiler. Also records the two places where a bound is a bound and not a measurement: the tolerance in the frame-fraction test is exactly what rounding a kernel to a whole pixel costs on the smallest frame it uses, and the halo test's floor and ceiling bracket a peak derived from the step, the soft limit and the midtone taper rather than from a run. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
881 lines
38 KiB
Rust
881 lines
38 KiB
Rust
//! TRACES: FR-DEV-3 | FR-DSP-1
|
||
//! Clarity and texture — local contrast at two scales.
|
||
//!
|
||
//! Both are unsharp masks. Both build a blurred *base*, subtract it from the
|
||
//! pixel to get a local contrast signal, and add a multiple of that signal
|
||
//! back. The only thing that separates them is the width of the blur, and
|
||
//! that single difference is the whole of what a photographer means by the two
|
||
//! words:
|
||
//!
|
||
//! - **Clarity** works at roughly a hundredth of the frame. At that scale the
|
||
//! base is a picture of where the *subject* is, so the difference is the
|
||
//! subject's modelling — the sense of a face standing away from its
|
||
//! background, of cloud having volume. It is the "punch" control, and it is
|
||
//! also the one that produces visible halos when it is got wrong, because a
|
||
//! forty-pixel overshoot along a skyline is not a subtlety.
|
||
//!
|
||
//! - **Texture** works a decade finer, at a few pixels. At that scale the base
|
||
//! is a picture of the *surface*, so the difference is skin, fabric, bark,
|
||
//! foliage. Its overshoot is a band two or three pixels wide, which the eye
|
||
//! reads as acutance rather than as a halo — which is exactly why it can be
|
||
//! pushed much harder than clarity without looking artificial.
|
||
//!
|
||
//! # Why two nodes and not one node with two parameters
|
||
//!
|
||
//! The tempting shape is a single `local_contrast` node with a `clarity` and a
|
||
//! `texture` slider, since they share every line of machinery. It is the wrong
|
||
//! one, for four reasons that all point the same way.
|
||
//!
|
||
//! **The scale is not a parameter, it is the definition.** Neither control
|
||
//! exposes a radius, and neither should: a texture slider with a large radius
|
||
//! *is* clarity, and offering the photographer that knob would ask them to
|
||
//! re-derive the distinction the two names already make. So the radius is a
|
||
//! constant of the node — and a node whose defining constant differs is a
|
||
//! different node, not a different setting.
|
||
//!
|
||
//! **Neutrality would have to be re-implemented by hand.** The rule the whole
|
||
//! pipeline rests on is that an operation at its defaults contributes nothing:
|
||
//! no code, no uniform, no dispatch. `is_active()` gives each of these that for
|
||
//! free. Merged, the node would be active whenever *either* slider had moved,
|
||
//! and would then need an internal guard per half to avoid dispatching a
|
||
//! forty-pixel blur for a control sitting at zero — hand-writing, in one
|
||
//! place, the thing the pipeline already does everywhere.
|
||
//!
|
||
//! **There is no dispatch to save.** The usual reason to merge two operations
|
||
//! is to fuse their work. Here there is nothing to fuse: the two blurs are
|
||
//! different blurs, by definition, so a merged node costs the same four passes
|
||
//! that two nodes cost, and costs them in the same order.
|
||
//!
|
||
//! **The sidecar, the history and the reset all read better.** `clarity.amount`
|
||
//! and `texture.amount` say what they are; `local_contrast.clarity` names a
|
||
//! concept no photographer asked for in order to reach one that they did.
|
||
//! Undo says "clarity", and double-tapping clarity to reset it leaves texture
|
||
//! alone — which is what a photographer who has just tuned texture expects.
|
||
//!
|
||
//! Against all that, the cost of two nodes is one shared implementation
|
||
//! parameterised by a [`Band`], below. The `attributes:` grouping is
|
||
//! `[detail]` either way, so it offers no argument in either direction.
|
||
//!
|
||
//! # Halos, and what is done about them
|
||
//!
|
||
//! A naive unsharp mask — `c + amount * (c - blur(c))` in linear light — is
|
||
//! the single most common way this feature is got wrong, and it fails in four
|
||
//! separate ways at once. Each is addressed by a specific decision here.
|
||
//!
|
||
//! **1. Work in stops, not in levels.** The base is a Gaussian mean of *log*
|
||
//! luminance, so the detail signal is a ratio: "this pixel is 0.4 stops
|
||
//! brighter than its surroundings". In linear light the same edge produces an
|
||
//! overshoot proportional to absolute brightness, so an edge against a bright
|
||
//! sky blows out while the identical edge in shadow does nothing — and the
|
||
//! amount that looked right stops looking right the moment exposure moves.
|
||
//! Stops also make the negative direction symmetric: −50 removes exactly the
|
||
//! proportion of local contrast that +50 adds.
|
||
//!
|
||
//! **2. Soft-limit the detail signal — this is the main halo control.** The
|
||
//! signal is passed through `t * tanh(d / t)` before it is used. Below the
|
||
//! threshold the function is the identity to within a percent, so structure
|
||
//! and surface detail pass through at full strength; far above it the output
|
||
//! saturates at `t` whatever the input, so a four-stop skyline transition
|
||
//! contributes no more overshoot than a one-stop one. That is the distinction
|
||
//! between *structure* and an *edge*, drawn on amplitude rather than by an
|
||
//! edge detector — a guided or bilateral base would draw it more precisely and
|
||
//! would cost several more full-frame passes to do it. `tanh` costs one
|
||
//! instruction and has no threshold artefact, because it is smooth everywhere;
|
||
//! a hard clamp would put a visible contour along the locus where the detail
|
||
//! signal crosses `t`.
|
||
//!
|
||
//! It is also the right thing on the negative side. At amount −100 an
|
||
//! unlimited unsharp mask subtracts the whole detail signal and dissolves
|
||
//! edges into mud; limited, it removes at most `t` stops, so negative clarity
|
||
//! softens surface and modelling while leaving real edges standing.
|
||
//!
|
||
//! **3. Move luminance only, and scale the triple.** The gain is applied as
|
||
//! `c * 2^stops`, which leaves chromaticity exactly where it was. Boosting the
|
||
//! three channels independently shifts hue and saturation wherever the detail
|
||
//! signal is large — that is a *coloured* fringe along every edge, arriving
|
||
//! from a control the photographer thinks of as contrast, and it is the hardest
|
||
//! kind of halo to attribute to its cause. `apply_tone_gain` already takes this
|
||
//! position for the tonal controls, for the same reason.
|
||
//!
|
||
//! **4. Taper clarity to nothing at both ends of the range.** Clarity is
|
||
//! midtone structure by definition, and its two worst halos are at the
|
||
//! extremes: a bright sky beside a dark subject blooms, and deep shadow goes
|
||
//! to mud. A weight of `1 - (2p - 1)^2` over the perceptual tone position
|
||
//! removes exactly those, and stops a *contrast* slider from creating a blown
|
||
//! highlight by pushing a recovered value back over one.
|
||
//!
|
||
//! Texture deliberately does **not** get this taper. Skin in a highlight and
|
||
//! fabric in a shadow are precisely what the control is for, and a fine-scale
|
||
//! overshoot at either end is a two-pixel band, not a bloom.
|
||
//!
|
||
//! # Why the radius is a fraction of the frame
|
||
//!
|
||
//! [`RenderScale`] names two units, and picking the wrong one produces an
|
||
//! effect that is a different photograph on screen and in the file. These two
|
||
//! controls take [`RenderScale::frame_fraction`] — the unit a mask feather is
|
||
//! already stored in — and not [`RenderScale::source_pixels`].
|
||
//!
|
||
//! The test is whose property the length is. Capture sharpening's radius
|
||
//! belongs to the *sensor*: it is about the lens's circle of confusion and the
|
||
//! demosaic's interpolation, both of which are facts about the file and
|
||
//! neither of which changes if the photograph is cropped. Clarity's radius
|
||
//! belongs to the *composition*: "separate the subject from its background" is
|
||
//! a statement about how much of the frame the subject occupies, and it stays
|
||
//! true when the same frame is printed large or viewed small. Crop into a
|
||
//! quarter of the frame and the subject now fills it, so the scale that models
|
||
//! it really has grown — which `frame_fraction` gives, because
|
||
//! [`crate::EditGraph::render_scale`] folds the crop in before this code runs.
|
||
//!
|
||
//! The practical consequence is that these two controls preview honestly at
|
||
//! every zoom level, which the acutance family cannot. There is no
|
||
//! [`RenderScale::resolves`] check here and no reason for one: at a small
|
||
//! render the kernel shrinks with the frame and keeps its proportions, and the
|
||
//! effect is the effect.
|
||
//!
|
||
//! Texture does eventually round to a zero-pixel kernel on a thumbnail, and
|
||
//! then contributes no pass at all. That is not the acutance family's problem
|
||
//! restated — it is the honest answer. A two-pixel surface structure is not
|
||
//! present in a 300-pixel rendering of the frame in the first place, and it
|
||
//! reappears, exactly, as soon as the view is zoomed.
|
||
//!
|
||
//! # What this costs
|
||
//!
|
||
//! Clarity's kernel is large — of the order of a hundred taps per pass at
|
||
//! preview resolution — and the two passes are the honest, exact separable
|
||
//! Gaussian rather than a sparse approximation of one. A strided kernel would
|
||
//! be several times cheaper and is deliberately not taken: undersampling an
|
||
//! image that is not band-limited aliases high-frequency content down into the
|
||
//! base, the base is then subtracted, and the aliasing arrives in the output as
|
||
//! low-frequency mottling across smooth gradients. Mottled skies are precisely
|
||
//! the artefact this control must not have. The right optimisation is a base
|
||
//! computed at reduced resolution, which needs a detail stage that can write a
|
||
//! smaller target than it reads; that is a change to [`crate::detail`], not to
|
||
//! this file.
|
||
|
||
use std::marker::PhantomData;
|
||
|
||
use crate::descriptor::{Attribute, LocalizedKey, OpDescriptor, OpId, ParamDescriptor, ParamId};
|
||
use crate::detail::{DetailPass, DetailStage, RenderScale};
|
||
use crate::operation::{Affects, Helper, Operation, Uniform};
|
||
use crate::ops::helpers;
|
||
|
||
pub const CLARITY: OpId = OpId("clarity");
|
||
pub const TEXTURE: OpId = OpId("texture");
|
||
|
||
/// The one parameter each control has. Both are called `amount`, so the
|
||
/// sidecar keys read `clarity.amount` and `texture.amount`.
|
||
pub const AMOUNT: ParamId = ParamId("amount");
|
||
|
||
/// How far the kernel runs, in standard deviations.
|
||
///
|
||
/// Two, not three. A Gaussian truncated at 2σ and renormalised keeps 95.4% of
|
||
/// its mass and is still a perfectly monotone low-pass; the missing tail
|
||
/// changes the base by less than the difference between two adjacent settings
|
||
/// of the slider, and it halves the tap count of the widest pass in the
|
||
/// pipeline.
|
||
const TRUNCATION: f32 = 2.0;
|
||
|
||
/// Everything that makes one of these two controls the control it is.
|
||
///
|
||
/// A struct rather than four associated constants so that the differences
|
||
/// between clarity and texture can be read side by side, which is the one
|
||
/// thing a reader comes to this file to do.
|
||
pub struct Recipe {
|
||
descriptor: &'static OpDescriptor,
|
||
helpers: &'static [Helper],
|
||
/// The Gaussian's σ, as a fraction of the frame's shorter edge.
|
||
sigma: f32,
|
||
/// Where the soft limit starts to bite, in stops. See the module
|
||
/// documentation, halo control (2).
|
||
threshold: f32,
|
||
/// Stops of local contrast added at full slider travel.
|
||
gain: f32,
|
||
/// Whether the effect is tapered away from the midtones. See halo control
|
||
/// (4) — true for clarity, false for texture, and that asymmetry is
|
||
/// deliberate.
|
||
midtone_taper: bool,
|
||
}
|
||
|
||
/// The band of spatial frequencies a control acts on.
|
||
///
|
||
/// The type parameter of [`LocalContrast`], because the scale is the *only*
|
||
/// thing that differs between clarity and texture and it differs at compile
|
||
/// time. One implementation, two nodes, and no branch anywhere that could
|
||
/// drift.
|
||
pub trait Band: Send + Sync + 'static {
|
||
const RECIPE: Recipe;
|
||
}
|
||
|
||
/// Clarity's band: roughly a hundredth of the frame.
|
||
pub struct Coarse;
|
||
|
||
/// Texture's band: a decade finer, a few pixels at any size.
|
||
pub struct Fine;
|
||
|
||
impl Band for Coarse {
|
||
const RECIPE: Recipe = Recipe {
|
||
descriptor: &CLARITY_DESCRIPTOR,
|
||
helpers: CLARITY_HELPERS,
|
||
// 1.2% of the shorter edge — about 48 px on a 4000 px frame. Wide
|
||
// enough that the base is the subject rather than the surface, narrow
|
||
// enough that the result is still local contrast and not a second
|
||
// exposure slider.
|
||
sigma: 0.012,
|
||
// A third of a stop. Clarity's whole difficulty is that a wide kernel
|
||
// sees an enormous detail signal at every real edge, so the limit has
|
||
// to bite early: at full travel the largest overshoot any edge can
|
||
// produce is a third of a stop, about 26%, before the midtone taper
|
||
// reduces it further.
|
||
threshold: 0.35,
|
||
gain: 1.0,
|
||
midtone_taper: true,
|
||
};
|
||
}
|
||
|
||
impl Band for Fine {
|
||
const RECIPE: Recipe = Recipe {
|
||
descriptor: &TEXTURE_DESCRIPTOR,
|
||
helpers: TEXTURE_HELPERS,
|
||
// Exactly a decade below clarity, which is what makes the two controls
|
||
// separable in use: at a ten-to-one ratio of scales, neither can
|
||
// substantially do the other's job, so a photographer setting both is
|
||
// setting two things and not the same thing twice.
|
||
sigma: 0.0012,
|
||
// Three times clarity's, because at this scale the overshoot is a band
|
||
// two or three pixels wide and the eye reads that as acutance. Limiting
|
||
// it as hard as clarity would take the crispness out of the one control
|
||
// that exists to provide it.
|
||
threshold: 1.0,
|
||
// A narrow overshoot carries less visual weight than a wide one, so
|
||
// equal numbers on the two sliders should land at comparable strength.
|
||
gain: 1.25,
|
||
midtone_taper: false,
|
||
};
|
||
}
|
||
|
||
static CLARITY_DESCRIPTOR: OpDescriptor = OpDescriptor {
|
||
id: CLARITY,
|
||
label: LocalizedKey("op.clarity"),
|
||
params: &[ParamDescriptor::amount("amount", "param.clarity.amount")],
|
||
attributes: &[Attribute::Detail],
|
||
};
|
||
|
||
static TEXTURE_DESCRIPTOR: OpDescriptor = OpDescriptor {
|
||
id: TEXTURE,
|
||
label: LocalizedKey("op.texture"),
|
||
params: &[ParamDescriptor::amount("amount", "param.texture.amount")],
|
||
attributes: &[Attribute::Detail],
|
||
};
|
||
|
||
/// Luminance as a position on a logarithmic scale, floored.
|
||
///
|
||
/// Declared here rather than in `_helpers.yaml` because it is not a shared
|
||
/// idea: it exists so that the base can be a mean of *log* luminance, which is
|
||
/// the first of this file's four halo decisions and means nothing outside it.
|
||
const LOG_LUMA: Helper = Helper {
|
||
name: "log_luma",
|
||
source: "\
|
||
// Luminance in stops, floored fourteen stops below white.
|
||
//
|
||
// The floor is what makes the logarithm safe on the values this stage
|
||
// actually receives: the intermediate is unclipped and scene-referred, so a
|
||
// pixel can be exactly zero and an out-of-gamut colour can be negative. It
|
||
// sits far enough down that no real signal is affected — a fourteen-stop
|
||
// range is more than any sensor delivers — and it turns both of those into a
|
||
// very dark pixel rather than an infinity that would propagate through the
|
||
// blur into every pixel within the kernel's reach.
|
||
fn log_luma(c: vec3<f32>) -> f32 {
|
||
return log2(max(luminance(c), 0.00006103515625));
|
||
}",
|
||
};
|
||
|
||
/// How much of clarity applies at a given luminance.
|
||
const MIDTONE_WEIGHT: Helper = Helper {
|
||
name: "midtone_weight",
|
||
source: "\
|
||
// A parabola over the perceptual tone position: one in the midtones, zero at
|
||
// both black and white.
|
||
//
|
||
// Clarity is midtone structure by definition, and this is also where two of
|
||
// its three worst halos live — a bright sky beside a dark subject blooms, and
|
||
// deep shadow turns to mud. Tapering to nothing at both ends removes them, and
|
||
// stops a control the photographer reads as `contrast` from pushing a
|
||
// recovered highlight back over one and clipping it.
|
||
//
|
||
// `tone_position` rather than the raw value, so the taper is even to the eye
|
||
// rather than crowded into the bottom of the range the way a linear weight
|
||
// would be.
|
||
fn midtone_weight(luma: f32) -> f32 {
|
||
let p = 2.0 * tone_position(luma) - 1.0;
|
||
return 1.0 - p * p;
|
||
}",
|
||
};
|
||
|
||
static CLARITY_HELPERS: &[Helper] = &[
|
||
helpers::LUMINANCE,
|
||
LOG_LUMA,
|
||
helpers::TONE_POSITION,
|
||
MIDTONE_WEIGHT,
|
||
];
|
||
|
||
static TEXTURE_HELPERS: &[Helper] = &[helpers::LUMINANCE, LOG_LUMA];
|
||
|
||
/// An unsharp mask at one fixed scale.
|
||
///
|
||
/// See the module documentation for why the scale is a type parameter rather
|
||
/// than a parameter, and why there are two nodes rather than one.
|
||
pub struct LocalContrast<B: Band> {
|
||
/// −100…100, exactly as the slider reports it.
|
||
amount: f32,
|
||
band: PhantomData<B>,
|
||
}
|
||
|
||
/// Clarity: local contrast at roughly a hundredth of the frame.
|
||
pub type Clarity = LocalContrast<Coarse>;
|
||
|
||
/// Texture: local contrast a decade finer than clarity.
|
||
pub type Texture = LocalContrast<Fine>;
|
||
|
||
impl<B: Band> Default for LocalContrast<B> {
|
||
fn default() -> Self {
|
||
Self {
|
||
amount: 0.0,
|
||
band: PhantomData,
|
||
}
|
||
}
|
||
}
|
||
|
||
impl<B: Band> LocalContrast<B> {
|
||
pub fn new() -> Self {
|
||
Self::default()
|
||
}
|
||
|
||
/// Start from a slider position, for tests and presets.
|
||
pub fn with_amount(amount: f32) -> Self {
|
||
Self {
|
||
amount,
|
||
band: PhantomData,
|
||
}
|
||
}
|
||
|
||
/// The Gaussian's σ at this render, in **render pixels**.
|
||
///
|
||
/// The one conversion this operation performs, and the reason it happens
|
||
/// here rather than in WGSL: `frame_fraction` is named after its unit,
|
||
/// where a bare `f32` in a shader would not be.
|
||
pub fn sigma(&self, scale: RenderScale) -> f32 {
|
||
scale.frame_fraction(B::RECIPE.sigma)
|
||
}
|
||
|
||
/// The kernel radius at this render, in render pixels.
|
||
///
|
||
/// Exposed so a test can state what it expects without repeating the
|
||
/// rounding rule — a test that recomputed it would agree with a bug.
|
||
pub fn kernel(&self, scale: RenderScale) -> u32 {
|
||
(self.sigma(scale) * TRUNCATION).round().max(0.0) as u32
|
||
}
|
||
|
||
/// Stops of local contrast at this slider position.
|
||
fn gain(&self) -> f32 {
|
||
self.amount / 100.0 * B::RECIPE.gain
|
||
}
|
||
|
||
/// The largest excursion this control can produce at its current setting,
|
||
/// in stops — the bound the soft limit guarantees.
|
||
///
|
||
/// `gain * threshold`, because `t * tanh(d / t)` saturates at `t` however
|
||
/// violent the edge. Public because it is the one number a test can hold
|
||
/// the halo to without re-deriving the shader: whatever the picture, no
|
||
/// pixel may move further than this. See the module documentation, halo
|
||
/// control (2).
|
||
pub fn overshoot_bound(&self) -> f32 {
|
||
self.gain().abs() * B::RECIPE.threshold
|
||
}
|
||
}
|
||
|
||
impl<B: Band> Operation for LocalContrast<B> {
|
||
fn descriptor(&self) -> &'static OpDescriptor {
|
||
B::RECIPE.descriptor
|
||
}
|
||
|
||
fn set_param(&mut self, _id: ParamId, value: f32) {
|
||
self.amount = value;
|
||
}
|
||
|
||
fn param(&self, _id: ParamId) -> f32 {
|
||
self.amount
|
||
}
|
||
|
||
fn is_active(&self) -> bool {
|
||
self.amount != 0.0
|
||
}
|
||
|
||
/// Never called: a neighbourhood operation contributes no fused fragment,
|
||
/// and `compose_full` filters it out before asking.
|
||
fn wgsl_body(&self) -> String {
|
||
String::new()
|
||
}
|
||
|
||
fn uniforms(&self) -> Vec<Uniform> {
|
||
Vec::new()
|
||
}
|
||
|
||
fn affects(&self) -> Affects {
|
||
Affects::Detail
|
||
}
|
||
|
||
fn detail(&self) -> Option<&dyn DetailStage> {
|
||
Some(self)
|
||
}
|
||
|
||
fn helpers(&self) -> &'static [Helper] {
|
||
B::RECIPE.helpers
|
||
}
|
||
}
|
||
|
||
impl<B: Band> DetailStage for LocalContrast<B> {
|
||
fn passes(&self, scale: RenderScale) -> Vec<DetailPass> {
|
||
let sigma = self.sigma(scale);
|
||
let radius = self.kernel(scale);
|
||
|
||
// A kernel that rounded to nothing is not "blur by zero" — it is a
|
||
// scale this render is too small to show. Texture reaches this on a
|
||
// thumbnail and the honest answer is to contribute no pass, which is
|
||
// also what stops a degenerate one-tap Gaussian from burning two
|
||
// dispatches to copy the image.
|
||
if radius == 0 {
|
||
return Vec::new();
|
||
}
|
||
|
||
// 1/σ², so the shader's inner loop is a multiply rather than a
|
||
// division per tap.
|
||
let inv_variance = 1.0 / (sigma * sigma);
|
||
let shape = vec![
|
||
Uniform {
|
||
name: "radius",
|
||
value: radius as f32,
|
||
},
|
||
Uniform {
|
||
name: "inv_variance",
|
||
value: inv_variance,
|
||
},
|
||
];
|
||
|
||
let mut combine = shape.clone();
|
||
combine.push(Uniform {
|
||
name: "threshold",
|
||
value: B::RECIPE.threshold,
|
||
});
|
||
combine.push(Uniform {
|
||
name: "gain",
|
||
value: self.gain(),
|
||
});
|
||
|
||
vec![
|
||
DetailPass {
|
||
label: "base",
|
||
radius,
|
||
uniforms: shape,
|
||
wgsl: BASE_X.to_string(),
|
||
},
|
||
DetailPass {
|
||
label: "combine",
|
||
radius,
|
||
uniforms: combine,
|
||
wgsl: combine_body(B::RECIPE.midtone_taper),
|
||
},
|
||
]
|
||
}
|
||
}
|
||
|
||
/// Half of the base, along x.
|
||
///
|
||
/// Deliberately does not touch `c`: the pass after this one needs the
|
||
/// *original* colour as well as the blur, which is what an unsharp mask is and
|
||
/// why the `aux` lane exists at all.
|
||
const BASE_X: &str = "\
|
||
// Half of a separable Gaussian, over log luminance, along x.
|
||
//
|
||
// The colour is left exactly as it arrived. An unsharp mask needs the blur and
|
||
// the original in the same place at the same time, and the ping-pong hands
|
||
// each pass only what the pass before it wrote — so the blur travels in `aux`
|
||
// and the colour rides through untouched. See `DetailPass::wgsl`.
|
||
//
|
||
// Weights are evaluated rather than tabulated: a table would need a uniform
|
||
// array sized for the largest kernel any resolution could ask for, and `exp`
|
||
// is cheaper than the bandwidth that array would cost.
|
||
let r = i32(radius);
|
||
var sum = 0.0;
|
||
var weight = 0.0;
|
||
for (var i = -r; i <= r; i = i + 1) {
|
||
let f = f32(i);
|
||
let w = exp(-0.5 * f * f * inv_variance);
|
||
sum = sum + w * log_luma(tap(coord, vec2<i32>(i, 0)));
|
||
weight = weight + w;
|
||
}
|
||
// Normalised by the weights actually summed, not by an analytic constant, so
|
||
// truncating the Gaussian at 2σ leaves a true mean rather than a slightly dark
|
||
// one — and so a kernel clamped at the image border averages the pixels that
|
||
// exist.
|
||
aux = sum / weight;";
|
||
|
||
/// The second pass: finish the base along y, then apply the mask.
|
||
///
|
||
/// Generated rather than constant because the midtone taper is present for
|
||
/// clarity and absent for texture. Emitting the line only where it applies
|
||
/// keeps texture's shader honest about not having one, and saves it a uniform
|
||
/// and two helper functions it would never call.
|
||
fn combine_body(midtone_taper: bool) -> String {
|
||
let weight = if midtone_taper {
|
||
"\n\
|
||
// Clarity only: tapered to nothing at both ends of the range. See\n\
|
||
// `midtone_weight` for what that is worth against a halo.\n\
|
||
let stops = gain * shaped * midtone_weight(luminance(c));"
|
||
} else {
|
||
"\n\
|
||
// Texture is deliberately *not* tapered towards black and white.\n\
|
||
// Skin in a highlight and fabric in a shadow are what the control is\n\
|
||
// for, and at this scale an overshoot is two pixels wide — acutance,\n\
|
||
// not a bloom.\n\
|
||
let stops = gain * shaped;"
|
||
};
|
||
|
||
format!(
|
||
"\
|
||
// The other half of the base, then the unsharp mask itself.
|
||
//
|
||
// `tap_aux` reads the previous pass's log-luminance blur, while `c` is still
|
||
// the colour the colour pass produced — which is the arrangement that makes an
|
||
// unsharp mask expressible in a chain that hands on one texture per pass.
|
||
let r = i32(radius);
|
||
var sum = 0.0;
|
||
var weight = 0.0;
|
||
for (var i = -r; i <= r; i = i + 1) {{
|
||
let f = f32(i);
|
||
let w = exp(-0.5 * f * f * inv_variance);
|
||
sum = sum + w * tap_aux(coord, vec2<i32>(0, i));
|
||
weight = weight + w;
|
||
}}
|
||
let base = sum / weight;
|
||
|
||
// Local contrast, in **stops**. Both terms are logarithms, so this is a ratio:
|
||
// `detail` says how much brighter this pixel is than its surroundings, and
|
||
// says it in a unit that means the same thing in a highlight and in a shadow.
|
||
// The linear-light difference an unsharp mask usually takes does not, which is
|
||
// why it blows out bright edges and does nothing to dark ones.
|
||
let detail = log_luma(c) - base;
|
||
|
||
// The halo control. Below the threshold `tanh` is the identity to within a
|
||
// percent, so structure and surface pass through at full strength; far above
|
||
// it the output saturates at the threshold, so a four-stop edge contributes no
|
||
// more overshoot than a one-stop one. Smooth everywhere, so unlike a clamp it
|
||
// leaves no contour along the locus where the detail signal crosses it.
|
||
let shaped = threshold * tanh(detail / threshold);
|
||
{weight}
|
||
|
||
// Applied as a scale on the whole triple, which leaves chromaticity exactly
|
||
// where it was. Boosting the channels independently would put a *coloured*
|
||
// fringe along every edge, arriving from a control the photographer reads as
|
||
// contrast — the hardest kind of halo to attribute to its cause.
|
||
c = c * exp2(stops);"
|
||
)
|
||
}
|
||
|
||
#[cfg(test)]
|
||
mod tests {
|
||
use super::*;
|
||
use crate::detail::compose_detail;
|
||
use dr_types::ColourSpace;
|
||
|
||
/// The two controls, as the graph would hold them.
|
||
fn ops(clarity: f32, texture: f32) -> Vec<Box<dyn Operation>> {
|
||
vec![
|
||
Box::new(Clarity::with_amount(clarity)),
|
||
Box::new(Texture::with_amount(texture)),
|
||
]
|
||
}
|
||
|
||
fn composed(clarity: f32, texture: f32, scale: RenderScale) -> crate::ComposedDetail {
|
||
compose_detail(&ops(clarity, texture), scale, ColourSpace::Srgb)
|
||
}
|
||
|
||
#[test]
|
||
fn both_controls_start_neutral_and_cost_nothing() {
|
||
// The rule the whole pipeline rests on. An unedited photograph must
|
||
// not pay for a clarity slider nobody has touched — and, because these
|
||
// are the widest kernels in the pipeline, "nothing" here is a large
|
||
// amount of nothing.
|
||
assert!(!Clarity::new().is_active());
|
||
assert!(!Texture::new().is_active());
|
||
assert!(composed(0.0, 0.0, RenderScale::full((2000, 1500))).is_empty());
|
||
}
|
||
|
||
#[test]
|
||
fn one_control_moving_does_not_dispatch_the_other() {
|
||
// The concrete reason these are two nodes rather than one with two
|
||
// sliders. Merged, the node would be active whenever either had moved
|
||
// and would need a hand-written guard per half to avoid running a
|
||
// forty-pixel blur for a control sitting at zero.
|
||
let scale = RenderScale::full((2000, 1500));
|
||
let only_clarity = composed(50.0, 0.0, scale);
|
||
assert_eq!(only_clarity.len(), 2, "one operation, two passes");
|
||
assert!(only_clarity.passes.iter().all(|p| p.label.starts_with("clarity/")));
|
||
|
||
let both = composed(50.0, 50.0, scale);
|
||
assert_eq!(both.len(), 4);
|
||
}
|
||
|
||
#[test]
|
||
fn the_two_controls_differ_by_a_decade_of_scale() {
|
||
// The whole point of there being two of them. If these ever converge,
|
||
// one of the controls has stopped doing its job and the second slider
|
||
// has become a duplicate of the first.
|
||
let scale = RenderScale::full((4000, 3000));
|
||
let clarity = Clarity::with_amount(100.0).kernel(scale);
|
||
let texture = Texture::with_amount(100.0).kernel(scale);
|
||
// Both derived rather than observed, because a number copied out of a
|
||
// test run agrees with whatever the code did on the day.
|
||
//
|
||
// `frame_fraction` takes the *shorter* edge: min(4000, 3000) = 3000.
|
||
// clarity σ = 0.012 × 3000 = 36.0 → round(36.0 × 2) = 72
|
||
// texture σ = 0.0012 × 3000 = 3.6 → round( 3.6 × 2) = 7
|
||
//
|
||
// (7.2 rounds down, which is why texture is 7 and not 8 — the
|
||
// truncation is two sigmas, and two sigmas of 3.6 px is 7.2 px.)
|
||
assert_eq!(clarity, 72);
|
||
assert_eq!(texture, 7, "a decade finer");
|
||
assert!(
|
||
clarity >= texture * 8,
|
||
"clarity {clarity} and texture {texture} are not separable scales"
|
||
);
|
||
}
|
||
|
||
#[test]
|
||
fn a_radius_is_a_fraction_of_the_frame_and_not_a_count_of_source_pixels() {
|
||
// TRACES: FR-DSP-1 — the decision this whole file's units rest on.
|
||
//
|
||
// Clarity is compositional: "separate the subject from its background"
|
||
// is a statement about how much of the frame the subject occupies, and
|
||
// it stays true at every size the frame is rendered at. So the kernel
|
||
// must cover the same *proportion* of the picture on a proxy as in the
|
||
// export, which is what `frame_fraction` gives and what
|
||
// `source_pixels` would not.
|
||
// The declared proportion is σ × 2 = 0.012 × 2 = 0.024 of the shorter
|
||
// edge, and the tolerance is what rounding to a whole pixel costs:
|
||
//
|
||
// 300 → round(0.024 × 300) = 7 → 7/300 = 0.02333 (−0.00067)
|
||
// 1500 → round(0.024 × 1500) = 36 → 36/1500 = 0.02400 ( 0.00000)
|
||
// 4500 → round(0.024 × 4500) = 108 → 108/4500 = 0.02400 ( 0.00000)
|
||
//
|
||
// Half a pixel over the smallest frame here is 0.5/300 = 0.0017, so
|
||
// 0.002 is the tolerance a rounded kernel can actually hold — and it
|
||
// is a bound, not a fitted number.
|
||
let sizes = [(400u32, 300u32), (2000, 1500), (6000, 4500)];
|
||
let proportions: Vec<f32> = sizes
|
||
.iter()
|
||
.map(|&(w, h)| {
|
||
let scale = RenderScale::full((w, h));
|
||
Clarity::with_amount(60.0).kernel(scale) as f32 / w.min(h) as f32
|
||
})
|
||
.collect();
|
||
for p in &proportions {
|
||
assert!(
|
||
(p - 0.024).abs() < 0.002,
|
||
"the kernel drifted from its declared fraction: {proportions:?}"
|
||
);
|
||
}
|
||
|
||
// And the contrast with the other unit, stated rather than implied: on
|
||
// a one-third proxy a source-pixel radius *shrinks* to a third of the
|
||
// proportion it had, which is the bug this choice avoids.
|
||
//
|
||
// ratio = (2000/6000 + 1500/4500) / 2 = 1/3
|
||
// frame_fraction(0.012) → 0.012 × 1500 = 18 px, the same 18 px the
|
||
// export of that framing gets, because the
|
||
// unit is a proportion of what is rendered;
|
||
// source_pixels(96) → 96 × 1/3 = 32 px, a third of the reach
|
||
// the same edit had at full size.
|
||
//
|
||
// 96 is clarity's kernel at 4000 px of shorter edge, so the second line
|
||
// is what this control would have done had it been written in the
|
||
// acutance family's unit.
|
||
let proxy = RenderScale::new((2000, 1500), (6000, 4500));
|
||
let clarity = Clarity::with_amount(60.0);
|
||
assert_eq!(clarity.kernel(proxy), clarity.kernel(RenderScale::full((2000, 1500))));
|
||
assert!(
|
||
proxy.source_pixels(96.0) < 40.0,
|
||
"the same length in the other unit would have collapsed"
|
||
);
|
||
}
|
||
|
||
#[test]
|
||
fn texture_stops_rather_than_lying_when_the_render_is_too_small() {
|
||
// A two-pixel surface structure is not present in a 300-pixel
|
||
// rendering of the frame, so the honest thing is to contribute no
|
||
// pass. Unlike the acutance family this is not an approximation being
|
||
// hidden: zoom in and the kernel comes back, exactly.
|
||
//
|
||
// shorter edge = 120
|
||
// texture σ = 0.0012 × 120 = 0.144 → round(0.288) = 0 — no pass
|
||
// clarity σ = 0.012 × 120 = 1.44 → round(2.88) = 3 — two passes
|
||
//
|
||
// Texture's kernel crosses back above zero at round(0.0024 × e) ≥ 1,
|
||
// i.e. a shorter edge of about 209 px, which is a little larger than a
|
||
// contact sheet thumbnail and a great deal smaller than any view a
|
||
// photographer judges surface detail in.
|
||
let thumbnail = RenderScale::full((160, 120));
|
||
assert_eq!(Texture::with_amount(100.0).kernel(thumbnail), 0);
|
||
assert!(Texture::with_amount(100.0).passes(thumbnail).is_empty());
|
||
|
||
// Clarity is a hundred times wider and survives, which is what a
|
||
// thumbnail should show: the modelling, not the surface.
|
||
assert!(Clarity::with_amount(100.0).kernel(thumbnail) > 0);
|
||
assert_eq!(Clarity::with_amount(100.0).passes(thumbnail).len(), 2);
|
||
}
|
||
|
||
#[test]
|
||
fn the_first_pass_hands_the_original_colour_to_the_second() {
|
||
// The property that makes an unsharp mask expressible in a chain that
|
||
// passes on one texture per pass. If the blur pass ever writes `c`,
|
||
// the combining pass has nothing to subtract the base *from* and the
|
||
// operation silently becomes a blur.
|
||
let passes = Clarity::with_amount(50.0).passes(RenderScale::full((2000, 1500)));
|
||
let base = &passes[0];
|
||
let combine = &passes[1];
|
||
|
||
assert!(base.wgsl.contains("aux = sum / weight;"));
|
||
assert!(
|
||
!base.wgsl.contains("c = "),
|
||
"the blur pass must leave the colour alone: {}",
|
||
base.wgsl
|
||
);
|
||
assert!(
|
||
combine.wgsl.contains("tap_aux("),
|
||
"the combining pass must read the blur out of the scratch lane"
|
||
);
|
||
assert!(combine.wgsl.contains("log_luma(c) - base"));
|
||
}
|
||
|
||
#[test]
|
||
fn the_declared_radius_is_the_halo_a_tile_would_need() {
|
||
// ARCH §5.3 grows a tile by the widest reach of the pass computing it,
|
||
// and nothing can infer that from the WGSL because the offsets come
|
||
// from a uniform. An understated radius shows as a seam at every tile
|
||
// boundary — an artefact that reads as a driver bug.
|
||
//
|
||
// shorter edge = 1500
|
||
// clarity → round(0.024 × 1500) = 36 px
|
||
// texture → round(0.0024 × 1500) = 4 px
|
||
//
|
||
// so the halo the four passes together need is clarity's 36, taken as
|
||
// the maximum rather than the sum: the passes are separate dispatches,
|
||
// and a tile is grown for whichever of them reaches furthest.
|
||
let scale = RenderScale::full((2000, 1500));
|
||
let composed = composed(50.0, 50.0, scale);
|
||
let clarity = Clarity::with_amount(50.0).kernel(scale);
|
||
assert_eq!(composed.radius(), clarity, "the widest pass sets the halo");
|
||
for pass in &composed.passes {
|
||
assert!(pass.radius > 0, "{} declared no reach", pass.label);
|
||
}
|
||
}
|
||
|
||
#[test]
|
||
fn the_halo_limit_is_in_the_shader_and_bounds_the_overshoot() {
|
||
// The single most common way this feature is got wrong. `tanh`
|
||
// saturates at the threshold, so the largest overshoot a full-travel
|
||
// slider can produce is `gain * threshold` stops however violent the
|
||
// edge — a bound that holds by construction rather than by tuning.
|
||
let combine = &Clarity::with_amount(100.0).passes(RenderScale::full((2000, 1500)))[1];
|
||
assert!(combine.wgsl.contains("threshold * tanh(detail / threshold)"));
|
||
|
||
let bound = |u: &[Uniform]| {
|
||
let get = |n| u.iter().find(|x| x.name == n).unwrap().value;
|
||
get("gain").abs() * get("threshold")
|
||
};
|
||
// A third of a stop for clarity, before the midtone taper takes more
|
||
// off; a little over a stop for texture, whose overshoot is two pixels
|
||
// wide and reads as acutance.
|
||
//
|
||
// clarity gain = 100/100 × 1.00 = 1.00 ; × 0.35 = 0.35 stops (26%)
|
||
// texture gain = 100/100 × 1.25 = 1.25 ; × 1.00 = 1.25 stops
|
||
//
|
||
// Both at full travel, which is what makes them a bound and not a
|
||
// measurement: no picture, and no edge in any picture, can produce more.
|
||
assert!((bound(&combine.uniforms) - 0.35).abs() < 1e-6);
|
||
let texture = &Texture::with_amount(100.0).passes(RenderScale::full((2000, 1500)))[1];
|
||
assert!((bound(&texture.uniforms) - 1.25).abs() < 1e-6);
|
||
}
|
||
|
||
#[test]
|
||
fn only_clarity_tapers_towards_black_and_white() {
|
||
// The asymmetry is the deliberate part: texture must work on skin in a
|
||
// highlight and fabric in a shadow, which is exactly where clarity
|
||
// must not.
|
||
let scale = RenderScale::full((2000, 1500));
|
||
let clarity = &Clarity::with_amount(50.0).passes(scale)[1];
|
||
let texture = &Texture::with_amount(50.0).passes(scale)[1];
|
||
assert!(clarity.wgsl.contains("midtone_weight(luminance(c))"));
|
||
assert!(!texture.wgsl.contains("midtone_weight"));
|
||
|
||
// And texture does not carry the helpers it would need for one, so its
|
||
// shader says what it does rather than merely not calling it.
|
||
assert!(Texture::new().helpers().iter().any(|h| h.name == "log_luma"));
|
||
assert!(!Texture::new()
|
||
.helpers()
|
||
.iter()
|
||
.any(|h| h.name == "midtone_weight"));
|
||
assert!(Clarity::new()
|
||
.helpers()
|
||
.iter()
|
||
.any(|h| h.name == "midtone_weight"));
|
||
}
|
||
|
||
#[test]
|
||
fn the_amount_is_symmetric_about_neutral() {
|
||
// Working in stops is what buys this: −50 removes exactly the
|
||
// proportion of local contrast that +50 adds, at every brightness.
|
||
// In linear light it would not, and the pair of settings that looked
|
||
// balanced would depend on exposure.
|
||
let scale = RenderScale::full((2000, 1500));
|
||
let up = Clarity::with_amount(50.0).passes(scale);
|
||
let down = Clarity::with_amount(-50.0).passes(scale);
|
||
let gain = |p: &[DetailPass]| {
|
||
p[1].uniforms
|
||
.iter()
|
||
.find(|u| u.name == "gain")
|
||
.unwrap()
|
||
.value
|
||
};
|
||
assert!((gain(&up) + gain(&down)).abs() < 1e-6);
|
||
// Same kernel either way — the direction is a sign, not a scale.
|
||
assert_eq!(up[0].radius, down[0].radius);
|
||
}
|
||
|
||
#[test]
|
||
fn every_pass_declares_a_uniform_block_the_gpu_will_accept() {
|
||
// A uniform struct whose size is not a multiple of 16 is rejected
|
||
// outright by the WGSL uniform address space rules, and arrives as a
|
||
// compilation failure against generated source.
|
||
for pass in composed(70.0, -40.0, RenderScale::full((1600, 1200))).passes {
|
||
assert_eq!(pass.uniforms.len() % 4, 0, "{}", pass.label);
|
||
assert!(
|
||
pass.uniforms.iter().all(|v| v.is_finite()),
|
||
"{} uploaded a non-finite uniform",
|
||
pass.label
|
||
);
|
||
}
|
||
}
|
||
|
||
#[test]
|
||
fn the_parameter_round_trips_under_its_own_id() {
|
||
// Mechanical, and exactly why it is worth checking: a `set_param` that
|
||
// read the wrong field would look perfect and silently break the
|
||
// sidecar.
|
||
let mut op = Clarity::new();
|
||
op.set_param(AMOUNT, -37.0);
|
||
assert_eq!(op.param(AMOUNT), -37.0);
|
||
assert_eq!(op.descriptor().id, CLARITY);
|
||
assert_eq!(Texture::new().descriptor().id, TEXTURE);
|
||
}
|
||
}
|