分组¶

def add_to_back(self, *mobjects: "Mobject") -> Self:
    """在 mobject 已有的子 mobject 之前添加子 mobject：它们绘制在之前的
    之下（在相同 z 索引下）。

    已经是子 mobject 的会移到前面；`add` 拒绝的操作，此方法同样拒绝。

    Args:
        *mobjects: 要添加的 mobject，按顺序排列。
    """
    return self._place(0, mobjects)

def insert(self, index: int, mobject: "Mobject") -> Self:
    """在 mobject 的其他子 mobject 之间某处插入一个子 mobject。

    已经是子 mobject 的会移到该位置；`add` 拒绝的操作，此方法同样拒绝。

    Args:
        index: 其在其他子 mobject 列表中的位置，与 `list.insert`
            接受的方式相同。
        mobject: 要插入的 mobject。
    """
    return self._place(index, (mobject,))

def remove(self, *mobjects: "Mobject") -> Self:
    """移除子 mobject：在 mobject 自身的子 mobject 中（而非其子 mobject 的子 mobject 中）
    与给定者匹配的那些；其余的被忽略。

    Args:
        *mobjects: 要移除的 mobject。
    """
    for m in mobjects:
        if m in self.submobjects:
            self.submobjects.remove(m)
    return self

def get_family(self) -> list["Mobject"]:
    """mobject 及其所有后代：自身，然后依次是每个子 mobject 的家族，
    每个成员出现一次（若树中持有它两次，则在其最后出现的位置）。

    Returns:
        一个新列表。
    """
    if not self.submobjects:
        return [self]
    return _family((self,))

def family_members_with_points(self) -> list["Mobject"]:
    """mobject 家族中拥有自身点的成员：即被绘制的那些。

    Returns:
        一个新列表，按家族顺序排列。
    """
    return [m for m in self.get_family() if m.has_points()]

def arrange(
    self,
    direction: Vector3DLike = RIGHT,
    buff: float = DEFAULT_MOBJECT_TO_MOBJECT_BUFFER,
    center: bool = True,
    **kwargs: Unpack[Beside],
) -> Self:
    """将子 mobject 排成一行：每个在前一个旁边（参见
    [next_to][manimgx.Mobject.next_to]），间距 `buff`；然后将整体居中于
    原点。

    Args:
        direction: 行的方向：RIGHT（默认），DOWN 表示列，…
        buff: 相邻者之间的间距，以场景单位表示（默认 0.25）。
        center: 之后是否将 mobject 居中于原点；若否，
            第一个子 mobject 保持原位。
        **kwargs: [Beside 关键字][manimgx.mobject.Beside]：相邻者如何
            对齐（`aligned_edge=DOWN` 使它们的底部在一条线上）。

    Examples:
        ```python
        import manimgx as m


        class MobjectArrangeExample(m.Scene):
            def construct(self) -> None:
                sizes = (0.5, 1, 2)
                squares = m.VGroup(*(m.Square(s, color=m.BLUE) for s in sizes))
                squares.arrange(buff=0.5, aligned_edge=m.DOWN)
                words = m.VGroup(m.Text("one"), m.Text("three"), m.Text("eleven"))
                words.arrange(m.DOWN, aligned_edge=m.LEFT)
                self.add(m.VGroup(squares, words).arrange(buff=1.5))
        ```
    """
    for m1, m2 in zip(self.submobjects[:-1], self.submobjects[1:], strict=True):
        m2.next_to(m1, direction, buff, **kwargs)
    return self.center() if center else self

def arrange_in_grid(
    self,
    rows: int | None = None,
    cols: int | None = None,
    buff: float | tuple[float, float] = MED_SMALL_BUFF,
    cell_alignment: Vector3DLike = ORIGIN,
    row_alignments: str | None = None,
    col_alignments: str | None = None,
    row_heights: Iterable[float | None] | None = None,
    col_widths: Iterable[float | None] | None = None,
    flow_order: str = "rd",
) -> Self:
    """将子 mobject 排成行列网格，居中于 mobject 原来的位置。

    每行与其最高的 mobject 等高，每列与其最宽的 mobject 等宽，除非另行指定。
    每个 mobject 按 `cell_alignment` 所示位于其单元格中，
    但垂直方向按 `row_alignments` 为其行所示，水平方向按
    `col_alignments` 为其列所示，在已指定的地方。行和列太少
    无法容纳所有子 mobject 时抛出异常。

    Args:
        rows: 行数；None 表示与 `row_alignments` 或 `row_heights`
            列出的数量相同，否则与子 mobject 所需的数量相同。当 `rows` 和
            `cols` 均未指定时，网格尽可能呈正方形。
        cols: 列数；None 表示与 `col_alignments` 或 `col_widths`
            列出的数量相同，否则与子 mobject 所需的数量相同。
        buff: 单元格之间的间距，以场景单位表示：两个方向共用一个值，或
            (水平, 垂直)（默认 0.25）。
        cell_alignment: 每个 mobject 在其单元格中的位置，以方向命名：
            UL 表示其左上角（默认 ORIGIN：居中）。
        row_alignments: 每行的垂直对齐方式，从上到下：每行一个
            字母，"u"（上）、"c"（居中）或 "d"（下）；None：按
            `cell_alignment` 的垂直部分所示（UL：上）。
        col_alignments: 每列的水平对齐方式，从左到右：每列一个
            字母，"l"（左）、"c"（居中）或 "r"（右）；None：按
            `cell_alignment` 的水平部分所示（UL：左）。
        row_heights: 每行的高度，从上到下，以场景单位表示；None（对于
            网格或某行）表示该行最高 mobject 的高度。
        col_widths: 每列的宽度，从左到右，以场景单位表示；None（对于
            网格或某列）表示该列最宽 mobject 的宽度。
        flow_order: 单元格的填充顺序：两个字母，一行单元格的填充方向，
            随后是各行彼此跟随的方向，
            "r"（右）、"l"（左）、"u"（上）或 "d"（下）。默认 "rd" 表示
            行从左到右，从上到下；"dr" 表示列从上到下，
            从左到右。

    Examples:
        ```python
        import manimgx as m


        def cells() -> m.VGroup:
            return m.VGroup(
                *(
                    m.Square(0.9, color=m.BLUE).add(m.Text(str(i), font_size=36))
                    for i in range(1, 11)
                )
            )


        class MobjectArrangeInGridExample(m.Scene):
            def construct(self) -> None:
                by_rows = cells().arrange_in_grid(rows=3, buff=0.2)
                by_cols = cells().arrange_in_grid(rows=3, buff=0.2, flow_order="dr")
                self.add(m.VGroup(by_rows, by_cols).arrange(buff=1.5))
        ```
    """
    mobs = list(self.submobjects)
    start_pos = self.get_center()
    heights_in = list(row_heights) if row_heights is not None else None
    widths_in = list(col_widths) if col_widths is not None else None
    cols = cols or (
        len(col_alignments)
        if col_alignments
        else len(widths_in)
        if widths_in
        else None
    )
    rows = rows or (
        len(row_alignments)
        if row_alignments
        else len(heights_in)
        if heights_in
        else None
    )
    if rows is None:
        cols = math.ceil(math.sqrt(len(mobs))) if cols is None else cols
        rows = math.ceil(len(mobs) / cols)
    elif cols is None:
        cols = math.ceil(len(mobs) / rows)
    if rows * cols < len(mobs):
        raise ValueError("Too few rows and columns to fit all submobjetcs.")
    bx, by = buff if isinstance(buff, tuple) else (buff, buff)
    cell = np.asarray(cell_alignment, dtype=float)
    rdirs = (  # a row aligns its cells vertically, a column horizontally
        [cell * UP] * rows
        if row_alignments is None
        else [{"u": UP, "c": ORIGIN, "d": DOWN}[c] for c in row_alignments]
    )
    cdirs = (
        [cell * RIGHT] * cols
        if col_alignments is None
        else [{"l": LEFT, "c": ORIGIN, "r": RIGHT}[c] for c in col_alignments]
    )
    index = {
        "dr": lambda r, c: rows - r - 1 + c * rows,
        "dl": lambda r, c: rows - r - 1 + (cols - c - 1) * rows,
        "ur": lambda r, c: r + c * rows,
        "ul": lambda r, c: r + (cols - c - 1) * rows,
        "rd": lambda r, c: (rows - r - 1) * cols + c,
        "ld": lambda r, c: (rows - r - 1) * cols + (cols - c - 1),
        "ru": lambda r, c: r * cols + c,
        "lu": lambda r, c: r * cols + (cols - c - 1),
    }[flow_order]
    rdirs.reverse()
    heights_given = list(reversed(heights_in)) if heights_in else [None] * rows
    placeholder = Mobject()
    mobs.extend([placeholder] * (rows * cols - len(mobs)))
    grid = [[mobs[index(r, c)] for c in range(cols)] for r in range(rows)]
    heights = [
        h if h is not None else max(grid[r][c].height for c in range(cols))
        for r, h in enumerate(heights_given)
    ]
    widths = [
        w if w is not None else max(grid[r][c].width for r in range(rows))
        for c, w in enumerate(widths_in or [None] * cols)
    ]
    y = 0.0
    for r in range(rows):
        x = 0.0
        for c in range(cols):
            if grid[r][c] is not placeholder:
                lo, hi = (
                    np.array([x, y, 0.0]),
                    np.array([x + widths[c], y + heights[r], 0.0]),
                )
                align = rdirs[r] + cdirs[c]
                corner = np.where(
                    align < 0, lo, np.where(align > 0, hi, (lo + hi) / 2)
                )
                grid[r][c].move_to(corner, align)
            x += widths[c] + bx
        y += heights[r] + by
    return self.move_to(start_pos)

def sort(
    self,
    point_to_num_func: Callable[[Point3D], float] = lambda p: p[0],
    submob_func: Callable[["Mobject"], float] | None = None,
) -> Self:
    """按数字排序子 mobject：从每个子 mobject 的中心计算（默认
    为其 x 坐标，即从左到右），或从每个子 mobject 本身计算。

    它们的顺序即绘制顺序（在相同 z 索引下），也是
    `lag_ratio` 错开其动画的顺序。

    Args:
        point_to_num_func: 关于子 mobject 中心的函数，给出排序
            所依据的数字。
        submob_func: 关于子 mobject 的函数，给出排序所依据的数字，
            替代 `point_to_num_func`。
    """
    key = submob_func or (lambda m: point_to_num_func(m.get_center()))
    self.submobjects.sort(key=key)
    return self

def shuffle(self, recursive: bool = False) -> Self:
    """将子 mobject 置于随机顺序，从 Python 的 `random` 中抽取。

    Args:
        recursive: 每个子 mobject 的子 mobject 是否也被打乱，
            以及它们的。
    """
    if recursive:
        for sub in self.submobjects:
            sub.shuffle(recursive=True)
    random.shuffle(self.submobjects)
    return self

def invert(self, recursive: bool = False) -> Self:
    """反转子 mobject 的顺序。

    Args:
        recursive: 每个子 mobject 的子 mobject 是否也被反转，
            以及它们的。
    """
    if recursive:
        for sub in self.submobjects:
            sub.invert(recursive=True)
    self.submobjects.reverse()
    return self

def index_labels(
    mobject: Mobject, label_height: float = 0.15, **kwargs: Unpack[NumberStyle]
) -> VGroup:
    r"""为一个 mobject 的子对象编号：在每个子对象中心放置一个
    [Integer][manimgx.Integer]，带深色轮廓，用于查找某个部分的索引。

    一种调试辅助：将标签添加到场景中即可看到它们；它们不跟随该 mobject。

    Args:
        mobject: 其子对象从 0 开始编号的 mobject。
        label_height: 每个标签的高度，以场景单位计。
        **kwargs: [数字关键字][manimgx.mobjects.numbers.NumberStyle]（除非给定，
            否则使用宽度为 5 的黑色背景描边）。

    Returns:
        由标签按顺序组成的新组。

    Examples:
        ```python
        import manimgx as m


        class IndexLabelsExample(m.Scene):
            def construct(self) -> None:
                formula = m.MathTex(r"\binom{2n}{n+2}", font_size=144)
                formula[0][1:3].set_color(m.YELLOW)
                formula[0][3:6].set_color(m.RED)
                self.add(formula, m.index_labels(formula[0], label_height=0.3))
        ```
    """
    kwargs.setdefault("background_stroke_width", 5)
    kwargs.setdefault("background_stroke_color", BLACK)
    labels = VGroup()
    for n, submob in enumerate(mobject):
        label = Integer(n, **kwargs)
        label.height = label_height
        labels.add(label.move_to(submob))
    return labels