Color Transfer (Correlated RGB Space)

Color transfer between two images using covariance alignment in correlated RGB space.

This repository contains:

• MATLAB implementation: Color_Transfer_CCS.m, ColorTransferDemo.m
• Python notebook: Colortransfer.ipynb
• Python CLI demo: color_transfer_demo.py
• Example images: files.
• Report: Djahnine_Aissam_Color_Transfer_in_Correlated_color_space.pdf

What the algorithm does

Given a source and target image, the method:

1. Computes channel means and covariance matrices.
2. Uses SVD to decorrelate/re-correlate color distributions.
3. Applies translation + rotation + scaling transforms.
4. Produces a source-shaped output with target-like color statistics.

Python Setup (uv)

From the repo root:

cd /Users/aissam/ColorTransfer
uv sync

This creates .venv and installs required runtime dependencies.

Run the Python Demo

1) Batch mode on bundled examples

uv run color-transfer --save outputs

This processes:

• files./source.jpg + files./target.jpg
• files./source_1.jpg + files./target_1.jpg
• files./source_2.jpg + files./target_2.jpg
• files./source_3.jpg + files./target_3.jpg

and writes:

• outputs/result.jpg
• outputs/result_1.jpg
• outputs/result_2.jpg
• outputs/result_3.jpg

2) Single-pair mode (your own files)

uv run color-transfer --source /path/to/source.jpg --target /path/to/target.jpg --save outputs

3) Preview window and preview-grid export

uv run color-transfer --save outputs --show
uv run color-transfer --save outputs --save-preview-grid previews

--save-preview-grid writes side-by-side comparison images (preview*.jpg).

4) Histogram matching baseline (option 3)

uv run color-transfer --method histogram --postprocess clip --save outputs --save-preview-grid previews --metrics-file outputs/histogram_metrics.csv

Use --method ccs (default) to switch back to the correlated-color-space transform.

CLI Options

uv run color-transfer --help

Important options:

• --method {ccs,histogram}: choose algorithm (default: ccs)
• --source, --target: process one pair explicitly
• --pairs: number of indexed pairs in --base-dir (batch mode)
• --save / --save-dir: output directory for result images
• --show: OpenCV display windows
• --save-preview-grid: save source/target/result side-by-side grids
• --postprocess {minmax,clip,percentile}: output scaling mode
• --percentile-low, --percentile-high: percentile bounds for percentile mode
• --eps: eigenvalue regularization epsilon (stability for low-variance targets)
• --metrics-file: write run metrics to .json or .csv

Metrics Output

Example:

uv run color-transfer --save outputs --metrics-file outputs/metrics.csv
uv run color-transfer --save outputs --metrics-file outputs/metrics.json

Metrics include per-pair runtime, source/target dimensions, and per-channel mean/std for source, target, and result.

Testing

Install dev dependencies and run tests:

uv sync --group dev
uv run --group dev pytest

Current tests cover:

• shape/type invariants
• deterministic behavior for same inputs
• no crash on mismatched image sizes and degenerate targets

MATLAB Usage

Main function:

function est_im = Color_Transfer_CCS(source, target)

Demo script:

ColorTransferDemo

Reference

Algorithm write-up: Djahnine_Aissam_Color_Transfer_in_Correlated_color_space.pdf