1 Colour - Checker Detection

A Python package implementing various colour checker detection algorithms and related utilities.

It is open source and freely available under the BSD-3-Clause terms.

1.1 Features

The following colour checker detection algorithms are implemented:

• Segmentation

• Machine learning inference via Ultralytics YOLOv8

  • The model is published on HuggingFace, and was trained on a purposely constructed dataset.

  • The model has only been trained on ColorChecker Classic 24 images and will not work with ColorChecker Nano or ColorChecker SG images.

  • Inference is performed by a script licensed under the terms of the GNU Affero General Public License v3.0 as it uses the Ultralytics YOLOv8 API which is incompatible with the BSD-3-Clause.

1.1.1 Examples

Various usage examples are available from the examples directory.

1.2 User Guide

User Guide

The user guide provides an overview of Colour - Checker Detection and explains important concepts and features, details can be found in the API Reference.

Installation Guide

Because of their size, the resources dependencies needed to run the various examples and unit tests are not provided within the Pypi package. They are separately available as Git Submodules when cloning the repository.

Primary Dependencies

Colour - Checker Detection requires various dependencies in order to run:

• python >= 3.8, < 4

• colour-science >= 4.3

• imageio >= 2, < 3

• numpy >= 1.22, < 2

• opencv-python >= 4, < 5

• scipy >= 1.8, < 2

Secondary Dependencies

• ultralytics >= 8, < 9

Pypi

Once the dependencies are satisfied, Colour - Checker Detection can be installed from the Python Package Index by issuing this command in a shell:

pip install --user colour-checker-detection

The tests suite dependencies are installed as follows:

pip install --user 'colour-checker-detection[tests]'

The documentation building dependencies are installed as follows:

pip install --user 'colour-checker-detection[docs]'

The overall development dependencies are installed as follows:

pip install --user 'colour-checker-detection[development]'

Bibliography

[Abe11]

Felix Abecassis. OpenCV - Rotation (Deskewing). http://felix.abecassis.me/2011/10/opencv-rotation-deskewing/, 2011.

[Dal24]

Jacob Dallas. [BUG]: Flipped colour chart. January 2024.

[Olf19]

Alexander Olferuk. How to force approxPolyDP() to return only the best 4 corners? - Opencv 2.4.2. https://stackoverflow.com/a/55339684/931625, March 2019.

[Wal22]

Tim Walter. [ENHANCEMENT] Proposal to allow detection from different perspectives. https://github.com/colour-science/colour-checker-detection/issues/60, 2022.

1.3 API Reference

API Reference

Colour - Checker Detection

Detection

Inference

colour_checker_detection

SETTINGS_INFERENCE_COLORCHECKER_CLASSIC	Settings for the inference of the X-Rite ColorChecker Classic.
SETTINGS_INFERENCE_COLORCHECKER_CLASSIC_MINI	Settings for the inference of the X-Rite ColorChecker Classic Mini.
inferencer_default(image[, cctf_encoding, ...])	Predict the colour checker rectangles in given image using Ultralytics YOLOv8.
detect_colour_checkers_inference(image[, ...])	Detect the colour checkers swatches in given image using inference.

Segmentation

colour_checker_detection

SETTINGS_SEGMENTATION_COLORCHECKER_CLASSIC	Settings for the segmentation of the X-Rite ColorChecker Classic and X-Rite ColorChecker Passport.
SETTINGS_SEGMENTATION_COLORCHECKER_SG	Settings for the segmentation of the X-Rite ColorChecker SG*.
SETTINGS_SEGMENTATION_COLORCHECKER_NANO	Settings for the segmentation of the X-Rite ColorChecker Nano*.
segmenter_default(image[, cctf_encoding, ...])	Detect the colour checker rectangles in given image \(image\) using segmentation.
detect_colour_checkers_segmentation(image[, ...])	Detect the colour checkers swatches in given image using segmentation.

Common Utilities

colour_checker_detection.detection

DTYPE_INT_DEFAULT	alias of int32
DTYPE_FLOAT_DEFAULT	alias of float32
SETTINGS_DETECTION_COLORCHECKER_CLASSIC	Settings for the detection of the X-Rite ColorChecker Classic and X-Rite ColorChecker Passport.
SETTINGS_DETECTION_COLORCHECKER_SG	Settings for the detection of the X-Rite ColorChecker SG*.
SETTINGS_CONTOUR_DETECTION_DEFAULT	Settings for contour detection.
as_int32_array(a)	Convert given variable \(a\) to numpy.ndarray using np.int32 numpy.dtype.
as_float32_array(a)	Convert given variable \(a\) to numpy.ndarray using np.float32 numpy.dtype.
swatch_masks(width, height, swatches_h, ...)	Return swatch masks for given image width and height and swatches count.
swatch_colours(image, masks)	Extract the swatch colours from given image using given masks.
reformat_image(image, target_width[, ...])	Reformat given image so that it is horizontal and resizes it to given target width.
transform_image(image[, translation, ...])	Transform given image using given translation, rotation and scale values.
detect_contours(image[, additional_data])	Detect the contours of given image using given settings.
is_square(contour[, tolerance])	Return if given contour is a square.
contour_centroid(contour)	Return the centroid of given contour.
scale_contour(contour, factor)	Scale given contour by given scale factor.
approximate_contour(contour[, points, ...])	Approximate given contour to have given number of points.
quadrilateralise_contours(contours)	Convert given to quadrilaterals.
remove_stacked_contours(contours[, ...])	Remove amd filter out the stacked contours from given contours keeping either the smallest or the largest ones.
DataDetectionColourChecker(swatch_colours, ...)	Colour checker swatches data used for plotting, debugging and further analysis.
sample_colour_checker(image, quadrilateral, ...)	Sample the colour checker using the given source quadrilateral, i.e. detected colour checker in the image, and the given target rectangle.

Indices and tables

• Index

• Search Page

1.4 Code of Conduct

The Code of Conduct, adapted from the Contributor Covenant 1.4, is available on the Code of Conduct page.

1.5 Contact & Social

The Colour Developers can be reached via different means:

• Email

• Facebook

• Github Discussions

• Gitter

• Twitter

1.6 About

Colour - Checker Detection by Colour Developers

Copyright 2018 Colour Developers – colour-developers@colour-science.org

This software is released under terms of BSD-3-Clause: https://opensource.org/licenses/BSD-3-Clause

colour-science/colour-checker-detection