Meziantou.FrameworkColorMatrix Class
An immutable matrix that gives each pixel a new color from its own one: brighter, grayer, tinted, inverted, more transparent. It is applied to an image by ImageProcessingExtensions.ApplyColorMatrix, and to a drawing by DrawingCanvas.Filter.
public sealed class ColorMatrixRemarks
The matrix has four rows, for the red, the green, the blue and the alpha of the result, and five columns, for the red, the green, the blue and the alpha of the pixel and for a constant: with the samples as fractions of one and straight alpha, R' = m00 R + m01 G + m02 B + m03 A + m04, and so on for each row. This is the matrix of the feColorMatrix filter of SVG, and the ready-made matrices are those of the filter functions of CSS (grayscale(), sepia(), saturate(), hue-rotate(), invert(), opacity(), brightness(), contrast()), from "Filter Effects Module Level 1" of the W3C.
Arithmetic. The matrix is applied to the stored sample values of the pixel, at their precision: with M the largest sample value, a sample of the result is floor(m0 R + m1 G + m2 B + m3 A + m4 M + 1/2 + 2^-20), the terms added in that order in double precision, kept between 0 and M. Only multiplications and additions are involved: the result does not depend on the platform. A pixel format without alpha has an alpha of M and gets the color of the result over black (each color multiplied by the alpha of the result); a grayscale format has its gray level as red, green and blue, and gets the Rec. 709 luma of the result.
A color matrix is thread-safe: create it once and use it as many times as needed. ColorMatrix.Then makes one matrix of two, which is applied once per pixel instead of twice, without the rounding in between.
Constructors
| Name | Description |
|---|---|
| ColorMatrix(ReadOnlySpan<double>) | Initializes a new instance of the ColorMatrix class. |
ColorMatrix(ReadOnlySpan<double>)
ColorMatrix.csInitializes a new instance of the ColorMatrix class.
public ColorMatrix(ReadOnlySpan<double> values)Parameters
valuesReadOnlySpan<double>- The twenty coefficients, row by row: the row of the red of the result first, then green, blue and alpha; in each row, the coefficients of the red, the green, the blue and the alpha of the pixel, then the constant, as a fraction of the largest sample value. They are copied.
Exceptions
ArgumentExceptionvaluesdoes not hold exactly twenty values, or a value is not finite.
Properties
| Name | Description |
|---|---|
| BlackWhite | Gets the matrix that makes a high-contrast black and white image: every color becomes 1.5 (R + G + B) - 1, so that most pixels are black or white and only the middle tones stay gray. It is the BlackWhite matrix of ImageProcessor (James Jackson-South, Apache License 2.0). For gray levels that keep the tones, see ColorMatrix.CreateGrayscale; for pixels that are only black or white, see ImageProcessingExtensions.Threshold. |
| Identity | Gets the matrix that changes nothing. |
| IsIdentity | Gets a value indicating whether the matrix changes nothing: every coefficient is the one of ColorMatrix.Identity. |
| Kodachrome | Gets the matrix that gives the colors the warm contrast of a Kodachrome slide: the kodachrome() preset of the ColorMatrixFilter of PixiJS 8.6.6 (MIT license), whose constants are published on the 0 to 255 scale and are divided by 255 here, as PixiJS does. |
| Lomograph | Gets the matrix that gives the colors the strong, shifted tones of a Lomography camera: each color scaled and moved on its own, R' = 1.5 R - 0.1, G' = 1.45 G + 0.05, B' = 1.09 B - 0.08. It is the Lomograph matrix of ImageProcessor (James Jackson-South, Apache License 2.0). |
| LuminanceToAlpha | Gets the matrix that makes the luminance of the color the alpha of a black: luminanceToAlpha of the feColorMatrix filter of SVG, A' = 0.2125 R + 0.7154 G + 0.0721 B, the colors zero. It turns an image into a mask: white is opaque, black transparent. |
| Polaroid | Gets the matrix that gives the colors the cool, saturated look of an instant photograph: the polaroid() preset of the ColorMatrixFilter of PixiJS 8.6.6 (MIT license), written as published. |
BlackWhite
ColorMatrix.csGets the matrix that makes a high-contrast black and white image: every color becomes 1.5 (R + G + B) - 1, so that most pixels are black or white and only the middle tones stay gray. It is the BlackWhite matrix of ImageProcessor (James Jackson-South, Apache License 2.0). For gray levels that keep the tones, see ColorMatrix.CreateGrayscale; for pixels that are only black or white, see ImageProcessingExtensions.Threshold.
public static ColorMatrix BlackWhite { get; }Property value
Identity
ColorMatrix.csIsIdentity
ColorMatrix.csGets a value indicating whether the matrix changes nothing: every coefficient is the one of ColorMatrix.Identity.
public bool IsIdentity { get; }Property value
Kodachrome
ColorMatrix.csGets the matrix that gives the colors the warm contrast of a Kodachrome slide: the kodachrome() preset of the ColorMatrixFilter of PixiJS 8.6.6 (MIT license), whose constants are published on the 0 to 255 scale and are divided by 255 here, as PixiJS does.
public static ColorMatrix Kodachrome { get; }Property value
Lomograph
ColorMatrix.csGets the matrix that gives the colors the strong, shifted tones of a Lomography camera: each color scaled and moved on its own, R' = 1.5 R - 0.1, G' = 1.45 G + 0.05, B' = 1.09 B - 0.08. It is the Lomograph matrix of ImageProcessor (James Jackson-South, Apache License 2.0).
public static ColorMatrix Lomograph { get; }LuminanceToAlpha
ColorMatrix.csGets the matrix that makes the luminance of the color the alpha of a black: luminanceToAlpha of the feColorMatrix filter of SVG, A' = 0.2125 R + 0.7154 G + 0.0721 B, the colors zero. It turns an image into a mask: white is opaque, black transparent.
public static ColorMatrix LuminanceToAlpha { get; }Property value
Polaroid
ColorMatrix.csGets the matrix that gives the colors the cool, saturated look of an instant photograph: the polaroid() preset of the ColorMatrixFilter of PixiJS 8.6.6 (MIT license), written as published.
public static ColorMatrix Polaroid { get; }Property value
Indexers
| Name | Description |
|---|---|
| this[int, int] | Gets a coefficient. |
this[int, int]
ColorMatrix.csGets a coefficient.
Parameters
rowint- The row: 0 for the red of the result, 1 for its green, 2 for its blue, 3 for its alpha.
columnint- The column: 0 to 3 for the red, the green, the blue and the alpha of the pixel, 4 for the constant.
Property value
Exceptions
ArgumentOutOfRangeExceptionroworcolumnis out of range.
Methods
| Name | Description |
|---|---|
| CreateBrightness(double) | Creates the matrix that multiplies the colors by a factor: brightness() in CSS. |
| CreateColorBlindness(ColorBlindnessType) | Creates the matrix that shows the colors as a person with a color vision deficiency sees them: a dichromacy, or an anomalous trichromacy of severity 0.5. |
| CreateColorBlindness(ColorBlindnessType, double) | Creates the matrix that shows the colors as a person with an anomalous trichromacy of a given severity sees them. |
| CreateContrast(double) | Creates the matrix that moves the colors away from the middle gray, or toward it: contrast() in CSS. |
| CreateDuotone(Rgba64, Rgba64) | Creates the matrix that draws an image with two inks: each pixel gets the color between dark and light that its gray level says. |
| CreateGrayscale(double) | Creates the matrix that replaces the colors by their gray level, entirely or in part: grayscale() in CSS. |
| CreateHueRotation(double) | Creates the matrix that turns the hues around the color wheel: hue-rotate() in CSS. |
| CreateInvert(double) | Creates the matrix that inverts the colors, entirely or in part: invert() in CSS. |
| CreateLightness(double) | Creates the matrix that adds a constant to the colors, lighter or darker: c' = c + amount. |
| CreateOpacity(double) | Creates the matrix that multiplies the alpha by a factor: opacity() in CSS. |
| CreateSaturation(double) | Creates the matrix that makes the colors more or less vivid: saturate() in CSS. |
| CreateSepia(double) | Creates the matrix that gives the colors the brown tones of an old photograph, entirely or in part: sepia() in CSS. |
| CreateTint(Rgba64) | Creates the matrix that gives every pixel one color and keeps its alpha: an icon or a glyph that was drawn in one color is drawn in another one. |
| Then(ColorMatrix) | Creates the matrix that applies this one, then another one, to the color this one gives. |
CreateBrightness(double)
ColorMatrix.csCreates the matrix that multiplies the colors by a factor: brightness() in CSS.
public static ColorMatrix CreateBrightness(double amount)Parameters
amountdouble- The factor: 1 changes nothing, 0 gives black, more than 1 brightens.
Returns
ColorMatrix The matrix.
Exceptions
ArgumentOutOfRangeExceptionamountis negative or not a finite number.
CreateColorBlindness overloads
CreateColorBlindness(ColorBlindnessType)
ColorMatrix.csCreates the matrix that shows the colors as a person with a color vision deficiency sees them: a dichromacy, or an anomalous trichromacy of severity 0.5.
public static ColorMatrix CreateColorBlindness(ColorBlindnessType type)Parameters
typeColorBlindnessType- The deficiency.
Returns
ColorMatrix The matrix.
Exceptions
ArgumentOutOfRangeExceptiontypeis not a defined value.
Remarks
See ColorMatrix.CreateColorBlindness for the model and its coefficients.
CreateColorBlindness(ColorBlindnessType, double)
ColorMatrix.csCreates the matrix that shows the colors as a person with an anomalous trichromacy of a given severity sees them.
public static ColorMatrix CreateColorBlindness(ColorBlindnessType type, double severity)Parameters
typeColorBlindnessType- The deficiency:
ColorBlindnessType.Protanomaly,ColorBlindnessType.DeuteranomalyorColorBlindnessType.Tritanomaly. severitydouble- How far the sensitivity of the cones is shifted: from 0 (normal vision) to 1 (the dichromacy).
Returns
ColorMatrix The matrix.
Exceptions
ArgumentOutOfRangeExceptiontypeis not a defined value, orseverityis not between 0 and 1.ArgumentExceptiontypeis a dichromacy, which has no severity: useColorMatrix.CreateColorBlindness.
Remarks
The coefficients are those of Table 1 of G. M. Machado, M. M. Oliveira and L. A. F. Fernandes, "A Physiologically-based Model for Simulation of Color Vision Deficiency", IEEE Transactions on Visualization and Computer Graphics 15(6), 2009, pp. 1291-1298, published for the severities 0, 0.1, 0.2 ... 1: a severity between two of them is interpolated linearly between their matrices, as the authors recommend. A severity of 0 changes nothing, and a severity of 1 is the dichromacy (ColorBlindnessType.Protanopia for ColorBlindnessType.Protanomaly, and so on). The alpha is kept.
The model works on linear RGB. Like every matrix, this one is applied to the stored sample values: it is exact on a linear-light image (an RgbaFloat image converted from the sRGB colors), and an approximation on sRGB-encoded samples, which is how most simulators apply it.
CreateContrast(double)
ColorMatrix.csCreates the matrix that moves the colors away from the middle gray, or toward it: contrast() in CSS.
public static ColorMatrix CreateContrast(double amount)Parameters
amountdouble- The factor: 1 changes nothing, 0 gives the middle gray, more than 1 increases the contrast.
Returns
ColorMatrix The matrix: each color c becomes amount c + (1 - amount) / 2.
Exceptions
ArgumentOutOfRangeExceptionamountis negative or not a finite number.
CreateDuotone(Rgba64, Rgba64)
ColorMatrix.csCreates the matrix that draws an image with two inks: each pixel gets the color between dark and light that its gray level says.
public static ColorMatrix CreateDuotone(Rgba64 dark, Rgba64 light)Parameters
darkRgba64- The color of black pixels. An
Rgba32converts implicitly. lightRgba64- The color of white pixels. An
Rgba32converts implicitly.
Returns
ColorMatrix The matrix.
Remarks
The gray level is the Rec. 709 luma of the stored sample values: black becomes dark, white becomes light, and a gray the color that far between them, each color sample apart. The alpha of the pixels is kept, and the alpha of the two colors is not used.
CreateGrayscale(double)
ColorMatrix.csCreates the matrix that replaces the colors by their gray level, entirely or in part: grayscale() in CSS.
public static ColorMatrix CreateGrayscale(double amount = 1d)Parameters
amountdouble- How much of the color is replaced: 1 (the default) for gray levels, 0 to change nothing.
Returns
ColorMatrix The matrix.
Exceptions
ArgumentOutOfRangeExceptionamountis not between 0 and 1.
Remarks
With an amount of 1, the gray level is the Rec. 709 luma of the stored sample values, with the rounding of ImageProcessingExtensions.Grayscale: both give the same pixels.
CreateHueRotation(double)
ColorMatrix.csCreates the matrix that turns the hues around the color wheel: hue-rotate() in CSS.
public static ColorMatrix CreateHueRotation(double degrees)Parameters
degreesdouble- The angle, in degrees: 180 gives each color its opposite hue.
Returns
ColorMatrix The matrix.
Exceptions
ArgumentExceptiondegreesis not a finite number.
Remarks
The sine and the cosine of the angle do not come from the platform: the matrix is the same everywhere, and a multiple of a full turn gives ColorMatrix.Identity.
CreateInvert(double)
ColorMatrix.csCreates the matrix that inverts the colors, entirely or in part: invert() in CSS.
public static ColorMatrix CreateInvert(double amount = 1d)Parameters
amountdouble- How far each color goes to its opposite: 1 (the default) for the negative, 0.5 for the middle gray, 0 to change nothing.
Returns
ColorMatrix The matrix: each color c becomes (1 - 2 amount) c + amount. The alpha is kept.
Exceptions
ArgumentOutOfRangeExceptionamountis not between 0 and 1.
CreateLightness(double)
ColorMatrix.csCreates the matrix that adds a constant to the colors, lighter or darker: c' = c + amount.
public static ColorMatrix CreateLightness(double amount)Parameters
amountdouble- The fraction of the range added to each color: from -1 (black) to 1 (white), 0 to change nothing.
Returns
ColorMatrix The matrix.
Exceptions
ArgumentOutOfRangeExceptionamountis not between -1 and 1.
Remarks
Unlike ColorMatrix.CreateBrightness, which multiplies the colors and keeps black black, the lightness moves every color by the same amount: the linear transfer function of the feComponentTransfer filter of SVG with a slope of 1 and an intercept of amount. The alpha is kept.
CreateOpacity(double)
ColorMatrix.csCreates the matrix that multiplies the alpha by a factor: opacity() in CSS.
public static ColorMatrix CreateOpacity(double amount)Parameters
amountdouble- The factor: 1 changes nothing, 0 makes every pixel transparent.
Returns
ColorMatrix The matrix.
Exceptions
ArgumentOutOfRangeExceptionamountis not between 0 and 1.
CreateSaturation(double)
ColorMatrix.csCreates the matrix that makes the colors more or less vivid: saturate() in CSS.
public static ColorMatrix CreateSaturation(double amount)Parameters
amountdouble- The factor: 1 changes nothing, 0 leaves no color, more than 1 makes the colors more vivid.
Returns
ColorMatrix The matrix.
Exceptions
ArgumentOutOfRangeExceptionamountis negative or not a finite number.
CreateSepia(double)
ColorMatrix.csCreates the matrix that gives the colors the brown tones of an old photograph, entirely or in part: sepia() in CSS.
public static ColorMatrix CreateSepia(double amount = 1d)Parameters
amountdouble- How much of the color is replaced: 1 (the default) for sepia tones, 0 to change nothing.
Returns
ColorMatrix The matrix.
Exceptions
ArgumentOutOfRangeExceptionamountis not between 0 and 1.
CreateTint(Rgba64)
ColorMatrix.csCreates the matrix that gives every pixel one color and keeps its alpha: an icon or a glyph that was drawn in one color is drawn in another one.
public static ColorMatrix CreateTint(Rgba64 color)Parameters
colorRgba64- The color, with straight alpha: its alpha multiplies the alpha of the pixels. An
Rgba32converts implicitly.
Returns
ColorMatrix The matrix.
Then(ColorMatrix)
ColorMatrix.csCreates the matrix that applies this one, then another one, to the color this one gives.
public ColorMatrix Then(ColorMatrix next)Parameters
nextColorMatrix- The matrix that is applied second.
Returns
ColorMatrix The combined matrix.
Exceptions
ArgumentNullExceptionnextisnull.ArgumentException- A coefficient of the result is not a finite number.
Remarks
The result is the product of the two matrices: applying it is applying both without rounding or clamping the color in between. A color that the first matrix takes out of range is therefore not clamped before the second one, as it is when two matrices are applied one after the other.