Number lines¶

def rotate_about_zero(self, angle: float, axis: Vector3DLike = OUT) -> Self:
    """Turn the line about the point of its number 0.

    Args:
        angle: The angle, in radians, counterclockwise about `axis`.
        axis: The axis of the turn: OUT turns it in the plane of the screen.
    """
    return self.rotate_about_number(0, angle, axis)

def rotate_about_number(
    self, number: float, angle: float, axis: Vector3DLike = OUT
) -> Self:
    """Turn the line about the point of one of its numbers.

    Args:
        number: The number whose point stays fixed.
        angle: The angle, in radians, counterclockwise about `axis`.
        axis: The axis of the turn: OUT turns it in the plane of the screen.
    """
    return self.rotate(angle, axis, about_point=self.n2p(number))

def number_to_point(self, number: float | np.ndarray) -> np.ndarray:
    """Convert a number to its point on the line, or numbers to their points.

    A number outside the range is on the line extended past its ends.

    Args:
        number: The number; or an array of numbers, of any shape.

    Returns:
        The point, in scene coordinates; for an array, the points, with the
        coordinates last (the array's shape, then 3).

    Examples:
        ```python
        import manimgx as m


        class NumberLineNumberToPointExample(m.Scene):
            def construct(self) -> None:
                line = m.NumberLine(
                    x_range=[-4, 4, 1], length=12, include_numbers=True
                )
                dot = m.Dot(line.n2p(-3), radius=0.15, color=m.YELLOW)
                self.add(line, dot)
                self.play(dot.animate.move_to(line.n2p(2.5)))
        ```
    """
    number = self.scaling.inverse_function(np.asarray(number, dtype=float))
    alphas = (number - self.x_range[0]) / (self.x_range[1] - self.x_range[0])
    start, end = self.get_start(), self.get_end()
    a = np.asarray(alphas)[..., None]
    return (1 - a) * start + a * end

def point_to_number(self, point: Point3DLike) -> float:
    """Convert a point to the number at its projection on the line: the inverse of
    [number_to_point][manimgx.NumberLine.number_to_point] for points on the line.

    Args:
        point: The point, in scene coordinates.
    """
    point = np.asarray(point, dtype=float)
    start, end = self.get_start(), self.get_end()
    unit_vect = normalize(end - start)
    proportion: float = np.dot(point - start, unit_vect) / np.dot(
        end - start, unit_vect
    )
    # along the range, then through the scale, as number_to_point goes back
    return self.scaling.function(
        interpolate(self.x_range[0], self.x_range[1], proportion)
    )

def n2p(self, number: float | np.ndarray) -> Point3D:
    """Convert a number to its point on the line:
    [number_to_point][manimgx.NumberLine.number_to_point], by a shorter name.

    Args:
        number: The number; or an array of numbers, of any shape.

    Returns:
        The point, in scene coordinates; or the points.
    """
    return self.number_to_point(number)

def get_unit_size(self) -> float:
    """The length of one unit of the line: its length over its range.

    Returns:
        The length, in scene units (of one unit of exponent, on a logarithmic
        line).
    """
    val: float = self.get_length() / (self.x_range[1] - self.x_range[0])
    return val

def get_unit_vector(self) -> Vector3D:
    """The line's direction, one unit long: the vector from its start toward its
    end, as long as the unit the line was made with (its `unit_size`).

    Returns:
        The vector, in scene units.
    """
    return super().get_unit_vector() * self.unit_size

def get_number_mobject(
    self,
    x: float,
    direction: Vector3DLike | None = None,
    buff: float | None = None,
    label_constructor: type[ManimTextLabel] | None = None,
    **number_config: Unpack[DecimalNumberOptions],
) -> VMobject:
    """Make a number, written beside its point on the line.

    It is a [DecimalNumber][manimgx.DecimalNumber] in the line's number style (its
    `decimal_number_config` and `font_size`), with `number_config` over it. A
    negative number written straight below or above the line is shifted so its
    digits, not its minus sign, are centered on the point.

    Args:
        x: The number.
        direction: The side of the line it goes on; None for the line's
            `label_direction`.
        buff: The gap between the line and the number, in scene units; None for the
            line's `line_to_number_buff`.
        label_constructor: The class it is typeset with; None for the line's.
        **number_config: [Number keywords][manimgx.DecimalNumber],
            over the line's.

    Returns:
        A new number, not added to the line.
    """
    options = self.decimal_number_config | number_config
    options.setdefault("font_size", self.font_size)
    options["mob_class"] = label_constructor or self.label_constructor
    num_mob = DecimalNumber(x, **options)
    num_mob.next_to(
        self.number_to_point(x),
        direction=self.label_direction if direction is None else direction,
        buff=self.line_to_number_buff if buff is None else buff,
    )
    if x < 0 and self.label_direction[0] == 0:
        num_mob.shift(num_mob[0].width * LEFT / 2)
    return num_mob

def add_numbers(
    self,
    x_values: Iterable[float] | None = None,
    excluding: Iterable[float] | None = None,
    label_constructor: type[ManimTextLabel] | None = None,
    **kwargs: Unpack[DecimalNumberOptions],
) -> Self:
    """Number the line: write numbers beside the points of the given values, or of
    its ticks.

    Each number is written as
    [get_number_mobject][manimgx.NumberLine.get_number_mobject] writes it. The
    numbers are a group added to the line, and kept as its `numbers`.

    Args:
        x_values: The numbers to write; None for the ticks' numbers.
        excluding: Numbers not to write; None for the line's `numbers_to_exclude`.
        label_constructor: The class they are typeset with; None for the line's.
        **kwargs: [Number keywords][manimgx.DecimalNumber],
            over the line's: `font_size`, `num_decimal_places`, `color`, ….

    Examples:
        ```python
        import manimgx as m


        class NumberLineAddNumbersExample(m.Scene):
            def construct(self) -> None:
                ticks = m.NumberLine(x_range=[0, 10, 1], length=12).add_numbers()
                chosen = m.NumberLine(x_range=[0, 10, 1], length=12, color=m.BLUE)
                chosen.add_numbers(
                    [0, 2.5, 5, 7.5, 10], num_decimal_places=1, color=m.BLUE
                )
                self.add(m.VGroup(ticks, chosen).arrange(m.DOWN, buff=1.5))
        ```
    """
    if x_values is None:
        x_values = self.get_tick_range()
    excluded = list(self.numbers_to_exclude if excluding is None else excluding)
    numbers = VGroup()
    for x in x_values:
        if x in excluded:
            continue
        numbers.add(
            self.get_number_mobject(
                x, label_constructor=label_constructor, **kwargs
            )
        )
    self.add(numbers)
    self.numbers = numbers
    return self

def add_labels(
    self,
    dict_values: Mapping[float, Label],
    direction: Point3DLike | None = None,
    buff: float | None = None,
    font_size: float | None = None,
    label_constructor: type[ManimTextLabel] | None = None,
) -> Self:
    r"""Label the line: put each label beside the point of its number.

    A string is typeset as text with [Tex][manimgx.Tex] when the constructor is
    [MathTex][manimgx.MathTex] (as by default), and with the constructor otherwise;
    a number is written with the constructor. A mobject is used as it is, and must
    be typeset (a [Typst][manimgx.Typst] mobject: [Text][manimgx.Text],
    [Tex][manimgx.Tex], [MathTex][manimgx.MathTex], …) or a
    [DecimalNumber][manimgx.DecimalNumber]: another raises an exception. Every label
    is set to `font_size`. The labels are a group added to the line, and kept as its
    `labels`.

    Args:
        dict_values: The labels, by number.
        direction: The side of the line they go on, as a direction; None for the
            line's `label_direction`.
        buff: The gap between the line and the labels, in scene units; None for the
            line's `line_to_number_buff`.
        font_size: The labels' font size; None for the line's.
        label_constructor: The class strings and numbers are typeset with; None for
            the line's.

    Examples:
        ```python
        import manimgx as m


        class NumberLineAddLabelsExample(m.Scene):
            def construct(self) -> None:
                line = m.NumberLine(x_range=[0, m.TAU, m.PI / 2], length=12)
                line.add_labels(
                    {
                        0: "0",
                        m.PI / 2: m.MathTex(r"\frac{\pi}{2}"),
                        m.PI: m.MathTex(r"\pi"),
                        3 * m.PI / 2: m.MathTex(r"\frac{3\pi}{2}"),
                        m.TAU: m.MathTex(r"2\pi"),
                    },
                    font_size=44,
                )
                self.add(line)
        ```
    """
    direction = self.label_direction if direction is None else direction
    buff = self.line_to_number_buff if buff is None else buff
    font_size = self.font_size if font_size is None else font_size
    if label_constructor is None:
        label_constructor = self.label_constructor
    labels = VGroup()
    for x, label in dict_values.items():
        if isinstance(label, str):
            if label_constructor is MathTex:
                label = Tex(label)
            else:
                label = self._create_label_tex(label, label_constructor)
        else:
            label = self._create_label_tex(label, label_constructor)
        if not isinstance(
            label, (Typst, DecimalNumber)
        ):  # its type size can be set
            raise AttributeError(f"{label} is not compatible with add_labels.")
        label.font_size = font_size
        label.next_to(self.number_to_point(x), direction=direction, buff=buff)
        labels.add(label)
    self.labels = labels
    self.add(labels)
    return self

def function(self, value: float | np.ndarray) -> float | np.ndarray:
    """The number of the axis at a value of its range: 10² for 2, on a logarithmic
    axis.

    Args:
        value: The value of the range; or an array of values.

    Returns:
        The number; or the numbers, an array of the same shape.
    """
    return self._function(value)

def inverse_function(self, value: float | np.ndarray) -> float | np.ndarray:
    """The value of the axis's range at one of its numbers: 2 for 100, on a
    logarithmic axis; the inverse of `function`.

    Args:
        value: The number; or an array of numbers.

    Returns:
        The value of the range; or the values, an array of the same shape.
    """
    return self._inverse_function(value)

def function(self, value: float | np.ndarray) -> float | np.ndarray:
    """The number of the axis at a value of its range: 10² for 2, on a logarithmic
    axis.

    Args:
        value: The value of the range; or an array of values.

    Returns:
        The number; or the numbers, an array of the same shape.
    """
    return self._function(value)

def inverse_function(self, value: float | np.ndarray) -> float | np.ndarray:
    """The value of the axis's range at one of its numbers: 2 for 100, on a
    logarithmic axis; the inverse of `function`.

    Args:
        value: The number; or an array of numbers.

    Returns:
        The value of the range; or the values, an array of the same shape.
    """
    return self._inverse_function(value)