dtourolle/DarkRoom
1
0
Fork 0
Code Issues 39 Pull Requests Actions Packages Projects Releases 20 Wiki Activity

Hold the repairs a photographer makes, and say which may share a pass

Browse Source 
A spot is a disc, a source offset and four numbers, and it lives beside
`ops` for the reason `masks` and `film` do: the operation trait is
ParamId -> f32, and a list of repairs is neither scalar nor fixed.

Two decisions here are not obvious. The id is derived from the position
rather than counted, because two devices editing offline would each mint
`spot3` for different marks and the sidecar merge would then treat two
repairs as one — from the position, two devices that removed the same
piece of dust agree, and two that removed different ones do not. And
every length is in the frame's isotropic units, not a mixture of those
and shorter-edge fractions: one unit for the radius, the feather and the
offset agrees on a landscape frame and on a portrait one, where a mixture
only agrees on the first.

`rounds` is the arithmetic that keeps a source from reading a
destination. Every spot in one pass reads the photograph as it stood
before that pass, so a spot sourcing from an earlier spot's destination
would copy the mark that spot was removing. Grouping is not a pass per
spot — that is sixty-four dispatches for a case that almost never arises
— it is a new round only when the sources actually collide.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
dtourolle
2026-08-26 19:50:00 +02:00
co-authored by Claude Opus 5
parent 8d8d6491ad
commit 97479a0512
6 changed files with 794 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
core/dr-pipeline/src/spot.rs
+492
View File
@@ -0,0 +1,492 @@
//! TRACES: FR-DEV-8
//! Spot removal — the marks a photographer paints out, as parameters.
//!
//! A spot is a disc over something unwanted, a source offset saying where the
//! replacement comes from, and the handful of numbers that decide how the two
//! are blended. No pixels are stored, here or anywhere: the shader draws the
//! repair from these numbers every time the photograph is rendered, which is
//! what makes it non-destructive, cheap to sync, and undoable
//! (`docs/spot-removal.md`).
//!
//! # Why this is not an operation
//!
//! [`crate::Operation`] is `ParamId -> f32`, and the generic machinery built on
//! that — the develop panel, the sidecar, the presets — works precisely because
//! it is true. A spot list is neither scalar nor of fixed length, so it lives
//! beside `ops` in [`crate::EditGraph`], as `framing`, `masks` and `film`
//! already do for the same reason. The trait says as much where it refuses a
//! downcast for film tables: a thing that is not a slider should not pretend to
//! be one.
//!
//! # Units, once, for all of a spot's lengths
//!
//! `centre` is in **normalised source coordinates**, the space every mask uses,
//! so a spot survives a crop, a straighten, a zoom and an export at another
//! size with no arithmetic to keep it where the dust was.
//!
//! Every *length* — the radius, the feather, the source offset — is in the
//! frame's **isotropic units**, where y spans `0..1` and x spans `0..aspect`.
//! That is [`crate::mask::MaskSource::Radial`]'s convention and it is chosen
//! here for the same reason: only in those units is a disc a disc. Normalised
//! coordinates would make a spot on a 3:2 frame an ellipse half again wider
//! than it is tall, and the source offset would point somewhere other than
//! where the photographer dragged it.
//!
//! It is deliberately *one* unit for all three. A radius in shorter-edge
//! fractions beside an offset in frame units agrees on a landscape frame and
//! silently disagrees on a portrait one, which is the kind of bug that stays
//! invisible until somebody rotates a photograph.
//!
//! # What is not decided here
//!
//! How a spot is drawn. That is `dr-gpu`, from the passes [`crate::detail`]
//! composes — this module holds the state and the two pieces of arithmetic
//! nobody downstream should have to repeat: where a spot's source is
//! ([`Spot::source`]), and which spots may share a pass ([`SpotSet::rounds`]).
use crate::operation::{canonical_bits, hash_bytes, mix, FNV_OFFSET};
/// The most spots one edit holds.
///
/// Past a few dozen marks the answer is to clean the sensor, and a bound is
/// what keeps a sidecar a file a human can still read. Pushing past it refuses
/// rather than dropping the oldest — the rule [`crate::mask::MaskStack::push`]
/// follows, for the reason it gives: work the user can see on screen must not
/// vanish without being told.
pub const MAX_SPOTS: usize = 64;
/// The furthest a source may be dragged from what it repairs, in frame units.
///
/// Half the frame's height is well past any repair a photographer makes, and it
/// bounds something that is otherwise unbounded: a detail pass declares how far
/// it reads from the pixel it writes, and for a spot that is the offset plus
/// the radius. An unbounded offset is an unbounded halo, which is a pass the
/// tile scheduler cannot plan (ARCH §5.3, `docs/spot-removal.md` §5.3).
pub const MAX_SOURCE_DISTANCE: f32 = 0.5;
/// The radius a new spot starts at, in frame units.
///
/// About 25 px on the short edge of a 24 MP frame — a dust mark. Small enough
/// that the first click on a speck usually covers it, large enough to be worth
/// clicking at all.
pub const DEFAULT_RADIUS: f32 = 0.012;
/// The smallest radius a spot may be dragged to, in frame units.
///
/// Not zero: a spot with no radius repairs nothing and reads as the tool being
/// broken rather than as a spot being small.
pub const MIN_RADIUS: f32 = 0.001;
/// The largest radius a spot may be dragged to, in frame units.
///
/// A repair wider than half the frame is not a repair, and the same bound on
/// the radius as on the offset keeps the halo arithmetic honest.
pub const MAX_RADIUS: f32 = 0.5;
/// The fraction of the radius over which a new spot's edge falls away.
///
/// Soft by default because the common repair is dust on a gradient sky, where
/// a hard edge shows as a disc even when the colour underneath it is right.
pub const DEFAULT_FEATHER: f32 = 0.35;
/// The grid every stored length and coordinate is rounded to, as a divisor.
///
/// The same value and the same reasoning as [`crate::mask::Stroke`]'s grid:
/// values are snapped on the way in *and* written at that precision, so a
/// sidecar round trip is exact rather than nearly exact, and two devices that
/// placed the same spot 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.
const SPOT_GRID: f32 = 10_000.0;
/// Round to the stored grid. See [`SPOT_GRID`].
fn snap(v: f32) -> f32 {
(v * SPOT_GRID).round() / SPOT_GRID
}
/// TRACES: FR-DEV-8
/// How a spot's patch meets what is already there.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum SpotMode {
/// Copy the source's texture and take the destination's colour and
/// brightness from the boundary. The right answer for dust on a sky, and
/// the default because that is the overwhelming majority of spots.
#[default]
Heal,
/// Copy the source, unaltered.
///
/// Kept because heal is wrong on an edge: a spot straddling a horizon
/// healed by interpolating its boundary smears the horizon's contrast
/// across the disc, and the honest tool then is a straight copy from a
/// matching part of the frame. FR-DEV-8 asks for both for this reason.
Clone,
}
impl SpotMode {
/// The name this mode is stored under. Stable: it is in every sidecar.
pub fn name(self) -> &'static str {
match self {
Self::Heal => "heal",
Self::Clone => "clone",
}
}
pub fn from_name(name: &str) -> Option<Self> {
match name {
"heal" => Some(Self::Heal),
"clone" => Some(Self::Clone),
_ => None,
}
}
}
/// TRACES: FR-DEV-8
/// One repair: what is covered, what covers it, and how the two meet.
#[derive(Debug, Clone, PartialEq)]
pub struct Spot {
/// Stable across devices — see [`Spot::derive_id`].
pub id: String,
/// What is being covered, in normalised source coordinates.
pub centre: (f32, f32),
/// Where the replacement comes from, as a displacement from `centre` in
/// frame units.
///
/// A vector rather than a second point, so that nudging a spot half a pixel
/// carries its source along instead of asking the photographer to place it
/// again. Moving the source alone is an edit to this.
pub offset: (f32, f32),
/// The radius of the disc, in frame units.
pub radius: f32,
/// The fraction of the radius over which the edge falls away, `0.0..=1.0`.
/// Zero is a hard disc.
pub feather: f32,
/// How much of the patch is laid down, `0.0..=1.0`.
///
/// Below one the repair is partial, which is how a mark is *reduced* rather
/// than removed — worth having for a blemish that is part of the subject
/// rather than dirt on the sensor.
pub opacity: f32,
pub mode: SpotMode,
/// Whether this spot draws.
///
/// Kept rather than deleted so a photographer can see what a repair was
/// doing without losing it, exactly as [`crate::mask::MaskLayer::enabled`]
/// does for a layer.
pub enabled: bool,
}
impl Spot {
/// A spot covering `centre`, sourced `offset` away, clamped to what the
/// renderer can express.
///
/// The id is derived from the position — see [`Spot::derive_id`]. A caller
/// adding to a set should go through [`SpotSet::place`], which is what
/// resolves the case of two spots landing on the same point.
pub fn new(centre: (f32, f32), offset: (f32, f32), radius: f32) -> Self {
let centre = (snap(centre.0), snap(centre.1));
Self {
id: Self::derive_id(centre),
centre,
offset: clamp_offset(offset),
radius: snap(radius.clamp(MIN_RADIUS, MAX_RADIUS)),
feather: DEFAULT_FEATHER,
opacity: 1.0,
mode: SpotMode::default(),
enabled: true,
}
}
/// TRACES: FR-NC-9
/// The id a spot at `centre` is given: a short base-36 hash of the position
/// it was placed at.
///
/// **Derived rather than counted**, which is the opposite of what
/// [`crate::mask::MaskStack::next_id`] does, and the difference is worth
/// stating. A layer is a thing a user names and reorders, so a sequence is
/// natural. A spot is not named, and two devices editing the same
/// photograph offline would each mint `spot3` for different marks — after
/// which the merge in [`crate::sidecar`] would treat two repairs as one and
/// quietly keep whichever revision was higher.
///
/// From the position, two devices that removed *the same piece of dust*
/// agree on the id and the merge resolves them as one spot — which is
/// exactly right, because it is one spot. Two devices that removed
/// different marks disagree, and both survive.
///
/// The id is minted once, at placement, and never re-derived: dragging a
/// spot moves the repair, it does not make a different one.
pub fn derive_id(centre: (f32, f32)) -> String {
let mut h = FNV_OFFSET;
h = mix(h, u64::from(canonical_bits(snap(centre.0))));
h = mix(h, u64::from(canonical_bits(snap(centre.1))));
base36(h)
}
/// Where this spot reads from, in normalised source coordinates.
///
/// `aspect` is the source's width over its height. The offset is in frame
/// units and the answer is in normalised ones, and this is the only place
/// that conversion happens on this side — a caller doing it itself would be
/// the second place, and the two would eventually disagree about which axis
/// carries the aspect.
pub fn source(&self, aspect: f32) -> (f32, f32) {
let aspect = if aspect > 0.0 { aspect } else { 1.0 };
(
self.centre.0 + self.offset.0 / aspect,
self.centre.1 + self.offset.1,
)
}
/// This spot's centre in frame units, where a disc is a disc.
pub fn frame_centre(&self, aspect: f32) -> (f32, f32) {
(self.centre.0 * aspect, self.centre.1)
}
/// How far the source is from what it repairs, in frame units.
pub fn distance(&self) -> f32 {
self.offset.0.hypot(self.offset.1)
}
/// Whether this spot changes the photograph.
///
/// A spot with no offset reads the pixel it is writing: a clone copies a
/// pixel onto itself and a heal interpolates a boundary difference that is
/// zero everywhere, so both are the identity and both would cost a pass. A
/// spot just placed and not yet given a source is in exactly that state,
/// which is why this is asked per spot rather than per set.
pub fn is_active(&self) -> bool {
self.enabled && self.radius > 0.0 && self.opacity > 0.0 && self.distance() > f32::EPSILON
}
/// Move the whole repair, source and all, to a new centre.
///
/// The id does not move with it — see [`Spot::derive_id`].
pub fn set_centre(&mut self, centre: (f32, f32)) {
self.centre = (snap(centre.0), snap(centre.1));
}
/// Move the source, leaving what is being repaired where it is.
pub fn set_offset(&mut self, offset: (f32, f32)) {
self.offset = clamp_offset(offset);
}
pub fn set_radius(&mut self, radius: f32) {
self.radius = snap(radius.clamp(MIN_RADIUS, MAX_RADIUS));
}
pub fn set_feather(&mut self, feather: f32) {
self.feather = snap(feather.clamp(0.0, 1.0));
}
pub fn set_opacity(&mut self, opacity: f32) {
self.opacity = snap(opacity.clamp(0.0, 1.0));
}
/// Fold this spot into a running hash, for the detail stage's cache key.
///
/// Every value is a parameter — a position a finger left, a number from a
/// sidecar — never a float that came back from the GPU, which is what makes
/// hashing the bit patterns sound rather than reckless (ARCH §6.13). The id
/// is in it too: two spots that swapped ids are a different edit to sync
/// even though they draw the same picture.
pub(crate) fn hash(&self, h: u64) -> u64 {
let mut h = hash_bytes(h, self.id.as_bytes());
for v in [
self.centre.0,
self.centre.1,
self.offset.0,
self.offset.1,
self.radius,
self.feather,
self.opacity,
] {
h = mix(h, u64::from(canonical_bits(v)));
}
h = hash_bytes(h, self.mode.name().as_bytes());
mix(h, u64::from(self.enabled))
}
}
/// An offset clamped to what the halo bound allows, snapped to the grid.
///
/// Clamped along its own direction rather than per axis, so a drag towards a
/// corner stops at the bound instead of sliding along it — a per-axis clamp
/// would turn a diagonal drag into an L-shaped one under the finger.
fn clamp_offset(offset: (f32, f32)) -> (f32, f32) {
let distance = offset.0.hypot(offset.1);
if distance > MAX_SOURCE_DISTANCE {
let scale = MAX_SOURCE_DISTANCE / distance;
(snap(offset.0 * scale), snap(offset.1 * scale))
} else {
(snap(offset.0), snap(offset.1))
}
}
/// A hash as base-36 digits.
///
/// Short because it becomes a sidecar key that a human reads while debugging an
/// edit that went wrong. Six digits is two thousand million ids against the
/// sixty-four an edit may hold, so a collision is not a thing that happens by
/// accident — and [`SpotSet::place`] resolves it anyway when it does.
fn base36(mut h: u64) -> String {
const DIGITS: &[u8; 36] = b"0123456789abcdefghijklmnopqrstuvwxyz";
let mut out = String::with_capacity(6);
for _ in 0..6 {
out.push(DIGITS[(h % 36) as usize] as char);
h /= 36;
}
out
}
/// TRACES: FR-DEV-8
/// Every repair on one photograph, in the order they were made.
///
/// The order is not decoration: it decides which spots may share a pass
/// ([`Self::rounds`]) and which repair sits on top where two overlap.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct SpotSet {
spots: Vec<Spot>,
}
impl SpotSet {
pub fn new() -> Self {
Self::default()
}
pub fn spots(&self) -> &[Spot] {
&self.spots
}
pub fn len(&self) -> usize {
self.spots.len()
}
pub fn is_empty(&self) -> bool {
self.spots.is_empty()
}
/// Whether this set draws nothing, and the detail stage may skip it
/// entirely.
pub fn is_neutral(&self) -> bool {
!self.spots.iter().any(Spot::is_active)
}
pub fn get(&self, id: &str) -> Option<&Spot> {
self.spots.iter().find(|s| s.id == id)
}
pub fn get_mut(&mut self, id: &str) -> Option<&mut Spot> {
self.spots.iter_mut().find(|s| s.id == id)
}
/// The spots that draw, in order.
pub fn active(&self) -> impl Iterator<Item = &Spot> {
self.spots.iter().filter(|s| s.is_active())
}
/// Add a spot, returning its id, or `None` if the set is full.
///
/// Full **refuses** rather than dropping the oldest: sixty-four repairs are
/// sixty-four decisions, and silently discarding the first to make room for
/// the sixty-fifth would undo work the photographer can see on screen.
///
/// A spot placed on top of an existing one is given a distinct id by
/// salting the hash, so the set never holds two spots under one name. This
/// is rare by construction — the same point to a ten-thousandth of the
/// frame — and it is the one case [`Spot::derive_id`]'s determinism cannot
/// resolve on its own.
pub fn place(&mut self, mut spot: Spot) -> Option<String> {
if self.spots.len() >= MAX_SPOTS {
log::warn!("spots: {MAX_SPOTS} is the limit; refusing to place another");
return None;
}
let mut salt: u64 = 0;
while self.spots.iter().any(|s| s.id == spot.id) {
salt += 1;
let mut h = FNV_OFFSET;
h = mix(h, u64::from(canonical_bits(spot.centre.0)));
h = mix(h, u64::from(canonical_bits(spot.centre.1)));
spot.id = base36(mix(h, salt));
}
let id = spot.id.clone();
self.spots.push(spot);
Some(id)
}
/// Remove one repair.
pub fn remove(&mut self, id: &str) -> Option<Spot> {
let index = self.spots.iter().position(|s| s.id == id)?;
Some(self.spots.remove(index))
}
pub fn clear(&mut self) {
self.spots.clear();
}
/// TRACES: FR-DEV-8
/// The active spots grouped into passes, as indices into the order
/// [`Self::active`] yields.
///
/// # Why grouping is needed at all
///
/// A detail pass reads one texture and writes another, so every spot in one
/// pass reads the photograph as it stood *before* that pass. A spot whose
/// source sits on an earlier spot's destination therefore copies the very
/// mark the earlier spot was removing, and the mark reappears a few hundred
/// pixels away — which reads as the tool being broken rather than as two
/// repairs that disagree.
///
/// The fix is not a pass per spot: sixty-four dispatches for a frame that
/// needs one is a frame budget spent on a case that almost never arises.
/// Instead a spot joins the round being built unless its source disc
/// intersects the destination disc of a spot already in that round, in
/// which case it opens a new one. Spots scattered over a sky with their
/// sources beside them — the overwhelming majority — come out as a single
/// round.
///
/// Only the round being built is consulted. Earlier rounds have already
/// been applied by the time a later one runs, so reading their destinations
/// is not a hazard: it is the repaired photograph, which is exactly what a
/// source should see.
///
/// Destinations overlapping destinations is not a hazard either — both
/// write the same output and the later spot lands on top, which is the
/// order the photographer made them in.
pub fn rounds(&self, aspect: f32) -> Vec<Vec<usize>> {
let active: Vec<&Spot> = self.active().collect();
let mut rounds: Vec<Vec<usize>> = Vec::new();
let mut current: Vec<usize> = Vec::new();
for (index, spot) in active.iter().enumerate() {
let source = spot.source(aspect);
let source_frame = (source.0 * aspect, source.1);
let conflicts = current.iter().any(|&earlier| {
let other = active[earlier];
let dest = other.frame_centre(aspect);
let reach = spot.radius + other.radius;
let dx = source_frame.0 - dest.0;
let dy = source_frame.1 - dest.1;
dx * dx + dy * dy < reach * reach
});
if conflicts {
rounds.push(std::mem::take(&mut current));
}
current.push(index);
}
if !current.is_empty() {
rounds.push(current);
}
rounds
}
/// Fold the set into a running hash, for the detail stage's cache key.
///
/// The order is in it: two spots swapped is a different grouping in
/// [`Self::rounds`] and a different picture where they overlap.
pub(crate) fn hash(&self, mut h: u64) -> u64 {
for spot in &self.spots {
h = spot.hash(h);
}
mix(h, self.spots.len() as u64)
}
}