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;
}
}