Files
vectorcraft/crates/trace/src/opaque.rs
T
bflatastic 79572cbf6c Revert "Cut over roxmltree, png, tiff, psd, and trace codecs to craft-libs (#7638)"
This reverts commit bada8e1710. #7638 merged with its gate failing: besides six unformatted
files, render and trace don't compile against craft-libs e2dc681 (u64::from(usize) in
render/src/paint.rs, a private craft-libs function, and a call with one argument too many in
trace/src/opaque.rs), so main's CI fails. The tree is that of 0adbdce6cb, whose CI passed.
2026-11-15 02:26:07 +07:00

293 lines
14 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! The outline of an image's opaque area: what Outline Object on an image's own fill or stroke
//! follows.
use vectorcraft_geom::{Affine, PathData};
use crate::raster::{MAX_PIXELS, fit_size, gif_first_frame_pixels};
use crate::{Mode, Raster, TraceError, TraceParams, trace_within};
/// The most pixels [`opaque_outline`] traces: a larger image is reduced to this many first,
/// aspect kept ([`reduced`]), and its outline is scaled back up to the image's size.
pub const OUTLINE_MAX_PIXELS: u64 = 4 << 20;
/// The most anchor points an outline may have; an image whose outline would have more gives
/// [`TraceError::TooComplex`].
pub const OUTLINE_MAX_ANCHORS: usize = 100_000;
/// The most bytes [`decode_alpha`] decodes an image's samples into (256 MB: 64 megapixels at 8
/// bits a channel, 32 megapixels at 16).
pub const ALPHA_MAX_DECODE_BYTES: u64 = 256 << 20;
/// The alpha of the encoded image `bytes` (PNG, WebP, GIF, TIFF and the other formats the image
/// reader takes), one byte a pixel, row by row, with the image's width and height. `None` when the
/// image's format or color type has no alpha; the image is then not decoded. An image of more
/// than [`MAX_PIXELS`] (64 megapixels), or whose samples take more than [`ALPHA_MAX_DECODE_BYTES`],
/// gives [`TraceError::TooLarge`] before it is decoded.
pub fn decode_alpha(bytes: &[u8]) -> Result<Option<(u32, u32, Vec<u8>)>, TraceError> {
use image::ImageDecoder;
let decode_err = |e: image::ImageError| TraceError::Decode(e.to_string());
let reader = image::ImageReader::new(std::io::Cursor::new(bytes)).with_guessed_format().map_err(|e| TraceError::Decode(e.to_string()))?;
let decoder = reader.into_decoder().map_err(decode_err)?;
let (w, h) = decoder.dimensions();
if w == 0 || h == 0 {
return Err(TraceError::Empty);
}
if !decoder.color_type().has_alpha() {
return Ok(None);
}
let pixels = u64::from(w) * u64::from(h);
let frame = gif_first_frame_pixels(bytes).unwrap_or(0);
if pixels.max(frame) > MAX_PIXELS || decoder.total_bytes() > ALPHA_MAX_DECODE_BYTES {
return Err(TraceError::TooLarge { width: w, height: h, max: MAX_PIXELS >> 20 });
}
let alpha: Vec<u8> = match image::DynamicImage::from_decoder(decoder).map_err(decode_err)? {
image::DynamicImage::ImageRgba8(img) => img.as_raw().as_chunks::<4>().0.iter().map(|p| p[3]).collect(),
image::DynamicImage::ImageLumaA8(img) => img.as_raw().as_chunks::<2>().0.iter().map(|p| p[1]).collect(),
img => img.to_rgba8().as_raw().as_chunks::<4>().0.iter().map(|p| p[3]).collect(),
};
Ok(Some((w, h, alpha)))
}
/// The outline of the pixels of a `width × height` image whose `alpha` (one byte a pixel, row by
/// row) is at least half opaque (128 or more), in its pixel space (x right, y down; the image
/// spans `0..width × 0..height`). `None` when every pixel is: the outline is then the image's
/// frame. An image with no such pixel gives an empty outline.
///
/// The alpha is traced as Image Trace's Black and White mode traces a gray at threshold 128, with
/// its Paths and Corners at their defaults and no area left out as noise: the edge runs where the
/// alpha crosses one half, to a fraction of a pixel along anti-aliased edges, and the outline is
/// fitted with curves. Outer outlines and holes run in opposite directions, and an island in a
/// hole runs as outer outlines do, so the outline fills the same with either fill rule. An image
/// of more than [`OUTLINE_MAX_PIXELS`] is traced at that size ([`reduced`]).
pub fn opaque_outline(width: u32, height: u32, alpha: Vec<u8>) -> Result<Option<PathData>, TraceError> {
let (w, h) = (width, height);
if (w as usize).checked_mul(h as usize).is_none_or(|n| n == 0 || n != alpha.len()) {
return Err(TraceError::Empty);
}
if alpha.iter().all(|&a| a >= 128) {
return Ok(None);
}
if alpha.iter().all(|&a| a < 128) {
return Ok(Some(PathData::default()));
}
let (nw, nh) = fit_size(w, h, OUTLINE_MAX_PIXELS);
let alpha = if (nw, nh) == (w, h) { alpha } else { reduced(&alpha, w, h, nw, nh) };
// Opaque pixels are black, transparent ones white.
let mut rgba = Vec::with_capacity(alpha.len() * 4);
for a in alpha {
let g = 255 - a;
rgba.extend_from_slice(&[g, g, g, 255]);
}
let gray = Raster::new(nw, nh, rgba)?;
let params = TraceParams { mode: Mode::BlackAndWhite, threshold: 128, ignore_white: true, noise: 0, ..TraceParams::default() };
let traced = trace_within(&gray, &params, OUTLINE_MAX_ANCHORS)?;
let mut out = PathData::default();
for p in traced.paths {
out.subpaths.extend(p.path.subpaths);
}
if (nw, nh) != (w, h) {
out = out.transformed(Affine::scale_non_uniform(f64::from(w) / f64::from(nw), f64::from(h) / f64::from(nh)));
}
Ok(Some(out))
}
/// The `w × h` `alpha` reduced to `nw × nh` (at most `w × h`): each pixel holds the mean of the
/// block of pixels it covers, and at least 128 when that block holds a pixel of 128 or more, so an
/// opaque line thinner than a block stays inside the outline. Along an edge the outline can then
/// run up to half a block further out than the full-size image's would.
fn reduced(alpha: &[u8], w: u32, h: u32, nw: u32, nh: u32) -> Vec<u8> {
let span = |i: u32, n: u32, of: u32| {
let at = |i: u32| usize::try_from(u64::from(i) * u64::from(of) / u64::from(n.max(1))).unwrap_or(usize::MAX);
let start = at(i);
start..at(i + 1).max(start + 1)
};
let cols: Vec<_> = (0..nw).map(|x| span(x, nw, w)).collect();
let mut out = Vec::with_capacity(nw as usize * nh as usize);
let (mut sums, mut maxes) = (vec![0u64; cols.len()], vec![0u8; cols.len()]);
for ty in 0..nh {
let rows = span(ty, nh, h);
sums.fill(0);
maxes.fill(0);
for y in rows.clone() {
let Some(row) = alpha.get(y * w as usize..(y + 1) * w as usize) else { break };
for (x, c) in cols.iter().enumerate() {
for &a in row.get(c.clone()).unwrap_or_default() {
sums[x] += u64::from(a);
maxes[x] = maxes[x].max(a);
}
}
}
for (x, c) in cols.iter().enumerate() {
let count = (rows.len() * c.len()).max(1) as u64;
let mean = u8::try_from((sums[x] + count / 2) / count).unwrap_or(u8::MAX);
out.push(if maxes[x] >= 128 { mean.max(128) } else { mean });
}
}
out
}
#[cfg(test)]
mod tests {
use kurbo::Shape;
use super::*;
/// The width, height and alpha of `img`, as [`opaque_outline`] takes them.
fn alpha(img: &Raster) -> (u32, u32, Vec<u8>) {
(img.width, img.height, img.rgba.as_chunks::<4>().0.iter().map(|p| p[3]).collect())
}
fn outline(img: &Raster) -> Result<Option<PathData>, TraceError> {
let (w, h, a) = alpha(img);
opaque_outline(w, h, a)
}
/// A `w × h` raster, opaque red inside the disc of radius `r` around the middle and
/// transparent outside it.
fn disc(w: u32, h: u32, r: f64) -> Raster {
let (cx, cy) = (f64::from(w) / 2.0, f64::from(h) / 2.0);
Raster::from_fn(w, h, |x, y| {
let (dx, dy) = (f64::from(x) + 0.5 - cx, f64::from(y) + 0.5 - cy);
if dx.hypot(dy) <= r { [255, 0, 0, 255] } else { [0, 0, 0, 0] }
})
}
fn area(p: &PathData) -> f64 {
p.to_bezpath().area().abs()
}
#[test]
fn the_outline_follows_the_opaque_disc_not_the_frame() {
let outline = outline(&disc(100, 100, 30.0)).unwrap().unwrap();
let b = outline.bounds().unwrap();
for (got, want) in [(b.x0, 20.0), (b.y0, 20.0), (b.x1, 80.0), (b.y1, 80.0)] {
assert!((got - want).abs() < 1.0, "{b:?}");
}
let disc_area = std::f64::consts::PI * 30.0 * 30.0;
assert!((area(&outline) - disc_area).abs() < disc_area * 0.02, "{}", area(&outline));
// Fitted with curves, not one line per pixel step.
assert!(outline.anchor_count() < 40, "{} anchors", outline.anchor_count());
}
#[test]
fn an_opaque_image_keeps_its_frame_and_a_transparent_one_has_no_outline() {
let opaque = Raster::from_fn(10, 10, |_, _| [0, 0, 255, 128]);
assert_eq!(outline(&opaque).unwrap(), None);
let clear = Raster::from_fn(10, 10, |_, _| [0, 0, 255, 127]);
assert!(outline(&clear).unwrap().unwrap().is_empty());
// One pixel either way.
assert_eq!(outline(&Raster::from_fn(1, 1, |_, _| [9, 9, 9, 255])).unwrap(), None);
assert!(outline(&Raster::from_fn(1, 1, |_, _| [9, 9, 9, 0])).unwrap().unwrap().is_empty());
// No pixels at all, or an alpha that doesn't match the size.
assert!(opaque_outline(0, 0, vec![]).is_err());
assert!(opaque_outline(2, 2, vec![0]).is_err());
}
#[test]
fn pixels_less_than_half_opaque_are_outside() {
// A 20 px square, opaque, inside a 6 px band of alpha `band`, on a transparent 40 px image.
let framed = |band: u8| {
Raster::from_fn(40, 40, |x, y| {
let d = x.min(y).min(39 - x).min(39 - y);
let alpha = match d {
10.. => 255,
4.. => band,
_ => 0,
};
[0, 0, 0, alpha]
})
};
let inner = outline(&framed(127)).unwrap().unwrap().bounds().unwrap();
assert!((inner.x0 - 10.0).abs() < 0.5 && (inner.x1 - 30.0).abs() < 0.5, "{inner:?}");
// A half-opaque band is inside; the edge runs through the middle of its outer pixels,
// which are half covered.
let outer = outline(&framed(128)).unwrap().unwrap().bounds().unwrap();
assert!((outer.x0 - 4.5).abs() < 0.25 && (outer.x1 - 35.5).abs() < 0.25, "{outer:?}");
let outer = outline(&framed(255)).unwrap().unwrap().bounds().unwrap();
assert!((outer.x0 - 4.0).abs() < 0.25 && (outer.x1 - 36.0).abs() < 0.25, "{outer:?}");
}
#[test]
fn a_hole_in_the_opaque_area_is_a_hole_in_the_outline() {
let ring = Raster::from_fn(60, 60, |x, y| {
let d = (f64::from(x) + 0.5 - 30.0).hypot(f64::from(y) + 0.5 - 30.0);
[0, 0, 0, if (10.0..=25.0).contains(&d) { 255 } else { 0 }]
});
let outline = outline(&ring).unwrap().unwrap();
let want = std::f64::consts::PI * (25.0 * 25.0 - 10.0 * 10.0);
assert!((outline.to_bezpath().area().abs() - want).abs() < want * 0.03, "{}", outline.to_bezpath().area());
assert!(!outline.to_bezpath().contains(kurbo::Point::new(30.0, 30.0)));
assert!(outline.to_bezpath().contains(kurbo::Point::new(30.0, 12.0)));
}
#[test]
fn the_outline_fills_the_same_with_either_fill_rule() {
// A ring with an opaque island in its hole.
let target = Raster::from_fn(80, 80, |x, y| {
let d = (f64::from(x) + 0.5 - 40.0).hypot(f64::from(y) + 0.5 - 40.0);
[0, 0, 0, if (25.0..=35.0).contains(&d) || d <= 10.0 { 255 } else { 0 }]
});
let path = outline(&target).unwrap().unwrap().to_bezpath();
let winding = |x: f64, y: f64| path.winding(kurbo::Point::new(x, y));
let (ring, hole, island, outside) = (winding(40.0, 10.0), winding(40.0, 20.0), winding(40.0, 40.0), winding(2.0, 2.0));
// Non-zero and even-odd agree when every winding number is -1, 0 or 1.
assert!(ring.abs() == 1 && island == ring && hole == 0 && outside == 0, "{ring} {hole} {island} {outside}");
}
#[test]
fn a_large_image_is_traced_smaller_and_scaled_back() {
let big = disc(2400, 2000, 800.0);
assert!(u64::from(big.width) * u64::from(big.height) > OUTLINE_MAX_PIXELS);
let b = outline(&big).unwrap().unwrap().bounds().unwrap();
for (got, want) in [(b.x0, 400.0), (b.y0, 200.0), (b.x1, 2000.0), (b.y1, 1800.0)] {
assert!((got - want).abs() < 3.0, "{b:?}");
}
}
#[test]
fn a_line_thinner_than_the_reduction_stays_in_a_large_images_outline() {
// 39 megapixels, reduced to 4: each traced pixel covers about 3 × 3. The only opaque
// pixels are a line 1 pixel wide, which averages to about a third opaque.
let (w, h) = (8192u32, 4800u32);
let mut a = vec![0u8; (w * h) as usize];
for y in 1000..3000 {
a[(y * w + 2001) as usize] = 255;
}
let b = opaque_outline(w, h, a).unwrap().unwrap().bounds().unwrap();
assert!(b.x0 > 1990.0 && b.x1 < 2012.0 && (b.y0 - 1000.0).abs() < 6.0 && (b.y1 - 3000.0).abs() < 6.0, "{b:?}");
}
#[test]
fn an_outline_of_too_many_anchors_is_refused() {
// A checkerboard of 2 px squares: more than 50,000 opaque squares.
let checker = Raster::from_fn(640, 640, |x, y| [0, 0, 0, if (x / 2 + y / 2) % 2 == 0 { 255 } else { 0 }]);
assert!(matches!(outline(&checker), Err(TraceError::TooComplex { max: OUTLINE_MAX_ANCHORS })));
}
/// `img` encoded as `format`.
fn encoded(img: image::DynamicImage, format: image::ImageFormat) -> Vec<u8> {
let mut out = vec![];
img.write_to(&mut std::io::Cursor::new(&mut out), format).unwrap();
out
}
#[test]
fn decode_alpha_reads_the_alpha_of_formats_that_have_one() {
let px = |x: u32, y: u32| image::Rgba([10, 20, 30, u8::try_from((x + 4 * y) * 16).unwrap()]);
let rgba = image::DynamicImage::ImageRgba8(image::RgbaImage::from_fn(4, 4, px));
let want: Vec<u8> = (0..16).map(|i| u8::try_from(i * 16).unwrap()).collect();
for (name, img) in [
("rgba", rgba.clone()),
("gray and alpha", image::DynamicImage::ImageLumaA8(rgba.to_luma_alpha8())),
("16 bits", image::DynamicImage::ImageRgba16(rgba.to_rgba16())),
] {
let got = decode_alpha(&encoded(img, image::ImageFormat::Png)).unwrap();
assert_eq!(got, Some((4, 4, want.clone())), "{name}");
}
let rgb = image::DynamicImage::ImageRgb8(rgba.to_rgb8());
assert_eq!(decode_alpha(&encoded(rgb.clone(), image::ImageFormat::Png)).unwrap(), None);
assert_eq!(decode_alpha(&encoded(rgb, image::ImageFormat::Jpeg)).unwrap(), None);
assert!(decode_alpha(b"not an image").is_err());
}
}