feat(math): add Matrix3, Bradford adaptation and chromaticity
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
3 files changed
+214
No files matched your search
@@ -0,0 +1,39 @@
|
||||
namespace Titano.Core.Mathematics;
|
||||
|
||||
/// <summary>CIE 1931 chromaticity coordinates (lower-case x, y in the literature).</summary>
|
||||
public readonly record struct Chromaticity(double X, double Y)
|
||||
{
|
||||
/// <summary>CIE standard illuminant D65 (2° observer).</summary>
|
||||
public static Chromaticity D65 { get; } = new(0.3127, 0.3290);
|
||||
|
||||
/// <summary>CIE standard illuminant D50 (2° observer), the ICC/DNG profile connection white.</summary>
|
||||
public static Chromaticity D50 { get; } = new(0.3457, 0.3585);
|
||||
|
||||
/// <summary>Tristimulus values with luminance <paramref name="luminance"/>: X = x·Y/y, Z = (1 − x − y)·Y/y.</summary>
|
||||
public Vector3D ToXyz(double luminance = 1)
|
||||
{
|
||||
if (!(Y > 0)) throw new InvalidOperationException("Chromaticity y must be positive.");
|
||||
return new Vector3D(X * luminance / Y, luminance, (1 - X - Y) * luminance / Y);
|
||||
}
|
||||
|
||||
/// <summary>Chromaticity of tristimulus values; NaN coordinates when X + Y + Z is not positive.</summary>
|
||||
public static Chromaticity FromXyz(Vector3D xyz)
|
||||
{
|
||||
var sum = xyz.X + xyz.Y + xyz.Z;
|
||||
return sum > 0 ? new Chromaticity(xyz.X / sum, xyz.Y / sum) : new Chromaticity(double.NaN, double.NaN);
|
||||
}
|
||||
|
||||
/// <summary>CIE 1960 UCS coordinates u = 4x/(−2x + 12y + 3), v = 6y/(−2x + 12y + 3).</summary>
|
||||
public (double U, double V) ToUv1960()
|
||||
{
|
||||
var d = -2 * X + 12 * Y + 3;
|
||||
return (4 * X / d, 6 * Y / d);
|
||||
}
|
||||
|
||||
/// <summary>Chromaticity from CIE 1960 UCS coordinates.</summary>
|
||||
public static Chromaticity FromUv1960(double u, double v)
|
||||
{
|
||||
var d = 2 * u - 8 * v + 4;
|
||||
return new Chromaticity(3 * u / d, 2 * v / d);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,105 @@
|
||||
namespace Titano.Core.Mathematics;
|
||||
|
||||
/// <summary>A 3-vector in double precision (colour triplets, homogeneous 2-D points).</summary>
|
||||
public readonly record struct Vector3D(double X, double Y, double Z)
|
||||
{
|
||||
public static Vector3D operator +(Vector3D a, Vector3D b) => new(a.X + b.X, a.Y + b.Y, a.Z + b.Z);
|
||||
|
||||
public static Vector3D operator -(Vector3D a, Vector3D b) => new(a.X - b.X, a.Y - b.Y, a.Z - b.Z);
|
||||
|
||||
public static Vector3D operator *(Vector3D a, double s) => new(a.X * s, a.Y * s, a.Z * s);
|
||||
|
||||
public static double Dot(Vector3D a, Vector3D b) => a.X * b.X + a.Y * b.Y + a.Z * b.Z;
|
||||
}
|
||||
|
||||
/// <summary>Row-major 3×3 matrix in double precision for colour-space and planar projective work.</summary>
|
||||
public readonly record struct Matrix3(
|
||||
double M11, double M12, double M13,
|
||||
double M21, double M22, double M23,
|
||||
double M31, double M32, double M33)
|
||||
{
|
||||
public static Matrix3 Identity { get; } = new(1, 0, 0, 0, 1, 0, 0, 0, 1);
|
||||
|
||||
/// <summary>Bradford cone-response matrix (Lam 1985), XYZ → sharpened LMS.</summary>
|
||||
public static Matrix3 Bradford { get; } = new(
|
||||
0.8951, 0.2664, -0.1614,
|
||||
-0.7502, 1.7135, 0.0367,
|
||||
0.0389, -0.0685, 1.0296);
|
||||
|
||||
/// <summary>Linear Rec.709/sRGB (D65) → CIE XYZ, derived from the primaries.</summary>
|
||||
public static Matrix3 Rec709ToXyz { get; } = RgbToXyz(new(0.64, 0.33), new(0.30, 0.60), new(0.15, 0.06), Chromaticity.D65);
|
||||
|
||||
/// <summary>CIE XYZ → linear Rec.709/sRGB (D65).</summary>
|
||||
public static Matrix3 XyzToRec709 { get; } = Rec709ToXyz.Inverse();
|
||||
|
||||
public static Matrix3 Diagonal(double a, double b, double c) => new(a, 0, 0, 0, b, 0, 0, 0, c);
|
||||
|
||||
/// <summary>Matrix whose columns are <paramref name="c1"/>, <paramref name="c2"/>, <paramref name="c3"/>.</summary>
|
||||
public static Matrix3 FromColumns(Vector3D c1, Vector3D c2, Vector3D c3) => new(c1.X, c2.X, c3.X, c1.Y, c2.Y, c3.Y, c1.Z, c2.Z, c3.Z);
|
||||
|
||||
public static Matrix3 operator *(Matrix3 a, Matrix3 b) => new(
|
||||
a.M11 * b.M11 + a.M12 * b.M21 + a.M13 * b.M31, a.M11 * b.M12 + a.M12 * b.M22 + a.M13 * b.M32, a.M11 * b.M13 + a.M12 * b.M23 + a.M13 * b.M33,
|
||||
a.M21 * b.M11 + a.M22 * b.M21 + a.M23 * b.M31, a.M21 * b.M12 + a.M22 * b.M22 + a.M23 * b.M32, a.M21 * b.M13 + a.M22 * b.M23 + a.M23 * b.M33,
|
||||
a.M31 * b.M11 + a.M32 * b.M21 + a.M33 * b.M31, a.M31 * b.M12 + a.M32 * b.M22 + a.M33 * b.M32, a.M31 * b.M13 + a.M32 * b.M23 + a.M33 * b.M33);
|
||||
|
||||
public static Vector3D operator *(Matrix3 m, Vector3D v) => new(
|
||||
m.M11 * v.X + m.M12 * v.Y + m.M13 * v.Z,
|
||||
m.M21 * v.X + m.M22 * v.Y + m.M23 * v.Z,
|
||||
m.M31 * v.X + m.M32 * v.Y + m.M33 * v.Z);
|
||||
|
||||
public static Matrix3 operator *(Matrix3 m, double s) => new(
|
||||
m.M11 * s, m.M12 * s, m.M13 * s, m.M21 * s, m.M22 * s, m.M23 * s, m.M31 * s, m.M32 * s, m.M33 * s);
|
||||
|
||||
public double Determinant =>
|
||||
M11 * (M22 * M33 - M23 * M32) - M12 * (M21 * M33 - M23 * M31) + M13 * (M21 * M32 - M22 * M31);
|
||||
|
||||
public Matrix3 Transpose() => new(M11, M21, M31, M12, M22, M32, M13, M23, M33);
|
||||
|
||||
/// <summary>Inverse by the adjugate; false when the matrix is singular relative to its scale.</summary>
|
||||
public bool TryInvert(out Matrix3 inverse)
|
||||
{
|
||||
var det = Determinant;
|
||||
var scale = MaxAbs();
|
||||
if (!(Math.Abs(det) > 1e-14 * scale * scale * scale) || !double.IsFinite(det))
|
||||
{
|
||||
inverse = default;
|
||||
return false;
|
||||
}
|
||||
var r = 1 / det;
|
||||
inverse = new Matrix3(
|
||||
(M22 * M33 - M23 * M32) * r, (M13 * M32 - M12 * M33) * r, (M12 * M23 - M13 * M22) * r,
|
||||
(M23 * M31 - M21 * M33) * r, (M11 * M33 - M13 * M31) * r, (M13 * M21 - M11 * M23) * r,
|
||||
(M21 * M32 - M22 * M31) * r, (M12 * M31 - M11 * M32) * r, (M11 * M22 - M12 * M21) * r);
|
||||
return true;
|
||||
}
|
||||
|
||||
/// <exception cref="InvalidOperationException">The matrix is singular.</exception>
|
||||
public Matrix3 Inverse() => TryInvert(out var inverse) ? inverse : throw new InvalidOperationException("Matrix is singular.");
|
||||
|
||||
/// <summary>
|
||||
/// Bradford chromatic adaptation (von Kries scaling in the Bradford cone space) mapping colours seen under
|
||||
/// <paramref name="sourceWhite"/> to <paramref name="destinationWhite"/>; both whites as XYZ.
|
||||
/// </summary>
|
||||
public static Matrix3 BradfordAdaptation(Vector3D sourceWhite, Vector3D destinationWhite)
|
||||
{
|
||||
var s = Bradford * sourceWhite;
|
||||
var d = Bradford * destinationWhite;
|
||||
if (!(s.X > 0 && s.Y > 0 && s.Z > 0)) throw new ArgumentOutOfRangeException(nameof(sourceWhite), "White point must have positive cone responses.");
|
||||
return Bradford.Inverse() * Diagonal(d.X / s.X, d.Y / s.Y, d.Z / s.Z) * Bradford;
|
||||
}
|
||||
|
||||
/// <summary>RGB → XYZ matrix of an additive colour space from its primaries and white point (white maps to Y = 1).</summary>
|
||||
public static Matrix3 RgbToXyz(Chromaticity red, Chromaticity green, Chromaticity blue, Chromaticity white)
|
||||
{
|
||||
var primaries = FromColumns(red.ToXyz(), green.ToXyz(), blue.ToXyz());
|
||||
var s = primaries.Inverse() * white.ToXyz();
|
||||
return primaries * Diagonal(s.X, s.Y, s.Z);
|
||||
}
|
||||
|
||||
private double MaxAbs()
|
||||
{
|
||||
var m = Math.Max(Math.Max(Math.Abs(M11), Math.Abs(M12)), Math.Abs(M13));
|
||||
m = Math.Max(m, Math.Max(Math.Max(Math.Abs(M21), Math.Abs(M22)), Math.Abs(M23)));
|
||||
return Math.Max(m, Math.Max(Math.Max(Math.Abs(M31), Math.Abs(M32)), Math.Abs(M33)));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,70 @@
|
||||
using Titano.Core.Imaging;
|
||||
using Titano.Core.Mathematics;
|
||||
using Titano.Testing;
|
||||
|
||||
namespace Titano.Core.Tests.Mathematics;
|
||||
|
||||
public sealed class Matrix3Tests
|
||||
{
|
||||
[Test]
|
||||
public void InverseAndTranspose()
|
||||
{
|
||||
var m = new Matrix3(2, -1, 0.5, 0.3, 4, 1, -2, 0.7, 3);
|
||||
AssertClose(Matrix3.Identity, m * m.Inverse(), 1e-12);
|
||||
AssertClose(Matrix3.Identity, m.Inverse() * m, 1e-12);
|
||||
Assert.Equal(m, m.Transpose().Transpose());
|
||||
Assert.Equal(m.M12, m.Transpose().M21);
|
||||
Assert.Approximately(m.Determinant, m.Transpose().Determinant, 1e-12);
|
||||
Assert.False(new Matrix3(1, 2, 3, 2, 4, 6, 0, 1, 1).TryInvert(out _));
|
||||
Assert.Throws<InvalidOperationException>(() => new Matrix3(0, 0, 0, 0, 0, 0, 0, 0, 0).Inverse());
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void BradfordD65ToD50MatchesLindbloom()
|
||||
{
|
||||
// Lindbloom's published matrix uses these tristimulus whites.
|
||||
var d65 = new Vector3D(0.95047, 1.0, 1.08883);
|
||||
var d50 = new Vector3D(0.96422, 1.0, 0.82521);
|
||||
var expected = new Matrix3(
|
||||
1.0478112, 0.0228866, -0.0501270,
|
||||
0.0295424, 0.9904844, -0.0170491,
|
||||
-0.0092345, 0.0150436, 0.7521316);
|
||||
var adaptation = Matrix3.BradfordAdaptation(d65, d50);
|
||||
AssertClose(expected, adaptation, 1e-6);
|
||||
var mapped = adaptation * d65;
|
||||
Assert.Approximately(d50.X, mapped.X, 1e-12);
|
||||
Assert.Approximately(d50.Z, mapped.Z, 1e-12);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void Rec709MatrixMatchesLumaWeightsAndWhite()
|
||||
{
|
||||
var m = Matrix3.Rec709ToXyz;
|
||||
Assert.Approximately(ColorSpace.LumaR, m.M21, 1e-4);
|
||||
Assert.Approximately(ColorSpace.LumaG, m.M22, 1e-4);
|
||||
Assert.Approximately(ColorSpace.LumaB, m.M23, 1e-4);
|
||||
var white = Chromaticity.FromXyz(m * new Vector3D(1, 1, 1));
|
||||
Assert.Within(0.3127, 0.3290, white.X, white.Y, 1e-12);
|
||||
AssertClose(Matrix3.Identity, Matrix3.XyzToRec709 * m, 1e-12);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void ChromaticityRoundTrips()
|
||||
{
|
||||
var xyz = Chromaticity.D50.ToXyz(0.4);
|
||||
var back = Chromaticity.FromXyz(xyz);
|
||||
Assert.Within(0.3457, 0.3585, back.X, back.Y, 1e-14);
|
||||
Assert.Approximately(0.4, xyz.Y, 1e-15);
|
||||
var (u, v) = Chromaticity.D65.ToUv1960();
|
||||
var again = Chromaticity.FromUv1960(u, v);
|
||||
Assert.Within(0.3127, 0.3290, again.X, again.Y, 1e-14);
|
||||
Assert.True(double.IsNaN(Chromaticity.FromXyz(new Vector3D(0, 0, 0)).X));
|
||||
}
|
||||
|
||||
private static void AssertClose(Matrix3 expected, Matrix3 actual, double tolerance)
|
||||
{
|
||||
double[] e = [expected.M11, expected.M12, expected.M13, expected.M21, expected.M22, expected.M23, expected.M31, expected.M32, expected.M33];
|
||||
double[] a = [actual.M11, actual.M12, actual.M13, actual.M21, actual.M22, actual.M23, actual.M31, actual.M32, actual.M33];
|
||||
for (var i = 0; i < 9; i++) Assert.Approximately(e[i], a[i], tolerance, $"element {i}");
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user