using System.Buffers; using System.Numerics; using System.Runtime.CompilerServices; namespace Titano.Core.Imaging; /// How integer samples relate to light: sRGB-encoded (display referred) or proportional to linear light. public enum TransferFunction { Srgb, Linear, } /// /// Conversions between interleaved integer pixels and planar linear-light s, gray ↔ RGB, /// Exif orientation, and clamping. Interleaved layouts: 1 = gray, 2 = gray+alpha, 3 = RGB, 4 = RGBA. Alpha is /// never transfer-encoded. Row loops are parallel for large images. /// public static class PixelConvert { private const int ParallelThreshold = 1 << 16; /// 8×8 Bayer thresholds in code units, centred on zero (ordered dither). private static readonly float[] Bayer = BuildBayer(); /// Interleaved 8-bit samples → linear buffer. /// 0 = natural (1/2 → 1, 3 → 3, 4 → 3); 3 expands gray; 4 keeps alpha. public static ImageBuffer FromInterleaved8(ReadOnlySpan pixels, int width, int height, int channels, TransferFunction transfer = TransferFunction.Srgb, int outputChannels = 0) { var outCh = OutputChannels(channels, outputChannels); CheckLength(pixels.Length, width, height, channels); var lut = new float[256]; for (var i = 0; i < 256; i++) lut[i] = transfer == TransferFunction.Srgb ? ColorSpace.Linear8((byte)i) : i / 255f; var image = new ImageBuffer(width, height, outCh, clear: false); unsafe { fixed (byte* p = pixels) { var ptr = (nint)p; ForRows(height, width, y => { var row = new ReadOnlySpan((byte*)ptr + (long)y * width * channels, width * channels); Scatter(row, image, y, channels, lut, 1f / 255f); }); } } return image; } /// Interleaved 16-bit container samples (values 0..) → linear buffer. public static ImageBuffer FromInterleaved16(ReadOnlySpan pixels, int width, int height, int channels, TransferFunction transfer = TransferFunction.Srgb, int maxValue = 65535, int outputChannels = 0) { if (maxValue is < 1 or > 65535) throw new ArgumentOutOfRangeException(nameof(maxValue)); var outCh = OutputChannels(channels, outputChannels); CheckLength(pixels.Length, width, height, channels); var lut = new float[maxValue + 1]; for (var i = 0; i <= maxValue; i++) { lut[i] = transfer == TransferFunction.Linear ? i / (float)maxValue : maxValue == 65535 ? ColorSpace.Linear16((ushort)i) : (float)ColorSpace.SrgbToLinear(i / (double)maxValue); } var alphaScale = 1f / maxValue; var image = new ImageBuffer(width, height, outCh, clear: false); unsafe { fixed (ushort* p = pixels) { var ptr = (nint)p; ForRows(height, width, y => { var row = new ReadOnlySpan((ushort*)ptr + (long)y * width * channels, width * channels); Scatter(row, image, y, channels, lut, alphaScale); }); } } return image; } /// Linear buffer → interleaved 8-bit samples with per pixel /// (1 from RGB takes Rec.709 luminance; missing alpha is opaque). /// Add 8×8 ordered dither before rounding (breaks banding in smooth gradients). public static void ToInterleaved8(ImageBuffer image, Span destination, int channels, TransferFunction transfer = TransferFunction.Srgb, bool dither = false) { CheckLength(destination.Length, image.Width, image.Height, channels); unsafe { fixed (byte* p = destination) { var ptr = (nint)p; ForRows(image.Height, image.Width, y => { var row = new Span((byte*)ptr + (long)y * image.Width * channels, image.Width * channels); EncodeRow8(image, y, row, channels, transfer, dither); }); } } } /// Allocating overload of . public static byte[] ToInterleaved8(ImageBuffer image, int channels, TransferFunction transfer = TransferFunction.Srgb, bool dither = false) { var result = new byte[checked(image.Width * image.Height * channels)]; ToInterleaved8(image, result, channels, transfer, dither); return result; } /// Linear buffer → interleaved 16-bit samples (0..65535). public static void ToInterleaved16(ImageBuffer image, Span destination, int channels, TransferFunction transfer = TransferFunction.Srgb) { CheckLength(destination.Length, image.Width, image.Height, channels); unsafe { fixed (ushort* p = destination) { var ptr = (nint)p; ForRows(image.Height, image.Width, y => { var row = new Span((ushort*)ptr + (long)y * image.Width * channels, image.Width * channels); EncodeRow16(image, y, row, channels, transfer); }); } } } /// Allocating overload of . public static ushort[] ToInterleaved16(ImageBuffer image, int channels, TransferFunction transfer = TransferFunction.Srgb) { var result = new ushort[checked(image.Width * image.Height * channels)]; ToInterleaved16(image, result, channels, transfer); return result; } /// Encodes row into interleaved 8-bit samples (codec edge helper). internal static void EncodeRow8(ImageBuffer image, int y, Span row, int channels, TransferFunction transfer, bool dither) { Span offsets = stackalloc float[8]; for (var i = 0; i < 8; i++) offsets[i] = dither ? 0.5f + Bayer[(y & 7) * 8 + i] : 0.5f; var srgb = transfer == TransferFunction.Srgb; var scratch = channels <= 2 && image.Channels >= 3 ? ArrayPool.Shared.Rent(image.Width) : null; for (var c = 0; c < channels; c++) { if (c == (channels <= 2 ? 1 : 3)) { var a = image.Channels == 4 ? image.Row(3, y) : default; for (var x = 0; x < image.Width; x++) row[x * channels + c] = a.IsEmpty ? (byte)255 : (byte)(Math.Clamp(a[x], 0f, 1f) * 255f + 0.5f); continue; } var src = ColourRow(image, y, c, channels, scratch); for (var x = 0; x < src.Length; x++) { var e = srgb ? ColorSpace.EncodeFast(src[x]) : Math.Clamp(src[x], 0f, 1f); row[x * channels + c] = (byte)Math.Clamp(e * 255f + offsets[x & 7], 0f, 255f); } } if (scratch is not null) ArrayPool.Shared.Return(scratch); } /// Encodes row into interleaved 16-bit samples (codec edge helper). internal static void EncodeRow16(ImageBuffer image, int y, Span row, int channels, TransferFunction transfer) { var srgb = transfer == TransferFunction.Srgb; var scratch = channels <= 2 && image.Channels >= 3 ? ArrayPool.Shared.Rent(image.Width) : null; for (var c = 0; c < channels; c++) { if (c == (channels <= 2 ? 1 : 3)) { var a = image.Channels == 4 ? image.Row(3, y) : default; for (var x = 0; x < image.Width; x++) row[x * channels + c] = a.IsEmpty ? (ushort)65535 : (ushort)(Math.Clamp(a[x], 0f, 1f) * 65535f + 0.5f); continue; } var src = ColourRow(image, y, c, channels, scratch); for (var x = 0; x < src.Length; x++) { row[x * channels + c] = srgb ? ColorSpace.Encode16(src[x]) : (ushort)(Math.Clamp(src[x], 0f, 1f) * 65535f + 0.5f); } } if (scratch is not null) ArrayPool.Shared.Return(scratch); } /// Single-channel buffer replicated into three channels. public static ImageBuffer GrayToRgb(ImageBuffer gray) { if (gray.Channels != 1) throw new ArgumentException("Expected one channel", nameof(gray)); var rgb = new ImageBuffer(gray.Width, gray.Height, 3, clear: false); for (var c = 0; c < 3; c++) gray.Plane(0).CopyTo(rgb.Plane(c)); return rgb; } /// Rec.709 luminance of an RGB(A) buffer. public static ImageBuffer RgbToGray(ImageBuffer rgb) { if (rgb.Channels < 3) throw new ArgumentException("Expected RGB", nameof(rgb)); var gray = new ImageBuffer(rgb.Width, rgb.Height, 1, clear: false); var r = rgb.Plane(0); var g = rgb.Plane(1); var b = rgb.Plane(2); var d = gray.Plane(0); var i = 0; if (Vector.IsHardwareAccelerated) { var wr = new Vector(ColorSpace.LumaR); var wg = new Vector(ColorSpace.LumaG); var wb = new Vector(ColorSpace.LumaB); for (; i <= d.Length - Vector.Count; i += Vector.Count) { (new Vector(r[i..]) * wr + new Vector(g[i..]) * wg + new Vector(b[i..]) * wb).CopyTo(d[i..]); } } for (; i < d.Length; i++) d[i] = ColorSpace.Luminance(r[i], g[i], b[i]); return gray; } /// Clamps every value into [, ] (NaN becomes ). public static void Clamp(Span values, float min = 0f, float max = 1f) { var i = 0; if (Vector.IsHardwareAccelerated) { var lo = new Vector(min); var hi = new Vector(max); for (; i <= values.Length - Vector.Count; i += Vector.Count) { var v = new Vector(values[i..]); // Max(v, lo) with v as the first operand maps NaN to lo on x86 (maxps returns the second operand). Vector.Min(Vector.ConditionalSelect(Vector.Equals(v, v), Vector.Max(v, lo), lo), hi).CopyTo(values[i..]); } } for (; i < values.Length; i++) { var v = values[i]; values[i] = float.IsNaN(v) ? min : Math.Clamp(v, min, max); } } /// Size after applying an Exif orientation (5–8 swap width and height). public static (int Width, int Height) OrientedSize(int width, int height, int orientation) => orientation is >= 5 and <= 8 ? (height, width) : (width, height); /// Applies an Exif orientation (1–8) into a new buffer; other values are treated as 1 (copy). public static ImageBuffer ApplyOrientation(ImageBuffer source, int orientation) { int w = source.Width, h = source.Height; var (ow, oh) = OrientedSize(w, h, orientation); var result = new ImageBuffer(ow, oh, source.Channels, clear: false); if (orientation is < 2 or > 8) { source.CopyTo(result); return result; } for (var c = 0; c < source.Channels; c++) { var src = source.Storage.AsMemory(c * source.PlaneLength, source.PlaneLength); var dst = result.Storage.AsMemory(c * result.PlaneLength, result.PlaneLength); if (orientation <= 4) { ForRows(oh, ow, y => { var sy = orientation is 3 or 4 ? h - 1 - y : y; var s = src.Span.Slice(sy * w, w); var d = dst.Span.Slice(y * ow, ow); s.CopyTo(d); if (orientation is 2 or 3) d.Reverse(); }); continue; } // Transposing orientations: copy in 32×32 tiles so both sides stay cache-friendly. const int tile = 32; var tilesY = (oh + tile - 1) / tile; ForRows(tilesY, ow * tile, ty => { var s = src.Span; var d = dst.Span; var y1 = Math.Min(oh, (ty + 1) * tile); for (var x0 = 0; x0 < ow; x0 += tile) { var x1 = Math.Min(ow, x0 + tile); for (var y = ty * tile; y < y1; y++) { for (var x = x0; x < x1; x++) { var (sx, sy) = orientation switch { 5 => (y, x), 6 => (y, h - 1 - x), 7 => (w - 1 - y, h - 1 - x), _ => (w - 1 - y, x), }; d[y * ow + x] = s[sy * w + sx]; } } } }); } return result; } /// Linear row feeding output colour channel : gray is replicated, and a gray output /// from RGB takes Rec.709 luminance computed into . private static ReadOnlySpan ColourRow(ImageBuffer image, int y, int c, int channels, float[]? scratch) { if (image.Channels == 1) return image.Row(0, y); if (scratch is null) return image.Row(c, y); var r = image.Row(0, y); var g = image.Row(1, y); var b = image.Row(2, y); var luminance = scratch.AsSpan(0, image.Width); for (var x = 0; x < luminance.Length; x++) luminance[x] = ColorSpace.Luminance(r[x], g[x], b[x]); return luminance; } /// De-interleaves one row: colour through (indices clamped to its range), alpha scaled. private static void Scatter(ReadOnlySpan row, ImageBuffer image, int y, int channels, float[] lut, float alphaScale) where T : unmanaged, IBinaryInteger { var w = image.Width; var top = lut.Length - 1; var colour = channels is 1 or 2 ? 1 : 3; for (var c = 0; c < image.Channels; c++) { var dst = image.Row(c, y); if (c == 3) { if (channels is 2 or 4) { var a = channels - 1; for (var x = 0; x < w; x++) dst[x] = Math.Min(int.CreateTruncating(row[x * channels + a]), top) * alphaScale; } else { dst.Fill(1f); } continue; } var s = colour == 1 ? 0 : c; for (var x = 0; x < w; x++) dst[x] = lut[Math.Min(int.CreateTruncating(row[x * channels + s]), top)]; } } private static int OutputChannels(int channels, int requested) { if (channels is < 1 or > 4) throw new ArgumentOutOfRangeException(nameof(channels)); if (requested is not (0 or 1 or 3 or 4)) throw new ArgumentOutOfRangeException(nameof(requested)); if (requested == 1 && channels > 2) throw new ArgumentException("Use RgbToGray to reduce colour to one channel", nameof(requested)); return requested != 0 ? requested : channels <= 2 ? 1 : 3; } private static void CheckLength(int length, int width, int height, int channels) { ArgumentOutOfRangeException.ThrowIfNegativeOrZero(width); ArgumentOutOfRangeException.ThrowIfNegativeOrZero(height); if (channels is < 1 or > 4) throw new ArgumentOutOfRangeException(nameof(channels)); if (length < (long)width * height * channels) throw new ArgumentException("Pixel buffer too small"); } [MethodImpl(MethodImplOptions.AggressiveInlining)] private static void ForRows(int rows, int rowWork, Action body) { if ((long)rows * rowWork < ParallelThreshold) { for (var y = 0; y < rows; y++) body(y); } else { Parallel.For(0, rows, body); } } private static float[] BuildBayer() { // Recursive Bayer matrix: interleave bits of (x ^ y) and y, least significant coordinate bits first. var m = new float[64]; for (var y = 0; y < 8; y++) { for (var x = 0; x < 8; x++) { var v = 0; for (var bit = 0; bit < 3; bit++) v = v << 2 | (((x ^ y) >> bit) & 1) << 1 | ((y >> bit) & 1); m[y * 8 + x] = (v + 0.5f) / 64f - 0.5f; } } return m; } }