绘图¶

def plot(
    self,
    function: Callable[[float], float],
    x_range: Sequence[float] | None = None,
    use_vectorized: bool = False,
    colorscale: Colorscale | None = None,
    colorscale_axis: int = 1,
    **kwargs: Unpack[CurveOptions],
) -> ParametricFunction:
    """在坐标轴上以坐标轴坐标系绘制函数 y = f(x) 的图像。

    函数在 `x_range` 上采样，采样点平滑连接（参见 [ParametricFunction][manimgx.ParametricFunction]）；对数 x 轴上 x 在幂上运行。图像将函数保留为其 `underlying_function`，供处理图像的方法使用。带 `colorscale` 时，图像的描边是其值（y 或 x）颜色的从左到右渐变，在 `x_range` 的每一步处取值（未给出时每 0.01）。

    Args:
        function: 函数，从 x 到 y，在坐标轴坐标系中。
        x_range: 图像所跨越的 x 的范围，`[x_min, x_max]` 或
            `[x_min, x_max, x_step]`，函数每 `x_step` 采样一次；None
            表示 x 轴的范围。未给出步长时为 x 轴的十分之一。
        use_vectorized: `function` 是否一次性接收所有 x 值（作为数组）；无论如何都会先尝试用数组，若不接受则每个值调用一次。
        colorscale: 按值给图像上色的颜色：颜色在坐标轴范围内均匀分布，或 `(color, value)` 对，在之间混合；None 表示图像自身的颜色。
        colorscale_axis: 色阶所依据的值：1 为 y，0 为 x。
        **kwargs: [曲线关键字][manimgx.mobjects.plotting.CurveOptions]：
            `discontinuities`、`use_smoothing` 和样式关键字。

    Returns:
        一个新的 [ParametricFunction][manimgx.ParametricFunction]，未添加到坐标轴。

    Examples:
        ```python
        import numpy as np

        import manimgx as m


        class AxesPlotExample(m.Scene):
            def construct(self) -> None:
                axes = m.Axes(x_range=[-4, 4], y_range=[-2, 2], y_length=6)
                sine = axes.plot(np.sin, color=m.BLUE)
                parabola = axes.plot(
                    lambda x: x**2 - 1.5,
                    x_range=[-1.8, 1.8],
                    colorscale=[m.GREEN, m.YELLOW, m.RED],
                )
                self.add(axes)
                self.play(m.Create(sine), m.Create(parabola))
        ```
    """
    t_range = np.array(self.x_range, dtype=float)
    if x_range is not None:
        t_range[: len(x_range)] = x_range
    if x_range is None or len(x_range) < 3:
        t_range[2] /= self.num_sampled_graph_points_per_tick

    def point(t: float | np.ndarray) -> np.ndarray:
        """图像在 t 处的点——或数组中每个 t 处的点，一次调用映射完成。"""
        if isinstance(t, np.ndarray):
            return self.coords_to_point(t, sample(function, t))
        return self.coords_to_point(t, function(t))

    graph = ParametricFunction(
        point,
        t_range=t_range,
        scaling=self.x_axis.scaling,
        use_vectorized=use_vectorized,
        **kwargs,
    )
    graph.underlying_function = function
    if colorscale:
        resolution = (
            x_range[2] if x_range is not None and len(x_range) == 3 else 0.01
        )
        graph.set_stroke(
            self._colorscale(
                function, colorscale, colorscale_axis, t_range, resolution
            )
        )
        graph.set_sheen_direction(RIGHT)
    return graph

def plot_line_graph(
    self,
    x_values: Iterable[float],
    y_values: Iterable[float],
    z_values: Iterable[float] | None = None,
    line_color: ParsableManimColor = PURE_YELLOW,
    add_vertex_dots: bool = True,
    vertex_dot_radius: float = DEFAULT_DOT_RADIUS,
    vertex_dot_style: Style | None = None,
    **kwargs: Unpack[Style],
) -> VDict:
    """绘制折线图：过由其坐标给出的点的直线段，每个点处有一个点；未设置样式时为亮黄色（`PURE_YELLOW`），带白色点。空输入产生空图。

    Args:
        x_values: 点的 x 坐标。
        y_values: 点的 y 坐标，数量相同。
        z_values: 点的 z 坐标，在三维坐标轴上；None 表示 0。
        line_color: 线的颜色，除非关键字给出 `color`。
        add_vertex_dots: 是否每个点处有一个点标记。
        vertex_dot_radius: 点的半径，以场景单位计。
        vertex_dot_style: 点的 [样式关键字][manimgx.drawing.paint.Style]；None 表示无。
        **kwargs: 线的 [样式关键字][manimgx.drawing.paint.Style]。

    Returns:
        一个新的 [VDict][manimgx.VDict]，未添加到坐标轴，线在 `"line_graph"` 下，点（在一个组中）在 `"vertex_dots"` 下。

    Examples:
        ```python
        import manimgx as m


        class AxesPlotLineGraphExample(m.Scene):
            def construct(self) -> None:
                axes = m.Axes(x_range=[0, 7], y_range=[0, 5], y_length=6)
                graph = axes.plot_line_graph(
                    x_values=[0, 1.5, 2, 2.8, 4, 6.25],
                    y_values=[1, 3, 2.25, 4, 2.5, 1.75],
                    line_color=m.ORANGE,
                    vertex_dot_radius=0.12,
                    vertex_dot_style={"color": m.PURPLE},
                    stroke_width=6,
                )
                self.add(axes.add_coordinates())
                self.play(m.Create(graph))
        ```
    """
    xs, ys = (
        np.array(list(x_values), dtype=float),
        np.array(list(y_values), dtype=float),
    )
    zs = (
        np.zeros(xs.shape)
        if z_values is None
        else np.array(list(z_values), dtype=float)
    )
    line_graph = VDict()
    if kwargs.get("color") is None:  # not given, None too
        kwargs["color"] = line_color
    graph = VMobject(**kwargs)
    vertices = self.coords_to_point(*np.array((xs, ys, zs))).T
    graph.set_points_as_corners(vertices)
    line_graph["line_graph"] = graph
    if add_vertex_dots:
        line_graph["vertex_dots"] = VGroup(
            *(
                Dot(
                    point=vertex.copy(),  # the dot retains its center
                    radius=vertex_dot_radius,
                    **(vertex_dot_style or Style()),
                )
                for vertex in vertices
            )
        )
    return line_graph

def plot_polar_graph(
    self,
    r_func: Callable[[float], float],
    theta_range: Sequence[float] | None = None,
    **kwargs: Unpack[CurveOptions],
) -> ParametricFunction:
    """在坐标轴上以极坐标绘制曲线，r = r_func(θ)：对于其范围的每个角度 θ，在原点朝 θ 方向、距离 `r_func(θ)` 处的点。

    Args:
        r_func: 函数，从角度 θ（弧度）到距离 r（坐标轴单位）。
        theta_range: θ 的范围，`[θ_min, θ_max]` 或 `[θ_min, θ_max, θ_step]`，弧度，未给出步长时每 0.01 采样；None 表示一整圈，[0, 2π]。
        **kwargs: [曲线关键字][manimgx.mobjects.plotting.CurveOptions]：
            `use_smoothing` 和样式关键字。

    Returns:
        一个新的 [ParametricFunction][manimgx.ParametricFunction]，未添加到坐标轴。

    Examples:
        ```python
        import numpy as np

        import manimgx as m


        class AxesPlotPolarGraphExample(m.Scene):
            def construct(self) -> None:
                plane = m.PolarPlane(radius_max=3, size=7.5)
                rose = plane.plot_polar_graph(
                    lambda theta: 3 * np.sin(5 * theta), color=m.ORANGE
                )
                self.add(plane)
                self.play(m.Create(rose), run_time=3)
        ```
    """
    theta_range = theta_range if theta_range is not None else [0, 2 * PI]
    return ParametricFunction(
        function=lambda th: self.pr2pt(r_func(th), th),
        t_range=theta_range,
        **kwargs,
    )

def plot_implicit_curve(
    self,
    func: Callable[[float, float], float],
    min_depth: int = 5,
    max_quads: int = 1500,
    **kwargs: Unpack[ImplicitOptions],
) -> ImplicitFunction:
    """在坐标轴上以坐标轴坐标系绘制 x 和 y 的函数为零的曲线，即 `func(x, y) = 0`：在其范围内寻找。

    范围的矩形被四等分，每一部分再四等分，在曲线经过处更精细（参见 [ImplicitFunction][manimgx.ImplicitFunction]）。对数坐标轴上，函数接收幂。

    Args:
        func: x 和 y 的函数，在坐标轴坐标系中。
        min_depth: 矩形至少被四等分的次数：更多次能找到曲线更小的段。
        max_quads: 矩形最多可划分的单元格数：更多能更紧密地跟随曲线，但耗时更长。
        **kwargs: [隐式曲线关键字][manimgx.mobjects.plotting.ImplicitOptions]：
            `use_smoothing` 和样式关键字。

    Returns:
        一个新的 [ImplicitFunction][manimgx.ImplicitFunction]，未添加到坐标轴。

    Examples:
        ```python
        import manimgx as m


        class AxesPlotImplicitCurveExample(m.Scene):
            def construct(self) -> None:
                axes = m.Axes(x_range=[-3, 3], y_range=[-3, 3], y_length=7)
                curve = axes.plot_implicit_curve(
                    lambda x, y: y**2 - x**3 + 2 * x - 1, color=m.YELLOW
                )
                self.add(axes)
                self.play(m.Create(curve))
        ```
    """
    x_scale = self.get_x_axis().scaling
    y_scale = self.get_y_axis().scaling
    graph = ImplicitFunction(
        func=lambda x, y: func(x_scale.function(x), y_scale.function(y)),
        x_range=self.x_range[:2],
        y_range=self.y_range[:2],
        min_depth=min_depth,
        max_quads=max_quads,
        **kwargs,
    )
    graph.stretch(self.get_x_unit_size(), 0, about_point=ORIGIN).stretch(
        self.get_y_unit_size(), 1, about_point=ORIGIN
    ).shift(self.get_origin())
    return graph

def plot_derivative_graph(
    self, graph: ParametricFunction, **kwargs: Unpack[PlotOptions]
) -> ParametricFunction:
    """绘制图像的导数：在每个 x 处为其 [斜率][manimgx.Axes.slope_of_tangent]；未设置样式时为绿色。

    Args:
        **kwargs: [绘图关键字][manimgx.mobjects.plotting.PlotOptions]：
            `x_range`、`color`、…。

    Returns:
        一个新的 [ParametricFunction][manimgx.ParametricFunction]，未添加到坐标轴。

    Examples:
        ```python
        import manimgx as m


        class AxesPlotDerivativeGraphExample(m.Scene):
            def construct(self) -> None:
                axes = m.Axes(x_range=[-3, 3], y_range=[-3, 4], y_length=6.5)
                cubic = axes.plot(lambda x: x**3 / 6 - x, color=m.BLUE)
                derivative = axes.plot_derivative_graph(cubic)
                labels = m.VGroup(
                    axes.get_graph_label(cubic, "f(x)", x_val=-1.4, direction=m.UP),
                    axes.get_graph_label(derivative, "f'(x)", x_val=2.5),
                )
                self.add(axes, cubic, labels[0])
                self.play(m.Create(derivative), m.FadeIn(labels[1]))
        ```
    """
    if kwargs.get("color") is None:  # not given, None too
        kwargs["color"] = GREEN
    return self.plot(lambda x: self.slope_of_tangent(x, graph), **kwargs)

def plot_antiderivative_graph(
    self,
    graph: ParametricFunction,
    y_intercept: float = 0,
    samples: int = 50,
    **kwargs: Unpack[PlotOptions],
) -> ParametricFunction:
    """绘制图像的一个原函数：在每个 x 处为图像从 0 到 x 的积分，加上 `y_intercept`。

    每个值是图像在从 0 到 x 的 `samples` 个点处值的梯形和。

    Args:
        y_intercept: 原函数在 0 处的值。
        samples: 每个积分所求和的图像值个数。
        **kwargs: [绘图关键字][manimgx.mobjects.plotting.PlotOptions]：
            `x_range`、`color`、…。

    Returns:
        一个新的 [ParametricFunction][manimgx.ParametricFunction]，未添加到坐标轴。

    Examples:
        ```python
        import manimgx as m


        class AxesPlotAntiderivativeGraphExample(m.Scene):
            def construct(self) -> None:
                axes = m.Axes(x_range=[-3, 3], y_range=[-3, 3], y_length=6.5)
                graph = axes.plot(lambda x: (x**2 - 2) / 3, color=m.RED)
                antiderivative = axes.plot_antiderivative_graph(
                    graph, y_intercept=1, color=m.BLUE
                )
                self.add(axes, graph)
                self.play(m.Create(antiderivative))
        ```
    """
    axis = 1 if kwargs.get("use_vectorized", False) else 0
    f_vec = np.vectorize(
        graph.underlying_function
        or (lambda x: self.input_to_graph_coords(x, graph)[1])
    )

    def antideriv(x: float) -> float:
        x_vals = np.linspace(0, x, samples, axis=axis)
        return float(np.trapezoid(f_vec(x_vals), x_vals) + y_intercept)

    return self.plot(antideriv, **kwargs)

def input_to_graph_point(self, x: float, graph: ParametricFunction) -> Point3D:
    """在输入处找图像的点：[plot][manimgx.Axes.plot] 的图像在 x 处；其他曲线在其参数的某个值处。

    `i2gp` 是其简写名。输入可以超出图像的末端：该点为其函数在所绘部分之外的值。

    Args:
        x: 输入：图像的 x，在坐标轴坐标系中。
        graph: 图像或曲线。

    Returns:
        点，在场景坐标系中。

    Examples:
        ```python
        import numpy as np

        import manimgx as m


        class AxesInputToGraphPointExample(m.Scene):
            def construct(self) -> None:
                axes = m.Axes(x_range=[0, 7], y_range=[-1.5, 1.5, 0.5])
                curve = axes.plot(np.cos, color=m.BLUE)
                dots = m.VGroup(
                    *(m.Dot(axes.i2gp(x, curve), radius=0.12) for x in range(7))
                )
                self.add(axes, curve, dots.set_color(m.YELLOW))
        ```
    """
    return graph.function(x)

def input_to_graph_coords(
    self, x: float, graph: ParametricFunction
) -> tuple[float, float]:
    """找图像在输入处的点的坐标：[plot][manimgx.Axes.plot] 的图像为 (x, f(x))；其他曲线为其参数某值处的点的坐标。

    Args:
        x: 输入：图像的 x。
        graph: 图像或曲线。

    Returns:
        点的坐标，(x, y)。
    """
    if (
        graph.underlying_function is None
    ):  # a curve, not a graph of y(x): its point's coordinates
        coords = self.point_to_coords(graph.function(x))
        return float(coords[0]), float(coords[1])
    return (x, graph.underlying_function(x))

def get_graph_label(
    self,
    graph: ParametricFunction,
    label: Label = "f(x)",
    x_val: float | None = None,
    direction: Vector3DLike = RIGHT,
    buff: float = MED_SMALL_BUFF,
    color: ParsableManimColor | None = None,
    dot: bool = False,
    dot_config: Style | None = None,
) -> Mobject:
    r"""为图像制作标签，在其某个点旁：采用图像的颜色，除非给出其他颜色。

    字符串或数字用坐标轴的 `label_constructor` 排版（默认按数学排版，用 [MathTex][manimgx.MathTex]）；mobject 按原样使用，并重新着色。标签放在图像在 `x_val` 处的点旁，朝 `direction` 方向，然后若在屏幕外则移回屏幕上。未给出 `x_val` 时，该点为 x 轴范围内一百个点中最右侧的、位于画框顶部下方的点。

    Args:
        label: 标签：字符串或数字，按数学排版，或 mobject。
        x_val: 标签所放的点的 x；None 表示屏幕上最右侧的。
        direction: 标签从该点放置的方向。
        buff: 点与标签之间的间距，以场景单位计。
        color: 标签的颜色；None 表示图像的。
        dot: 是否有一个点标记该点，作为标签的一部分。
        dot_config: 点的 [样式关键字][manimgx.drawing.paint.Style]；None 表示无。

    Returns:
        标签，未添加到坐标轴。

    Examples:
        ```python
        import numpy as np

        import manimgx as m


        class AxesGetGraphLabelExample(m.Scene):
            def construct(self) -> None:
                axes = m.Axes(x_range=[-4, 4], y_range=[-2, 4], x_length=11)
                parabola = axes.plot(lambda x: x**2 / 4, color=m.BLUE)
                sine = axes.plot(np.sin, color=m.YELLOW)
                parabola_label = axes.get_graph_label(parabola, "x^2 / 4")
                sine_label = axes.get_graph_label(
                    sine, r"\sin x", x_val=m.PI / 2, direction=m.UP, dot=True
                )
                self.add(axes, parabola, sine, parabola_label, sine_label)
        ```
    """
    label_object: Mobject = self.x_axis._create_label_tex(label).set_color(
        graph.get_color() if color is None else color
    )
    if x_val is None:  # the rightmost point of the graph that is on screen
        xs = np.linspace(self.x_range[1], self.x_range[0], 100)
        points = (self.input_to_graph_point(x, graph) for x in xs)
        point = next(
            (p for p in points if p[1] < config["frame_y_radius"]),
            self.input_to_graph_point(xs[-1], graph),
        )
    else:
        point = self.input_to_graph_point(x_val, graph)
    label_object.next_to(point, direction, buff=buff)
    label_object.shift_onto_screen()
    if dot:
        label_object.add(Dot(point=point, **(dot_config or Style())))
    return label_object

def get_T_label(
    self,
    x_val: float,
    graph: ParametricFunction,
    label: float | str | Mobject | None = None,
    label_color: ParsableManimColor | None = None,
    triangle_size: float = MED_SMALL_BUFF,
    triangle_color: ParsableManimColor | None = WHITE,
    line_func: type[Line] = Line,
    line_color: ParsableManimColor = PURE_YELLOW,
) -> VGroup:
    """为某个 x 值制作 T 标签：x 轴下方一个朝上指向该值的小三角形、三角形下方的标签，以及从 x 轴向上到图像的线。

    Args:
        x_val: 它标记的 x 值。
        graph: 线所达到的图像。
        label: 三角形下方的标签：字符串或数字，按数学排版，或 mobject；None 表示无。
        label_color: 标签的颜色；None 表示保持原样。
        triangle_size: 三角形的高度，以场景单位计。
        triangle_color: 三角形的颜色。
        line_func: 线的类：[Line][manimgx.Line]（实线）、[DashedLine][manimgx.DashedLine]、…。
        line_color: 线的颜色。

    Returns:
        标签（若有）、三角形和线的新组；未添加到坐标轴。

    Examples:
        ```python
        import numpy as np

        import manimgx as m


        class AxesGetTLabelExample(m.Scene):
            def construct(self) -> None:
                axes = m.Axes(x_range=[0, 10], y_range=[0, 10], y_length=6)
                graph = axes.plot(lambda x: 3 * np.sqrt(x), color=m.BLUE)
                t_label = axes.get_T_label(4, graph, label=m.MathTex("x = 4"))
                self.add(axes, graph)
                self.play(m.FadeIn(t_label))
        ```
    """
    T_label_group = VGroup()
    triangle = RegularPolygon(n=3, start_angle=np.pi / 2, stroke_width=0).set_fill(
        color=triangle_color, opacity=1
    )
    triangle.height = triangle_size
    triangle.move_to(self.coords_to_point(x_val, 0), UP)
    if label is not None:
        t_label = self.x_axis._create_label_tex(label)
        if label_color is not None:
            t_label.set_color(label_color)
        t_label.next_to(triangle, DOWN)
        T_label_group.add(t_label)
    v_line = self.get_vertical_line(
        self.i2gp(x_val, graph), color=line_color, line_func=line_func
    )
    T_label_group.add(triangle, v_line)
    return T_label_group

def get_vertical_lines_to_graph(
    self,
    graph: ParametricFunction,
    x_range: Sequence[float] | None = None,
    num_lines: int = 20,
    **kwargs: Unpack[AxisLine],
) -> VGroup:
    """制作从 x 轴到图像的线，在某 x 范围内均匀分布：虚线，未设置样式时为白色细线。

    Args:
        x_range: x 的范围，`[x_min, x_max]`：第一条线在 x_min 处，最后一条在 x_max 处；None 表示 x 轴的范围。
        num_lines: 线的数量。
        **kwargs: [坐标轴线关键字][manimgx.mobjects.plotting.AxisLine]：
            线的类、关键字、`color` 和 `stroke_width`。

    Returns:
        线的新组，从左到右；未添加到坐标轴。

    Examples:
        ```python
        import numpy as np

        import manimgx as m


        class AxesGetVerticalLinesToGraphExample(m.Scene):
            def construct(self) -> None:
                axes = m.Axes(x_range=[0, 8], y_range=[-1, 1, 0.5], y_length=5)
                curve = axes.plot(
                    lambda x: np.sin(2 * x) * np.exp(-x / 4), color=m.YELLOW
                )
                lines = axes.get_vertical_lines_to_graph(
                    curve, x_range=[0.5, 7.5], num_lines=15, color=m.BLUE
                )
                self.add(axes, curve)
                self.play(m.Create(lines))
        ```
    """
    x_range = x_range if x_range is not None else self.x_range
    return VGroup(
        *(
            self.get_vertical_line(self.i2gp(x, graph), **kwargs)
            for x in np.linspace(x_range[0], x_range[1], num_lines)
        )
    )

def get_area(
    self,
    graph: ParametricFunction,
    x_range: Sequence[float] | None = None,
    color: ParsableManimColor | Iterable[ParsableManimColor] = (BLUE, GREEN),
    opacity: float = 0.3,
    bounded_graph: ParametricFunction | None = None,
    **kwargs: Unpack[StyleBase],
) -> Polygon:
    """制作图像与 x 轴之间、或两个图像之间在某 x 范围内的面积：一个多边形，未设置样式时从蓝到绿且半透明。

    面积的边缘跟随图像自身的点，沿 x 轴闭合，或沿 `bounded_graph` 返回；其填充和轮廓都采用 `color` 和 `opacity`。两个范围不相交的图像引发 ValueError。

    Args:
        x_range: x 的范围，`(x_min, x_max)`；None 表示图像的。
        color: 面积的颜色，或渐变颜色。
        opacity: 面积的不透明度，从 0 到 1。
        bounded_graph: 面积所达到的第二个图像，而非 x 轴；None 表示 x 轴。仅覆盖两个图像都跨越的范围。
        **kwargs: 多边形的 [样式关键字][manimgx.drawing.paint.Style]，但不包括其颜色和不透明度：`stroke_width`、…。

    Returns:
        一个新的 [Polygon][manimgx.Polygon]，未添加到坐标轴。

    Examples:
        ```python
        import manimgx as m


        class AxesGetAreaExample(m.Scene):
            def construct(self) -> None:
                axes = m.Axes(x_range=[0, 5], y_range=[0, 6], y_length=6.5)
                curve = axes.plot(lambda x: 5 - (x - 2.5) ** 2 / 2, color=m.BLUE)
                line = axes.plot(lambda x: x / 2, color=m.YELLOW)
                under = axes.get_area(curve, x_range=(0.5, 2))
                between = axes.get_area(
                    curve, x_range=(3, 4.5), bounded_graph=line, color=m.RED
                )
                self.add(axes, under, between, curve, line)
        ```
    """
    if x_range is None:
        a = graph.t_min
        b = graph.t_max
    else:
        a, b = x_range
    if bounded_graph is not None:
        if bounded_graph.t_min > b:
            raise ValueError(f"Ranges not matching: {bounded_graph.t_min} < {b}")
        if bounded_graph.t_max < a:
            raise ValueError(f"Ranges not matching: {bounded_graph.t_max} > {a}")
        a = max(a, bounded_graph.t_min)
        b = min(b, bounded_graph.t_max)
    if bounded_graph is None:
        points = (
            [self.c2p(a), graph.function(a)]
            + [p for p in graph.points if a <= self.p2c(p)[0] <= b]
            + [graph.function(b), self.c2p(b)]
        )
    else:
        graph_points, bounded_graph_points = (
            [g.function(a)]
            + [p for p in g.points if a <= self.p2c(p)[0] <= b]
            + [g.function(b)]
            for g in (graph, bounded_graph)
        )
        points = graph_points + bounded_graph_points[::-1]
    return Polygon(*points, **kwargs).set_opacity(opacity).set_color(color)