Skip to content

Commit adc1ac9

Browse files
TravorLZHTravorLZH
committed
Format README and add make some adjustments (malhotra5#5)
* README.md: Add installation guide for Mac OSX, and use TexMobject for equations in the LaTeX tutorial (It's spelled as `LaTeX` instead of `LaTex`). See more in README.md
1 parent 32ea94d commit adc1ac9

File tree

1 file changed

+108
-81
lines changed

1 file changed

+108
-81
lines changed

‎README.md

+108-81
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
# Manim-Tutorial
22
A tutorial for manim, a mathematical animation engine made by 3b1b for Python.
3-
## Requirements
4-
* Python 3.7 (I managed to run it on version 3.6.7, so I'm guessing 3.6 and above works)
5-
* Linux
3+
64
## Table of Contents
75
* [Installations](#Installations)
8-
* [Common Problems](#Common-Problems)
6+
* [Linux](#Linux)
7+
* [Mac OSX](#Mac-OSX)
8+
* [Common Problems during Installation](#Common-Problems-during-Installation)
99
* [Running Manim Projects](#Running-Manim-Projects)
1010
* [What ClassName means](#classNames)
1111
* [What are the possible args](#Args)
@@ -32,66 +32,91 @@ A tutorial for manim, a mathematical animation engine made by 3b1b for Python.
3232
* [Resources](#Resources)
3333
* [Further Work](#Further-Work)
3434
* [Acknowledgements](#Acknowledgements)
35+
3536
## Installations
36-
This installation and guide is meant for linux users. We will start by installing prerequisites.
3737

38-
Lets first get the repo for manim, using:
39-
``` bash
40-
git clone https://github.com/3b1b/manim.git
41-
```
38+
Assuming you have Python 3 installed and set up properly on your machine.
39+
40+
Since [a commit][commit] by [@JohnAZoidberg][committer] in April, manim has been made installable using Python's tool `pip`, so the installation process is much simpler than before.
4241

42+
[commit]: https://github.com/3b1b/manim/commit/2a6918cc30336544856a68f065a21ba2b769b01c
43+
[committer]: https://github.com/JohnAZoidberg
44+
45+
### Linux
4346
We will start with installing some system requirements: Cairo, Latex, ffmpeg and sox.
4447

45-
Install by running the following commands on the terminal:
48+
```shell
49+
$ sudo apt-get install libcairo2-dev libjpeg-dev libgif-dev
50+
$ sudo apt-get install texlive-latex-base texlive-full texlive-fonts-extra
51+
```
4652

47-
``` bash
48-
sudo apt install SystemReq
53+
After having these libraries and tools installed in your computer, you can now type this command to finish the last step of the installation
54+
```shell
55+
$ pip3 install manim
4956
```
57+
> Don't worry, `pip` automatically gathers Python dependencies of manim
5058
51-
Some additional installations are mentioned below
52-
``` bash
53-
sudo apt-get install libcairo2-dev libjpeg-dev libgif-dev
54-
sudo apt install texlive-latex-base texlive-full texlive-fonts-extra
59+
### Mac OSX
60+
A popular package manager called [HomeBrew][brew_website] is recommended for coding on a Mac because you do not have to go to App Store to or download dmg files from websites.
61+
62+
To support rendering SVG files when creating videos, you need to install MacTex either by downloading from [its website][mactex_website] or using HomeBrew:
63+
```shell
64+
$ brew cask install mactex
5565
```
56-
Phew! This will be the last installation for additional python modules. Run this in the terminal
57-
``` bash
58-
python3 -m pip install -r requirements.txt
66+
67+
At last, use `pip` to install your manim:
68+
```shell
69+
$ pip3 install manim
5970
```
6071

61-
### Common-Problems
62-
* Problem #1: Cairo System requirement
63-
People are sometimes unable to install cairo through the terminal. But, it is possible to install it using the Python.
64-
``` bash
65-
pip3 install pycairo
72+
[brew_website]: https://brew.sh
73+
[mactex_website]: https://www.tug.org/mactex/
74+
75+
### Common Problems
76+
1. Cairo System requirement
77+
78+
People are sometimes unable to install cairo through the terminal, but luckily Python can help us fix this:
79+
```shell
80+
$ pip3 install pycairo
6681
```
6782

68-
* Problem #2: **Exception: Latex error converting to dvi. See log output above or the log file**
69-
This error can be frustrating. Especially when you don't know what to isntall. But if you followed my installation guide, this error is not due to missing a system requirement. Rather, there is a problem with the code.
83+
2. `Exception: Latex error converting to dvi. See log output above or the log file`
84+
85+
This error can be frustrating especially when you don't know what to install. But if you followed my installation guide, this error is not due to missing a system requirement. Otherwise, check your `TexMobject`s in your code.
86+
87+
3. `No module named manim`
7088

71-
* Problem #3: **No module named manim**
7289
This error occurs when you use the command to run a manim project when your not in the parent directory. Make sure that your current directory is in manim, and no other sub directory.
73-
## Running-Manim-Projects
90+
91+
## Running Manim Projects
92+
93+
> I recommend to look at these later, and start with the tutorial
94+
7495
Easy way to test whether all your installations are working is by running the command below
75-
```bash
76-
python3 -m manim example_scenes.py SquareToCircle -pl
96+
```shell
97+
$ manim example_scenes.py SquareToCircle -pl
7798
```
7899

79100
If it worked, then congratulations! Now you can run manim programs and get started with making animations.
80101
Now, this will be the general command to run all manim projects
81-
```python
82-
python3 -m manim pythonFile.py className -args
102+
```shell
103+
$ manim pythonFile.py SceneName options...
83104
```
84105

85-
**NOTE 1**: Your videos that you make are saved in the folder called *media*. \
86-
**NOTE 2**: The command for running the manim programs should only be run in the parent directory.
87-
88-
### classNames
89-
Manim programs have a certain structure. The Python program file requires you to make classes for all your series of animations. If you make more than a few classes, you have to run commands for every class you make. Seperate videos are made for every class.
90-
### Args
91-
Args are a list of arguements that can be stated when running the program. The most important agruements and it's explanations are provided in the [GO TO GUIDE.](#GO-TO-GUIDE)
92-
I recommend to look at it later, and start with the tutorial.
106+
* **SceneName**: Manim programs have a certain structure. The Python program file requires you to make classes for all your series of animations. If you make more than a few classes, you have to run commands for every class you make. Seperate videos are made for every class.
107+
* **options**: Args are a list of arguments that can be stated when running the program. The most important arguments and it's explanations are provided in the [GO TO GUIDE](#GO-TO-GUIDE-).
108+
109+
There are also some intersting facts **to care about** when building the videos:
110+
111+
1. The videos you've made are saved in a folder called `videos`.
112+
2. Manim converts `TexMobject` (`TextMobject` is a child class of `TexMobject`) to SVG before rendering them in the video, so a folder called `Tex` is created for storing the svg files of these `TexMobject`'s.
113+
3. Do **NOT** delete `Tex` when cleaning your project. When generating LaTeX, manim first generates the hash for the specific `TexMobject` according to the content of text. This generated hash will eventually be the file name of the svg output of the `TexMobject`, and when the svg file already exists in the `Tex` directory, manim will skip compiling the current `TexMobject` since the SVG is already available for rendering. If you delete `Tex` folder, you will need to have all the SVG's built again when running manim next time, which is _extremely_ time-consuming. See also [`manimlib/utils/tex_file_writing.py`][tex_file_writing_source]
114+
115+
[tex_file_writing_source]: https://github.com/3b1b/manim/blob/master/manimlib/utils/tex_file_writing.py
116+
93117
## Tutorial!
94118
Finally we can start. In this tutorial, we will learn by doing.
119+
95120
### Basics
96121
``` python
97122
from manimlib.imports import *
@@ -112,14 +137,16 @@ class Shapes(Scene):
112137
```
113138

114139
We will break this into parts:
115-
* Import: The import in this code is the import we will use in all manim projects. It has almost all the imports we will ever require
140+
* Import: The creators of manim understands our mind when using abundant animation objects in the video, so they allow us to import everything needed for creating math animations by importing `manimlib.imports`
116141
* Class: For running animations, you have to make a class that has a base class from manim.
117-
* Method: The construct method is special to manim. Manim calls on construct for creating animations. Therefore, every class that runs manim has to have this method.
142+
* **construct()** method: While creating animation for a scene, manim creates an object for the specific scene class. According to the source code of [`manimlib/scene/scene.py`][scene_source], after being run from `__init__()`, the Scene class itself calls `construct()`, so put your animation code in `construct()` if you want manim to render them.
118143
* Code: You don't have to fully understand how the code works yet. But you can see that you first define your animations, and then you display it. You can experiment with the order in which you define and display.
119144

120-
**NOTE**: If you recall, to run this animation, you would run the following in the terminal -
121-
```bash
122-
python3 -m manim fileName.py Shapes -pl
145+
[scene_source]: https://github.com/3b1b/manim/blob/master/manimlib/scene/scene.py
146+
147+
**NOTE**: If you recall, to run this animation, you would run the following in the terminal
148+
```shell
149+
$ manim fileName.py Shapes -pl
123150
```
124151
**Click for results on YouTube:**
125152

@@ -162,10 +189,10 @@ class Shapes(Scene):
162189
```
163190
After looking at a lot of pieces of code in this tutorial, you will eventually familiarize yourself with manim. So lets start!
164191

165-
Our focus is going to shift from understanding the structure of our code, to understanding the code itself. The first import statement imports many of the classes we will use.
192+
Our focus is going to shift from understanding the structure of our code, to understanding the code itself.
166193

167-
The section for making shapes creates shapes that can be used in manim. You can define it's size, color,etc.
168-
You will see some methods such as *surround* or *FadeOut*, we wil classify them later. The code is simple enough to read, most of it looks like English.
194+
The section for making shapes creates shapes that can be used in manim. You can define it's size, color, etc.
195+
You will see some methods such as `surround` or `FadeOut`, we will classify them later. The code is simple enough to read, most of it looks like English.
169196

170197
The section for showing the animaton displays the shapes, as specified in the code. Let's look at the what the code offers.
171198

@@ -182,27 +209,26 @@ The section for showing the animaton displays the shapes, as specified in the co
182209
* FadeOut
183210
* GrowFromCenter
184211

185-
**Adding:**
186-
These are some of the methods for adding mobjects or playing Animations on mobjects. Note: If you play an animation, you don't have to add it to the screen. The animation does it for you.
212+
**Adding:** These are some of the methods for adding mobjects or playing Animations on mobjects. Note: If you play an animation, you don't have to add it to the screen. The animation does it for you.
187213
* Play
188214
* Add
189215

190216
In this code, I specifically included an example that I found useful to know.
191-
``` python
192-
pointers.append(Line(ORIGIN, np.array([cos(pi/180*360/8*i),sin(pi/180*360/8*i), 0]),color=YELLOW))
217+
```python
218+
pointers.append(Line(ORIGIN, np.array([cos(pi/180*360/8*i),sin(pi/180*360/8*i), 0]),color=YELLOW))
193219
```
194220
I am appending mobjects into an list. This way I can manipulate the mobjects in the list. However, some manim methods such as *FadeOut()* can't take multiple mobjects at once. This makes it hard to do multiple tasks with less lines of code. We will take a look at a way to overcome that problem later. Although, some methods do however take multiple mobjects.
195221

196222
For example: self.add() took the list. However, you have to unpack the list first.
197223
```python
198-
self.add(*pointers)
224+
self.add(*pointers)
199225
```
200226
Here, mobjects in the list pointers, we unpacked and passed as arguments to *add()*. Notice the syntax for doing so. We put * before the list.
201227

202228
Last note. If you realized, the base class of the class above was *Scene*. This is provided by manim. Using it, we can access methods pertaining to manim. Manim also has many other base classes that we can use. If you realize, the lines of code below come from the base class.
203229
```python
204-
self.add()
205-
self.play()
230+
self.add()
231+
self.play()
206232
```
207233
There are other bases classes we will explore for making Graphs, 3D Scenes,etc.
208234

@@ -250,7 +276,7 @@ TextMobjects will be used later on to write good looking math equations.
250276

251277
[![Youtube video link](https://img.youtube.com/vi/3pxIVQxlpRQ/0.jpg)](https://www.youtube.com/watch?v=3pxIVQxlpRQ)
252278

253-
### Math-Equations
279+
### Math Equations
254280

255281
```python
256282

@@ -301,38 +327,41 @@ class Equations(Scene):
301327
```
302328
Here, we will look at very important concepts that will help when using Manim.
303329

304-
That looks long, but it's very simple. Here I have provided 2 ways of making equation and displaying it to the screen. If you remember, we installed some latex system requirements. We will use LaTex to make our equations look nice.
330+
That looks long, but it's very simple. Here I have provided 2 ways of making equation and displaying it to the screen. If you remember, we installed some latex system requirements. We will use LaTeX to make our equations look nice.
305331

306-
LaTex will take it's own tutorial. However, you don't need to know a lot of LaTex. I will introduce some rules that will help you write any math equation. Notice that equations are specified in TextMobjects.
332+
LaTeX will take it's own tutorial. However, you don't need to know a lot of LaTeX. I will introduce some rules that will help you write any math equation. Notice that equations are specified in `TexMobject`s instead of `TextMobject`s.
307333

308-
**LaTex:** When making an equation, the general rule is to put a *$* at the start and end of the text. For example:
309334
```python
310-
text = TextMobject("This is text") #Normal text
311-
equation = TextMobject("$X$") #This is an equation X
335+
text = TextMobject("This is text") # Normal text
336+
equation = TexMobject("2x+1=3") # Math equation
312337
```
313338

314-
Now for the fun part. In LaTex, you can represent symbols using a backslash and a keyword. THis include theta, alpha, summation, etc. In Manim, it is similar.
339+
If you want to put both regular text and math equations in one animation, you can use `$` to at both start and end of the math equations:
340+
```python
341+
equation_alternative = TextMobject("Equation: $2x+1=3$") # This is an equation
342+
```
315343

344+
Now for the fun part. In LaTeX, you can represent symbols using a backslash and a keyword. THis include theta, alpha, summation, integral, fractions, etc.
316345
```python
317-
theta = TextMobject("$\\theta$")
346+
theta = TexMobject("\\theta")
318347
```
319-
Notice, in Manim, you specify symbols by putting 2 backslash before the keyword.
348+
For the sake of escape sequences, we need to use two backslashes to represent `\` in Python
320349

321350
Finally, the I will introduce the syntax for adding subscripts and superscripts. Here is the syntax for superscripts.
322351

323352
```python
324-
superScript_equation = TextMobject("$r^{\\theta}$")
353+
superScript_equation = TexMobject("r^{\\theta}")
325354
```
326355

327-
The ^ symbol signifies superscript. We put the symbol theta as the superscript. Also, when specifying superscript the {} brackets are not displayed in the equation. They help group all the elements you want to add to the superscript.
356+
The `^` symbol signifies superscript. We put the symbol theta as the superscript. Also, when specifying superscript the {} brackets are not displayed in the equation. They help group all the elements you want to add to the superscript.
328357

329358
For subscripts, it is similar.
330359

331360
```python
332-
subScript_equation = TextMobject("$\\theta_{1}$")
361+
subScript_equation = TexMobject("\\theta_{1}")
333362
```
334363

335-
This is theta subscript 1. The _ signifies subscript. Like usual, the {} brackets aren't displayed in the equation. For more symbol options, go to the [resources](#Resources) section.
364+
This is theta subscript 1. The `_` signifies subscript. Like usual, the {} brackets aren't displayed in the equation. For more symbol options, go to the [resources](#Resources) section.
336365

337366
Now, we will look at a complex way of writing equations using VGroup. Let's look at what a VGroup is.
338367

@@ -346,7 +375,6 @@ Let's look at the example where we make a VGroup for the math equation.
346375
second_eq = ["$J(\\theta_{0}, \\theta_{1})$", "=", "$\\frac{1}{2m}$", "$\\sum\\limits_{i=1}^m$", "(", "$h_{\\theta}(x^{(i)})$", "-", "$y^{(i)}$", "$)^2$"]
347376
```
348377

349-
350378
**Click for results on YouTube:**
351379

352380
[![Youtube video link](https://img.youtube.com/vi/k9U4VjqTyPA/0.jpg)](https://www.youtube.com/watch?v=k9U4VjqTyPA)
@@ -505,8 +533,6 @@ class Images(Scene):
505533
img.shift(2 * UP) # Move the image
506534

507535
self.play(ShowCreation(img)) # Display the image
508-
509-
510536
```
511537

512538
Alternatively, you could load the image using OpenCV or PIL, and then display the image using Manim.
@@ -526,9 +552,9 @@ class Images(Scene):
526552
self.play(ShowCreation(imMob))
527553
```
528554

529-
## GO-TO-GUIDE!
555+
## GO TO GUIDE!
530556
[Click Here For the Guide](https://github.com/malhotra5/Manim-Guide)
531-
## Exploring-the-Repo
557+
## Exploring the Repo
532558

533559
### ManimLib
534560
#### Animations
@@ -538,9 +564,9 @@ class Images(Scene):
538564
#### Utils
539565

540566
### Media
541-
### Old_Projects
567+
### Old\_Projects
542568

543-
## Putting-it-together
569+
## Putting it together
544570
Manim is extremely powerful, and is capable of creating high quality graphics. You can make your animations using graphics and then overlay your voice over the video.
545571

546572
If you were able to follow this tutorial successfully, then Congrats! Hopefully you can profiently use Manim!
@@ -550,11 +576,12 @@ If you were able to follow this tutorial successfully, then Congrats! Hopefully
550576
* Manim Guide
551577
* [Manim Resource Guide](https://github.com/malhotra5/Manim-Guide)
552578

553-
## Further-Work
579+
## Further Work
554580
I am missing a lot of aspects behind this powerful library after reverse engineering manim. There are things such as 3D scenes that still need to be documented. But hopefully this guide will cater to your basic needs.
555581
## Acknowledgements
556-
* 3 Blue 1 Brown: The creator of this engine who uses it for creating cool math videos. Visit his YouTube channel and manin repo at
557-
* https://www.youtube.com/channel/UCYO_jab_esuFRV4b17AJtAw
558-
* https://github.com/3b1b/manim
559-
* Todd Zimmerman: Recently made a new documentation made in Python3.7. Visit it at
560-
* https://talkingphysics.wordpress.com/tag/manim/
582+
* 3Blue1Brown: The creator of this engine who uses it for creating cool math videos. Visit his [YouTube channel][1] and [manim repo][2] for more information
583+
* Todd Zimmerman: Recently made a new documentation made in Python3.7. Visit it [here][3]
584+
585+
[1]: https://www.youtube.com/channel/UCYO_jab_esuFRV4b17AJtAw
586+
[2]: https://github.com/3b1b/manim
587+
[3]: https://talkingphysics.wordpress.com/tag/manim/

0 commit comments

Comments
 (0)