{"id":6332,"library":"color-matcher","title":"Color Matcher","description":"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.","status":"active","version":"0.6.0","language":"en","source_language":"en","source_url":"https://github.com/hahnec/color-matcher","tags":["image processing","color transfer","color grading","computer vision","image augmentation"],"install":[{"cmd":"pip install color-matcher","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for image data manipulation (NumPy arrays) passed to ColorMatcher functions.","package":"numpy","optional":false},{"reason":"Often used by color_matcher.io_handler for loading and saving image files, though not explicitly listed as a direct dependency on PyPI.","package":"Pillow","optional":true},{"reason":"Alternative to Pillow, also commonly used for image I/O and manipulation, especially in computer vision contexts.","package":"opencv-python","optional":true}],"imports":[{"symbol":"ColorMatcher","correct":"from color_matcher import ColorMatcher"},{"symbol":"load_img_file","correct":"from color_matcher.io_handler import load_img_file"},{"symbol":"save_img_file","correct":"from color_matcher.io_handler import save_img_file"}],"quickstart":{"code":"import numpy as np\nfrom color_matcher import ColorMatcher\nfrom color_matcher.io_handler import load_img_file, save_img_file\nimport os\nfrom PIL import Image # For creating dummy images\n\n# Create dummy image files for demonstration if they don't exist\ndef create_dummy_image(filepath, color):\n    img = np.full((100, 100, 3), color, dtype=np.uint8)\n    Image.fromarray(img).save(filepath)\n\nsrc_path = 'source_image.png'\nref_path = 'reference_image.png'\noutput_path = 'output_image.png'\n\n# Ensure Pillow is installed if creating dummy images\ntry:\n    from PIL import Image\nexcept ImportError:\n    print(\"Pillow not installed. Please install with 'pip install Pillow' to run this quickstart.\")\n    exit(1)\n\nif not os.path.exists(src_path):\n    create_dummy_image(src_path, [255, 0, 0]) # Red\nif not os.path.exists(ref_path):\n    create_dummy_image(ref_path, [0, 0, 255]) # Blue\n\n# Load source and reference images\n# Images are expected as NumPy arrays, typically (H, W, C) with values 0-255\nimg_src = load_img_file(src_path)\nimg_ref = load_img_file(ref_path)\n\n# Initialize ColorMatcher\ncm = ColorMatcher()\n\n# Perform color transfer using the 'hm-mkl-hm' method (a robust compound method)\n# Other methods include 'reinhard', 'mvgd', 'hm', 'mkl', etc.\nimg_transferred = cm.transfer(src=img_src, ref=img_ref, method='hm-mkl-hm')\n\n# Save the result\nsave_img_file(img_transferred, output_path)\n\nprint(f\"Color transfer complete. Output saved to {output_path}\")\n\n# Clean up dummy images (optional)\nos.remove(src_path)\nos.remove(ref_path)\nos.remove(output_path)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.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.","message":"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.","severity":"gotcha","affected_versions":"<0.5.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<0.3.4 (resolved), general for user error"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}