Class Lut3D

Namespace

Egami.Operations

Assembly

Egami.dll

A 3D color lookup table: an N × N × N grid of output RGB values over the input cube, with red varying fastest, as .cube files and Hald images store it, and an optional 1D shaper per channel read before the grid (DaVinci Resolve's 1D-plus-3D .cube). Read one with Read(string, EgamiContext?) or FromHald(Raster), and apply it with FromLut(Lut3D, LutInterpolation).

public sealed class Lut3D

Inheritance

object

Lut3D

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Export a grade for DaVinci Resolve or Premiere, then load a .cube file and apply it at 70%.
ColorFilter grade = ColorFilter.Curves(ToneCurve.FromPoints([(0, 0), (0.25f, 0.2f), (0.75f, 0.82f), (1, 1)]))
    .Then(ColorFilter.Saturation(1.1f));
CubeFile.Write("my-grade.cube", grade.ToLut3D(size: 33), title: "My grade");

Lut3D lut = CubeFile.Read("my-grade.cube");
raster.Apply(o => o.ApplyFilter(ColorFilter.Lerp(ColorFilter.Identity, ColorFilter.FromLut(lut), 0.7f)), Ct);

// Tables can also be built from a function, and read at any color.
Lut3D warm = Lut3D.FromFunction(c => new Vector3(c.X, c.Y * 0.97f, c.Z * 0.9f), size: 17);
Vector3 gray = warm.Evaluate(new Vector3(0.5f), LutInterpolation.Tetrahedral);

Remarks

Values are 32-bit floats and may lie outside 0..1; a filter clamps what it reads. Immutable and safe to share between threads.

Properties

DomainMax

Gets the input that maps to the last grid point on each axis (DOMAIN_MAX in a .cube file). Defaults to 1.

public Vector3 DomainMax { get; }

Property Value

Vector3

DomainMin

Gets the input that maps to the first grid point on each axis (DOMAIN_MIN in a .cube file). Defaults to 0.

public Vector3 DomainMin { get; }

Property Value

Vector3

this[int, int, int]

Gets one grid point's output.

public Vector3 this[int red, int green, int blue] { get; }

Parameters

red int

The red index, 0 to Size − 1.

green int

The green index.

blue int

The blue index.

Property Value

Vector3

The output color.

Exceptions

ArgumentOutOfRangeException

An index is out of range.

ShaperSize

Gets the number of entries in the 1D shaper read before the grid, or 0 when there is none.

public int ShaperSize { get; }

Property Value

int

Size

Gets the number of grid points along each axis.

public int Size { get; }

Property Value

int

Methods

Evaluate(Vector3, LutInterpolation)

Returns the table's output for one color.

public Vector3 Evaluate(Vector3 color, LutInterpolation interpolation = LutInterpolation.Tetrahedral)

Parameters

color Vector3

The input; each channel is clamped to the shaper's range, then to the domain.

interpolation LutInterpolation

How to read between grid points. Defaults to Tetrahedral.

Returns

Vector3

The output, unclamped.

Exceptions

ArgumentOutOfRangeException

interpolation is not defined.

FromFunction(Func<Vector3, Vector3>, int)

Creates a table by sampling function at every grid point over 0..1.

public static Lut3D FromFunction(Func<Vector3, Vector3> function, int size = 33)

Parameters

function Func<Vector3, Vector3>

The color function; it is called only here.

size int

The points per axis, from 2 to 256. Defaults to 33.

Returns

Lut3D

The table.

Exceptions

ArgumentNullException

function is null.

ArgumentOutOfRangeException

size is outside 2 to 256.

ArgumentException

The function returned a value that is not finite.

FromHald(Raster)

Reads a Hald CLUT image, as ImageMagick, G'MIC and RawTherapee write them: a level-L image is L³ × L³ pixels holding an L² table, red fastest, row by row. The image's own color profile is ignored, since it is a table rather than a picture.

public static Lut3D FromHald(Raster hald)

Parameters

hald Raster

The image; its first frame is read.

Returns

Lut3D

The table.

Exceptions

ArgumentNullException

hald is null.

ArgumentException

The image is not square with a side that is a cube from 8 to 4096.

FromValues(int, ReadOnlySpan<Vector3>, Vector3?, Vector3?)

Creates a table from its grid values, red varying fastest, then green, then blue.

public static Lut3D FromValues(int size, ReadOnlySpan<Vector3> values, Vector3? domainMin = null, Vector3? domainMax = null)

Parameters

size int

The points per axis, from 2 to 256.

values ReadOnlySpan<Vector3>

Exactly size³ finite colors.

domainMin Vector3?

The input at the first grid point, or null for 0.

domainMax Vector3?

The input at the last grid point, or null for 1; above domainMin on every axis.

Returns

Lut3D

The table.

Exceptions

ArgumentOutOfRangeException

size is outside 2 to 256.

ArgumentException

The value count is wrong, a value is not finite, or the domain is empty.

ToHald(int)

Writes the table as a Hald image of level: (level²)³ grid points in a level³ × level³ 16-bit image, for grading in an editor and loading back with FromHald(Raster).

public Raster<Rgba16> ToHald(int level = 8)

Parameters

level int

The Hald level, from 2 to 16. Defaults to 8 (a 512 × 512 image holding a 64³ table).

Returns

Raster<Rgba16>

The image; the caller disposes it.

Exceptions

ArgumentOutOfRangeException

level is outside 2 to 16.

WithShaper(ReadOnlySpan<Vector3>, float, float)

Returns this table with a 1D shaper read before it, as the first table of a 1D-plus-3D .cube file.

public Lut3D WithShaper(ReadOnlySpan<Vector3> shaper, float inputMin = 0, float inputMax = 1)

Parameters

shaper ReadOnlySpan<Vector3>

From 2 to 65,536 finite RGB entries, the first for inputMin and the last for inputMax.

inputMin float

The input at the shaper's first entry. Defaults to 0.

inputMax float

The input at its last entry, above inputMin. Defaults to 1.

Returns

Lut3D

The table with the shaper, replacing any it had.

Exceptions

ArgumentException

The shaper's length or values are out of range, or the range is empty.