{"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":"python","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,"search_vec":"'0.6.0':10 'across':16 'activ':83 'al':57,66 'analyt':69 'augment':40,98 'automat':25 'base':53 'color':1,3,14,27,48,91,93 'color-grad':26 'comput':95 'data':39 'deep':42 'design':11 'develop':84 'distribut':76 'effici':13 'et':56,65 'film':33 'gaussian':75 'grade':28,94 'high':20 'imag':17,38,89,97 'implement':46 'includ':51 'kantorovich':60 'learn':43 'librari':45 'like':24 'linear':61 'maintain':81 'map':49 'matcher':2,4 'method':50 'mkl':62 'mong':59 'monge-kantorovich':58 'multi':73 'multi-vari':72 'mvgd':77 'packag':8 'paint':31 'photograph':30 'piti':64 'process':90 'project':80 'python':7 'regular':87 'reinhard':55 'sequenc':34 'solut':70 'status':85 'task':23 'transfer':15,78,92 'updat':88 'use':21 'variat':74 'various':47 'version':9 'vision':96 'well':36","created_at":"2026-04-15T05:32:42.519445+00:00","updated_at":"2026-04-16T03:07:01.853972+00:00","problems":[{"fix":"Ensure the package is correctly installed using pip: `pip install color-matcher`","cause":"This error occurs when the 'color-matcher' package is not installed in the Python environment or the Python interpreter cannot find it.","error":"ModuleNotFoundError: No module named 'color_matcher'"},{"fix":"Before 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.","cause":"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.","error":"ValueError: Images do not match"},{"fix":"Review 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).","cause":"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.","error":"AttributeError: 'ColorMatcher' object has no attribute 'some_method'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.6.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"http://github.com/hahnec/color-matcher","docs":null,"changelog":null,"pypi":"https://pypi.org/project/color-matcher/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}