Paths¶

def set_points_as_corners(self, points: Point3DLike_Array) -> Self:
    """Give the path new points, in place of its own: straight lines through the
    given points in turn.

    The path is open: to close it, end with its first point again.

    Args:
        points: The corners, in scene coordinates, in order.

    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:
    """Give the path new points, in place of its own: a smooth curve through the
    given points in turn.

    The curve passes through each point, bending smoothly there, with no change of
    curvature (a cubic spline); if the last point is the first, it closes smoothly.

    Args:
        points: The points it passes through, in scene coordinates, in order.

    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:
    """Start a new subpath at a point: the next curve added begins there, not where
    the path ends.

    A curve left unfinished (a subpath started and given no curve yet) is completed
    with copies of its first point, as a curve of no length. Started where the path
    ends, the subpath just goes on.

    Args:
        point: Where the new subpath starts, in scene coordinates.
    """
    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:
    """Add a straight line from where the path ends to a point.

    The path must have a point to start from.

    Args:
        point: Where the line ends, in scene coordinates.

    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:
    """Add straight lines from where the path ends through each point in turn.

    The path must have a point to start from.

    Args:
        points: The corners, in scene coordinates, in order: the path then ends at
            the last.
    """
    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:
    """Add a curve that continues the path smoothly: it leaves where the path ends
    in the direction the path arrives there.

    Its first handle is the path's last handle mirrored through the path's end.
    Given only the anchor, the curve arrives there as the mirror image of how it
    leaves (mirrored across the perpendicular bisector of the line between its
    ends); given a second handle first, it arrives heading away from that. With no
    curve to continue, after [start_new_path][manimgx.VMobject.start_new_path], it
    is a straight line to the anchor.

    Args:
        *points: The anchor where the curve ends, or the second handle and then the
            anchor, in scene coordinates.

    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:
    """Add a curve from where the path ends to `anchor`, bending toward two handles.

    The curve leaves the path's last point heading toward `handle1`, and arrives at
    `anchor` heading away from `handle2`. The path must have a point to start from.

    Args:
        handle1: The first handle, in scene coordinates.
        handle2: The second handle.
        anchor: Where the curve ends.

    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:
    """Add a quadratic Bézier curve from where the path ends to `anchor`, bending
    toward one handle.

    It is added as the cubic curve of the same shape. The path must have a point to
    start from.

    Args:
        handle: The handle, in scene coordinates: the curve leaves the path's last
            point heading toward it, and arrives at `anchor` heading away from it.
        anchor: Where the curve ends.

    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:
    """Add a curve from `anchor1` to `anchor2`, bending toward two handles: a new
    subpath, unless `anchor1` is where the path ends.

    Its four points are appended as they are, so the path's curves must all be
    whole: after [start_new_path][manimgx.VMobject.start_new_path], use
    [add_cubic_bezier_curve_to][manimgx.VMobject.add_cubic_bezier_curve_to].

    Args:
        anchor1: Where the curve starts, in scene coordinates.
        handle1: The handle it leaves `anchor1` heading toward.
        handle2: The handle it arrives at `anchor2` heading away from.
        anchor2: Where it ends.
    """
    return self.append_points([anchor1, handle1, handle2, anchor2])

def add_cubic_bezier_curves(self, curves: Point3DLike_Array) -> Self:
    """Add curves after the path's own, given by their control points, four per
    curve: anchor, handle, handle, anchor.

    Args:
        curves: The curves' control points, in scene coordinates: an (n, 4, 3)
            array, or the points one after another.
    """
    return self.append_points(np.asarray(curves).reshape(-1, 3))

def add_subpath(self, points: Point3DLike_Array) -> Self:
    """Add curves after the path's own, by their control points, four per curve: a
    new subpath, unless they start where the path ends.

    Args:
        points: The curves' control points, in scene coordinates.
    """
    return self.append_points(points)

def append_vectorized_mobject(self, vmobject: "VMobject") -> Self:
    """Add another path's curves after this path's own: its points, not its
    submobjects.

    A subpath just started and given no curve yet (see
    [start_new_path][manimgx.VMobject.start_new_path]) is dropped for them.

    Args:
        vmobject: The path whose points to add.
    """
    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:
    """Close the path: add a straight line from where it ends back to where its last
    subpath starts, unless it ends where it starts.

    The fill closes every subpath anyway; closing one makes its stroke go all the
    way around.

    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:
    """Whether the path ends where it starts: its first and last points coincide,
    within a millionth of a unit."""
    return self.consider_points_equals(
        self._geometry.point(0), self._geometry.point(-1)
    )

def make_smooth(self) -> Self:
    """Make every subpath in the family a smooth curve through its anchors, with no
    change of curvature at any (a cubic spline); a closed subpath closes smoothly.

    The anchors stay and the handles move: a polygon becomes a rounded loop through
    its corners.

    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:
    """Make every subpath in the family straight lines between its anchors: a curve
    through points becomes the polygon through them.
    """
    return self.change_anchor_mode("jagged")

def insert_n_curves(self, n: int) -> Self:
    """Divide the path's curves into more curves, its shape unchanged.

    Each curve is split into equal stretches of its parameter, the new curves
    spread among the curves as evenly as can be (curve i of m gets the new curves j
    of n with j·m // n = i): the way a transform gives two paths as many curves as
    each other.

    Args:
        n: How many curves to add.
    """
    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:
    """The mobject's first point: where a path starts.

    Raises an exception if the mobject has no points of its own.

    Returns:
        The point, in scene coordinates.
    """
    self._require_points()
    return np.array(self.points[0])

def get_end(self) -> Point3D:
    """The mobject's last point: where a path ends.

    Raises an exception if the mobject has no points of its own.

    Returns:
        The point, in scene coordinates.
    """
    self._require_points()
    return np.array(self.points[-1])

def get_midpoint(self) -> Point3D:
    """The point halfway along the mobject: for a path, half its length from its
    start.

    Returns:
        The point, in scene coordinates.
    """
    return self.point_from_proportion(0.5)

def point_from_proportion(self, alpha: float) -> Point3D:
    """The point a proportion of the way along the path, by length: 0 is its start,
    1 its end.

    The length is the path's own measure, the one a reveal draws by (nine straight
    pieces per curve), so it is where a [Create][manimgx.Create] at that proportion
    has drawn to, and a [MoveAlongPath][manimgx.MoveAlongPath] moves at a steady
    speed. Raises an exception if `alpha` is outside [0, 1] or the path has no
    points.

    Args:
        alpha: The proportion, from 0 to 1.

    Returns:
        The point, in scene coordinates.

    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:
    """How far along the path a point on it lies, by length: the inverse of
    [point_from_proportion][manimgx.VMobject.point_from_proportion].

    The first curve the point lies on counts. Raises an exception if the point is
    not on the path.

    Args:
        point: The point, in scene coordinates.
        tolerance: How near the path the point must be: within 100 times this, in
            scene units, along each axis.

    Returns:
        The proportion, from 0 (the path's start) to 1 (its end).
    """
    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:
    """The path's length: the sum of its curves' lengths, each measured along
    straight pieces between points on it.

    Args:
        sample_points_per_curve: How many points each curve is measured through, its
            ends included; None for 10, the path's own measure.

    Returns:
        The length, in scene units.
    """
    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 copy of the path cut down to its part from proportion `a` of the way along
    it to proportion `b`.

    The proportions go by the path's curves, each an equal share whatever its
    length, and along each curve by its parameter
    ([point_from_proportion][manimgx.VMobject.point_from_proportion] goes by
    length). The copy's submobjects are copied whole.

    Args:
        a: Where the part starts, from 0 to 1.
        b: Where it ends, from `a` to 1.

    Returns:
        A new path.

    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:
    """Which way the path turns: "CW" (clockwise) or "CCW" (counterclockwise), by
    the sign of the area its curves' start anchors enclose.

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

def reverse_direction(self) -> Self:
    """Reverse the order of the path's own points, so it runs the other way: from
    its end to its start.

    Its submobjects stay as they are. A drawing animation then draws it the other
    way, and a subpath inside another cuts
    a hole in the fill only if the two run opposite ways.

    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:
    """Make the path run clockwise or counterclockwise: reverse it if it runs the
    other way (see [get_direction][manimgx.VMobject.get_direction]).

    Args:
        target_direction: "CW" for clockwise, "CCW" for counterclockwise.
    """
    if self.get_direction() != target_direction:
        self.reverse_direction()
    return self