colour_checker_detection.extractor_templated#

colour_checker_detection.extractor_templated(image: ArrayLike, segmentation_data: DataSegmentationColourCheckers, samples: int = 32, cctf_decoding: Callable = eotf_sRGB, apply_cctf_decoding: bool = False, additional_data: Literal[True] = True, **kwargs: Any) → tuple[DataDetectionColourChecker, ...][source]#

colour_checker_detection.extractor_templated(image: ArrayLike, segmentation_data: DataSegmentationColourCheckers, samples: int = 32, cctf_decoding: Callable = eotf_sRGB, apply_cctf_decoding: bool = False, *, additional_data: Literal[False], **kwargs: Any) → tuple[NDArrayFloat, ...]

colour_checker_detection.extractor_templated(image: ArrayLike, segmentation_data: DataSegmentationColourCheckers, samples: int, cctf_decoding: Callable, apply_cctf_decoding: bool, additional_data: Literal[False], **kwargs: Any) → tuple[NDArrayFloat, ...]

Extract colour swatches using template-based perspective transformation.

This function takes segmentation data and extracts colors using template matching with perspective transformation. This extractor should be used when the colour checker is not facing the camera straight.

The process is as follows:

The swatches are converted to centroids and used to filter clusters to only keep the ones that contain the expected number of swatches. Moreover, the centroids are grouped by the clusters.
The centroids are ordered within their group to enforce the same ordering as the template, which is important to extract the transformation, since OpenCV’s perspective transform is not invariant to the ordering of the points.
The best transformation is determined by finding the transformation that minimizes the average distance of the warped points from the reference template points.
The image is warped using the determined transformation.
The colours are extracted from the warped image using a sampling window around the centroids.
The colours are corrected if the chromatic swatches have a lower standard deviation than the achromatic swatches.

Parameters:

image (ArrayLike) – Image to extract the colour checker swatches and colours from.
segmentation_data (DataSegmentationColourCheckers) – Segmentation colour checkers data from the segmenter.
samples (int) – Sample count to use to average (mean) the swatches colours. The effective sample count is \(samples^2\).
cctf_decoding (Callable) – Decoding colour component transfer function / opto-electronic transfer function used when converting the image from 8-bit to float.
apply_cctf_decoding (bool) – Apply the decoding colour component transfer function / opto-electronic transfer function.
additional_data (bool) – Whether to output additional data.
template – Template defining the swatches structure, which is exploited to find the best correspondences between template and detected swatches, which yield the optimal transformation. If not provided, defaults to built-in ColorChecker Classic template.
residual_threshold – Maximum allowed residual between detected and template colours. Higher values are more permissive. Default is 0.3 (30%).
adaptive_threshold_kwargs – Keyword arguments for cv2.adaptiveThreshold() definition.
aspect_ratio – Colour checker aspect ratio, e.g. 1.5.
aspect_ratio_minimum – Minimum colour checker aspect ratio for detection: projective geometry might reduce the colour checker aspect ratio.
aspect_ratio_maximum – Maximum colour checker aspect ratio for detection: projective geometry might increase the colour checker aspect ratio.
bilateral_filter_iterations – Number of iterations to use for bilateral filtering.
bilateral_filter_kwargs – Keyword arguments for cv2.bilateralFilter() definition.
contour_approximation_factor – Approximation factor for the Douglas-Peucker polygon approximation algorithm. It controls how aggressively contours are simplified, expressed as a fraction of the contour’s perimeter. Lower values (e.g., 0.01) preserve more detail, higher values (e.g., 0.1) simplify more aggressively.
convolution_iterations – Number of iterations to use for the erosion / dilation process.
convolution_kernel – Convolution kernel to use for the erosion / dilation process.
dbscan_eps – DBSCAN epsilon parameter defining the maximum distance between two samples for them to be considered in the same neighborhood. Lower values create tighter clusters. Default is 0.5.
dbscan_min_samples – DBSCAN minimum samples parameter defining the number of samples in a neighborhood for a point to be considered a core point. Default is 5.
transformation_cost_threshold – Cost threshold for early termination of transformation search. If a transformation achieves an average distance below this threshold, the search stops immediately. Lower values require better matches. Default is 10.0.
interpolation_method – Interpolation method used when resizing the images, cv2.INTER_CUBIC and cv2.INTER_LINEAR methods are recommended.
reference_values – Reference values for the colour checker of interest.
swatch_contour_scale – As the image is filtered, the swatches area will tend to shrink, the generated contours can thus be scaled.
swatch_minimum_area_factor – Swatch minimum area factor \(f\) with the minimum area \(m_a\) expressed as follows: \(m_a = image_w * image_h / s_c / f\) where \(image_w\), \(image_h\) and \(s_c\) are respectively the image width, height and the swatches count.
swatches – Colour checker swatches total count.
swatches_achromatic_slice – A slice instance defining achromatic swatches used to detect if the colour checker is upside down.
swatches_chromatic_slice – A slice instance defining chromatic swatches used to detect if the colour checker is upside down.
swatches_count_maximum – Maximum swatches count to be considered for the detection.
swatches_count_minimum – Minimum swatches count to be considered for the detection.
swatches_horizontal – Colour checker swatches horizontal columns count.
swatches_vertical – Colour checker swatches vertical row count.
transform – Transform to apply to the colour checker image post-detection.
working_width – Width the input image is resized to for detection.
working_height – Height the input image is resized to for detection.
kwargs (Any)

Returns:

Tuple of DataDetectionColourChecker class instances or colour checkers swatches.

Return type:

class`tuple`

Examples

>>> import os
>>> from colour import read_image
>>> from colour_checker_detection import (
...     ROOT_RESOURCES_TESTS,
...     segmenter_templated,
...     extractor_templated,
... )
>>> path = os.path.join(
...     ROOT_RESOURCES_TESTS,
...     "colour_checker_detection",
...     "detection",
...     "IMG_1967.png",
... )
>>> image = read_image(path)
>>> segmentation_data = segmenter_templated(image, additional_data=True)
>>> extractor_templated(image, segmentation_data)
(array([[ 0.36081576,  0.22396202,  0.11733589],
       [ 0.6274815 ,  0.39514375,  0.24308297],
       [ 0.33063054,  0.3158751 ,  0.28996205],
       [ 0.30372787,  0.2742474 ,  0.10494538],
       [ 0.41764253,  0.31940183,  0.30804706],
       [ 0.34960267,  0.44142178,  0.29417506],
       [ 0.682801  ,  0.3538923 ,  0.07184852],
       [ 0.27251157,  0.2532009 ,  0.33145225],
       [ 0.62005484,  0.2703342 ,  0.18676178],
       [ 0.3079272 ,  0.1803046 ,  0.19187638],
       [ 0.48746303,  0.4604792 ,  0.03282085],
       [ 0.6541456 ,  0.40173233,  0.01583917],
       [ 0.19250122,  0.185604  ,  0.2739023 ],
       [ 0.28076768,  0.38508102,  0.12207687],
       [ 0.5527626 ,  0.21404609,  0.1256289 ],
       [ 0.7217179 ,  0.51569265,  0.00520882],
       [ 0.57813776,  0.25853688,  0.26927036],
       [ 0.17615536,  0.31684747,  0.29624644],
       [ 0.74493927,  0.6126149 ,  0.44073734],
       [ 0.6314545 ,  0.5187937 ,  0.3728771 ],
       [ 0.5143494 ,  0.42190555,  0.29967216],
       [ 0.37282884,  0.30393514,  0.21030639],
       [ 0.2645776 ,  0.21623953,  0.1437975 ],
       [ 0.16090113,  0.13422866,  0.081468  ]], dtype=float32),)

colour_checker_detection.extractor_templated#

This Page