Bunch of more examples for the docs

[kolibril13]

In this PR, I am adding more examples.
Mostly for MovingCameraScene but I will also add some things regarding ZoomedScene here.

[behackl]

We should be a little careful when it comes to rendering more complex examples: this PR currently adds over 100 seconds to the build process of the documentation (see https://readthedocs.org/projects/manimce/builds/11922534/).

Maybe it would be better to render in :quality: low by default -- it would be interesting to see in how far this brings down the build time from the 388 sec currently on this branch.

[kolibril13]

Good point.
But maybe we can get some more build time from rdt, see their message here:
https://docs.readthedocs.io/en/stable/builds.html
Read the docs community:

• 15 minutes build time
• 3GB of memory
• 2 concurrent builds
  We can increase build limits on a per-project basis. Send an email to support@readthedocs.org providing a good reason why your documentation needs more resources.
  If your business is hitting build limits hosting documentation on Read the Docs, please consider Read the Docs for Business which has much higher build resources.

[leotrs]

We should consider both adding lighter and fewer examples, as well as asking RTD for more resources.

[kolibril13]

We should consider both adding lighter and fewer examples, as well as asking RTD for more resources.

I agree on lighter, I agree on asking RTD, and I disagree on fewer examples.
Of course, examples should not be redundant, but having lots of examples for special use cases is very helpful for learning!
One website I find very inspiring in having lots of small examples is this here:
https://www.w3schools.com/python/default.asp

I will write an e-mail to them.

And one idea for making videos for the website.
In google chrome, I just inspected the frame width and the frame height of the displayed videos, and this is:
788x443 (I am working with a 1920×1080 resolution display).
Probably we can introduce a new flag :quality: website
which has these exact values.
Further, I would not render videos on low quality and therefor with 15 fps.
For me, manim is one of its main charms in having 30 or 60 fps, and when we would not show this on the website, some of its magic would not be transported.

[behackl]

Rendering videos as-is on #463 on my local PC:

The HTML pages are in build/html.

real    1m20.731s
user    1m33.939s
sys     0m46.954s

Same thing, but rendering everything in 800\times 450 with 30 fps:

The HTML pages are in build/html.

real    1m7.157s
user    1m14.398s
sys     0m36.459s

Same thing, but rendering everything in 800\times 450 with 60 fps:

The HTML pages are in build/html.

real    1m17.310s
user    1m29.425s
sys     0m37.793s

I do admit, I am surprised. I expected that rendering with 60fps was completely unfeasible anyways, but this seems like actually the resolution is the bigger limiting factor. And writing tex, thats really slow as hell. Examples with a lot of tex (like plots) take very long to render, regardless of quality.

In this way, we can choose something like 450p30 as the default quality settings for the docs. But lets not add that to the pile here; we can do it in a separate PR.

[leotrs]

Im very skeptical of those numbers 👀

[behackl]

Im very skeptical of those numbers 👀

Same. I just ran it again:

• 1440p60

The HTML pages are in build/html.

real    3m17.687s
user    4m25.648s
sys     2m27.279s

• 720p30

The HTML pages are in build/html.

real    1m18.725s
user    1m30.697s
sys     0m47.842s

• 480p15

The HTML pages are in build/html.

real    1m0.565s
user    1m5.250s
sys     0m30.015s

• 480p30

The HTML pages are in build/html.

real    1m7.150s
user    1m15.228s
sys     0m33.430s

The slowest operations, by far, is creating/compiling/converting TeX. (Which is actually not that surprising.)

And obviously, this is on a more or less decent PC. The RTD instances this is running on are slower (and need to setup the environment before building, which takes a lot of time).

[leotrs]

Thanks for those new numbers. I suggest we use 720p30 and use very minimal use of latex rendering. @kolibril13 your thoughts?

[kolibril13]

Yeah, I am happy that we don't have to drop the hight quality.
Regrading tex, I made some tests:

class Text1(Scene):
    def construct(self):
        t = MathTex("Hello World")
        self.add(t)

--- 2.0 seconds ---

class Text2(Scene):
    def construct(self):
        t = TextMobject("Hello Word")
        self.add(t)

--- 3.0 seconds ---

class Text3(Scene):
    def construct(self):
        t = Text("Hello Word")
        self.add(t)

--- 0.9 seconds ---

And now a proof of concept that including latex can be way faster, with the detour of matplotlib:
No Latex

from manim import *
class Text4(Scene):
    def construct(self):
        import matplotlib.pyplot as plt
        fig = plt.figure()
        t = np.linspace(-10, 10, 100)
        sig = 1 / (1 + np.exp(-t))
        plt.plot(t, sig, linewidth=2, label=r"Hello World")
        plt.legend(fontsize=14)
        plt.show()
        fig.canvas.draw()
        img = ImageMobject(fig.canvas.buffer_rgba())
        self.add(img)

--- 1.1 seconds ---

With Latex

class Text5(Scene):
    def construct(self):
        import matplotlib.pyplot as plt
        fig = plt.figure()
        t = np.linspace(-10, 10, 100)
        sig = 1 / (1 + np.exp(-t))
        plt.plot(t, sig, linewidth=2, label=r"$\sigma(t) = \frac{1}{1 + e^{-t}}$")
        plt.legend(fontsize=14)
        plt.show()
        fig.canvas.draw()
        img = ImageMobject(fig.canvas.buffer_rgba())
        self.add(img)

--- 1.4 seconds ---

[naveen521kk]

I can very well read from https://matplotlib.org/3.1.0/tutorials/text/usetex.html and https://matplotlib.org/3.1.0/tutorials/text/mathtext.html that what you showed is not actually LaTeX. It is a custom parser which matplotlib ships and not actually LateX.

[kolibril13]

There seems to be a problem with changing the font right now.
Also when I run this locally, without building the docs, Text it is not using the right font...
I would nevertheless keep this example for now, and make an note to it, that this still has to be improved.

[leotrs]

If the example is broken, we shouldn't add it.

[kolibril13]

...or we try to fix the font :)

[kolibril13]

what you showed is not actually LaTeX. It is a custom parser which matplotlib ships and not actually LateX.

Maybe we can use something similar?

[behackl]

Thanks for those new numbers. I suggest we use 720p30 and use very minimal use of latex rendering. @kolibril13 your thoughts?

As soon as this branch stabilizes a bit, I'd like to test the time difference between 720p30 and 480p30 on the RTD build. Then we can still see where we would rather like to go.

@kolibril13, great work with the examples so far. I like pretty much all of them. Some points I'd like to discuss when this stabilizes a little:

• https://manimce--458.org.readthedocs.build/en/458/examples/text.html contains really many very similar examples whose character rather remind me of stuff that belongs in the reference manual; maybe this could be condensed a little.
• Example3 in https://manimce--458.org.readthedocs.build/en/458/examples/animations.html is actually the same as the example in the reference manual: https://manimce--458.org.readthedocs.build/en/458/reference/manim.mobject.value_tracker.ValueTracker.html -- in cases like these, I'd rather wait for a better connection between reference manual and the examples than include duplicates.
• Render quality, as mentioned above.
• More expressive class names than Example1 - Example1453. :-)

[leotrs]

I think these three should be joined in the same example.

Also, their names could be improved a lot. Something like "TextColorExample".

[kolibril13]

I've updated the default quality and removed most :quality: low and :quality: medium. While doing so, I noticed that the examples Example3DNo3 and Example3DNo4 take extremely long (almost 40sec) to render on my PC, compared to the others (even in 480p30). Maybe we can replace these by ones that are a bit lighter on the rendering?

I think this is just the nature of these 3D scenes, that they take very long.
For the release of the first manim version, I would like to keep this example, but later I am open to finding another and better solution.
Also, now could be a good point to send the email to rdt to ask for more time (the email is already written by me and @behackl :))

[kolibril13]

I know that the example section is not completely ready by now, but I would like to merge this pr now, and make a new pr with further changes on the example files.
Things that are still to do in a future pr:

• https://manimce--458.org.readthedocs.build/en/458/examples/text.html contains really many very similar examples whose character rather remind of stuff that belongs in the reference manual; maybe this could be condensed a little.
• First example form Formula should better go into the Docstrings
• Example3 in https://manimce--458.org.readthedocs.build/en/458/examples/animations.html is actually the same as the example in the reference manual
• More expressive class names than Example1 - Example1453.
• Make https://manimce--458.org.readthedocs.build/en/458/examples/advanced_projects.html a GraphScene
• Giving credits to people

[behackl]

I think this is just the nature of these 3D scenes, that they take very long.
For the release of the first manim version, I would like to keep this example, but later I am open to finding another and better solution.

I would prefer to consider a lighter example right now such that the render time is closer to the example afterwards (~20 sec). I don't think that 40 seconds of build time is justified for any example.

Also, now could be a good point to send the email to rdt to ask for more time (the email is already written by me and @behackl :))

I would still wait a bit longer: maybe until we have a first release and exceed 10 minutes of build time? We could then ask specifically for a 30min build time limit, which seems plenty right now.

Also, somewhat related: our documentation is currently hosted at manimce.readthedocs.org, which fits if the library is called manimce. If, at some point, we switch to manim, we might want to switch to manim.readthedocs.org too. If RTD identifies projects by name, it might be good to wait for that final transfer.

[behackl]

I've been thinking: should we try to move this examples gallery to something that is closer to https://matplotlib.org/gallery.html ? (Not on this PR, but generally.)

Both considering the quantity and selection of examples, as well as the thumbnail representation on one page, I like this a lot.

[leotrs]

The last time this was discussed, I said that I would like to first see a lot more examples [than what we had then, a few weeks ago], so that then we would have a better idea of what a gallery-like page for manim would look like.

Now that we have more examples (once this PR is merged), I'm happy to revisit that idea.

[kolibril13]

Both considering the quantity and selection of examples, as well as the thumbnail representation on one page, I like this a lot.

I also like the thumbnail idea a lot!
However, I also like the idea a lot that you can press Ctrl + F on a page and Search e.g. for "y_tick_frequency" without clicking through all examples.

Probably there is a way to connect these two advantages: moving closer to https://matplotlib.org/gallery.html by adding links with thumbnails to scenes but still having scenes from the same topic on the same page. This could be maybe possible by adding hyperlinks to the subsections, like e.g. in Wikipedia: https://en.wikipedia.org/wiki/Animation#History

[behackl]

Both considering the quantity and selection of examples, as well as the thumbnail representation on one page, I like this a lot.

I also like the thumbnail idea a lot!
However, I also like the idea a lot that you can press Ctrl + F on a page and Search e.g. for "y_tick_frequency" without clicking through all examples.

Probably there is a way to connect these two advantages: moving closer to https://matplotlib.org/gallery.html by adding links with thumbnails to scenes but still having scenes from the same topic on the same page. This could be maybe possible by adding hyperlinks to the subsections, like e.g. in Wikipedia: https://en.wikipedia.org/wiki/Animation#History

We can discuss specifics at a later point. However, if you have a concrete parameter like y_tick_frequency in mind, the best way is simply to use the search function provided by RTD. It does exactly that pretty well.

[leotrs]

I know that the example section is not completely ready by now, but I would like to merge this pr now, and make a new pr with further changes on the example files.
Things that are still to do in a future pr:

If you are able to gather all of the questions and comments that are still open, and move them to a new PR, then I'm all for that.

[leotrs]

@kolibril13 has told me he has stored all the open discussion and comments and will work on them on a future PR. This is ready to merge as far as I can tell :)

[behackl]

Sounds good to me as well. Please make sure to either put the open TODOs from here in an issue, or if you open a PR soon, then it is also fine to document them there.

It is great to see our documentation come to life a bit more! :-)