API documentation

Class hierarchy

A schematic overview of the class hierarchy is seen in the diagram below:

_images/arch.png

As the classes will be of primary interest for future extensions, all are documented hereafter.

API

class color_matcher.ColorMatcher(*args, **kwargs)
__init__(*args, **kwargs)
main() → numpy.ndarray

The main function is the high-level entry point performing the mapping based on instantiation arguments.

Returns

Resulting image after color mapping

Return type

np.ndarray

transfer(src: Optional[numpy.ndarray] = None, ref: Optional[numpy.ndarray] = None, method: Optional[str] = None) → numpy.ndarray

Transfer function to map colors based on provided transfer method.

Parameters

  • src (ndarray) – Source image that requires transfer

  • ref (ndarray) – Palette image which serves as reference

  • method (str) – (‘default’, ‘hm’, ‘reinhard’, ‘mvgd’, ‘mkl’, ‘hm-mvgd-hm’, ‘hm-mkl-hm’) determining color mapping

Returns

Resulting image after color mapping

Return type

np.ndarray

class color_matcher.HistogramMatcher(*args, **kwargs)
__init__(*args, **kwargs)
hist_match(src: Optional[numpy.ndarray] = None, ref: Optional[numpy.ndarray] = None) → numpy.ndarray

This function conducts channel-wise histogram matching which is invariant of image resolutions, but requires the same number of color channels in both images.

Parameters

  • src (ndarray) – Source image that requires transfer

  • ref (ndarray) – Palette image which serves as reference

  • res (ndarray) – Resulting image after the mapping

Returns

res

Return type

np.ndarray

class color_matcher.TransferMVGD(*args, **kwargs)
__init__(*args, **kwargs)
analytical_solver() → numpy.ndarray

An analytical solution to the linear equation system of Multi-Variate Gaussian Distributions (MVGDs).

Returns

transfer_mat: Transfer matrix

Return type

np.ndarray

check_dims()

Catch error for wrong color channel number (e.g., gray scale image)

Returns

None

mkl_solver()

This function computes the transfer matrix based on the Monge-Kantorovich Linearization (MKL).

Returns

transfer_mat: Transfer matrix

Return type

np.ndarray

multivar_transfer(src: Optional[numpy.ndarray] = None, ref: Optional[numpy.ndarray] = None, fun: Optional[function] = None) → numpy.ndarray

Transfer function to map colors based on for Multi-Variate Gaussian Distributions (MVGDs).

Parameters

  • src (ndarray) – Source image that requires transfer

  • ref (ndarray) – Palette image which serves as reference

  • fun – Optional argument to pass a transfer function to solve for covariance matrices

  • res (ndarray) – Resulting image after the mapping

Returns

res

Return type

np.ndarray

static w2_dist(mu_a: numpy.ndarray, mu_b: numpy.ndarray, cov_a: numpy.ndarray, cov_b: numpy.ndarray) → float

Wasserstein-2 distance metric is a similarity measure for Gaussian distributions

Parameters

  • mu_a (ndarray) – Gaussian mean of distribution a

  • mu_b (ndarray) – Gaussian mean of distribution b

  • cov_a (ndarray) – Covariance matrix of distribution a

  • cov_b (ndarray) – Covariance matrix of distribution b

Returns

scalar: Wasserstein-2 metric as a scalar

Return type

float

w2_img_dist(img_a: numpy.ndarray, img_b: numpy.ndarray)

Wasserstein-2 image distance metric is a similarity measure for Gaussian distributions

Parameters
Returns

scalar: Wasserstein-2 image metric as a scalar

Return type

float

class color_matcher.ReinhardMatcher(*args, **kwargs)
__init__(*args, **kwargs)
reinhard(src: Optional[numpy.ndarray] = None, ref: Optional[numpy.ndarray] = None) → numpy.ndarray

This function conducts color matching based on the principles proposed by Reinhard et al. The paper of the original work can be found at https://www.cs.tau.ac.il/~turkel/imagepapers/ColorTransfer.pdf

Parameters

  • src (ndarray) – Source image that requires transfer

  • ref (ndarray) – Palette image which serves as reference

  • res (ndarray) – Resulting image after the mapping

Returns

res

Return type

np.ndarray

class color_matcher.MatcherBaseclass(*args, **kwargs)
__init__(*args, **kwargs)
static rgb2gray(rgb: Optional[numpy.ndarray] = None, standard: str = 'HDTV') → numpy.ndarray

Convert RGB color space to monochromatic color space

Parameters

  • rgb (ndarray) – input array in red, green and blue (RGB) space

  • standard (string) – option that determines whether head- and footroom are excluded (‘HDTV’) or considered otherwise

Returns

array in monochromatic space

Return type

ndarray

validate_color_chs()

This function checks whether provided images consist of a valid number of color channels.

validate_img_dims()

This function validates the image dimensions. It throws an exception if the dimension are unequal to 2 or 3.