color-matcher enables color transfer across images which comes in handy for automatic color-grading of photographs, paintings and film sequences as well as light-field and stopmotion corrections. The methods behind the mappings are based on the approach from Reinhard et al., the Monge-Kantorovich Linearization (MKL) as proposed by Pitie et al. and our analytical solution to a Multi-Variate Gaussian Distribution (MVGD) transfer in conjunction with classical histogram matching. As shown below our HM-MVGD-HM compound outperforms existing methods.

  Source Target Result
Film sequence
Light-field correction


  • via pip:
    1. install with pip3 install color-matcher
    2. type color-matcher -h to the command line once installation finished
  • from source:
    1. install Python from
    2. download the source using git clone
    3. go to the root directory cd color-matcher
    4. load dependencies $ pip3 install -r requirements.txt
    5. install with python3 install
    6. if installation ran smoothly, enter color-matcher -h to the command line

CLI Usage

From the root directory of your downloaded repo, you can run the tool on the provided test data by

color-matcher -s './tests/data/scotland_house.png' -r './tests/data/scotland_plain.png'

on a UNIX system where the result is found at ./tests/data/. A windows equivalent of the above command is

color-matcher --src=".\\tests\\data\\scotland_house.png" --ref=".\\tests\\data\\scotland_plain.png"

Alternatively, you can specify the method or select your images manually with

color-matcher --win --method='hm-mkl-hm'

Note that batch processing is possible by passing a source directory, e.g., via

color-matcher -s './tests/data/' -r './tests/data/scotland_plain.png'

More information on optional arguments, can be found using the help parameter

color-matcher -h

API Usage

from color_matcher import ColorMatcher
from color_matcher.io_handler import load_img_file, save_img_file, FILE_EXTS
from color_matcher.normalizer import Normalizer
import os

img_ref = load_img_file('./tests/data/scotland_plain.png')

src_path = '.'
filenames = [os.path.join(src_path, f) for f in os.listdir(src_path)
                     if f.lower().endswith(FILE_EXTS)]

for i, fname in enumerate(filenames):
    img_src = load_img_file(fname)
    obj = ColorMatcher(src=img_src, ref=img_ref, method='mkl')
    img_res = obj.main()
    img_res = Normalizer(img_res).uint8_norm()
    save_img_file(img_res, os.path.join(os.path.dirname(fname), str(i)+'.png'))

Experimental results

The above diagram illustrates light-field color consistency from Wasserstein metric W_1 and histogram distance D_2 where low values indicate higher similarity between source \mathbf{r} and target \mathbf{z}. These distance metrics are computed as follows

where f(k,\cdot) and F(k,\cdot) represent the Probability Density Function (PDF) and Cumulative Density Function (CDF) at intensity level k, respectively. More detailed information can be found in our IEEE paper.


    author={Hahne, Christopher and Aggoun, Amar},
    journal={IEEE Transactions on Image Processing},
    title={PlenoptiCam v1.0: A Light-Field Imaging Framework},


Christopher Hahne