数轴¶

def rotate_about_zero(self, angle: float, axis: Vector3DLike = OUT) -> Self:
    """将数轴绕其数字 0 的点旋转。

    Args:
        angle: 角度，以弧度计，绕 `axis` 逆时针方向。
        axis: 旋转的轴：OUT 使其在屏幕平面内旋转。
    """
    return self.rotate_about_number(0, angle, axis)

def rotate_about_number(
    self, number: float, angle: float, axis: Vector3DLike = OUT
) -> Self:
    """将数轴绕其某个数字的点旋转。

    Args:
        number: 其点保持不变的数字。
        angle: 角度，以弧度计，绕 `axis` 逆时针方向。
        axis: 旋转的轴：OUT 使其在屏幕平面内旋转。
    """
    return self.rotate(angle, axis, about_point=self.n2p(number))

def number_to_point(self, number: float | np.ndarray) -> np.ndarray:
    """将数字转换为其在数轴上的点，或将数字转换为其点。

    范围外的数字位于数轴向两端延伸的部分。

    Args:
        number: 数字；或任意形状的数字数组。

    Returns:
        点，在场景坐标系中；对于数组，为点，坐标在最后（数组的形状，然后 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:
    """将点转换为其在数轴上投影处的数字：对于数轴上的点，是 [number_to_point][manimgx.NumberLine.number_to_point] 的反函数。

    Args:
        point: 点，在场景坐标系中。
    """
    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:
    """将数字转换为其在数轴上的点：[number_to_point][manimgx.NumberLine.number_to_point] 的简写名。

    Args:
        number: 数字；或任意形状的数字数组。

    Returns:
        点，在场景坐标系中；或点。
    """
    return self.number_to_point(number)

def get_unit_size(self) -> float:
    """数轴一个单位的长度：其长度除以其范围。

    Returns:
        长度，以场景单位计（对数数轴上为指数单位的长度）。
    """
    val: float = self.get_length() / (self.x_range[1] - self.x_range[0])
    return val

def get_unit_vector(self) -> Vector3D:
    """数轴的方向，一个单位长：从其起点指向终点的向量，长度为数轴创建时的单位（其 `unit_size`）。

    Returns:
        向量，以场景单位计。
    """
    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:
    """制作一个数字，写在其数轴上的点旁。

    它是一个 [DecimalNumber][manimgx.DecimalNumber]，采用数轴的数字样式（其 `decimal_number_config` 和 `font_size`），并用 `number_config` 覆盖。直接写在数轴下方或上方的负数会被移位，使其数字而非负号居中于该点。

    Args:
        x: 数字。
        direction: 数字位于数轴的哪一侧；None 表示数轴的 `label_direction`。
        buff: 数轴与数字之间的间距，以场景单位计；None 表示数轴的 `line_to_number_buff`。
        label_constructor: 其排版类；None 表示数轴的。
        **number_config: [数字关键字][manimgx.DecimalNumber]，覆盖数轴的。

    Returns:
        一个新的数字，未添加到数轴。
    """
    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:
    """为数轴编号：在给定值的点旁写数字，或在其刻度处写。

    每个数字按 [get_number_mobject][manimgx.NumberLine.get_number_mobject] 的书写方式书写。数字是一个组，添加到数轴，并保留为其 `numbers`。

    Args:
        x_values: 要写的数字；None 表示刻度的数字。
        excluding: 不写的数字；None 表示数轴的 `numbers_to_exclude`。
        label_constructor: 它们的排版类；None 表示数轴的。
        **kwargs: [数字关键字][manimgx.DecimalNumber]，覆盖数轴的：`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"""为数轴加标签：将每个标签放在其数字的点旁。

    字符串在构造函数为 [MathTex][manimgx.MathTex]（默认情况）时用 [Tex][manimgx.Tex] 排版为文本，否则用构造函数排版；数字用构造函数书写。mobject 按原样使用，且必须是已排版的（一个 [Typst][manimgx.Typst] mobject：[Text][manimgx.Text]、[Tex][manimgx.Tex]、[MathTex][manimgx.MathTex]、…）或一个 [DecimalNumber][manimgx.DecimalNumber]：其他会引发异常。每个标签设置为 `font_size`。标签是一个组，添加到数轴，并保留为其 `labels`。

    Args:
        dict_values: 标签，按数字。
        direction: 标签位于数轴的哪一侧，作为方向；None 表示数轴的 `label_direction`。
        buff: 数轴与标签之间的间距，以场景单位计；None 表示数轴的 `line_to_number_buff`。
        font_size: 标签的字号；None 表示数轴的。
        label_constructor: 字符串和数字的排版类；None 表示数轴的。

    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:
    """坐标轴的值在其范围某值处的数字：在对数坐标轴上，2 对应 10²。

    Args:
        value: 范围的值；或值的数组。

    Returns:
        数字；或数字，即相同形状的数组。
    """
    return self._function(value)

def inverse_function(self, value: float | np.ndarray) -> float | np.ndarray:
    """坐标轴的范围在其某个数字处的值：在对数坐标轴上，100 对应 2；即 `function` 的反函数。

    Args:
        value: 数字；或数字的数组。

    Returns:
        范围的值；或范围的值，即相同形状的数组。
    """
    return self._inverse_function(value)

def function(self, value: float | np.ndarray) -> float | np.ndarray:
    """坐标轴的值在其范围某值处的数字：在对数坐标轴上，2 对应 10²。

    Args:
        value: 范围的值；或值的数组。

    Returns:
        数字；或数字，即相同形状的数组。
    """
    return self._function(value)

def inverse_function(self, value: float | np.ndarray) -> float | np.ndarray:
    """坐标轴的范围在其某个数字处的值：在对数坐标轴上，100 对应 2；即 `function` 的反函数。

    Args:
        value: 数字；或数字的数组。

    Returns:
        范围的值；或范围的值，即相同形状的数组。
    """
    return self._inverse_function(value)