diff --git a/src/Titano.Core/Imaging/Resampler.cs b/src/Titano.Core/Imaging/Resampler.cs new file mode 100644 index 00000000..225917d1 --- /dev/null +++ b/src/Titano.Core/Imaging/Resampler.cs @@ -0,0 +1,201 @@ +using System.Numerics; + +namespace Titano.Core.Imaging; + +/// Reconstruction filters for . +public enum ResampleFilter +{ + /// Lanczos3 on axes that shrink, Catmull-Rom on axes that grow. + Auto, + + /// Exact area average (no ringing; fastest for large reductions such as thumbnails). + Box, + + Lanczos3, + CatmullRom, +} + +/// +/// Separable two-pass resampling of linear-light s. When shrinking, the kernel is stretched +/// by the reduction factor (proper low-pass support); weights are normalised and folded at the edges (clamp), so +/// constant images stay constant and mean energy is preserved. Rows are processed in parallel. +/// +public static class Resampler +{ + /// Resizes into a new buffer with the same channel count. + public static ImageBuffer Resize(ImageBuffer source, int width, int height, ResampleFilter filter = ResampleFilter.Auto, int maxDegreeOfParallelism = -1) + { + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(width); + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(height); + var parallel = new ParallelOptions { MaxDegreeOfParallelism = maxDegreeOfParallelism }; + if (width == source.Width && height == source.Height) return source.Clone(); + var wx = width == source.Width ? null : Weights.Build(source.Width, width, filter); + var wy = height == source.Height ? null : Weights.Build(source.Height, height, filter); + if (wx is null) return Vertical(source, wy!, parallel); + if (wy is null) return Horizontal(source, wx, parallel); + + // Run the pass that leaves the smaller intermediate work first. + var horizontalFirst = (long)source.Height * width * wx.Stride + (long)height * width * wy.Stride + <= (long)height * source.Width * wy.Stride + (long)height * width * wx.Stride; + using var intermediate = horizontalFirst ? Horizontal(source, wx, parallel) : Vertical(source, wy, parallel); + return horizontalFirst ? Vertical(intermediate, wy, parallel) : Horizontal(intermediate, wx, parallel); + } + + /// Area-average reduction so that the long edge is at most + /// (a copy when the image is already small enough). + public static ImageBuffer Thumbnail(ImageBuffer source, int maxLongEdge) + { + var (w, h) = FitWithin(source.Width, source.Height, maxLongEdge); + return w == source.Width && h == source.Height ? source.Clone() : Resize(source, w, h, ResampleFilter.Box); + } + + /// Largest size with the same aspect ratio whose long edge is ≤ (never upscales). + public static (int Width, int Height) FitWithin(int width, int height, int maxLongEdge) + { + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(maxLongEdge); + var longEdge = Math.Max(width, height); + if (longEdge <= maxLongEdge) return (width, height); + var scale = maxLongEdge / (double)longEdge; + return (Math.Max(1, (int)Math.Round(width * scale)), Math.Max(1, (int)Math.Round(height * scale))); + } + + private static ImageBuffer Horizontal(ImageBuffer source, Weights w, ParallelOptions parallel) + { + var result = new ImageBuffer(w.Length, source.Height, source.Channels, clear: false); + Parallel.For(0, source.Height, parallel, y => + { + for (var c = 0; c < source.Channels; c++) + { + ReadOnlySpan src = source.Row(c, y); + var dst = result.Row(c, y); + for (var x = 0; x < dst.Length; x++) + { + dst[x] = Dot(src.Slice(w.Start[x], w.Count[x]), w.Values.AsSpan(x * w.Stride, w.Count[x])); + } + } + }); + return result; + } + + private static ImageBuffer Vertical(ImageBuffer source, Weights w, ParallelOptions parallel) + { + var result = new ImageBuffer(source.Width, w.Length, source.Channels, clear: false); + Parallel.For(0, w.Length, parallel, y => + { + var taps = w.Values.AsSpan(y * w.Stride, w.Count[y]); + for (var c = 0; c < source.Channels; c++) + { + var dst = result.Row(c, y); + dst.Clear(); + for (var k = 0; k < taps.Length; k++) MultiplyAdd(source.Row(c, w.Start[y] + k), taps[k], dst); + } + }); + return result; + } + + private static float Dot(ReadOnlySpan a, ReadOnlySpan b) + { + var i = 0; + var sum = 0f; + if (Vector.IsHardwareAccelerated && a.Length >= Vector.Count) + { + var acc = Vector.Zero; + for (; i <= a.Length - Vector.Count; i += Vector.Count) acc += new Vector(a[i..]) * new Vector(b[i..]); + sum = Vector.Sum(acc); + } + for (; i < a.Length; i++) sum += a[i] * b[i]; + return sum; + } + + private static void MultiplyAdd(ReadOnlySpan src, float weight, Span dst) + { + var i = 0; + if (Vector.IsHardwareAccelerated) + { + var w = new Vector(weight); + for (; i <= dst.Length - Vector.Count; i += Vector.Count) (new Vector(dst[i..]) + new Vector(src[i..]) * w).CopyTo(dst[i..]); + } + for (; i < dst.Length; i++) dst[i] += src[i] * weight; + } + + /// Per output sample: a contiguous source range and its normalised weights (stride-padded). + private sealed class Weights + { + public required int Length { get; init; } + public required int Stride { get; init; } + public required int[] Start { get; init; } + public required int[] Count { get; init; } + public required float[] Values { get; init; } + + public static Weights Build(int source, int target, ResampleFilter filter) + { + var scale = target / (double)source; + var kind = filter == ResampleFilter.Auto ? (scale < 1 ? ResampleFilter.Lanczos3 : ResampleFilter.CatmullRom) : filter; + var radius = kind switch { ResampleFilter.Lanczos3 => 3.0, ResampleFilter.CatmullRom => 2.0, _ => 0.5 }; + var stretch = Math.Max(1.0, 1 / scale); + var stride = (int)Math.Ceiling(2 * radius * stretch) + 2; + var start = new int[target]; + var count = new int[target]; + var values = new float[target * stride]; + var taps = new double[source]; + for (var i = 0; i < target; i++) + { + double lo, hi; + if (kind == ResampleFilter.Box) + { + lo = i / scale; + hi = (i + 1) / scale; + } + else + { + var center = (i + 0.5) / scale; + lo = center - radius * stretch; + hi = center + radius * stretch; + } + int first = Math.Max(0, (int)Math.Floor(lo) - 1), last = Math.Min(source - 1, (int)Math.Ceiling(hi)); + int left = (int)Math.Floor(lo) - 1, right = (int)Math.Ceiling(hi); + Array.Clear(taps, first, last - first + 1); + var sum = 0.0; + for (var j = left; j <= right; j++) + { + double weight; + if (kind == ResampleFilter.Box) + { + weight = Math.Max(0, Math.Min(hi, j + 1) - Math.Max(lo, j)); + } + else + { + var x = (j + 0.5 - (i + 0.5) / scale) / stretch; + weight = kind == ResampleFilter.Lanczos3 ? Lanczos3(x) : CatmullRom(x); + } + if (weight == 0) continue; + taps[Math.Clamp(j, 0, source - 1)] += weight; // clamp-to-edge folds outside taps inward + sum += weight; + } + while (first < last && taps[first] == 0) first++; + while (last > first && taps[last] == 0) last--; + start[i] = first; + count[i] = last - first + 1; + for (var j = first; j <= last; j++) values[i * stride + j - first] = (float)(taps[j] / sum); + } + return new Weights { Length = target, Stride = stride, Start = start, Count = count, Values = values }; + } + + private static double Lanczos3(double x) + { + x = Math.Abs(x); + if (x < 1e-9) return 1; + if (x >= 3) return 0; + var px = Math.PI * x; + return 3 * Math.Sin(px) * Math.Sin(px / 3) / (px * px); + } + + private static double CatmullRom(double x) + { + x = Math.Abs(x); + return x < 1 ? (1.5 * x - 2.5) * x * x + 1 + : x < 2 ? ((-0.5 * x + 2.5) * x - 4) * x + 2 + : 0; + } + } +} diff --git a/tests/Titano.Core.Tests/Imaging/PixelConvertTests.cs b/tests/Titano.Core.Tests/Imaging/PixelConvertTests.cs new file mode 100644 index 00000000..17b2954e --- /dev/null +++ b/tests/Titano.Core.Tests/Imaging/PixelConvertTests.cs @@ -0,0 +1,128 @@ +using Titano.Core.Imaging; +using Titano.Testing; + +namespace Titano.Core.Tests.Imaging; + +public sealed class PixelConvertTests +{ + [Theory] + [Case(1)] + [Case(2)] + [Case(3)] + [Case(4)] + public void EightBitRoundTripIsExact(int channels) + { + const int w = 19, h = 7; + var pixels = new byte[w * h * channels]; + new Random(channels).NextBytes(pixels); + var keepAlpha = channels is 2 or 4; + using var image = PixelConvert.FromInterleaved8(pixels, w, h, channels, outputChannels: keepAlpha ? 4 : 0); + Assert.Equal(keepAlpha ? 4 : channels == 1 ? 1 : 3, image.Channels); + var back = PixelConvert.ToInterleaved8(image, channels); + Assert.SequenceEqual(pixels, back); + } + + [Test] + public void SixteenBitRoundTripWithinOneCode() + { + var samples = Enumerable.Range(0, 3 * 4096).Select(i => (ushort)(i * 16 % 65536)).ToArray(); + using var image = PixelConvert.FromInterleaved16(samples, 64, 64, 3); + var back = PixelConvert.ToInterleaved16(image, 3); + for (var i = 0; i < samples.Length; i++) Assert.InRange(back[i], samples[i] - 1, samples[i] + 1); + using var linear = PixelConvert.FromInterleaved16(samples, 64, 64, 3, TransferFunction.Linear); + Assert.SequenceEqual(samples, PixelConvert.ToInterleaved16(linear, 3, TransferFunction.Linear)); + } + + [Test] + public void CustomMaximumScalesTwelveBitData() + { + ushort[] samples = [0, 2048, 4095]; + using var image = PixelConvert.FromInterleaved16(samples, 3, 1, 1, TransferFunction.Linear, maxValue: 4095); + Assert.Approximately(2048 / 4095.0, image[0, 1, 0], 1e-6); + Assert.Equal(1f, image[0, 2, 0]); + } + + [Test] + public void GrayRgbConversions() + { + using var gray = PixelConvert.FromInterleaved8([0, 128, 255], 3, 1, 1); + using var rgb = PixelConvert.GrayToRgb(gray); + Assert.Equal(3, rgb.Channels); + Assert.Equal(gray[0, 1, 0], rgb[2, 1, 0]); + using var back = PixelConvert.RgbToGray(rgb); + Assert.Approximately(gray[0, 1, 0], back[0, 1, 0], 1e-6); + using var colour = PixelConvert.FromInterleaved8([255, 0, 0], 1, 1, 3, TransferFunction.Linear); + Assert.Equal((byte)Math.Round(ColorSpace.LinearToSrgb(ColorSpace.LumaR) * 255), PixelConvert.ToInterleaved8(colour, 1)[0]); + } + + [Theory] + [Case(1)] + [Case(2)] + [Case(3)] + [Case(4)] + [Case(5)] + [Case(6)] + [Case(7)] + [Case(8)] + public void OrientationMatchesExifDefinition(int orientation) + { + // A 3×2 image with unique values; Exif row 0 / column 0 placement per orientation (CIPA DC-008 table). + using var source = new ImageBuffer(3, 2, 1); + for (var i = 0; i < 6; i++) source.Plane(0)[i] = i; + using var result = PixelConvert.ApplyOrientation(source, orientation); + float[] expected = orientation switch + { + 1 => [0, 1, 2, 3, 4, 5], + 2 => [2, 1, 0, 5, 4, 3], + 3 => [5, 4, 3, 2, 1, 0], + 4 => [3, 4, 5, 0, 1, 2], + 5 => [0, 3, 1, 4, 2, 5], + 6 => [3, 0, 4, 1, 5, 2], + 7 => [5, 2, 4, 1, 3, 0], + _ => [2, 5, 1, 4, 0, 3], + }; + Assert.Equal(orientation >= 5 ? 2 : 3, result.Width); + Assert.SequenceEqual(expected, result.Plane(0).ToArray()); + } + + [Test] + public void LargeOrientationUsesTilesCorrectly() + { + using var source = new ImageBuffer(301, 157, 3); + for (var i = 0; i < source.Data.Length; i++) source.Data[i] = i; + using var rotated = PixelConvert.ApplyOrientation(source, 6); + using var back = PixelConvert.ApplyOrientation(rotated, 8); + Assert.SequenceEqual(source.Data.ToArray(), back.Data.ToArray()); + } + + [Test] + public void ClampHandlesNaNAndRange() + { + var values = Enumerable.Range(0, 37).Select(i => i % 5 == 0 ? float.NaN : i / 10f - 1f).ToArray(); + PixelConvert.Clamp(values); + for (var i = 0; i < values.Length; i++) Assert.InRange(values[i], 0, 1); + Assert.Equal(0f, values[5]); + } + + [Test] + public void DitherBreaksBandingButKeepsTheMean() + { + using var ramp = new ImageBuffer(256, 64, 1); + for (var y = 0; y < 64; y++) + { + for (var x = 0; x < 256; x++) ramp[0, x, y] = (float)ColorSpace.SrgbToLinear((100 + x / 64.0) / 255); + } + var plain = PixelConvert.ToInterleaved8(ramp, 1); + var dithered = PixelConvert.ToInterleaved8(ramp, 1, dither: true); + Assert.True(plain.Distinct().Count() <= 5, "a 4-code ramp quantises to few levels"); + for (var x0 = 0; x0 < 256; x0 += 64) + { + var mean = 0.0; + for (var y = 0; y < 64; y++) + { + for (var x = x0; x < x0 + 64; x++) mean += dithered[y * 256 + x]; + } + Assert.Approximately(100 + (x0 + 31.5) / 64.0, mean / (64 * 64), 0.15); + } + } +} diff --git a/tests/Titano.Core.Tests/Imaging/ResamplerTests.cs b/tests/Titano.Core.Tests/Imaging/ResamplerTests.cs new file mode 100644 index 00000000..4497cebb --- /dev/null +++ b/tests/Titano.Core.Tests/Imaging/ResamplerTests.cs @@ -0,0 +1,156 @@ +using System.Diagnostics; +using Titano.Core.Imaging; +using Titano.Testing; + +namespace Titano.Core.Tests.Imaging; + +public sealed class ResamplerTests(TestContext context) +{ + private static ImageBuffer Filled(int w, int h, Func value, int channels = 3) + { + var image = new ImageBuffer(w, h, channels); + for (var c = 0; c < channels; c++) + { + for (var y = 0; y < h; y++) + { + for (var x = 0; x < w; x++) image[c, x, y] = value(c, x, y); + } + } + return image; + } + + [Theory] + [Case(ResampleFilter.Lanczos3, 97, 31)] + [Case(ResampleFilter.Lanczos3, 400, 260)] + [Case(ResampleFilter.CatmullRom, 400, 260)] + [Case(ResampleFilter.CatmullRom, 20, 15)] + [Case(ResampleFilter.Box, 37, 23)] + [Case(ResampleFilter.Box, 333, 211)] + [Case(ResampleFilter.Auto, 300, 40)] + public void ConstantImageStaysConstant(ResampleFilter filter, int width, int height) + { + using var source = Filled(150, 100, (c, _, _) => 0.25f + 0.25f * c); + using var result = Resampler.Resize(source, width, height, filter); + Assert.Equal(width, result.Width); + Assert.Equal(height, result.Height); + for (var c = 0; c < 3; c++) + { + foreach (var v in result.Plane(c)) Assert.Approximately(0.25 + 0.25 * c, v, 1e-5); + } + } + + [Theory] + [Case(ResampleFilter.Lanczos3)] + [Case(ResampleFilter.Box)] + [Case(ResampleFilter.CatmullRom)] + public void DownscalePreservesEnergy(ResampleFilter filter) + { + var rng = new Random(4); + using var source = Filled(640, 480, (_, x, y) => (float)(rng.NextDouble() * 0.5 + 0.4 * Math.Sin(x * 0.05) * Math.Cos(y * 0.07) + 0.4), 1); + using var result = Resampler.Resize(source, 213, 157, filter); + double Mean(ImageBuffer b) => b.Plane(0).ToArray().Average(v => (double)v); + var ratio = Mean(result) / Mean(source); + context.Log($"{filter}: mean ratio {ratio:F5}"); + Assert.Approximately(1, ratio, 0.005); + } + + [Theory] + [Case(ResampleFilter.Lanczos3, 0.3)] + [Case(ResampleFilter.Lanczos3, 2.7)] + [Case(ResampleFilter.CatmullRom, 3.0)] + [Case(ResampleFilter.CatmullRom, 0.45)] + [Case(ResampleFilter.Box, 0.3)] + public void StepRingingStaysWithinKernelBounds(ResampleFilter filter, double scale) + { + const int w = 200; + using var step = Filled(w, 4, (_, x, _) => x < w / 2 + 0.3 ? 0f : 1f, 1); + using var result = Resampler.Resize(step, (int)(w * scale), 4, filter); + var values = result.Row(0, 1).ToArray(); + var bound = StepBound(filter, scale); + context.Log($"{filter} ×{scale}: range [{values.Min():F4}, {values.Max():F4}], bound {bound:F4}"); + Assert.GreaterOrEqual(values.Min(), -bound - 1e-4); + Assert.LessOrEqual(values.Max(), 1 + bound + 1e-4); + if (filter == ResampleFilter.Box) + { + Assert.GreaterOrEqual(values.Min(), 0); + Assert.LessOrEqual(values.Max(), 1 + 1e-6); + } + Assert.Approximately(0, values[0], 1e-5); + Assert.Approximately(1, values[^1], 1e-5); + } + + /// + /// The "Lanczos bound" for a step at this scale: every output sample is a normalised sum of kernel taps spaced + /// 1/stretch apart, so on a step it equals a partial sum of those taps. The bound is the largest excursion + /// outside [0, 1] of any partial sum, over all sub-pixel phases. + /// + private static double StepBound(ResampleFilter filter, double scale) + { + if (filter == ResampleFilter.Box) return 0; + var radius = filter == ResampleFilter.Lanczos3 ? 3.0 : 2.0; + var stretch = Math.Max(1, 1 / scale); + var reach = (int)Math.Ceiling(radius * stretch) + 1; + var worst = 0.0; + for (var phase = 0.0; phase < 1; phase += 1 / 512.0) + { + var taps = new List(); + for (var k = -reach; k <= reach; k++) taps.Add(Kernel(filter, (k + phase) / stretch)); + var total = taps.Sum(); + var running = 0.0; + foreach (var t in taps) + { + running += t / total; + worst = Math.Max(worst, Math.Max(running - 1, -running)); + } + } + return worst; + } + + private static double Kernel(ResampleFilter filter, double x) + { + var a = Math.Abs(x); + if (filter == ResampleFilter.Lanczos3) return a < 1e-12 ? 1 : a >= 3 ? 0 : 3 * Math.Sin(Math.PI * a) * Math.Sin(Math.PI * a / 3) / (Math.PI * Math.PI * a * a); + return a < 1 ? (1.5 * a - 2.5) * a * a + 1 : a < 2 ? ((-0.5 * a + 2.5) * a - 4) * a + 2 : 0; + } + + [Test] + public void ThumbnailFitsAndAveragesAreas() + { + using var source = Filled(1200, 800, (c, x, _) => x % 2 == 0 ? 1f : 0f); + using var thumb = Resampler.Thumbnail(source, 300); + Assert.Equal(300, thumb.Width); + Assert.Equal(200, thumb.Height); + foreach (var v in thumb.Plane(1)) Assert.Approximately(0.5, v, 1e-5); + Assert.Equal((300, 200), Resampler.FitWithin(1200, 800, 300)); + Assert.Equal((10, 20), Resampler.FitWithin(10, 20, 300)); + using var small = Resampler.Thumbnail(thumb, 1000); + Assert.Equal(300, small.Width); + } + + [Test] + public void UpscaleInterpolatesThroughSamples() + { + using var source = Filled(16, 16, (_, x, y) => x * 0.05f + y * 0.01f, 1); + using var up = Resampler.Resize(source, 64, 64, ResampleFilter.CatmullRom); + // Catmull-Rom reproduces linear ramps exactly away from the edges. + for (var x = 8; x < 56; x++) + { + var sx = (x + 0.5) / 4 - 0.5; + Assert.Approximately(sx * 0.05 + ((20 + 0.5) / 4 - 0.5) * 0.01, up[0, x, 20], 1e-4); + } + } + + [Test] + public void TwentyFourMegapixelThumbnailIsFast() + { + using var source = new ImageBuffer(6000, 4000, 3, clear: true); + var sw = Stopwatch.StartNew(); + using var thumb = Resampler.Thumbnail(source, 320); + var box = sw.Elapsed; + sw.Restart(); + using var lanczos = Resampler.Resize(source, 1920, 1280); + context.Log($"24 MP → 320 px box {box.TotalMilliseconds:F0} ms; → 1920 px Lanczos3 {sw.Elapsed.TotalMilliseconds:F0} ms"); + Assert.Equal(320, thumb.Width); + Assert.Less(box.TotalSeconds, 2.5); + } +}