Skip to content

07 Dictionaries

Jump to bottom
tei187 edited this page Apr 23, 2024 · 2 revisions

Standard dictionaries

This package comes with defined standard dictionaries for:

  • chromaticity adaptation transformation matrices (class \tei187\ColorTools\Dictionaries\CAT\Matrices),
  • deltaE calculations (class \tei187\ColorTools\Dictionaries\DeltaE\Dictionary),
  • standard illuminants,
  • standard RGB primaries (class \tei187\ColorTools\Dictionaries\RGBPrimaries\Standard\Dictionary).

CAT matrices

tei187\ColorTools\Dictionaries\CAT\Matrices

Description

Chromaticity adaptation transformation matrices (CAT) are used to convert between different color spaces.

Standard dictionary includes:

  • Bradford (default),
  • CIECAT02,
  • CMCCAT2000,
  • HuntPointerEsteves,
  • Sharp,
  • Von_Kries,
  • XYZ_Scaling.

There are no additional methods handling these, they only exist as constant parameters, called like this:

use tei187\ColorTools\Dictionaries\CAT\Matrices;

var_dump(Matrices::Bradford);
/*
array(3) {
  [0]=>
  array(3) {
    [0]=>
    float(0.8951)
    [1]=>
    float(0.2664)
    [2]=>
    float(-0.1614)
  }
  [1]=>
  array(3) {
    [0]=>
    float(-0.7502)
    [1]=>
    float(1.7135)
    [2]=>
    float(0.0367)
  }
  [2]=>
  array(3) {
    [0]=>
    float(0.0389)
    [1]=>
    float(-0.0685)
    [2]=>
    float(1.0296)
  }
*/

DeltaE dictionary

tei187\ColorTools\Dictionaries\DeltaE\Dictionary

DeltaE dictionary is only used for methods that require deltaE calculations. It matches the passed names of the deltaE functions with their respective equations. Nothing more to see here, unless you want to check out X06 DeltaE - used-equations for a lot of unfathomable math equations.

Standard illuminants dictionary

tei187\ColorTools\Dicitionaries\Illuminants\Standard\Dictionary

Description

Standard illuminants are theoretical light sources with precisely defined spectral power distributions that are used as reference illuminants in colorimetry calculations. They represent different types of illumination conditions, such as daylight, incandescent light, or fluorescent light.

Proper use of standard illuminants is very important in colorimetry, due to providing a standardized reference for colorimetric measuring and comparing colors under different lighting conditions. Their use is also advised in the field of computer graphics, where they are used as reference illuminants for rendering.

Some common standard illuminants include:

  • A illuminant, representing a tungsten incandescent light source with a color temperature of approximately 2856K.
  • D-series illuminants, representing different phases of daylight, with D65 being the most commonly used to represent average daylight.
  • E illuminant, representing equal-energy illumination, where all wavelengths in the visible spectrum have equal radiant power.
  • F-series illuminants, representing different types of fluorescent light sources.
  • LED-series illuminants, representing different types of LED light sources, with varying correlated color temperatures and spectral power distributions.

Usage

Standard illuminants are handled by Dictionary class of tei187\ColorTools\Dictionaries\Illuminants\Standard namespace, based on values described in WhitePoint2, WhitePoint10, Tristimulus2, Tristimulus10 constants of the same namespace, where suffix 2 and 10 describe the standard observer angle degrees. For specific information refer to X03-Standard-Illuminants.md.

For user convenience, Dictionary class provides a static method getIlluminant() to retrieve illuminant by its name and standard observer angle.

use tei187\ColorTools\Dictionaries\Illuminants\Standard\Dictionary;

var_dump(Dictionary::getIlluminant('A', 2));

...will produce:

object(tei187\ColorTools\Illuminants\Illuminant)#1 (4) {
  ["angle":protected] => int(2)
  ["name":protected] => string(1) "A"
  ["whitepoint":protected]=> array(2) {
    [0] => float(0.44757)
    [1] => float(0.40745)
  }
  ["tristimulus":protected]=> array(3) {
    ["X" ]=> float(1.098466069456375)
    ["Y"] => int(1)
    ["Z"] => float(0.3558228003436005)
  }
}

Customization

At some point, it may be useful for you to define your own dictionary of in-house standard illuminants. To do this, you can create a class that extends tei187\ColorTools\Abstracts\IlluminantDictionary abstract class, which implements tei187\ColorTools\Interfaces\IlluminantDictionary interface.

Within, you have to define 3 constant parameters.

  • INDEX, which lists the names of custom-defined illuminants,
  • ANGLES, which holds an array with all observer angles used by this dictionary,
  • WHITEPOINT, which holds a partial namespace for a class that holds whitepoint constants WITHOUT the suffix defining the observer angle. It is done so to somewhat dynamically find the correct dictionary of whitepoints which you can customize and use with your new dictionary of illuminants.

Apart of that, you also have to define the class for white point / (x,y) chromaticity coordinates for each of the angles. Example below:

  • new dictionary:
namespace my\new\illuminant\dictionary;

class NewDictionary extends \tei187\ColorTools\Abstracts\IlluminantDictionary {
    const INDEX      = [ 'MORNING', 'AFTERNOON', 'EVENING' ];
    const ANGLES     = [ 1, 7 ];
    const WHITEPOINT = '\\my\\new\\illuminant\\dictionary\\WhitePoint';
}
  • new white point reference for 1° observer angle. Notice how the NewDictionary::WHITEPOINT if the prefix for the class name with namespace, and the suffix is the observer angle.
namespace my\new\illuminant\dictionary;

class WhitePoint1 {
    const MORNING =   [ 0.37242, 0.37743 ];
    const AFTERNOON = [ 0.33242, 0.34743 ];
    const EVENING =   [ 0.29902, 0.31485 ];
}
  • new white point reference for 7° observer angle. Class name follows the same logic as above - prefix from dictionary constant and suffix for observer angle.
namespace my\new\illuminant\dictionary;

class WhitePoint7 {
    // (...)
}

RGB primaries dictionary

tei187\ColorTools\Dictionaries\RGBPrimaries\Standard\Dictionary

Description

RGB primaries refer to the specific red, green, and blue colors that are used as the primary colors in an RGB color space or color model. These primaries define the gamut (range of colors) that can be represented within that particular RGB color space.

In an RGB color space, any color is represented as a combination of these three primary colors, with each primary having a specific chromaticity coordinate (x, y) in the CIE 1931 xy chromaticity diagram. The chromaticity coordinates of the RGB primaries, along with the white point (reference white) and gamma correction, define the characteristics of a specific RGB color space.

Some common RGB primaries include:

  • sRGB primaries: These are the primaries used in the sRGB color space, which is the default color space for many digital imaging devices and the web.
  • Adobe RGB primaries: These primaries define a wider color gamut than sRGB, making them suitable for professional photography and printing applications.

Understanding RGB primaries is crucial for accurate color management and conversion between different color spaces, as well as for ensuring consistent color reproduction across various devices and applications.

Usage

Most of the usage of this dictionary is handled by RGB color model. However, you can also use it directly, by retrieving the RGB primaries by their name. If the name exists in the index, the class wil return an instance based on tei187\ColorTools\Interfaces\RGBPrimaries interface and tei187\ColorTools\Abstracts\RGBPrimaries abstract class, corresponding to the passed name.

To load specific primaries, you can use the getPrimaries() method, like this:

use tei187\ColorTools\Dictionaries\RGBPrimaries\Standard\Dictionary;

$primaries = Dictionary::getPrimaries('sRGB');

Each of these RGB primaries classes have defined constants:

  • ::NAME, for name of the primaries,
  • ::XYY for xyY chromaticity coordinates of the primaries,
  • ::ILLUMINANT for the name of standard illuminant used,
  • ::GAMMA.

Notice!

This whole dictionary as well as full RGB conversion functionality is still a work in progress. Even though the supported RGB primaries are quite common, there are still some that are not yet supported. That being said, entire structure of how RGB primaries are being interacted with is due to be reworked. For the time being, this dictionary does not allow customization or abstraction, however it is planned in the future.

Clone this wiki locally