Groups¶

def add_to_back(self, *mobjects: "Mobject") -> Self:
    """Add submobjects before the ones the mobject has: they are drawn under them
    (at an equal z-index).

    A mobject that is a submobject already moves to the front; what `add` refuses,
    this refuses too.

    Args:
        *mobjects: The mobjects to add, in order.
    """
    return self._place(0, mobjects)

def insert(self, index: int, mobject: "Mobject") -> Self:
    """Insert a submobject at a place among the mobject's other submobjects.

    A mobject that is a submobject already moves there; what `add` refuses, this
    refuses too.

    Args:
        index: Its place in the list of the other submobjects, as `list.insert`
            takes it.
        mobject: The mobject to insert.
    """
    return self._place(index, (mobject,))

def remove(self, *mobjects: "Mobject") -> Self:
    """Remove submobjects: those given that are among the mobject's own submobjects
    (not its submobjects' submobjects); the rest are ignored.

    Args:
        *mobjects: The mobjects to remove.
    """
    for m in mobjects:
        if m in self.submobjects:
            self.submobjects.remove(m)
    return self

def get_family(self) -> list["Mobject"]:
    """The mobject and all its descendants: itself, then each submobject's family in
    turn, each member once (where it last occurs, if the tree holds it twice).

    Returns:
        A new list.
    """
    if not self.submobjects:
        return [self]
    return _family((self,))

def family_members_with_points(self) -> list["Mobject"]:
    """The members of the mobject's family that have points of their own: the ones
    that are drawn.

    Returns:
        A new list, in family order.
    """
    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:
    """Lay the submobjects out in a row: each one beside the one before it (see
    [next_to][manimgx.Mobject.next_to]), `buff` apart; then center the whole at the
    origin.

    Args:
        direction: The way the row goes: RIGHT (default), DOWN for a column, …
        buff: The gap between neighbours, in scene units (default 0.25).
        center: Whether to center the mobject at the origin afterwards; if not, the
            first submobject stays where it was.
        **kwargs: [Beside keywords][manimgx.mobject.Beside]: how neighbours
            line up (`aligned_edge=DOWN` puts their bottoms on one line).

    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:
    """Lay the submobjects out in a grid of rows and columns, centered where the
    mobject was.

    Each row is as tall as its tallest mobject and each column as wide as its
    widest, unless given. Each mobject sits in its cell as `cell_alignment` says,
    but vertically as `row_alignments` says for its row and horizontally as
    `col_alignments` says for its column, where they are given. Too few rows and
    columns for the submobjects raise an exception.

    Args:
        rows: How many rows; None for as many as `row_alignments` or `row_heights`
            lists, else as many as the submobjects need. With neither `rows` nor
            `cols`, the grid is as square as it can be.
        cols: How many columns; None for as many as `col_alignments` or `col_widths`
            lists, else as many as the submobjects need.
        buff: The gap between cells, in scene units: one for both directions, or
            (horizontal, vertical) (default 0.25).
        cell_alignment: Where each mobject sits in its cell, named by a direction:
            UL for its top left corner (default ORIGIN: centered).
        row_alignments: Each row's vertical alignment, top to bottom: a letter per
            row, "u" (up), "c" (center) or "d" (down); None: as the vertical part of
            `cell_alignment` says (UL: up).
        col_alignments: Each column's horizontal alignment, left to right: a letter
            per column, "l" (left), "c" (center) or "r" (right); None: as the
            horizontal part of `cell_alignment` says (UL: left).
        row_heights: Each row's height, top to bottom, in scene units; None (for the
            grid or a row) for the height of the row's tallest mobject.
        col_widths: Each column's width, left to right, in scene units; None (for
            the grid or a column) for the width of the column's widest mobject.
        flow_order: The order the cells are filled in: two letters, the direction a
            line of cells fills and then the direction the lines follow each other,
            "r" (right), "l" (left), "u" (up) or "d" (down). The default "rd" fills
            rows left to right, from the top down; "dr" fills columns top to bottom,
            from the left.

    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:
    """Sort the submobjects by a number: one computed from each one's center (by
    default its x coordinate, so left to right), or from each one itself.

    Their order is the order they are drawn in (at an equal z-index), and the order
    a `lag_ratio` staggers their animation in.

    Args:
        point_to_num_func: A function of a submobject's center, giving the number to
            sort it by.
        submob_func: A function of a submobject, giving the number to sort it by, in
            place of `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:
    """Put the submobjects in a random order, drawn from Python's `random`.

    Args:
        recursive: Whether each submobject's submobjects are shuffled too, and
            theirs.
    """
    if recursive:
        for sub in self.submobjects:
            sub.shuffle(recursive=True)
    random.shuffle(self.submobjects)
    return self

def invert(self, recursive: bool = False) -> Self:
    """Reverse the order of the submobjects.

    Args:
        recursive: Whether each submobject's submobjects are reversed too, and
            theirs.
    """
    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"""Number the submobjects of a mobject: an [Integer][manimgx.Integer] at the center
    of each, on a dark outline, to find a part's index.

    A debugging help: add the labels to the scene to see them; they don't follow the
    mobject.

    Args:
        mobject: The mobject whose submobjects are numbered, from 0.
        label_height: Each label's height, in scene units.
        **kwargs: [Number keywords][manimgx.mobjects.numbers.NumberStyle] (a black
            background stroke 5 wide unless given).

    Returns:
        A new group of the labels, in order.

    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