Skip to content

armgit / manim

Public Imported from GitHub
0

A community-maintained Python framework for creating mathematical animations.

add new-readme

safinsingh62a31eed8125
diff --git a/README.md b/README.md
index b581f9bbf..df384ec07 100644
--- a/README.md
+++ b/README.md
@@ -8,76 +8,180 @@
Manim is an animation engine for explanatory math videos. It's used to create precise animations programmatically, as seen in the videos at [3Blue1Brown](https://www.3blue1brown.com/).
-### NOTE: This repository is maintained by the Manim Community, and is not associated with Grant Sanderson or 3Blue1Brown in any way (though we are definitely indebted to him for providing his work to the world). If you want to study how Grant make's his videos, head over to the main repository (3b1b/manim). This is a more frequently updated repository than the main one, and is recommended if you want to use Manim for your own projects.
+> NOTE: This repository is maintained by the Manim Community, and is not associated with Grant Sanderson or 3Blue1Brown in any way (though we are definitely indebted to him for providing his work to the world). If you want to study how Grant make's his videos, head over to the main repository (3b1b/manim). This is a more frequently updated repository than the main one, and is recommended if you want to use Manim for your own projects.
+
+## Table of Contents:
+- [Installation](#installation)
+ * [Windows](#windows)
+ + [Cairo Installation](#cairo-installation)
+ + [FFmpeg Installation](#ffmpeg-installation)
+ + [SoX Installation](#sox-installation)
+ + [LaTeX Installation](#latex-installation)
+ * [Linux](#linux)
+ + [Cairo Installation](#cairo-installation-1)
+ + [FFmpeg Installation](#ffmpeg-installation-1)
+ + [SoX Installation](#sox-installation-1)
+ + [LaTeX Installation](#latex-installation-1)
+ + [Additional Installation Steps](#additional-installation-steps)
+ * [Mac](#mac)
+ + [Cairo Installation](#cairo-installation-2)
+ + [FFmpeg Installation](#ffmpeg-installation-2)
+ + [SoX Installation](#sox-installation-2)
+ + [LaTeX Installation](#latex-installation-2)
+ * [Installing Manim-Community itself](#installing-manim-community-itself)
+- [Usage](#usage)
+- [Documentation](#documentation)
+- [Help with Manim](#help-with-manim)
+- [Contributing](#contributing)
## Installation
-Manim runs on Python 3.7. You can install it from PyPI via pip:
-```sh
-pip3 install manimlib
-```
+### Windows
-System requirements are [cairo](https://www.cairographics.org), [ffmpeg](https://www.ffmpeg.org), [sox](http://sox.sourceforge.net), [latex](https://www.latex-project.org) (optional, if you want to use LaTeX).
+Before installing `manim-community`, there are some additional dependencies that you must have installed:
+ - Cairo
+ - FFmpeg
+ - Sox (optional, for sound)
+ - LaTeX (optional, for LaTeX)
-You can now use it via the `manim` command. For example:
+#### Cairo Installation
+1. Visit the [Download Page](https://www.lfd.uci.edu/~gohlke/pythonlibs/#pycairo)
+2. Select the download that corresponds to your PC's architechture and Python Version
-```sh
-manim my_project.py MyScene
-```
+<img style="width: 20vw;" src="./readme-assets/windows_cairo.png" />
+<br><br>
-For more options, take a look at the [Using manim](#using-manim) sections further below.
+> cp38 corresponds to Python 3.8, cp37 corresponds to Python 3.7, etc
+> win_amd64 corresponds to 64-bit machines, win32 corresponds to 32-bit machines
-### Directly
+3. Open up your command prompt by hitting the Win key and typing `cmd`
+4. Enter the directory where you install cairo by typing `cd C:\path\to\cairo` with the path being where you downloaded the `.whl` file
+5. Finally, run `pip3 install (cairo-file).whl`, where the file the appropriate name of the `.whl` file.
-If you want to hack on manimlib itself, clone this repository and in that directory execute:
+#### FFmpeg Installation
+1. To install `ffmpeg` and add it to your PATH, install [Chocolatey](https://chocolatey.org/) and run `choco install ffmpeg`
+2. You can check you did it right by running `refreshenv` to update your environment variable and running `ffmpeg`
-```sh
-# Install python requirements
-python3 -m pip install -r requirements.txt
+#### SoX Installation
+1. Go to the SoX [SourceForge](https://sourceforge.net/projects/sox/files/sox/) page
+2. Select the newest version, and download the `.exe` file
+
+<img style="width: 20vw;" src="./readme-assets/windows_sox.png" />
+<br><br>
+
+3. Add SoX to your PATH
+ - Find the directory where SoX is installed. By default, this is probably `C:\Program Files (x86)\sox-(version_number)` or `C:\Program Files\sox-(version_number)`
+ - Open a command prompt window by hitting the Win key and typing `cmd`
+ - Run this command to update your PATH: `setx PATH %PATH%;C:\Program Files (x86)\sox-(version_number)`
+ - Check you did it right by running `refreshenv` to update your environment variable and running `sox`
+
+#### LaTeX Installation
+1. Download the MiKTex installer from its [Download Page](https://miktex.org/download)
+2. You can check you did it right by running `refreshenv` to update your environment variable and running `latex`
+
+<img style="width: 20vw;" src="./readme-assets/windows_miktex.png" />
+<br><br>
+
+### Linux
+
+Before installing `manim-community`, there are some additional dependencies that you must have installed:
+ - Cairo
+ - FFmpeg
+ - Sox (optional, for sound)
+ - LaTeX (optional, for LaTeX)
+
+#### Cairo Installation
+1. Install the `libcairo2-dev` package with your package manager: `sudo apt-get install libcairo2-dev`
+
+#### FFmpeg Installation
+1. Install the `ffmpeg` package with your package manager: `sudo apt-get install ffmpeg`
+2. You can check you did it right by running `ffmpeg -version`
+
+#### SoX Installation
+1. Install the `sox` package with your package manager: `sudo apt-get install sox`
+2. You can check you did it right by running `sox`
+
+#### LaTeX Installation
+1. Install `texlive` with your package manager by running the following commands:
+```
+sudo apt install texlive texlive-latex-extra texlive-fonts-extra texlive-latex-recommended texlive-science texlive-fonts-extra tipa
+```
+> Note: this installation may take up a lot of space. The developers are working on providing a simpler, lighter LaTeX package for you to install
+2. You can check you did it right by running `latex`
+
+#### Additional Installation Steps
+- You must install additional codecs to play MP4 files:
+```
+sudo apt install libdvdnav4 libdvd-pkg gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly libdvd-pkg
+sudo apt install ubuntu-restricted-extras
+```
+
+### Mac
-# Try it out
-python3 ./manim.py example_scenes.py SquareToCircle -pl
+Before installing `manim-community`, there are some additional dependencies that you must have installed:
+ - Cairo
+ - FFmpeg
+ - Sox (optional, for sound)
+ - LaTeX (optional, for LaTeX)
+
+#### Cairo Installation
+1. Press Command+Space and type Terminal and press enter/return key
+2. Run the following in the Terminal app:
+```
+ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" < /dev/null 2> /dev/null
```
+and press your enter/return key.
+> If the screen prompts you to enter a password, please enter your Mac's user password to continue. When you type the password, it won't be displayed on screen, but the system would accept it. So just type your password and press ENTER/RETURN key. Then wait for the command to finish.
-### Directly (Windows)
-1. [Install FFmpeg](https://www.wikihow.com/Install-FFmpeg-on-Windows).
-2. [Install Cairo](https://www.lfd.uci.edu/~gohlke/pythonlibs/#pycairo). For most users, ``pycairo‑1.18.0‑cp37‑cp37m‑win32.whl`` will do fine.
- ```sh
- pip3 install C:\path\to\wheel\pycairo‑1.18.0‑cp37‑cp37m‑win32.whl
- ```
-3. Install a LaTeX distribution. [MiKTeX](https://miktex.org/download) is recommended.
+3. Run `brew install cairo`
-4. [Install SoX](https://sourceforge.net/projects/sox/files/sox/).
+#### FFmpeg Installation
+1. Refer to the section on Cairo installation to see how to install `brew`
+2. Run `brew install ffmpeg`
+3. You can check you did it right by running `ffmpeg -version`
-5. Install the remaining Python packages. Make sure that ``pycairo==1.17.1`` is changed to ``pycairo==1.18.0`` in requirements.txt.
- ```sh
- git clone https://github.com/3b1b/manim.git
- cd manim
- pip3 install -r requirements.txt
- python3 manim.py example_scenes.py SquareToCircle -pl
- ```
+#### SoX Installation
+1. Refer to the section on Cairo installation to see how to install `brew`
+2. Run `brew install sox`
+3. You can check you did it right by running `sox`
+#### LaTeX Installation
+1. Refer to the section on Cairo installation to see how to install `brew`
+2. Run `brew cask install mactex`
+2. You can check you did it right by running `latex`
-## Anaconda Install
+### Installing Manim-Community itself
-* Install sox and latex as above.
-* Create a conda environment using `conda env create -f environment.yml`
-* **WINDOWS ONLY** Install `pyreadline` via `pip install pyreadline`.
+Manim runs on Python 3.7+. If you'd like to just use the library, you can install it from PyPI via pip:
+```sh
+pip3 install manimlib
+```
+
+However, if you'd like to contribute to and/or help develop `manim-community`, you can clone this branch to your local device. To do this, run the following command (with `git` installed):
-### Using `virtualenv` and `virtualenvwrapper`
-After installing `virtualenv` and `virtualenvwrapper`
```sh
-git clone https://github.com/3b1b/manim.git
-mkvirtualenv -a manim -r requirements.txt manim
-python3 -m manim example_scenes.py SquareToCircle -pl
+git clone https://github.com/ManimCommunity/manim.git
+python3 -m pip install -r requirements.txt
```
-## Using manim
-Try running the following:
+## Usage
+
+To run your first example Scene, you can run the following commands:
+For users:
+1. Download the `example_scenes.py` file from [GitHub](https://github.com/ManimCommunity/manim/blob/master/example_scenes.py)
+2. Run the following command:
+```sh
+manim example_scenes.py SquareToCircle -pl
+```
+1. Run the following command:
+For developers:
```sh
-python3 -m manim example_scenes.py SquareToCircle -pl
+python3 manim.py example_scenes.py SquareToCircle -pl
```
+
+![](./readme-assets/command.png)
+
The `-p` flag in the command above is for previewing, meaning the video file will automatically open when it is done rendering. The `-l` flag is for a faster rendering at a lower quality.
Some other useful flags include:
@@ -85,25 +189,13 @@ Some other useful flags include:
* `-n <number>` to skip ahead to the `n`'th animation of a scene.
* `-f` to show the file in finder (for OSX).
-Set `MEDIA_DIR` environment variable to specify where the image and animation files will be written.
+You can also set `MEDIA_DIR` environment variable to specify where the image and animation files will be written.
-Look through the `old_projects` folder to see the code for previous 3b1b videos. Note, however, that developments are often made to the library without considering backwards compatibility with those old projects. To run an old project with a guarantee that it will work, you will have to go back to the commit which completed that project.
-
-While developing a scene, the `-sp` flags are helpful to just see what things look like at the end without having to generate the full animation. It can also be helpful to use the `-n` flag to skip over some number of animations.
-
-### Documentation
+## Documentation
Documentation is in progress at [eulertour.com/docs](https://www.eulertour.com/docs/).
-### Walkthrough
-Todd Zimmerman put together a [tutorial](https://talkingphysics.wordpress.com/2019/01/08/getting-started-animating-with-manim-and-python-3-7/) on getting started with manim, which has been updated to run on Python 3.7.
-
-## Help With Usage and Installation
+## Help with Manim
The issues board is reserved for bugs, and future features planned for Manim. If you need help installing or using Manim, please take a look at [the Reddit Community](https://www.reddit.com/r/manim) or the [Discord Community](https://discord.gg/mMRrZQW)
## Contributing
-Is always welcome. In particular, there is a dire need for tests and documentation.
-
-## License
-All files in the directory `from_3b1b`, which by and large generate the visuals for 3b1b videos, are copyright 3Blue1Brown.
-
-The general purpose animation code found in the remainder of the repository, on the other hand, is under the MIT license.
+Is always welcome. In particular, there is a dire need for tests and documentation.
\ No newline at end of file
diff --git a/readme-assets/command.png b/readme-assets/command.png
new file mode 100644
index 000000000..1fc7004dd
Binary files /dev/null and b/readme-assets/command.png differ
diff --git a/readme-assets/windows_cairo.png b/readme-assets/windows_cairo.png
new file mode 100644
index 000000000..e9691edda
Binary files /dev/null and b/readme-assets/windows_cairo.png differ
diff --git a/readme-assets/windows_miktex.png b/readme-assets/windows_miktex.png
new file mode 100644
index 000000000..9189428a1
Binary files /dev/null and b/readme-assets/windows_miktex.png differ
diff --git a/readme-assets/windows_sox.png b/readme-assets/windows_sox.png
new file mode 100644
index 000000000..27fae80d3
Binary files /dev/null and b/readme-assets/windows_sox.png differ