856f865cf98d
convolution.rs
//! Native5×5 channel-selective convolution with explicit edge and alpha support rules.
pub use crate::coverage::Error;
use crate::{Ctx, image::Image};
use photocraft_color::{ColorMode, PixelFormat, SampleType};
use photocraft_geom::Rect;
use photocraft_raster::{Interrupt, Surface};
use serde::{Deserialize, Serialize};
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum Edge {
Transparent,
Repeat,
Wrap,
Black,
White,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct Params {
pub kernel: Vec<f64>,
pub scale: f64,
pub offset: f64,
pub channels: Vec<bool>,
pub alpha_weighted: bool,
pub edge: Edge,
}
/// Require a finite 5-by-5 kernel, nonzero divisor and channel mask matching the actual native format.
pub fn validate(p: &Params, channels: usize) -> Result<(), Error> {
if channels == 0
|| channels > 5
|| p.channels.len() != channels
|| p.kernel.len() != 25
|| p.kernel.iter().any(|v| !v.is_finite())
|| !p.scale.is_finite()
|| p.scale == 0.
|| !p.offset.is_finite()
|| !p.kernel.iter().map(|v| v.abs()).sum::<f64>().is_finite()
{
return Err(Error::InvalidParameter);
}
Ok(())
}
/// Bound positive convolution geometry using widened arithmetic before deriving buffer sizes.
fn dimensions(r: Rect) -> Result<(usize, usize), Error> {
let w = i64::from(r.x1) - i64::from(r.x0);
let h = i64::from(r.y1) - i64::from(r.y0);
if w <= 0 || h <= 0 || w > 65536 || h > 65536 || w.checked_mul(h).is_none_or(|n| n > 64 * 1024 * 1024) {
return Err(Error::InvalidGeometry);
}
Ok((w as usize, h as usize))
}
/// Admit padded output tiles, map clones and fixed halo scratch under the existing native workspace ceiling.
fn preflight(s: &Surface, area: Rect, selection: Option<&Surface>) -> Result<(), Error> {
dimensions(area)?;
let tiles = |a: i32, b: i32| -> Result<usize, Error> {
usize::try_from((i64::from(b) - 1).div_euclid(256) - i64::from(a).div_euclid(256) + 1).map_err(|_| Error::WorkspaceLimit)
};
let bytes = tiles(area.x0, area.x1)?
.checked_mul(tiles(area.y0, area.y1)?)
.and_then(|n| n.checked_mul(256 * 256 * s.format().bytes_per_pixel() + 128))
.and_then(|n| n.checked_add(s.tile_count().checked_mul(128)?))
.and_then(|n| n.checked_add(68 * 68 * s.channels() * 4 + 64 * 64 * (s.channels() * 3 + selection.map_or(0, Surface::channels)) * 4))
.ok_or(Error::WorkspaceLimit)?;
if bytes > crate::coverage::MAX_WORKSPACE_BYTES {
return Err(Error::WorkspaceLimit);
}
Ok(())
}
/// Fill black or white edge samples in the native color model, with opaque alpha when present.
fn neutral(mode: ColorMode, white: bool, out: &mut [f32], alpha: bool) {
let color_count = out.len().saturating_sub(usize::from(alpha));
let value = if white { 1. } else { 0. };
for (c, v) in out.iter_mut().take(color_count).enumerate() {
*v = match mode {
ColorMode::Cmyk => {
if c == 3 {
1. - value
} else {
0.
}
}
ColorMode::Lab => {
if c == 0 {
value
} else {
128. / 255.
}
}
_ => value,
};
}
if alpha && let Some(v) = out.last_mut() {
*v = 1.;
}
}
/// Sample the requested native edge policy, distinguishing repeated/wrapped coordinates from transparent or neutral
/// borders.
fn sample(s: &Surface, x: i64, y: i64, domain: Rect, edge: Edge, out: &mut [f32]) -> Result<(), Error> {
let inside = x >= i64::from(domain.x0) && x < i64::from(domain.x1) && y >= i64::from(domain.y0) && y < i64::from(domain.y1);
if inside {
s.read_pixel(x as i32, y as i32, out);
return Ok(());
}
let axis = |v: i64, lo: i32, hi: i32| match edge {
Edge::Repeat => v.clamp(i64::from(lo), i64::from(hi) - 1),
Edge::Wrap => i64::from(lo) + (v - i64::from(lo)).rem_euclid(i64::from(hi) - i64::from(lo)),
_ => v,
};
match edge {
Edge::Repeat | Edge::Wrap => s.read_pixel(axis(x, domain.x0, domain.x1) as i32, axis(y, domain.y0, domain.y1) as i32, out),
Edge::Transparent => out.fill(0.),
Edge::Black => neutral(s.format().mode, false, out, s.format().alpha),
Edge::White => neutral(s.format().mode, true, out, s.format().alpha),
};
Ok(())
}
/// Apply selected kernel channels with explicit alpha support, finite-value checks and row cancellation.
fn convolve(data: &[f32], w: usize, h: usize, format: PixelFormat, p: &Params, ctl: &Interrupt<'_>) -> Result<Vec<f32>, Error> {
let ch = format.channels();
let stride = (w + 4) * ch;
if data.len() != (w + 4) * (h + 4) * ch {
return Err(Error::InvalidGeometry);
}
let mut out = Vec::new();
out.try_reserve_exact(w * h * ch).map_err(|_| Error::Allocation)?;
let weight_sum = p.kernel.iter().map(|v| v.abs()).sum::<f64>();
for y in 0..h {
if ctl.cancelled() {
return Err(Error::Cancelled);
}
for x in 0..w {
let base = (y + 2) * stride + (x + 2) * ch;
let original = data.get(base..base + ch).ok_or(Error::InvalidGeometry)?;
for (c, &before) in original.iter().enumerate() {
if !before.is_finite() {
return Err(Error::NonFiniteSample);
}
if !p.channels.get(c).copied().ok_or(Error::InvalidParameter)? {
out.push(before);
continue;
}
let alpha = format.alpha && c + 1 == ch;
let subtractive = format.mode == ColorMode::Cmyk && !alpha;
let weighted = p.alpha_weighted && format.alpha && !alpha;
let mut sum = 0f64;
let mut support = 0f64;
for (k, &coefficient) in p.kernel.iter().enumerate() {
if coefficient == 0. {
continue;
}
let i = (y + k / 5) * stride + (x + k % 5) * ch;
let pixel = data.get(i..i + ch).ok_or(Error::InvalidGeometry)?;
let mut value = f64::from(*pixel.get(c).ok_or(Error::InvalidGeometry)?);
if !value.is_finite() {
return Err(Error::NonFiniteSample);
}
if subtractive {
value = 1. - value;
}
let a = if weighted {
let a = f64::from(*pixel.last().ok_or(Error::InvalidGeometry)?);
if !a.is_finite() {
return Err(Error::NonFiniteSample);
}
a.clamp(0., 1.)
} else {
1.
};
sum += coefficient * value * a;
support += coefficient.abs() * a;
}
if !sum.is_finite() || !support.is_finite() {
return Err(Error::NonFiniteSample);
}
// Absolute support avoids division by signed/zero convolved alpha. Empty
// support retains hidden color; a zero kernel deliberately produces offset.
let result = if weighted && weight_sum > 0. && support <= weight_sum * 1e-12 {
f64::from(before)
} else {
if weighted && weight_sum > 0. {
sum *= weight_sum / support;
}
let result = sum / p.scale + p.offset;
if subtractive { 1. - result } else { result }
};
if !result.is_finite() || result.abs() > f64::from(f32::MAX) {
return Err(Error::NonFiniteSample);
}
out.push(if alpha { result.clamp(0., 1.) as f32 } else { result as f32 });
}
}
}
Ok(out)
}
/// Selection changes publication only; the complete owner supplies the stencil.
pub fn apply_with(s: &Surface, p: &Params, area: Rect, domain: Rect, selection: Option<&Surface>, ctl: &Interrupt<'_>) -> Result<Surface, Error> {
validate(p, s.channels())?;
// Edge sampling does not allocate the domain; preflight bounds the output area.
if domain.is_empty() {
return Err(Error::InvalidGeometry);
}
if ctl.cancelled() {
return Err(Error::Cancelled);
}
if area.x1 < area.x0 || area.y1 < area.y0 {
return Err(Error::InvalidGeometry);
}
let area = area.intersect(&domain);
if area.is_empty() {
return Ok(s.clone());
}
preflight(s, area, selection)?;
let ch = s.channels();
let mut result = s.clone();
let mut y = area.y0;
while y < area.y1 {
let y1 = (i64::from(y) + 64).min(i64::from(area.y1)) as i32;
let mut x = area.x0;
while x < area.x1 {
if ctl.cancelled() {
return Err(Error::Cancelled);
}
let x1 = (i64::from(x) + 64).min(i64::from(area.x1)) as i32;
let tile = Rect::new(x, y, x1, y1);
let (w, h) = dimensions(tile)?;
let mut data = Vec::new();
data.try_reserve_exact((w + 4) * (h + 4) * ch).map_err(|_| Error::Allocation)?;
for yy in i64::from(y) - 2..i64::from(y1) + 2 {
if ctl.cancelled() {
return Err(Error::Cancelled);
}
for xx in i64::from(x) - 2..i64::from(x1) + 2 {
let mut pixel = [0.; 5];
let target = pixel.get_mut(..ch).ok_or(Error::InvalidGeometry)?;
sample(s, xx, yy, domain, p.edge, target)?;
data.extend_from_slice(target);
}
}
let mut filtered = convolve(&data, w, h, s.format(), p, ctl)?;
drop(data);
if let Some(selection) = selection {
let mask = selection.try_read_region(tile).map_err(|_| Error::Allocation)?;
if mask.iter().any(|v| !v.is_finite()) {
return Err(Error::NonFiniteSample);
}
let original = Image { rect: tile, ch, data: s.try_read_region(tile).map_err(|_| Error::Allocation)? };
crate::mix_selection(&mut filtered, tile, selection, &original, s.format().alpha);
for (pixel, before) in filtered.chunks_exact_mut(ch).zip(original.data.chunks_exact(ch)) {
for ((value, original), selected) in pixel.iter_mut().zip(before).zip(&p.channels) {
if !selected {
*value = *original;
}
}
}
}
if filtered.iter().any(|v| !v.is_finite()) {
return Err(Error::NonFiniteSample);
}
result.try_write_region(tile, &filtered).map_err(|_| Error::Allocation)?;
x = x1;
}
y = y1;
ctl.progress((i64::from(y) - i64::from(area.y0)) as f32 / (i64::from(area.y1) - i64::from(area.y0)) as f32);
}
if ctl.cancelled() {
return Err(Error::Cancelled);
}
Ok(result)
}
/// Bridge raw float images to checked convolution and use bounded identity output when admission fails.
pub(crate) fn run_image(src: &Image, out: Rect, ctx: &Ctx, p: &Params) -> Vec<f32> {
let identity = || -> Result<Vec<f32>, Error> {
let (w, h) = dimensions(src.rect)?;
let (ow, oh) = dimensions(out)?;
if src.ch == 0 || src.ch > 5 || out.intersect(&src.rect) != out || w.checked_mul(h).and_then(|n| n.checked_mul(src.ch)) != Some(src.data.len()) {
return Err(Error::InvalidGeometry);
}
let mut result = Vec::new();
result.try_reserve_exact(ow * oh * src.ch).map_err(|_| Error::Allocation)?;
for y in out.y0..out.y1 {
let i = ((i64::from(y) - i64::from(src.rect.y0)) as usize * w + (i64::from(out.x0) - i64::from(src.rect.x0)) as usize) * src.ch;
result.extend_from_slice(src.data.get(i..i + ow * src.ch).ok_or(Error::InvalidGeometry)?);
}
Ok(result)
};
let run = || -> Result<Vec<f32>, Error> {
validate(p, src.ch)?;
let (w, h) = dimensions(src.rect)?;
dimensions(out)?;
if out.intersect(&src.rect) != out {
return Err(Error::InvalidGeometry);
}
if src.data.len() > 64 * 1024 * 1024 || w.checked_mul(h).and_then(|n| n.checked_mul(src.ch)) != Some(src.data.len()) {
return Err(Error::WorkspaceLimit);
}
let format = PixelFormat::new(ctx.mode, SampleType::F32, ctx.alpha);
if format.channels() != src.ch {
return Err(Error::InvalidGeometry);
}
let mut s = Surface::new(format);
s.try_write_region(src.rect, &src.data).map_err(|_| Error::Allocation)?;
apply_with(&s, p, out, src.rect, None, &Interrupt::NONE)?.try_read_region(out).map_err(|_| Error::Allocation)
};
run().unwrap_or_else(|_| identity().unwrap_or_default())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
/// Retain every convolution edge policy on a large owner without admitting oversized output work.
fn small_convolution_area_in_large_domain_keeps_edge_sampling_and_work_bounds() {
let area = Rect::new(0, 0, 1, 1);
let mut s = Surface::new(PixelFormat::RGBA32F);
s.fill_rect(area, &[0.2, 0.4, 0.6, 1.]);
let domain = Rect::new(0, 0, 9_000, 9_000);
let mut p = params(4);
p.kernel[12] = 0.;
p.kernel[11] = 1.;
for edge in [Edge::Repeat, Edge::Wrap, Edge::Transparent, Edge::Black, Edge::White] {
p.edge = edge;
let got = apply_with(&s, &p, area, domain, None, &Interrupt::NONE).unwrap();
let mut expected = [0.; 4];
sample(&s, -1, 0, domain, edge, &mut expected).unwrap();
assert_eq!(got.pixel(0, 0), expected, "{edge:?}");
}
assert_eq!(apply_with(&s, &p, domain, domain, None, &Interrupt::NONE), Err(Error::InvalidGeometry));
assert_eq!(apply_with(&s, &p, area, Rect::new(0, 0, 0, 1), None, &Interrupt::NONE), Err(Error::InvalidGeometry));
}
/// Define the native custom-filter fixture kernel independently of imported source configuration.
fn params(ch: usize) -> Params {
let mut k = vec![0.; 25];
k[12] = 1.;
Params { kernel: k, scale: 1., offset: 0., channels: vec![true; ch], alpha_weighted: false, edge: Edge::Repeat }
}
/// Populate a native-format test surface with original samples for cross-depth counterpart comparisons.
fn surface(mode: ColorMode, depth: SampleType, r: Rect) -> Surface {
let fmt = PixelFormat::new(mode, depth, true);
let mut s = Surface::new(fmt);
let data: Vec<f32> = (0..r.width() as usize * r.height() as usize * fmt.channels())
.map(|i| if depth == SampleType::F32 { (i % 31) as f32 / 9. - 1. } else { (i % 31) as f32 / 30. })
.collect();
s.try_write_region(r, &data).unwrap();
s
}
#[test]
/// Compare the checked kernel with the existing native Custom filter's row-major brightness policy.
fn native_custom_counterpart_matches_row_major_brightness_at_every_depth_and_model() {
let r = Rect::new(-3, -3, 10, 9);
let out = Rect::new(0, 0, 7, 6);
for mode in [
ColorMode::Bitmap,
ColorMode::Grayscale,
ColorMode::Indexed,
ColorMode::Rgb,
ColorMode::Cmyk,
ColorMode::Lab,
ColorMode::Multichannel,
ColorMode::Duotone,
] {
for depth in [SampleType::U8, SampleType::U16, SampleType::F32] {
let s = surface(mode, depth, r);
let mut p = params(s.channels());
p.kernel[12] = 2.;
p.kernel[6] = -0.25;
p.kernel[19] = 0.5;
p.scale = 2.25;
p.offset = 0.125;
p.channels[s.channels() - 1] = false;
let input = Image::read(&s, r);
let kernel: Vec<f32> = p.kernel.iter().map(|v| *v as f32).collect();
let expected = crate::other2::custom(&input, out, &Ctx { bounds: r, mode, alpha: true }, &kernel, p.scale as f32, p.offset as f32 * 255.);
let mut native = Surface::new(s.format());
native.try_write_region(out, &expected).unwrap();
let got = apply_with(&s, &p, out, r, None, &Interrupt::NONE).unwrap().read_region(out);
for (a, b) in got.iter().zip(native.read_region(out)) {
assert!((a - b).abs() < 2. / 65535., "{mode:?} {depth:?} {a}/{b}");
}
}
}
}
#[test]
/// Exercise signed kernels and missing alpha support without inventing nonfinite hidden HDR samples.
fn signed_alpha_weighting_and_empty_support_preserve_finite_hidden_hdr() {
let r = Rect::new(0, 0, 3, 1);
let mut s = Surface::new(PixelFormat::new(ColorMode::Rgb, SampleType::F32, true));
s.try_write_region(r, &[1000., -1000., 2., 0., 4., -2., 0.5, 0.5, 8., 3., 0.25, 1.]).unwrap();
let mut p = params(4);
p.kernel[12] = 2.;
p.kernel[11] = -1.;
p.alpha_weighted = true;
p.channels = vec![true, false, true, true];
let got = apply_with(&s, &p, r, r, None, &Interrupt::NONE).unwrap();
assert_eq!(got.pixel(1, 0), vec![12., -2., 1.5, 1.]);
s.fill_rect(r, &[-2., 3., 0.4, 0.]);
let before = s.clone();
let got = apply_with(&s, &p, r, r, None, &Interrupt::NONE).unwrap();
assert_eq!(got.read_region(r), before.read_region(r));
p.kernel.fill(0.);
p.offset = 0.25;
let got = apply_with(&s, &p, r, r, None, &Interrupt::NONE).unwrap();
assert_eq!(got.pixel(1, 0), vec![0.25, 3., 0.25, 0.25]);
}
#[test]
/// Check border policies, native neutral colors and actual scalar/alpha channel selections.
fn explicit_edges_neutral_models_and_alpha_scalar_channel_masks() {
let r = Rect::new(0, 0, 1, 1);
for mode in [ColorMode::Rgb, ColorMode::Grayscale, ColorMode::Cmyk, ColorMode::Lab] {
let mut s = Surface::new(PixelFormat::new(mode, SampleType::F32, true));
s.fill_rect(r, &vec![0.4; s.channels()]);
let mut p = params(s.channels());
p.kernel.fill(0.);
p.kernel[11] = 1.;
for edge in [Edge::Repeat, Edge::Wrap, Edge::Transparent, Edge::Black, Edge::White] {
p.edge = edge;
let got = apply_with(&s, &p, r, r, None, &Interrupt::NONE).unwrap().pixel(0, 0);
let mut expected = vec![0.; s.channels()];
match edge {
Edge::Repeat | Edge::Wrap => expected.fill(0.4),
Edge::Transparent => {}
Edge::Black => neutral(mode, false, &mut expected, true),
Edge::White => neutral(mode, true, &mut expected, true),
}
assert_eq!(got, expected, "{mode:?} {edge:?}");
}
}
}
#[test]
/// Verify tiled selection output while cancellation and numeric failure cannot modify the original input.
fn tiling_selection_mid_cancel_and_numeric_failures_are_atomic() {
let r = Rect::new(-2, 4, 132, 12);
let s = surface(ColorMode::Rgb, SampleType::F32, r);
let before = s.clone();
let mut p = params(4);
p.kernel[12] = 0.5;
p.kernel[11] = 0.5;
p.channels[3] = false;
let got = apply_with(&s, &p, r, r, None, &Interrupt::NONE).unwrap();
let crop = Rect::new(60, 5, 68, 11);
assert_eq!(apply_with(&s, &p, crop, r, None, &Interrupt::NONE).unwrap().read_region(crop), got.read_region(crop));
let mask = Surface::new(PixelFormat::new(ColorMode::Grayscale, SampleType::F32, false));
assert_eq!(apply_with(&s, &p, r, r, Some(&mask), &Interrupt::NONE).unwrap(), s);
let count = std::sync::atomic::AtomicUsize::new(0);
let cancel = || count.fetch_add(1, std::sync::atomic::Ordering::Relaxed) > 8;
assert_eq!(apply_with(&s, &p, r, r, None, &Interrupt::cancel_only(&cancel)).unwrap_err(), Error::Cancelled);
assert_eq!(s, before);
p.scale = f64::MIN_POSITIVE;
assert_eq!(apply_with(&s, &p, r, r, None, &Interrupt::NONE).unwrap_err(), Error::NonFiniteSample);
}
#[test]
/// Ensure opaque formats retain their real channel count rather than acquiring an invented alpha plane.
fn opaque_native_models_use_actual_channel_counts_without_synthetic_alpha() {
let r = Rect::new(0, 0, 3, 2);
for mode in [ColorMode::Rgb, ColorMode::Grayscale, ColorMode::Cmyk, ColorMode::Lab] {
for depth in [SampleType::U8, SampleType::U16, SampleType::F32] {
let mut s = Surface::new(PixelFormat::new(mode, depth, false));
let ch = s.channels();
s.fill_rect(r, &vec![0.4; ch]);
let mut p = params(ch);
p.alpha_weighted = true;
assert_eq!(apply_with(&s, &p, r, r, None, &Interrupt::NONE).unwrap(), s);
let rank =
crate::rank::Params { radius: 1, color_percentile: 17., alpha_percentile: 83., shape: crate::rank::Neighborhood::Disc, channels: None };
assert_eq!(crate::rank::apply_with(&s, &rank, r, r, None, &Interrupt::NONE).unwrap(), s);
let noise = crate::channel_noise::Params {
amounts: vec![0.; ch],
distribution: crate::Distribution::Uniform,
monochromatic: false,
relative: true,
seed: 71,
};
assert_eq!(crate::channel_noise::apply_with(&s, &noise, r, r, None, &Interrupt::NONE).unwrap(), s);
}
}
}
#[test]
/// Reject malformed kernel shapes, masks and geometry before native convolution can allocate or publish work.
fn strict_kernel_channel_and_geometry_admission() {
let r = Rect::new(0, 0, 2, 2);
let s = surface(ColorMode::Rgb, SampleType::F32, r);
let mut p = params(4);
for bad in [0., f64::NAN, f64::INFINITY] {
p.scale = bad;
assert!(validate(&p, 4).is_err());
}
p = params(4);
p.channels.pop();
assert!(validate(&p, 4).is_err());
p = params(4);
p.kernel[0] = f64::INFINITY;
assert!(validate(&p, 4).is_err());
p = params(4);
p.kernel[0] = f64::MAX;
p.kernel[1] = f64::MAX;
assert!(validate(&p, 4).is_err());
let huge = Rect::new(0, 0, 65536, 65536);
assert_eq!(apply_with(&s, ¶ms(4), huge, huge, None, &Interrupt::NONE).unwrap_err(), Error::InvalidGeometry);
}
}
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.