Color Matcher

0.6.0 · active · verified Wed Apr 15

Color Matcher is a Python package (version 0.6.0) designed for efficient color transfer across images. It is highly useful for tasks like automatic color-grading of photographs, paintings, and film sequences, as well as image data augmentation in deep learning. The library implements various color mapping methods, including those based on Reinhard et al., Monge-Kantorovich Linearization (MKL) by Pitie et al., and an analytical solution to Multi-Variate Gaussian Distribution (MVGD) transfer. The project maintains an active development status with regular updates.

Warnings

gotcha The `ColorMatcher` class historically used a `main()` method for color transfer. While `main()` is still viable in v0.6.0, the `transfer(src, ref, method)` method was introduced in v0.5.0 as the preferred and more flexible API for performing color mapping.
Fix: Prefer using `ColorMatcher().transfer(src=img_src, ref=img_ref, method='method_name')` over `ColorMatcher(src=img_src, ref=img_ref, method='method_name').main()` for future-proof code and explicit control.
gotcha Prior to version 0.5.0, `color-matcher` might not have correctly handled grayscale images or images with an alpha channel. This functionality was improved starting with v0.5.0.
Fix: Ensure you are using `color-matcher` version 0.5.0 or newer for robust handling of grayscale and alpha-channel images. Consider converting images to RGB if issues persist on older versions.
gotcha Earlier versions (e.g., <0.3.4) had known issues with command-line interface (CLI) usage, particularly concerning batch processing, directory paths, and quoting arguments. Although these are largely resolved, incorrect path formatting remains a common user error.
Fix: Always use absolute paths or paths relative to your current working directory. On Windows, ensure paths with spaces are correctly quoted (e.g., `--src="./my images/source.png"`). Refer to the official documentation's CLI usage examples.

Install

pip install color-matcher Install stable version

Imports

ColorMatcher
```
from color_matcher import ColorMatcher
```

load_img_file

from color_matcher.io_handler import load_img_file

save_img_file

from color_matcher.io_handler import save_img_file

Quickstart

This quickstart demonstrates how to load source and reference images (creating dummy ones for easy demonstration), perform color transfer using the `ColorMatcher` class's `transfer()` method, and save the resulting image. Images are handled as NumPy arrays.

import numpy as np
from color_matcher import ColorMatcher
from color_matcher.io_handler import load_img_file, save_img_file
import os
from PIL import Image # For creating dummy images

# Create dummy image files for demonstration if they don't exist
def create_dummy_image(filepath, color):
    img = np.full((100, 100, 3), color, dtype=np.uint8)
    Image.fromarray(img).save(filepath)

src_path = 'source_image.png'
ref_path = 'reference_image.png'
output_path = 'output_image.png'

# Ensure Pillow is installed if creating dummy images
try:
    from PIL import Image
except ImportError:
    print("Pillow not installed. Please install with 'pip install Pillow' to run this quickstart.")
    exit(1)

if not os.path.exists(src_path):
    create_dummy_image(src_path, [255, 0, 0]) # Red
if not os.path.exists(ref_path):
    create_dummy_image(ref_path, [0, 0, 255]) # Blue

# Load source and reference images
# Images are expected as NumPy arrays, typically (H, W, C) with values 0-255
img_src = load_img_file(src_path)
img_ref = load_img_file(ref_path)

# Initialize ColorMatcher
cm = ColorMatcher()

# Perform color transfer using the 'hm-mkl-hm' method (a robust compound method)
# Other methods include 'reinhard', 'mvgd', 'hm', 'mkl', etc.
img_transferred = cm.transfer(src=img_src, ref=img_ref, method='hm-mkl-hm')

# Save the result
save_img_file(img_transferred, output_path)

print(f"Color transfer complete. Output saved to {output_path}")

# Clean up dummy images (optional)
os.remove(src_path)
os.remove(ref_path)
os.remove(output_path)

view raw JSON →