样式¶

def set_color(
    self,
    color: ParsableManimColor | Iterable[ParsableManimColor],
    family: bool = True,
) -> Self:
    """为 mobject 着色：其填充和描边，保持各自的不透明度（未填充的
    形状保持未填充）。

    Args:
        color: 颜色；多个颜色在 mobject 上形成渐变，从第一个
            到最后一个沿其光泽方向（除非设置否则为 UL）。
        family: 其整个家族是否被着色，还是仅 mobject 本身。

    Examples:
        ```python
        import manimgx as m


        class MobjectSetColorExample(m.Scene):
            def construct(self) -> None:
                circle = m.Circle(radius=1.5)
                square = m.Square(side_length=3, fill_opacity=0.5)
                shapes = m.VGroup(circle, square).arrange(buff=2)
                self.add(shapes)
                self.play(shapes.animate.set_color(m.YELLOW))
                self.play(square.animate.set_color([m.BLUE, m.GREEN]))
        ```
    """
    self.set_fill(color, family=family)
    return self.set_stroke(color, family=family)

def set_fill(
    self,
    color: ParsableManimColor | Iterable[ParsableManimColor] | None = None,
    opacity: float | Iterable[float] | None = None,
    family: bool = True,
) -> Self:
    """设置 mobject 的填充：其颜色、不透明度，或两者。

    Args:
        color: 颜色；多个颜色在 mobject 上形成渐变，从第一个
            到最后一个沿其光泽方向（除非设置否则为 UL）。None 保持
            当前值。
        opacity: 不透明度，从 0（无填充）到 1（不透明）；多个值形成
            不透明度渐变。None 保持当前值。
        family: 其整个家族是否被填充，还是仅 mobject 本身。

    Examples:
        ```python
        import manimgx as m


        class MobjectSetFillExample(m.Scene):
            def construct(self) -> None:
                a, b, c = (m.Square(side_length=2.5) for _ in range(3))
                m.VGroup(a, b, c).arrange(buff=1)
                a.set_fill(m.BLUE, opacity=1)
                b.set_fill(m.GREEN, opacity=0.4)
                c.set_fill([m.YELLOW, m.RED], opacity=1)
                self.add(a, b, c)
        ```
    """
    for mob in reversed(self._each(family)):
        mob.paint = mob.paint.updated("fill", color, opacity)
    return self

def set_stroke(
    self,
    color: ParsableManimColor | Iterable[ParsableManimColor] | None = None,
    width: float | None = None,
    opacity: float | Iterable[float] | None = None,
    background: bool = False,
    family: bool = True,
) -> Self:
    """设置 mobject 的描边，即其轮廓：其颜色、宽度和不透明度，任意
    组合。

    Args:
        color: 颜色；多个颜色形成渐变，从第一个到最后一个沿
            mobject 的光泽方向（除非设置否则为 UL）。None 保持
            当前值。
        width: 宽度，以场景单位的百分之一表示（除非已设置否则为 4；0：无
            描边）；None 保持当前值。
        opacity: 不透明度，从 0 到 1；多个值形成不透明度渐变。
            None 保持当前值。
        background: 是否改为设置背景描边：即在
            填充之后绘制的轮廓。
        family: 其整个家族是否被描边，还是仅 mobject 本身。

    Examples:
        ```python
        import manimgx as m


        class MobjectSetStrokeExample(m.Scene):
            def construct(self) -> None:
                a = m.Circle(radius=1.5, color=m.BLUE, fill_opacity=0.3)
                b, c = a.copy(), a.copy()
                m.VGroup(a, b, c).arrange(buff=1)
                a.set_stroke(m.YELLOW, width=2)
                b.set_stroke(m.YELLOW, width=16)
                c.set_stroke(m.YELLOW, width=16, opacity=0.3)
                self.add(a, b, c)
        ```
    """
    channel = "background" if background else "stroke"
    for mob in reversed(self._each(family)):
        paint = mob.paint.updated(channel, color, opacity)
        if width is not None:
            paint = (
                paint.but(background_width=width)
                if background
                else paint.but(stroke_width=width)
            )
        mob.paint = paint
    return self

def set_opacity(self, opacity: float, family: bool = True) -> Self:
    """统一设置 mobject 填充、描边和背景描边的不透明度——
    因此未填充的形状获得该不透明度的填充。

    Args:
        opacity: 不透明度，从 0（不可见）到 1（不透明）。
        family: 其整个家族是否都获得它，还是仅 mobject 本身。

    Examples:
        ```python
        import manimgx as m


        class MobjectSetOpacityExample(m.Scene):
            def construct(self) -> None:
                square = m.Square(side_length=3, color=m.BLUE, fill_opacity=1)
                circle = m.Circle(radius=1.5, color=m.YELLOW, fill_opacity=1)
                square.shift(m.LEFT)
                circle.shift(m.RIGHT)
                self.add(square, circle)
                self.play(circle.animate.set_opacity(0.3))
        ```
    """
    self.set_fill(opacity=opacity, family=family)
    self.set_stroke(opacity=opacity, family=family)
    return self.set_stroke(opacity=opacity, background=True, family=family)

def fade(self, darkness: float = 0.5, family: bool = True) -> Self:
    """使 mobject 更淡：其填充、描边和背景描边的
    不透明度各乘以 1 − `darkness`。

    Args:
        darkness: 变淡程度，从 0（原样）到 1（不可见）。
        family: 其整个家族是否变淡，还是仅 mobject 本身。
    """
    factor = 1.0 - darkness
    if factor == 1.0:
        return self
    for mob in self._each(family):
        p, faded = mob.paint, {}
        for name in ("fill", "stroke", "background"):  # every row: stops, points
            rows = getattr(p, name)
            if len(rows):
                faded[name] = rows * [1.0, 1.0, 1.0, factor]
        mob.paint = p.but(**faded)
    return self

def fade_to(
    self, color: ParsableManimColor, alpha: float, family: bool = True
) -> Self:
    """将 mobject 的颜色向另一种混合：每个绘制成员自身的颜色，
    混合到 `color` 的 `alpha` 处。

    Args:
        color: 要混合到的目标颜色。
        alpha: 混合程度，从 0（原样）到 1（`color`）。
        family: 其整个家族是否混合，还是仅 mobject 本身。
    """
    if self.has_points():
        self.set_color(
            interpolate_color(self.get_color(), ManimColor(color), alpha),
            family=False,
        )
    if family:
        for sub in self.submobjects:
            sub.fade_to(color, alpha)
    return self

def set_style(
    self,
    fill_color: ParsableManimColor | Iterable[ParsableManimColor] | None = None,
    fill_opacity: float | Iterable[float] | None = None,
    stroke_color: ParsableManimColor | Iterable[ParsableManimColor] | None = None,
    stroke_width: float | None = None,
    stroke_opacity: float | Iterable[float] | None = None,
    background_stroke_color: (
        ParsableManimColor | Iterable[ParsableManimColor] | None
    ) = None,
    background_stroke_width: float | None = None,
    background_stroke_opacity: float | Iterable[float] | None = None,
    sheen_factor: float | None = None,
    sheen_direction: Vector3DLike | None = None,
    family: bool = True,
) -> Self:
    """一次性设置 mobject 的任意样式：为 None 的保持不变。

    参见 [set_fill][manimgx.Mobject.set_fill]、
    [set_stroke][manimgx.Mobject.set_stroke] 和
    [set_sheen][manimgx.Mobject.set_sheen]；光泽仅在 `sheen_factor`
    非零时改变。

    Args:
        fill_color: 填充的颜色；多个颜色形成渐变。
        fill_opacity: 填充的不透明度，从 0 到 1。
        stroke_color: 描边的颜色；多个颜色形成渐变。
        stroke_width: 描边的宽度，以场景单位的百分之一表示。
        stroke_opacity: 描边的不透明度，从 0 到 1。
        background_stroke_color: 在填充之后绘制的轮廓的颜色。
        background_stroke_width: 该轮廓的宽度，以场景单位的
            百分之一表示。
        background_stroke_opacity: 该轮廓的不透明度，从 0 到 1。
        sheen_factor: 颜色向 `sheen_direction` 变亮的程度，从 -1
            到 1；None 或 0 使光泽保持不变。
        sheen_direction: 它们变亮的方向，与 `sheen_factor` 一起设置。
        family: 其整个家族是否被设置样式，还是仅 mobject 本身。
    """
    self.set_fill(fill_color, fill_opacity, family)
    self.set_stroke(stroke_color, stroke_width, stroke_opacity, family=family)
    self.set_stroke(
        background_stroke_color,
        background_stroke_width,
        background_stroke_opacity,
        background=True,
        family=family,
    )
    if sheen_factor:
        self.set_sheen(sheen_factor, sheen_direction, family)
    return self

def match_style(self, mobject: "Mobject", family: bool = True) -> Self:
    """将另一个的样式赋予 mobject：其颜色、不透明度、描边宽度、光泽
    及其余外观，但不包括揭示动画显示多少。

    Args:
        mobject: 要取其样式的 mobject。
        family: 子 mobject 是否也按顺序取另一个的样式：
            当数量不同时均匀配对，各自取另一个
            mobject 自身的样式（若无子 mobject）。
    """
    self.paint = mobject.paint.but(trim=self.paint.trim)
    if family:
        subs1, subs2 = self.submobjects, mobject.submobjects
        if subs1:
            subs2 = subs2 or [mobject]
            n = max(len(subs1), len(subs2))
            for i in range(n):
                subs1[i * len(subs1) // n].match_style(subs2[i * len(subs2) // n])
    return self

def match_color(self, mobject: "Mobject") -> Self:
    """用另一个的 [color][manimgx.Mobject.color] 为 mobject 及其整个家族
    着色。

    Args:
        mobject: 要取其颜色的 mobject。
    """
    return self.set_color(mobject.get_color())

def set_color_by_gradient(self, *colors: ParsableManimColor) -> Self:
    """沿渐变为家族中绘制的成员着色：按家族顺序，每个
    为纯色，从第一个颜色到最后一个。

    一个颜色为它们全部着色；无颜色抛出异常。

    Args:
        *colors: 渐变所经过的颜色，均匀分布。

    Examples:
        ```python
        import manimgx as m


        class MobjectSetColorByGradientExample(m.Scene):
            def construct(self) -> None:
                dots = m.VGroup(*(m.Dot(radius=0.35) for _ in range(9)))
                dots.arrange(buff=0.5)
                dots.set_color_by_gradient(m.BLUE, m.GREEN, m.YELLOW)
                word = m.Text("gradient", font_size=120)
                word.set_color_by_gradient(m.RED, m.YELLOW)
                self.add(m.VGroup(dots, word).arrange(m.DOWN, buff=1))
        ```
    """
    return self.set_submobject_colors_by_gradient(*colors)

def set_colors_by_radial_gradient(
    self,
    center: Point3DLike | None = None,
    radius: float = 1,
    inner_color: ParsableManimColor = WHITE,
    outer_color: ParsableManimColor = "#000000",
) -> Self:
    """按距某点的远近为 mobject 着色：该处为 `inner_color`，在
    `radius` 及以外混合到 `outer_color`。

    家族中每个绘制的成员为一种纯色，按其中心的距离。

    Args:
        center: 该点；None 表示 mobject 的中心。
        radius: 颜色为 `outer_color` 时的距离，以场景单位表示。
        inner_color: 该点处的颜色。
        outer_color: `radius` 及以外的颜色。
    """
    c = self.get_center() if center is None else np.asarray(center)
    for mob in self.family_members_with_points():
        t = min(float(np.linalg.norm(mob.get_center() - c)) / radius, 1)
        mob.set_color(
            interpolate_color(ManimColor(inner_color), ManimColor(outer_color), t),
            family=False,
        )
    return self

def set_submobject_colors_by_radial_gradient(
    self,
    center: Point3DLike | None = None,
    radius: float = 1,
    inner_color: ParsableManimColor = WHITE,
    outer_color: ParsableManimColor = "#000000",
) -> Self:
    """按家族中绘制成员的中心距某点的远近为它们着色：
    该处为 `inner_color`，在 `radius` 及以外混合到 `outer_color`；
    每个成员为一种纯色。

    Args:
        center: 该点；None 表示 mobject 的中心。
        radius: 颜色为 `outer_color` 时的距离，以场景单位表示。
        inner_color: 该点处的颜色。
        outer_color: `radius` 及以外的颜色。
    """
    c = self.get_center() if center is None else np.asarray(center)
    for mob in self.family_members_with_points():
        t = min(float(np.linalg.norm(mob.get_center() - c)) / radius, 1.0)
        mob.set_color(
            interpolate_color(ManimColor(inner_color), ManimColor(outer_color), t),
            family=False,
        )
    return self

def set_sheen(
    self, factor: float, direction: Vector3DLike | None = None, family: bool = True
) -> Self:
    """赋予 mobject 光泽：其颜色在其上变亮，朝某方向。

    当因子非零时，其填充和描边各自成为从其颜色到该颜色按因子变亮
    的渐变。

    Args:
        factor: 颜色变亮的程度，从 -1 到 1：0 表示无光泽，
            负因子使颜色变暗。
        direction: 它们变亮的方向，作为值拷贝；None
            保持当前值（除非已设置否则为 UL）。调用者的数组
            不变。
        family: 其整个家族是否都获得它，还是仅 mobject 本身。
    """
    if direction is not None:
        direction = frozen(np.array(direction, dtype=float, copy=True))
    for mob in self._each(family):
        mob.paint = (
            mob.paint.but(sheen_factor=factor)
            if direction is None
            else mob.paint.but(sheen_factor=factor, sheen_direction=direction)
        )
        if factor != 0:
            mob.paint = mob.paint.updated("stroke", mob.get_stroke_color(), None)
            mob.paint = mob.paint.updated("fill", mob.get_fill_color(), None)
    return self

def set_sheen_direction(self, direction: Vector3DLike, family: bool = True) -> Self:
    """设置 mobject 颜色变亮的方向，其渐变也沿此方向运行。

    Args:
        direction: 方向，作为值拷贝，不改变
            调用者的数组。
        family: 其整个家族是否都获得它，还是仅 mobject 本身。
    """
    direction = frozen(np.array(direction, dtype=float, copy=True))
    for mob in self._each(family):
        mob.paint = mob.paint.but(sheen_direction=direction)
    return self

def set_cap_style(self, cap_style: CapStyleType) -> Self:
    """设置路径及其家族的描边在它们显示的每个端点处如何结束：
    开放路径的端点、揭示动画的移动端、每个虚线的端点。

    二维场景绘制端帽；三维场景将每条
    描边平头结束（参见 [CapStyleType][manimgx.CapStyleType]）。

    Args:
        cap_style: 端帽样式：圆头、平头或方头。
    """
    for mob in self.get_family():
        mob.paint = mob.paint.but(cap=cap_style)
    return self

def set_z_index(self, z_index_value: float, family: bool = True) -> Self:
    """设置 mobject 在绘制顺序中的位置：z 索引较高的绘制在较低的之上，
    在场景中的任何位置。

    z 索引相同的 mobject 按场景的顺序绘制：后添加的绘制在先添加的之上，
    mobject 的子 mobject 各自绘制在之前的之上。每个 mobject 的 z 索引
    除非设置否则为 0。

    Args:
        z_index_value: z 索引。
        family: 其整个家族是否都获得它，还是仅 mobject 本身（仅
            排序其自身的点）。

    Examples:
        ```python
        import manimgx as m


        class MobjectSetZIndexExample(m.Scene):
            def construct(self) -> None:
                red = m.Square(3, color=m.RED, fill_opacity=1).shift(m.LEFT + m.UP)
                blue = m.Square(3, color=m.BLUE, fill_opacity=1)
                green = m.Square(3, color=m.GREEN, fill_opacity=1)
                green.shift(m.RIGHT + m.DOWN)
                red.set_z_index(1)  # added first, drawn on top
                self.add(red, blue, green)
        ```
    """
    if family:
        for sub in self.submobjects:
            sub.set_z_index(z_index_value, family)
    self.z_index = z_index_value
    return self

def add_background_rectangle(
    self,
    color: ParsableManimColor | None = None,
    opacity: float = 0.75,
    **kwargs: Unpack[BackgroundOptions],
) -> Self:
    """在 mobject 后面放一个矩形，使其与后面的内容区分开来：
    一个围绕它的 [BackgroundRectangle][manimgx.BackgroundRectangle]，作为其
    第一个子 mobject 添加。

    该矩形随 mobject 移动；它是 mobject 的
    [background_rectangle][manimgx.Mobject.background_rectangle]。

    Args:
        color: 矩形的颜色；None 表示场景的背景色。
        opacity: 矩形的不透明度，从 0 到 1（默认 0.75）。
        **kwargs: [背景关键字][manimgx.mobject.BackgroundOptions]：其
            边距、圆角和轮廓。

    Examples:
        ```python
        import manimgx as m


        class MobjectAddBackgroundRectangleExample(m.Scene):
            def construct(self) -> None:
                label = m.Text("set off from the grid", font_size=64)
                label.add_background_rectangle(color=m.BLACK, opacity=0.9, buff=0.2)
                self.add(m.NumberPlane(), label)
        ```
    """
    from manimgx.mobjects.annotations import BackgroundRectangle

    self.background_rectangle = BackgroundRectangle(
        self, color=color, fill_opacity=opacity, **kwargs
    )
    return self.add_to_back(self.background_rectangle)

@classmethod
def set_default(cls, **kwargs: object) -> None:
    """更改该类构造器关键字的默认值，对之后创建的该类每个
    mobject 生效；不给出参数时恢复默认值。

    在 `Text.set_default(font_size=100)` 之后，`Text` 为 100 磅，除非
    创建时指定了其他尺寸。关键字在创建 mobject 时检查。

    更改或恢复默认值会丢弃已记忆的构造。现有的
    mobject 保持其状态；后续构造读取当前默认值。

    重复调用替换此类的关键字默认值。重置恢复其
    原始构造器，或若无自身构造器则恢复正常继承。
    默认值在创建 mobject 时应用，使用当时生效的构造器：
    类自身的，或所创建 mobject 类顺序中的下一个（因此
    父类的后续默认值能到达已配置的子类，已配置的混入调用
    子类顺序中其后的类）。

    Args:
        **kwargs: 该类构造器的关键字，及其新默认值。
    """
    if kwargs:
        original = cls.__dict__.get(
            "_original__init__", cls.__dict__.get("__init__")
        )
        defaults = dict(kwargs)

        # The constructor checks the keywords when it runs: defaults applied to a
        # signature have no static type
        def init(self: Mobject, *args: object, **given: object) -> None:
            merged = defaults | given
            if original is not None:
                original(self, *args, **merged)
            else:
                super(cls, self).__init__(*args, **merged)

        setattr(cls, "_original__init__", original)  # noqa: B010
        setattr(cls, "__init__", init)  # noqa: B010
    elif "_original__init__" in cls.__dict__:
        original = cls.__dict__["_original__init__"]
        delattr(cls, "_original__init__")
        if original is None:
            delattr(cls, "__init__")
        else:
            setattr(cls, "__init__", original)  # noqa: B010
    caches.clear()