# Documentation Overview

## Page Overviews

[mobject-overview.mdx](mobject-overview.mdx)
#### Mobjects

Mobjects in `smanim` are Python objects that represent different components in the diagram.
Examples of common mobject classes include `Square`, `Text`, `Group`, and `Graph` mobjects.
While similar to mobjects in Manim, smanim mobjects have minor variations in their function names and parameters.

- Mobjects by default are positioned at the `ORIGIN` (0, 0, 0).
- Mobjects can be copied (e.g. `mob2 = mob1.copy()`).
- Mobjects can be layered via z_index.

  - Set the z_index manually (e.g. `s = Square(z_index=2))`.
  - Or use higher-level functions (e.g.`group.bring_to_front(mob_in_group)` or `group.bring_to_back(mob_in_group)`).
  - The default z_index of all mobjects is 0 besides text mobjects which are 1.

- Mobjects can be spatially transformed (e.g. `scale` or `shift`).
- Mobjects can be spatially related (e.g. `mob1.next_to(mob2)`).
- Mobjects can be styled with `set_color` or `set_opacity`.

  - Note that VMobjects, or vectorized mobjects, can be styled with `set_fill(color, opacity)` or `set_stroke(color, opacity)`.

- Mobjects have a center and an 8 point bounding box (4 corners, 4 edge midpoints).

  - `mobject.center` to access the center
  - `mobject.left`, `mobject.right`, `mobject.top`, `mobject.bottom` to access the edge midpoints
  - `mobject.get_corner(UL)`, `mobject.get_corner(UR)`, `mobject.get_corner(DL)`, `mobject.get_corner(DR)` to access corners

- Mobjects can have submobjects (e.g. `square.add(Text("Square"))`), though creating a `Group` should be preferred.

#### VMobjects

VMobjects in `smanim` are vectorized mobjects represented spatially by a list of points.
`Circle`, `Square`, `Arrow`, and any other mobject that doesn't include `Text` is a `VMobject`.
The relevant params for the `VMobject` constructor:

- `color` (ManimColor | None, default=None): by default, sets the `fill_color`.
- `opacity` (float | None, default=None)
- `stroke_color` (ManimColor | None, default=None): the color of the shape outline. Independent of `fill_color`. When set, ignore `color`.
- `stroke_opacity` (float | None, default=None)
- `stroke_width` (float | None, default=None)
- `fill_color` (ManimColor | None, default=None): When set, ignore `color`.
- `fill_opacity` (float | None, default=None)
- `dashed` (bool, default=False)

- `kwargs` (dict): Additional arguments for customization.

##### Usage Example

`Square(stroke_color=RED, dashed=True)`

[spatial-relations-overview.mdx](spatial-relations-overview.mdx)
Spatial relations are used to position one mobject relative to another mobject.
The main spatial relations in smanim are `next_to`, `close_to`, `align_to`, `move_to`, and `to_edge`.
These functions live in the `Mobject` class, and any mobject can apply them.

This section also covers bounding boxes, which are used for accessing the corners, edge points, and center of a mobject.

## Detailed Documentation Overview

Below is an overview of all the files in the smanim documentation.
- [canvas.mdx](canvas.mdx)
  - Description: A canvas is what is drawn on.
    Mobjects can be added to the `canvas`: `canvas.add(mobject)`.
    Added mobjects can be drawn: `canvas.draw()`.
    The canvas is constructed using the default `CONFIG`: `canvas = Canvas(CONFIG)` and is available in the global scope.
  - Example 1: Show some text using the global default text color to black (instead of its default, white). Crop and ignore the background on the canvas.
- [intro.mdx](intro.mdx)
  - Description: still-manim, or `smanim`, is a python library for drawing static graphics of conceptual content in domains like math and programming.
    It's based on 3blue1brown's animation library, [manim](https://github.com/3b1b/manim), except it is designed for static graphics and for running in the browser.
- [labeling.mdx](labeling.mdx)
  - Description: `label = mob.create_label("example text")` can be applied to create a `Text` mobject `label` for a mobject `mob`.
    `create_label` should be used as the default way to label mobjects in smanim, since mobject classes like `Line` override `create_label` to provide a custom labeling.
- [surrounding-rectangle.mdx](surrounding-rectangle.mdx)
  - Description: The `SurroundingRectangle` class, which inherits from `Rectangle`, represents a rectangle that surrounds a given `Mobject`.
    It can be applied to emphasize a shape or some text to the user.
  - Example 1: A surrounding rectangle around a square with custom padding.
- [box-list.mdx](box-list.mdx)
  - Description: The `BoxList` class is a specialized `Group` that places each of its submobjects in a rectangle with a default white outline and arranges them in a row or a column.
    A common use case is showing a list of numbers or values in programming.
  - Example 1: A horizontal box list where the items are squares of varying opacity.
  - Example 2: A horizontal box list of numbers (e.g. for teaching a sorting algorithm).
- [text.mdx](text.mdx)
  - Description: The `Text` class, which inherits from `TransformableMobject`, represents a customizable text mobject.
    The method `create_label` of the Mobject class constructs a `Text` instance.
  - Example 1: Text with custom color, size, and styling.
- [arc.mdx](arc.mdx)
  - Description: The `Arc` class, which inherits from `VMobject`, represents an arc.
- [circle.mdx](circle.mdx)
  - Description: The `Circle` class, which inherits from `Arc`, represents a circle.
  - Example 1: A circle with a custom radius.
- [group.mdx](group.mdx)
  - Description: A `Group` is a `Mobject` that can contain others mobjects, including sub-groups.
    Groups have additional spatial relationships for arranging their submobjects in a row, column, or grid, which are covered on this page.
  - Example 1: Create a group with a square, an arrow, and a text label and set the group's color.
  - Example 2: Create a group of 8 squares with different opacities and put them in a grid with 2 rows and 4 cols.
- [arrow.mdx](arrow.mdx)
  - Description: The `Arrow` class inherits from `TipableLine`, representing an arrow with optional tips at either end.
    The default arrow has a tip only at the true "end" and has a drawing style with color set to WHITE.
  - Example 1: An arrow between two mobjects.
  - Example 2: An arrow pointing at a corner of a square.
- [line.mdx](line.mdx)
  - Description: The `Line` class inherits from `VMobject`, representing a line segment between two points or Mobjects.
    The default drawing style for a line is a stroke with the color WHITE. A line cannot be "filled".
  - Example 1: A line between two points with custom color.
  - Example 2: A line between two mobjects.
  - Example 3: A kite with a line segment between a vertex and a side's midpoint.
- [graph.mdx](graph.mdx)
  - Description: The `Graph` class represents directed and undirected graphs with unweighted edges.
  - Example 1: A simple graph, with "circular layout" and vertex labels.
  - Example 2: A graph with a start vertex colored and labeled, with its outgoing edges colored.
  - Example 3: A graph created from an adjacency list. Also styled with custom coloring.
- [weighted-graph.mdx](weighted-graph.mdx)
  - Description: The `WeightedGraph` class inherits from `Graph` and includes functionality for adding edge labels (weights).
  - Example 1: A simple undirected weighted graph.
  - Example 2: A weighted directed graph from an adjacency list representation.
- [polygon.mdx](polygon.mdx)
  - Description: The `Polygon` class, which inherits from `Polygram`, represents a polygon with optional rounded corners.
  - Example 1: An irregular triangle, with its corner radius set.
  - Example 2: A concave pentagon.
- [rectangle.mdx](rectangle.mdx)
  - Description: The `Rectangle` class, which inherits from `Polygon`, represents a rectangle.
  - Example 1: A rectangle with custom width and height.
- [regular-polygon.mdx](regular-polygon.mdx)
  - Description: The `RegularPolygon` class, which inherits from `Polygon`, represents a regular polygon.
  - Example 1: An octagon, tilted at an angle.
- [square.mdx](square.mdx)
  - Description: The `Square` class, which inherits from `Polygon`, represents a square.
  - Example 1: A square with a custom side length.
- [triangle.mdx](triangle.mdx)
  - Description: The `Triangle` class, which inherits from `RegularPolygon`, represents a triangle.
  - Example 1: The default triangle.
- [align-to.mdx](align-to.mdx)
  - Description: The `align_to` function is used for two main purposes:
    
    - to align a mobject's edge `E` to edge `E` of another mobject where `E` is the `direction` parameter.
    - to move a mobject so that its corner `C` is positioned at the corner `C` of another mobject, where `C` is the `direction` parameter.
  - Example 1: A stretched circle aligned to the top edge of a rectangle, with a tiny buff.
  - Example 2: A small square aligned to be in the corner of larger rectangle.
- [bounding-box.mdx](bounding-box.mdx)
  - Description: Every mobject has a "bounding box", which is the smallest rectangle that surrounds it completely.
- [close-to.mdx](close-to.mdx)
  - Description: The `close_to` function positions one mobject near another, testing various directions to avoid collisions with the `obstacle_mobjects`.
    This function is useful when `next_to` may cause overlaps with other mobjects.
    Often used for labeling a submobject of a complex mobject like a network graph.
  - Example 1: A circle placed close to a rectangle, avoiding collision with a triangle.
- [move-to.mdx](move-to.mdx)
  - Description: The `move_to` function moves the center of a mobject to the center of another mobject or a specific point.
  - Example 1: Move a dot's center to a square's center.
- [next-to.mdx](next-to.mdx)
  - Description: The `next_to` function is used to place one mobject next to another mobject in the specified direction, optionally adding buffer and edge alignment.
    Use `close_to` instead to avoid collisions with other mobjects that `next_to` might cause, though `close_to` also requires specifying potentially colliding mobjects.
  - Example 1: A circle beneath a rotated rectangle.
    
    Note: Bounding box points are shown for demo purposes. They are not included in the code.
  - Example 2: A circle to the right of a rectangle, with their bottom (down) edges aligned. A Text label above the rectangle.
- [to-edge.mdx](to-edge.mdx)
  - Description: The `to_edge` function moves a mobject to a specified edge of the canvas with an optional buffer.
  - Example 1: Move a text mobject to the top canvas edge (like a title).
- [spatial-transformations.mdx](spatial-transformations.mdx)
  - Description: Spatial transformations are used to transform a mobject in space.
    They typically operate as affine transformations to scale, shift, stretch, or rotate the mobject.
  - Example 1: Simple scaling of a square.
  - Example 2: Stretching and rotating a simple number line (which contains vmobjects and text).
  - Example 3: Scaling of a group to fit the width of a text description.