Skip to content

armgit / manim

Public Imported from GitHub
0

A community-maintained Python framework for creating mathematical animations.

Add some documentation to Scene.construct (#753)

Leo Torres9ab2327953de
diff --git a/manim/animation/creation.py b/manim/animation/creation.py
index f8bc9e182..0c8aff24c 100644
--- a/manim/animation/creation.py
+++ b/manim/animation/creation.py
@@ -1,4 +1,40 @@
-"""Animate the display or removal of a mobject from a scene."""
+r"""Animate the display or removal of a mobject from a scene.
+
+.. manim:: CreationModule
+ :hide_source:
+
+ from manim import ManimBanner
+
+ class CreationModule(Scene):
+ def construct(self):
+ texts = [Text('manim'), Text('manim')]
+ texts[0].shift(LEFT * 2 + UP)
+ texts[1].shift(RIGHT * 2 + UP)
+ self.add(*texts)
+
+ objs = [ManimBanner().scale(0.25) for _ in range(5)]
+ for idx, obj in enumerate(objs):
+ obj.shift(LEFT * 6 + RIGHT * (2.75 * idx) + DOWN)
+ self.add(*objs)
+
+ self.play(
+ # text creation
+ Write(texts[0]),
+ AddTextLetterByLetter(texts[1]),
+
+ # mobject creation
+ ShowCreation(objs[0]),
+ Uncreate(objs[1]),
+ DrawBorderThenFill(objs[2]),
+ ShowIncreasingSubsets(objs[3]),
+ ShowSubmobjectsOneByOne(objs[4]),
+
+ run_time=3,
+ )
+
+ self.wait()
+
+"""
__all__ = [
@@ -47,14 +83,24 @@ class ShowPartial(Animation):
super().__init__(mobject, **kwargs)
def interpolate_submobject(self, submob, start_submob, alpha):
- submob.pointwise_become_partial(start_submob, *self.get_bounds(alpha))
+ submob.pointwise_become_partial(start_submob, *self._get_bounds(alpha))
- def get_bounds(self, alpha):
+ def _get_bounds(self, alpha):
raise NotImplementedError("Please use ShowCreation or ShowPassingFlash")
class ShowCreation(ShowPartial):
- """Incrementally shows the VMobject.
+ """Incrementally show a VMobject.
+
+ Parameters
+ ----------
+ mobject : :class:`~.VMobject`
+ The VMobject to animate.
+
+ Raises
+ ------
+ :class:`TypeError`
+ If ``mobject`` is not an instance of :class:`~.VMobject`.
Examples
--------
@@ -64,7 +110,6 @@ class ShowCreation(ShowPartial):
def construct(self):
self.play(ShowCreation(Square()))
-
See Also
--------
:class:`~.ShowPassingFlash`
@@ -74,11 +119,19 @@ class ShowCreation(ShowPartial):
def __init__(self, mobject, lag_ratio=1, **kwargs):
super().__init__(mobject, lag_ratio=lag_ratio, **kwargs)
- def get_bounds(self, alpha):
+ def _get_bounds(self, alpha):
return (0, alpha)
class Uncreate(ShowCreation):
+ """Like :class:`ShowCreation` but in reverse.
+
+ See Also
+ --------
+ :class:`ShowCreation`
+
+ """
+
def __init__(
self, mobject, rate_func=lambda t: smooth(1 - t), remover=True, **kwargs
):
@@ -86,6 +139,8 @@ class Uncreate(ShowCreation):
class DrawBorderThenFill(Animation):
+ """Draw the border first and then show the fill."""
+
def __init__(
self,
vmobject,
@@ -140,6 +195,8 @@ class DrawBorderThenFill(Animation):
class Write(DrawBorderThenFill):
+ """Simulate hand-writing a :class:`~.Text` or hand-drawing a :class:`~.VMobject`."""
+
def __init__(
self, vmobject, run_time=None, lag_ratio=None, rate_func=linear, **kwargs
):
@@ -166,6 +223,8 @@ class Write(DrawBorderThenFill):
class ShowIncreasingSubsets(Animation):
+ """Show one submobject at a time, leaving all previous ones displayed on screen."""
+
def __init__(
self, group, suspend_mobject_updating=False, int_func=np.floor, **kwargs
):
@@ -185,8 +244,13 @@ class ShowIncreasingSubsets(Animation):
class AddTextLetterByLetter(ShowIncreasingSubsets):
- """
- Add a Text Object letter by letter on the scene. Use time_per_char to change frequency of appearance of the letters.
+ """Show a :class:`~.Text` letter by letter on the scene.
+
+ Parameters
+ ----------
+ time_per_char : :class:`float`
+ Frequency of appearance of the letters.
+
"""
def __init__(
@@ -216,6 +280,8 @@ class AddTextLetterByLetter(ShowIncreasingSubsets):
class ShowSubmobjectsOneByOne(ShowIncreasingSubsets):
+ """Show one submobject at a time, removing all previously displayed ones from screen."""
+
def __init__(self, group, int_func=np.ceil, **kwargs):
new_group = Group(*group)
super().__init__(new_group, int_func=int_func, **kwargs)
@@ -229,6 +295,8 @@ class ShowSubmobjectsOneByOne(ShowIncreasingSubsets):
# TODO, this is broken...
class AddTextWordByWord(Succession):
+ """Show a :class:`~.Text` word by word on the scene."""
+
def __init__(self, text_mobject, run_time=None, time_per_char=0.06, **kwargs):
self.time_per_char = time_per_char
tpc = self.time_per_char
diff --git a/manim/animation/indication.py b/manim/animation/indication.py
index ba6a3629a..860973705 100644
--- a/manim/animation/indication.py
+++ b/manim/animation/indication.py
@@ -177,7 +177,7 @@ class ShowPassingFlash(ShowPartial):
self.time_width = time_width
super().__init__(mobject, remover=remover, **kwargs)
- def get_bounds(self, alpha):
+ def _get_bounds(self, alpha):
tw = self.time_width
upper = interpolate(0, 1 + tw, alpha)
lower = upper - tw
diff --git a/manim/scene/scene.py b/manim/scene/scene.py
index feced94d6..193fb524c 100644
--- a/manim/scene/scene.py
+++ b/manim/scene/scene.py
@@ -28,28 +28,32 @@ from ..utils.exceptions import EndSceneEarlyException
class Scene(Container):
"""A Scene is the canvas of your animation.
- All of your own named Scenes will be subclasses of Scene, or other named
- scenes.
+ The primary role of :class:`Scene` is to provide the user with tools to manage
+ mobjects and animations. Generally speaking, a manim script consists of a class
+ that derives from :class:`Scene` whose :meth:`Scene.construct` method is overriden
+ by the user's code.
+
+ Mobjects are displayed on screen by calling :meth:`Scene.add` and removed from
+ screen by calling :meth:`Scene.remove`. All mobjects currently on screen are kept
+ in :attr:`Scene.mobjects`. Animations are played by calling :meth:`Scene.play`.
+
+ A :class:`Scene` is rendered internally by calling :meth:`Scene.render`. This in
+ turn calls :meth:`Scene.setup`, :meth:`Scene.construct`, and
+ :meth:`Scene.tear_down`, in that order.
+
+ It is not recommended to override the ``__init__`` method in user Scenes. For code
+ that should be ran before a Scene is rendered, use :meth:`Scene.setup` instead.
+
Examples
--------
- Override the construct() method to tell Manim what should go on in the
- Scene.
+ Override the :meth:`Scene.construct` method with your code.
.. code-block:: python
class MyScene(Scene):
def construct(self):
- self.play(
- Write(Text("Hello World!"))
- )
-
- Some important variables to note are:
- camera: The camera object to be used for the scene.
- file_writer : The object that writes the animations in the scene to a video file.
- mobjects : The list of mobjects present in the scene.
- foreground_mobjects : List of mobjects explicitly in the foreground.
- random_seed: The seed with which all random operations are done.
+ self.play(Write(Text("Hello World!")))
"""
@@ -118,9 +122,35 @@ class Scene(Container):
pass
def construct(self):
- """
- The primary method for constructing (i.e adding content to)
- the Scene.
+ """Add content to the Scene.
+
+ From within :meth:`Scene.construct`, display mobjects on screen by calling
+ :meth:`Scene.add` and remove them from screen by calling :meth:`Scene.remove`.
+ All mobjects currently on screen are kept in :attr:`Scene.mobjects`. Play
+ animations by calling :meth:`Scene.play`.
+
+ Notes
+ -----
+ Initialization code should go in :meth:`Scene.setup`. Termination code should
+ go in :meth:`Scene.tear_down`.
+
+ Examples
+ --------
+ A typical manim script includes a class derived from :class:`Scene` with an
+ overriden :meth:`Scene.contruct` method:
+
+ .. code-block:: python
+
+ class MyScene(Scene):
+ def construct(self):
+ self.play(Write(Text("Hello World!")))
+
+ See Also
+ --------
+ :meth:`Scene.setup`
+ :meth:`Scene.render`
+ :meth:`Scene.tear_down`
+
"""
pass # To be implemented in subclasses