Colors¶

def to_rgb(self) -> np.ndarray:
    """The color's red, green and blue.

    Returns:
        An array of three floats, from 0 to 1.
    """
    return self._rgba[:3]

def to_rgba(self) -> np.ndarray:
    """The color's red, green, blue and opacity.

    Returns:
        An array of four floats, from 0 to 1.
    """
    return self._rgba

def to_hex(self, with_alpha: bool = False) -> str:
    """The color as a hex string, `"#RRGGBB"`, in capitals.

    Args:
        with_alpha: Whether to add the opacity's two digits: `"#RRGGBBAA"`.

    Returns:
        The string.
    """
    r, g, b, a = _bytes(self._rgba)
    return f"#{r:02X}{g:02X}{b:02X}" + (f"{a:02X}" if with_alpha else "")

def interpolate(self, other: "ManimColor", alpha: float) -> "ManimColor":
    """The color a fraction of the way from this one to another, mixed as every
    blend of colors is: in OKLab, where the colors between two are those the eye sees
    between them.

    Args:
        other: The color at 1.
        alpha: How far toward it, from 0 (this color) to 1 (`other`).

    Returns:
        A new color.
    """
    return ManimColor(tuple(mix_rgba(self._rgba, other._rgba, alpha)))

def opacity(self, opacity: float) -> "ManimColor":
    """This color with another opacity.

    Args:
        opacity: The opacity, from 0 (transparent) to 1 (opaque).

    Returns:
        A new color.
    """
    return ManimColor((*self._rgba[:3], float(opacity)))

def lighter(self, blend: float = 0.2) -> "ManimColor":
    """This color mixed toward white, its opacity kept.

    Args:
        blend: How far toward white, from 0 (this color) to 1 (white).

    Returns:
        A new color.
    """
    return self.interpolate(WHITE, blend).opacity(self._rgba[3])

def darker(self, blend: float = 0.2) -> "ManimColor":
    """This color mixed toward black, its opacity kept.

    Args:
        blend: How far toward black, from 0 (this color) to 1 (black).

    Returns:
        A new color.
    """
    return self.interpolate(BLACK, blend).opacity(self._rgba[3])

@classmethod
def from_hex(cls, hex_str: str, alpha: float = 1.0) -> "ManimColor":
    """The color of a hex string, read as the constructor reads it (`"#RRGGBB"`,
    `"#RGB"`, with or without opacity digits; a color's name too).

    Args:
        hex_str: The string.
        alpha: The opacity, from 0 to 1, if the string gives none.

    Returns:
        A new color.
    """
    return cls(hex_str, alpha)

@classmethod
def from_rgb(
    cls, rgb: Sequence[float] | Floats, alpha: float = 1.0
) -> "ManimColor":
    """The color of a red, green and blue.

    Args:
        rgb: Red, green and blue, from 0 to 1.
        alpha: The opacity, from 0 to 1.

    Returns:
        A new color.
    """
    return cls(tuple(float(x) for x in rgb), alpha)

@classmethod
def from_rgba(cls, rgba: Sequence[float] | Floats) -> "ManimColor":
    """The color of a red, green, blue and opacity.

    Args:
        rgba: Red, green, blue and opacity, from 0 to 1.

    Returns:
        A new color.
    """
    return cls(tuple(float(x) for x in rgba[:3]), float(rgba[3]))

@classmethod
def from_hsv(
    cls, hsv: Sequence[float] | Floats, alpha: float = 1.0
) -> "ManimColor":
    """The color of a hue, saturation and value.

    Args:
        hsv: Hue, saturation and value, each a float from 0 to 1: a hue of 0 (or 1)
            is red, 1/3 green, 2/3 blue.
        alpha: The opacity, from 0 to 1.

    Returns:
        A new color.
    """
    return cls(colorsys.hsv_to_rgb(*hsv[:3]), alpha)

@classmethod
def from_hsl(
    cls, hsl: Sequence[float] | Floats, alpha: float = 1.0
) -> "ManimColor":
    """The color of a hue, saturation and lightness.

    Args:
        hsl: Hue, saturation and lightness, each from 0 to 1: a hue of 0 (or 1) is
            red, 1/3 green, 2/3 blue; a lightness of 0.5 is the full color.
        alpha: The opacity, from 0 to 1.

    Returns:
        A new color.
    """
    hue, saturation, lightness = hsl[:3]
    return cls(colorsys.hls_to_rgb(hue, lightness, saturation), alpha)

def to_hsv(self) -> np.ndarray:
    """The color's hue, saturation and value.

    Returns:
        An array of three floats, from 0 to 1.
    """
    return np.array(colorsys.rgb_to_hsv(*self.to_rgb()))

def contrasting(
    self,
    threshold: float = 0.5,
    light: "ManimColor | None" = None,
    dark: "ManimColor | None" = None,
) -> "ManimColor":
    """A color that stands out against this one, as text on it would: dark on a
    light color, light on a dark one.

    Args:
        threshold: The luma (0.30 red + 0.59 green + 0.11 blue), from 0 to 1,
            above which this color counts as light.
        light: The color for a dark color; None for white.
        dark: The color for a light color; None for black.

    Returns:
        `dark` or `light`.
    """
    luminance = colorsys.rgb_to_yiq(*self.to_rgb())[0]
    return (dark or BLACK) if luminance > threshold else (light or WHITE)

def invert(self) -> "ManimColor":
    """The color's complement: each of red, green and blue taken from 1, the opacity
    kept.

    Returns:
        A new color.
    """
    return ManimColor((*(1.0 - self._rgba[:3]), self._rgba[3]))

def next(self) -> ManimColor:
    """The stream's next color: one of its colors, drawn at random."""
    return self.choice(self.colors)