Install & Compatibility
Where this runs
tested against v0.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.257s · 185.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 8.3s · import 0.273s · 178MB
189MB installed
● package 189MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
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)
Debug
Known issues
gotchaThe `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.fixPrefer 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.
affects: >=0.5.0
gotchaPrior 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.fixEnsure 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.
affects: <0.5.0
gotchaEarlier 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.fixAlways 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.
affects: <0.3.4 (resolved), general for user error
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'color_matcher'
This error occurs when the 'color-matcher' package is not installed in the Python environment or the Python interpreter cannot find it.
fixEnsure the package is correctly installed using pip: `pip install color-matcher`
ValueError: Images do not match
This error typically arises when attempting to perform a color transfer or comparison operation between two input images that have incompatible dimensions (height, width) or different numbers of color channels.
fixBefore passing images to `color-matcher` functions, ensure they have consistent dimensions and color channels (e.g., both RGB, both grayscale, and the same height/width). Resizing or converting image formats might be necessary using libraries like OpenCV or Pillow.
AttributeError: 'ColorMatcher' object has no attribute 'some_method'
This error indicates that you are trying to call a method or access an attribute that does not exist on the `ColorMatcher` object, often due to a typo in the method name or attempting to use a feature not available in the library's API.
fixReview the official `color-matcher` documentation for the correct method names and available attributes. Double-check your spelling and ensure the method you're trying to use is part of the installed `color-matcher` version (0.6.0).
Upgrade
Version history
0.6.0latest on PyPI · released Mar 30, 2025
Audit
Dependencies
numpyrequiredRequired for image data manipulation (NumPy arrays) passed to ColorMatcher functions.
PillowoptionalOften used by color_matcher.io_handler for loading and saving image files, though not explicitly listed as a direct dependency on PyPI.
opencv-pythonoptionalAlternative to Pillow, also commonly used for image I/O and manipulation, especially in computer vision contexts.