颜色¶

def to_rgb(self) -> np.ndarray:
    """颜色的红、绿、蓝分量。

    Returns:
        一个由三个浮点数组成的数组，取值从 0 到 1。
    """
    return self._rgba[:3]

def to_rgba(self) -> np.ndarray:
    """颜色的红、绿、蓝及不透明度。

    Returns:
        一个由四个浮点数组成的数组，取值从 0 到 1。
    """
    return self._rgba

def to_hex(self, with_alpha: bool = False) -> str:
    """以大写十六进制字符串 `"#RRGGBB"` 表示的颜色。

    Args:
        with_alpha: 是否追加不透明度的两位数字：`"#RRGGBBAA"`。

    Returns:
        该字符串。
    """
    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":
    """从本颜色到另一颜色之间某分数位置处的颜色，按所有颜色混合的方式混合：
    在 OKLab 中，两色之间的颜色即人眼在其间所看到的颜色。

    Args:
        other: 对应 1 的颜色。
        alpha: 朝其移动的距离，从 0（本颜色）到 1（`other`）。

    Returns:
        一个新颜色。
    """
    return ManimColor(tuple(mix_rgba(self._rgba, other._rgba, alpha)))

def opacity(self, opacity: float) -> "ManimColor":
    """具有另一个不透明度的本颜色。

    Args:
        opacity: 不透明度，从 0（透明）到 1（不透明）。

    Returns:
        一个新颜色。
    """
    return ManimColor((*self._rgba[:3], float(opacity)))

def lighter(self, blend: float = 0.2) -> "ManimColor":
    """向白色混合后的本颜色，保持其不透明度。

    Args:
        blend: 朝白色移动的距离，从 0（本颜色）到 1（白色）。

    Returns:
        一个新颜色。
    """
    return self.interpolate(WHITE, blend).opacity(self._rgba[3])

def darker(self, blend: float = 0.2) -> "ManimColor":
    """向黑色混合后的本颜色，保持其不透明度。

    Args:
        blend: 朝黑色移动的距离，从 0（本颜色）到 1（黑色）。

    Returns:
        一个新颜色。
    """
    return self.interpolate(BLACK, blend).opacity(self._rgba[3])

@classmethod
def from_hex(cls, hex_str: str, alpha: float = 1.0) -> "ManimColor":
    """由十六进制字符串表示的颜色，按构造函数的方式读取（`"#RRGGBB"`、
    `"#RGB"`，含或不含不透明度数字；也可为颜色名）。

    Args:
        hex_str: 该字符串。
        alpha: 当字符串未给出不透明度时的不透明度，取值从 0 到 1。

    Returns:
        一个新颜色。
    """
    return cls(hex_str, alpha)

@classmethod
def from_rgb(
    cls, rgb: Sequence[float] | Floats, alpha: float = 1.0
) -> "ManimColor":
    """由红、绿、蓝构成的颜色。

    Args:
        rgb: 红、绿、蓝，取值从 0 到 1。
        alpha: 不透明度，取值从 0 到 1。

    Returns:
        一个新颜色。
    """
    return cls(tuple(float(x) for x in rgb), alpha)

@classmethod
def from_rgba(cls, rgba: Sequence[float] | Floats) -> "ManimColor":
    """由红、绿、蓝及不透明度构成的颜色。

    Args:
        rgba: 红、绿、蓝及不透明度，取值从 0 到 1。

    Returns:
        一个新颜色。
    """
    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":
    """由色相、饱和度与明度构成的颜色。

    Args:
        hsv: 色相、饱和度与明度，各为从 0 到 1 的浮点数：色相为 0（或 1）时为红色，
            1/3 为绿色，2/3 为蓝色。
        alpha: 不透明度，取值从 0 到 1。

    Returns:
        一个新颜色。
    """
    return cls(colorsys.hsv_to_rgb(*hsv[:3]), alpha)

@classmethod
def from_hsl(
    cls, hsl: Sequence[float] | Floats, alpha: float = 1.0
) -> "ManimColor":
    """由色相、饱和度与亮度构成的颜色。

    Args:
        hsl: 色相、饱和度与亮度，各取值从 0 到 1：色相为 0（或 1）时为红色，
            1/3 为绿色，2/3 为蓝色；亮度为 0.5 时为纯色。
        alpha: 不透明度，取值从 0 到 1。

    Returns:
        一个新颜色。
    """
    hue, saturation, lightness = hsl[:3]
    return cls(colorsys.hls_to_rgb(hue, lightness, saturation), alpha)

def to_hsv(self) -> np.ndarray:
    """颜色的色相、饱和度与明度。

    Returns:
        一个由三个浮点数组成的数组，取值从 0 到 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":
    """一种与本颜色形成对比、能从其上脱颖而出的颜色，如同文字落于其上一般：
    浅色之上用深色，深色之上用浅色。

    Args:
        threshold: 亮度（0.30 红 + 0.59 绿 + 0.11 蓝），取值从 0 到 1，
            超过此值则本颜色视为浅色。
        light: 用于深色的颜色；None 表示白色。
        dark: 用于浅色的颜色；None 表示黑色。

    Returns:
        `dark` 或 `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":
    """颜色的补色：红、绿、蓝各分量取自 1 减原值，不透明度保持不变。

    Returns:
        一个新颜色。
    """
    return ManimColor((*(1.0 - self._rgba[:3]), self._rgba[3]))

def next(self) -> ManimColor:
    """流的下一个颜色：从其颜色中随机抽取的一个。"""
    return self.choice(self.colors)