路径¶

def set_points_as_corners(self, points: Point3DLike_Array) -> Self:
    """给路径新点，替换其自身的点：依次经过
    给定点的直线。

    路径是开放的：要闭合它，以第一个点再次结束。

    Args:
        points: 角点，场景坐标，按顺序。

    Examples:
        ```python
        import manimgx as m


        class VMobjectSetPointsAsCornersExample(m.Scene):
            def construct(self) -> None:
                zigzag = m.VMobject(color=m.YELLOW, stroke_width=8)
                zigzag.set_points_as_corners(
                    [[-3, -1.5, 0], [-1.5, 1.5, 0], [0, -1.5, 0], [1.5, 1.5, 0]]
                )
                triangle = m.VMobject(color=m.BLUE, fill_opacity=0.5)
                triangle.set_points_as_corners(
                    [[-2, -1.5, 0], [0, 2, 0], [2, -1.5, 0], [-2, -1.5, 0]]
                )
                self.add(m.VGroup(zigzag, triangle).arrange(buff=2))
        ```
    """
    pts = np.asarray(points, dtype=float)
    if len(pts) == 2:  # a segment: the one segment, placed
        self._geometry = segment(pts[0], pts[1])
        return self
    return self.set_anchors_and_handles(
        *(interpolate(pts[:-1], pts[1:], t) for t in _T_VALUES)
    )

def set_points_smoothly(self, points: Point3DLike_Array) -> Self:
    """给路径新点，替换其自身的点：依次经过
    给定点的平滑曲线。

    曲线经过每个点，在该处平滑弯曲，曲率无
    突变（三次样条）；若最后一个点为第一个点，则平滑闭合。

    Args:
        points: 曲线经过的点，场景坐标，按顺序。

    Examples:
        ```python
        import manimgx as m


        class VMobjectSetPointsSmoothlyExample(m.Scene):
            def construct(self) -> None:
                points = [[-5, -1, 0], [-3, 2, 0], [-1, -2, 0], [1, 2, 0]]
                points += [[3, -1, 0], [5, 1, 0]]
                corners = m.VMobject(color=m.GREY).set_points_as_corners(points)
                curve = m.VMobject(color=m.YELLOW, stroke_width=8)
                curve.set_points_smoothly(points)
                self.add(corners, *(m.Dot(p, radius=0.12) for p in points))
                self.play(m.Create(curve, run_time=2))
        ```
    """
    self.set_points_as_corners(points)
    return self.make_smooth()

def start_new_path(self, point: Point3DLike) -> Self:
    """在某点开始新的子路径：下一条添加的曲线从该点开始，而非
    路径终点。

    未完成的曲线（已开始但尚未添加曲线的子路径）以
    其第一个点的副本补全，作为零长度曲线。若在路径终点处开始，
    子路径直接延续。

    Args:
        point: 新子路径的起点，场景坐标。
    """
    n = self._geometry.n
    if n % _NPPCC != 0:
        last = self._geometry.point(n // _NPPCC * _NPPCC)
        self.append_points([last] * (_NPPCC - n % _NPPCC) + [point])
    else:
        self.append_points([point])
    return self

def add_line_to(self, point: Point3DLike) -> Self:
    """从路径终点到某点添加直线。

    路径必须有一个点作为起点。

    Args:
        point: 直线终点，场景坐标。

    Examples:
        ```python
        import manimgx as m


        class VMobjectAddLineToExample(m.Scene):
            def construct(self) -> None:
                stairs = m.VMobject(color=m.BLUE, stroke_width=8)
                stairs.start_new_path([-5, -3, 0])
                for _ in range(5):
                    stairs.add_line_to(stairs.get_end() + 1.2 * m.UP)
                    stairs.add_line_to(stairs.get_end() + 2 * m.RIGHT)
                self.play(m.Create(stairs, run_time=3))
        ```
    """
    last = self.get_last_point()
    p = np.asarray(point, dtype=float)
    return self.add_cubic_bezier_curve_to(
        *(interpolate(last, p, t) for t in _T_VALUES[1:])
    )

def add_points_as_corners(self, points: Point3DLike_Array) -> Self:
    """从路径终点依次经过每个点添加直线。

    路径必须有一个点作为起点。

    Args:
        points: 角点，场景坐标，按顺序：路径随后在
            最后一个点处结束。
    """
    self._require_points()
    pts = np.asarray(points, dtype=float).reshape(-1, self.dim)
    if len(pts) == 0:
        return self
    starts = np.vstack([self.points[-1:], pts[:-1]])
    if self.has_new_path_started():
        self.points = self.points[:-1]
    new = np.empty((_NPPCC * len(starts), self.dim))
    for i, t in enumerate(_T_VALUES):
        new[i::_NPPCC] = interpolate(starts, pts, t)
    return self.append_points(new)

def add_smooth_curve_to(self, *points: Point3DLike) -> Self:
    """添加平滑延续路径的曲线：它从路径终点沿
    路径到达该处的方向离开。

    其第一个手柄是路径最后一个手柄关于路径终点的镜像。
    仅给出锚点时，曲线以其离开方式的镜像到达该处
    （关于其两端连线的垂直平分线镜像）；先给出第二个手柄时，
    曲线背离该手柄到达。若无曲线可延续，在
    [start_new_path][manimgx.VMobject.start_new_path] 之后，
    为到锚点的直线。

    Args:
        *points: 曲线终点的锚点，或先第二个手柄再
            锚点，场景坐标。

    Examples:
        ```python
        import manimgx as m


        class VMobjectAddSmoothCurveToExample(m.Scene):
            def construct(self) -> None:
                wave = m.VMobject(color=m.YELLOW, stroke_width=8)
                wave.start_new_path([-6, 0, 0])
                wave.add_cubic_bezier_curve_to([-6, 2, 0], [-4, 2, 0], [-4, 0, 0])
                for x in (-2, 0, 2, 4, 6):
                    wave.add_smooth_curve_to([x, 0, 0])
                self.play(m.Create(wave, run_time=3))
        ```
    """
    if len(points) == 1:
        handle2, new_anchor = None, np.asarray(points[0])
    elif len(points) == 2:
        handle2, new_anchor = np.asarray(points[0]), np.asarray(points[1])
    else:
        raise ValueError("Only call add_smooth_curve_to with 1 or 2 points")
    if self.has_new_path_started():
        return self.add_line_to(new_anchor)
    last_h2, last_a2 = self.points[-2:]
    tangent = last_a2 - last_h2
    handle1 = last_a2 + tangent
    if handle2 is None:  # the tangent mirrored across the ends' bisector
        chord = normalize(new_anchor - last_a2)
        handle2 = new_anchor + tangent - 2 * (tangent @ chord) * chord
    return self.append_points([last_a2, handle1, handle2, new_anchor])

def add_cubic_bezier_curve_to(
    self, handle1: Point3DLike, handle2: Point3DLike, anchor: Point3DLike
) -> Self:
    """从路径终点到 `anchor` 添加曲线，弯向两个手柄。

    曲线从路径最后一个点朝向 `handle1` 离开，到达
    `anchor` 时背离 `handle2`。路径必须有一个点作为起点。

    Args:
        handle1: 第一个手柄，场景坐标。
        handle2: 第二个手柄。
        anchor: 曲线终点。

    Examples:
        ```python
        import manimgx as m


        class VMobjectAddCubicBezierCurveToExample(m.Scene):
            def construct(self) -> None:
                start, h1, h2, end = [-4, -2, 0], [-2, 3, 0], [2, 3, 0], [4, -2, 0]
                path = m.VMobject(color=m.YELLOW, stroke_width=8)
                path.start_new_path(start).add_cubic_bezier_curve_to(h1, h2, end)
                handles = m.VGroup(m.Line(start, h1), m.Line(h2, end))
                dots = [m.Dot(p, radius=0.12) for p in (start, h1, h2, end)]
                self.add(handles.set_color(m.GREY), *dots)
                self.play(m.Create(path, run_time=2))
        ```
    """
    self._require_points()
    new = [handle1, handle2, anchor]
    return self.append_points(
        new if self.has_new_path_started() else [self.get_last_point(), *new]
    )

def add_quadratic_bezier_curve_to(
    self, handle: Point3DLike, anchor: Point3DLike
) -> Self:
    """从路径终点到 `anchor` 添加二次贝塞尔曲线，弯向
    一个手柄。

    它作为同形状的三次曲线添加。路径必须有一个点作为起点。

    Args:
        handle: 手柄，场景坐标：曲线从路径最后
            一个点朝向它离开，到达 `anchor` 时背离它。
        anchor: 曲线终点。

    Examples:
        ```python
        import manimgx as m


        class VMobjectAddQuadraticBezierCurveToExample(m.Scene):
            def construct(self) -> None:
                start, handle, end = [-4, -2, 0], [0, 3, 0], [4, -2, 0]
                path = m.VMobject(color=m.TEAL, stroke_width=8)
                path.start_new_path(start)
                path.add_quadratic_bezier_curve_to(handle, end)
                handles = m.VGroup(m.Line(start, handle), m.Line(handle, end))
                dots = [m.Dot(p, radius=0.12) for p in (start, handle, end)]
                self.add(handles.set_color(m.GREY), *dots)
                self.play(m.Create(path, run_time=2))
        ```
    """
    h, a, last = np.asarray(handle), np.asarray(anchor), self.get_last_point()
    return self.add_cubic_bezier_curve_to(
        2 / 3 * h + 1 / 3 * last, 2 / 3 * h + 1 / 3 * a, a
    )

def add_cubic_bezier_curve(
    self,
    anchor1: Point3DLike,
    handle1: Point3DLike,
    handle2: Point3DLike,
    anchor2: Point3DLike,
) -> Self:
    """添加从 `anchor1` 到 `anchor2` 的曲线，弯向两个手柄：新的
    子路径，除非 `anchor1` 是路径终点。

    其四个点按原样追加，因此路径的曲线必须全部
    完整：在 [start_new_path][manimgx.VMobject.start_new_path] 之后，使用
    [add_cubic_bezier_curve_to][manimgx.VMobject.add_cubic_bezier_curve_to]。

    Args:
        anchor1: 曲线起点，场景坐标。
        handle1: 离开 `anchor1` 时所朝向的手柄。
        handle2: 到达 `anchor2` 时所背离的手柄。
        anchor2: 曲线终点。
    """
    return self.append_points([anchor1, handle1, handle2, anchor2])

def add_cubic_bezier_curves(self, curves: Point3DLike_Array) -> Self:
    """在路径自身的曲线之后添加曲线，由控制点给出，每条曲线四个：
    锚点、手柄、手柄、锚点。

    Args:
        curves: 曲线的控制点，场景坐标：(n, 4, 3)
            数组，或依次排列的点。
    """
    return self.append_points(np.asarray(curves).reshape(-1, 3))

def add_subpath(self, points: Point3DLike_Array) -> Self:
    """在路径自身的曲线之后添加曲线，由控制点给出，每条曲线四个：
    新的子路径，除非它们从路径终点开始。

    Args:
        points: 曲线的控制点，场景坐标。
    """
    return self.append_points(points)

def append_vectorized_mobject(self, vmobject: "VMobject") -> Self:
    """在此路径自身的曲线之后添加另一路径的曲线：其点，而非其
    子 mobject。

    刚开始但尚未添加曲线的子路径（参见
    [start_new_path][manimgx.VMobject.start_new_path]）被丢弃。

    Args:
        vmobject: 要添加其点的路径。
    """
    if self.has_new_path_started():  # its start begins the path that was begun
        self.points = self.points[:-1]
    return self.append_points(vmobject.points)

def close_path(self) -> Self:
    """闭合路径：从路径终点到其最后一个子路径起点添加直线，
    除非路径已在起点处结束。

    填充无论如何都会闭合每个子路径；闭合子路径使其描边
    完整绕行一圈。

    Examples:
        ```python
        import manimgx as m


        class VMobjectClosePathExample(m.Scene):
            def construct(self) -> None:
                corners = [[-2, -1.5, 0], [0, 1.5, 0], [2, -1.5, 0]]
                style = {"fill_opacity": 0.5, "stroke_width": 8}
                open_path = m.VMobject(color=m.GREEN, **style)
                closed_path = m.VMobject(color=m.YELLOW, **style)
                open_path.set_points_as_corners(corners)
                closed_path.set_points_as_corners(corners).close_path()
                self.add(m.VGroup(open_path, closed_path).arrange(buff=2))
        ```
    """
    if not self.is_closed():
        self.add_line_to(self.get_subpaths()[-1][0])
    return self

def is_closed(self) -> bool:
    """路径是否在起点处结束：其第一个和最后一个点在
    百万分之一单位内重合。"""
    return self.consider_points_equals(
        self._geometry.point(0), self._geometry.point(-1)
    )

def make_smooth(self) -> Self:
    """使家族中每个子路径成为经过其锚点的平滑曲线，在任何锚点处
    曲率无突变（三次样条）；闭合的子路径平滑闭合。

    锚点保持不变，手柄移动：多边形变为经过其
    角点的圆滑环线。

    Examples:
        ```python
        import manimgx as m


        class VMobjectMakeSmoothExample(m.Scene):
            def construct(self) -> None:
                square = m.Square(side_length=4, color=m.BLUE, stroke_width=8)
                self.add(square.copy().set_stroke(m.GREY, 3))
                self.play(square.animate.make_smooth(), run_time=2)
        ```
    """
    return self.change_anchor_mode("smooth")

def make_jagged(self) -> Self:
    """使家族中每个子路径成为其锚点间的直线：经过点的曲线
    变为经过它们的多边形。
    """
    return self.change_anchor_mode("jagged")

def insert_n_curves(self, n: int) -> Self:
    """将路径的曲线分成更多曲线，形状不变。

    每条曲线按参数等分，新曲线尽可能均匀地分布在各曲线之间
    （m 条中的第 i 条获得 n 条中的第 j 条新曲线，满足 j·m // n = i）：
    这是变换使两条路径拥有相同曲线数的方式。

    Args:
        n: 要添加多少条曲线。
    """
    new_path_point = self.get_last_point() if self.has_new_path_started() else None
    self.set_points(self.insert_n_curves_to_point_list(n, self.points))
    if new_path_point is not None:
        self.append_points([new_path_point])
    return self

def get_start(self) -> Point3D:
    """mobject 的第一个点：路径的起点。

    如果 mobject 没有自身的点，则抛出异常。

    Returns:
        该点，以场景坐标表示。
    """
    self._require_points()
    return np.array(self.points[0])

def get_end(self) -> Point3D:
    """mobject 的最后一个点：路径的终点。

    如果 mobject 没有自身的点，则抛出异常。

    Returns:
        该点，以场景坐标表示。
    """
    self._require_points()
    return np.array(self.points[-1])

def get_midpoint(self) -> Point3D:
    """mobject 上中点处的点：对于路径，为从起点出发其长度一半处。

    Returns:
        该点，以场景坐标表示。
    """
    return self.point_from_proportion(0.5)

def point_from_proportion(self, alpha: float) -> Point3D:
    """沿路径按长度比例处的点：0 为起点，
    1 为终点。

    长度是路径自身的度量，即揭示动画所依据的度量（每条曲线九个直线
    段），因此它是 [Create][manimgx.Create] 在该比例处
    已绘制到的位置，[MoveAlongPath][manimgx.MoveAlongPath] 以匀速
    移动。若 `alpha` 在 [0, 1] 之外或路径无点则抛出异常。

    Args:
        alpha: 比例，从 0 到 1。

    Returns:
        该点，场景坐标。

    Examples:
        ```python
        import manimgx as m


        class VMobjectPointFromProportionExample(m.Scene):
            def construct(self) -> None:
                points = [[-5, -2, 0], [-2, 2, 0], [1, -1, 0], [5, 2, 0]]
                curve = m.VMobject(color=m.BLUE, stroke_width=6)
                curve.set_points_smoothly(points)
                self.add(curve)
                for alpha in (0, 0.25, 0.5, 0.75, 1):
                    point = curve.point_from_proportion(alpha)
                    dot = m.Dot(point, radius=0.15, color=m.YELLOW)
                    label = m.Text(str(alpha), font_size=32).next_to(dot, m.DOWN)
                    self.add(dot, label)
        ```
    """
    if alpha < 0 or alpha > 1:
        raise ValueError(f"Alpha {alpha} not between 0 and 1.")
    self._require_points()
    curves = self.get_num_curves()
    if curves == 0:  # a point, or a subpath just started
        return self.points[-1]
    at = self._geometry.parameter_at(alpha)
    n = min(int(at), curves - 1)
    return self.get_nth_curve_function(n)(at - n)

def proportion_from_point(
    self, point: Point3DLike, tolerance: float = 1e-6
) -> float:
    """路径上某点沿路径的位置，按长度计算：
    [point_from_proportion][manimgx.VMobject.point_from_proportion] 的逆。

    以点所在的第一条曲线为准。若点不在路径上则抛出异常。

    Args:
        point: 该点，场景坐标。
        tolerance: 点离路径多近才算在上面：沿每个轴在
            此值的 100 倍以内，场景单位。

    Returns:
        比例，从 0（路径起点）到 1（路径终点）。
    """
    p = np.asarray(point, dtype=float)
    for n in range(self.get_num_curves()):
        curve = self.get_nth_curve_points(n)
        dim = int(
            np.argmax(np.ptp(curve, axis=0))
        )  # solve along the curve's widest coordinate, then check all
        c = [
            curve[0],
            3 * (curve[1] - curve[0]),
            3 * (curve[2] - 2 * curve[1] + curve[0]),
            curve[3] - 3 * curve[2] + 3 * curve[1] - curve[0],
        ]
        coeffs = np.array([ci[dim] for ci in c])
        coeffs[0] -= p[dim]
        roots = [
            r.real
            for r in (
                np.polynomial.Polynomial(coeffs).roots()
                if coeffs[1:].any()
                else [0.0]  # constant along its widest coordinate: a point
            )
            # candidates, each checked below: a double root (a stationary end) comes
            # back as a complex pair with parts near √ε
            if abs(r.imag) < 1e-4 and -1e-4 <= r.real <= 1 + 1e-4
        ]
        hits = [
            t
            for t in roots
            if np.allclose(
                bezier(curve)(min(max(t, 0), 1)), p, atol=tolerance * 100
            )
        ]
        if hits:  # by the path's own measure: the inverse of point_from_proportion
            return self._geometry.fraction_at(n + min(max(max(hits), 0.0), 1.0))
    raise ValueError(f"Point {point} does not lie on this curve.")

def get_arc_length(self, sample_points_per_curve: int | None = None) -> float:
    """路径的长度：各曲线长度之和，每条沿其上点间
    直线段测量。

    Args:
        sample_points_per_curve: 每条曲线经过多少个点测量，包含
            端点；None 为 10，即路径自身的度量。

    Returns:
        长度，场景单位。
    """
    if sample_points_per_curve in (None, 10):
        return float(self._geometry.curve_lengths().sum())
    return sum(
        length
        for _, length in self.get_curve_functions_with_lengths(
            sample_points_per_curve
        )
    )

def get_subcurve(self, a: float, b: float) -> Self:
    """路径的副本，截取从比例 `a` 到比例 `b` 的部分。

    比例按路径的曲线计算，每条曲线等份额不论其
    长度，沿每条曲线按其参数
    （[point_from_proportion][manimgx.VMobject.point_from_proportion] 按长度
    计算）。副本的子 mobject 整体复制。

    Args:
        a: 部分起点，从 0 到 1。
        b: 部分终点，从 `a` 到 1。

    Returns:
        新路径。

    Examples:
        ```python
        import manimgx as m


        class VMobjectGetSubcurveExample(m.Scene):
            def construct(self) -> None:
                circle = m.Circle(radius=2.5, color=m.GREY)
                half = circle.get_subcurve(0.25, 0.75).set_stroke(m.YELLOW, 12)
                self.add(circle)
                self.play(m.Create(half))
        ```
    """
    return self.copy().pointwise_become_partial(self, a, b)

def get_direction(self) -> str:
    """路径的转向："CW"（顺时针）或 "CCW"（逆时针），由
    其曲线起始锚点所围面积的符号决定。

    Returns:
        "CW" 或 "CCW"。
    """
    return shoelace_direction(self.get_start_anchors())

def reverse_direction(self) -> Self:
    """反转路径自身点的顺序，使其反向运行：从
    终点到起点。

    其子 mobject 保持不变。绘制动画随后以另一方向绘制它，
    在另一个子路径内部的子路径仅当两者反向运行时才在填充中
    切出一个洞。

    Examples:
        ```python
        import manimgx as m


        class VMobjectReverseDirectionExample(m.Scene):
            def construct(self) -> None:
                outer, inner = m.Square(side_length=4), m.Square(side_length=2)
                same = m.VMobject(color=m.BLUE, fill_opacity=0.8)
                same.append_vectorized_mobject(outer)
                same.append_vectorized_mobject(inner)
                opposite = m.VMobject(color=m.YELLOW, fill_opacity=0.8)
                opposite.append_vectorized_mobject(outer)
                opposite.append_vectorized_mobject(inner.reverse_direction())
                self.add(m.VGroup(same, opposite).arrange(buff=2))
        ```
    """
    self.points = self.points[::-1].copy()
    return self

def force_direction(self, target_direction: Literal["CW", "CCW"]) -> Self:
    """使路径顺时针或逆时针运行：若方向相反则反转
    （参见 [get_direction][manimgx.VMobject.get_direction]）。

    Args:
        target_direction: "CW" 为顺时针，"CCW" 为逆时针。
    """
    if self.get_direction() != target_direction:
        self.reverse_direction()
    return self