[![build][badge_thumbnail]][badge_link]

# colortrans

An implementation of various algorithms for transferring the colors from a reference image to a
content image while preserving the qualitative appearance of the content image (i.e., color
transfer).

<div align="center">
  <a href="https://github.com/dstein64/media/blob/main/colortrans/content.jpg?raw=true">
    <img src="https://github.com/dstein64/media/blob/main/colortrans/content_thumbnail.jpg?raw=true" height="164"/>
  </a>
  <a href="https://github.com/dstein64/media/blob/main/colortrans/reference.jpg?raw=true">
    <img src="https://github.com/dstein64/media/blob/main/colortrans/reference_thumbnail.jpg?raw=true" height="164"/>
  </a>
  <br>
  <a href="https://github.com/dstein64/media/blob/main/colortrans/output.jpg?raw=true">
    <img src="https://github.com/dstein64/media/blob/main/colortrans/output_thumbnail.jpg?raw=true" width="536"/>
  </a>
</div>

Installation
------------

#### Requirements

- Python 3.8 or greater (earlier versions may work, but are not tested)

#### Install

```sh
$ pip3 install colortrans
```

#### Update

```sh
$ pip3 install --upgrade colortrans
```

Command-Line Usage
------------------

The program can be used from the command line.

The general command line usage is shown below.

```sh
$ colortrans [--method METHOD] [--single-precision] CONTENT REFERENCE OUTPUT
```

`CONTENT` is the path to the content image, `REFERENCE` is the path to the style image, and `OUTPUT`
is the path to save the output image.

`METHOD` specifies the color transfer algorithm. The following methods are supported:

1. `lhm` Linear Histogram Matching [1] (default)
2. `pccm` Principal Components Color Matching [2, 3]
3. `reinhard` Reinhard et al. [4]

If the optional `--single-precision` flag is present, 32-bit floats will be used instead of 64-bit floats.

If the launcher script was not installed within a directory on your PATH, colortrans can be launched by
passing its module name to Python.

```sh
$ python3 -m colortrans [--method METHOD] CONTENT REFERENCE OUTPUT
```

Library Usage
-------------

The algorithms can also be used directly from Python programs. Each of the methods listed above has
a corresponding function, `transfer_METHOD`, taking two NumPy arrays corresponding to the content
and reference image, respectively. The arrays have `HxWxC` data ordering (channels-last). The functions
also take an optional keyword argument, `single_precision`, a boolean that specifies whether 32-bit
floats will be used instead of 64-bit floats (defaults to `False`).

#### Example

```python
import colortrans
import numpy as np
from PIL import Image

# Load data
with Image.open('/path/to/content.jpg') as img:
    content = np.array(img.convert('RGB'))
with Image.open('/path/to/reference.jpg') as img:
    reference = np.array(img.convert('RGB'))

# Transfer colors using different algorithms
output_lhm = colortrans.transfer_lhm(content, reference)
output_pccm = colortrans.transfer_pccm(content, reference)
output_reinhard = colortrans.transfer_reinhard(content, reference)

# Save outputs
Image.fromarray(output_lhm).save('/path/to/output_lhm.jpg')
Image.fromarray(output_pccm).save('/path/to/output_pccm.jpg')
Image.fromarray(output_reinhard).save('/path/to/output_reinhard.jpg')
```

References
----------

[1] Hertzmann, Aaron. "Algorithms for Rendering in Artistic Styles." Ph.D., New York University,
2001.

[2] Kotera, Hiroaki, Hung-Shing Chen, and Tetsuro Morimoto. "Object-to-Object Color Mapping by Image
Segmentation." In Color Imaging: Device-Independent Color, Color Hardcopy, and Graphic Arts IV,
3648:148–57. SPIE, 1998.

[3] Kotera, Hiroaki. "A Scene-Referred Color Transfer for Pleasant Imaging on Display." In IEEE
International Conference on Image Processing 2005, 2:II–5, 2005.

[4] Reinhard, Erik, Michael Adhikhmin, Bruce Gooch, and Peter Shirley. "Color Transfer between
Images." IEEE Computer Graphics and Applications 21, no. 5 (July 2001): 34–41.

[badge_link]: https://github.com/dstein64/colortrans/actions/workflows/build.yml
[badge_thumbnail]: https://github.com/dstein64/colortrans/actions/workflows/build.yml/badge.svg
