Color Correction

Package formerly published as color-correction-asdfghjkl on PyPI. The name has been simplified for better accessibility and professional recognition.

This package is designed to perform color correction on images using the Color Checker Classic 24 Patch card. It provides a robust solution for ensuring accurate color representation in your images.

📦 Installation

Requirements:

• Python 3.11 or higher

pip install color-correction

🏋️‍♀️ How it works

✨ Features

• Multiple Detection Methods:
  • YOLOv8: Fast and accurate ONNX-based detection
  • MCCardDetector: OpenCV's mcc module for robust color checker detection
• Segmentation Support: Detect color checker cards using quadrilateral segmentation regions
• Multiple Correction Models: Choose from polynomial, least_squares, affine_reg, or linear_reg
• GPU Support: Optional GPU acceleration for faster processing
• Comprehensive Analysis: Built-in analyzer for comparing different correction methods and detection approaches

⚡ How to use

from color_correction import ColorCorrection

# Step 1: Define the path to the input image
image_path = "asset/images/cc-19.png"

# Step 2: Load the input image
input_image = cv2.imread(image_path)

# Step 3: Initialize the color correction model with specified parameters
color_corrector = ColorCorrection(
    detection_model="yolov8",  # "yolov8" or "mcc" (MCCardDetector)
    detection_conf_th=0.25,
    correction_model="polynomial", # "least_squares", "affine_reg", "linear_reg"
    degree=3,  # for polynomial correction model
    use_gpu=True,
)

# Step 4: Extract color patches from the input image
# you can set reference patches from another image (image has color checker card)
# or use the default D50
# color_corrector.set_reference_patches(image=None, debug=True)
color_corrector.set_input_patches(image=input_image, debug=True)
color_corrector.fit()
corrected_image = color_corrector.predict(
    input_image=input_image,
    debug=True,
    debug_output_dir="zzz",
)

# Step 5: Evaluate the color correction results
eval_result = color_corrector.calc_color_diff_patches()
print(eval_result)

Sample Evaluation Output

{
    "initial": {
        "min": 2.254003059526461,
        "max": 13.461066402633447,
        "mean": 8.3072755187654,
        "std": 3.123962754767539,
    },
    "corrected": {
        "min": 0.30910031798755183,
        "max": 5.422311999126372,
        "mean": 1.4965478752947827,
        "std": 1.2915738724958112,
    },
    "delta": {
        "min": 1.9449027415389093,
        "max": 8.038754403507074,
        "mean": 6.810727643470616,
        "std": 1.8323888822717276,
    },
}

Sample Output Debug Image

🛡️ Error Handling

The package provides clear, actionable error messages through custom exceptions:

from color_correction import ColorCorrection
from color_correction.exceptions import (
    UnsupportedModelError,
    PatchesNotSetError,
    ModelNotFittedError,
    InvalidImageError,
)

try:
    # Initialize with invalid model
    cc = ColorCorrection(detection_model="invalid_model")
except UnsupportedModelError as e:
    print(f"Error: {e}")
    # Output: "Unsupported model: 'invalid_model'. Supported models are: yolov8, mcc"

try:
    cc = ColorCorrection()
    # Forgot to set input patches
    cc.fit()
except PatchesNotSetError as e:
    print(f"Error: {e}")
    # Output: "Input patches must be set before this operation. Call set_input_patches() first."

try:
    cc = ColorCorrection()
    # Forgot to fit the model
    corrected = cc.predict(image)
except ModelNotFittedError as e:
    print(f"Error: {e}")
    # Output: "Model must be fitted before prediction. Call fit() first."

try:
    cc = ColorCorrection()
    # Invalid image format
    cc.set_input_patches(grayscale_image)  # 2D array instead of 3D
except InvalidImageError as e:
    print(f"Error: {e}")
    # Output: "Invalid image: image must have 3 dimensions (H, W, C), got 2"

For more details, see the Exception Reference.

🔎 Reporting

import cv2

from color_correction import ColorCorrectionAnalyzer

# input_image_path = "assets/cc-19.png"
input_image_path = "assets/cc-1.jpg"

report = ColorCorrectionAnalyzer(
    list_correction_methods=[
        ("least_squares", {}),
        ("linear_reg", {}),
        ("affine_reg", {}),
        ("polynomial", {"degree": 2}),
        ("polynomial", {"degree": 3}),
        # ("polynomial", {"degree": 4}),
        # ("polynomial", {"degree": 5}),
    ],
    list_detection_methods=[
        ("yolov8", {"detection_conf_th": 0.25}),
        # ("mcc", {}),  # MCCardDetector using OpenCV's mcc module
    ],
)
report.run(
    input_image=cv2.imread(input_image_path),
    reference_image=None,
    output_dir="report-output",
)

Sample Report Output

📈 Benefits

• Consistency: Ensure uniform color correction across multiple images.
• Accuracy: Leverage the color correction matrix for precise color adjustments.
• Flexibility: Adaptable for various image sets with different color profiles.

🤸 TODO

• Add Loggers
• Add detection MCCardDetector from OpenCV's mcc module
• Add Segmentation support for Color Checker detection
• Improve validation preprocessing (e.g., auto-match-orientation CC)
• Add more analysis and evaluation metrics (Still thinking...)

📚 References

• Color Checker Classic 24 Patch Card
• Color Correction Tool ML
• Colour Science Python
• Fast and Robust Multiple ColorChecker Detection ()
• Automatic color correction with OpenCV and Python (PyImageSearch)
• ONNX-YOLOv8-Object-Detection
• yolov8-triton
• Streamlined Data Science Development: Organizing, Developing and Documenting Your Code