856f865cf98d
average.rs
//! Bounded alpha-weighted averaging and Photoshop's coverage-preserving Average.
pub use crate::coverage::Error;
use photocraft_geom::Rect;
use photocraft_raster::{Interrupt, Surface, from_rgba_into, to_rgba};
/// Accumulation order and F32 products preserve the original Raster Average policy.
#[derive(Default)]
pub struct Mean {
sum: [f64; 3],
weight: f64,
alpha: f64,
count: f64,
}
impl Mean {
/// Accumulate the native selection/alpha-weighted color mean while preserving the established multiplication
/// order.
pub fn push(&mut self, p: [f32; 4], coverage: f32) {
let weight = f64::from(p[3] * coverage);
for (sum, value) in self.sum.iter_mut().zip(p) {
*sum += f64::from(value) * weight;
}
self.weight += weight;
self.alpha += f64::from(p[3] * coverage);
self.count += f64::from(coverage);
}
/// Photoshop Average weights straight colors by selection, including hidden RGB, without changing coverage.
fn push_colour(&mut self, p: [f32; 4], coverage: f32) {
let weight = f64::from(coverage);
for (sum, value) in self.sum.iter_mut().zip(p) {
*sum += f64::from(value) * weight;
}
self.weight += weight;
self.count += weight;
self.alpha += f64::from(p[3]) * weight;
}
/// Return the normalized mean only when positive alpha weight exists, keeping the native average-alpha policy.
pub fn rgba(&self) -> Option<[f32; 4]> {
(self.weight > 0.).then(|| {
[
(self.sum[0] / self.weight) as f32,
(self.sum[1] / self.weight) as f32,
(self.sum[2] / self.weight) as f32,
(self.alpha / self.count.max(1e-9)) as f32,
]
})
}
}
/// Translate interruption into the shared checked native-filter cancellation error.
fn check(ctl: &Interrupt) -> Result<(), Error> {
ctl.check().map_err(|_| Error::Cancelled)
}
/// Selection coverage saturates like the ordinary filter path; nonfinite masks remain invalid.
fn selection_coverage(selection: Option<&Surface>, x: i32, y: i32) -> Result<f32, Error> {
let coverage = selection.map_or(1., |surface| surface.sample_channel(x, y, 0));
if !coverage.is_finite() {
return Err(Error::NonFiniteSample);
}
Ok(coverage.clamp(0., 1.))
}
/// Average a bounded native area using fallible row storage and publish only finite, uncancelled selection-mixed
/// output.
pub fn apply_with(surface: &Surface, area: Rect, bounds: Rect, selection: Option<&Surface>, ctl: &Interrupt) -> Result<Surface, Error> {
apply_policy(surface, area, bounds, selection, ctl, false)
}
/// Photoshop Average edits straight colors with selection weights while preserving every native alpha sample.
pub fn apply_preserving_alpha_with(surface: &Surface, area: Rect, bounds: Rect, selection: Option<&Surface>, ctl: &Interrupt) -> Result<Surface, Error> {
apply_policy(surface, area, bounds, selection, ctl, true)
}
/// Preserve the upstream optional dispatcher contract while using bounded checked publication.
pub(crate) fn apply(surface: &Surface, area: Rect, selection: Option<&Surface>, ctl: &Interrupt) -> Option<Surface> {
apply_preserving_alpha_with(surface, area, area, selection, ctl).ok()
}
/// Both averaging policies share finite-sample checks, output admission and cancellable row scratch.
fn apply_policy(surface: &Surface, area: Rect, bounds: Rect, selection: Option<&Surface>, ctl: &Interrupt, preserve_alpha: bool) -> Result<Surface, Error> {
check(ctl)?;
let area = area.intersect(&bounds);
if area.is_empty() {
return Ok(surface.clone());
}
let w = area.width() as usize;
let h = area.height() as usize;
if w.checked_mul(h).is_none_or(|n| n > crate::coverage::MAX_PIXELS) {
return Err(Error::InvalidGeometry);
}
let tile = i64::from(photocraft_geom::TILE_SIZE);
let axes = |a: i32, b: i32| -> Result<usize, Error> {
usize::try_from((i64::from(b) - 1).div_euclid(tile) - i64::from(a).div_euclid(tile) + 1).map_err(|_| Error::WorkspaceLimit)
};
let bytes = axes(area.x0, area.x1)?
.checked_mul(axes(area.y0, area.y1)?)
.and_then(|n| n.checked_mul((tile * tile) as usize * surface.format().bytes_per_pixel() + 128))
.and_then(|n| n.checked_add(w * (surface.channels() + 4) * 4))
.and_then(|n| n.checked_add(surface.tile_count().checked_mul(128)?))
.ok_or(Error::WorkspaceLimit)?;
if bytes > crate::coverage::MAX_WORKSPACE_BYTES {
return Err(Error::WorkspaceLimit);
}
let n = surface.channels();
if n == 0 || n > 5 {
return Err(Error::InvalidGeometry);
}
let mut row = Vec::new();
row.try_reserve_exact(w * n).map_err(|_| Error::Allocation)?;
let mut mean = Mean::default();
for y in area.y0..area.y1 {
check(ctl)?;
surface.read_region_into(Rect::new(area.x0, y, area.x1, y + 1), &mut row);
for (x, pixel) in (area.x0..area.x1).zip(row.chunks_exact(n)) {
let p = to_rgba(&surface.format(), pixel);
let k = selection_coverage(selection, x, y)?;
if p.into_iter().any(|v| !v.is_finite()) {
return Err(Error::NonFiniteSample);
}
if preserve_alpha {
mean.push_colour(p, k);
} else {
mean.push(p, k);
}
}
}
let Some(avg) = mean.rgba() else { return Ok(surface.clone()) };
if avg.into_iter().any(|v| !v.is_finite()) {
return Err(Error::NonFiniteSample);
}
let mut out = surface.clone();
for y in area.y0..area.y1 {
check(ctl)?;
surface.read_region_into(Rect::new(area.x0, y, area.x1, y + 1), &mut row);
for (x, dst) in (area.x0..area.x1).zip(row.chunks_exact_mut(n)) {
let k = selection_coverage(selection, x, y)?;
if k == 0. {
continue;
}
let original_alpha = dst.last().copied();
let p = to_rgba(&surface.format(), dst);
let mut target = avg;
if preserve_alpha {
target[3] = p[3];
}
let mut mixed = p;
if !preserve_alpha && surface.format().alpha && p[3] != avg[3] {
let before = f64::from(p[3]) * (1. - f64::from(k));
let after = f64::from(avg[3]) * f64::from(k);
let alpha = before + after;
for c in 0..3 {
mixed[c] = if alpha > 0. { ((f64::from(p[c]) * before + f64::from(avg[c]) * after) / alpha) as f32 } else { 0. };
}
mixed[3] = alpha as f32;
if mixed.iter().any(|value| !value.is_finite()) {
return Err(Error::NonFiniteSample);
}
from_rgba_into(&surface.format(), mixed, dst);
if dst.iter().any(|v| !v.is_finite()) {
return Err(Error::NonFiniteSample);
}
continue;
}
for (v, (a, b)) in mixed.iter_mut().zip(p.into_iter().zip(target)) {
*v = a + (b - a) * k;
if !v.is_finite() {
let precise = f64::from(a) + (f64::from(b) - f64::from(a)) * f64::from(k);
if !precise.is_finite() || precise.abs() > f64::from(f32::MAX) {
return Err(Error::NonFiniteSample);
}
*v = precise as f32;
}
}
from_rgba_into(&surface.format(), mixed, dst);
if preserve_alpha
&& surface.format().alpha
&& let Some(alpha) = dst.last_mut()
{
*alpha = original_alpha.unwrap_or(p[3]);
}
if dst.iter().any(|v| !v.is_finite()) {
return Err(Error::NonFiniteSample);
}
}
out.try_write_region(Rect::new(area.x0, y, area.x1, y + 1), &row).map_err(|_| Error::Allocation)?;
}
check(ctl)?;
out.prune();
Ok(out)
}
/// Adapt raw native float images to checked Average, preserving bounded identity fallback on rejected work.
#[cfg(test)]
pub(crate) fn run_image(src: &crate::image::Image, out: Rect, ctx: &crate::Ctx) -> Vec<f32> {
run_image_policy(src, out, ctx, false)
}
/// The ordinary command's direct kernel shares the canvas-clipped mean and alpha-preserving policy.
pub(crate) fn kernel(src: &crate::image::Image, out: Rect, ctx: &crate::Ctx) -> Vec<f32> {
run_image_policy(src, out, ctx, true)
}
/// Raw native images remain bounded and retain identity fallback on rejected work.
fn run_image_policy(src: &crate::image::Image, out: Rect, ctx: &crate::Ctx, preserve_alpha: bool) -> Vec<f32> {
let format = photocraft_color::PixelFormat::new(ctx.mode, photocraft_color::SampleType::F32, ctx.alpha);
let valid = [src.rect, out].into_iter().all(|r| (r.width() as usize).checked_mul(r.height() as usize).is_some_and(|n| n <= crate::coverage::MAX_PIXELS));
if !valid
|| src.ch != format.channels()
|| (src.rect.width() as usize).checked_mul(src.rect.height() as usize).and_then(|n| n.checked_mul(src.ch)) != Some(src.data.len())
{
return Vec::new();
}
let tile = photocraft_geom::TILE_SIZE as u64;
let tiles = |r: Rect| (u64::from(r.width()).div_ceil(tile) + 1) * (u64::from(r.height()).div_ceil(tile) + 1);
if (tiles(src.rect) + tiles(out)).saturating_mul(tile * tile * format.bytes_per_pixel() as u64) > crate::coverage::MAX_WORKSPACE_BYTES as u64 {
return Vec::new();
}
let mut surface = Surface::new(format);
let identity = || -> Result<Vec<f32>, Error> {
let count = (out.width() as usize).checked_mul(out.height() as usize).and_then(|n| n.checked_mul(src.ch)).ok_or(Error::WorkspaceLimit)?;
let mut values = Vec::new();
values.try_reserve_exact(count).map_err(|_| Error::Allocation)?;
for y in out.y0..out.y1 {
for x in out.x0..out.x1 {
for c in 0..src.ch {
values.push(src.get(x, y, c));
}
}
}
Ok(values)
};
let mut run = || -> Result<Vec<f32>, Error> {
let domain = src.rect.intersect(&ctx.bounds);
surface.try_write_region(src.rect, &src.data).map_err(|_| Error::Allocation)?;
// Average the complete supplied image, even when only one output tile is
// requested. Unpopulated canvas pixels are not part of this image.
apply_policy(&surface, domain, domain, None, &Interrupt::NONE, preserve_alpha)?.try_read_region(out).map_err(|_| Error::Allocation)
};
run().unwrap_or_else(|_| identity().unwrap_or_default())
}
#[cfg(test)]
mod tests {
use super::*;
use photocraft_color::{ColorMode, PixelFormat, SampleType};
/// Canvas size and output tiling must not dilute a small offset image's color or alpha mean.
#[test]
fn raw_average_uses_image_domain_and_keeps_global_mean_across_output_tiles() {
let rect = Rect::new(12, 15, 14, 16);
for alpha in [false, true] {
let format = PixelFormat::new(ColorMode::Rgb, SampleType::F32, alpha);
let mut data = vec![0.2, 0.4, 0.6];
if alpha {
data.push(0.5);
}
data.extend([0.8, 0.6, 0.4]);
if alpha {
data.push(1.);
}
let image = crate::Image { rect, ch: format.channels(), data };
for bounds in [Rect::new(0, 0, 20, 20), Rect::new(0, 0, 10_000, 10_000)] {
let ctx = crate::Ctx { bounds, mode: ColorMode::Rgb, alpha };
let expected = if alpha { vec![0.6, 8. / 15., 7. / 15., 0.75] } else { vec![0.5, 0.5, 0.5] };
for out in [rect, Rect::new(12, 15, 13, 16), Rect::new(13, 15, 14, 16)] {
let result = run_image(&image, out, &ctx);
assert_eq!(result.len(), out.size().area() as usize * format.channels());
for pixel in result.chunks_exact(format.channels()) {
for (value, want) in pixel.iter().zip(&expected) {
assert!((value - want).abs() < 1e-6);
}
}
}
}
}
}
#[test]
/// Keep unselected CMYK separations and out-of-gamut Lab samples unchanged at every native depth.
fn zero_coverage_preserves_native_cmyk_and_out_of_gamut_lab_samples() {
for mode in [ColorMode::Cmyk, ColorMode::Lab] {
for depth in SampleType::ALL {
let format = PixelFormat::new(mode, depth, true);
let mut source = Surface::new(format);
let untouched: &[f32] = if mode == ColorMode::Cmyk { &[0.2, 0.4, 0.6, 0.5, 1.] } else { &[0.5, 1., 1., 1.] };
source.write_pixel(1, 0, untouched);
source.write_pixel(0, 0, &vec![0.75; format.channels()]);
let before = source.pixel(1, 0);
let mut mask = Surface::new(PixelFormat::new(ColorMode::Grayscale, SampleType::F32, false));
mask.write_pixel(0, 0, &[1.]);
let bounds = Rect::new(0, 0, 2, 1);
let output = apply_with(&source, bounds, bounds, Some(&mask), &Interrupt::NONE).unwrap();
assert_eq!(output.pixel(1, 0), before, "{mode:?} {depth:?}");
}
}
}
#[test]
#[ignore = "24MP native Average performance probe"]
/// Measure release Average on a full-size original surface with bounded rows rather than a whole-frame sample
/// copy.
fn average_24mp_bounded_rows_benchmark() {
let b = Rect::new(0, 0, 6000, 4000);
let mut source = Surface::new(PixelFormat::RGBA32F);
source.fill_rect(Rect::new(0, 0, 3000, 4000), &[1., 0., 0., 0.5]);
source.fill_rect(Rect::new(3000, 0, 6000, 4000), &[0., 0., 1., 1.]);
let started = std::time::Instant::now();
let output = apply_with(&source, b, b, None, &Interrupt::NONE).unwrap();
println!("native Average24MP RGBA32F elapsed_ms={}", started.elapsed().as_millis());
let p = output.pixel(3000, 2000);
assert!((p[0] - 1. / 3.).abs() < 1e-6 && (p[2] - 2. / 3.).abs() < 1e-6 && p[3] == 0.75);
}
#[test]
/// Pin native mean weighting, premultiplied feathering and quantization across color models and depths.
fn rgba_weighted_mean_and_premultiplied_selection_at_every_depth() {
for mode in [ColorMode::Rgb, ColorMode::Grayscale, ColorMode::Cmyk, ColorMode::Lab] {
for depth in [SampleType::U8, SampleType::U16, SampleType::F32] {
let format = PixelFormat { mode, sample: depth, alpha: true };
let mut s = Surface::new(format);
let mut p = vec![0.; format.channels()];
from_rgba_into(&format, [0.2, 0.4, 0.6, 0.5], &mut p);
s.write_pixel(0, 0, &p);
from_rgba_into(&format, [0.8, 0.3, 0.1, 1.], &mut p);
s.write_pixel(1, 0, &p);
let a = to_rgba(&format, &s.pixel(0, 0));
let b = to_rgba(&format, &s.pixel(1, 0));
let mut mask = Surface::new(PixelFormat::new(ColorMode::Grayscale, SampleType::F32, false));
mask.write_pixel(0, 0, &[1.]);
mask.write_pixel(1, 0, &[0.25]);
let mut m = Mean::default();
m.push(a, 1.);
m.push(b, 0.25);
let expected = m.rgba().unwrap();
let out = apply_with(&s, Rect::new(0, 0, 2, 1), Rect::new(0, 0, 2, 1), Some(&mask), &Interrupt::NONE).unwrap();
let mut encoded = Surface::new(format);
from_rgba_into(&format, expected, &mut p);
encoded.write_pixel(0, 0, &p);
assert_eq!(out.pixel(0, 0), encoded.pixel(0, 0));
let alpha = f64::from(b[3]) * 0.75 + f64::from(expected[3]) * 0.25;
let mixed = std::array::from_fn(|c| {
if c == 3 {
alpha as f32
} else {
((f64::from(b[c]) * f64::from(b[3]) * 0.75 + f64::from(expected[c]) * f64::from(expected[3]) * 0.25) / alpha) as f32
}
});
from_rgba_into(&format, mixed, &mut p);
encoded.write_pixel(1, 0, &p);
assert_eq!(out.pixel(1, 0), encoded.pixel(1, 0));
}
}
}
#[test]
/// Compare with an independently calculated weighted mean and require cancellation to preserve source pixels.
fn independent_mean_and_cancel_are_atomic() {
let mut s = Surface::new(PixelFormat::RGBA32F);
s.write_pixel(0, 0, &[1., 0., 0., 0.5]);
s.write_pixel(1, 0, &[0., 0., 1., 1.]);
let b = Rect::new(0, 0, 2, 1);
let out = apply_with(&s, b, b, None, &Interrupt::NONE).unwrap();
let p = out.pixel(0, 0);
assert!((p[0] - 1. / 3.).abs() < 1e-6);
assert!((p[2] - 2. / 3.).abs() < 1e-6);
assert_eq!(p[3], 0.75);
let cancel = || true;
assert_eq!(apply_with(&s, b, b, None, &Interrupt::cancel_only(&cancel)).unwrap_err(), Error::Cancelled);
assert_eq!(s.pixel(0, 0), vec![1., 0., 0., 0.5]);
assert!(apply_with(&s, Rect::new(0, 0, 100000, 100000), Rect::new(0, 0, 100000, 100000), None, &Interrupt::NONE).is_err());
}
#[test]
/// Cover opaque HDR, empty alpha support and delayed cancellation under the existing native Average policy.
fn opaque_hdr_empty_alpha_and_mid_pass_cancel_keep_native_rules() {
let b = Rect::new(0, 0, 2, 2);
let mut opaque = Surface::new(PixelFormat::new(ColorMode::Rgb, SampleType::F32, false));
opaque.fill_rect(b, &[4., -2., 0.5]);
let out = apply_with(&opaque, b, b, None, &Interrupt::NONE).unwrap();
assert_eq!(out.read_region(b), opaque.read_region(b));
let mut transparent = Surface::new(PixelFormat::RGBA32F);
transparent.fill_rect(b, &[1., 0., 0., 0.]);
assert_eq!(apply_with(&transparent, b, b, None, &Interrupt::NONE).unwrap().read_region(b), transparent.read_region(b));
use std::sync::atomic::{AtomicUsize, Ordering};
let checks = AtomicUsize::new(0);
let cancel = || checks.fetch_add(1, Ordering::Relaxed) >= 3;
let before = opaque.clone();
assert_eq!(apply_with(&opaque, b, b, None, &Interrupt::cancel_only(&cancel)).unwrap_err(), Error::Cancelled);
assert_eq!(opaque, before);
opaque.write_pixel(0, 0, &[f32::NAN, 0., 0.]);
assert_eq!(apply_with(&opaque, b, b, None, &Interrupt::NONE).unwrap_err(), Error::NonFiniteSample);
}
#[test]
/// Exercise extreme finite HDR selection mixtures so intermediate overflow cannot publish nonfinite pixels.
fn finite_hdr_selection_intermediates_never_publish_infinity() {
let b = Rect::new(0, 0, 2, 1);
let mut source = Surface::new(PixelFormat::RGBA32F);
source.write_pixel(0, 0, &[f32::MAX, 0., 0., 1.]);
source.write_pixel(1, 0, &[-f32::MAX, 0., 0., 1.]);
let mut selection = Surface::new(PixelFormat::new(ColorMode::Grayscale, SampleType::F32, false));
selection.write_pixel(0, 0, &[1.]);
selection.write_pixel(1, 0, &[0.5]);
let before = source.clone();
let output = apply_with(&source, b, b, Some(&selection), &Interrupt::NONE).unwrap();
assert!(output.read_region(b).iter().all(|v| v.is_finite()));
assert!((f64::from(output.pixel(0, 0)[0]) / f64::from(f32::MAX) - 1. / 3.).abs() < 1e-6);
assert!((f64::from(output.pixel(1, 0)[0]) / f64::from(f32::MAX) + 1. / 3.).abs() < 1e-6);
assert_eq!(source, before);
// Hostile finite signed coverage can make the mean itself unrepresentable.
source.write_pixel(1, 0, &[-f32::MAX, 0., 0., -0.5]);
let before = source.clone();
assert_eq!(apply_with(&source, b, b, None, &Interrupt::NONE).unwrap_err(), Error::NonFiniteSample);
assert_eq!(source, before);
}
#[test]
/// Reject selected Average results that overflow native Lab conversion without modifying the input surface.
fn alpha_changing_lab_selection_rejects_nonfinite_native_conversion_atomically() {
let format = PixelFormat::new(ColorMode::Lab, SampleType::F32, true);
let bounds = Rect::new(0, 0, 3, 1);
let neutral = 128. / 255.;
// Finite signed alpha is hostile but accepted input. Its weights nearly cancel while the
// white pixel's color contribution remains, creating finite HDR RGB that overflows Lab.
let pixels: [[f32; 4]; 3] = [[1., neutral, neutral, 1.], [0., neutral, neutral, -1.], [0., neutral, neutral, 1e-20]];
let mut source = Surface::new(format);
let mut selection = Surface::new(PixelFormat::new(ColorMode::Grayscale, SampleType::F32, false));
let mut mean = Mean::default();
for (x, (pixel, coverage)) in pixels.into_iter().zip([1., 1., 0.5]).enumerate() {
assert!(pixel.iter().all(|v| v.is_finite()));
source.write_pixel(x as i32, 0, &pixel);
selection.write_pixel(x as i32, 0, &[coverage]);
let rgba = to_rgba(&format, &pixel);
assert!(rgba.iter().all(|v| v.is_finite()));
mean.push(rgba, coverage);
}
let avg = mean.rgba().unwrap();
assert!(avg.iter().all(|v| v.is_finite()));
assert!(avg[0] > 1e19);
assert_ne!(avg[3], pixels[0][3]);
// Full selection coverage at the first pixel makes its premultiplied mix exactly avg.
let mut native = [0.; 4];
from_rgba_into(&format, avg, &mut native);
assert!(native.iter().any(|v| !v.is_finite()));
let before = source.clone();
assert_eq!(apply_with(&source, bounds, bounds, Some(&selection), &Interrupt::NONE).unwrap_err(), Error::NonFiniteSample);
assert_eq!(source, before);
}
}
#[cfg(test)]
#[path = "average/tests.rs"]
mod upstream_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.