A community-maintained Python framework for creating mathematical animations.
New tutorial: manim internals basic (#394)
Leo Torrese48d46717bff
diff --git a/docs/source/_static/building_blocks/addremove.gif b/docs/source/_static/building_blocks/addremove.gifnew file mode 100644index 000000000..d5d69db96Binary files /dev/null and b/docs/source/_static/building_blocks/addremove.gif differdiff --git a/docs/source/_static/building_blocks/placement.png b/docs/source/_static/building_blocks/placement.pngnew file mode 100644index 000000000..2b2aab6cdBinary files /dev/null and b/docs/source/_static/building_blocks/placement.png differdiff --git a/docs/source/_static/building_blocks/shapes.png b/docs/source/_static/building_blocks/shapes.pngnew file mode 100644index 000000000..dc664e8cdBinary files /dev/null and b/docs/source/_static/building_blocks/shapes.png differdiff --git a/docs/source/_static/building_blocks/styling.png b/docs/source/_static/building_blocks/styling.pngnew file mode 100644index 000000000..e1c1bd490Binary files /dev/null and b/docs/source/_static/building_blocks/styling.png differdiff --git a/docs/source/_static/building_blocks/zorder.png b/docs/source/_static/building_blocks/zorder.pngnew file mode 100644index 000000000..6dbce6a74Binary files /dev/null and b/docs/source/_static/building_blocks/zorder.png differdiff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rstindex 2f1393b59..ab470ae21 100644--- a/docs/source/tutorials.rst+++ b/docs/source/tutorials.rst@@ -3,7 +3,9 @@ Tutorials.. toctree:::caption: Table of Contents+ :maxdepth: 2tutorials/quickstarttutorials/a_deeper_look+ tutorials/building_blockstutorials/configurationdiff --git a/docs/source/tutorials/building_blocks.rst b/docs/source/tutorials/building_blocks.rstnew file mode 100644index 000000000..750055899--- /dev/null+++ b/docs/source/tutorials/building_blocks.rst@@ -0,0 +1,326 @@+#######################+Manim's building blocks+#######################++This document explains the building blocks of manim and will give you all the+necessary tools to start producing your own videos.++Essentially, manim puts at your disposal three different concepts that you can+orchestrate together in order to produce mathematical animations: the+**mathematical object** (or **mobject** for short) the **animation**, and the+**scene**. As we will see in the following sections, each of these three+concepts is implemented in manim as a separate class: the :class:`.Mobject`,+:class:`.Animation`, and :class:`.Scene` classes.++.. note:: It is recommended that you read the tutorials :doc:`quickstart` and+ :doc:`a_deeper_look` before reading this page.+++********+Mobjects+********++Mobjects are the basic building block for all manim animations. Each class+that derives from :class:`.Mobject` represents an object that can be displayed+on screen. For example, simple shapes such as :class:`.Circle`,+:class:`.Arrow`, and :class:`.Rectangle` are all mobjects. More complicated+constructs such as :class:`.Axes`, :class:`.FunctionGraph`, or+:class:`.BarChart` are mobjects as well.++If you try to display on screen an instance of :class:`.Mobject`, you will only+see an empty frame. The reason is that the :class:`.Mobject` class is an+abstract base class of all other mobjects, i.e. it does not have any+pre-determined visual shape that can be displayed on screen. It is only the+skeleton of a thing that *could* be displayed. Therefore, you will rarely need+to use plain instances of :class:`.Mobject`; instead you will most likely+create instances of its derived classes. One of these derived classes is+:class:`.VMobject`. The ``V`` stands for Vectorized Mobject. In essence, a+vmobject is a mobject that uses vector `vector graphics+<https://en.wikipedia.org/wiki/Vector_graphics/>`_ to be displayed. Most of+the time, you will be dealing with vmobjects, though we will continue to use+the term "mobject" to refer to the class of shapes that can be displayed on+screen, as it is more general.++.. note:: Any object that can be displayed on screen is a ``mobject``, even if+ it is not necessarily *mathematical* in nature.++.. tip:: To see examples of classes derived from :class:`.Mobject`, see the+ :mod:`.geometry` module. Most of these are in fact derived from+ :class:`.VMobject` as well.+++Creating and displaying mobjects+================================++As explained in :doc:`quickstart`, usually all of the code in a manim+script is put inside the :meth:`.construct` method of a :class:`.Scene` class.+To display a mobject on the screen, call the :meth:`~.Scene.add` method of the+containing :class:`.Scene`. This is the principal way of displaying a mobject+on the screen when it is not being animated. To remove a mobject from the+screen, simply call the :meth:`~.Scene.remove` method from the containing+:class:`.Scene`.++.. manim:: CreatingMobjects+ :display_source:+ :quality: medium++ class CreatingMobjects(Scene):+ def construct(self):+ circle = Circle()+ self.add(circle)+ self.wait(1)+ self.remove(circle)+ self.wait(1)+++Placing mobjects+================++Let's define a new :class:`.Scene` called ``Shapes`` and :meth:`~.Scene.add`+some mobjects to it. This script generates a static picture that displays a+circle, a square, and a triangle:++.. manim:: Shapes+ :display_source:+ :quality: medium++ class Shapes(Scene):+ def construct(self):+ circle = Circle()+ square = Square()+ triangle = Triangle()++ circle.shift(LEFT)+ square.shift(UP)+ triangle.shift(RIGHT)++ self.add(circle, square, triangle)+ self.wait(1)++By default, mobjects are placed at the center of coordinates, or *origin*, when+they are first created. They are also given some default colors. Further, the+``Shapes`` scene places the mobjects by using the :meth:`.shift` method. The+square is shifted one unit in the ``UP`` direction from the origin, while the+circle and triangle are shifted one unit ``LEFT`` and ``RIGHT``, respectively.++.. attention:: Unlike other graphics software, manim places the center of+ coordinates at the center of the screen. The positive vertical+ direction is up, and the positive horizontal direction is right.+ See also the constants ``ORIGIN``, ``UP``, ``DOWN``, ``LEFT``,+ ``RIGHT``, and others, defined in the :mod:`.constants` module.++There are many other possible ways to place mobjects on the screen, for example+:meth:`.move_to`, :meth:`.next_to`, and :meth:`.align_to`. The next scene+``MobjectPlacement`` uses all three.++.. manim:: MobjectPlacement+ :display_source:+ :quality: medium++ class MobjectPlacement(Scene):+ def construct(self):+ circle = Circle()+ square = Square()+ triangle = Triangle()++ # place the circle two units left from the origin+ circle.move_to(LEFT * 2)+ # place the square to the left of the circle+ square.next_to(circle, LEFT)+ # align the left border of the triangle to the left border of the circle+ triangle.align_to(circle, LEFT)++ self.add(circle, square, triangle)+ self.wait(1)++The :meth:`.move_to` method uses absolute units (measured relative to the+``ORIGIN``), while :meth:`.next_to` uses relative units (measured from the+mobject passed as the first argument). :meth:`align_to` uses ``LEFT`` not as+measuring units but as a way to determine the border to use for alignment. The+coordinates of the borders of a mobject are determined using an imaginary+bounding box around it.++.. tip:: Many methods in manim can be chained together. For example the two+ lines++ .. code-block:: python++ square = Square()+ square.shift(LEFT)++ can be replaced by++ .. code-block:: python++ square = Square().shift(LEFT)++ Technically, this is possible because most methods calls return the modified mobject.+++Styling mobjects+================++The following scene changes the default aesthetics of the mobjects.++.. manim:: MobjectStyling+ :display_source:+ :quality: medium++ class MobjectStyling(Scene):+ def construct(self):+ circle = Circle().shift(LEFT)+ square = Square().shift(UP)+ triangle = Triangle().shift(RIGHT)++ circle.set_stroke(color=GREEN, width=20)+ square.set_fill(YELLOW, opacity=1.0)+ triangle.set_fill(PINK, opacity=0.5)++ self.add(circle, square, triangle)+ self.wait(1)++This scene uses two of the main functions that change the visual style of a+mobject: :meth:`.set_stroke` and :meth:`.set_fill`. The former changes the+visual style of the mobject's border while the latter changes the style of the+interior. By default, most mobjects have a fully transparent interior so you+must specify the ``opacity`` parameter in order to display the color. An+opacity of ``1.0`` means fully opaque, while ``0.0`` means fully transparent.++Only instances of :class:`.VMobject` implement :meth:`.set_stroke` and+:meth:`.set_fill`. Instances of :class:`.Mobject` implement+:meth:`.~Mobject.set_color` instead. The vast majority of pre-defined classes+are derived from :class:`.VMobject` so it is usually safe to assume that you+have access to :meth:`.set_stroke` and :meth:`.set_fill`.+++Mobject on-screen order+=======================++The next scene is exactly the same as the ``MobjectStyling`` scene from the+previous section, except for exactly one line.++.. manim:: MobjectZOrder+ :display_source:+ :quality: medium++ class MobjectZOrder(Scene):+ def construct(self):+ circle = Circle().shift(LEFT)+ square = Square().shift(UP)+ triangle = Triangle().shift(RIGHT)++ circle.set_stroke(color=GREEN, width=20)+ square.set_fill(YELLOW, opacity=1.0)+ triangle.set_fill(PINK, opacity=0.5)++ self.add(triangle, square, circle)+ self.wait(1)++The only difference here (besides the scene name) is the order in which the+mobjects are added to the scene. In ``MobjectStyling``, we added them as+``add(circle, square, triangle)``, whereas in ``MobjectZOrder`` we add them as+``add(triangle, square, circle)``.++As you can see, the order of the arguments of :meth:`~.Scene.add` determines+the order that the mobjects are displayed on screen, with the left-most+arguments being put in the back.+++**********+Animations+**********++At the heart of manim is animation. Generally, you can add an animation to+your scene by calling the :meth:`~.Scene.play` method.++.. manim:: SomeAnimations+ :display_source:+ :quality: medium++ class SomeAnimations(Scene):+ def construct(self):+ square = Square()+ self.add(square)++ # some animations display mobjects, ...+ self.play(FadeIn(square))++ # ... some move or rotate mobjects around...+ self.play(Rotate(square, PI/4))++ # some animations remove mobjects from the screen+ self.play(FadeOut(square))++ self.wait(1)++Put simply, animations are procedures that interpolate between two mobjects.+For example, :code:`FadeIn(square)` starts with a fully transparent version of+:code:`square` and ends with a fully opaque version, interpolating between them+by gradually increasing the opacity. :class:`.FadeOut` works in the opposite+way: it interpolates from fully opaque to fully transparent. As another+example, :class:`.Rotate` starts with the mobject passed to it as argument, and+ends with the same object but rotated by a certain amount, this time+interpolating the mobject's angle instead of its opacity.+++Animating methods+=================++Any property of a mobject that can be changed can be animated. In fact, any+method that changes a mobject's property can be used as an animation, through+the use of :class:`.ApplyMethod`.++.. manim:: ApplyMethodExample+ :display_source:+ :quality: medium++ class ApplyMethodExample(Scene):+ def construct(self):+ square = Square().set_fill(RED, opacity=1.0)+ self.add(square)++ # animate the change of color+ self.play(ApplyMethod(square.set_fill, WHITE))+ self.wait(1)++ # animate the change of position+ self.play(ApplyMethod(square.shift, UP))+ self.wait(1)++:meth:`.ApplyMethod` receives one mandatory argument which is the method of the+mobject to animate (e.g. :code:`square.set_fill` or :code:`square.shift`), and+any number of optional arguments which are then passed to the method call. For+example, :code:`ApplyMethod(square.shift, UP)` executes+:code:`square.shift(UP)`, but animates it instead of applying it immediately.++Animation run time+==================++By default, any animation passed to :meth:`play` lasts for exactly one second.+Use the :code:`run_time` argument to control the duration.++.. manim:: RunTime+ :display_source:+ :quality: medium++ class RunTime(Scene):+ def construct(self):+ square = Square()+ self.add(square)+ self.play(ApplyMethod(square.shift, UP), run_time=3)+ self.wait(1)+++******+Scenes+******++The :class:`.Scene` class is the connective tissue of manim. Every mobject has+to be :meth:`added <.Scene.add>` to a scene to be displayed, or :meth:`removed+<.Scene.remove>` from it to cease being displayed. Every animation has to be+:meth:`played <.Scene.play>` by a scene, and every time interval where no+animation occurs is determined by a call to :meth:`~.Scene.wait`. All of the+code of your video must be contained in the :meth:`~.Scene.construct` method of+a class that derives from :class:`.Scene`. Finally, a single file may contain+multiple :class:`.Scene` subclasses in the event that multiple scenes are to be+rendered at the same time.diff --git a/docs/source/tutorials/quickstart.rst b/docs/source/tutorials/quickstart.rstindex 8ac7a42ab..9ab8f05d1 100644--- a/docs/source/tutorials/quickstart.rst+++ b/docs/source/tutorials/quickstart.rst@@ -1,3 +1,4 @@+==========Quickstart==========@@ -39,9 +40,6 @@ and copy the following code in it... code-block:: pythonfrom manim import *-- # all code must be contained inside the construct- # method of a class that inherits from Sceneclass SquareToCircle(Scene):def construct(self):circle = Circle() # create a circle@@ -75,6 +73,54 @@ manim has not been installed correctly. Please refer to the:doc:`../installation/troubleshooting` page for more information.+***********+Explanation+***********++Let's go line by line over the script we just executed to see how manim was+able to generate the video.++The first line++.. code-block:: python++ from manim import *++imports all of the contents of the library. This is the recommended way of+using manim, as usually in a single script you will be using quite a few names+from the manim namespace. In particular, this line includes all of the names+used in the script: ``Scene``, ``Circle``, ``PINK`` and ``ShowCreation``.++Now let's look at the next two lines.++.. code-block:: python++ class SquareToCircle(Scene):+ def construct(self):++Most of the time, the code for scripting an animation with manim will go inside+the :meth:`~.Scene.construct` method of a class that derives from :class:`.Scene`. Inside this+method, you will create objects, display them on screen, and animate them.++The next two lines create a circle and set its color and opacity.++.. code-block:: python++ circle = Circle() # create a circle+ circle.set_fill(PINK, opacity=0.5) # set the color and transparency++Finally, the last line uses the animation :class:`.ShowCreation` to display the+circle on screen.++.. code-block:: python++ self.play(ShowCreation(circle)) # show the circle on screen++.. tip:: Every animation must be contained within the :meth:`~.Scene.construct` method of a+ class that derives from :class:`.Scene`. Other code, for example auxiliary+ or mathematical functions, may reside outside the class.++Some bells and whistles***********************@@ -127,6 +173,7 @@ implement complicated and mathematically-intensive animations (such as cleanlyinterpolating between two geometric shapes) in very few lines of code.+************You're done!************