Planes¶

def prepare_for_nonlinear_transform(self, num_inserted_curves: int = 50) -> Self:
    """Split the plane's lines into many curves, so that a nonlinear function bends
    them smoothly.

    A function applied to the plane (with
    [apply_function][manimgx.Mobject.apply_function] or
    [apply_complex_function][manimgx.Mobject.apply_complex_function]) moves the
    points of its lines, and a straight line is a single curve: moving its few
    points would barely bend it. Each part of the plane with fewer curves than
    `num_inserted_curves` is divided into that many.

    Args:
        num_inserted_curves: How many curves each line has at least.

    Examples:
        ```python
        import numpy as np

        import manimgx as m


        class PlanePrepareForNonlinearTransformExample(m.Scene):
            def construct(self) -> None:
                plane = m.ComplexPlane(x_range=[-3, 3, 0.5], y_range=[-2, 2, 0.5])
                plane.prepare_for_nonlinear_transform()
                self.add(plane)
                self.play(plane.animate.apply_complex_function(np.sin), run_time=3)
        ```
    """
    for mob in self.family_members_with_points():
        if isinstance(mob, VMobject):
            num_curves = mob.get_num_curves()
            if num_inserted_curves > num_curves:
                mob.insert_n_curves(num_inserted_curves - num_curves)
    return self

def number_to_point(self, number: float | complex) -> Point3D:
    """Convert a complex number to its point on the plane: x + yi to the point of
    coordinates (x, y).

    `n2p` is its short name.

    Args:
        number: The number; a real number is on the x-axis.

    Returns:
        The point, in scene coordinates.
    """
    number = complex(number)
    return self.coords_to_point(number.real, number.imag)

def point_to_number(self, point: Point3DLike) -> complex:
    """Convert a point to the complex number at it: x + yi, for the point's
    coordinates (x, y).

    `p2n` is its short name.

    Args:
        point: The point, in scene coordinates.
    """
    x, y = self.point_to_coords(point)[:2]
    return complex(x, y)

def get_coordinate_labels(
    self, *numbers: float | complex, **kwargs: Unpack[DecimalNumberOptions]
) -> VGroup:
    """Make labels for numbers of the plane: a real number by its point on the
    x-axis, an imaginary one, with `i`, by its point on the y-axis.

    A number is written as its larger part: its imaginary part, by the y-axis, if
    that is larger in size than its real part; its real part, by the x-axis,
    otherwise. Each is written as the axis numbers its ticks (see
    [get_number_mobject][manimgx.NumberLine.get_number_mobject]).

    Args:
        *numbers: The numbers to label; none for the ticks of both axes, but 0.
        **kwargs: [Number keywords][manimgx.DecimalNumber]
            for the labels: `font_size`, `num_decimal_places`, `color`, ….

    Returns:
        A new group of the labels, kept as the plane's `coordinate_labels`; not
        added to the plane.
    """
    self.coordinate_labels = VGroup()
    for number in numbers or self._get_default_coordinate_values():
        z = complex(number)
        if abs(z.imag) > abs(z.real):
            self.coordinate_labels.add(
                self.get_y_axis().get_number_mobject(
                    z.imag, **(kwargs | {"unit": "i"})
                )
            )
        else:
            self.coordinate_labels.add(
                self.get_x_axis().get_number_mobject(z.real, **kwargs)
            )
    return self.coordinate_labels

def add_coordinates(  # pyright: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]  # CE's: numbers, not per-axis values
    self, *numbers: float | complex, **kwargs: Unpack[DecimalNumberOptions]
) -> Self:
    """Label numbers of the plane, as
    [get_coordinate_labels][manimgx.ComplexPlane.get_coordinate_labels] makes the
    labels, and add them to the plane.

    Args:
        *numbers: The numbers to label; none for the ticks of both axes, but 0.
        **kwargs: [Number keywords][manimgx.DecimalNumber]
            for the labels: `font_size`, `num_decimal_places`, `color`, ….
    """
    self.add(self.get_coordinate_labels(*numbers, **kwargs))
    return self

def get_coordinate_labels(
    self,
    r_values: Iterable[float] | None = None,
    a_values: Iterable[float] | None = None,
) -> VGroup:
    """Number the plane's radii, and make labels for its angles.

    The radii are numbered along the x-axis, right of the center; the numbers are
    added to the axis. The angles' labels, in the plane's `azimuth_units`, go around
    the outer circle, `azimuth_label_buff` beyond it: placed for a plane centered on
    the scene's origin, as it is made.

    Args:
        r_values: The radii to number, in the plane's units; None for every
            circle's but 0.
        a_values: The angles to label, as fractions of a turn (0.25 is a quarter
            turn); None for every line's.

    Returns:
        A new group of the x-axis, now numbered, and a group of the angles' labels
        (not added to the plane); kept as the plane's `coordinate_labels`.
    """
    if r_values is None:
        r_values = [r for r in self.get_x_axis().get_tick_range() if r >= 0]
    if a_values is None:
        a_values = np.arange(0, 1, 1 / self.azimuth_step)
    r_mobs = self.get_x_axis().add_numbers(r_values)
    d = 1 if self.azimuth_direction == "CCW" else -1
    radius = self.get_right()[0]
    labels = VGroup()
    for i in a_values:
        angle = d * (i * TAU) + self.azimuth_offset
        point = np.array([radius * np.cos(angle), radius * np.sin(angle), 0])
        label = self._azimuth_label(i)
        labels.add(
            label.next_to(
                point,
                direction=point,
                aligned_edge=point,
                buff=self.azimuth_label_buff,
            )
        )
    self.coordinate_labels = VGroup(r_mobs, labels)
    return self.coordinate_labels

def add_coordinates(  # pyright: ignore[reportIncompatibleMethodOverride]  # ty: ignore[invalid-method-override]  # CE's: a polar plane numbers radii and angles
    self,
    r_values: Iterable[float] | None = None,
    a_values: Iterable[float] | None = None,
) -> Self:
    """Number the plane's radii along its x-axis, and label its angles around it,
    as [get_coordinate_labels][manimgx.PolarPlane.get_coordinate_labels] makes them.

    Args:
        r_values: The radii to number, in the plane's units; None for every
            circle's but 0.
        a_values: The angles to label, as fractions of a turn (0.25 is a quarter
            turn); None for every line's.
    """
    self.add(self.get_coordinate_labels(r_values, a_values))
    return self

def get_radian_label(
    self, number: float, **kwargs: Unpack[MathTexOptions]
) -> MathTex:
    """Make the label of an angle in radians: a fraction of π, or of τ if the
    plane's units are `"TAU radians"`.

    The fraction is the nearest with a denominator up to 100, written as the plane's
    `azimuth_compact_fraction` says: 3π/4, or 3/4 π.

    Args:
        number: The angle, as a fraction of a turn (0.375 for 3π/4).
        **kwargs: [Math keywords][manimgx.MathTex]
            for the label; its font size is 24 unless given.

    Returns:
        A new [MathTex][manimgx.MathTex].
    """
    kwargs.setdefault("font_size", 24)
    units = (
        self.azimuth_units
        if self.azimuth_units in ("PI radians", "TAU radians")
        else "PI radians"
    )
    constant = {"PI radians": "\\pi", "TAU radians": "\\tau"}[units]
    frac = fr.Fraction(number * {"PI radians": 2, "TAU radians": 1}[units])
    p, q = (frac := frac.limit_denominator(100)).numerator, frac.denominator
    if p == 0:
        string = "0"
    elif q == 1:
        string = constant if p == 1 else f"{p}{constant}"
    elif self.azimuth_compact_fraction:
        string = f"\\tfrac{{{'' if p == 1 else p}{constant}}}{{{q}}}"
    else:
        string = f"\\tfrac{{{p}}}{{{q}}}{constant}"
    return MathTex(string, **kwargs)