Mathematical Objects

class Mobject:
    """
    Base class for all mathematical objects that can be displayed and animated.
    
    Provides fundamental positioning, transformation, and animation capabilities
    that all visual elements inherit from.
    """
    
    def __init__(
        color: str = WHITE,
        name: str = None,
        dim: int = 3,
        target: Mobject = None
    ) -> None:
        """
        Parameters:
        - color: Default color for the mobject
        - name: Optional name for debugging
        - dim: Dimensionality (2 or 3)
        - target: Target mobject for transformations
        """
    
    # Position and transformation methods
    def shift(vector: np.ndarray) -> Self:
        """Move mobject by the given vector offset."""
    
    def move_to(
        point_or_mobject: np.ndarray | Mobject,
        aligned_edge: np.ndarray = ORIGIN,
        coor_mask: np.ndarray = np.array([1, 1, 1])
    ) -> Self:
        """Move mobject so point_or_mobject is at its center or aligned edge."""
    
    def rotate(
        angle: float,
        axis: np.ndarray = OUT,
        about_point: np.ndarray = None,
        **kwargs
    ) -> Self:
        """Rotate mobject by angle around axis through about_point."""
    
    def scale(
        scale_factor: float,
        **kwargs
    ) -> Self:
        """Scale mobject by scale_factor around its center or specified point."""
    
    def stretch(
        factor: float,
        dim: int,
        **kwargs
    ) -> Self:
        """Stretch mobject by factor along specified dimension (0=x, 1=y, 2=z)."""
    
    def flip(axis: np.ndarray = RIGHT, **kwargs) -> Self:
        """Flip mobject across the given axis."""
    
    # Position query methods
    def get_center() -> np.ndarray:
        """Get center point of mobject."""
    
    def get_corner(direction: np.ndarray) -> np.ndarray:
        """Get corner of mobject in given direction."""
    
    def get_edge_center(direction: np.ndarray) -> np.ndarray:
        """Get center of edge in given direction."""
    
    def get_boundary_point(direction: np.ndarray) -> np.ndarray:
        """Get point on boundary in given direction."""
    
    # Relative positioning methods
    def next_to(
        mobject_or_point: Mobject | np.ndarray,
        direction: np.ndarray = RIGHT,
        buff: float = DEFAULT_MOBJECT_TO_MOBJECT_BUFFER,
        aligned_edge: np.ndarray = ORIGIN,
        submobject_to_align: Mobject = None,
        index_of_submobject_to_align: int = None,
        coor_mask: np.ndarray = np.array([1, 1, 1])
    ) -> Self:
        """
        Position this mobject next to another mobject or point.
        
        Parameters:
        - mobject_or_point: Reference object or point
        - direction: Direction to place mobject (UP, DOWN, LEFT, RIGHT, etc.)
        - buff: Buffer distance between objects
        - aligned_edge: Which edge to align with reference
        - submobject_to_align: Specific submobject to use for alignment
        - index_of_submobject_to_align: Index of submobject to align
        - coor_mask: Mask for which coordinates to consider
        """
    
    def to_corner(corner: np.ndarray = DL, buff: float = DEFAULT_MOBJECT_TO_EDGE_BUFFER) -> Self:
        """Move mobject to specified corner of the frame."""
    
    def to_edge(edge: np.ndarray = LEFT, buff: float = DEFAULT_MOBJECT_TO_EDGE_BUFFER) -> Self:
        """Move mobject to specified edge of the frame."""
    
    # Submobject management
    def add(*mobjects: Mobject) -> Self:
        """Add mobjects as submobjects of this mobject."""
    
    def remove(*mobjects: Mobject) -> Self:
        """Remove mobjects from this mobject's submobjects."""
    
    def get_submobjects() -> list[Mobject]:
        """Get list of direct submobjects."""
    
    def get_family() -> list[Mobject]:
        """Get this mobject and all its descendants."""
    
    # Animation and updater methods
    def add_updater(
        update_function: Callable,
        index: int = None,
        call_updater: bool = True
    ) -> Self:
        """
        Add function to be called every frame to update this mobject.
        
        Parameters:
        - update_function: Function taking mobject and optionally dt as parameters
        - index: Position to insert updater in list
        - call_updater: Whether to call updater immediately
        """
    
    def remove_updater(update_function: Callable) -> Self:
        """Remove updater function."""
    
    def suspend_updating(recursive: bool = True) -> Self:
        """Temporarily stop calling updaters."""
    
    def resume_updating(recursive: bool = True) -> Self:
        """Resume calling updaters."""
    
    # State management
    def save_state(use_deepcopy: bool = False) -> Self:
        """Save current state for later restoration."""
    
    def restore() -> Self:
        """Restore to previously saved state."""
    
    # Animation property access
    @property
    def animate() -> _AnimationBuilder:
        """Access to animation builder for fluent animation syntax."""
    
    def copy() -> Self:
        """Create a deep copy of this mobject."""

class VMobject(Mobject):
    """
    Vector-based mobject using Bézier curves for smooth, scalable graphics.
    
    The primary mobject type for 2D graphics, providing stroke, fill,
    and path-based rendering with mathematical precision.
    """
    
    def __init__(
        fill_color: str = None,
        fill_opacity: float = 0.0,
        stroke_color: str = None,
        stroke_opacity: float = 1.0,
        stroke_width: float = DEFAULT_STROKE_WIDTH,
        background_stroke_color: str = BLACK,
        background_stroke_opacity: float = 1.0,
        background_stroke_width: float = 0,
        sheen_factor: float = 0.0,
        sheen_direction: np.ndarray = UL,
        close_new_points: bool = False,
        pre_function_handle_to_anchor_scale_factor: float = 0.01,
        make_smooth_after_applying_functions: bool = False,
        **kwargs
    ) -> None:
        """
        Parameters:
        - fill_color: Interior color
        - fill_opacity: Interior opacity (0=transparent, 1=opaque)
        - stroke_color: Outline color
        - stroke_opacity: Outline opacity
        - stroke_width: Outline thickness
        - background_stroke_color: Background outline color
        - background_stroke_opacity: Background outline opacity
        - background_stroke_width: Background outline thickness
        - sheen_factor: Glossy reflection amount
        - sheen_direction: Direction of glossy reflection
        - close_new_points: Whether to close paths automatically
        - pre_function_handle_to_anchor_scale_factor: Bézier handle scaling
        - make_smooth_after_applying_functions: Auto-smooth after transformations
        """
    
    # Style methods
    def set_color(color: str) -> Self:
        """Set both fill and stroke color."""
    
    def set_fill(
        color: str = None,
        opacity: float = None,
        family: bool = True
    ) -> Self:
        """
        Set fill properties.
        
        Parameters:
        - color: Fill color
        - opacity: Fill opacity
        - family: Whether to apply to submobjects
        """
    
    def set_stroke(
        color: str = None,
        width: float = None,
        opacity: float = None,
        background: bool = False,
        family: bool = True
    ) -> Self:
        """
        Set stroke properties.
        
        Parameters:
        - color: Stroke color
        - width: Stroke width
        - opacity: Stroke opacity
        - background: Whether to set background stroke
        - family: Whether to apply to submobjects
        """
    
    def set_style(
        fill_color: str = None,
        fill_opacity: float = None,
        stroke_color: str = None,
        stroke_width: float = None,
        stroke_opacity: float = None,
        family: bool = True
    ) -> Self:
        """Set multiple style properties at once."""
    
    def get_fill_color() -> str:
        """Get current fill color."""
    
    def get_stroke_color() -> str:
        """Get current stroke color."""
    
    def get_stroke_width() -> float:
        """Get current stroke width."""
    
    # Path manipulation methods
    def set_points(points: np.ndarray) -> Self:
        """Set the path points directly."""
    
    def set_points_as_corners(points: np.ndarray) -> Self:
        """Set points as corners with straight line segments."""
    
    def set_points_smoothly(points: np.ndarray) -> Self:
        """Set points with smooth Bézier curve interpolation."""
    
    def add_line_to(point: np.ndarray) -> Self:
        """Add straight line to specified point."""
    
    def add_smooth_curve_to(*points: np.ndarray) -> Self:
        """Add smooth curve through specified points."""
    
    def close_path() -> Self:
        """Close the current path by connecting end to start."""
    
    def get_points() -> np.ndarray:
        """Get array of all path points."""
    
    def get_start() -> np.ndarray:
        """Get starting point of path."""
    
    def get_end() -> np.ndarray:
        """Get ending point of path."""
    
    def get_anchors() -> np.ndarray:
        """Get anchor points (excluding Bézier control points)."""

class Group(Mobject):
    """
    Container for grouping multiple mobjects together.
    
    Provides collective operations on multiple objects while maintaining
    their individual properties and behaviors.
    """
    
    def __init__(*mobjects: Mobject, **kwargs) -> None:
        """
        Parameters:
        - *mobjects: Mobjects to include in the group
        """
    
    def arrange(
        direction: np.ndarray = RIGHT,
        buff: float = DEFAULT_MOBJECT_TO_MOBJECT_BUFFER,
        center: bool = True,
        **kwargs
    ) -> Self:
        """
        Arrange submobjects in a line.
        
        Parameters:
        - direction: Direction to arrange along
        - buff: Buffer space between objects
        - center: Whether to center the arrangement
        """
    
    def arrange_in_grid(
        rows: int = None,
        cols: int = None,
        buff: float = MED_SMALL_BUFF,
        cell_alignment: np.ndarray = ORIGIN,
        row_alignments: str = "c",
        col_alignments: str = "c",
        row_heights: list[float] = None,
        col_widths: list[float] = None,
        flow_order: str = "rd",
        **kwargs
    ) -> Self:
        """
        Arrange submobjects in a grid layout.
        
        Parameters:
        - rows: Number of rows (auto-calculated if None)
        - cols: Number of columns (auto-calculated if None)
        - buff: Buffer space between objects
        - cell_alignment: Alignment within each cell
        - row_alignments: Alignment for each row ("c", "l", "r")
        - col_alignments: Alignment for each column
        - row_heights: Height of each row
        - col_widths: Width of each column
        - flow_order: Fill order ("rd"=right-down, "dr"=down-right)
        """

class VGroup(VMobject, Group):
    """
    Group of VMobjects that can be styled collectively.
    
    Combines the grouping functionality of Group with the styling
    capabilities of VMobject.
    """
    
    def __init__(*vmobjects: VMobject, **kwargs) -> None:
        """
        Parameters:
        - *vmobjects: VMobjects to include in the group
        """

# Circles and Arcs
def Circle(
    radius: float = 1.0,
    color: str = RED,
    **kwargs
) -> Circle:
    """
    Perfect circle with specified radius.
    
    Parameters:
    - radius: Circle radius
    - color: Circle color
    """

def Arc(
    radius: float = 1.0,
    start_angle: float = 0,
    angle: float = TAU / 4,
    arc_center: np.ndarray = ORIGIN,
    **kwargs
) -> Arc:
    """
    Circular arc segment.
    
    Parameters:
    - radius: Arc radius
    - start_angle: Starting angle in radians
    - angle: Arc span in radians
    - arc_center: Center point of arc
    """

def Dot(
    point: np.ndarray = ORIGIN,
    radius: float = DEFAULT_DOT_RADIUS,
    stroke_width: float = 0,
    fill_opacity: float = 1.0,
    color: str = WHITE,
    **kwargs
) -> Dot:
    """
    Small filled circle, typically used as a point indicator.
    
    Parameters:
    - point: Position of the dot
    - radius: Dot radius
    - stroke_width: Outline width (0 for no outline)
    - fill_opacity: Fill opacity
    - color: Dot color
    """

def Ellipse(
    width: float = 2,
    height: float = 1,
    **kwargs
) -> Ellipse:
    """
    Elliptical shape with specified width and height.
    
    Parameters:
    - width: Ellipse width
    - height: Ellipse height
    """

def Annulus(
    inner_radius: float = 1,
    outer_radius: float = 2,
    **kwargs
) -> Annulus:
    """
    Ring shape (annulus) between two concentric circles.
    
    Parameters:
    - inner_radius: Inner circle radius
    - outer_radius: Outer circle radius
    """

def Sector(
    outer_radius: float = 1,
    inner_radius: float = 0,
    angle: float = TAU / 4,
    start_angle: float = 0,
    arc_center: np.ndarray = ORIGIN,
    **kwargs
) -> Sector:
    """
    Circular sector (pie slice) shape.
    
    Parameters:
    - outer_radius: Outer radius
    - inner_radius: Inner radius (0 for full sector)
    - angle: Sector angle in radians
    - start_angle: Starting angle in radians
    - arc_center: Center point
    """

# Lines and Polygons
def Line(
    start: np.ndarray = LEFT,
    end: np.ndarray = RIGHT,
    buff: float = 0,
    path_arc: float = None,
    **kwargs
) -> Line:
    """
    Straight line segment between two points.
    
    Parameters:
    - start: Starting point
    - end: Ending point
    - buff: Buffer distance from endpoints
    - path_arc: Arc curvature (None for straight line)
    """

def DashedLine(
    *args,
    dash_length: float = DEFAULT_DASH_LENGTH,
    dashed_ratio: float = 0.5,
    **kwargs
) -> DashedLine:
    """
    Dashed line with customizable dash pattern.
    
    Parameters:
    - dash_length: Length of each dash
    - dashed_ratio: Ratio of dash to gap (0.5 = equal dash and gap)
    """

def Arrow(
    start: np.ndarray = LEFT,
    end: np.ndarray = RIGHT,
    buff: float = MED_SMALL_BUFF,
    stroke_width: float = 6,
    tip_length: float = 0.35,
    max_stroke_width_to_length_ratio: float = 5,
    max_tip_length_to_length_ratio: float = 0.5,
    **kwargs
) -> Arrow:
    """
    Arrow with customizable arrowhead.
    
    Parameters:
    - start: Arrow start point
    - end: Arrow end point
    - buff: Buffer from start/end points
    - stroke_width: Arrow shaft thickness
    - tip_length: Arrowhead length
    - max_stroke_width_to_length_ratio: Max stroke width ratio
    - max_tip_length_to_length_ratio: Max tip length ratio
    """

def Vector(
    direction: np.ndarray = RIGHT,
    buff: float = 0,
    **kwargs
) -> Vector:
    """
    Vector arrow starting from origin.
    
    Parameters:
    - direction: Vector direction and magnitude
    - buff: Buffer from origin
    """

def DoubleArrow(
    *args,
    **kwargs
) -> DoubleArrow:
    """Arrow with arrowheads on both ends."""

# Polygons
def Rectangle(
    height: float = 2.0,
    width: float = 4.0,
    **kwargs
) -> Rectangle:
    """
    Rectangular shape.
    
    Parameters:
    - height: Rectangle height
    - width: Rectangle width
    """

def Square(
    side_length: float = 2.0,
    **kwargs
) -> Square:
    """
    Square with equal sides.
    
    Parameters:
    - side_length: Length of each side
    """

def RoundedRectangle(
    height: float = 2.0,
    width: float = 4.0,
    corner_radius: float = 0.5,
    **kwargs
) -> RoundedRectangle:
    """
    Rectangle with rounded corners.
    
    Parameters:
    - height: Rectangle height
    - width: Rectangle width
    - corner_radius: Radius of rounded corners
    """

def Triangle(
    **kwargs
) -> Triangle:
    """Equilateral triangle."""

def Polygon(
    *vertices: np.ndarray,
    **kwargs
) -> Polygon:
    """
    Polygon defined by vertex coordinates.
    
    Parameters:
    - *vertices: Vertex coordinates as numpy arrays
    """

def RegularPolygon(
    n: int = 6,
    radius: float = 1,
    start_angle: float = 0,
    **kwargs
) -> RegularPolygon:
    """
    Regular polygon with n sides.
    
    Parameters:
    - n: Number of sides
    - radius: Circumscribed circle radius
    - start_angle: Rotation of first vertex
    """

# Curves
def CubicBezier(
    start_anchor: np.ndarray,
    start_handle: np.ndarray,
    end_handle: np.ndarray,
    end_anchor: np.ndarray,
    **kwargs
) -> CubicBezier:
    """
    Cubic Bézier curve with control points.
    
    Parameters:
    - start_anchor: Starting point
    - start_handle: Starting control point
    - end_handle: Ending control point
    - end_anchor: Ending point
    """

def CurvedArrow(
    start_point: np.ndarray,
    end_point: np.ndarray,
    radius: float = -2.0,
    **kwargs
) -> CurvedArrow:
    """
    Curved arrow along circular arc.
    
    Parameters:
    - start_point: Arrow start
    - end_point: Arrow end
    - radius: Curvature radius (negative for clockwise)
    """

def Text(
    text: str,
    fill_opacity: float = 1.0,
    stroke_width: float = 0,
    font_size: float = 48,
    line_spacing: float = -1,
    font: str = '',
    slant: str = "NORMAL",
    weight: str = "NORMAL",
    t2c: dict = None,
    t2f: dict = None,
    t2g: dict = None,
    t2s: dict = None,
    t2w: dict = None,
    gradient: tuple = None,
    tab_width: int = 4,
    height: float = None,
    width: float = None,
    should_center: bool = True,
    unpack_groups: bool = True,
    disable_ligatures: bool = False,
    warn_missing_font: bool = True,
    **kwargs
) -> Text:
    """
    Text rendered using system fonts with Pango library.
    
    Supports international characters, font styling, and per-character formatting.
    
    Parameters:
    - text: Text string to render
    - fill_opacity: Text opacity
    - stroke_width: Text outline width
    - font_size: Font size in points
    - line_spacing: Line spacing multiplier (-1 for auto)
    - font: Font family name
    - slant: Font slant ("NORMAL", "ITALIC", "OBLIQUE")
    - weight: Font weight ("NORMAL", "BOLD", etc.)
    - t2c: Text-to-color mapping dict
    - t2f: Text-to-font mapping dict
    - t2g: Text-to-gradient mapping dict
    - t2s: Text-to-slant mapping dict
    - t2w: Text-to-weight mapping dict
    - gradient: Color gradient tuple
    - tab_width: Tab character width
    - height: Target height (auto-scales font)
    - width: Target width (auto-scales font)
    - should_center: Whether to center text
    - unpack_groups: Whether to unpack character groups
    - disable_ligatures: Whether to disable font ligatures
    - warn_missing_font: Whether to warn about missing fonts
    """

def MarkupText(
    text: str,
    **kwargs
) -> MarkupText:
    """
    Text with Pango markup formatting support.
    
    Supports HTML-like markup for rich text formatting within a single string.
    
    Parameters:
    - text: Text with Pango markup tags
    """

def Paragraph(
    *text: str,
    line_spacing: float = -1,
    alignment: str = "left",
    **kwargs
) -> Paragraph:
    """
    Multi-line text with paragraph formatting.
    
    Parameters:
    - *text: Text lines
    - line_spacing: Spacing between lines
    - alignment: Text alignment ("left", "center", "right")
    """

def MathTex(
    *tex_strings: str,
    arg_separator: str = " ",
    substrings_to_isolate: list[str] = None,
    tex_to_color_map: dict[str, str] = None,
    tex_template: TexTemplate = None,
    **kwargs
) -> MathTex:
    """
    Mathematical expressions rendered with LaTeX in math mode.
    
    Automatically wraps content in math delimiters and processes with LaTeX
    for high-quality mathematical typesetting.
    
    Parameters:
    - *tex_strings: LaTeX math expressions
    - arg_separator: Separator between tex_strings
    - substrings_to_isolate: Substrings to treat as separate objects
    - tex_to_color_map: Color mapping for specific LaTeX substrings
    - tex_template: Custom LaTeX template
    """

def Tex(
    *tex_strings: str,
    arg_separator: str = "",
    substrings_to_isolate: list[str] = None,
    tex_to_color_map: dict[str, str] = None,
    tex_template: TexTemplate = None,
    **kwargs
) -> Tex:
    """
    General LaTeX text rendering for text mode content.
    
    Renders LaTeX content in text mode, supporting complex formatting,
    symbols, and layout commands.
    
    Parameters:
    - *tex_strings: LaTeX text content
    - arg_separator: Separator between tex_strings
    - substrings_to_isolate: Substrings to treat as separate objects
    - tex_to_color_map: Color mapping for specific LaTeX substrings
    - tex_template: Custom LaTeX template
    """

def Title(
    *text_parts: str,
    include_underline: bool = True,
    match_underline_width_to_text: bool = False,
    underline_buff: float = MED_SMALL_BUFF,
    **kwargs
) -> Title:
    """
    Title text with optional underline.
    
    Parameters:
    - *text_parts: Text content for title
    - include_underline: Whether to add underline
    - match_underline_width_to_text: Whether underline matches text width
    - underline_buff: Space between text and underline
    """

def BulletedList(
    *items: str,
    bullet_style: str = "-",
    **kwargs
) -> BulletedList:
    """
    Bulleted list using LaTeX formatting.
    
    Parameters:
    - *items: List items
    - bullet_style: Bullet character or LaTeX symbol
    """

# Mathematical number display
def DecimalNumber(
    number: float = 0,
    num_decimal_places: int = 2,
    include_sign: bool = False,
    group_with_commas: bool = True,
    digit_buff_per_font_unit: float = 0.001,
    show_ellipsis: bool = False,
    unit: str = None,
    include_background_rectangle: bool = False,
    edge_to_fix: np.ndarray = LEFT,
    **kwargs
) -> DecimalNumber:
    """
    Decimal number with customizable formatting.
    
    Parameters:
    - number: Numeric value to display
    - num_decimal_places: Number of decimal places
    - include_sign: Whether to show + sign for positive numbers
    - group_with_commas: Whether to use comma thousands separators
    - digit_buff_per_font_unit: Spacing between digits
    - show_ellipsis: Whether to show ellipsis for truncated numbers
    - unit: Unit string to append
    - include_background_rectangle: Whether to add background
    - edge_to_fix: Which edge to keep fixed during updates
    """

def Integer(
    number: int = 0,
    **kwargs
) -> Integer:
    """
    Integer number display.
    
    Parameters:
    - number: Integer value to display
    """

def Variable(
    var: float | complex,
    label: str | Tex | MathTex,
    var_type: type = DecimalNumber,
    **kwargs
) -> Variable:
    """
    Variable display with label and updating value.
    
    Parameters:
    - var: Initial variable value
    - label: Variable label text
    - var_type: Class for displaying the value
    """

def Sphere(
    center: np.ndarray = ORIGIN,
    radius: float = 1,
    resolution: tuple[int, int] = (101, 51),
    u_range: tuple[float, float] = (0, TAU),
    v_range: tuple[float, float] = (0, PI),
    **kwargs
) -> Sphere:
    """
    Three-dimensional sphere.
    
    Parameters:
    - center: Sphere center point
    - radius: Sphere radius
    - resolution: Surface mesh resolution (u, v)
    - u_range: Azimuthal angle range
    - v_range: Polar angle range
    """

def Cube(
    side_length: float = 2,
    fill_opacity: float = 0.75,
    fill_color: str = BLUE,
    stroke_width: float = 0,
    **kwargs
) -> Cube:
    """
    Three-dimensional cube.
    
    Parameters:
    - side_length: Length of each edge
    - fill_opacity: Face opacity
    - fill_color: Face color
    - stroke_width: Edge line width
    """

def Prism(
    dimensions: tuple[float, float, float] = (3, 2, 1),
    **kwargs
) -> Prism:
    """
    Rectangular prism (box) with specified dimensions.
    
    Parameters:
    - dimensions: Width, height, depth
    """

def Cylinder(
    radius: float = 1,
    height: float = 2,
    direction: np.ndarray = Z_AXIS,
    v_range: tuple[float, float] = (0, TAU),
    show_ends: bool = True,
    resolution: tuple[int, int] = (24, 24),
    **kwargs
) -> Cylinder:
    """
    Three-dimensional cylinder.
    
    Parameters:
    - radius: Cylinder radius
    - height: Cylinder height
    - direction: Cylinder axis direction
    - v_range: Angular range for partial cylinders
    - show_ends: Whether to show end caps
    - resolution: Surface mesh resolution
    """

def Cone(
    base_radius: float = 1,
    height: float = 2,
    direction: np.ndarray = Z_AXIS,
    show_base: bool = True,
    v_range: tuple[float, float] = (0, TAU),
    resolution: tuple[int, int] = (24, 24),
    **kwargs
) -> Cone:
    """
    Three-dimensional cone.
    
    Parameters:
    - base_radius: Base circle radius
    - height: Cone height
    - direction: Cone axis direction
    - show_base: Whether to show base circle
    - v_range: Angular range for partial cones
    - resolution: Surface mesh resolution
    """

def Dot3D(
    point: np.ndarray = ORIGIN,
    radius: float = DEFAULT_DOT_RADIUS,
    color: str = WHITE,
    resolution: tuple[int, int] = (8, 8),
    **kwargs
) -> Dot3D:
    """
    Three-dimensional dot (small sphere).
    
    Parameters:
    - point: Position of the dot
    - radius: Dot radius
    - color: Dot color
    - resolution: Sphere mesh resolution
    """

def Line3D(
    start: np.ndarray = LEFT,
    end: np.ndarray = RIGHT,
    thickness: float = 0.02,
    color: str = WHITE,
    **kwargs
) -> Line3D:
    """
    Three-dimensional line (cylindrical).
    
    Parameters:
    - start: Line start point
    - end: Line end point
    - thickness: Line thickness
    - color: Line color
    """

def Arrow3D(
    start: np.ndarray = ORIGIN,
    end: np.ndarray = RIGHT + UP + OUT,
    thickness: float = 0.02,
    height: float = 0.3,
    base_radius: float = 0.08,
    color: str = WHITE,
    **kwargs
) -> Arrow3D:
    """
    Three-dimensional arrow.
    
    Parameters:
    - start: Arrow start point
    - end: Arrow end point
    - thickness: Shaft thickness
    - height: Arrowhead height
    - base_radius: Arrowhead base radius
    - color: Arrow color
    """

def Surface(
    func: Callable[[float, float], np.ndarray],
    u_range: tuple[float, float] = (-1, 1),
    v_range: tuple[float, float] = (-1, 1),
    resolution: int | tuple[int, int] = 32,
    fill_color: str = BLUE_D,
    fill_opacity: float = 1.0,
    checkerboard_colors: list[str] = None,
    stroke_color: str = LIGHT_GREY,
    stroke_width: float = 0.5,
    should_make_jagged: bool = False,
    **kwargs
) -> Surface:
    """
    Parametric surface defined by function.
    
    Creates 3D surface by evaluating function over parameter grid.
    
    Parameters:
    - func: Function (u,v) -> [x,y,z] defining surface
    - u_range: Parameter u range (u_min, u_max)
    - v_range: Parameter v range (v_min, v_max)
    - resolution: Surface mesh resolution
    - fill_color: Surface color
    - fill_opacity: Surface opacity
    - checkerboard_colors: Alternating face colors
    - stroke_color: Edge line color
    - stroke_width: Edge line width
    - should_make_jagged: Whether to use sharp edges
    """

# Polyhedra
def Tetrahedron(
    edge_length: float = 2,
    **kwargs
) -> Tetrahedron:
    """Regular tetrahedron (4 triangular faces)."""

def Octahedron(
    edge_length: float = 2,
    **kwargs
) -> Octahedron:
    """Regular octahedron (8 triangular faces)."""

def Icosahedron(
    edge_length: float = 2,
    **kwargs
) -> Icosahedron:
    """Regular icosahedron (20 triangular faces)."""

def Dodecahedron(
    edge_length: float = 2,
    **kwargs
) -> Dodecahedron:
    """Regular dodecahedron (12 pentagonal faces)."""

def Union(
    *vmobjects: VMobject,
    **kwargs
) -> VMobject:
    """
    Boolean union of multiple VMobjects.
    
    Combines shapes to create a single shape containing all areas
    covered by any of the input shapes.
    
    Parameters:
    - *vmobjects: VMobjects to unite
    """

def Intersection(
    *vmobjects: VMobject,
    **kwargs
) -> VMobject:
    """
    Boolean intersection of multiple VMobjects.
    
    Creates shape containing only areas covered by all input shapes.
    
    Parameters:
    - *vmobjects: VMobjects to intersect
    """

def Difference(
    subject: VMobject,
    clip: VMobject,
    **kwargs
) -> VMobject:
    """
    Boolean difference operation (subject minus clip).
    
    Removes the clip shape from the subject shape.
    
    Parameters:
    - subject: Base shape to subtract from
    - clip: Shape to subtract
    """

def Exclusion(
    *vmobjects: VMobject,
    **kwargs
) -> VMobject:
    """
    Boolean exclusive or of VMobjects.
    
    Creates shape containing areas covered by exactly one input shape
    (removes overlapping regions).
    
    Parameters:
    - *vmobjects: VMobjects for exclusive or operation
    """

def SurroundingRectangle(
    mobject: Mobject,
    color: str = YELLOW,
    buff: float = SMALL_BUFF,
    corner_radius: float = 0,
    **kwargs
) -> Rectangle:
    """
    Rectangle that surrounds another mobject.
    
    Automatically sizes to encompass the target mobject with buffer spacing,
    useful for highlighting and emphasis.
    
    Parameters:
    - mobject: Mobject to surround
    - color: Rectangle outline color
    - buff: Buffer distance around mobject
    - corner_radius: Radius for rounded corners
    """

def BackgroundRectangle(
    mobject: Mobject,
    color: str = BLACK,
    stroke_width: float = 0,
    stroke_color: str = BLACK,
    fill_opacity: float = 0.75,
    buff: float = 0,
    **kwargs
) -> Rectangle:
    """
    Background rectangle for text or objects.
    
    Creates opaque background behind mobject to improve visibility
    over complex backgrounds.
    
    Parameters:
    - mobject: Mobject to create background for
    - color: Background fill color
    - stroke_width: Outline thickness
    - stroke_color: Outline color
    - fill_opacity: Background opacity
    - buff: Buffer around mobject
    """

def Cross(
    size: float = 0.5,
    stroke_width: float = 6,
    stroke_color: str = RED,
    **kwargs
) -> VGroup:
    """
    Cross or X mark symbol.
    
    Creates intersection of diagonal lines, useful for marking
    incorrect answers or indicating removal.
    
    Parameters:
    - size: Size of cross arms
    - stroke_width: Line thickness
    - stroke_color: Line color
    """

def Underline(
    mobject: Mobject,
    buff: float = SMALL_BUFF,
    **kwargs
) -> Line:
    """
    Underline decoration for text or objects.
    
    Creates horizontal line positioned below mobject,
    automatically sized to match mobject width.
    
    Parameters:
    - mobject: Mobject to underline
    - buff: Distance below mobject
    """

def LabeledDot(
    label: str | Mobject,
    point: np.ndarray = ORIGIN,
    color: str = WHITE,
    radius: float = DEFAULT_DOT_RADIUS,
    **kwargs
) -> VGroup:
    """
    Dot with integrated text label.
    
    Combines dot marker with positioned text label,
    useful for marking points in geometric diagrams.
    
    Parameters:
    - label: Text or mobject to use as label
    - point: Position for dot center
    - color: Dot color
    - radius: Dot radius
    """

def LabeledLine(
    start: np.ndarray,
    end: np.ndarray,
    label: str | Mobject,
    label_position: float = 0.5,
    **kwargs
) -> VGroup:
    """
    Line segment with integrated label.
    
    Combines line with positioned label, commonly used
    for labeled edges in geometric diagrams.
    
    Parameters:
    - start: Starting point coordinates
    - end: Ending point coordinates  
    - label: Text or mobject label
    - label_position: Position along line for label [0, 1]
    """

def LabeledArrow(
    start: np.ndarray,
    end: np.ndarray,
    label: str | Mobject,
    label_position: float = 0.5,
    **kwargs
) -> VGroup:
    """
    Arrow with integrated label.
    
    Combines directional arrow with positioned label,
    useful for labeled vectors and directed edges.
    
    Parameters:
    - start: Arrow starting point
    - end: Arrow ending point
    - label: Text or mobject label
    - label_position: Position along arrow for label [0, 1]
    """

def AnnotationDot(
    point: np.ndarray = ORIGIN,
    radius: float = DEFAULT_SMALL_DOT_RADIUS,
    color: str = WHITE,
    **kwargs
) -> Dot:
    """
    Small dot specifically for annotations and marking points.
    
    Smaller than regular dots, optimized for marking specific
    points without dominating the visual presentation.
    
    Parameters:
    - point: Position for annotation dot
    - radius: Dot radius (smaller than standard)
    - color: Dot color
    """

def VectorField(
    func: Callable,
    x_range: Sequence[float] = None,
    y_range: Sequence[float] = None,
    z_range: Sequence[float] = None,
    delta_x: float = 0.5,
    delta_y: float = 0.5,
    delta_z: float = 0.5,
    min_color_scheme_value: float = 0,
    max_color_scheme_value: float = 2,
    colors: list[str] = None,
    **kwargs
) -> VGroup:
    """
    Vector field visualization using arrow arrays.
    
    Creates grid of arrows showing vector field values,
    with optional color coding based on vector magnitude.
    
    Parameters:
    - func: Vector field function (x,y,z) -> (vx,vy,vz)
    - x_range: X coordinate range [min, max, step]
    - y_range: Y coordinate range [min, max, step]
    - z_range: Z coordinate range [min, max, step]
    - delta_x: Spacing between arrows in x direction
    - delta_y: Spacing between arrows in y direction
    - delta_z: Spacing between arrows in z direction
    - min_color_scheme_value: Minimum value for color mapping
    - max_color_scheme_value: Maximum value for color mapping
    - colors: List of colors for magnitude-based coloring
    """

def StreamLines(
    func: Callable,
    x_range: Sequence[float] = None,
    y_range: Sequence[float] = None,
    n_repeats: int = 1,
    noise_factor: float = None,
    **kwargs
) -> VGroup:
    """
    Streamline visualization for vector fields.
    
    Creates flowing curves that follow vector field directions,
    showing field flow patterns and trajectories.
    
    Parameters:
    - func: Vector field function (x,y) -> (vx,vy)
    - x_range: X coordinate range for streamlines
    - y_range: Y coordinate range for streamlines
    - n_repeats: Number of streamline repetitions
    - noise_factor: Random variation in starting positions
    """

def ArrowVectorField(
    func: Callable,
    color_function: Callable = None,
    **kwargs
) -> VGroup:
    """
    Arrow-based vector field with customizable coloring.
    
    Enhanced vector field visualization with per-arrow
    customization and advanced coloring options.
    
    Parameters:
    - func: Vector field function
    - color_function: Function determining arrow colors based on field values
    """

def Brace(
    mobject: Mobject,
    direction: np.ndarray = DOWN,
    buff: float = 0.2,
    **kwargs
) -> VMobject:
    """
    Curly brace that spans the width or height of a mobject.
    
    Automatically sizes to bracket the specified mobject dimension,
    commonly used for mathematical annotations and grouping.
    
    Parameters:
    - mobject: Mobject to create brace for
    - direction: Direction to place brace (UP, DOWN, LEFT, RIGHT)
    - buff: Distance from mobject to brace
    """

def BraceLabel(
    mobject: Mobject,
    text: str,
    brace_direction: np.ndarray = DOWN,
    label_constructor: Callable = MathTex,
    **kwargs
) -> VGroup:
    """
    Brace with integrated text label.
    
    Combines brace with positioned label, streamlining
    the creation of labeled mathematical groupings.
    
    Parameters:
    - mobject: Mobject to brace and label
    - text: Label text content
    - brace_direction: Direction for brace placement
    - label_constructor: Function to create label (Text, MathTex, etc.)
    """

def BraceBetweenPoints(
    point_1: np.ndarray,
    point_2: np.ndarray,
    direction: np.ndarray = None,
    **kwargs
) -> VMobject:
    """
    Brace spanning between two specific points.
    
    Creates brace of exact length to span between given points,
    useful for measuring or indicating distances.
    
    Parameters:
    - point_1: First endpoint for brace span
    - point_2: Second endpoint for brace span
    - direction: Direction perpendicular to span for brace placement
    """

def ArcBrace(
    arc_mobject: Arc | Circle,
    direction: np.ndarray = RIGHT,
    **kwargs
) -> VMobject:
    """
    Curved brace that follows arc or circular shapes.
    
    Creates brace that curves to match arc geometry,
    ideal for labeling curved sections and arc measurements.
    
    Parameters:
    - arc_mobject: Arc or circular mobject to brace
    - direction: Radial direction for brace placement
    """

# Tables and matrices
def Table(
    table: list[list[str | Mobject]],
    row_labels: list[Mobject] = None,
    col_labels: list[Mobject] = None,
    top_left_entry: Mobject = None,
    v_buff: float = 0.8,
    h_buff: float = 1.3,
    include_outer_lines: bool = False,
    add_background_rectangles_to_entries: bool = False,
    entries_background_color: str = BLACK,
    include_background_rectangle: bool = False,
    background_rectangle_color: str = BLACK,
    line_config: dict = None,
    **kwargs
) -> Table:
    """
    Table with customizable formatting and styling.
    
    Parameters:
    - table: 2D list of table entries
    - row_labels: Labels for rows
    - col_labels: Labels for columns
    - top_left_entry: Entry for top-left corner
    - v_buff: Vertical spacing between entries
    - h_buff: Horizontal spacing between entries
    - include_outer_lines: Whether to draw outer border
    - add_background_rectangles_to_entries: Whether entries have backgrounds
    - entries_background_color: Background color for entries
    - include_background_rectangle: Whether table has background
    - background_rectangle_color: Table background color
    - line_config: Configuration for table lines
    """

def Matrix(
    matrix: list[list[float | str]] | np.ndarray,
    v_buff: float = 0.8,
    h_buff: float = 0.8,
    bracket_h_buff: float = MED_SMALL_BUFF,
    bracket_v_buff: float = MED_SMALL_BUFF,
    add_background_rectangles_to_entries: bool = False,
    include_background_rectangle: bool = False,
    element_to_mobject: Callable = MathTex,
    element_to_mobject_config: dict = None,
    element_alignment_corner: np.ndarray = DR,
    left_bracket: str = "[",
    right_bracket: str = "]",
    **kwargs
) -> Matrix:
    """
    Mathematical matrix with brackets.
    
    Parameters:
    - matrix: 2D array or list of matrix entries
    - v_buff: Vertical spacing between entries
    - h_buff: Horizontal spacing between entries
    - bracket_h_buff: Horizontal bracket spacing
    - bracket_v_buff: Vertical bracket spacing
    - add_background_rectangles_to_entries: Whether entries have backgrounds
    - include_background_rectangle: Whether matrix has background
    - element_to_mobject: Function to convert entries to mobjects
    - element_to_mobject_config: Config for element conversion
    - element_alignment_corner: How to align elements in cells
    - left_bracket: Left bracket character
    - right_bracket: Right bracket character
    """

# Code display
def Code(
    file_name: str = None,
    code: str = None,
    tab_width: int = 3,
    line_spacing: float = 0.3,
    font_size: float = 24,
    font: str = "Monospace",
    stroke_width: float = 0,
    margin: float = 0.3,
    indentation_chars: str = "    ",
    background: str = "rectangle",
    background_stroke_width: float = 1,
    background_stroke_color: str = WHITE,
    corner_radius: float = 0.2,
    insert_line_no: bool = True,
    line_no_from: int = 1,
    line_no_buff: float = 0.4,
    style: str = "vim",
    language: str = None,
    generate_html_file: bool = False,
    warn_missing_font: bool = True,
    **kwargs
) -> Code:
    """
    Syntax-highlighted code display.
    
    Parameters:
    - file_name: Path to source code file
    - code: Code string (if not using file)
    - tab_width: Width of tab characters
    - line_spacing: Spacing between lines
    - font_size: Code font size
    - font: Font family for code
    - stroke_width: Text outline width
    - margin: Margin around code block
    - indentation_chars: Characters used for indentation
    - background: Background type ("rectangle", "window", None)
    - background_stroke_width: Background outline width
    - background_stroke_color: Background outline color
    - corner_radius: Background corner radius
    - insert_line_no: Whether to show line numbers
    - line_no_from: Starting line number
    - line_no_buff: Space between line numbers and code
    - style: Syntax highlighting style
    - language: Programming language for highlighting
    - generate_html_file: Whether to generate HTML file
    - warn_missing_font: Whether to warn about missing fonts
    """

# Value tracking
def ValueTracker(
    value: float = 0,
    **kwargs
) -> ValueTracker:
    """
    Invisible mobject that tracks a numeric value for animations.
    
    Used to animate numeric values that control other object properties,
    enabling complex parametric animations.
    
    Parameters:
    - value: Initial numeric value
    """

def ComplexValueTracker(
    value: complex = 0 + 0j,
    **kwargs
) -> ComplexValueTracker:
    """
    Value tracker for complex numbers.
    
    Parameters:
    - value: Initial complex value
    """

from manim import *

class ShapesExample(Scene):
    def construct(self):
        # Create and style basic shapes
        circle = Circle(radius=1.5, color=BLUE, fill_opacity=0.5)
        square = Square(side_length=2, color=RED, stroke_width=5)
        triangle = Triangle(color=GREEN, fill_opacity=0.7)
        
        # Position shapes
        shapes = VGroup(circle, square, triangle)
        shapes.arrange(RIGHT, buff=1)
        
        # Add to scene
        self.add(shapes)

class TextExample(Scene):
    def construct(self):
        # Regular text
        title = Text("Mathematical Animation", font_size=48, color=BLUE)
        title.to_edge(UP)
        
        # LaTeX math
        equation = MathTex(
            r"e^{i\pi} + 1 = 0",
            font_size=60,
            color=YELLOW
        )
        
        # Position and animate
        self.play(Write(title))
        self.play(Write(equation))

class ThreeDExample(ThreeDScene):
    def construct(self):
        # Set 3D camera
        self.set_camera_orientation(phi=75*DEGREES, theta=45*DEGREES)
        
        # Create 3D objects
        cube = Cube(side_length=2, fill_color=BLUE, fill_opacity=0.7)
        sphere = Sphere(radius=1.2, fill_color=RED, fill_opacity=0.8)
        
        # Position objects
        cube.shift(LEFT * 2)
        sphere.shift(RIGHT * 2)
        
        # Add to scene
        self.add(cube, sphere)
        
        # Rotate camera
        self.begin_ambient_camera_rotation(rate=0.1)
        self.wait(3)

class ComplexExample(Scene):
    def construct(self):
        # Create matrix
        matrix = Matrix([
            ["a", "b"],
            ["c", "d"]
        ], bracket_h_buff=0.1)
        
        # Create table
        table_data = [
            ["x", "y", "f(x,y)"],
            ["0", "0", "1"],
            ["1", "0", "2"],
            ["0", "1", "3"]
        ]
        table = Table(table_data, include_outer_lines=True)
        
        # Create code
        code = Code(
            code="def fibonacci(n):\n    if n <= 1:\n        return n\n    return fibonacci(n-1) + fibonacci(n-2)",
            language="python",
            font_size=20
        )
        
        # Arrange and display
        VGroup(matrix, table, code).arrange(DOWN, buff=0.5).scale(0.8)
        self.add(matrix, table, code)