Bring in main's FileWriter into experimental

.github/workflows/publish-docker.yml

@@ -25,7 +25,7 @@ jobs:
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Build and push
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v6
         with:
           platforms: linux/arm64,linux/amd64
           push: true
@@ -61,7 +61,7 @@ jobs:
             print(f"tag_name={ref_tag}", file=f)
 
       - name: Build and push
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v6
         with:
           platforms: linux/arm64,linux/amd64
           push: true

.pre-commit-config.yaml

@@ -18,7 +18,7 @@ repos:
       - id: python-check-blanket-noqa
         name: Precision flake ignores
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.4.9
+    rev: v0.5.1
     hooks:
       - id: ruff
         name: ruff lint
@@ -41,7 +41,7 @@ repos:
             flake8-simplify==0.14.1,
           ]
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.10.0
+    rev: v1.10.1
     hooks:
       - id: mypy
         additional_dependencies:

README.md

@@ -21,7 +21,8 @@
 
 Manim is an animation engine for explanatory math videos. It's used to create precise animations programmatically, as demonstrated in the videos of [3Blue1Brown](https://www.3blue1brown.com/).
 
-> NOTE: This repository is maintained by the Manim Community and is not associated with Grant Sanderson or 3Blue1Brown in any way (although we are definitely indebted to him for providing his work to the world). If you would like to study how Grant makes his videos, head over to his repository ([3b1b/manim](https://github.com/3b1b/manim)). This fork is updated more frequently than his, and it's recommended to use this fork if you'd like to use Manim for your own projects.
+> [!NOTE]
+> This repository is maintained by the Manim Community and is not associated with Grant Sanderson or 3Blue1Brown in any way (although we are definitely indebted to him for providing his work to the world). If you would like to study how Grant makes his videos, head over to his repository ([3b1b/manim](https://github.com/3b1b/manim)). This fork is updated more frequently than his, and it's recommended to use this fork if you'd like to use Manim for your own projects.
 
 ## Table of Contents:
 
@@ -35,7 +36,8 @@ Manim is an animation engine for explanatory math videos. It's used to create pr
 
 ## Installation
 
-> **WARNING:** These instructions are for the community version _only_. Trying to use these instructions to install [3b1b/manim](https://github.com/3b1b/manim) or instructions there to install this version will cause problems. Read [this](https://docs.manim.community/en/stable/faq/installation.html#why-are-there-different-versions-of-manim) and decide which version you wish to install, then only follow the instructions for your desired version.
+> [!WARNING]
+> These instructions are for the community version _only_. Trying to use these instructions to install [3b1b/manim](https://github.com/3b1b/manim) or instructions there to install this version will cause problems. Read [this](https://docs.manim.community/en/stable/faq/installation.html#why-are-there-different-versions-of-manim) and decide which version you wish to install, then only follow the instructions for your desired version.
 
 Manim requires a few dependencies that must be installed prior to using it. If you
 want to try it out first before installing it locally, you can do so
@@ -71,7 +73,7 @@ In order to view the output of this scene, save the code in a file called `examp
 manim -p -ql example.py SquareToCircle
 ```
 
-You should see your native video player program pop up and play a simple scene in which a square is transformed into a circle. You may find some more simple examples within this
+You should see a window pop up and play a simple scene in which a square is transformed into a circle. You may find some more simple examples within this
 [GitHub repository](example_scenes). You can also visit the [official gallery](https://docs.manim.community/en/stable/examples.html) for more advanced examples.
 
 Manim also ships with a `%%manim` IPython magic which allows to use it conveniently in JupyterLab (as well as classic Jupyter) notebooks. See the
@@ -84,13 +86,15 @@ The general usage of Manim is as follows:
 
 ![manim-illustration](https://raw.githubusercontent.com/ManimCommunity/manim/main/docs/source/_static/command.png)
 
-The `-p` flag in the command above is for previewing, meaning the video file will automatically open when it is done rendering. The `-ql` flag is for a faster rendering at a lower quality.
+The `-p` flag in the command above is for previewing, meaning a window will show up to render it in real time.
+The `-ql` flag is for a faster rendering at a lower quality.
 
 Some other useful flags include:
 
 -  `-s` to skip to the end and just show the final frame.
 -  `-n <number>` to skip ahead to the `n`'th animation of a scene.
 -  `-f` show the file in the file browser.
+-  `-w` to actually write the result into a video file.
 
 For a thorough list of command line arguments, visit the [documentation](https://docs.manim.community/en/stable/guides/configuration.html).
 

conftest.py

@@ -5,7 +5,6 @@
 
 from __future__ import annotations
 
-import cairo
 import moderngl
 
 # If it is running Doctest the current directory
@@ -34,7 +33,6 @@ def pytest_report_header(config):
     info = ctx.info
     ctx.release()
     return (
-        f"\nCairo Version: {cairo.cairo_version()}",
         "\nOpenGL information",
         "------------------",
         f"vendor: {info['GL_VENDOR'].strip()}",

docker/Dockerfile

@@ -22,9 +22,9 @@ RUN wget -O /tmp/install-tl-unx.tar.gz http://mirror.ctan.org/systems/texlive/tl
     tar -xzf /tmp/install-tl-unx.tar.gz -C /tmp/install-tl --strip-components=1 && \
     /tmp/install-tl/install-tl --profile=/tmp/texlive-profile.txt \
     && tlmgr install \
-        amsmath babel-english cbfonts-fd cm-super ctex doublestroke dvisvgm everysel \
+        amsmath babel-english cbfonts-fd cm-super count1to ctex doublestroke dvisvgm everysel \
         fontspec frcursive fundus-calligra gnu-freefont jknapltx latex-bin \
-        mathastext microtype ms physics preview ragged2e relsize rsfs \
+        mathastext microtype multitoc physics prelim2e preview ragged2e relsize rsfs \
         setspace standalone tipa wasy wasysym xcolor xetex xkeyval
 
 # clone and build manim

docs/i18n/sv/LC_MESSAGES/tutorials/building_blocks.po

@@ -163,8 +163,8 @@ msgid "Creating a custom animation"
 msgstr "Skapa en egen animation"
 
 #: ../../source/tutorials/building_blocks.rst:299
-msgid "Even though Manim has many built-in animations, you will find times when you need to smoothly animate from one state of a :class:`~.Mobject` to another. If you find yourself in that situation, then you can define your own custom animation. You start by extending the :class:`~.Animation` class and overriding its :meth:`~.Animation.interpolate_mobject`. The :meth:`~.Animation.interpolate_mobject` method receives alpha as a parameter that starts at 0 and changes throughout the animation. So, you just have to manipulate self.mobject inside Animation according to the alpha value in its interpolate_mobject method. Then you get all the benefits of :class:`~.Animation` such as playing it for different run times or using different rate functions."
-msgstr "Även om Manim har många inbyggda animationer, kommer det vara stunder när du behöver animera smidigt från ett tillstånd av ett :class:`~.Mobject` till ett annat. Om du befinner dig i den situationen kan du definiera en egen animation. Du börjar med att utöka :class:`~.Animation`-klassen och åsidosätter dess :meth:`~.Animation.interpolate_mobject`. :meth:`~.Animation.interpolate_mobject` -metoden får alfa som en parameter som startar vid 0 och ändras under hela animationen. Så du behöver bara manipulera self.mobject inuti Animation enligt alfa värdet i dess interpolate_mobject-metod. Då får du alla fördelar med :class:`~.Animation` såsom att spela det under olika körtider eller använda olika hastighetsfunktioner."
+msgid "Even though Manim has many built-in animations, you will find times when you need to smoothly animate from one state of a :class:`~.Mobject` to another. If you find yourself in that situation, then you can define your own custom animation. You start by extending the :class:`~.Animation` class and overriding its :meth:`~.Animation.interpolate`. The :meth:`~.Animation.interpolate` method receives alpha as a parameter that starts at 0 and changes throughout the animation. So, you just have to manipulate self.mobject inside Animation according to the alpha value in its interpolate method. Then you get all the benefits of :class:`~.Animation` such as playing it for different run times or using different rate functions."
+msgstr "Även om Manim har många inbyggda animationer, kommer det vara stunder när du behöver animera smidigt från ett tillstånd av ett :class:`~.Mobject` till ett annat. Om du befinner dig i den situationen kan du definiera en egen animation. Du börjar med att utöka :class:`~.Animation`-klassen och åsidosätter dess :meth:`~.Animation.interpolate`. :meth:`~.Animation.interpolate` -metoden får alfa som en parameter som startar vid 0 och ändras under hela animationen. Så du behöver bara manipulera self.mobject inuti Animation enligt alfa värdet i dess interpolate-metod. Då får du alla fördelar med :class:`~.Animation` såsom att spela det under olika körtider eller använda olika hastighetsfunktioner."
 
 #: ../../source/tutorials/building_blocks.rst:306
 msgid "Let's say you start with a number and want to create a :class:`~.Transform` animation that transforms it to a target number. You can do it using :class:`~.FadeTransform`, which will fade out the starting number and fade in the target number. But when we think about transforming a number from one to another, an intuitive way of doing it is by incrementing or decrementing it smoothly. Manim has a feature that allows you to customize this behavior by defining your own custom animation."
@@ -175,12 +175,12 @@ msgid "You can start by creating your own ``Count`` class that extends :class:`~
 msgstr "Du kan börja med att skapa din egen ``Count`` klass som utökar klassen :class:`~.Animation`. Klassen kan ha en konstruktor med tre argument, ett :class:`~.DecimalNumber` Mobject, start and end. Konstruktorn kommer att skicka :class:`~.DecimalNumber` Mobject till superkonstruktorn (i detta fall konstruktorn i :class:`~.Animation`) och kommer att ställa in start och slut."
 
 #: ../../source/tutorials/building_blocks.rst:315
-msgid "The only thing that you need to do is to define how you want it to look at every step of the animation. Manim provides you with the alpha value in the :meth:`~.Animation.interpolate_mobject` method based on frame rate of video, rate function, and run time of animation played. The alpha parameter holds a value between 0 and 1 representing the step of the currently playing animation. For example, 0 means the beginning of the animation, 0.5 means halfway through the animation, and 1 means the end of the animation."
-msgstr "Det enda du behöver göra är att definiera hur du vill att det ska se ut för varje steg i animationen. Manim ger dig alfavärdet i :meth:`~. nimation.interpolate_mobject' metoden baserat på bildhastigheten av videon, hastighetsfunktionen och körtiden för den animation som spelas. Alfaparametern har ett värde mellan 0 och 1 som representerar steget i den aktuella animationen. Till exempel betyder 0 början av animationen, 0,5 betyder halvvägs genom animationen och 1 betyder slutet av animationen."
+msgid "The only thing that you need to do is to define how you want it to look at every step of the animation. Manim provides you with the alpha value in the :meth:`~.Animation.interpolate` method based on frame rate of video, rate function, and run time of animation played. The alpha parameter holds a value between 0 and 1 representing the step of the currently playing animation. For example, 0 means the beginning of the animation, 0.5 means halfway through the animation, and 1 means the end of the animation."
+msgstr "Det enda du behöver göra är att definiera hur du vill att det ska se ut för varje steg i animationen. Manim ger dig alfavärdet i :meth:`~. nimation.interpolate' metoden baserat på bildhastigheten av videon, hastighetsfunktionen och körtiden för den animation som spelas. Alfaparametern har ett värde mellan 0 och 1 som representerar steget i den aktuella animationen. Till exempel betyder 0 början av animationen, 0,5 betyder halvvägs genom animationen och 1 betyder slutet av animationen."
 
 #: ../../source/tutorials/building_blocks.rst:320
-msgid "In the case of the ``Count`` animation, you just have to figure out a way to determine the number to display at the given alpha value and then set that value in the :meth:`~.Animation.interpolate_mobject` method of the ``Count`` animation. Suppose you are starting at 50 and incrementing until the :class:`~.DecimalNumber` reaches 100 at the end of the animation."
-msgstr "I fallet med ``Count`` animationen, behöver du bara hitta ett sätt att bestämma talet som ska visas för det givna alfavärdet och sedan ange det värdet i :meth:`~.Animation.interpolate_mobject` -metoden för ``Count``-animationen. Antag att du börjar med 50 och inkrementerar värdet tills :class:`~.DecimalNumber` når 100 i slutet av animationen."
+msgid "In the case of the ``Count`` animation, you just have to figure out a way to determine the number to display at the given alpha value and then set that value in the :meth:`~.Animation.interpolate` method of the ``Count`` animation. Suppose you are starting at 50 and incrementing until the :class:`~.DecimalNumber` reaches 100 at the end of the animation."
+msgstr "I fallet med ``Count`` animationen, behöver du bara hitta ett sätt att bestämma talet som ska visas för det givna alfavärdet och sedan ange det värdet i :meth:`~.Animation.interpolate` -metoden för ``Count``-animationen. Antag att du börjar med 50 och inkrementerar värdet tills :class:`~.DecimalNumber` når 100 i slutet av animationen."
 
 #: ../../source/tutorials/building_blocks.rst:323
 msgid "If alpha is 0, you want the value to be 50."

docs/source/contributing/docs.rst

@@ -81,3 +81,4 @@ Index
    docs/examples
    docs/references
    docs/typings
+   docs/types

docs/source/contributing/docs/types.rst

@@ -0,0 +1,134 @@
+===================
+Choosing Type Hints
+===================
+In order to provide the best user experience,
+it's important that type hints are chosen correctly.
+With the large variety of types provided by Manim, choosing
+which one to use can be difficult. This guide aims to
+aid you in the process of choosing the right type for the scenario.
+
+
+The first step is figuring out which category your type hint fits into.
+
+Coordinates
+-----------
+Coordinates encompass two main categories: points, and vectors.
+
+
+Points
+~~~~~~
+The purpose of points is pretty straightforward: they represent a point
+in space. For example:
+
+.. code-block:: python
+
+   def status2D(coord: Point2D) -> None:
+       x, y = coord
+       print(f"Point at {x=},{y=}")
+
+
+   def status3D(coord: Point3D) -> None:
+       x, y, z = coord
+       print(f"Point at {x=},{y=},{z=}")
+
+
+   def get_statuses(coords: Point2D_Array | Point3D_Array) -> None:
+       for coord in coords:
+           if len(coord) == 2:
+               # it's a Point2D
+               status2D(coord)
+           else:
+               # it's a point3D
+               status3D(coord)
+
+It's important to realize that the status functions accepted both
+tuples/lists of the correct length, and ``NDArray``'s of the correct shape.
+If they only accepted ``NDArray``'s, we would use their ``Internal`` counterparts:
+:class:`~.typing.InternalPoint2D`, :class:`~.typing.InternalPoint3D`, :class:`~.typing.InternalPoint2D_Array` and :class:`~.typing.InternalPoint3D_Array`.
+
+In general, the type aliases prefixed with ``Internal`` should never be used on
+user-facing classes and functions, but should be reserved for internal behavior.
+
+Vectors
+~~~~~~~
+Vectors share many similarities to points. However, they have a different
+connotation. Vectors should be used to represent direction. For example,
+consider this slightly contrived function:
+
+.. code-block:: python
+
+   def shift_mobject(mob: Mobject, direction: Vector3D, scale_factor: float = 1) -> mob:
+       return mob.shift(direction * scale_factor)
+
+Here we see an important example of the difference. ``direction`` can not, and
+should not, be typed as a :class:`~.typing.Point3D` because the function does not accept tuples/lists,
+like ``direction=(0, 1, 0)``. You could type it as :class:`~.typing.InternalPoint3D` and
+the type checker and linter would be happy; however, this makes the code harder
+to understand.
+
+As a general rule, if a parameter is called ``direction`` or ``axis``,
+it should be type hinted as some form of :class:`~.VectorND`.
+
+.. warning::
+
+   This is not always true. For example, as of Manim 0.18.0, the direction
+   parameter of the :class:`.Vector` Mobject should be ``Point2D | Point3D``,
+   as it can also accept ``tuple[float, float]`` and ``tuple[float, float, float]``.
+
+Colors
+------
+The interface Manim provides for working with colors is :class:`.ManimColor`.
+The main color types Manim supports are RGB, RGBA, and HSV. You will want
+to add type hints to a function depending on which type it uses. If any color will work,
+you will need something like:
+
+.. code-block:: python
+
+   if TYPE_CHECKING:
+       from manim.utils.color import ParsableManimColor
+
+   # type hint stuff with ParsableManimColor
+
+
+
+Béziers
+-------
+Manim internally represents a :class:`.Mobject` by a collection of points. In the case of :class:`.VMobject`,
+the most commonly used subclass of :class:`.Mobject`, these points represent Bézier curves,
+which are a way of representing a curve using a sequence of points.
+
+.. note::
+
+   To learn more about Béziers, take a look at https://pomax.github.io/bezierinfo/
+
+
+Manim supports two different renderers, which each have different representations of
+Béziers: Cairo uses cubic Bézier curves, while OpenGL uses quadratic Bézier curves.
+
+Type hints like :class:`~.typing.BezierPoints` represent a single bezier curve, and :class:`~.typing.BezierPath`
+represents multiple Bézier curves. A :class:`~.typing.Spline` is when the Bézier curves in a :class:`~.typing.BezierPath`
+forms a single connected curve. Manim also provides more specific type aliases when working with
+quadratic or cubic curves, and they are prefixed with their respective type (e.g. :class:`~.typing.CubicBezierPoints`,
+is a :class:`~.typing.BezierPoints` consisting of exactly 4 points representing a cubic Bézier curve).
+
+
+Functions
+---------
+Throughout the codebase, many different types of functions are used. The most obvious example
+is a rate function, which takes in a float and outputs a float (``Callable[[float], float]``).
+Another example is for overriding animations. One will often need to map a :class:`.Mobject`
+to an overridden :class:`.Animation`, and for that we have the :class:`~.typing.FunctionOverride` type hint.
+
+:class:`~.typing.PathFuncType` and :class:`~.typing.MappingFunction` are more niche, but are related to moving objects
+along a path, or applying functions. If you need to use it, you'll know.
+
+
+Images
+------
+There are several representations of images in Manim. The most common is
+the representation as a NumPy array of floats representing the pixels of an image.
+This is especially common when it comes to the OpenGL renderer.
+
+This is the use case of the :class:`~.typing.Image` type hint. Sometimes, Manim may use ``PIL.Image``,
+in which case one should use that type hint instead.
+Of course, if a more specific type of image is needed, it can be annotated as such.

docs/source/contributing/docs/typings.rst

@@ -1,6 +1,6 @@
-==============
-Adding Typings
-==============
+==================
+Typing Conventions
+==================
 
 .. warning::
    This section is still a work in progress.