dtourolle
89c4ff1820
A subject or category layer was written to the sidecar as identity alone —
which run, which instance, which category — on the reasoning that the pixels
are reproducible by running the same model over the same image. They are, but
only by *running the model*, and nothing runs one except a photographer
pressing "find subjects". So on every path that did not already have a run in
memory the layer resolved to no coverage, `MaskPass::render` logged "has no
distance field; skipping", and the adjustment was silently absent:
- reopening an edited photograph rendered it without its local adjustments,
and then saved that state back on the way out;
- a batch export from the grid could not have them at any point, because
`render_from_library` opens a session, applies a version and renders, and
there is no model anywhere on that path. Three hundred files written
without the edits their photographer made, over a log warning.
Neither failure announced itself. The generated shader still emits the layer's
block and the empty placeholder multiplies it by zero, so the result is a
well-formed frame that is simply missing an edit — `mask_is_stale` already
named the state and called it "not stale, just unrenderable".
The coverage now travels in the file, as one `coverage = w h levels payload`
line at the end of the layer's block.
Two levels, and that is not a compromise. The model hands out a byte per pixel
but `Shaped::build` measures its distance field from `coverage >= 128` and
throws the shoulder away on the first line; everything soft about the rendered
edge comes afterwards from the layer's feather and falloff, which are read off
the distance. So one bit per pixel is not an approximation of what the model
said — it is exactly the part of it that reaches a pixel, and the stored mask
renders the identical frame. Storing all 256 levels would have stored 1.7 MB
of bilinear interpolation to reconstruct a predicate, and would not even have
compressed: a model mask is a bilinear upsample of a coarse grid, so almost no
two adjacent bytes are alike. Measured on a simulated sky and a simulated
figure at 1600x1067, against 1.71 MB raw: 4.0 kB and 6.5 kB at two levels,
46 kB and 76 kB at sixteen, 835 kB and 1.43 MB at all 256. The level count is
still written into the line, so a later build that finds a use for the
shoulder can write sixteen and this one will read them rather than misreading
a stream of lengths as pairs.
The coder is hand-rolled — run-length pairs in a base-64 varint — because
`dr-pipeline` links nothing, which is the property that lets the descriptor
and codegen logic be tested without a device. `flate2` would have been fewer
lines and a dependency in the one crate that has none.
Where it lives matters more than how it is coded. The raster sits on
`MaskLayer` beside the source, not inside `MaskSource::Subject`: the source is
*identity*, which is what makes it diff as a handful of numbers and merge per
field under FR-NC-9, and a raster in there would have given the merge a binary
blob to arbitrate. It takes no part in `MaskLayer`'s equality for the same
reason — a device that has run the model and one that has not hold the same
edit, and counting the difference would raise a conflict over a cache and let
`remote_wins` answer it by discarding the only copy of the pixels.
Encoding happens in `masks_for_storage`, on the save path, rather than in
`ensure_subject_fields` where every coverage already funnels through.
`ensure_subject_fields` runs on a drag — dilating a mask with a compound
morphology rebuilds the field every frame — and encoding a megapixel raster
per frame is the kind of work NFR-P5 exists to keep off a gesture. Saving
happens once, when the photograph stops being the open one, and already costs
a network round trip.
Version skew holds both ways. A file with no `coverage` line reads exactly as
it did before, which is a layer that needs the model run; an unreadable one
costs the pixels and not the layer, because the layer is the edit and the
raster is a cache of it. An old build reading a new file drops the key it does
not understand, which costs a model run and no work. And a payload that will
not compress is refused rather than truncated: a checkerboard would encode to
twice the raster it came from, so past 64 kB nothing is stored and the
behaviour falls back to what it was — half a mask would render as a mask that
is confidently wrong, which is the failure that tells nobody.
1907 lines
76 KiB
Rust
1907 lines
76 KiB
Rust
//! Local adjustments — a stack of masked edits over the global chain.
|
||
//!
|
||
//! FR-DEV-3's last line: "linear gradient, radial gradient, and brush masks".
|
||
//! A mask layer is an ordinary develop chain plus a rule saying *where* it
|
||
//! applies, and the two halves are deliberately independent — every operation
|
||
//! that works globally works locally, with no per-operation support needed and
|
||
//! nothing to add when a new one is declared in `ops/`.
|
||
//!
|
||
//! # Where a mask actually exists
|
||
//!
|
||
//! **Not here, and not on the CPU at all.** A layer stores the *rule* — some
|
||
//! region ids, a gradient's geometry, or the points a finger travelled through
|
||
//! — and a pass on the device rasterises it into a texture (ARCH §5.4). This
|
||
//! module's job is to describe the rule and to emit the WGSL that blends by
|
||
//! the result.
|
||
//!
|
||
//! That split is the direct response to darktable, where CPU-rasterised brush
|
||
//! masks make painting lag badly enough that users call it unworkable. The
|
||
//! problem there is architectural rather than a tuning failure, and the only
|
||
//! way not to inherit it is to never put a mask in CPU memory. [`Stroke`] is
|
||
//! where that promise is actually kept: a gesture reaches the GPU as a few
|
||
//! numbers and a list of coordinates, and no raster of it is built anywhere
|
||
//! else at any resolution.
|
||
//!
|
||
//! # Why region ids rather than a raster
|
||
//!
|
||
//! [`MaskSource::Regions`] stores integers naming regions in the segmentation
|
||
//! hierarchy (`dr-segment`). That choice is what makes a mask diffable, cheap
|
||
//! in a sidecar, and mergeable per-field under FR-NC-9 — three properties a
|
||
//! stored raster has none of (docs/segmentation.md §1). Two devices that
|
||
//! select the same subject produce the same small sorted list, and a sync
|
||
//! conflict between them is resolvable rather than a binary blob fight.
|
||
//!
|
||
//! The cost is that the ids only mean anything alongside the segmentation that
|
||
//! produced them, so [`MaskSource::Regions::signature`] records which one —
|
||
//! see there for what happens when it does not match.
|
||
//!
|
||
//! # And the raster that had to come back anyway
|
||
//!
|
||
//! The same reasoning was applied to [`MaskSource::Subject`] and
|
||
//! [`MaskSource::Category`], and there it went one step too far. A model's
|
||
//! coverage is reproducible in principle, but only by running the model — and
|
||
//! nothing runs one except a photographer pressing a button. So a stored
|
||
//! subject layer resolved to no pixels on every path that did not have a run
|
||
//! already in memory: reopening the photograph, and exporting it from the
|
||
//! grid, which never runs one at all.
|
||
//!
|
||
//! [`MaskLayer::coverage`] is the answer, and note what it is *not*: the
|
||
//! source still stores identity, still diffs as a handful of numbers, and
|
||
//! still merges per field. The raster sits beside it as a cache, takes no part
|
||
//! in equality, and is thrown away rather than trusted when it does not fit.
|
||
//! See [`crate::coverage`].
|
||
|
||
use std::fmt::Write as _;
|
||
use std::sync::Arc;
|
||
|
||
use crate::coverage::Coverage;
|
||
use crate::descriptor::{OpDescriptor, ParamId};
|
||
use crate::operation::Operation;
|
||
use crate::ops;
|
||
|
||
/// The feather a new layer starts with, as a fraction of the shorter edge.
|
||
///
|
||
/// Named because two places have to agree about it: the constructor sets it,
|
||
/// and the sidecar omits it when unchanged. A literal in both would eventually
|
||
/// be a literal in one.
|
||
pub const DEFAULT_FEATHER: f32 = 0.004;
|
||
|
||
/// The most a layer's [`MaskLayer::refine`] may be, in nats.
|
||
///
|
||
/// Mirrors `dr_segment::STRICTNESS_MAX`, and is a separate constant for the
|
||
/// same reason [`Falloff`] and [`Morphology`] are separate types from that
|
||
/// crate's: this one holds the *description* of an edit and must not depend on
|
||
/// the crate that runs a model. `dr-ui` is where the two meet, and it is the
|
||
/// only place that converts between them.
|
||
///
|
||
/// Used here to bound what a sidecar is allowed to claim. A file is not
|
||
/// trusted, and a strictness off the end of the scale would render as a
|
||
/// category that had silently deleted itself.
|
||
pub const MAX_REFINE: f32 = 8.0;
|
||
|
||
/// The most points one stroke keeps before a gesture continues as a new one.
|
||
///
|
||
/// This is a *cost* bound, not a storage one. Each stroke is drawn over its own
|
||
/// bounding box and the shader walks that stroke's segments once per pixel
|
||
/// inside it, so the work is `area(box) × segments`. Both grow with the length
|
||
/// of the gesture, so an unbroken stroke is quadratic in how far it travelled —
|
||
/// and one long scribble would cost more than the mask it draws is worth.
|
||
///
|
||
/// A gesture longer than this continues as a second stroke beginning where the
|
||
/// first ended, rather than stopping. A stroke that quietly stops recording
|
||
/// half way through a drag is the failure a painter notices immediately; the
|
||
/// cost of continuing is that the two overlap by one dab, so below a flow of 1
|
||
/// the join deposits twice. One dab in 256, against a stroke that dies under
|
||
/// the finger.
|
||
pub const MAX_STROKE_POINTS: usize = 256;
|
||
|
||
/// The most points one brush layer holds, across all of its strokes.
|
||
///
|
||
/// Bounds the sidecar as much as the rasteriser: a stroke is a line of text,
|
||
/// and this is roughly 50 kB of it in the worst case, which is a file a human
|
||
/// can still open. Painting past it refuses rather than dropping the oldest
|
||
/// strokes — the same rule [`MaskStack::push`] follows, for the same reason:
|
||
/// work the user can see on screen must not vanish without being told.
|
||
pub const MAX_LAYER_POINTS: usize = 4096;
|
||
|
||
/// Brush radius a new stroke starts at, as a fraction of the shorter edge.
|
||
pub const DEFAULT_BRUSH_RADIUS: f32 = 0.05;
|
||
/// Fraction of the radius that is fully covered before the edge falls away.
|
||
pub const DEFAULT_BRUSH_HARDNESS: f32 = 0.5;
|
||
/// How much of the brush one stroke deposits.
|
||
pub const DEFAULT_BRUSH_FLOW: f32 = 1.0;
|
||
|
||
/// The grid stroke coordinates are rounded to, as a divisor.
|
||
///
|
||
/// Points are snapped to it on the way in *and* written at that precision, so
|
||
/// the float in memory and the text on disk are the same number. A round trip
|
||
/// is then exact rather than nearly exact, and two devices that painted the
|
||
/// same gesture produce the same line instead of a diff of noise in the sixth
|
||
/// decimal — which under per-field merge (FR-NC-9) is a conflict over nothing.
|
||
///
|
||
/// A ten-thousandth of the frame is a sixth of a pixel at the proxy size a mask
|
||
/// rasterises at, and well under a pixel on a 24 MP export, so nothing survives
|
||
/// the rounding that could be seen.
|
||
const STROKE_GRID: f32 = 10_000.0;
|
||
|
||
/// How far a simplified stroke may stray from the one that was painted, as a
|
||
/// fraction of the brush radius.
|
||
///
|
||
/// A swept disc cannot express detail finer than its own radius: moving the
|
||
/// centre line by an eighth of `r` moves the painted edge by the same eighth,
|
||
/// which is inside the softest part of any brush that is not perfectly hard.
|
||
/// So the points that describe such detail are stored bytes that no pixel can
|
||
/// tell apart from their absence.
|
||
const SIMPLIFY_FRACTION: f32 = 0.125;
|
||
|
||
/// The closest two recorded points may be, as a fraction of the brush radius.
|
||
///
|
||
/// This is what actually bounds a stroke, and it applies while the finger is
|
||
/// down rather than afterwards. A touch screen reports around 120 positions a
|
||
/// second, so a finger held still for five seconds is six hundred points at the
|
||
/// same place; simplification would remove them, but only once the gesture
|
||
/// ended, and every frame until then would have rasterised all of them.
|
||
const MIN_STEP_FRACTION: f32 = 0.125;
|
||
|
||
/// Round to the stored grid. See [`STROKE_GRID`].
|
||
fn snap(v: f32) -> f32 {
|
||
(v * STROKE_GRID).round() / STROKE_GRID
|
||
}
|
||
|
||
/// TRACES: FR-DEV-3
|
||
/// One painted stroke: a disc of radius `radius` swept along a polyline.
|
||
///
|
||
/// # Why parameters rather than pixels
|
||
///
|
||
/// This is the whole of ARCH §5.4. darktable stores drawn masks as strokes too
|
||
/// but rasterises them on the CPU, and the lag that produces is what users
|
||
/// describe as unworkable. What arrives on the GPU here is this struct: a few
|
||
/// numbers and a list of positions, from which a shader draws the mask. No
|
||
/// raster of a brush stroke is ever built in CPU memory, at any resolution, at
|
||
/// any point.
|
||
///
|
||
/// It is also why a stroke costs almost nothing to store, to diff, to merge and
|
||
/// to undo — a mask that had to be persisted as pixels would be none of those.
|
||
///
|
||
/// # Why not a distance field
|
||
///
|
||
/// `dr-segment` computes exact Euclidean distance fields on the CPU and
|
||
/// documents when that is right: once per mask edit, over input that is already
|
||
/// CPU-side. A stroke fails both halves — it changes continuously while the
|
||
/// finger moves, and its input is a handful of coordinates that never needed to
|
||
/// be pixels. And it needs no transform at all: the distance from a point to a
|
||
/// swept disc is the distance to the nearest segment of the polyline, which is
|
||
/// a closed form. A stroke is the one mask whose distance field is known
|
||
/// without computing one.
|
||
#[derive(Debug, Clone, PartialEq)]
|
||
pub struct Stroke {
|
||
/// Whether this stroke takes coverage away instead of adding it.
|
||
///
|
||
/// Painting must be able to erase or a mask is one slip away from being
|
||
/// started again. An erasing stroke removes only what earlier strokes in
|
||
/// *this* layer deposited — it cannot cut a hole in a mask it is not part
|
||
/// of, because coverage below zero has no meaning.
|
||
pub erase: bool,
|
||
/// Radius as a fraction of the frame's **shorter edge**, matching
|
||
/// [`MaskLayer::feather`]. Normalised for the same reason: the same edit
|
||
/// renders to a viewport and to a 24 MP export, and a radius in pixels
|
||
/// would be a different brush in each.
|
||
pub radius: f32,
|
||
/// Fraction of the radius that is fully covered, `0.0..=1.0`. The rest is
|
||
/// the edge falling away to nothing.
|
||
pub hardness: f32,
|
||
/// How much coverage this stroke deposits where it is fully inside,
|
||
/// `0.0..=1.0`. Strokes below 1 build up over each other.
|
||
pub flow: f32,
|
||
/// The path, in normalised source coordinates — the same space the
|
||
/// gradients use, so a stroke survives a crop, a straighten and an export
|
||
/// at another size. A single point is a legitimate stroke: it is a tap, and
|
||
/// it paints one dab.
|
||
pub points: Vec<(f32, f32)>,
|
||
}
|
||
|
||
impl Stroke {
|
||
/// A stroke with no points yet, with its parameters clamped to what the
|
||
/// rasteriser can express.
|
||
pub fn new(erase: bool, radius: f32, hardness: f32, flow: f32) -> Self {
|
||
Self {
|
||
erase,
|
||
// A radius of zero would be a stroke that paints nothing at all,
|
||
// which is indistinguishable from the brush being broken.
|
||
radius: snap(radius.clamp(1e-4, 1.0)),
|
||
hardness: snap(hardness.clamp(0.0, 1.0)),
|
||
flow: snap(flow.clamp(0.0, 1.0)),
|
||
points: Vec::new(),
|
||
}
|
||
}
|
||
|
||
pub fn is_empty(&self) -> bool {
|
||
self.points.is_empty()
|
||
}
|
||
|
||
pub fn len(&self) -> usize {
|
||
self.points.len()
|
||
}
|
||
|
||
/// Whether this stroke is full and a gesture must continue in another.
|
||
pub fn is_full(&self) -> bool {
|
||
self.points.len() >= MAX_STROKE_POINTS
|
||
}
|
||
|
||
/// Record a position, returning whether it was kept.
|
||
///
|
||
/// Rejects anything closer to the last point than [`MIN_STEP_FRACTION`] of
|
||
/// the radius, which is what stops a stationary finger filling the stroke.
|
||
/// The first point is always kept, so a tap paints.
|
||
pub fn push_point(&mut self, x: f32, y: f32) -> bool {
|
||
if self.is_full() {
|
||
return false;
|
||
}
|
||
let p = (snap(x), snap(y));
|
||
if let Some(&(lx, ly)) = self.points.last() {
|
||
let step = self.radius * MIN_STEP_FRACTION;
|
||
if (p.0 - lx).abs() < step && (p.1 - ly).abs() < step {
|
||
return false;
|
||
}
|
||
}
|
||
self.points.push(p);
|
||
true
|
||
}
|
||
|
||
/// Drop the points that a disc of this radius cannot tell apart.
|
||
///
|
||
/// Run once, when the gesture ends — never while it is being painted, since
|
||
/// simplifying a path that is still growing would move points the user has
|
||
/// already seen drawn. Ramer–Douglas–Peucker, which is the one that keeps
|
||
/// the *shape*: dropping every other point instead would round off corners,
|
||
/// and a corner is where a painter aimed.
|
||
///
|
||
/// The tolerance is in normalised units while the radius is in shorter-edge
|
||
/// units, so on a frame that is not square the horizontal tolerance is
|
||
/// larger than intended by the aspect ratio. At an eighth of the radius
|
||
/// that leaves it near a fifth on a 3:2 frame, still inside the brush's own
|
||
/// edge, and the alternative is a model that has to be told the shape of a
|
||
/// photograph it is not part of.
|
||
pub fn simplify(&mut self) {
|
||
if self.points.len() < 3 {
|
||
return;
|
||
}
|
||
let tolerance = self.radius * SIMPLIFY_FRACTION;
|
||
let last = self.points.len() - 1;
|
||
let mut keep = vec![false; self.points.len()];
|
||
keep[0] = true;
|
||
keep[last] = true;
|
||
douglas_peucker(&self.points, 0, last, tolerance, &mut keep);
|
||
|
||
let mut i = 0;
|
||
self.points.retain(|_| {
|
||
let k = keep[i];
|
||
i += 1;
|
||
k
|
||
});
|
||
}
|
||
}
|
||
|
||
/// Mark the points needed to describe `points[first..=last]` within `tolerance`.
|
||
fn douglas_peucker(
|
||
points: &[(f32, f32)],
|
||
first: usize,
|
||
last: usize,
|
||
tolerance: f32,
|
||
keep: &mut [bool],
|
||
) {
|
||
if last <= first + 1 {
|
||
return;
|
||
}
|
||
|
||
let (ax, ay) = points[first];
|
||
let (bx, by) = points[last];
|
||
let (dx, dy) = (bx - ax, by - ay);
|
||
let len2 = dx * dx + dy * dy;
|
||
|
||
let mut worst = first;
|
||
let mut worst_d = 0.0f32;
|
||
for (i, &(px, py)) in points.iter().enumerate().take(last).skip(first + 1) {
|
||
// Distance to the *segment*, not to the infinite line: a stroke that
|
||
// doubles back has both ends in the same place, and a line through them
|
||
// is undefined. Clamping the projection makes that case the distance to
|
||
// the shared endpoint, which is the right answer rather than a NaN.
|
||
let d = if len2 <= f32::EPSILON {
|
||
((px - ax).powi(2) + (py - ay).powi(2)).sqrt()
|
||
} else {
|
||
let t = (((px - ax) * dx + (py - ay) * dy) / len2).clamp(0.0, 1.0);
|
||
((px - ax - t * dx).powi(2) + (py - ay - t * dy).powi(2)).sqrt()
|
||
};
|
||
if d > worst_d {
|
||
worst_d = d;
|
||
worst = i;
|
||
}
|
||
}
|
||
|
||
if worst_d > tolerance {
|
||
keep[worst] = true;
|
||
douglas_peucker(points, first, worst, tolerance, keep);
|
||
douglas_peucker(points, worst, last, tolerance, keep);
|
||
}
|
||
}
|
||
|
||
/// Bilinear sampling of one slice of the mask array, in **source** space.
|
||
///
|
||
/// Hand-rolled rather than done with a sampler, matching how the source
|
||
/// texture is read: adding a sampler would change a bind group layout every
|
||
/// pass shares.
|
||
///
|
||
/// Bilinear rather than a straight load because the array is at proxy
|
||
/// resolution and the view may be zoomed well past it. A nearest-neighbour
|
||
/// mask shows as visible stair-stepping along the edge of the adjustment at
|
||
/// 100%, which is exactly where a mask is judged.
|
||
pub(crate) const MASK_SAMPLER: crate::operation::Helper = crate::operation::Helper {
|
||
name: "sample_mask",
|
||
source: "fn sample_mask(uv: vec2<f32>, layer: i32) -> f32 {
|
||
let dims = vec2<f32>(textureDimensions(masks));
|
||
let last = vec2<i32>(dims) - vec2<i32>(1);
|
||
|
||
// Sample positions are texel centres, so the half-texel offset is what
|
||
// keeps the interpolated edge where the rasteriser drew it.
|
||
let t = uv * dims - vec2<f32>(0.5);
|
||
let base = vec2<i32>(floor(t));
|
||
let f = fract(t);
|
||
|
||
let p0 = clamp(base, vec2<i32>(0), last);
|
||
let p1 = clamp(base + vec2<i32>(1), vec2<i32>(0), last);
|
||
|
||
let a = textureLoad(masks, vec2<i32>(p0.x, p0.y), layer, 0).r;
|
||
let b = textureLoad(masks, vec2<i32>(p1.x, p0.y), layer, 0).r;
|
||
let c = textureLoad(masks, vec2<i32>(p0.x, p1.y), layer, 0).r;
|
||
let d = textureLoad(masks, vec2<i32>(p1.x, p1.y), layer, 0).r;
|
||
|
||
return mix(mix(a, b, f.x), mix(c, d, f.x), f.y);
|
||
}",
|
||
};
|
||
|
||
/// Per-layer uniforms the generated shader reads: `invert`, then `opacity`.
|
||
pub const LAYER_UNIFORM_FIELDS: usize = 2;
|
||
|
||
/// The most layers one image may carry.
|
||
///
|
||
/// A limit exists because the masks are bound as one texture array and every
|
||
/// layer costs a full-resolution channel of VRAM — at 24 MP that is ~24 MB
|
||
/// each, so an unbounded stack is an out-of-memory waiting for a patient user.
|
||
/// Eight is comfortably past what an edit uses in practice and still bounded.
|
||
pub const MAX_LAYERS: usize = 8;
|
||
|
||
/// How a mask's coverage falls away from its edge.
|
||
///
|
||
/// Applied to the **signed distance** from the mask boundary, which is what
|
||
/// makes an arbitrary curve possible: the rasteriser computes one exact
|
||
/// Euclidean distance field and the choice below is a function of it, so a
|
||
/// new shape costs a line rather than a pass.
|
||
///
|
||
/// A watershed boundary is pixel-exact, which is correct and also harsher
|
||
/// than any edit wants at a subject's edge — an exposure change that stops
|
||
/// dead at a hairline reads as a cut-out. So the useful default is a soft one.
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
|
||
pub enum Falloff {
|
||
/// No transition. The boundary as the segmentation drew it.
|
||
///
|
||
/// Worth keeping rather than approximating with a tiny feather: it is what
|
||
/// you want when checking *where* a boundary actually fell, and a feather
|
||
/// hides exactly that.
|
||
Hard,
|
||
/// Straight ramp. Predictable, and visibly banded on a gradient.
|
||
Linear,
|
||
/// Smoothstep — zero derivative at both ends.
|
||
///
|
||
/// The default. The ends are where a ramp shows: a linear falloff leaves a
|
||
/// visible crease where the effect starts and where it stops, because the
|
||
/// eye finds discontinuities in the *slope*, not in the value.
|
||
#[default]
|
||
Smooth,
|
||
/// Gaussian-shaped. Softest, and reaches further than its radius suggests.
|
||
Gaussian,
|
||
/// Sharp near the edge, long tail. For blending an adjustment out over a
|
||
/// large area without moving the boundary itself.
|
||
Exponential,
|
||
}
|
||
|
||
impl Falloff {
|
||
pub fn name(self) -> &'static str {
|
||
match self {
|
||
Self::Hard => "hard",
|
||
Self::Linear => "linear",
|
||
Self::Smooth => "smooth",
|
||
Self::Gaussian => "gaussian",
|
||
Self::Exponential => "exponential",
|
||
}
|
||
}
|
||
|
||
pub fn from_name(name: &str) -> Option<Self> {
|
||
Some(match name {
|
||
"hard" => Self::Hard,
|
||
"linear" => Self::Linear,
|
||
"smooth" => Self::Smooth,
|
||
"gaussian" => Self::Gaussian,
|
||
"exponential" => Self::Exponential,
|
||
_ => return None,
|
||
})
|
||
}
|
||
|
||
/// Every variant, for a UI building a choice control.
|
||
pub const ALL: [Falloff; 5] = [
|
||
Falloff::Hard,
|
||
Falloff::Linear,
|
||
Falloff::Smooth,
|
||
Falloff::Gaussian,
|
||
Falloff::Exponential,
|
||
];
|
||
}
|
||
|
||
/// Growing, shrinking and tidying a mask's extent.
|
||
///
|
||
/// All four are thresholds of the same distance field, which is why they
|
||
/// arrive together rather than one at a time: dilation is "distance ≥ −r",
|
||
/// erosion is "distance ≥ +r", and the two compound operations are one of
|
||
/// those followed by the other.
|
||
///
|
||
/// The compound pair costs a **second** distance field, because after the
|
||
/// first threshold the shape has changed and the old distances no longer
|
||
/// describe it. That is a real cost and the reason they are named separately
|
||
/// rather than presented as a radius that happens to be signed.
|
||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
|
||
pub enum Morphology {
|
||
#[default]
|
||
None,
|
||
/// Grow. The everyday fix for a selection that stops just inside a
|
||
/// subject's edge, which is what an under-segmented boundary produces.
|
||
Dilate,
|
||
/// Shrink. Pulls a selection back off a halo it caught.
|
||
Erode,
|
||
/// Dilate then erode: fills pinholes and closes narrow gaps without
|
||
/// growing the outline. What to reach for when a mask is speckled with
|
||
/// missed pixels inside an area that is plainly one thing.
|
||
Close,
|
||
/// Erode then dilate: removes specks and thin spurs without shrinking the
|
||
/// outline. The complement, for a selection that leaked along an edge.
|
||
Open,
|
||
}
|
||
|
||
impl Morphology {
|
||
pub fn name(self) -> &'static str {
|
||
match self {
|
||
Self::None => "none",
|
||
Self::Dilate => "dilate",
|
||
Self::Erode => "erode",
|
||
Self::Close => "close",
|
||
Self::Open => "open",
|
||
}
|
||
}
|
||
|
||
pub fn from_name(name: &str) -> Option<Self> {
|
||
Some(match name {
|
||
"none" => Self::None,
|
||
"dilate" => Self::Dilate,
|
||
"erode" => Self::Erode,
|
||
"close" => Self::Close,
|
||
"open" => Self::Open,
|
||
_ => return None,
|
||
})
|
||
}
|
||
|
||
/// Whether this needs a second distance field.
|
||
pub fn is_compound(self) -> bool {
|
||
matches!(self, Self::Close | Self::Open)
|
||
}
|
||
|
||
pub const ALL: [Morphology; 5] = [
|
||
Morphology::None,
|
||
Morphology::Dilate,
|
||
Morphology::Erode,
|
||
Morphology::Close,
|
||
Morphology::Open,
|
||
];
|
||
}
|
||
|
||
/// Where a mask layer applies.
|
||
#[derive(Debug, Clone, PartialEq)]
|
||
pub enum MaskSource {
|
||
/// A set of segmentation regions — the click-to-select mask.
|
||
///
|
||
/// This is what the watershed and the semantic model exist to produce.
|
||
/// Selecting a subject means "the regions the model's instance covers",
|
||
/// and the resulting edge is the watershed's, which is to say the image's
|
||
/// own (docs/segmentation.md §5).
|
||
Regions {
|
||
/// Which segmentation these ids index into.
|
||
///
|
||
/// Region numbering is a property of one particular segmentation of
|
||
/// one particular image at one particular proxy size. Store ids
|
||
/// without recording that, and a later build with a retuned watershed
|
||
/// silently reinterprets the mask as a different shape — the failure
|
||
/// mode being *a wrong mask*, which is far worse than *no mask*,
|
||
/// because nothing announces it.
|
||
///
|
||
/// When this does not match the current segmentation the layer is
|
||
/// treated as stale rather than applied: see [`MaskLayer::is_stale`].
|
||
signature: u64,
|
||
/// Granularity: how far up the merge hierarchy the ids were taken.
|
||
level: u32,
|
||
/// Sorted and deduplicated, so the same selection is byte-identical
|
||
/// however it was arrived at — which is what lets it be a cache key.
|
||
ids: Vec<u32>,
|
||
},
|
||
|
||
/// One object the model recognised, used as the mask directly.
|
||
///
|
||
/// **The primary way a local adjustment is made.** The watershed hierarchy
|
||
/// this crate was first built around does not survive a photograph: its
|
||
/// saddles are near zero almost everywhere, so a global cut collapses the
|
||
/// frame into one region plus noise (docs/segmentation.md §15). A model
|
||
/// instance is a whole object, found as one thing, and needs no ladder.
|
||
///
|
||
/// The trade is that the boundary is the model's — a quarter-resolution
|
||
/// sigmoid — rather than the image's own gradient. That is what the edge
|
||
/// treatment on [`MaskLayer`] is for: the mask arrives approximately
|
||
/// right and soft, and dilation, erosion and a chosen falloff are how it
|
||
/// is made to fit.
|
||
///
|
||
/// Stored as *identity*, not as pixels: the mask is several megabytes and
|
||
/// the fields below are what is needed to find it again. The pixels do go
|
||
/// in the sidecar as well, run-length coded beside the layer rather than
|
||
/// inside this variant, because "reproducible by running the model again"
|
||
/// turned out to mean "absent everywhere a model has not been run" — see
|
||
/// [`MaskLayer::coverage`].
|
||
Subject {
|
||
/// Which segmentation run produced it, so a layer can tell whether
|
||
/// the index below still means what it meant.
|
||
signature: u64,
|
||
/// Position in that run's detection list, strongest first.
|
||
index: u32,
|
||
/// The class name, for display and as a sanity check on re-detection:
|
||
/// if instance 3 is a "car" where it was a "dog", the model or the
|
||
/// image changed and the layer should be treated as stale rather than
|
||
/// silently masking something else.
|
||
class: String,
|
||
score: f32,
|
||
},
|
||
|
||
/// Every pixel of one photographic category, from the scene model.
|
||
///
|
||
/// The counterpart to [`Self::Subject`], and the difference is the whole
|
||
/// reason both exist. A subject is *one* instance — this dog, not that one
|
||
/// — found by a COCO-trained instance model. A category is *all* the sky,
|
||
/// or all the foliage, from an ADE20K-trained semantic model that has no
|
||
/// notion of instances at all (docs/segmentation.md §16).
|
||
///
|
||
/// So this is what a global grade attaches to: lift the sky, desaturate
|
||
/// the vegetation, warm the architecture. Asking it for "that person
|
||
/// rather than the other two" is a category error — the model merged them
|
||
/// before the mask ever existed, and [`Self::Subject`] is the source for
|
||
/// that question.
|
||
///
|
||
/// Stored as identity like a subject, and the coverage travels beside it
|
||
/// for the same reason — see [`MaskLayer::coverage`].
|
||
Category {
|
||
/// Which segmentation run produced it, so a layer can tell whether
|
||
/// the name below still refers to something that was computed.
|
||
signature: u64,
|
||
/// The category name from `models/scene/categories.txt` — "sky",
|
||
/// "vegetation".
|
||
///
|
||
/// A name rather than an index because the descriptor is editable: a
|
||
/// category added to it would silently renumber every layer stored
|
||
/// against an index, and the failure would be a mask quietly grading
|
||
/// the wrong thing. A name that no longer exists is simply not found,
|
||
/// and the layer reads as stale.
|
||
name: String,
|
||
},
|
||
|
||
/// A linear gradient — the graduated-filter mask.
|
||
///
|
||
/// Geometry is in **normalised source coordinates**, so it survives a crop,
|
||
/// a zoom or an export at another size: the mask is rasterised in source
|
||
/// space and sampled through the framing map, exactly as a subject mask is.
|
||
/// Storing pixels would make a mask that silently moves when the frame
|
||
/// changes.
|
||
///
|
||
/// # Two spaces, and why both are here
|
||
///
|
||
/// The **centre** is a point, so it is a plain `0.0..=1.0` fraction of each
|
||
/// axis — the same coordinates a click carries.
|
||
///
|
||
/// The **angle and the width are measurements**, and a fraction of the
|
||
/// width is not the same length as a fraction of the height on any frame
|
||
/// that is not square. So they are in the frame's *isotropic* units: y
|
||
/// spans `0..1` and x spans `0..aspect`, which is what makes 45° actually
|
||
/// 45° and a circle actually round. `frame_delta` in `mask.wgsl` is the
|
||
/// one place that conversion happens, and it must stay the only one.
|
||
Linear {
|
||
/// Midpoint of the ramp, `0.0..=1.0` in each axis.
|
||
centre: (f32, f32),
|
||
/// Radians, measured clockwise from the +x axis in frame units.
|
||
/// Coverage increases in this direction.
|
||
angle: f32,
|
||
/// Distance from full effect to none, in frame units. Zero is a hard
|
||
/// edge.
|
||
width: f32,
|
||
},
|
||
|
||
/// A radial gradient — the classic vignette-shaped local adjustment.
|
||
///
|
||
/// The same two spaces as [`Self::Linear`]: a `0..1` centre, and semi-axes
|
||
/// measured in the frame's isotropic units so equal radii draw a circle.
|
||
Radial {
|
||
centre: (f32, f32),
|
||
/// Semi-axes, in frame units. Two of them, because a face is an
|
||
/// ellipse and forcing a circle makes the user compensate with a crop.
|
||
radii: (f32, f32),
|
||
/// Rotation of the ellipse, radians.
|
||
angle: f32,
|
||
/// Fraction of the radius over which the edge falls off.
|
||
feather: f32,
|
||
},
|
||
|
||
/// Painted strokes — the drawn mask (FR-DEV-3, ARCH §5.4).
|
||
///
|
||
/// Ordered, and the order is the meaning: each stroke composites over what
|
||
/// the ones before it left, so an erase after an add removes it and the
|
||
/// same two the other way round do not. Reordering them would be editing
|
||
/// the mask.
|
||
///
|
||
/// Geometry is normalised like the gradients', so a stroke stays on the
|
||
/// thing it was painted on through a crop, a straighten and an export at
|
||
/// any size.
|
||
Brush { strokes: Vec<Stroke> },
|
||
}
|
||
|
||
impl MaskSource {
|
||
/// A short stable name for the UI and for debugging.
|
||
pub fn kind(&self) -> &'static str {
|
||
match self {
|
||
Self::Regions { .. } => "regions",
|
||
Self::Subject { .. } => "subject",
|
||
Self::Category { .. } => "category",
|
||
Self::Linear { .. } => "linear",
|
||
Self::Radial { .. } => "radial",
|
||
Self::Brush { .. } => "brush",
|
||
}
|
||
}
|
||
|
||
/// An empty brush mask, ready to be painted into.
|
||
pub fn brush() -> Self {
|
||
Self::Brush {
|
||
strokes: Vec::new(),
|
||
}
|
||
}
|
||
|
||
/// The strokes, or nothing for a source that is not painted.
|
||
pub fn strokes(&self) -> &[Stroke] {
|
||
match self {
|
||
Self::Brush { strokes } => strokes,
|
||
_ => &[],
|
||
}
|
||
}
|
||
}
|
||
|
||
/// One local adjustment: a rule about *where*, plus a chain saying *what*.
|
||
pub struct MaskLayer {
|
||
/// Stable identity, for the sidecar and for merge (FR-NC-9).
|
||
pub id: String,
|
||
/// What the user called it. Empty means "name me after my source".
|
||
pub name: String,
|
||
pub source: MaskSource,
|
||
/// Swap inside for outside.
|
||
pub invert: bool,
|
||
/// Global strength of the layer, `0.0..=1.0`.
|
||
pub opacity: f32,
|
||
/// Off without being deleted — the A/B a local edit is always wanting.
|
||
pub enabled: bool,
|
||
|
||
/// Half-width of the edge transition, as a fraction of the frame's
|
||
/// **shorter edge**.
|
||
///
|
||
/// Normalised rather than in pixels for the same reason the gradient
|
||
/// geometry is: the same edit renders to a viewport and to a 24 MP export,
|
||
/// and a feather measured in pixels would be a different edge in each.
|
||
///
|
||
/// Zero means no transition regardless of [`Self::falloff`].
|
||
pub feather: f32,
|
||
pub falloff: Falloff,
|
||
|
||
/// Grow, shrink or tidy the mask before the feather is applied.
|
||
///
|
||
/// Before, and it matters: dilating a *feathered* mask would push the
|
||
/// half-way point outward and soften it further, so the two controls would
|
||
/// not be independent. Morphology moves the boundary; feather describes
|
||
/// how the boundary is crossed.
|
||
pub morphology: Morphology,
|
||
/// How far, in the same units as [`Self::feather`].
|
||
pub morph_radius: f32,
|
||
|
||
/// How strictly a category source is cut back to the pixels whose colour
|
||
/// agrees with it, in nats. Zero leaves the model's own weighting alone.
|
||
///
|
||
/// Only [`MaskSource::Category`] has anything to apply it to — the
|
||
/// evidence is fitted per category during segmentation — so it sits at
|
||
/// zero and out of the panel for every other source.
|
||
///
|
||
/// A *quantity*, not a 0-to-100: it is how much more plausible than the
|
||
/// alternatives a colour must be before its weight is kept, which is why
|
||
/// `dr_segment::refine` can state where a flag falls on it and where a
|
||
/// cloud does. Bounded by [`MAX_REFINE`].
|
||
///
|
||
/// This is shaping, like [`Self::feather`], and it lives on the layer for
|
||
/// the same reason: two layers may sit on the same category and want
|
||
/// different amounts of it, and the model ran once for both.
|
||
pub refine: f32,
|
||
|
||
/// The pixels this layer covered, when a model produced them and they
|
||
/// were worth storing.
|
||
///
|
||
/// # Beside the source, not inside it
|
||
///
|
||
/// [`MaskSource::Subject`] and [`MaskSource::Category`] are *identity* —
|
||
/// which run, which instance, which category — and that is what makes them
|
||
/// diffable, small, and mergeable per field under FR-NC-9. Putting a
|
||
/// raster inside either variant would make two devices that selected the
|
||
/// same dog hold different values for the same selection, and the merge
|
||
/// would then have a binary blob to arbitrate rather than an index.
|
||
///
|
||
/// So this sits alongside as what it actually is: a **materialisation** of
|
||
/// the source, produced by a run of a model this crate has never heard of
|
||
/// and knows nothing about. `MaskSource` still says what the layer means;
|
||
/// this says what that meant last time anybody worked it out. The
|
||
/// distinction is why it takes no part in [`PartialEq`] — a layer with the
|
||
/// pixels cached and one without are the same edit, and a merge that
|
||
/// called them different would raise a conflict over a cache.
|
||
///
|
||
/// # Why it exists at all
|
||
///
|
||
/// Without it a stored subject or category layer renders as nothing until
|
||
/// somebody presses "find subjects" — so reopening a photograph dropped
|
||
/// its local adjustments, and a batch export, which never runs a model,
|
||
/// could not have them at any point. See [`crate::coverage`].
|
||
///
|
||
/// Shared rather than owned because the undo stack holds a snapshot per
|
||
/// step and a layer is cloned by value; an `Arc` makes recording a slider
|
||
/// drag cost a refcount rather than a copy of every mask in the stack.
|
||
/// Only ever set for the two model sources — nothing else has a model
|
||
/// behind it to cache.
|
||
pub coverage: Option<Arc<Coverage>>,
|
||
|
||
/// This layer's adjustments.
|
||
///
|
||
/// A full chain, the same one [`crate::EditGraph`] holds. That is the
|
||
/// whole reason local adjustments need no per-operation support: the
|
||
/// composer already knows how to turn a chain into WGSL, and a mask layer
|
||
/// is a chain that happens to be multiplied by a mask afterwards.
|
||
pub ops: Vec<Box<dyn Operation>>,
|
||
}
|
||
|
||
/// The chain a mask layer holds: every point operation, and none of the
|
||
/// neighbourhood ones.
|
||
///
|
||
/// A layer's adjustments are fused into the colour dispatch and multiplied by
|
||
/// the mask afterwards, which is exactly why a layer needs no per-operation
|
||
/// support — the composer already knows how to turn a chain into WGSL. A
|
||
/// neighbourhood operation cannot go through that path at all: it runs as its
|
||
/// own dispatch in [`crate::detail`], after the fused pass and after the masks
|
||
/// have already been applied, and there is nowhere in that arrangement for it
|
||
/// to be given one layer's mask.
|
||
///
|
||
/// Left in, it would be worse than absent. `Operation::wgsl_body` returns an
|
||
/// empty string for a detail operation, so the layer would emit an empty block
|
||
/// and the panel — which builds itself from [`MaskLayer::capabilities`] and
|
||
/// names no operation — would offer a slider that moved and did nothing.
|
||
/// Filtering here means a local sharpening or denoise control simply does not
|
||
/// appear until there is a stage that can honour it, which is the honest
|
||
/// state of affairs.
|
||
fn layer_chain() -> Vec<Box<dyn Operation>> {
|
||
ops::chain()
|
||
.into_iter()
|
||
.filter(|o| o.detail().is_none())
|
||
.collect()
|
||
}
|
||
|
||
impl Clone for MaskLayer {
|
||
/// Cloned by *value*, not by handle: the ops are trait objects, so this
|
||
/// rebuilds a fresh chain and copies the parameters across. Needed because
|
||
/// the UI edits a layer speculatively and the history stores snapshots.
|
||
fn clone(&self) -> Self {
|
||
let mut ops = layer_chain();
|
||
for (dst, src) in ops.iter_mut().zip(&self.ops) {
|
||
for p in &src.descriptor().params {
|
||
dst.set_param(p.id, src.param(p.id));
|
||
}
|
||
}
|
||
Self {
|
||
id: self.id.clone(),
|
||
name: self.name.clone(),
|
||
source: self.source.clone(),
|
||
invert: self.invert,
|
||
opacity: self.opacity,
|
||
enabled: self.enabled,
|
||
feather: self.feather,
|
||
falloff: self.falloff,
|
||
morphology: self.morphology,
|
||
morph_radius: self.morph_radius,
|
||
refine: self.refine,
|
||
// A refcount, not a raster. See the field.
|
||
coverage: self.coverage.clone(),
|
||
ops,
|
||
}
|
||
}
|
||
}
|
||
|
||
impl std::fmt::Debug for MaskLayer {
|
||
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
||
f.debug_struct("MaskLayer")
|
||
.field("id", &self.id)
|
||
.field("name", &self.name)
|
||
.field("source", &self.source)
|
||
.field("invert", &self.invert)
|
||
.field("opacity", &self.opacity)
|
||
.field("enabled", &self.enabled)
|
||
.field("feather", &self.feather)
|
||
.field("falloff", &self.falloff)
|
||
.field("morphology", &self.morphology)
|
||
.field("coverage", &self.coverage.as_ref().map(|c| c.encoded_len()))
|
||
.field("active_ops", &self.active_ops().count())
|
||
.finish()
|
||
}
|
||
}
|
||
|
||
impl PartialEq for MaskLayer {
|
||
/// Every field that is the *edit*, and deliberately not
|
||
/// [`Self::coverage`].
|
||
///
|
||
/// This comparison is what [`crate::sidecar::Version::merge`] uses to
|
||
/// decide whether a device changed a layer (FR-NC-9). A cached raster is
|
||
/// not something a photographer changed: one device that has run the model
|
||
/// and one that has not hold the same edit, and counting the difference
|
||
/// would raise a conflict over a cache — and, with `remote_wins`, could
|
||
/// answer it by discarding the only copy of the pixels.
|
||
fn eq(&self, other: &Self) -> bool {
|
||
self.id == other.id
|
||
&& self.name == other.name
|
||
&& self.source == other.source
|
||
&& self.invert == other.invert
|
||
&& self.opacity == other.opacity
|
||
&& self.enabled == other.enabled
|
||
&& self.feather == other.feather
|
||
&& self.falloff == other.falloff
|
||
&& self.morphology == other.morphology
|
||
&& self.morph_radius == other.morph_radius
|
||
&& self.params().eq(other.params())
|
||
}
|
||
}
|
||
|
||
impl MaskLayer {
|
||
/// A new layer over `source`, with every adjustment at neutral.
|
||
pub fn new(id: impl Into<String>, source: MaskSource) -> Self {
|
||
Self {
|
||
id: id.into(),
|
||
name: String::new(),
|
||
source,
|
||
invert: false,
|
||
opacity: 1.0,
|
||
enabled: true,
|
||
// A small default rather than zero. A watershed boundary is exact
|
||
// to the pixel, and an adjustment that stops dead on one looks
|
||
// pasted on — the first thing anyone would reach for, so it is
|
||
// where the control starts.
|
||
feather: DEFAULT_FEATHER,
|
||
falloff: Falloff::default(),
|
||
morphology: Morphology::default(),
|
||
morph_radius: 0.0,
|
||
// Off, so a layer built here is the model's own weighting. The
|
||
// useful starting point for a *category* is not zero, but it is
|
||
// `dr_segment`'s number to state and this crate does not depend on
|
||
// it — `Session::add_category_mask` sets it on the way in.
|
||
refine: 0.0,
|
||
// Nothing has run yet. Filled in the first time a model's coverage
|
||
// is turned into a distance field — see [`Self::coverage`].
|
||
coverage: None,
|
||
ops: layer_chain(),
|
||
}
|
||
}
|
||
|
||
/// The name to show, falling back to the source kind.
|
||
pub fn display_name(&self) -> &str {
|
||
if self.name.is_empty() {
|
||
self.source.kind()
|
||
} else {
|
||
&self.name
|
||
}
|
||
}
|
||
|
||
/// Whether this layer would change any pixel.
|
||
///
|
||
/// A layer with a mask but no adjustment is not inactive in the UI — it is
|
||
/// a selection the user is still working on — but it contributes nothing
|
||
/// to the shader and is omitted from it.
|
||
pub fn is_active(&self) -> bool {
|
||
self.enabled && self.opacity > 0.0 && self.active_ops().next().is_some() && self.covers()
|
||
}
|
||
|
||
/// Whether this mask could cover any pixel at all.
|
||
///
|
||
/// Only a brush can answer no, and it matters more than the slot it saves.
|
||
/// An unpainted mask is empty, [`Self::invert`] turns empty into
|
||
/// everything, and a layer created with invert already set would apply its
|
||
/// adjustment to the whole photograph before a single stroke was made —
|
||
/// the loud, wrong-looking failure this codebase avoids everywhere else a
|
||
/// mask can go missing.
|
||
fn covers(&self) -> bool {
|
||
match &self.source {
|
||
MaskSource::Brush { strokes } => strokes.iter().any(|s| !s.erase && !s.is_empty()),
|
||
_ => true,
|
||
}
|
||
}
|
||
|
||
/// The operations in this layer's chain that reach the shader.
|
||
///
|
||
/// Neighbourhood operations are excluded, and not as an oversight. A
|
||
/// layer's chain is *fused into the point-operation pass* and multiplied
|
||
/// by the mask afterwards; the detail stage runs once, over the whole
|
||
/// frame, after that pass has finished (see [`crate::detail`]). There is
|
||
/// nowhere in that arrangement for a sharpening confined to one mask to
|
||
/// happen, so a detail operation in a layer would contribute an empty
|
||
/// block, count towards [`Self::is_active`], and cost a mask rasterisation
|
||
/// to change nothing. Dropping it here means the layer reports honestly
|
||
/// that it has no adjustment rather than appearing to have one.
|
||
pub fn active_ops(&self) -> impl Iterator<Item = &dyn Operation> {
|
||
self.ops
|
||
.iter()
|
||
.map(|o| o.as_ref())
|
||
.filter(|o| o.is_active() && o.detail().is_none())
|
||
}
|
||
|
||
/// Whether this layer's region ids belong to a different segmentation.
|
||
///
|
||
/// Applying it anyway would produce a confidently wrong mask, so callers
|
||
/// should offer to recompute rather than render it.
|
||
pub fn is_stale(&self, current: u64) -> bool {
|
||
match self.source {
|
||
MaskSource::Regions { signature, .. }
|
||
| MaskSource::Subject { signature, .. }
|
||
| MaskSource::Category { signature, .. } => signature != current,
|
||
// A gradient is geometry in normalised coordinates. It means the
|
||
// same thing whatever was or was not detected, so nothing about a
|
||
// new run can invalidate it. Painted strokes are the same: they are
|
||
// where the user put them, not where a model thought something was.
|
||
MaskSource::Linear { .. } | MaskSource::Radial { .. } | MaskSource::Brush { .. } => {
|
||
false
|
||
}
|
||
}
|
||
}
|
||
|
||
/// The strokes on this layer, empty for any other kind of mask.
|
||
pub fn strokes(&self) -> &[Stroke] {
|
||
self.source.strokes()
|
||
}
|
||
|
||
/// How many stroke points this layer is holding. See [`MAX_LAYER_POINTS`].
|
||
pub fn stroke_points(&self) -> usize {
|
||
self.strokes().iter().map(Stroke::len).sum()
|
||
}
|
||
|
||
/// Start a stroke, returning whether there was room for it.
|
||
///
|
||
/// The interaction layer calls this on press, [`Self::extend_stroke`] for
|
||
/// every position the pointer reports, and [`Self::end_stroke`] on release.
|
||
/// Nothing in between needs to reach the GPU by any route other than the
|
||
/// stack itself: the rasteriser reads the strokes each time it runs.
|
||
pub fn begin_stroke(&mut self, erase: bool, radius: f32, hardness: f32, flow: f32) -> bool {
|
||
let full = self.stroke_points() >= MAX_LAYER_POINTS;
|
||
let MaskSource::Brush { strokes } = &mut self.source else {
|
||
log::warn!(
|
||
"layer {} is a {} mask, not a brush",
|
||
self.id,
|
||
self.source.kind()
|
||
);
|
||
return false;
|
||
};
|
||
if full {
|
||
log::warn!(
|
||
"brush layer is full ({MAX_LAYER_POINTS} points); refusing to start another stroke"
|
||
);
|
||
return false;
|
||
}
|
||
strokes.push(Stroke::new(erase, radius, hardness, flow));
|
||
true
|
||
}
|
||
|
||
/// Add a position to the stroke in progress, returning whether it was kept.
|
||
///
|
||
/// A position may be dropped for being too close to the last one, which is
|
||
/// ordinary and not a failure. When the stroke in progress fills up the
|
||
/// gesture continues in a new one starting at the same point, so the swept
|
||
/// path has no gap in it — see [`MAX_STROKE_POINTS`].
|
||
pub fn extend_stroke(&mut self, x: f32, y: f32) -> bool {
|
||
let room = MAX_LAYER_POINTS.saturating_sub(self.stroke_points());
|
||
let MaskSource::Brush { strokes } = &mut self.source else {
|
||
return false;
|
||
};
|
||
let Some(current) = strokes.last_mut() else {
|
||
return false;
|
||
};
|
||
if room == 0 {
|
||
return false;
|
||
}
|
||
|
||
if current.is_full() {
|
||
// Simplified here rather than in `end_stroke`, which only ever sees
|
||
// the last stroke of a gesture: a continuation closes the one
|
||
// before it for good, and an unsimplified stroke would reach the
|
||
// sidecar at full sampling — the one place the saving matters most,
|
||
// since a gesture long enough to split is a long line of text.
|
||
current.simplify();
|
||
let mut next = Stroke::new(
|
||
current.erase,
|
||
current.radius,
|
||
current.hardness,
|
||
current.flow,
|
||
);
|
||
if let Some(&joint) = current.points.last() {
|
||
next.points.push(joint);
|
||
}
|
||
strokes.push(next);
|
||
}
|
||
|
||
strokes
|
||
.last_mut()
|
||
.expect("a stroke was just ensured")
|
||
.push_point(x, y)
|
||
}
|
||
|
||
/// Finish the stroke in progress, simplifying it.
|
||
///
|
||
/// A stroke that recorded nothing is dropped rather than kept as an empty
|
||
/// one: a press with no movement still records its first point, so an empty
|
||
/// stroke can only be a press that never reached the model, and leaving it
|
||
/// would put a stroke in the sidecar that draws nothing.
|
||
pub fn end_stroke(&mut self) {
|
||
let MaskSource::Brush { strokes } = &mut self.source else {
|
||
return;
|
||
};
|
||
match strokes.last_mut() {
|
||
Some(s) if s.is_empty() => {
|
||
strokes.pop();
|
||
}
|
||
Some(s) => s.simplify(),
|
||
None => {}
|
||
}
|
||
}
|
||
|
||
/// Remove the most recent stroke, returning it.
|
||
///
|
||
/// The undo history already snapshots the whole graph, so this is not how
|
||
/// undo works — it is for the interaction layer to abandon a stroke it has
|
||
/// begun, when a gesture turns out to be a pinch or is cancelled.
|
||
pub fn drop_last_stroke(&mut self) -> Option<Stroke> {
|
||
match &mut self.source {
|
||
MaskSource::Brush { strokes } => strokes.pop(),
|
||
_ => None,
|
||
}
|
||
}
|
||
|
||
pub fn descriptors(&self) -> Vec<Arc<OpDescriptor>> {
|
||
self.ops.iter().map(|o| o.descriptor()).collect()
|
||
}
|
||
|
||
/// TRACES: FR-DEV-3a | FR-DEV-3c
|
||
/// The controls for this layer's adjustments.
|
||
///
|
||
/// The same shape [`crate::EditGraph::capabilities`] returns, so a panel
|
||
/// that can render the global chain renders a mask layer with no new code
|
||
/// — which is the practical payoff of a layer holding a real chain rather
|
||
/// than a handful of special-cased sliders.
|
||
///
|
||
/// Framing is absent, and that is the one real difference: a crop changes
|
||
/// the output's dimensions, so it is a property of the photograph and not
|
||
/// of a region within it. There is no such thing as cropping part of an
|
||
/// image.
|
||
///
|
||
/// The neighbourhood operations are absent for the same reason, and this
|
||
/// filter is the visible half of the one [`Self::active_ops`] already
|
||
/// applies. A layer's chain is fused into the point-operation pass; the
|
||
/// detail stage runs once, afterwards, over the whole frame, so there is
|
||
/// no seam through which a mask could reach it (see [`crate::detail`]).
|
||
/// Offering the controls anyway would put a sharpening slider on a mask
|
||
/// that moves and does nothing — which is worse than the control being
|
||
/// absent, because absence is legible and a dead slider is not.
|
||
pub fn capabilities(&self) -> Vec<crate::graph::OpCapability> {
|
||
self.ops
|
||
.iter()
|
||
.filter(|op| op.detail().is_none())
|
||
.map(|op| {
|
||
let desc = op.descriptor();
|
||
crate::graph::OpCapability {
|
||
id: desc.id,
|
||
label: desc.label,
|
||
active: op.is_active(),
|
||
params: desc
|
||
.params
|
||
.iter()
|
||
.map(|p| crate::graph::ParamCapability {
|
||
id: p.id,
|
||
label: p.label,
|
||
kind: p.kind.clone(),
|
||
default: p.default,
|
||
value: op.param(p.id),
|
||
facet: p.facet,
|
||
})
|
||
.collect(),
|
||
presentation: op.presentation(),
|
||
attributes: desc.attributes.clone(),
|
||
}
|
||
})
|
||
.collect()
|
||
}
|
||
|
||
/// Reset every adjustment, keeping the selection.
|
||
///
|
||
/// The selection is the expensive half — it took a click and a scroll to
|
||
/// arrive at — so "start this layer's edit again" must not throw it away.
|
||
pub fn reset_adjustments(&mut self) {
|
||
for op in &mut self.ops {
|
||
for p in &op.descriptor().params {
|
||
op.set_param(p.id, p.default);
|
||
}
|
||
}
|
||
}
|
||
|
||
pub fn set_param(&mut self, op: &str, param: ParamId, value: f32) {
|
||
if let Some(o) = self.ops.iter_mut().find(|o| o.descriptor().id.0 == op) {
|
||
let clamped = o
|
||
.descriptor()
|
||
.param(param)
|
||
.map_or(value, |d| d.clamp(value));
|
||
o.set_param(param, clamped);
|
||
}
|
||
}
|
||
|
||
/// Every non-default parameter, for the sidecar.
|
||
pub fn params(&self) -> impl Iterator<Item = (&'static str, &'static str, f32)> + '_ {
|
||
self.ops.iter().flat_map(|o| {
|
||
let desc = o.descriptor();
|
||
let id = desc.id.0;
|
||
// Collected rather than borrowed from `desc`: a descriptor is an
|
||
// `Arc` handed over by value now (FR-PLG-2), so it would be
|
||
// dropped at the end of this closure and the lazy iterator would
|
||
// outlive it. The ids and defaults are all this needs, and there
|
||
// are a handful of them.
|
||
let params: Vec<(ParamId, f32)> =
|
||
desc.params.iter().map(|p| (p.id, p.default)).collect();
|
||
params.into_iter().filter_map(move |(param, default)| {
|
||
let v = o.param(param);
|
||
(v != default).then_some((id, param.0, v))
|
||
})
|
||
})
|
||
}
|
||
|
||
/// The two uniforms the generated shader reads for this layer.
|
||
fn uniforms(&self) -> [f32; LAYER_UNIFORM_FIELDS] {
|
||
[if self.invert { 1.0 } else { 0.0 }, self.opacity]
|
||
}
|
||
}
|
||
|
||
/// The ordered stack of local adjustments.
|
||
#[derive(Debug, Clone, Default, PartialEq)]
|
||
pub struct MaskStack {
|
||
layers: Vec<MaskLayer>,
|
||
}
|
||
|
||
impl MaskStack {
|
||
pub fn new() -> Self {
|
||
Self::default()
|
||
}
|
||
|
||
pub fn layers(&self) -> &[MaskLayer] {
|
||
&self.layers
|
||
}
|
||
|
||
pub fn layers_mut(&mut self) -> &mut [MaskLayer] {
|
||
&mut self.layers
|
||
}
|
||
|
||
pub fn is_empty(&self) -> bool {
|
||
self.layers.is_empty()
|
||
}
|
||
|
||
pub fn len(&self) -> usize {
|
||
self.layers.len()
|
||
}
|
||
|
||
pub fn get(&self, id: &str) -> Option<&MaskLayer> {
|
||
self.layers.iter().find(|l| l.id == id)
|
||
}
|
||
|
||
pub fn get_mut(&mut self, id: &str) -> Option<&mut MaskLayer> {
|
||
self.layers.iter_mut().find(|l| l.id == id)
|
||
}
|
||
|
||
/// Add a layer, returning whether there was room for it.
|
||
///
|
||
/// Refuses past [`MAX_LAYERS`] rather than dropping the oldest: a stack at
|
||
/// its limit is a thing to tell the user about, and silently discarding
|
||
/// work they can see on screen is the wrong way to handle it.
|
||
pub fn push(&mut self, layer: MaskLayer) -> bool {
|
||
if self.layers.len() >= MAX_LAYERS {
|
||
log::warn!("mask stack is full ({MAX_LAYERS} layers); refusing to add another");
|
||
return false;
|
||
}
|
||
self.layers.push(layer);
|
||
true
|
||
}
|
||
|
||
pub fn remove(&mut self, id: &str) -> Option<MaskLayer> {
|
||
let i = self.layers.iter().position(|l| l.id == id)?;
|
||
Some(self.layers.remove(i))
|
||
}
|
||
|
||
/// Reorder, since later layers composite over earlier ones.
|
||
pub fn move_to(&mut self, id: &str, index: usize) {
|
||
let Some(from) = self.layers.iter().position(|l| l.id == id) else {
|
||
return;
|
||
};
|
||
let layer = self.layers.remove(from);
|
||
self.layers.insert(index.min(self.layers.len()), layer);
|
||
}
|
||
|
||
/// The layers that will appear in the shader, in composite order.
|
||
///
|
||
/// The index within *this* sequence is the texture-array layer the
|
||
/// rasteriser must write, which is why both sides call this rather than
|
||
/// indexing `layers` — an inactive layer occupies no mask slot, and the
|
||
/// two halves disagreeing about that shows as an edit applied through the
|
||
/// wrong mask.
|
||
pub fn active(&self) -> impl Iterator<Item = &MaskLayer> {
|
||
self.layers.iter().filter(|l| l.is_active())
|
||
}
|
||
|
||
pub fn active_count(&self) -> usize {
|
||
self.active().count()
|
||
}
|
||
|
||
/// Whether any layer changes any pixel.
|
||
pub fn is_neutral(&self) -> bool {
|
||
self.active_count() == 0
|
||
}
|
||
|
||
/// Generate a fresh layer id that does not collide with an existing one.
|
||
pub fn next_id(&self) -> String {
|
||
(1..)
|
||
.map(|n| format!("m{n}"))
|
||
.find(|id| self.get(id).is_none())
|
||
.expect("infinite range")
|
||
}
|
||
}
|
||
|
||
/// One layer's contribution to the generated shader.
|
||
pub(crate) struct LayerShader {
|
||
pub uniform_fields: String,
|
||
pub uniform_values: Vec<f32>,
|
||
pub body: String,
|
||
pub helpers: Vec<crate::operation::Helper>,
|
||
}
|
||
|
||
/// Emit the WGSL for every active layer.
|
||
///
|
||
/// `slot` is the layer's index in the mask texture array, matching
|
||
/// [`MaskStack::active`].
|
||
pub(crate) fn compose_layers(stack: &MaskStack) -> LayerShader {
|
||
let mut out = LayerShader {
|
||
uniform_fields: String::new(),
|
||
uniform_values: Vec::new(),
|
||
body: String::new(),
|
||
helpers: Vec::new(),
|
||
};
|
||
|
||
if stack.active().next().is_some() {
|
||
out.helpers.push(MASK_SAMPLER);
|
||
}
|
||
|
||
for (slot, layer) in stack.active().enumerate() {
|
||
let prefix = format!("mask{slot}");
|
||
|
||
let _ = writeln!(
|
||
out.uniform_fields,
|
||
" // mask {slot}: {}\n {prefix}_invert: f32,\n {prefix}_opacity: f32,",
|
||
layer.display_name()
|
||
);
|
||
out.uniform_values.extend_from_slice(&layer.uniforms());
|
||
|
||
let _ = writeln!(
|
||
out.body,
|
||
"\n // ======== mask {slot}: {} ({}) ========",
|
||
layer.display_name(),
|
||
layer.source.kind()
|
||
);
|
||
let _ = writeln!(out.body, " {{");
|
||
// **`uv_src`, not `gid.xy`.** The mask array is rasterised in *source*
|
||
// space, and `uv_src` is the source position this output pixel came
|
||
// from — after the crop, the zoom, the pan, the straightening and the
|
||
// flips. Sampling by output pixel instead, as this once did, pins the
|
||
// mask to the viewport: zooming in slides the photograph under a mask
|
||
// that stays where it was, and cropping moves the adjustment to a
|
||
// different part of the picture.
|
||
//
|
||
// Doing it this way also means the framing map exists in exactly one
|
||
// place. A second copy here would be a second thing to keep in step
|
||
// with `Framing::wgsl_prologue`, and the failure would be a mask that
|
||
// is subtly wrong only when straightened.
|
||
let _ = writeln!(out.body, " var m = sample_mask(uv_src, {slot});");
|
||
let _ = writeln!(
|
||
out.body,
|
||
" m = select(m, 1.0 - m, u.{prefix}_invert > 0.5);"
|
||
);
|
||
let _ = writeln!(
|
||
out.body,
|
||
" m = clamp(m * u.{prefix}_opacity, 0.0, 1.0);"
|
||
);
|
||
// Skipping the work where the mask is empty is most of the point of a
|
||
// local adjustment: a mask covering a tenth of the frame should cost
|
||
// about a tenth of the shader. Safe as non-uniform control flow —
|
||
// nothing inside samples with derivatives or synchronises.
|
||
let _ = writeln!(out.body, " if (m > 0.0) {{");
|
||
// `masked` is the outer-scope carrier: op fragments write to a `c`
|
||
// they expect to own, so the inner block shadows `c` and copies the
|
||
// result back out. Assigning the outer `c` from inside is not possible
|
||
// precisely because it is shadowed.
|
||
let _ = writeln!(out.body, " var masked = c;");
|
||
let _ = writeln!(out.body, " {{");
|
||
let _ = writeln!(out.body, " var c = masked;");
|
||
|
||
for op in layer.active_ops() {
|
||
let id = op.descriptor().id.0;
|
||
let op_prefix = format!("{prefix}_{}", crate::operation::sanitise(id));
|
||
|
||
let op_uniforms = op.uniforms();
|
||
if !op_uniforms.is_empty() {
|
||
let _ = writeln!(out.uniform_fields, " // mask {slot}: {id}");
|
||
}
|
||
for u in &op_uniforms {
|
||
let _ = writeln!(out.uniform_fields, " {op_prefix}_{}: f32,", u.name);
|
||
out.uniform_values.push(u.value);
|
||
}
|
||
|
||
for h in op.helpers() {
|
||
if !out.helpers.iter().any(|e| e.name == h.name) {
|
||
out.helpers.push(*h);
|
||
}
|
||
}
|
||
|
||
let mut fragment = op.wgsl_body();
|
||
for u in &op_uniforms {
|
||
fragment = crate::operation::rewrite_uniform(
|
||
&fragment,
|
||
u.name,
|
||
&format!("u.{op_prefix}_{}", u.name),
|
||
);
|
||
}
|
||
|
||
let _ = writeln!(out.body, " // ---- {id} ----");
|
||
let _ = writeln!(out.body, " {{");
|
||
for line in fragment.lines() {
|
||
let _ = writeln!(out.body, " {line}");
|
||
}
|
||
let _ = writeln!(out.body, " }}");
|
||
}
|
||
|
||
let _ = writeln!(out.body, " masked = c;");
|
||
let _ = writeln!(out.body, " }}");
|
||
let _ = writeln!(out.body, " c = mix(c, masked, m);");
|
||
let _ = writeln!(out.body, " }}");
|
||
let _ = writeln!(out.body, " }}");
|
||
}
|
||
|
||
out
|
||
}
|
||
|
||
/// A stable fingerprint of a segmentation, for [`MaskSource::Regions`].
|
||
///
|
||
/// Built from the things that change what a region id *means* — the proxy
|
||
/// size, the region count, and the options the watershed ran with. Deliberately
|
||
/// **not** a hash of the label field: that would be a readback on a path that
|
||
/// must not have one (ARCH §6.1), and would also make the signature depend on
|
||
/// float arithmetic whose cross-vendor determinism is exactly the open
|
||
/// question (docs/segmentation.md §6, M5).
|
||
pub fn segmentation_signature(width: u32, height: u32, regions: u32, tuning: u64) -> u64 {
|
||
// FNV-1a over the four fields. Small, dependency-free, and adequate: this
|
||
// guards against accidental mismatch, not against a forged sidecar.
|
||
let mut h: u64 = 0xcbf2_9ce4_8422_2325;
|
||
for word in [width as u64, height as u64, regions as u64, tuning] {
|
||
for byte in word.to_le_bytes() {
|
||
h ^= byte as u64;
|
||
h = h.wrapping_mul(0x1000_0000_01b3);
|
||
}
|
||
}
|
||
h
|
||
}
|
||
|
||
#[cfg(test)]
|
||
mod tests {
|
||
use super::*;
|
||
use crate::descriptor::ParamId;
|
||
|
||
fn regions(ids: &[u32]) -> MaskSource {
|
||
MaskSource::Regions {
|
||
signature: 7,
|
||
level: 300,
|
||
ids: ids.to_vec(),
|
||
}
|
||
}
|
||
|
||
fn lit_layer(id: &str, ev: f32) -> MaskLayer {
|
||
let mut layer = MaskLayer::new(id, regions(&[1, 2]));
|
||
layer.set_param("exposure", ParamId("exposure"), ev);
|
||
layer
|
||
}
|
||
|
||
#[test]
|
||
fn a_layer_with_no_adjustment_is_not_in_the_shader() {
|
||
let layer = MaskLayer::new("m1", regions(&[1]));
|
||
assert!(!layer.is_active(), "a bare selection changes no pixel");
|
||
|
||
let mut stack = MaskStack::new();
|
||
stack.push(layer);
|
||
assert!(stack.is_neutral());
|
||
assert_eq!(compose_layers(&stack).body, "");
|
||
}
|
||
|
||
#[test]
|
||
fn a_disabled_layer_is_omitted_but_kept() {
|
||
let mut stack = MaskStack::new();
|
||
let mut layer = lit_layer("m1", 1.0);
|
||
layer.enabled = false;
|
||
stack.push(layer);
|
||
|
||
assert_eq!(stack.active_count(), 0, "disabled layers do not render");
|
||
assert_eq!(stack.len(), 1, "but they are not deleted");
|
||
}
|
||
|
||
#[test]
|
||
fn a_layer_offers_only_the_operations_it_can_actually_apply() {
|
||
// A layer's adjustments are fused into the colour dispatch and then
|
||
// multiplied by the mask. A neighbourhood operation cannot take that
|
||
// route: it is a dispatch of its own, run after the fused pass and
|
||
// after the masks are already applied, so there is nowhere to hand it
|
||
// one layer's mask.
|
||
//
|
||
// The panel builds itself from `capabilities()` and names no
|
||
// operation, so anything left in this chain becomes a control. One
|
||
// that cannot work is worse than one that is missing: it moves, the
|
||
// picture does not change, and nothing says why.
|
||
let layer = lit_layer("m1", 1.0);
|
||
let ids: Vec<&str> = layer.capabilities().iter().map(|c| c.id.0).collect();
|
||
|
||
let global = crate::ops::chain();
|
||
for op in &global {
|
||
let id = op.descriptor().id.0;
|
||
assert_eq!(
|
||
ids.contains(&id),
|
||
op.detail().is_none(),
|
||
"{id} is offered as a local adjustment but cannot be one, \
|
||
or is a point operation and has gone missing from a layer"
|
||
);
|
||
}
|
||
assert!(
|
||
ids.len() < global.len() || global.iter().all(|o| o.detail().is_none()),
|
||
"the filter dropped nothing, so either it is not running or the \
|
||
chain has no neighbourhood operation left to drop"
|
||
);
|
||
|
||
// And a clone must rebuild the same chain: it copies parameters across
|
||
// by position, so a chain built one way and rebuilt another would
|
||
// silently apply each value to the wrong operation.
|
||
let cloned: Vec<&str> = layer
|
||
.clone()
|
||
.capabilities()
|
||
.iter()
|
||
.map(|c| c.id.0)
|
||
.collect();
|
||
assert_eq!(ids, cloned);
|
||
}
|
||
|
||
#[test]
|
||
fn zero_opacity_is_inactive() {
|
||
let mut layer = lit_layer("m1", 1.0);
|
||
layer.opacity = 0.0;
|
||
assert!(!layer.is_active());
|
||
}
|
||
|
||
#[test]
|
||
fn the_generated_block_reads_its_own_mask_slot() {
|
||
let mut stack = MaskStack::new();
|
||
stack.push(lit_layer("m1", 1.0));
|
||
stack.push(lit_layer("m2", -1.0));
|
||
|
||
let shader = compose_layers(&stack);
|
||
assert!(shader.body.contains("sample_mask(uv_src, 0)"));
|
||
assert!(shader.body.contains("sample_mask(uv_src, 1)"));
|
||
assert!(shader.body.contains("u.mask0_opacity"));
|
||
assert!(shader.body.contains("u.mask1_opacity"));
|
||
}
|
||
|
||
/// The slot a layer renders through must follow `active()`, not the raw
|
||
/// index — otherwise disabling layer 0 silently shifts every mask.
|
||
#[test]
|
||
fn slots_follow_active_order_not_stack_order() {
|
||
let mut stack = MaskStack::new();
|
||
let mut off = lit_layer("m1", 1.0);
|
||
off.enabled = false;
|
||
stack.push(off);
|
||
stack.push(lit_layer("m2", -1.0));
|
||
|
||
let shader = compose_layers(&stack);
|
||
assert!(
|
||
shader.body.contains("sample_mask(uv_src, 0)"),
|
||
"the one active layer must use slot 0, not slot 1"
|
||
);
|
||
assert!(!shader.body.contains("sample_mask(uv_src, 1)"));
|
||
}
|
||
|
||
#[test]
|
||
fn each_layer_gets_its_own_uniforms() {
|
||
let mut stack = MaskStack::new();
|
||
stack.push(lit_layer("m1", 1.0));
|
||
stack.push(lit_layer("m2", -1.0));
|
||
|
||
let shader = compose_layers(&stack);
|
||
assert!(shader.uniform_fields.contains("mask0_exposure_"));
|
||
assert!(shader.uniform_fields.contains("mask1_exposure_"));
|
||
assert_eq!(
|
||
shader.uniform_values.len(),
|
||
shader
|
||
.uniform_fields
|
||
.lines()
|
||
.filter(|l| l.trim_start().starts_with("mask"))
|
||
.count(),
|
||
"one value per emitted field"
|
||
);
|
||
}
|
||
|
||
#[test]
|
||
fn the_inner_block_shadows_c_and_copies_back() {
|
||
let mut stack = MaskStack::new();
|
||
stack.push(lit_layer("m1", 1.0));
|
||
let body = compose_layers(&stack).body;
|
||
|
||
assert!(body.contains("var masked = c;"));
|
||
assert!(body.contains("var c = masked;"));
|
||
assert!(body.contains("masked = c;"));
|
||
assert!(body.contains("c = mix(c, masked, m);"));
|
||
}
|
||
|
||
#[test]
|
||
fn a_full_stack_refuses_rather_than_dropping_work() {
|
||
let mut stack = MaskStack::new();
|
||
for i in 0..MAX_LAYERS {
|
||
assert!(stack.push(lit_layer(&format!("m{i}"), 1.0)));
|
||
}
|
||
assert!(!stack.push(lit_layer("overflow", 1.0)));
|
||
assert_eq!(stack.len(), MAX_LAYERS);
|
||
assert!(stack.get("overflow").is_none());
|
||
}
|
||
|
||
#[test]
|
||
fn ids_do_not_collide() {
|
||
let mut stack = MaskStack::new();
|
||
assert_eq!(stack.next_id(), "m1");
|
||
stack.push(MaskLayer::new("m1", regions(&[1])));
|
||
assert_eq!(stack.next_id(), "m2");
|
||
}
|
||
|
||
#[test]
|
||
fn a_layer_from_another_segmentation_is_stale() {
|
||
let layer = MaskLayer::new("m1", regions(&[1]));
|
||
assert!(!layer.is_stale(7), "same signature is fine");
|
||
assert!(layer.is_stale(8), "a retuned segmentation invalidates ids");
|
||
|
||
// A gradient has no region ids, so nothing can go stale about it.
|
||
let grad = MaskLayer::new(
|
||
"m2",
|
||
MaskSource::Linear {
|
||
centre: (0.5, 0.5),
|
||
angle: 0.0,
|
||
width: 0.2,
|
||
},
|
||
);
|
||
assert!(!grad.is_stale(999));
|
||
}
|
||
|
||
#[test]
|
||
fn signatures_separate_what_changes_a_region_id() {
|
||
let base = segmentation_signature(1600, 1067, 6730, 2);
|
||
assert_eq!(base, segmentation_signature(1600, 1067, 6730, 2));
|
||
assert_ne!(base, segmentation_signature(1600, 1067, 6730, 5), "tuning");
|
||
assert_ne!(
|
||
base,
|
||
segmentation_signature(800, 1067, 6730, 2),
|
||
"proxy size"
|
||
);
|
||
assert_ne!(
|
||
base,
|
||
segmentation_signature(1600, 1067, 42, 2),
|
||
"region count"
|
||
);
|
||
}
|
||
|
||
#[test]
|
||
fn cloning_copies_parameters_not_handles() {
|
||
let layer = lit_layer("m1", 1.5);
|
||
let mut copy = layer.clone();
|
||
assert_eq!(copy, layer);
|
||
|
||
copy.set_param("exposure", ParamId("exposure"), -1.0);
|
||
assert_ne!(copy, layer, "the clone edits independently");
|
||
}
|
||
|
||
#[test]
|
||
fn params_reports_only_what_moved() {
|
||
let layer = lit_layer("m1", 1.25);
|
||
let moved: Vec<_> = layer.params().collect();
|
||
assert_eq!(moved, vec![("exposure", "exposure", 1.25)]);
|
||
}
|
||
|
||
fn painted(id: &str) -> MaskLayer {
|
||
let mut layer = MaskLayer::new(id, MaskSource::brush());
|
||
layer.set_param("exposure", ParamId("exposure"), 1.0);
|
||
layer
|
||
}
|
||
|
||
/// A gesture: press, drag along `path`, release.
|
||
fn paint(layer: &mut MaskLayer, erase: bool, radius: f32, path: &[(f32, f32)]) {
|
||
layer.begin_stroke(erase, radius, 0.5, 1.0);
|
||
for &(x, y) in path {
|
||
layer.extend_stroke(x, y);
|
||
}
|
||
layer.end_stroke();
|
||
}
|
||
|
||
#[test]
|
||
fn a_brush_layer_is_never_stale() {
|
||
let mut layer = painted("m1");
|
||
paint(&mut layer, false, 0.05, &[(0.2, 0.2), (0.8, 0.8)]);
|
||
assert!(
|
||
!layer.is_stale(12345),
|
||
"strokes are where the user put them, not where a model found something"
|
||
);
|
||
}
|
||
|
||
/// The failure this prevents is loud and total: `invert` turns an empty
|
||
/// mask into the whole frame, so an unpainted layer that rendered would
|
||
/// apply its adjustment to the entire photograph.
|
||
#[test]
|
||
fn an_unpainted_brush_layer_is_not_active() {
|
||
let mut layer = painted("m1");
|
||
assert!(!layer.is_active(), "nothing has been painted yet");
|
||
|
||
paint(&mut layer, false, 0.05, &[(0.5, 0.5)]);
|
||
assert!(layer.is_active(), "one dab is a mask");
|
||
}
|
||
|
||
#[test]
|
||
fn a_layer_of_nothing_but_erasing_is_not_active() {
|
||
let mut layer = painted("m1");
|
||
paint(&mut layer, true, 0.05, &[(0.5, 0.5)]);
|
||
assert!(
|
||
!layer.is_active(),
|
||
"erasing an unpainted layer takes nothing away"
|
||
);
|
||
}
|
||
|
||
/// A press with no movement is a tap, and a tap paints one dab. Dropping
|
||
/// it as "no path" would make a brush that ignores the shortest stroke
|
||
/// there is.
|
||
#[test]
|
||
fn a_tap_is_a_stroke() {
|
||
let mut layer = painted("m1");
|
||
paint(&mut layer, false, 0.05, &[(0.5, 0.5)]);
|
||
assert_eq!(layer.strokes().len(), 1);
|
||
assert_eq!(layer.strokes()[0].points, vec![(0.5, 0.5)]);
|
||
}
|
||
|
||
/// A finger held still reports position after position at the same place.
|
||
/// Left in, they would fill the stroke and be rasterised every frame until
|
||
/// the gesture ended.
|
||
#[test]
|
||
fn a_stationary_finger_does_not_fill_the_stroke() {
|
||
let mut layer = painted("m1");
|
||
layer.begin_stroke(false, 0.05, 0.5, 1.0);
|
||
for _ in 0..200 {
|
||
layer.extend_stroke(0.5, 0.5);
|
||
}
|
||
layer.end_stroke();
|
||
assert_eq!(layer.strokes()[0].len(), 1);
|
||
}
|
||
|
||
#[test]
|
||
fn simplifying_keeps_the_shape_and_drops_the_rest() {
|
||
let mut straight = Stroke::new(false, 0.1, 0.5, 1.0);
|
||
let mut bent = Stroke::new(false, 0.1, 0.5, 1.0);
|
||
for i in 0..=10 {
|
||
let t = i as f32 / 10.0;
|
||
straight.points.push((t, 0.5));
|
||
// A corner at the halfway point, far enough out to matter.
|
||
bent.points.push((t, 0.5 + (0.5 - (t - 0.5).abs()) * 0.5));
|
||
}
|
||
|
||
straight.simplify();
|
||
assert_eq!(
|
||
straight.points,
|
||
vec![(0.0, 0.5), (1.0, 0.5)],
|
||
"a straight line is two points however finely it was sampled"
|
||
);
|
||
|
||
bent.simplify();
|
||
assert_eq!(bent.len(), 3, "the corner survives");
|
||
assert!(
|
||
bent.points[1].0 > 0.4 && bent.points[1].0 < 0.6,
|
||
"and it is the corner that survived, not an arbitrary midpoint: {:?}",
|
||
bent.points
|
||
);
|
||
}
|
||
|
||
/// Tolerance follows the radius, because a swept disc cannot express
|
||
/// detail finer than its own edge — so a fat brush may throw away wobble a
|
||
/// fine one has to keep.
|
||
#[test]
|
||
fn a_fat_brush_simplifies_harder_than_a_fine_one() {
|
||
let wobble: Vec<(f32, f32)> = (0..=20)
|
||
.map(|i| {
|
||
let t = i as f32 / 20.0;
|
||
(t, 0.5 + if i % 2 == 0 { 0.004 } else { -0.004 })
|
||
})
|
||
.collect();
|
||
|
||
let mut fine = Stroke::new(false, 0.005, 0.5, 1.0);
|
||
fine.points = wobble.clone();
|
||
fine.simplify();
|
||
|
||
let mut fat = Stroke::new(false, 0.2, 0.5, 1.0);
|
||
fat.points = wobble;
|
||
fat.simplify();
|
||
|
||
assert!(
|
||
fat.len() < fine.len(),
|
||
"fat {} should keep fewer than fine {}",
|
||
fat.len(),
|
||
fine.len()
|
||
);
|
||
assert_eq!(fat.len(), 2, "the wobble is far inside a fat brush's edge");
|
||
}
|
||
|
||
/// A gesture longer than one stroke holds must continue, not stop. A brush
|
||
/// that quietly stops recording under the finger is the failure a painter
|
||
/// notices first.
|
||
#[test]
|
||
fn a_long_gesture_continues_in_another_stroke() {
|
||
let mut layer = painted("m1");
|
||
layer.begin_stroke(false, 0.001, 0.5, 1.0);
|
||
for i in 0..(MAX_STROKE_POINTS + 40) {
|
||
let t = i as f32 / (MAX_STROKE_POINTS + 40) as f32;
|
||
layer.extend_stroke(t, 0.5);
|
||
}
|
||
layer.end_stroke();
|
||
|
||
let strokes = layer.strokes();
|
||
assert!(strokes.len() > 1, "the gesture should have continued");
|
||
assert!(strokes[0].len() <= MAX_STROKE_POINTS);
|
||
assert_eq!(
|
||
strokes[0].points.last(),
|
||
strokes[1].points.first(),
|
||
"the continuation starts where the last one ended, so the swept \
|
||
path has no gap in it"
|
||
);
|
||
}
|
||
|
||
/// Refusing rather than dropping the oldest strokes, the same way the layer
|
||
/// stack refuses a ninth layer: work already on screen must not vanish.
|
||
#[test]
|
||
fn a_full_brush_layer_refuses_more_paint() {
|
||
let mut layer = painted("m1");
|
||
layer.begin_stroke(false, 0.0005, 0.5, 1.0);
|
||
// A zigzag, so simplification cannot quietly make room by throwing the
|
||
// path away — this test is about the cap, not about the tolerance.
|
||
for i in 0..(MAX_LAYER_POINTS * 4) {
|
||
let t = i as f32 / (MAX_LAYER_POINTS * 4) as f32;
|
||
layer.extend_stroke(t, if i % 2 == 0 { 0.49 } else { 0.51 });
|
||
}
|
||
layer.end_stroke();
|
||
|
||
assert!(layer.stroke_points() <= MAX_LAYER_POINTS);
|
||
assert!(
|
||
!layer.begin_stroke(false, 0.05, 0.5, 1.0),
|
||
"a full layer says so rather than making room"
|
||
);
|
||
}
|
||
|
||
#[test]
|
||
fn strokes_snap_to_the_stored_grid() {
|
||
let mut layer = painted("m1");
|
||
paint(&mut layer, false, 0.0512345, &[(0.1234567, 0.7654321)]);
|
||
|
||
let stroke = &layer.strokes()[0];
|
||
assert_eq!(stroke.points[0], (0.1235, 0.7654));
|
||
assert_eq!(stroke.radius, 0.0512);
|
||
}
|
||
|
||
/// Beginning a stroke on a gradient would be a brush painting into a mask
|
||
/// that has nowhere to put it, and silently discarding the gesture is how
|
||
/// a mode bug looks like a broken digitiser.
|
||
#[test]
|
||
fn a_stroke_on_a_layer_that_is_not_a_brush_is_refused() {
|
||
let mut layer = MaskLayer::new(
|
||
"m1",
|
||
MaskSource::Linear {
|
||
centre: (0.5, 0.5),
|
||
angle: 0.0,
|
||
width: 0.2,
|
||
},
|
||
);
|
||
assert!(!layer.begin_stroke(false, 0.05, 0.5, 1.0));
|
||
assert!(!layer.extend_stroke(0.5, 0.5));
|
||
assert!(layer.strokes().is_empty());
|
||
}
|
||
|
||
#[test]
|
||
fn an_abandoned_stroke_can_be_taken_back() {
|
||
let mut layer = painted("m1");
|
||
paint(&mut layer, false, 0.05, &[(0.2, 0.2)]);
|
||
layer.begin_stroke(false, 0.05, 0.5, 1.0);
|
||
layer.extend_stroke(0.8, 0.8);
|
||
|
||
assert_eq!(layer.strokes().len(), 2);
|
||
assert!(layer.drop_last_stroke().is_some());
|
||
assert_eq!(layer.strokes().len(), 1, "the first gesture is untouched");
|
||
}
|
||
|
||
#[test]
|
||
fn reordering_moves_a_layer_within_the_stack() {
|
||
let mut stack = MaskStack::new();
|
||
stack.push(lit_layer("m1", 1.0));
|
||
stack.push(lit_layer("m2", 1.0));
|
||
stack.push(lit_layer("m3", 1.0));
|
||
|
||
stack.move_to("m3", 0);
|
||
let order: Vec<&str> = stack.layers().iter().map(|l| l.id.as_str()).collect();
|
||
assert_eq!(order, ["m3", "m1", "m2"]);
|
||
}
|
||
|
||
#[test]
|
||
fn a_layer_offers_no_control_it_cannot_honour() {
|
||
// A layer's chain is fused into the point-operation pass, and the
|
||
// detail stage runs once afterwards over the whole frame — so a
|
||
// neighbourhood operation inside a mask has nowhere to run.
|
||
// `active_ops` has always dropped them; this is the other half, which
|
||
// stops the panel drawing a sharpening slider on a mask that would
|
||
// move and change nothing.
|
||
let layer = lit_layer("m1", 1.0);
|
||
let global: Vec<&str> = crate::EditGraph::default_chain()
|
||
.capabilities()
|
||
.iter()
|
||
.map(|c| c.id.0)
|
||
.collect();
|
||
let scoped: Vec<&str> = layer.capabilities().iter().map(|c| c.id.0).collect();
|
||
|
||
let detail: Vec<&str> = crate::ops::chain()
|
||
.iter()
|
||
.filter(|o| o.detail().is_some())
|
||
.map(|o| o.descriptor().id.0)
|
||
.collect();
|
||
assert!(
|
||
!detail.is_empty(),
|
||
"the chain has neighbourhood operations, or this proves nothing"
|
||
);
|
||
for id in detail {
|
||
assert!(global.contains(&id), "{id} is missing from the chain");
|
||
assert!(
|
||
!scoped.contains(&id),
|
||
"{id} cannot run inside a mask and must not be offered there"
|
||
);
|
||
}
|
||
}
|
||
}
|