embcol.problem.Problem

class embcol.problem.Problem(dissimilarities, weights=None, fixed=None, min_lightness=0.0, max_lightness=1.0, hue_groups=(), hue_diff_tol=0.07)

Bases: object

Embedding problem.

Parameters:

• dissimilarities (array-like of float) – Dissimilarities among samples. The shape must be ((N-1)*N//2,), where N is the number of samples: items are off-diagonal elements above the main diagonal of a dissimilarity matrix in row-major order.

• weights (array-like of float, optional) – Weights of sample pairs. The shape must be ((N-1)*N//2,), where N is the number of samples: items are off-diagonal elements above the main diagonal of a dissimilarity matrix in row-major order. If nothing is given, all pairs are equally weighted.

• fixed (mapping of int to array-like of float, optional) – Color-fixed samples. Map the index of a sample to an Oklab color.

• min_lightness (float, optional) – Lower bound of the lightness. The value must be in the range [0, 1).

• max_lightness (float, optional) – Upper bound of the lightness. The value must be in the range (0, 1].

• hue_groups (collection of collection of int, optional) – Groups of samples whose hues are equal. An item indicates a group. The item is a collection of indices of samples.

• hue_diff_tol (float, optional) – Tolerance for the hue difference within each group given by hue_groups.

Notes

An instance represents an optimization problem minimizing

\[f(\vec{x}_1, \ldots, \vec{x}_N) = \frac{1}{2} \sum_{i=1}^{N-1} \sum_{j=i+1}^N w_{ij} \left[s \, \Delta E(\vec{x}_i, \vec{x}_j)^2 - d_{ij}^2\right]^2\]

subject to

\[ \begin{align}\begin{aligned}0 \le (\vec{x}_i)_k \le 1, \quad i \in \{1, \ldots, N\}, k \in \{1, 2, 3\}\\\left|h(\vec{x}_i) - h(\vec{x}_j)\right| \le \epsilon, \quad i \in g, j \in g \setminus \{i\}, g \in G\end{aligned}\end{align} \]

where \(\vec{x}_i\) is an sRGB color of the \(i\)th sample, \(\Delta E(\cdot, \cdot)\) is the color difference between two colors, \(d_{ij}\) is a dissimilarity between the \(i\)th and \(j\)th samples, \(w_{ij}\) is a weight of the pair of the \(i\)th and \(j\)th samples, \(s\) is a scaling factor, \(h(\cdot)\) is the hue of a color, \(\epsilon\) is a tolerance for the hue difference, \(G\) is a set of sets of sample indices, and \(N\) is the number of samples.

The weights, \(\{w_{ij}\}\), are normalized so that the mean is equal to one.

The scaling factor, \(s\), is determined so that the partial sum of \(f\) among color-fixed samples are minimized. If the number of color-fixed samples are less than two, \(s\) is set to one.

Attributes

bounds	Bounds of parameters.
constraints	Constraints.
dissimilarities	Dissimilarities among samples.
effective_bounds	Effective bounds of parameters.
fixed	Color-fixed samples.
hue_diff_tol	Tolerance for the hue difference.
hue_groups	Groups of samples whose hues are equal.
max_lightness	Upper bound of the lightness.
min_lightness	Lower bound of the lightness.
n_params	Number of parameters.
n_samples	Number of samples.
scale	Scaling factor.
unfixed_indices	Indices of color-unfixed samples.
weights	Weights of sample pairs.

Methods

cost(params, *[, return_jacobian, ...])	Evaluate a cost.
oklabs_to_params(oklabs)	Convert Oklab colors of samples to parameters.
params_to_oklabs(params)	Convert parameters to Oklab colors of samples.