856f865cf98d
retouch_cmds.rs
//! Retouching tools as commands: Clone Stamp, Pattern Stamp, Healing Brush, Spot Healing Brush,
//! Patch, Content-Aware Move, Remove, Dodge, Burn, Sponge, Blur, Sharpen, Smudge, History Brush and
//! Art History Brush.
//!
//! Every command takes a Photoshop-style brush (`points`, `size`, `hardness`, `opacity`, `flow`,
//! `spacing`, `layer`), respects the active selection as a mask and the layer's transparency lock, and
//! works at any depth (8/16/32f) and colour model. Like the Brush, each paints the targeted surface:
//! the layer's pixels, its mask (`"target":"mask"`), an alpha channel or the Quick Mask (`"target"`,
//! filled in from the Channels panel when absent). The pixel algorithms live in `photocraft-algo`
//! (`poisson`, `inpaint`, `retouch`) and the dab machinery in `photocraft-paint::retouch`; this module
//! only parses parameters and wires them together.
use photocraft_algo::inpaint::{self, CompleteParams};
use photocraft_algo::poisson;
use photocraft_algo::retouch::{ToneRange, dodge_burn, local_blur, local_sharpen, sponge};
use photocraft_color::{BlendMode, PixelFormat, SampleType};
use photocraft_doc::{Document, LayerContent, LayerId};
use photocraft_geom::Rect;
use photocraft_paint::retouch::{Footprint, Region, Smudge, alpha_index, apply_coverage, apply_dab_stroke};
use photocraft_paint::{BrushSettings, Stroke, StrokePoint};
use photocraft_raster::{Surface, from_rgba_into, to_rgba};
use rayon::prelude::*;
use serde_json::{Value, json};
use crate::commands::{CommandSpec, blend_from_str};
use crate::{EngineError, Result, Session};
mod art_history;
mod clone_sampling;
mod content_aware_move;
mod patch;
mod pattern_stamp;
pub use pattern_stamp::{
INDEXED_REFUSAL as PATTERN_STAMP_INDEXED_REFUSAL, live_impressionist as live_pattern_impressionist, press_refusal as pattern_stamp_press_refusal,
};
mod periodic;
mod remove;
pub use content_aware_move::{ContentAwarePreview, preview as content_aware_move_preview};
pub use patch::preview as patch_preview;
fn bad(cmd: &str, msg: impl Into<String>) -> EngineError {
EngineError::BadParams { cmd: cmd.into(), msg: msg.into() }
}
/// A single stroke's accumulated coverage must stay at or under this many pixels (8192², so a
/// stroke corner to corner across a 24–36 MP canvas fits). Larger footprints return an error
/// instead of allocating.
const MAX_STROKE_PIXELS: u64 = 67_108_864;
/// Refuse a stroke whose footprint would not fit the coverage budget, from the points and brush
/// size alone, before the renderer allocates anything for it.
fn reject_huge_stroke(cmd: &str, stroke: &Stroke) -> Result<()> {
// Dynamics place dabs beyond the input points, so half the tip is not the whole reach:
// Scattering offsets a centre by up to its amount times the tip size, and a Dual Brush dab
// reaches its own radius further. Pad by what those can add so this estimate does not fall
// short of what the renderer will cover. It is only the cheap early-out; the rendered extent
// is admitted for real in `coverage` below.
let b = &stroke.brush;
let size = f64::from(b.size.max(1.0));
let scatter = if b.scattering.enabled { size * f64::from(b.scattering.scatter.jitter.max(0.0)) } else { 0.0 };
let dual = if b.dual_brush.enabled { f64::from(b.dual_brush.size.max(0.0)) * 0.5 } else { 0.0 };
let pad = size.mul_add(0.5, 4.0) + scatter + dual;
let mut min_x = f64::INFINITY;
let mut min_y = f64::INFINITY;
let mut max_x = f64::NEG_INFINITY;
let mut max_y = f64::NEG_INFINITY;
for q in &stroke.points {
min_x = min_x.min(q.x);
min_y = min_y.min(q.y);
max_x = max_x.max(q.x);
max_y = max_y.max(q.y);
}
if !min_x.is_finite() || !min_y.is_finite() || !max_x.is_finite() || !max_y.is_finite() {
return Err(bad(cmd, "point coordinates must be finite"));
}
let w = (max_x - min_x + pad * 2.0).ceil().max(1.0);
let h = (max_y - min_y + pad * 2.0).ceil().max(1.0);
if !w.is_finite() || !h.is_finite() || w > 1.0e9 || h > 1.0e9 {
return Err(bad(cmd, format!("stroke too large (at most {MAX_STROKE_PIXELS} px)")));
}
let area = (w as u64).saturating_mul(h as u64);
if area > MAX_STROKE_PIXELS {
return Err(bad(cmd, format!("stroke too large ({w:.0}×{h:.0} px, at most {MAX_STROKE_PIXELS})")));
}
Ok(())
}
/// The stroke's coverage, with the **rendered** extent admitted before the dense buffer exists.
///
/// `reject_huge_stroke` estimates from the input points; this is the real bound. Rendering is
/// tiled, so it holds only the tiles the dabs touch; the extent is read from those tiles once
/// every dab is placed (tips, dynamics and scattering included) and checked against `max`, and
/// only a stroke that fits is made dense. `max` is a parameter so tests can inject a small budget.
fn coverage_within(cmd: &str, stroke: &Stroke, max: u64) -> Result<(Rect, Vec<f32>)> {
photocraft_paint::retouch::stroke_coverage_within(stroke, max).ok_or_else(|| bad(cmd, format!("stroke too large (at most {max} px)")))
}
/// [`coverage_within`] at the shared allowance.
fn coverage(cmd: &str, stroke: &Stroke) -> Result<(Rect, Vec<f32>)> {
coverage_within(cmd, stroke, MAX_STROKE_PIXELS)
}
/// A pixel layer, a layer with a mask, or a targeted alpha channel / Quick Mask (as the Brush).
fn has_pixel_layer(s: &Session) -> std::result::Result<(), String> {
if crate::channel_cmds::edits_channel(s) {
return Ok(());
}
let d = s.active().ok_or("no document open")?;
let l = d.active_layer.and_then(|id| d.doc.layer(id)).ok_or("no active layer")?;
if matches!(l.content, LayerContent::Raster(_)) || l.mask.is_some() {
Ok(())
} else {
Err(format!("active layer is {} {} layer, not a pixel layer", l.content.article(), l.content.kind_name()))
}
}
/// The stroke paints layer pixels (not a mask or channel), so other layers can be sampled.
fn targets_pixels(p: &Value) -> bool {
crate::channel_cmds::target_of(p) == crate::channel_cmds::Target::Pixels
}
fn num(p: &Value, k: &str, d: f32) -> f32 {
p.get(k).and_then(Value::as_f64).map_or(d, |v| v as f32)
}
fn flag(p: &Value, k: &str, d: bool) -> bool {
p.get(k).and_then(Value::as_bool).unwrap_or(d)
}
fn string<'a>(p: &'a Value, k: &str, d: &'a str) -> &'a str {
p.get(k).and_then(Value::as_str).unwrap_or(d)
}
fn point(p: &Value, k: &str) -> Option<(f64, f64)> {
let a = p.get(k)?.as_array()?;
Some((a.first()?.as_f64()?, a.get(1)?.as_f64()?))
}
/// The brush a retouching stroke paints with: the tool's brush (`base`, its tip, hardness and
/// shape dynamics) with the shared params of `p` applied. UI previews of a stroke (the Spot Healing
/// Brush's trail) render their coverage with it, so they match what the command changes.
pub fn stroke_brush(base: &BrushSettings, p: &Value) -> BrushSettings {
let pct = |k: &str, d: f32, lo: f32, hi: f32| num(p, k, d).clamp(lo, hi) / 100.0;
BrushSettings {
size: num(p, "size", base.size).max(1.0),
hardness: pct("hardness", base.hardness * 100.0, 0.0, 100.0),
opacity: pct("opacity", 100.0, 1.0, 100.0),
flow: pct("flow", 100.0, 1.0, 100.0),
// Brush Settings › Brush Tip Shape › Spacing, as the Brush uses it (#2140).
spacing: pct("spacing", base.spacing * 100.0, 1.0, 1000.0),
// The options bar's Smoothing; the UI sends 0 for a ⇧-click line, which isn't smoothed (#11887).
smoothing: match p.get("smoothing") {
Some(_) => photocraft_paint::Smoothing { enabled: true, amount: pct("smoothing", 0.0, 0.0, 100.0), ..base.smoothing.clone() },
None => base.smoothing.clone(),
},
erase: false,
..base.clone()
}
}
/// Parse the shared brush params into a stroke on a layer (`None` when an alpha channel or the
/// Quick Mask is targeted).
fn parse_brush(s: &Session, p: &Value, cmd: &str) -> Result<(Stroke, Option<LayerId>)> {
let pts: Vec<StrokePoint> = p
.get("points")
.and_then(Value::as_array)
.ok_or_else(|| bad(cmd, "missing `points`"))?
.iter()
.filter_map(|v| {
let a = v.as_array()?;
Some(StrokePoint::new(a.first()?.as_f64()?, a.get(1)?.as_f64()?, a.get(2).and_then(Value::as_f64).unwrap_or(1.0) as f32))
})
.collect();
if pts.is_empty() {
return Err(bad(cmd, "`points` is empty"));
}
crate::brush_cmds::check_coords(&pts, cmd)?;
// A History Brush stroke carries the brush it was pressed with (`"brush"`, deep-merged onto the
// session brush as `paint.stroke`'s is): a tool key mid-stroke changes the session brush, and
// the commit, its fallback and a replayed action must all paint what the press began.
let base = match p.get("brush").filter(|v| v.is_object()) {
Some(patch) if cmd == "paint.historyBrush" => {
let mut b = crate::brush_cmds::merge_brush(&s.tools.brush, patch, cmd)?;
s.load_brush_tips(&mut b).map_err(|e| bad(cmd, e))?;
b
}
_ => s.tools.brush.clone(),
};
let mut brush = stroke_brush(&base, p);
// The Eraser's Erase to History in Pencil or Block mode paints back through that hard tip.
if flag(p, "eraseToHistory", false) && (flag(p, "pencil", false) || flag(p, "block", false)) {
brush = crate::brush_cmds::pencil_shape(brush, p)?;
}
crate::brush_cmds::validate_brush(&brush, cmd)?;
if crate::channel_cmds::is_channel_target(p) {
return Ok((Stroke { brush, points: pts }, None));
}
let id = crate::commands::layer_param(s, p)?;
Ok((Stroke { brush, points: pts }, Some(id)))
}
/// Run `f` on the targeted surface (layer pixels, layer mask, alpha channel or Quick Mask: the
/// Brush's paint target) inside one undoable step. `f` gets the pre-stroke document (a cheap
/// copy-on-write snapshot), the surface, the selection and the transparency lock.
fn run_stroke(
s: &mut Session,
label: &str,
id: Option<LayerId>,
p: &Value,
f: impl FnOnce(&Document, &mut Surface, Option<&Surface>, bool) -> Result<Rect>,
) -> Result<Rect> {
let dmg = s.edit(label, |doc, _| {
let pre = doc.clone();
let (surf, lock) = crate::channel_cmds::target_surface(doc, id, p)?;
// No prune: retouching only rewrites pixels inside the stroke, and scanning every tile of a
// large layer would dominate the cost of a dab.
f(&pre, surf, pre.selection.as_ref(), lock)
})?;
s.hint_damage(dmg);
Ok(dmg)
}
fn damage_json(r: Rect) -> Value {
json!([r.x0, r.y0, r.width(), r.height()])
}
// ---------------------------------------------------------------------------------------------
// Registry
// ---------------------------------------------------------------------------------------------
/// The brush every retouching command shares, plus the tool's own params.
macro_rules! brush_params {
($extra:literal) => {
concat!("{", r#""points":[[x,y,pressure?],…],"size":1..5000 px=tool size,"hardness":0..100=tool hardness,"opacity":1..100=100,"flow":1..100=100,"spacing":1..1000 (% of size)=Brush Settings spacing,"smoothing":0..100=options bar Smoothing,"layer":id?=active,"target":"pixels"|"mask"|"filterMask"|"quickMask"|{"channel":i}=Channels panel target"#, $extra, "}")
};
}
mod clone;
mod dab;
mod heal;
mod sampling;
pub use clone::{LiveRetouch, clone_destination_preview, clone_preview, clone_preview_periodic, healing_preview, healing_preview_periodic};
use clone::{blend_param, clamp_samples, clone_stamp};
pub(crate) use dab::DabEffect;
#[cfg(test)]
use dab::DabTool;
pub use dab::LiveDab;
use dab::dab_cmd;
#[cfg(test)]
use heal::proximity_source_patch;
use heal::{heal_region, healing_brush, history_brush, history_source, spot_healing};
use sampling::sample;
pub(crate) use sampling::{SampleLayers, composite_region};
/// Retouching command specs.
pub fn specs() -> Vec<CommandSpec> {
vec![
CommandSpec {
id: "paint.cloneStamp",
label: "Clone Stamp",
menu: &[],
shortcut: None,
params: brush_params!(
r#","source":[sx,sy] (sampled under the first point) | "offset":[dx,dy],"aligned":bool=true,"sampleLayer":"current|currentAndBelow|all"="current","sourceLayer":id? (Current Layer: this layer, else the picked slot's layer/document, else the paint target; explicit source/offset use this document),"mode":"normal|multiply|…"="normal","wrap":bool=false (repeat source and stroke at document edges for Pattern Preview) → {"damage","offset","aligned","nextSource"}"#
),
enabled: has_pixel_layer,
run: clone_stamp,
journal: true,
},
CommandSpec {
id: "paint.patternStamp",
label: "Pattern Stamp",
menu: &[],
shortcut: None,
params: brush_params!(
r#","pattern":id|name?=Patterns panel current,"scale":1..1000 %=100,"angle":deg=0,"aligned":bool=true,"impressionist":bool=false,"mode":"normal|multiply|…|behind (paints beneath existing pixels)"="normal","phase":[px,py]? → {"damage","phase","aligned","pattern"}"#
),
enabled: pattern_stamp::enabled,
run: pattern_stamp::run,
journal: true,
},
CommandSpec {
id: "paint.healingBrush",
label: "Healing Brush",
menu: &[],
shortcut: None,
params: brush_params!(
r#","source":[sx,sy] | "offset":[dx,dy],"aligned":bool=true,"sampleLayer":"current|currentAndBelow|all"="current","mode":"normal|…"="normal","wrap":bool=false (View › Pattern Preview: the stroke goes on across the canvas edges) → {"damage","offset","aligned","nextSource"}"#
),
enabled: has_pixel_layer,
run: healing_brush,
journal: true,
},
CommandSpec {
id: "paint.spotHealing",
label: "Spot Healing Brush",
menu: &[],
shortcut: None,
params: brush_params!(r#","type":"contentAware|createTexture|proximityMatch"="contentAware","sampleAllLayers":bool=false"#),
enabled: has_pixel_layer,
run: spot_healing,
journal: true,
},
CommandSpec {
id: "paint.patch",
label: "Patch",
menu: &[],
shortcut: None,
params: r#"{"offset":[dx,dy] (how far the selection was dragged),"mode":"source|destination"="source","contentAware":bool=false (fill the selection content-aware from the dragged-to place; a background job),"structure":1..7=4 (content-aware: 3..7 copy the middle exactly, 1..2 re-synthesise more of it),"color":0..10=0 (content-aware: how far the copy's level adapts to the selection's surroundings),"sampleAllLayers":bool=false (content-aware),"layer":id?=active,"target":"pixels"|"mask"|"filterMask"|"quickMask"|{"channel":i}=Channels panel target} → {"damage","offset"}"#,
enabled: patch::enabled,
run: patch::patch,
journal: true,
},
CommandSpec {
id: "paint.contentAwareMove",
label: "Content-Aware Move",
menu: &[],
shortcut: None,
params: r#"{"offset":[dx,dy] (how far the selection was dragged),"mode":"move|extend"="move","structure":1..7=4 (3..7 copy the content exactly but for a band about a patch wide along its edge; 2 widens the band, 1 re-synthesises the content too),"color":0..10=0 (0 keeps the content's level; higher values bring it towards its new place, by up to about 0.04 × color),"sampleAllLayers":bool=false,"scaleX":%=100,"scaleY":%=100 (Transform On Drop: 1..10000, negative flips),"rotate":deg=0 (Transform On Drop, clockwise; scale and rotation are about the selection's centre, before the offset; a transformed patch may reach past the canvas edge),"layer":id?=active,"target":"pixels"|"mask"|"filterMask"|"quickMask"|{"channel":i}=Channels panel target} → {"damage","offset","mode","transformed"?} (a background job; the selection moves, and is transformed, with the content)"#,
enabled: content_aware_move::enabled,
run: content_aware_move::content_aware_move,
journal: true,
},
CommandSpec {
id: "paint.remove",
label: "Remove",
menu: &[],
shortcut: None,
params: brush_params!(
r#","strokes":[[[x,y,pressure?],…]|{"points":[…],"size"?,"hardness"?,"spacing"?},…]? (several strokes removed together, as one job and one undo step, each with its own size, hardness and spacing when given; else "points"),"closeLoops":bool=true (a stroke around an object removes what it encloses),"sampleAllLayers":bool=false,"newLayer":bool=false (the fill goes to a new layer above the target, which stays as it was) → {"damage","layer"?} (a background job)"#
),
enabled: has_pixel_layer,
run: remove::remove,
journal: true,
},
CommandSpec {
id: "paint.dodge",
label: "Dodge",
menu: &[],
shortcut: None,
params: brush_params!(r#","range":"shadows|midtones|highlights"="midtones","exposure":1..100=50,"protectTones":bool=true"#),
enabled: has_pixel_layer,
run: |s, p| dab_cmd(s, p, "paint.dodge"),
journal: true,
},
CommandSpec {
id: "paint.burn",
label: "Burn",
menu: &[],
shortcut: None,
params: brush_params!(r#","range":"shadows|midtones|highlights"="midtones","exposure":1..100=50,"protectTones":bool=true"#),
enabled: has_pixel_layer,
run: |s, p| dab_cmd(s, p, "paint.burn"),
journal: true,
},
CommandSpec {
id: "paint.sponge",
label: "Sponge",
menu: &[],
shortcut: None,
params: brush_params!(r#","mode":"desaturate|saturate"="desaturate","vibrance":bool=true (flow = sponge strength)"#),
enabled: has_pixel_layer,
run: |s, p| dab_cmd(s, p, "paint.sponge"),
journal: true,
},
CommandSpec {
id: "paint.blur",
label: "Blur",
menu: &[],
shortcut: None,
params: brush_params!(r#","strength":1..100=50,"sampleAllLayers":bool=false"#),
enabled: has_pixel_layer,
run: |s, p| dab_cmd(s, p, "paint.blur"),
journal: true,
},
CommandSpec {
id: "paint.sharpen",
label: "Sharpen",
menu: &[],
shortcut: None,
params: brush_params!(r#","strength":1..100=50,"protectDetail":bool=true,"sampleAllLayers":bool=false"#),
enabled: has_pixel_layer,
run: |s, p| dab_cmd(s, p, "paint.sharpen"),
journal: true,
},
CommandSpec {
id: "paint.smudge",
label: "Smudge",
menu: &[],
shortcut: None,
params: brush_params!(
r#","strength":1..100=50,"fingerPainting":bool=false (starts with the foreground colour),"sampleAllLayers":bool=false,"mode":"normal|darken|lighten|hue|saturation|color|luminosity"="normal" (how the smudged colour replaces the pixel; 8-bit RGB, else Normal)"#
),
enabled: has_pixel_layer,
run: |s, p| dab_cmd(s, p, "paint.smudge"),
journal: true,
},
CommandSpec {
id: "paint.historyBrush",
label: "History Brush",
menu: &[],
shortcut: None,
params: brush_params!(
r#","state":row (a History panel row, as history.setSource: 0 = oldest state, then the current one, then the greyed redo states),"snapshot":id (a history.newSnapshot id; default: the History panel's source, else the oldest held state; a source of another canvas size is an error),"eraseToHistory":bool=false (a layer missing from a source state that holds a single layer paints that layer's own pixels, or a shape's solid colour, else white, outside its shape too, as the Eraser's Erase to History does, instead of an error),"pencil":bool=false and "block":bool=false with "zoom" (with eraseToHistory: the hard aliased tip or the square, as paint.pencil's),"brush":{…}? (BrushSettings fields, deep-merged onto the session brush as paint.stroke's: the brush the stroke was pressed with, so a tool picked mid-stroke changes nothing)"#
),
enabled: has_pixel_layer,
run: history_brush,
journal: true,
},
CommandSpec {
id: "paint.artHistoryBrush",
label: "Art History Brush",
menu: &[],
shortcut: None,
params: brush_params!(
r#","state":row (a History panel row, as history.setSource),"snapshot":id (a history.newSnapshot id; default: the History panel's source, as paint.historyBrush; a source of another canvas size or colour mode is an error),"style":"tightShort|tightMedium|tightLong|looseMedium|looseLong|dab|tightCurl|looseCurl"="tightShort","area":0..100=50,"tolerance":0..100=0,"opacity":0..100=100 (overrides the common 1..100: how strongly the history state is painted; 0 changes nothing; no flow, mode is Normal)"#
),
enabled: has_pixel_layer,
run: art_history::run,
journal: true,
},
]
}
#[cfg(test)]
mod tests;
#[cfg(test)]
mod clone_source_layer_tests;
#[cfg(test)]
mod patch_history_names_tests;
#[cfg(test)]
mod remove_history_name_tests;
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.