Files
Chronos/src/Titano.Core/Imaging/PixelConvert.cs
T
Claude f2c0709ef2 refactor(codecs): pool luminance rows and gate timing on optimised builds
EncodeRow8/16 reuse one pooled scratch row for RGB-to-gray output
instead of allocating per row; drop unused JPEG marker constants; the
24 MP timing test skips itself when the JIT optimiser is disabled.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
2026-10-02 10:12:49 +00:00

384 lines
17 KiB
C#
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.
using System.Buffers;
using System.Numerics;
using System.Runtime.CompilerServices;
namespace Titano.Core.Imaging;
/// <summary>How integer samples relate to light: sRGB-encoded (display referred) or proportional to linear light.</summary>
public enum TransferFunction
{
Srgb,
Linear,
}
/// <summary>
/// Conversions between interleaved integer pixels and planar linear-light <see cref="ImageBuffer"/>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.
/// </summary>
public static class PixelConvert
{
private const int ParallelThreshold = 1 << 16;
/// <summary>8×8 Bayer thresholds in code units, centred on zero (ordered dither).</summary>
private static readonly float[] Bayer = BuildBayer();
/// <summary>Interleaved 8-bit samples → linear buffer.</summary>
/// <param name="outputChannels">0 = natural (1/2 → 1, 3 → 3, 4 → 3); 3 expands gray; 4 keeps alpha.</param>
public static ImageBuffer FromInterleaved8(ReadOnlySpan<byte> 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>((byte*)ptr + (long)y * width * channels, width * channels);
Scatter(row, image, y, channels, lut, 1f / 255f);
});
}
}
return image;
}
/// <summary>Interleaved 16-bit container samples (values 0..<paramref name="maxValue"/>) → linear buffer.</summary>
public static ImageBuffer FromInterleaved16(ReadOnlySpan<ushort> 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>((ushort*)ptr + (long)y * width * channels, width * channels);
Scatter(row, image, y, channels, lut, alphaScale);
});
}
}
return image;
}
/// <summary>Linear buffer → interleaved 8-bit samples with <paramref name="channels"/> per pixel
/// (1 from RGB takes Rec.709 luminance; missing alpha is opaque).</summary>
/// <param name="dither">Add 8×8 ordered dither before rounding (breaks banding in smooth gradients).</param>
public static void ToInterleaved8(ImageBuffer image, Span<byte> 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>((byte*)ptr + (long)y * image.Width * channels, image.Width * channels);
EncodeRow8(image, y, row, channels, transfer, dither);
});
}
}
}
/// <summary>Allocating overload of <see cref="ToInterleaved8(ImageBuffer, Span{byte}, int, TransferFunction, bool)"/>.</summary>
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;
}
/// <summary>Linear buffer → interleaved 16-bit samples (0..65535).</summary>
public static void ToInterleaved16(ImageBuffer image, Span<ushort> 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>((ushort*)ptr + (long)y * image.Width * channels, image.Width * channels);
EncodeRow16(image, y, row, channels, transfer);
});
}
}
}
/// <summary>Allocating overload of <see cref="ToInterleaved16(ImageBuffer, Span{ushort}, int, TransferFunction)"/>.</summary>
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;
}
/// <summary>Encodes row <paramref name="y"/> into interleaved 8-bit samples (codec edge helper).</summary>
internal static void EncodeRow8(ImageBuffer image, int y, Span<byte> row, int channels, TransferFunction transfer, bool dither)
{
Span<float> 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<float>.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<float>.Shared.Return(scratch);
}
/// <summary>Encodes row <paramref name="y"/> into interleaved 16-bit samples (codec edge helper).</summary>
internal static void EncodeRow16(ImageBuffer image, int y, Span<ushort> row, int channels, TransferFunction transfer)
{
var srgb = transfer == TransferFunction.Srgb;
var scratch = channels <= 2 && image.Channels >= 3 ? ArrayPool<float>.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<float>.Shared.Return(scratch);
}
/// <summary>Single-channel buffer replicated into three channels.</summary>
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;
}
/// <summary>Rec.709 luminance of an RGB(A) buffer.</summary>
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<float>(ColorSpace.LumaR);
var wg = new Vector<float>(ColorSpace.LumaG);
var wb = new Vector<float>(ColorSpace.LumaB);
for (; i <= d.Length - Vector<float>.Count; i += Vector<float>.Count)
{
(new Vector<float>(r[i..]) * wr + new Vector<float>(g[i..]) * wg + new Vector<float>(b[i..]) * wb).CopyTo(d[i..]);
}
}
for (; i < d.Length; i++) d[i] = ColorSpace.Luminance(r[i], g[i], b[i]);
return gray;
}
/// <summary>Clamps every value into [<paramref name="min"/>, <paramref name="max"/>] (NaN becomes <paramref name="min"/>).</summary>
public static void Clamp(Span<float> values, float min = 0f, float max = 1f)
{
var i = 0;
if (Vector.IsHardwareAccelerated)
{
var lo = new Vector<float>(min);
var hi = new Vector<float>(max);
for (; i <= values.Length - Vector<float>.Count; i += Vector<float>.Count)
{
var v = new Vector<float>(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);
}
}
/// <summary>Size after applying an Exif orientation (5–8 swap width and height).</summary>
public static (int Width, int Height) OrientedSize(int width, int height, int orientation) =>
orientation is >= 5 and <= 8 ? (height, width) : (width, height);
/// <summary>Applies an Exif orientation (1–8) into a new buffer; other values are treated as 1 (copy).</summary>
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;
}
/// <summary>Linear row feeding output colour channel <paramref name="c"/>: gray is replicated, and a gray output
/// from RGB takes Rec.709 luminance computed into <paramref name="scratch"/>.</summary>
private static ReadOnlySpan<float> 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;
}
/// <summary>De-interleaves one row: colour through <paramref name="lut"/> (indices clamped to its range), alpha scaled.</summary>
private static void Scatter<T>(ReadOnlySpan<T> row, ImageBuffer image, int y, int channels, float[] lut, float alphaScale)
where T : unmanaged, IBinaryInteger<T>
{
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<int> 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;
}
}