https://github.com/hahnec/color-matcher
automatic color-grading
https://github.com/hahnec/color-matcher
augmentation automatic color color-grading colour histogram histogram-equalization image kantorovich lightfield match matching mkl monge photography pitie re-color reinhard stopmotion transfer
Last synced: 5 months ago
JSON representation
automatic color-grading
- Host: GitHub
- URL: https://github.com/hahnec/color-matcher
- Owner: hahnec
- License: gpl-3.0
- Created: 2020-02-29T22:10:45.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2025-03-30T23:06:07.000Z (6 months ago)
- Last Synced: 2025-04-01T13:08:35.714Z (6 months ago)
- Topics: augmentation, automatic, color, color-grading, colour, histogram, histogram-equalization, image, kantorovich, lightfield, match, matching, mkl, monge, photography, pitie, re-color, reinhard, stopmotion, transfer
- Language: Python
- Homepage: https://hahnec.github.io/color-matcher/
- Size: 119 MB
- Stars: 510
- Watchers: 9
- Forks: 34
- Open Issues: 6
-
Metadata Files:
- Readme: README.rst
- License: LICENSE
Awesome Lists containing this project
README
=============
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.
|release| |license| |build_github| |coverage| |pypi_total| |pypi|
|binder|
|hf_spaces|
Results
-------
|vspace|
.. list-table::
:widths: 1 2 2 2
:header-rows: 1
:stub-columns: 1
* -
- Source
- Target
- Result
* - Photograph
- |src_photo|
- |ref_photo|
- |res_photo|
* - Film sequence
- |src_seq|
- |ref_seq|
- |res_seq|
* - Light-field correction
- |src_lfp|
- |ref_lfp|
- |res_lfp|
* - Paintings
- |src_paint|
- |ref_paint|
- |res_paint|
|
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
---------
.. code-block:: python
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'))
.. Hyperlink aliases
.. _source: https://github.com/hahnec/color-matcher/archive/master.zip
.. |src_photo| raw:: html
.. |ref_photo| raw:: html
.. |res_photo| raw:: html
.. |src_paint| raw:: html
.. |ref_paint| raw:: html
.. |res_paint| raw:: html
.. |src_seq| raw:: html
.. |ref_seq| raw:: html
.. |res_seq| raw:: html
.. |src_lfp| raw:: html
.. |ref_lfp| raw:: html
.. |res_lfp| raw:: html
.. |vspace| raw:: latex
\vspace{1mm}
.. |metric_chart| raw:: html
.. |metric_latex| raw:: latex
W_1 = \int_{0}^{\infty} \left| F\left(\mathbf{r}^{(g)}\right) - F\left(\mathbf{z}^{(g)}\right) \right|_1 \, \mathrm{d}k
D_2 = \left\| f(\mathbf{r}) - f(\mathbf{z}) \right\|_2
.. |metric_eqs| raw:: html
.. Image substitutions
.. |release| image:: https://img.shields.io/github/v/release/hahnec/color-matcher?style=square
:target: https://github.com/hahnec/color-matcher/releases/
:alt: release
.. |license| image:: https://img.shields.io/badge/License-GPL%20v3.0-orange.svg?style=square
:target: https://www.gnu.org/licenses/gpl-3.0.en.html
:alt: License
.. |build_travis| image:: https://img.shields.io/travis/com/hahnec/color-matcher?style=square
:target: https://travis-ci.com/github/hahnec/color-matcher
.. |build_github| image:: https://img.shields.io/github/actions/workflow/status/hahnec/color-matcher/gh_actions.yml?branch=master&style=square
:target: https://github.com/hahnec/color-matcher/actions
:alt: GitHub Workflow Status
.. |coverage| image:: https://img.shields.io/coveralls/github/hahnec/color-matcher?style=square
:target: https://coveralls.io/github/hahnec/color-matcher
.. |pypi| image:: https://img.shields.io/pypi/dm/color-matcher?label=PyPI%20downloads&style=square
:target: https://pypi.org/project/color-matcher/
:alt: PyPI Downloads
.. |pypi_total| image:: https://pepy.tech/badge/color-matcher?style=flat-square
:target: https://pepy.tech/project/color-matcher
:alt: PyPi Dl2
.. |binder| image:: https://mybinder.org/badge_logo.svg
:target: https://mybinder.org/v2/gh/hahnec/color-matcher/master?labpath=01_api_demo.ipynb
.. |paper| image:: http://img.shields.io/badge/paper-arxiv.2010.11687-red.svg?style=flat-square
:target: https://arxiv.org/pdf/2010.11687.pdf
:alt: arXiv link
.. |hf_spaces| image:: https://huggingface.co/datasets/huggingface/badges/resolve/main/deploy-on-spaces-md-dark.svg
:target: http://www.hahne.website/color_matcher.html
:alt: Deploy on Spaces
.. |starhistory| image:: https://api.star-history.com/svg?repos=hahnec/color-matcher&type=Date
:alt: Star history cannot be rendered.
Experimental results
--------------------
|metric_chart|
The above diagram illustrates light-field color consistency from Wasserstein metric :math:`W_1` and histogram distance
:math:`D_2` where low values indicate higher similarity between source :math:`\mathbf{r}` and target :math:`\mathbf{z}`.
These distance metrics are computed as follows
|metric_eqs|
where :math:`f(k,\cdot)` and :math:`F(k,\cdot)` represent the Probability Density Function (PDF) and Cumulative Density Function (CDF) at intensity level :math:`k`, respectively.
More detailed information can be found in `our IEEE paper `__.
|vspace|
Stats
-----
|starhistory|
Citation
--------
.. code-block:: BibTeX
@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 `__