Ready-made scenes¶

def add_plane(
    self, animate: bool = False, **kwargs: Unpack[NumberPlaneOptions]
) -> NumberPlane:
    """Add a number plane to the scene.

    Args:
        animate: Whether to draw it in ([`Create`][manimgx.Create], its lines
            overlapping).
        **kwargs: [Number plane keywords][manimgx.NumberPlane].

    Returns:
        The plane. It is not the scene's [`plane`][manimgx.VectorScene.plane] unless
        assigned to it.
    """
    plane = NumberPlane(**kwargs)
    if animate:
        self.play(Create(plane, lag_ratio=0.5))
    self.add(plane)
    return plane

def add_axes(self, animate: bool = False, color: Colors = WHITE) -> Axes:
    """Add axes to the scene, one scene unit to one unit.

    Args:
        animate: Whether to draw them in ([`Create`][manimgx.Create]).
        color: Their color.

    Returns:
        The axes.
    """
    axes = Axes(color=color, axis_config={"unit_size": 1})
    if animate:
        self.play(Create(axes))
    self.add(axes)
    return axes

def get_vector(
    self, numerical_vector: Vector3DLike, **kwargs: Unpack[ArrowTips]
) -> Arrow:
    """Make an arrow from the origin of the scene's plane to a point given in its
    coordinates.

    Args:
        numerical_vector: The point's coordinates on
            [`plane`][manimgx.VectorScene.plane]: x and y (a z is ignored).
        **kwargs: [Arrow keywords][manimgx.Arrow].

    Returns:
        A new arrow, not added to the scene.
    """
    x, y = np.asarray(numerical_vector, dtype=float)[:2]
    return Arrow(
        self.plane.coords_to_point(0, 0),
        self.plane.coords_to_point(x, y),
        buff=0,
        **kwargs,
    )

def add_vector(
    self,
    vector: Arrow | Vector3DLike,
    color: Colors = PURE_YELLOW,
    animate: bool | None = None,
    **kwargs: Unpack[ArrowTipsBase],
) -> Arrow:
    """Add a vector to the scene: the arrow given, or a [Vector][manimgx.Vector] from
    the origin to the coordinates given.

    It is shown growing from the origin ([GrowArrow][manimgx.GrowArrow]) if `animate`
    says so, or else if the scene's `grows_vectors` does (a vector scene's does, a
    transformation scene's doesn't); then the scene takes it up: a
    [LinearTransformationScene][manimgx.LinearTransformationScene] moves it with the
    plane.

    Args:
        vector: An arrow, or the coordinates of a vector's tip, in scene units.
        color: The vector's color, when it is made from coordinates.
        animate: Whether it grows in a play; None for the scene's `grows_vectors`.
        **kwargs: [Arrow keywords][manimgx.mobjects.shapes.ArrowTipsBase] for
            a vector made from coordinates.

    Returns:
        The arrow.
    """
    if not isinstance(vector, Arrow):
        vector = Vector(np.asarray(vector, dtype=float), color=color, **kwargs)
    if self.grows_vectors if animate is None else animate:
        self.play(GrowArrow(vector))
    self.add(vector)
    self.added_vector(vector)
    return vector

def write_vector_coordinates(
    self, vector: Vector, **kwargs: Unpack[MatrixOptions]
) -> Matrix:
    """Write a vector's coordinates beside its tip, as a column (its
    `coordinate_label`), in a play of [`Write`][manimgx.Write].

    Args:
        **kwargs: [Matrix keywords][manimgx.mobjects.grid.MatrixOptions] for the
            column.

    Returns:
        The column.
    """
    coords = vector.coordinate_label(**kwargs)
    self.play(Write(coords))
    return coords

def get_basis_vectors(
    self, i_hat_color: Colors = X_COLOR, j_hat_color: Colors = Y_COLOR
) -> VGroup:
    """Make the basis vectors î and ĵ: arrows from the origin to (1, 0) and (0, 1),
    in scene units.

    Args:
        i_hat_color: The color of î.
        j_hat_color: The color of ĵ.

    Returns:
        A new group of the two, î first.
    """
    return VGroup(
        *(
            Vector(
                np.asarray(vect, dtype=float),
                color=color,
                stroke_width=self.basis_vector_stroke_width,
            )
            for vect, color in [([1, 0], i_hat_color), ([0, 1], j_hat_color)]
        )
    )

def get_basis_vector_labels(self, **kwargs: Unpack[LabelPlacement]) -> VGroup:
    """Make labels for the basis vectors: î and ĵ, in the colors of the x and y axes
    (green and red).

    Args:
        **kwargs: [Label placement keywords][manimgx.scene.LabelPlacement].

    Returns:
        A new group of the two labels, î's first.
    """
    i_hat, j_hat = self.get_basis_vectors().submobjects
    return VGroup(
        *(
            self.get_vector_label(
                vect, label, color=color, label_scale_factor=1, **kwargs
            )
            for vect, label, color in [
                (i_hat, "\\hat{\\imath}", X_COLOR),
                (j_hat, "\\hat{\\jmath}", Y_COLOR),
            ]
            if isinstance(vect, Vector)
        )
    )

def get_vector_label(
    self,
    vector: Vector,
    label: ManimTextLabel | str,
    at_tip: bool = False,
    direction: Literal["left", "right"] = "left",
    rotate: bool = False,
    color: ParsableManimColor | None = None,
    label_scale_factor: float = LARGE_BUFF - 0.2,
) -> ManimTextLabel:
    r"""Make a label for a vector: beside its middle, on its left or its right, or
    beyond its tip.

    A string is typeset as LaTeX, a single letter as a bold vector
    (`\vec{\textbf{v}}`), in the vector's color. The label gets a background
    rectangle, to be read over the lines under it.

    Args:
        vector: The vector, from the origin.
        label: The label: a mobject, or LaTeX.
        at_tip: Whether it goes beyond the vector's tip, rather than beside its
            middle.
        direction: Which side of the vector it goes on, looking along the vector.
        rotate: Whether it turns with the vector, rather than staying upright.
        color: Its color, when it is made from a string; None for the vector's.
        label_scale_factor: How much it is scaled.

    Returns:
        The label, not added to the scene.
    """
    if isinstance(label, str):
        if len(label) == 1:
            label = f"\\vec{{\\textbf{{{label}}}}}"
        label = MathTex(label)
        label.set_color(vector.get_color() if color is None else color)
    label.scale(label_scale_factor)
    label.add_background_rectangle()
    if at_tip:
        vect = vector.get_vector()
        label.next_to(
            vector.get_end(), vect / np.linalg.norm(vect), buff=SMALL_BUFF
        )
    else:
        angle = vector.get_angle()
        if not rotate:
            label.rotate(-angle, about_point=ORIGIN)
        if direction == "left":
            label.shift(-np.asarray(label.get_bottom()) + 0.1 * UP)
        else:
            label.shift(-np.asarray(label.get_top()) + 0.1 * DOWN)
        label.rotate(angle, about_point=ORIGIN)
        label.shift((vector.get_end() - vector.get_start()) / 2)
    return label

def label_vector(
    self,
    vector: Vector,
    label: ManimTextLabel | str,
    animate: bool = True,
    **kwargs: Unpack[VectorLabelOptions],
) -> ManimTextLabel:
    """Label a vector, and add the label to the scene (see
    [`get_vector_label`][manimgx.VectorScene.get_vector_label]).

    Args:
        vector: The vector, from the origin.
        label: The label: a mobject, or LaTeX.
        animate: Whether to write it in ([`Write`][manimgx.Write]).
        **kwargs: [Vector label keywords][manimgx.scene.VectorLabelOptions].

    Returns:
        The label.
    """
    mathtex_label = self.get_vector_label(vector, label, **kwargs)
    if animate:
        self.play(Write(mathtex_label, run_time=1))
    self.add(mathtex_label)
    return mathtex_label

def vector_to_coords(
    self,
    vector: Vector | Vector3DLike,
    integer_labels: bool = True,
    clean_up: bool = True,
) -> tuple[Matrix, Line, Line]:
    """Show how a vector gives its coordinates, in a series of plays.

    The vector (drawn first, when it is given by its coordinates) gets a line along
    x and a line up to its tip, each written with its coordinate; the coordinates
    then move into a column beside its tip.

    Args:
        vector: The vector, from the origin, or its coordinates.
        integer_labels: Whether the coordinates are rounded to integers.
        clean_up: Whether the scene is left holding what it held before, at the end.

    Returns:
        The column of coordinates, the line along x and the line up to the tip.
    """
    starting_mobjects = list(self.mobjects)
    show_creation = not isinstance(vector, Vector)
    arrow = vector if isinstance(vector, Vector) else Vector(vector)
    end = arrow.get_end()[:2]
    array = arrow.coordinate_label(integer_labels=integer_labels)
    x_line = Line(ORIGIN, end[0] * RIGHT)
    y_line = Line(x_line.get_end(), arrow.get_end())
    x_line.set_color(X_COLOR)
    y_line.set_color(Y_COLOR)
    x_coord, y_coord = array.get_entries().submobjects[:2]
    x_coord_start = self.position_x_coordinate(x_coord.copy(), x_line, end)
    y_coord_start = self.position_y_coordinate(y_coord.copy(), y_line, end)
    brackets = array.get_brackets()
    if show_creation:
        self.play(Create(arrow))
    self.play(Create(x_line), Write(x_coord_start), run_time=1)
    self.play(Create(y_line), Write(y_coord_start), run_time=1)
    self.wait()
    self.play(
        Transform(x_coord_start, x_coord, lag_ratio=0),
        Transform(y_coord_start, y_coord, lag_ratio=0),
        Write(brackets, run_time=1),
    )
    self.wait()
    self.remove(x_coord_start, y_coord_start, brackets)
    self.add(array)
    if clean_up:
        self.clear()
        self.add(*starting_mobjects)
    return array, x_line, y_line

def setup(self) -> None:
    """Lay out the planes and the basis vectors, and add them to the scene.

    [`render`][manimgx.Scene.render] calls it before `construct`; it acts once. A
    subclass that overrides it calls this one first.
    """
    if hasattr(self, "has_already_setup"):
        return
    self.has_already_setup = True
    self.background_mobjects: list[Mobject] = []
    self.foreground_mobjects: list[Mobject] = []
    self.transformable_mobjects: list[Mobject] = []
    self.moving_vectors: list[Mobject] = []
    self.transformable_labels: list[_TransformableLabel] = []
    self.moving_mobjects: list[Mobject] = []
    self.background_plane = NumberPlane(**self.background_plane_kwargs)
    if self.show_coordinates:
        self.background_plane.add_coordinates()
    if self.include_background_plane:
        self.add_background_mobject(self.background_plane)
    if self.include_foreground_plane:
        self.plane = NumberPlane(**self.foreground_plane_kwargs)
        self.add_transformable_mobject(self.plane)
    if self.show_basis_vectors:
        self.basis_vectors = self.get_basis_vectors(
            i_hat_color=self.i_hat_color, j_hat_color=self.j_hat_color
        )
        self.moving_vectors += list(self.basis_vectors)
        self.i_hat, self.j_hat = self.basis_vectors
        self.add(self.basis_vectors)

def add_background_mobject(self, *mobjects: Mobject) -> None:
    """Add mobjects that the transformations leave where they are, as they leave the
    background plane.
    """
    self.add_special_mobjects(self.background_mobjects, *mobjects)

def add_foreground_mobject(self, *mobjects: Mobject) -> Self:
    """Add mobjects that stay in front: drawn over everything else, and left where
    they are by the transformations.
    """
    self.add_special_mobjects(self.foreground_mobjects, *mobjects)
    return self

def add_transformable_mobject(self, *mobjects: Mobject) -> None:
    """Add mobjects that the transformations move point by point, as they move the
    plane.
    """
    self.add_special_mobjects(self.transformable_mobjects, *mobjects)

def add_moving_mobject(
    self, mobject: Mobject, target_mobject: Mobject | None = None
) -> None:
    """Add a mobject that the transformations move whole, its shape unchanged: to
    where they take its center.

    Args:
        target_mobject: What it becomes as it moves, placed where the transformation
            takes its center; None for itself.
    """
    mobject.target = target_mobject
    self.add_special_mobjects(self.moving_mobjects, mobject)

def get_ghost_vectors(self) -> VGroup:
    """The faded copies the transformations left of what they moved whole, where it
    was, with `leave_ghost_vectors`.

    Returns:
        The group of them.
    """
    return self.ghost_vectors

def get_unit_square(
    self, color: Colors = PURE_YELLOW, opacity: float = 0.3, stroke_width: float = 3
) -> Rectangle:
    """Make a rectangle over the plane's unit square: from its origin, one unit of x
    wide and one unit of y tall.

    Args:
        color: The color of its fill and its stroke.
        opacity: Its fill's opacity, from 0 to 1.
        stroke_width: Its stroke's width, in hundredths of a scene unit.

    Returns:
        A new rectangle, also kept as the scene's `square`.
    """
    square = self.square = Rectangle(
        color=color,
        width=self.plane.get_x_unit_size(),
        height=self.plane.get_y_unit_size(),
        stroke_color=color,
        stroke_width=stroke_width,
        fill_color=color,
        fill_opacity=opacity,
    )
    square.move_to(self.plane.coords_to_point(0, 0), DL)
    return square

def add_unit_square(
    self, animate: bool = False, **kwargs: Unpack[UnitSquareOptions]
) -> Self:
    """Add the plane's unit square, which the transformations move with the plane:
    its area shows how they scale areas.

    The moving vectors are then brought to the front, over it.

    Args:
        animate: Whether to draw it in: its border, then its fill.
        **kwargs: [Unit square keywords][manimgx.scene.UnitSquareOptions].
    """
    square = self.get_unit_square(**kwargs)
    if animate:
        self.play(
            DrawBorderThenFill(square), Animation(Group(*self.moving_vectors))
        )
    self.add_transformable_mobject(square)
    self.bring_to_front(*self.moving_vectors)
    self.square = square
    return self

def write_vector_coordinates(
    self, vector: Vector, **kwargs: Unpack[MatrixOptions]
) -> Matrix:
    """Write a vector's coordinates beside its tip, as a column that stays in front,
    where it is, through the transformations.

    Args:
        **kwargs: [Matrix keywords][manimgx.mobjects.grid.MatrixOptions] for the
            column.

    Returns:
        The column.
    """
    coords = super().write_vector_coordinates(vector, **kwargs)
    self.add_foreground_mobject(coords)
    return coords

def add_transformable_label(
    self,
    vector: Vector,
    label: ManimTextLabel | str,
    transformation_name: str | ManimTextLabel = "L",
    new_label: str | ManimTextLabel | None = None,
    *,
    animate: bool = True,
    **kwargs: Unpack[VectorLabelOptions],
) -> ManimTextLabel:
    """Label a vector with a label that the transformations carry along and rewrite.

    After a transformation, the label sits by the vector where it went, and reads
    `new_label`, or else the label in the transformation's name: `L(v)` for a label
    `v`.

    Args:
        vector: The vector, from the origin.
        label: The label: a mobject, or LaTeX (see
            [`get_vector_label`][manimgx.VectorScene.get_vector_label]).
        transformation_name: The name of the transformation.
        new_label: What the label reads after a transformation; None for the
            transformation's name around it.
        animate: Whether to write it in.
        **kwargs: [Vector label keywords][manimgx.scene.VectorLabelOptions].

    Returns:
        The label.
    """
    label_mob = self.label_vector(vector, label, animate, **kwargs)
    if new_label:
        target_text: str | ManimTextLabel = new_label
    else:
        written = (
            label_mob.tex_string
            if isinstance(label_mob, (MathTex, SingleStringMathTex))
            else str(label)
        )
        target_text = f"{transformation_name}({written})"
    self.transformable_labels.append(
        _TransformableLabel(label_mob, vector, target_text, kwargs)
    )
    return label_mob

def add_title(
    self, title: str | Mobject, scale_factor: float = 1.5, animate: bool = False
) -> Self:
    """Add a title at the top of the frame, in front and still, on a background
    rectangle.

    Args:
        title: The title: a mobject, or text, typeset as [`Tex`][manimgx.Tex].
        scale_factor: How much text is scaled.
        animate: Whether to write it in.
    """
    if not isinstance(title, Mobject):
        title = Tex(title).scale(scale_factor)
    title.to_edge(UP)
    title.add_background_rectangle()
    if animate:
        self.play(Write(title))
    self.add_foreground_mobject(title)
    self.title = title
    return self

def apply_matrix(
    self, matrix: npt.ArrayLike, **kwargs: Unpack[TransformOptions]
) -> None:
    """Apply a matrix to the plane and to everything on it, in one play.

    Everything the transformations move goes where the matrix takes it (see
    [`apply_function`][manimgx.LinearTransformationScene.apply_function]). Unless a
    `path_arc` is given, the points travel along arcs that turn through the mean of
    the angles the matrix turns î and ĵ through.

    Args:
        matrix: A 2 × 2 matrix, which acts on x and y, or a 3 × 3 one: its columns
            are where it takes î and ĵ.
        **kwargs: [Transform options][manimgx.animation.transform.TransformOptions] for
            every animation of the play (3 seconds long unless given a `run_time`).
    """
    self.apply_transposed_matrix(np.array(matrix).T, **kwargs)

def apply_inverse(
    self, matrix: npt.ArrayLike, **kwargs: Unpack[TransformOptions]
) -> None:
    """Apply the inverse of a matrix to the plane and to everything on it: undo
    [`apply_matrix`][manimgx.LinearTransformationScene.apply_matrix] of the same
    matrix.

    Args:
        matrix: The matrix, 2 × 2 or 3 × 3, which must be invertible.
        **kwargs: [Transform options][manimgx.animation.transform.TransformOptions] for
            every animation of the play.
    """
    self.apply_matrix(np.linalg.inv(np.asarray(matrix, dtype=float)), **kwargs)

def apply_transposed_matrix(
    self, transposed_matrix: npt.ArrayLike, **kwargs: Unpack[TransformOptions]
) -> None:
    """Apply a matrix, given by its transpose, to the plane and to everything on it:
    as [`apply_matrix`][manimgx.LinearTransformationScene.apply_matrix] does.

    Args:
        transposed_matrix: The matrix's transpose, whose rows are where the matrix
            takes î and ĵ.
        **kwargs: [Transform options][manimgx.animation.transform.TransformOptions] for
            every animation of the play.
    """
    func = self.get_transposed_matrix_transformation(transposed_matrix)
    if "path_arc" not in kwargs:
        kwargs["path_arc"] = float(
            np.mean(
                [
                    angle_of_vector(func(RIGHT)),
                    angle_of_vector(func(UP)) - np.pi / 2,
                ]
            )
        )
    self.apply_function(func, **kwargs)

def apply_inverse_transpose(
    self, t_matrix: npt.ArrayLike, **kwargs: Unpack[TransformOptions]
) -> None:
    """Apply the inverse of a matrix's transpose to the plane and to everything on
    it.

    Args:
        t_matrix: The matrix, 2 × 2 or 3 × 3, which must be invertible.
        **kwargs: [Transform options][manimgx.animation.transform.TransformOptions] for
            every animation of the play.
    """
    t_inv = np.linalg.inv(np.array(t_matrix, dtype=float).T).T
    self.apply_transposed_matrix(t_inv, **kwargs)

def apply_nonlinear_transformation(
    self,
    function: Callable[[np.ndarray], np.ndarray],
    **kwargs: Unpack[TransformOptions],
) -> None:
    """Apply a function that need not be linear to the plane and to everything on
    it.

    The plane's lines are first divided into many curves, so that they can bend (see
    [`apply_function`][manimgx.LinearTransformationScene.apply_function]).

    Args:
        function: The function, from a point to its image, in scene coordinates.
        **kwargs: [Transform options][manimgx.animation.transform.TransformOptions] for
            every animation of the play.
    """
    self.plane.prepare_for_nonlinear_transform()
    self.apply_function(function, **kwargs)

def apply_function(
    self,
    function: MappingFunction,
    added_anims: Sequence[Animation] | None = None,
    **kwargs: Unpack[TransformOptions],
) -> None:
    """Apply a function to the plane and to everything on it, in one play.

    Every point of the transformable mobjects goes where `function` takes it; each
    vector is redrawn to where its tip goes, and its transformable label follows it;
    each moving mobject moves whole to where its center goes; the foreground
    mobjects stay where they are. With `leave_ghost_vectors`, faded copies of what
    moves whole are left behind.

    Args:
        function: The function, from a point to its image, in scene coordinates.
        added_anims: Animations to play along.
        **kwargs: [Transform options][manimgx.animation.transform.TransformOptions] for
            every animation of the play (3 seconds long unless given a `run_time`).
    """
    kwargs.setdefault("run_time", 3)
    anims: list[Animation] = [
        *(
            ApplyPointwiseFunction(function, t_mob)
            for t_mob in self.transformable_mobjects
        ),
        self.get_vector_movement(function),
        self.get_transformable_label_movement(),
        self.get_moving_mobject_movement(function),
        *(Animation(f_mob) for f_mob in self.foreground_mobjects),
        *(added_anims or ()),
    ]
    self.play(*anims, **kwargs)