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.pyindex 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_chartpc = self.time_per_chardiff --git a/manim/animation/indication.py b/manim/animation/indication.pyindex ba6a3629a..860973705 100644--- a/manim/animation/indication.py+++ b/manim/animation/indication.py@@ -177,7 +177,7 @@ class ShowPassingFlash(ShowPartial):self.time_width = time_widthsuper().__init__(mobject, remover=remover, **kwargs)- def get_bounds(self, alpha):+ def _get_bounds(self, alpha):tw = self.time_widthupper = interpolate(0, 1 + tw, alpha)lower = upper - twdiff --git a/manim/scene/scene.py b/manim/scene/scene.pyindex feced94d6..193fb524c 100644--- a/manim/scene/scene.py+++ b/manim/scene/scene.py@@ -28,28 +28,32 @@ from ..utils.exceptions import EndSceneEarlyExceptionclass 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:: pythonclass 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):passdef 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