TMSB XML Schema Part 5: Colour and Gradients

article by Ben Lincoln

The colour configuration file is a global configuration file (either for the entire system where TMSB is being executed, or any instance launched by the current user, if that user has created a copy of the file in their personal directory). It is where individual colours (for tinting) and gradients (for gradient-mapped images) are defined. This file must be named Global-Colours.xml.

Note: the FileType value in the metadata section of the file must be Colour Configuration.

Schema

<Name>

A short string to reference the tinting colour by

</Name>

See below

</Format>

<Red>

The red value for the colour (see below)

</Red>

<Green>

The green value for the colour (see below)

</Green>

<Blue>

The blue value for the colour (see below)

</Blue>

</TintingColour>

</TintingColours>

<Name>

A short string to reference the gradient by

</Name>

An integer value between 1 and 65536 (inclusive)

</Position>

See below

</Format>

<Red>

The red value for the colour (see below)

</Red>

<Green>

The green value for the colour (see below)

</Green>

<Blue>

The blue value for the colour (see below)

</Blue>

</GradientColour>

</Gradient>

</Gradients>

</ColourConfig>

Notes

TintingColours is an optional section in which individual colours used to tint greyscale images can be defined. Each colour is contained in a distinct TintingColour block.

Within a TintingColour block:

Name is a short, descriptive name. It is used in other configuration files where the colour defined here is referenced.

Format is one of:

Byte8
UnsignedInteger16
Float32

Red, Green, and Blue specify the corresponding values which define the colour. Permissible values depend on the value of Format:

If Format is Byte8, values should be in the range 0-255 (inclusive).
If Format is UnsignedInteger16, values should be in the range 0-65535 (inclusive).
If Format is Float32, values should be in the range 0.0 - 1.0 (inclusive).

Gradients is an optional section in which colour gradients are defined for use in gradient-mapped false colour images (see Gradient-Mapped False Colour Images). TMSB uses high-fidelity gradient maps in which the palette contains 65536 distinct colours. Each gradient is contained in a distinct Gradient block.

Within a Gradient block:

Name is a short, descriptive name. It is used in other configuration files where the gradient defined here is referenced.

GradientColour occurs once for each user-defined point on the gradient. For example, if a simple gradient based on blue being the minimum value and red being the maximum is defined, two GradientColour blocks would be used. TMSB handles the interpolation of colours in-between the user-defined points. These blocks should be specified in ascending order of their Position values (see below). At least two blocks should always be specified (one with a Position of 1, and the other with a Position of 65536), but any reasonable number of colours may be defined in-between those two positions.

Within a GradientColour block:

Position is the user-defined point along the gradient at which the fixed colour being specified should be placed. This value should be an integer of at least 1, but not more than 65536^[1].

All other values are identical in syntax and usage to the tags of the same name described in the TintingColours section, above.

Example

This configuration defines two colours ("Poppy_Red" and "Limelight"), and two gradients ("Modern_Thermograph_1" and "Vegetation_Index_Triple_Scale_4"). The first gradient is intended for use with common greyscale images in which the only criteria is that the gradient represent the full range of the image (from whatever the minimum happens to be to whatever the maximum happens to be), and is divided into thirds. The second gradient assumes that the greyscale image has been normalized and transformed using a special profile (defined in TMSB XML Schema Part 6: Transformation Profiles) in which floating-point values between 0.0 and 0.25 represent negative numbers, and values between 0.25 and 1.0 represent positive numbers. This not only allows a single image to show a distinction between positive and negative values (as discussed in Gradient-Mapped False Colour Images), but biases the scale so that the positive values (which are generally of more interest) have three times the fidelity of negative values. In this specific case, the gradient uses pink and purple tones for negative values, and "plant-like" colours for positive values, with a "fuzzy area" rendered in grey near the threshold between the two^[2].

<Name>

Poppy_Red

</Name>

UnsignedInteger16

</Format>

<Red>

40349

</Red>

<Green>

514

</Green>

<Blue>

2570

</Blue>

</TintingColour>

<Name>

Limelight

</Name>

UnsignedInteger16

</Format>

<Red>

16705

</Red>

<Green>

65535

</Green>

<Blue>

21331

</Blue>

</TintingColour>

</TintingColours>

<Name>

Modern_Thermograph_1

</Name>

</Position>

UnsignedInteger16

</Format>

<Red>

</Red>

<Green>

39321

</Green>

<Blue>

32896

</Blue>

</GradientColour>

32768

</Position>

UnsignedInteger16

</Format>

<Red>

52428

</Red>

<Green>

</Green>

<Blue>

17733

</Blue>

</GradientColour>

65536

</Position>

UnsignedInteger16

</Format>

<Red>

65535

</Red>

<Green>

47545

</Green>

<Blue>

3341

</Blue>

</GradientColour>

</Gradient>

<Name>

Vegetation_Index_Triple_Scale_4

</Name>

</Position>

UnsignedInteger16

</Format>

<Red>

65535

</Red>

<Green>

</Green>

<Blue>

24672

</Blue>

</GradientColour>

13107

</Position>

UnsignedInteger16

</Format>

<Red>

35466

</Red>

<Green>

</Green>

<Blue>

65535

</Blue>

</GradientColour>

14746

</Position>

UnsignedInteger16

</Format>

<Red>

14649

</Red>

<Green>

14649

</Green>

<Blue>

14649

</Blue>

</GradientColour>

21299

</Position>

UnsignedInteger16

</Format>

<Red>

37265

</Red>

<Green>

37265

</Green>

<Blue>

37265

</Blue>

</GradientColour>

22938

</Position>

UnsignedInteger16

</Format>

<Red>

20046

</Red>

<Green>

13364

</Green>

<Blue>

9509

</Blue>

</GradientColour>

41288

</Position>

UnsignedInteger16

</Format>

<Red>

35466

</Red>

<Green>

35466

</Green>

<Blue>

2570

</Blue>

</GradientColour>

65536

</Position>

UnsignedInteger16

</Format>

<Red>

</Red>

<Green>

65535

</Green>

<Blue>

</Blue>

</GradientColour>

</Gradient>

</Gradients>

</ColourConfig>

Footnotes

DaVinci uses the number 0 as a sort of wildcard, and so this particular value (which is passed mostly unchanged to DaVinci's Shadow) is 1-based instead of 0-based.

This threshold, combined with the biased scaling, is why the "Dark Grey" and "Light Grey" values may appear to be at odd positions along the gradient. 65536 * 0.25 = 16384, which is the absolute threshold. However, 16384 + ((65536 - 16384) * 0.1) = 21299, and 16384 - (16384 * 0.1) ~= 14746, so as you can see, the grey area as defined represents a 10% "zone of uncertainty" on either side of the absolute threshold, scaled correctly for both sides.