Axes¶

def coords_to_point(self, *coords: Coordinates) -> npt.NDArray[np.float64]:
    """Convert coordinates on the axes to a point of the scene, or arrays of them to
    points.

    `c2p` is its short name, and `axes @ (x, y)` its shortest. Coordinates past the
    ends of the axes are on the axes extended; a missing one is where the axes
    cross (`c2p(x)` is on the x-axis). Given an array per axis, of any shape (a
    grid too), it converts them all at once.

    Args:
        *coords: The coordinates, one per axis, in order: numbers, or arrays of one
            shape.

    Returns:
        The point, in scene coordinates; for arrays, the points, with the
        coordinates first (3, then the arrays' shape).

    Examples:
        ```python
        import manimgx as m


        class AxesCoordsToPointExample(m.Scene):
            def construct(self) -> None:
                axes = m.Axes(
                    x_range=[0, 6], y_range=[0, 4], x_length=10, y_length=6
                )
                dot = m.Dot(axes.c2p(1, 1), radius=0.15, color=m.YELLOW)
                self.add(axes.add_coordinates(), dot)
                self.play(dot.animate.move_to(axes.c2p(5, 3)))
                self.play(dot.animate.move_to(axes @ (3, 0.5)))
        ```
    """
    origin = self.x_axis.number_to_point(
        _origin_shift([self.x_axis.x_min, self.x_axis.x_max])
    )
    points = self.x_axis.number_to_point(np.asarray(coords[0], dtype=float))
    for axis, nums in zip(self.axes.submobjects[1:], coords[1:], strict=False):
        points = (
            points + axis.number_to_point(np.asarray(nums, dtype=float)) - origin
        )
    return points if points.ndim == 1 else np.moveaxis(points, -1, 0)

def point_to_coords(
    self, point: Point3DLike | Point3DLike_Array
) -> npt.NDArray[np.float64]:
    """Convert a point of the scene to its coordinates on the axes, or points to
    theirs.

    `p2c` is its short name. Each coordinate is the axis's number at the point's
    projection onto it: for perpendicular axes, the inverse of
    [coords_to_point][manimgx.Axes.coords_to_point].

    Args:
        point: The point, in scene coordinates; or an (n, 3) array of points.

    Returns:
        The coordinates, one per axis; for n points, an array of n rows of them.
    """
    array = np.asarray(point, dtype=float)
    result = np.asarray([axis.point_to_number(array) for axis in self.axes])
    return result.T if array.ndim == 2 else result

def polar_to_point(self, radius: float, azimuth: float) -> npt.NDArray[np.float64]:
    """Convert polar coordinates on the axes to a point of the scene.

    `pr2pt` is its short name. The point is at the coordinates
    (`radius` cos `azimuth`, `radius` sin `azimuth`).

    Args:
        radius: The distance from the origin, in the axes' units.
        azimuth: The angle from the positive x-axis, in radians, counterclockwise.

    Returns:
        The point, in scene coordinates.
    """
    return self.coords_to_point(radius * np.cos(azimuth), radius * np.sin(azimuth))

def get_origin(self) -> Point3D:
    """The point of the coordinates (0, 0): where the axes cross, if their ranges
    contain 0.

    Returns:
        The point, in scene coordinates.
    """
    return self.coords_to_point(0, 0)

def get_x_unit_size(self) -> float:
    """The length of one unit of the x-axis.

    Returns:
        The length, in scene units.
    """
    return self.get_x_axis().get_unit_size()

def get_y_unit_size(self) -> float:
    """The length of one unit of the y-axis.

    Returns:
        The length, in scene units.
    """
    return self.get_y_axis().get_unit_size()

def get_x_axis(self) -> NumberLine:
    """The x-axis.

    Returns:
        The axis, a [NumberLine][manimgx.NumberLine].
    """
    return self.get_axis(0)

def get_y_axis(self) -> NumberLine:
    """The y-axis.

    Returns:
        The axis, a [NumberLine][manimgx.NumberLine].
    """
    return self.get_axis(1)

def get_z_axis(self) -> NumberLine:
    """The z-axis, of three-dimensional axes.

    Returns:
        The axis, a [NumberLine][manimgx.NumberLine].
    """
    return self.get_axis(2)

def get_axis(self, index: int) -> NumberLine:
    """One of the axes.

    Args:
        index: The axis's index: 0 for x, 1 for y, 2 for z.

    Returns:
        The axis, a [NumberLine][manimgx.NumberLine].
    """
    return self.get_axes()[index]

def get_axes(self) -> Group[NumberLine]:
    """The axes: the x-axis, the y-axis (and the z-axis, in 3D).

    Returns:
        The group of the axes, each a [NumberLine][manimgx.NumberLine].
    """
    return self.axes

def add_coordinates(
    self,
    *axes_numbers: Iterable[float] | Mapping[float, Label] | None,
    **kwargs: Unpack[DecimalNumberOptions],
) -> Self:
    """Number the axes: at their ticks, at the values given, or with labels by
    value.

    Give one argument per axis, in order: None numbers the axis at its ticks, but
    0 (on a logarithmic axis, as powers: 10², 10³, …); values number it at those
    values; a dictionary from values to labels (strings, numbers or typeset
    mobjects) puts each label by its value (see
    [add_labels][manimgx.NumberLine.add_labels]). Without arguments, every axis is
    numbered at its ticks. The numbers are added to the axes, and kept, one group
    per axis, as the axes' `coordinate_labels`.

    Args:
        *axes_numbers: What to write on each axis, in order: None, values, or
            labels by value; the axes past the last argument get nothing.
        **kwargs: [Number keywords][manimgx.DecimalNumber]
            for the numbers: `font_size`, `num_decimal_places`, `color`, … (only
            `font_size`, for labels by value).

    Examples:
        ```python
        import manimgx as m


        class AxesAddCoordinatesExample(m.Scene):
            def construct(self) -> None:
                axes = m.Axes(
                    x_range=[0, 5], y_range=[0, 1, 0.25], x_length=10, y_length=6
                )
                axes.add_coordinates(
                    {1: "one", 2: "two", 3: "three", 4: "four"}, None, font_size=30
                )
                self.add(axes)
        ```
    """
    self.coordinate_labels = VGroup()
    for axis, values in zip(
        self.axes, axes_numbers or (None,) * self.dimension, strict=False
    ):
        if isinstance(values, Mapping):
            axis.add_labels(values, font_size=kwargs.get("font_size"))
            labels = axis.labels
        elif values is None and axis.scaling.custom_labels:
            tick_range = axis.get_tick_range()
            axis.add_labels(
                dict(
                    zip(
                        tick_range,
                        axis.scaling.get_custom_labels(tick_range),
                        strict=True,
                    )
                )
            )
            labels = axis.labels
        else:
            axis.add_numbers(values, **kwargs)
            labels = axis.numbers
        self.coordinate_labels.add(labels)
    return self

def get_axis_labels(self, x_label: Label = "x", y_label: Label = "y") -> VGroup:
    """Make a label for each axis, by its end, as
    [get_x_axis_label][manimgx.Axes.get_x_axis_label] and
    [get_y_axis_label][manimgx.Axes.get_y_axis_label] place them.

    Args:
        x_label: The x-axis's label: a string or a number, typeset as math, or a
            mobject.
        y_label: The y-axis's label, likewise.

    Returns:
        A new group of the labels, kept as the axes' `axis_labels`; not added to
        the axes.

    Examples:
        ```python
        import manimgx as m


        class AxesGetAxisLabelsExample(m.Scene):
            def construct(self) -> None:
                axes = m.Axes(x_range=[0, 10], y_range=[0, 5], x_length=10)
                labels = axes.get_axis_labels(m.Tex("time"), m.Tex("height"))
                self.add(axes, labels)
        ```
    """
    self.axis_labels = VGroup(
        self.get_x_axis_label(x_label), self.get_y_axis_label(y_label)
    )
    return self.axis_labels

def get_x_axis_label(
    self,
    label: Label,
    edge: Vector3DLike = UR,
    direction: Vector3DLike = UR,
    buff: float = SMALL_BUFF,
) -> Mobject:
    """Make a label for the x-axis, by its end.

    A string or a number is typeset with the axes' `label_constructor` (as math,
    with [MathTex][manimgx.MathTex], by default); a mobject is used as it is. The
    label is put next to a corner of the axis, toward `direction`, then moved onto
    the screen if it is off it.

    Args:
        label: The label: a string, a number or a mobject.
        edge: The corner of the axis the label is put by, as a direction: UR, the
            upper right one, by its end.
        direction: The direction the label is put toward, from that corner.
        buff: The gap between the corner and the label, in scene units.

    Returns:
        The label, not added to the axes.
    """
    return self._get_axis_label(
        label, self.get_x_axis(), edge, direction, buff=buff
    )

def get_y_axis_label(
    self,
    label: Label,
    edge: Vector3DLike = UR,
    direction: Vector3DLike = UP * 0.5 + RIGHT,
    buff: float = SMALL_BUFF,
) -> Mobject:
    """Make a label for the y-axis, by its end.

    A string or a number is typeset with the axes' `label_constructor` (as math,
    with [MathTex][manimgx.MathTex], by default); a mobject is used as it is. The
    label is put next to a corner of the axis, toward `direction`, then moved onto
    the screen if it is off it.

    Args:
        label: The label: a string, a number or a mobject.
        edge: The corner of the axis the label is put by, as a direction: UR, the
            upper right one, by its end.
        direction: The direction the label is put toward, from that corner: by
            default up and to the right.
        buff: The gap between the corner and the label, in scene units.

    Returns:
        The label, not added to the axes.
    """
    return self._get_axis_label(
        label, self.get_y_axis(), edge, direction, buff=buff
    )

def get_vertical_line(self, point: Point3DLike, **kwargs: Unpack[AxisLine]) -> Line:
    """Make a line from the x-axis up (or down) to a point: dashed, white and thin
    unless styled.

    Args:
        point: The point, in scene coordinates.
        **kwargs: [Axis line keywords][manimgx.mobjects.plotting.AxisLine]:
            the line's class, keywords, `color` and `stroke_width`.

    Returns:
        A new line, not added to the axes.
    """
    return self.get_line_from_axis_to_point(0, point, **kwargs)

def get_horizontal_line(
    self, point: Point3DLike, **kwargs: Unpack[AxisLine]
) -> Line:
    """Make a line from the y-axis across to a point: dashed, white and thin unless
    styled.

    Args:
        point: The point, in scene coordinates.
        **kwargs: [Axis line keywords][manimgx.mobjects.plotting.AxisLine]:
            the line's class, keywords, `color` and `stroke_width`.

    Returns:
        A new line, not added to the axes.
    """
    return self.get_line_from_axis_to_point(1, point, **kwargs)

def get_lines_to_point(
    self, point: Point3DLike, **kwargs: Unpack[AxisLine]
) -> VGroup:
    """Make the lines from both axes to a point: the
    [horizontal][manimgx.Axes.get_horizontal_line] one from the y-axis, then the
    [vertical][manimgx.Axes.get_vertical_line] one from the x-axis.

    Args:
        point: The point, in scene coordinates.
        **kwargs: [Axis line keywords][manimgx.mobjects.plotting.AxisLine]
            for both lines.

    Returns:
        A new group of the two lines, not added to the axes.

    Examples:
        ```python
        import manimgx as m


        class AxesGetLinesToPointExample(m.Scene):
            def construct(self) -> None:
                axes = m.Axes(x_range=[0, 6], y_range=[0, 4], x_length=10)
                dot = m.Dot(axes.c2p(4, 3), radius=0.15, color=m.YELLOW)
                lines = axes.get_lines_to_point(dot.get_center(), color=m.BLUE)
                self.add(axes.add_coordinates(), dot)
                self.play(m.Create(lines))
        ```
    """
    return VGroup(
        self.get_horizontal_line(point, **kwargs),
        self.get_vertical_line(point, **kwargs),
    )