Style¶

def set_color(
    self,
    color: ParsableManimColor | Iterable[ParsableManimColor],
    family: bool = True,
) -> Self:
    """Color the mobject: its fill and its stroke, which keep their opacities (an
    unfilled shape stays unfilled).

    Args:
        color: The color; several make a gradient across the mobject, from the first
            to the last toward its sheen direction (UL unless set).
        family: Whether its whole family is colored, or the mobject alone.

    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:
    """Set the mobject's fill: its color, its opacity, or both.

    Args:
        color: The color; several make a gradient across the mobject, from the first
            to the last toward its sheen direction (UL unless set). None keeps the
            present one.
        opacity: The opacity, from 0 (no fill) to 1 (opaque); several make a
            gradient of opacities. None keeps the present one.
        family: Whether its whole family is filled, or the mobject alone.

    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:
    """Set the mobject's stroke, its outline: its color, width and opacity, any of
    them.

    Args:
        color: The color; several make a gradient, from the first to the last toward
            the mobject's sheen direction (UL unless set). None keeps the present
            one.
        width: The width, in hundredths of a scene unit (4 unless styled; 0: no
            stroke); None keeps the present one.
        opacity: The opacity, from 0 to 1; several make a gradient of opacities.
            None keeps the present one.
        background: Whether to set the background stroke instead: an outline drawn
            behind the fill.
        family: Whether its whole family is stroked, or the mobject alone.

    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:
    """Set the opacity of the mobject's fill, stroke and background stroke alike —
    so an unfilled shape gets a fill of that opacity.

    Args:
        opacity: The opacity, from 0 (invisible) to 1 (opaque).
        family: Whether its whole family gets it, or the mobject alone.

    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:
    """Make the mobject fainter: its fill's, stroke's and background stroke's
    opacities each times 1 − `darkness`.

    Args:
        darkness: How much fainter, from 0 (as it is) to 1 (invisible).
        family: Whether its whole family fades, or the mobject alone.
    """
    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:
    """Blend the mobject's color toward another: each drawn member's own color,
    mixed `alpha` of the way to `color`.

    Args:
        color: The color to blend toward.
        alpha: How far, from 0 (as it is) to 1 (`color`).
        family: Whether its whole family blends, or the mobject alone.
    """
    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:
    """Set any of the mobject's style at once: what is None stays as it is.

    See [set_fill][manimgx.Mobject.set_fill],
    [set_stroke][manimgx.Mobject.set_stroke] and
    [set_sheen][manimgx.Mobject.set_sheen]; the sheen changes only with a nonzero
    `sheen_factor`.

    Args:
        fill_color: The fill's color; several make a gradient.
        fill_opacity: The fill's opacity, from 0 to 1.
        stroke_color: The stroke's color; several make a gradient.
        stroke_width: The stroke's width, in hundredths of a scene unit.
        stroke_opacity: The stroke's opacity, from 0 to 1.
        background_stroke_color: The color of the outline drawn behind the fill.
        background_stroke_width: That outline's width, in hundredths of a scene
            unit.
        background_stroke_opacity: That outline's opacity, from 0 to 1.
        sheen_factor: How much the colors lighten toward `sheen_direction`, from -1
            to 1; None or 0 leaves the sheen as it is.
        sheen_direction: The direction they lighten toward, set with `sheen_factor`.
        family: Whether its whole family is styled, or the mobject alone.
    """
    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:
    """Give the mobject another's style: its colors, opacities, stroke widths, sheen
    and the rest of its look, all but how much of it a reveal shows.

    Args:
        mobject: The mobject whose style to take.
        family: Whether the submobjects take the style of the other's too, in order:
            paired evenly when their numbers differ, and each taking the other
            mobject's own if it has none.
    """
    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 the mobject and its whole family with another's
    [color][manimgx.Mobject.color].

    Args:
        mobject: The mobject whose color to take.
    """
    return self.set_color(mobject.get_color())

def set_color_by_gradient(self, *colors: ParsableManimColor) -> Self:
    """Color the drawn members of the family along a gradient: in family order, each
    one solid, from the first color to the last.

    One color colors them all; none raises an exception.

    Args:
        *colors: The colors the gradient runs through, evenly.

    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:
    """Color the mobject by distance from a point: `inner_color` there, blending to
    `outer_color` at `radius` and beyond.

    Each drawn member of the family is one solid color, by its center's distance.

    Args:
        center: The point; None for the mobject's center.
        radius: The distance at which the color is `outer_color`, in scene units.
        inner_color: The color at the point.
        outer_color: The color at `radius` and beyond.
    """
    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:
    """Color the drawn members of the family by how far their centers are from a
    point: `inner_color` there, blending to `outer_color` at `radius` and beyond;
    each member one solid color.

    Args:
        center: The point; None for the mobject's center.
        radius: The distance at which the color is `outer_color`, in scene units.
        inner_color: The color at the point.
        outer_color: The color at `radius` and beyond.
    """
    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:
    """Give the mobject a sheen: its colors lighten across it, toward a direction.

    With a nonzero factor, its fill and its stroke each become a gradient from their
    color to that color lightened by the factor.

    Args:
        factor: How much the colors lighten, from -1 to 1: 0 for no sheen, a
            negative factor darkens.
        direction: The direction they lighten toward, copied as a value; None
            keeps the present one (UL unless styled). The caller's array is
            unchanged.
        family: Whether its whole family gets it, or the mobject alone.
    """
    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:
    """Set the direction the mobject's colors lighten toward, which its gradients
    run along too.

    Args:
        direction: The direction, copied as a value without changing the
            caller's array.
        family: Whether its whole family gets it, or the mobject alone.
    """
    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:
    """Set how the strokes of the path and its family end, at each end they show:
    an open path's ends, a reveal's moving end, each dash's ends.

    A two-dimensional scene draws the caps; a three-dimensional scene ends every
    stroke flat (see [CapStyleType][manimgx.CapStyleType]).

    Args:
        cap_style: The cap: round, butt or square.
    """
    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:
    """Set the mobject's place in the drawing order: a higher z-index is drawn over
    a lower one, anywhere in the scene.

    Mobjects of an equal z-index are drawn in the scene's order: the ones added
    later over the ones added earlier, and a mobject's submobjects each over those
    before it. Every mobject's z-index is 0 unless set.

    Args:
        z_index_value: The z-index.
        family: Whether its whole family gets it, or the mobject alone (which orders
            only its own points).

    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:
    """Put a rectangle behind the mobject, to set it off from whatever is behind it:
    a [BackgroundRectangle][manimgx.BackgroundRectangle] around it, added as its
    first submobject.

    The rectangle moves with the mobject; it is the mobject's
    [background_rectangle][manimgx.Mobject.background_rectangle].

    Args:
        color: The rectangle's color; None for the scene's background color.
        opacity: The rectangle's opacity, from 0 to 1 (default 0.75).
        **kwargs: [Background keywords][manimgx.mobject.BackgroundOptions]: its
            margin, corners and outline.

    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:
    """Change the defaults of the class's constructor keywords, for every mobject of
    the class made from then on; with none given, restore them.

    After `Text.set_default(font_size=100)`, a `Text` is 100 points unless it is
    made with another size. The keywords are checked when a mobject is made.

    Changing or restoring defaults discards remembered constructions. Existing
    mobjects keep their state; later construction reads the current defaults.

    Repeated calls replace this class's keyword defaults. Reset restores its
    original constructor, or normal inheritance if it had no constructor of its own.
    The defaults are applied when a mobject is made, to the constructor then in
    force: the class's own, or the next one in the made mobject's class's order (so a
    parent's later defaults reach a configured child, and a configured mixin calls the
    class after it in a subclass's order).

    Args:
        **kwargs: Keywords of the class's constructor, with their new defaults.
    """
    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()