Back to FabImage Library website

You are here: Start » Function Reference » Image » Image Metrics » ColorDistanceImage


Header: FIL.h
Namespace: fil
Module: FoundationPro

Compares each pixel with the specified color using chromatic and non-chromatic information.

Applications: Color analysis insensitive to changes of illumination.


void fil::ColorDistanceImage
	const fil::Image& inImage,
	ftl::Optional<const fil::Region&> inRoi,
	const fil::Pixel& inRgbColor,
	float inChromaAmount,
	fil::Image& outValueImage


Name Type Range Default Description
Input value inImage const Image& Unsigned color image used in comparison
Input value inRoi Optional<const Region&> NIL Range of pixels to be processed
Input value inRgbColor const Pixel& Color to compare the image to
Input value inChromaAmount float 0.0 - 1.0 0.7f Proportion of chromatic information in distance computation
Output value outValueImage Image& Unsigned image of distances


For input inImage only pixel formats are supported: 1⨯uint8, 2⨯uint8, 3⨯uint8, 4⨯uint8.

Read more about pixel formats in Image documentation.


The operation computes the distance between each pixel of inImage and a specified color, presenting result as a monochromatic image. Input image should be in RGB color space.

The distance between pixels is computed using two measures:

  • Value distance - the difference between average channel values
  • Chromatic distance - euclidean distance between pixels normalized to the same value level

The resulting distance is computed as a weighted average of these two values, parameter inChromaAmount ( 0.0 - 1.0 ) being the weight of the chromatic distance, and 1 - inChromaAmount being the weight of the value distance.


ColorDistanceImage run with inRgbColor = , inChromaAmount = 0.8

Hardware Acceleration

This operation supports automatic parallelization for multicore and multiprocessor systems.


List of possible exceptions:

Error type Description
DomainError Invalid image Depth in ColorDistanceImage.
DomainError Not supported inImage pixel format in ColorDistanceImage. Supported formats: 1xUInt8, 2xUInt8, 3xUInt8, 4xUInt8.
RuntimeError Each pixel component of inRgbColor must be nonnegative in ColorDistanceImage.

See Also

  • ColorDistance – Compares two pixels using chromatic and non-chromatic information. Assumes RGB color space.
  • ThresholdImage_Color – Transforms each pixel value to maximum or minimum depending on the distance from a given color.