hahnec / color-matcher

automatic color-grading

color-matcher

Description

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.

Results

	Source	Target	Result
Photograph
Film sequence
Light-field correction
Paintings

Installation

• 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 https://www.python.org/
  2. download the source using git clone https://github.com/hahnec/color-matcher.git
  3. go to the root directory cd color-matcher
  4. load dependencies $ pip3 install -r requirements.txt
  5. install with python3 setup.py 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)]

cm = ColorMatcher()
for i, fname in enumerate(filenames):
    img_src = load_img_file(fname)
    img_res = cm.transfer(src=img_src, ref=img_ref, method='mkl')
    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₁ and histogram distance D₂ where low values indicate higher similarity between source r and target z. These distance metrics are computed as follows

where f(k,  ⋅ ) and F(k,  ⋅ ) 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.

Citation

@ARTICLE{plenopticam,
    author={Hahne, Christopher and Aggoun, Amar},
    journal={IEEE Transactions on Image Processing},
    title={PlenoptiCam v1.0: A Light-Field Imaging Framework},
    year={2021},
    volume={30},
    number={},
    pages={6757-6771},
    doi={10.1109/TIP.2021.3095671}
}

Author

Christopher Hahne

color-matcher's Issues

Should there be a new release?

Hi Chris!

HM-MVGD-HM looks like an excellent algorithm for color matching. Thanks a lot for creating it!

I'm just curious. PyPi is at version 0.5.0 from Aug 25, 2021: https://pypi.org/project/color-matcher/#history

But I spotted a commit from Nov 4, 2021 which adds another algorithm: 552010d

Was that algorithm not good enough to make it into a new release? :)

Color-matcher batch processing

I've just discovered color-matcher and find it potentially very useful for preprocessing histopathological datasets for deep learning. I can't, however, find a way to use it in batch mode - that is - is there any way to load more than one source image and/or more than one target image to process larger image datasets in batch?

Change frame sequence output name

Hi, still amazed by this tool, great idea!

When a video is given as input, or rather, the frames folder of a video, the output (frame sequence) should be named like this: NAME_000, NAME_001, etc

This is because otherwise most video editing programs (eg Premiere) fail to import them correctly as a video. In fact, I had to change the name of all frames using a script.

I also confirm, as already reported in another issue, that the result is excellent, but it is not consistent between all frames. It's like the color are corrected frame by frame but without considering the previous ones and therefore always giving a slightly different output. This give in output a video that flickers.

Any way to increase consistency between frames? Maybe creating a "threshold" parameter that indicates how much keep closer to the previous frame?

Thanks
Emax

Doc suggests pip3 for install, Anaconda seems to work with pip only

I'm using Anaconda (Conda 4.9.2) and used the documentation's suggested pip3 install procedure for color-matcher, but I couldn't run it from the command prompt. However, when I installed it via pip (just pip) it worked fine.

I ain't entirely sure if this fella got Python 3.8 and Python 2.7 both in there, but somehow I can only get it to run by entering only color-matcher in the command line after installing through pip as opposed to pip3.

Might need an extra line in the documentation saying do this if you're using Anaconda or Python 2.x or something, I ain't entirely sure of what's going on behind the scenes really.

Rendering videos

hi
thanks for this great piece of code.

I am doing some tests on videos, is there a specific mode to ensure temporal consistency for video rendering?

I have tried a few image by image processing, and the results are subject to flickering, especially when there are strong intense areas, even small (the blinking crosswalk light in the below examples)

thanks

video7_bushi_compare_sml.mp4

video7_colorful_landscape_compare_sml.mp4

[ Feature Request ] CLUT Output

The ability to save a CLUT of the color transformation would be useful for applying the transformation to other scenes / videos / games, and for tweaking the transformation with other tools for artistic purposes with color-matcher's output as the starting point.

Look I got the early morning lightheadedness and I wanna gush about this program, this has saved me such a hassle trying to white balance the most fucked up of photos with purple skin, absolutely marvelous. Software intended for auto white-balance just made em all green, but this matched it to a collage of similar faces in better lighting and damn if it isn't just the best outcome I could imagine for the material. I could overhaul an entire dataset and augment the shit out of it if I wanted. This is baller.

Add option to run all methods at once ?

Is it possible to add a mask to the color matcher module

Hi!

Thanks for the great work! I'm wondering if I can add a mask onto the color matcher module to perform a local/regional color transfer.

Permission error & There is no CLI

macOS Monterey 12.6.1 (intel)
Python 3.11

1. pip3 install color-matcher permission eror

2. pip3 install -U color-matcher