SBColor#

This class describes a color and can be used to colorize e.g. atoms individually.

Please refer to the Apply color section to lear how to apply colors to nodes.

This class also provides functionality to convert between different color spaces:

  • sRGB (standard RGB)

  • HSV (Hue Saturation Value)

  • HCL (CIE L*u*v* in cylindrical coordinates, a.k.a. CIE LCh_uv)

  • CIE L*u*v*

  • CIE L*a*b*

  • CIE L*a*b* in cylindrical coordinates, a.k.a. CIE LCh_ab

  • CIE XYZ with D65/2° standard illuminant

To use any functionality in this module, pass a list with 3 floating point values in a function, e.g.:

Convert colors between color spaces#
color_in_sRGB = [1.0, 0.0, 0.0] # red color in sRGB color space
color_in_HCL = SBColor.toHCL(color_in_sRGB)

Note that the conversion is not exact. For example, a conversion from sRGB to HCL and then back from HCL to sRGB will result in values that might slightly differ from the original ones by some numerical error due to approximations in conversion functions.

You can also ligthen or darken the color using SBColor.lightenSRGBColor() and SBColor.darkenSRGBColor() functions respectively.

See also

Colorizing nodes

SAMSON SDK: SBDTypeColor

class samson.SBColor(*args, **kwargs)#

Bases: pybind11_object

This class describes a color.

Overloaded function.

  1. __init__(self: samson.SBColor) -> None

Constructs a color (1.0, 1.0, 1.0, 1.0) .. rubric:: Examples

>>> color = SBColor()
>>> print(color)
[1.000000, 1.000000, 1.000000, 1.000000]

  1. __init__(self: samson.SBColor, red: float, green: float, blue: float, alpha: float = 1.0) -> None

Constructs a color (red, green, blue, alpha). Arguments should be in the range [0.0, 1.0].

Parameters:

  • red (float) – The red component of RGB-color.

  • green (float) – The green component of RGB-color.

  • blue (float) – The blue component of RGB-color.

  • alpha (float, default=1.0) – The alpha component (transparency).

Examples

>>> color = SBColor(0.25, 0.5, 0.75, 1.0)
>>> print(color)
[0.250000, 0.500000, 0.750000, 1.000000]

  1. __init__(self: samson.SBColor, red: int, green: int, blue: int, alpha: int = 255) -> None

Constructs a color (red, green, blue, alpha). Arguments should be in the range [0, 255].

Parameters:

  • red (int) – The red component of RGB-color.

  • green (int) – The green component of RGB-color.

  • blue (int) – The blue component of RGB-color.

  • alpha (int, default=255) – The alpha component (transparency).

Examples

>>> color = SBColor(120, 160, 200, 255)
>>> print(color)
[0.470588, 0.627451, 0.784314, 1.000000]

  1. __init__(self: samson.SBColor, hexColor: str) -> None

Constructs a color from the hex color.

Parameters:

hexColor (string) – The hex color. It can start with ‘#’ or not and should contain a hex triplet (six-digit or eight-digit).

Examples

>>> color = SBColor("#0099CC")
>>> print(color)
[0.000000, 0.600000, 0.800000, 1.000000]

  1. __init__(self: samson.SBColor, color: samson.SBColor) -> None

Constructs a color based on another color color.

static CIELabfromCIEXYZ(arg0: list[float]) → list[float]#

Converts CIE XYZ D65/2° to CIE L*a*b*

static CIELabfromCylindricalCIELab(arg0: list[float]) → list[float]#

Converts CIE L*a*b* in cylindrical coordinates (a.k.a. CIE LCh_ab) to CIE L*a*b*

static CIELabfromSRGB(arg0: list[float]) → list[float]#

Converts color from standard RGB (sRGB) color space to CIE L*a*b* color space

static CIELuvfromCIEXYZ(arg0: list[float]) → list[float]#

Converts CIE XYZ D65/2° to CIE L*u*v*

static CIELuvfromCylindricalCIELuv(arg0: list[float]) → list[float]#

Converts CIE L*u*v* in cylindrical coordinates (a.k.a. CIE LCh_uv) to CIE L*u*v*

static CIEXYZfromCIELab(arg0: list[float]) → list[float]#

Converts CIE L*a*b* to CIE XYZ D65/2°

static CIEXYZfromCIELuv(arg0: list[float]) → list[float]#

Converts CIE L*u*v* to CIE XYZ D65/2°

static CIEXYZfromRGB(arg0: list[float]) → list[float]#

Converts linear RGB to CIE XYZ with D65/2° standard illuminant

static CIEXYZfromSRGB(arg0: list[float]) → list[float]#

Converts device independent standard RGB (sRGB) to CIE XYZ with D65/2° standard illuminant

static HCLfromSRGB(arg0: list[float]) → list[float]#

Converts standard RGB (sRGB) color to HCL color (cylindrical representation of CIE L*u*v* a.k.a. CIE LCh_uv)

static HSVfromSRGB(arg0: list[float]) → list[float]#

Converts sRGB color (as in SBColor) to HSV (Hue Saturation Value)

static RGBfromCIEXYZ(arg0: list[float]) → list[float]#

Converts CIE XYZ with D65/2° standard illuminant to linear RGB

static RGBfromSRGB(arg0: list[float]) → list[float]#

Converts standard RGB (sRGB) values to linear RGB values.

static SRGBfromCIELab(arg0: list[float]) → list[float]#

Converts color from CIE L*a*b* color space to standard RGB (sRGB) color space

static SRGBfromCIEXYZ(arg0: list[float]) → list[float]#

Converts CIEXYZ with D65/2° standard illuminant to device independent standard RGB (sRGB)

static SRGBfromCylindricalCIELab(arg0: list[float]) → list[float]#

Converts CIE L*a*b* in cylindrical coordinates (a.k.a. CIE LCh_ab) to standard RGB (sRGB)

static SRGBfromCylindricalCIELuv(arg0: list[float]) → list[float]#

Converts CIE L*u*v* in cylindrical coordinates (a.k.a. CIE LCh_uv) to standard RGB (sRGB)

static SRGBfromHCL(arg0: list[float]) → list[float]#

Converts HCL color (cylindrical representation of CIE L*u*v* a.k.a. CIE LCh_uv) to standard RGB (sRGB) color

static SRGBfromHSV(arg0: list[float]) → list[float]#

Converts HSV color (Hue Saturation Value) to sRGB color (as in SBColor)

static SRGBfromRGB(arg0: list[float]) → list[float]#

Converts linear RGB values to standard RGB (sRGB) values.

static SRGBtoGrayscale(red: float, green: float, blue: float) → float#

Converts sRGB to grayscale

bounded(self: samson.SBColor) → samson.SBColor#

Returns a bounded version of the color with components within [0, 1]

static cylindricalCIELabfromCIELab(arg0: list[float]) → list[float]#

Converts CIE L*a*b* to CIE L*a*b* in cylindrical coordinates (a.k.a. CIE LCh_ab)

static cylindricalCIELabfromSRGB(arg0: list[float]) → list[float]#

Converts standard RGB (sRGB) to CIE L*a*b* in cylindrical coordinates a.k.a. (CIE LCh_ab)

static cylindricalCIELuvfromCIELuv(arg0: list[float]) → list[float]#

Converts CIE L*u*v* to CIE L*u*v* in cylindrical coordinates (a.k.a. CIE LCh_uv)

static cylindricalCIELuvfromSRGB(arg0: list[float]) → list[float]#

Converts standard RGB (sRGB) to CIE L*u*v* in cylindrical coordinates (a.k.a. CIE LCh_uv)

static darkenSRGBColor(color: samson.SBColor, amount: float) → samson.SBColor#

Darkens the standard RGB (sRGB) color by the amount` amount`.

Parameters:

  • color (samson.SBColor) – The input color.

  • amount (float) – The amount by which the color should be darkened.

Returns:

The output color.

Return type:

samson.SBColor

Examples

>>> color = SBColor(0.25, 0.5, 0.75, 1.0)
>>> darkened_color = SBColor.darkenSRGBColor(color, 0.1)
>>> print(darkened_color)
[0.226566, 0.482166, 0.730498, 1.000000]
static fromHCL(*args, **kwargs)#

Overloaded function.

  1. fromHCL(hue: float, chroma: float, luminance: float) -> samson.SBColor

Creates a color from the given HCL (CIE LCh_uv) color

  1. fromHCL(arg0: list[float]) -> list[float]

Converts HCL color (cylindrical representation of CIE L*u*v* a.k.a. CIE LCh_uv) to sRGB color (as in SBColor)

static fromHSV(*args, **kwargs)#

Overloaded function.

  1. fromHSV(hue: float, saturation: float, value: float) -> samson.SBColor

Creates a color from the given HSV color

  1. fromHSV(arg0: list[float]) -> list[float]

Converts HSV color (Hue Saturation Value) to sRGB color (as in SBColor)

frozen(self: samson.SBColor) → samson.SBColor#

Returns a frozen version of the color

static lightenSRGBColor(color: samson.SBColor, amount: float) → samson.SBColor#

Lightens the standard RGB (sRGB) color by the amount amount.

Parameters:

  • color (samson.SBColor) – The input color.

  • amount (float) – The amount by which the color should be lightened.

Returns:

The output color.

Return type:

samson.SBColor

Examples

>>> color = SBColor(0.25, 0.5, 0.75, 1.0)
>>> lightened_color = SBColor.lightenSRGBColor(color, 0.1)
>>> print(lightened_color)
[0.272724, 0.517956, 0.769592, 1.000000]
printDebugInfo(self: samson.SBColor, offset: int = 0) → None#

Prints some debugging information in stdout.

toGrayscale(self: samson.SBColor) → float#

Returns the grayscale representation of the color.

static toHCL(arg0: list[float]) → list[float]#

Converts sRGB color (as in SBColor) to HCL (cylindrical representation of CIE L*u*v* a.k.a. CIE LCh_uv)

Parameters:

color (a list of 3 or 4 floats (rgb or rgba)) – A color in sRGB color space. The 4th element may represent the alpha-channel and is not modified but copied in the resulting list.

Returns:

A color in HCL color space (hcl or hcl with alpha-channel, corresponding to the size of the input list). If the input list had a 4th float then the 4th element is copied without changes.

Return type:

list of 3 or 4 floats

Examples

>>> color_in_sRGB = [1.0, 0.0, 0.0] # red color in sRGB color space
>>> color_in_HCL = SBColor.toHCL(color_in_sRGB)
>>> print(color_in_HCL)
[12.17395305633545, 179.04075622558594, 53.24058532714844]
static toHSV(arg0: list[float]) → list[float]#

Converts sRGB color (as in SBColor) to HSV (Hue Saturation Value)

toHex(self: samson.SBColor, includeAlpha: bool = False) → str#

Returns the hex representation of the color.

toList(self: samson.SBColor) → list[float]#

Returns the four color components as a list of floats.

property a#

The alpha component, the value is in the [0.0, 1.0] interval.

property b#

The blue component, the value is in the [0.0, 1.0] interval.

black = SBColor(0.000000, 0.000000, 0.000000, 1.000000)#
blue = SBColor(0.000000, 0.000000, 1.000000, 1.000000)#
cyan = SBColor(0.000000, 1.000000, 1.000000, 1.000000)#
defaultKeyframeColor = SBColor(0.800000, 0.898039, 1.000000, 1.000000)#
property g#

The green component, the value is in the [0.0, 1.0] interval.

globalXAxis = SBColor(0.878431, 0.380392, 0.227451, 1.000000)#
globalYAxis = SBColor(0.309804, 0.741176, 0.396078, 1.000000)#
globalZAxis = SBColor(0.290196, 0.556863, 0.929412, 1.000000)#
green = SBColor(0.000000, 1.000000, 0.000000, 1.000000)#
property ia#

The alpha component, the integer value is in the [0, 255] interval.

property ib#

The blue component, the integer value is in the [0, 255] interval.

ice = SBColor(0.000000, 0.098039, 0.196078, 1.000000)#
property ig#

The green component, the integer value is in the [0, 255] interval.

property ir#

The red component, the integer value is in the [0, 255] interval.

property isSerializable#

Returns True when the class is serializable

localXAxis = SBColor(0.949020, 0.976471, 1.000000, 1.000000)#
localYAxis = SBColor(0.800000, 0.898039, 1.000000, 1.000000)#
localZAxis = SBColor(0.650980, 0.823529, 1.000000, 1.000000)#
magenta = SBColor(1.000000, 0.000000, 1.000000, 1.000000)#
orange = SBColor(1.000000, 0.588235, 0.172549, 1.000000)#
property r#

The red component, the value is in the [0.0, 1.0] interval.

red = SBColor(1.000000, 0.000000, 0.000000, 1.000000)#
white = SBColor(1.000000, 1.000000, 1.000000, 1.000000)#
yellow = SBColor(1.000000, 1.000000, 0.000000, 1.000000)#