坐标轴¶

def coords_to_point(self, *coords: Coordinates) -> npt.NDArray[np.float64]:
    """将坐标轴上的坐标转换为场景的点，或将数组转换为点。

    `c2p` 是其简写名，`axes @ (x, y)` 是其最简写名。超出坐标轴末端的坐标位于延伸的坐标轴上；缺失的坐标在坐标轴交叉处（`c2p(x)` 在 x 轴上）。给定每个坐标轴一个任意形状的数组（也包括网格），它一次性转换它们全部。

    Args:
        *coords: 坐标，每个坐标轴一个，按顺序：数字，或同形状的数组。

    Returns:
        点，在场景坐标系中；对于数组，为点，坐标在前（3，然后数组的形状）。

    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]:
    """将场景的点转换为其在坐标轴上的坐标，或将点转换为它们的坐标。

    `p2c` 是其简写名。每个坐标是坐标轴在该点向其投影处的数字：对于垂直坐标轴，是 [coords_to_point][manimgx.Axes.coords_to_point] 的反函数。

    Args:
        point: 点，在场景坐标系中；或 (n, 3) 的点数组。

    Returns:
        坐标，每个坐标轴一个；对于 n 个点，为 n 行坐标的数组。
    """
    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]:
    """将坐标轴上的极坐标转换为场景的点。

    `pr2pt` 是其简写名。该点位于坐标（`radius` cos `azimuth`、`radius` sin `azimuth`）处。

    Args:
        radius: 到原点的距离，以坐标轴的单位计。
        azimuth: 从正 x 轴起的角度，以弧度计，逆时针方向。

    Returns:
        点，在场景坐标系中。
    """
    return self.coords_to_point(radius * np.cos(azimuth), radius * np.sin(azimuth))

def get_origin(self) -> Point3D:
    """坐标 (0, 0) 的点：坐标轴交叉处（若其范围包含 0）。

    Returns:
        点，在场景坐标系中。
    """
    return self.coords_to_point(0, 0)

def get_x_unit_size(self) -> float:
    """x 轴一个单位的长度。

    Returns:
        长度，以场景单位计。
    """
    return self.get_x_axis().get_unit_size()

def get_y_unit_size(self) -> float:
    """y 轴一个单位的长度。

    Returns:
        长度，以场景单位计。
    """
    return self.get_y_axis().get_unit_size()

def get_x_axis(self) -> NumberLine:
    """x 轴。

    Returns:
        该坐标轴，一个 [NumberLine][manimgx.NumberLine]。
    """
    return self.get_axis(0)

def get_y_axis(self) -> NumberLine:
    """y 轴。

    Returns:
        该坐标轴，一个 [NumberLine][manimgx.NumberLine]。
    """
    return self.get_axis(1)

def get_z_axis(self) -> NumberLine:
    """三维坐标轴的 z 轴。

    Returns:
        该坐标轴，一个 [NumberLine][manimgx.NumberLine]。
    """
    return self.get_axis(2)

def get_axis(self, index: int) -> NumberLine:
    """其中一个坐标轴。

    Args:
        index: 坐标轴的索引：0 为 x，1 为 y，2 为 z。

    Returns:
        该坐标轴，一个 [NumberLine][manimgx.NumberLine]。
    """
    return self.get_axes()[index]

def get_axes(self) -> Group[NumberLine]:
    """坐标轴：x 轴、y 轴（3D 中还有 z 轴）。

    Returns:
        坐标轴的组，每个是一个 [NumberLine][manimgx.NumberLine]。
    """
    return self.axes

def add_coordinates(
    self,
    *axes_numbers: Iterable[float] | Mapping[float, Label] | None,
    **kwargs: Unpack[DecimalNumberOptions],
) -> Self:
    """为坐标轴编号：在其刻度处、在给定值处，或按值给标签。

    每个坐标轴给一个参数，按顺序：None 在刻度处为坐标轴编号，但不含 0（对数坐标轴上为幂：10²、10³、…）；值在这些值处为坐标轴编号；从值到标签（字符串、数字或已排版的 mobject）的字典将每个标签放在其值旁（参见 [add_labels][manimgx.NumberLine.add_labels]）。不带参数时，每个坐标轴在其刻度处编号。数字添加到坐标轴，并保留，每个坐标轴一个组，作为坐标轴的 `coordinate_labels`。

    Args:
        *axes_numbers: 每个坐标轴上写什么，按顺序：None、值或按值的标签；最后一个参数之后的坐标轴什么也不写。
        **kwargs: 数字的 [数字关键字][manimgx.DecimalNumber]：`font_size`、`num_decimal_places`、`color`、…（按值的标签仅用 `font_size`）。

    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:
    """为每个坐标轴制作标签，在其末端处，按 [get_x_axis_label][manimgx.Axes.get_x_axis_label] 和 [get_y_axis_label][manimgx.Axes.get_y_axis_label] 的放置方式。

    Args:
        x_label: x 轴的标签：字符串或数字，按数学排版，或 mobject。
        y_label: y 轴的标签，同上。

    Returns:
        标签的新组，保留为坐标轴的 `axis_labels`；未添加到坐标轴。

    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:
    """为 x 轴制作标签，在其末端处。

    字符串或数字用坐标轴的 `label_constructor` 排版（默认按数学排版，用 [MathTex][manimgx.MathTex]）；mobject 按原样使用。标签放在坐标轴的某个角旁，朝 `direction` 方向，然后若在屏幕外则移回屏幕上。

    Args:
        label: 标签：字符串、数字或 mobject。
        edge: 标签所放的坐标轴的角，作为方向：UR，即右上角，在其末端处。
        direction: 标签从该角放置的方向。
        buff: 角与标签之间的间距，以场景单位计。

    Returns:
        标签，未添加到坐标轴。
    """
    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:
    """为 y 轴制作标签，在其末端处。

    字符串或数字用坐标轴的 `label_constructor` 排版（默认按数学排版，用 [MathTex][manimgx.MathTex]）；mobject 按原样使用。标签放在坐标轴的某个角旁，朝 `direction` 方向，然后若在屏幕外则移回屏幕上。

    Args:
        label: 标签：字符串、数字或 mobject。
        edge: 标签所放的坐标轴的角，作为方向：UR，即右上角，在其末端处。
        direction: 标签从该角放置的方向：默认向上向右。
        buff: 角与标签之间的间距，以场景单位计。

    Returns:
        标签，未添加到坐标轴。
    """
    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:
    """制作从 x 轴向上（或向下）到点的线：虚线，未设置样式时为白色细线。

    Args:
        point: 点，在场景坐标系中。
        **kwargs: [坐标轴线关键字][manimgx.mobjects.plotting.AxisLine]：
            线的类、关键字、`color` 和 `stroke_width`。

    Returns:
        一条新的线，未添加到坐标轴。
    """
    return self.get_line_from_axis_to_point(0, point, **kwargs)

def get_horizontal_line(
    self, point: Point3DLike, **kwargs: Unpack[AxisLine]
) -> Line:
    """制作从 y 轴横跨到点的线：虚线，未设置样式时为白色细线。

    Args:
        point: 点，在场景坐标系中。
        **kwargs: [坐标轴线关键字][manimgx.mobjects.plotting.AxisLine]：
            线的类、关键字、`color` 和 `stroke_width`。

    Returns:
        一条新的线，未添加到坐标轴。
    """
    return self.get_line_from_axis_to_point(1, point, **kwargs)

def get_lines_to_point(
    self, point: Point3DLike, **kwargs: Unpack[AxisLine]
) -> VGroup:
    """制作从两个坐标轴到点的线：从 y 轴的 [水平线][manimgx.Axes.get_horizontal_line]，然后从 x 轴的 [垂直线][manimgx.Axes.get_vertical_line]。

    Args:
        point: 点，在场景坐标系中。
        **kwargs: 两条线的 [坐标轴线关键字][manimgx.mobjects.plotting.AxisLine]。

    Returns:
        两条线的新组，未添加到坐标轴。

    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),
    )