schrodinger.application.matsci.colorutils module

Contains utilities for color manipulation and conversion

Copyright Schrodinger, LLC. All rights reserved.

schrodinger.application.matsci.colorutils.get_distance(point_1, point_2)

Get the distance between points 1 and 2. Accepts points as arbitrary-length lists or tuples and calculates the distance between them.

Parameters
  • point_1 (list or tuple) – The first point

  • point_2 (list or tuple) – The second point

Return type

float

Returns

The distance between the two points

schrodinger.application.matsci.colorutils.luminance_level(color_tuple)

Returns the luminance level of an RGB color tuple. Grabbed from the web, it is supposedly used to convert color TV to B&W. Luminance runs from 0 to X, where X is the upper limit of a color_tuple value (typically 255 or 65535). One place this algorithm is found is in the W3C accessibility working draft for color contrast in webpages.

Parameters

color_tuple (tuple) – The color’s RGB as a tuple

Return type

float

Returns

The luminance of the color

schrodinger.application.matsci.colorutils.color_distance(color1_rgb, color2_rgb)

Calculates the distance in u’v’ space between two colors

Parameters
  • color1_rgb (tuple) – The RGB tuple of color 1

  • color2_rgb (tuple) – The RGB tuple of color 2

Return type

float

Returns

The distance between the two colors in u’v’ space

schrodinger.application.matsci.colorutils.ciexy_to_upvp(ciex, ciey)

Converts CIE(x,y) to CIE(u’v’), returns CIEu’ and CIEv’. Note that u’v’ are from the CIELUV color space (1976).

Parameters
  • ciex (float) – CIE’s x component

  • ciey (float) – CIE’s y component

Return type

float, float

Returns

CIEu’ and CIEv’

schrodinger.application.matsci.colorutils.web_cie_to_rgb(color_tuple, whitepoint=(0.333, 0.333), xyz_to_rgb=True)

Converts CIEx,y,z data to RGB values if xyz_to_rgb is True. If false, the other way around.

Parameters
  • color_tuple (tuple) – CIEx,y,z or RGB tuple for the color

  • whitepoint (tuple) – CIEx,y for white

  • xyz_to_rgb (bool) – Whether CIEx,y,z should be converted to RGB or the other way around

Return type

tuple

Returns

Converted CIEx,y,z or RGB tuple for the color

schrodinger.application.matsci.colorutils.calculate_ciexy(x_vals, y_vals)

Calculates the CIE coordinates of the passed x and y data.

Parameters
  • x_vals (list) – X values of the spectrum

  • y_vals (list) – Y values of the spectrum

Return type

tuple

Returns

Tuple containing CIEx, CIEy, CIEX, CIEY and CIEZ

schrodinger.application.matsci.colorutils.calculate_nits(x_vals, y_vals)

Calculates and returns Candelas/m2 assuming x_vals is in nm and y_vals is in W-Light/Sr/m2

Parameters
  • x_vals (list) – X values of the spectrum

  • y_vals (list) – Y values of the spectrum

Return type

float

Returns

The nits of the spectrum

schrodinger.application.matsci.colorutils.color_temperature(cie_x, cie_y)

Calculates the correlated color temperature (CCT) from CIEx and CIEy values

Parameters
  • cie_x (float) – The CIEx value of the spectrum

  • cie_y (float) – The CIEy value of the spectrum

Return type

float, bool

Returns

CCT and a boolean that tells whether CCT falls within the required tolerance (0.05 in CIE1960 uv space) for valid CCT

schrodinger.application.matsci.colorutils.distance_from_planckian(cie_x, cie_y, cct=None)

Determines the distance of the point (cie_x, cie_y) from the Planckian locus in CIE 1960 uv space.

If the correlated color temperature of cie_x, cie_y is known, it can be supplied as cct, otherwise it is calculated.

Parameters
  • cie_x (float) – The CIEx value of the spectrum

  • cie_y (float) – The CIEy value of the spectrum

  • cct (float or None) – Correlated color temperature of the spectrum

Return type

float

Returns

Distance from the Planckian locus

schrodinger.application.matsci.colorutils.ciexy_to_cie1960uv(cie_x, cie_y)

Converts cie(x,y) to cie(uv).

Parameters
  • cie_x (float) – The CIEx value of the spectrum

  • cie_y (float) – The CIEy value of the spectrum

Return type

float, float

Returns

CIEu, CIEv of the spectrum. Note that u’v’ are from the 1960 USC color space.

schrodinger.application.matsci.colorutils.planckian_locus(temperature=None, delta=50)

” If temperature is given, returns the CIEx and CIEy values of the Planckian locus at that temperature. If temperature is not given, returns a list of (color, (CIEx, CIEy)) tuples of the Planckian locus from 1000K to 25000K at every delta CCT degrees.

Parameters
  • temperature (float or None) – The temperature to get CIEx and CIEy values at

  • delta (int) – The temperature step between each (CIEx, CIEy) tuple if temperature is not provided

Return type

tuple or list

Returns

CIEx and CIEy at the given temperature, or a list of (color, (CIEx, CIEy)) tuples

schrodinger.application.matsci.colorutils.get_gamut_area(cie_pairs, xy_space=True)

Calculates the area of the triangle formed by the provided CIEx,y pairs.

Parameters
  • cie_pairs (tuple) – Tuple of three (CIEx, CIEy) pairs

  • xy_space (bool) – Whether the CIE is given and the gamut is returned in the x,y space, or the u’v’ space

Return type

float

Returns

The area of triangle formed by the cie pairs

schrodinger.application.matsci.colorutils.calculate_cri(intensities, cct=None)

Calculates the CIE Color Rendering Index of the spectrum. Calculates cct if it is not supplied.

Parameters
  • intensities (list) – Spectrum intensities from 400-700 nm in arbitrary units.

  • cct (float or None) – Correlated color temperature

Return type

int, bool

Returns

CRI and a boolean that tells whether CRI falls within the required tolerance

schrodinger.application.matsci.colorutils.planckian_radiator(temp, low=400, high=700, step=1)

Returns the normalized spectrum of a Planckian (black body) radiator at the given color temperature.

The spectrum is a list of intensities returned starting at low nm and ending at high nm every step nm. The intensities are normalized. intensity = 2*pi*h*(c^2) / (L^5 * (exp(hc/Lkt) - 1)) Where L is the wavelength in meters

Parameters
  • temp (float) – The color temperature for the Planckian radiator

  • low (int) – The lower nm cutoff of the returned values

  • high (int) – The higher nm cutoff of the returned values

  • step (int) – The step between returned values

Return type

list

Returns

The normalized spectrum of a Planckian radiator

schrodinger.application.matsci.colorutils.daylight_radiator(temp, low=400, high=700, step=1)

Returns the normalized spectrum of a illuminant D (daylight) radiator at the given color temperature.

The spectrum is a list of intensities returned starting at low nm and ending at high nm every step nm. The intensities are normalized.

Parameters
  • temp (float) – The color temperature for the radiator

  • low (int) – The lower nm cutoff of the returned values

  • high (int) – The higher nm cutoff of the returned values

  • step (int) – The step in nm between returned values

Return type

list

Returns

The normalized spectrum of a illuminant D radiator

schrodinger.application.matsci.colorutils.daylight_locus(temperature=None, delta=50)

If temperature is given, returns the CIEx and CIEy values of the daylight locus at that temperature. If temperature is not given, returns a list of (color, (CIEx, CIEy)) tuples of the daylight locus from 4000K to 25000K at every delta CCT degrees

Parameters
  • temperature (float or None) – The temperature to get CIEx and CIEy values at

  • delta (int) – The temperature step between each (CIEx, CIEy) tuple if temperature is not provided

schrodinger.application.matsci.colorutils.get_complete_spectrum(x_vals, y_vals, data_min, data_max)

Fills in the missing values of a spectrum using a cubic interpolation, so that it has data for every nm.

Makes sure all y values are > 0, all x values are between data_min and data_max, and no x value is repeated.

Parameters
  • x_vals (list) – X values of the spectrum

  • y_vals (list) – Y values of the spectrum

  • data_min (int) – The low cut-off for x values

  • data_max (int) – The high cut-off for x values

Return type

list, list

Returns

The completed x and y values for the spectrum