From 957133e4d0442f3c6b8b5d9b439da8d38113a1b4 Mon Sep 17 00:00:00 2001 From: Splines Date: Sun, 19 Jan 2025 13:59:27 +0100 Subject: [PATCH 1/7] Add detailed installation guide for Manim & its dependencies --- src/walkthrough/manim-installation.md | 102 ++++++++++++++++++++++++-- 1 file changed, 95 insertions(+), 7 deletions(-) diff --git a/src/walkthrough/manim-installation.md b/src/walkthrough/manim-installation.md index dde0439e..5041b0f1 100644 --- a/src/walkthrough/manim-installation.md +++ b/src/walkthrough/manim-installation.md @@ -20,16 +20,104 @@ > **Manim Notebook only works with ManimGL by 3Blue1Brown,
NOT with the community edition of Manim (Manim CE)**. -If you haven't already installed ManimGL, follow the [**Manim installation guide**](https://3b1b.github.io/manim/getting_started/installation.html). This will be the most difficult part of all the steps here and there are quite a few dependencies to install. But don't despair; with a bit of patience and StackOverflow you will get there. +Unfortunately, installing 3Blue1Brown's Manim is not a trivial task due to its dependencies. Luckily, you have to do this only once. Get yourself some quiet time, and follow the steps below. -We recommend to install Manim by cloning the GitHub repo and using +- First, note that there is a [**Manim installation guide**](https://3b1b.github.io/manim/getting_started/installation.html) available. However, it mainly just tells you _what_ to install and not _how to_. +- In the GitHub Actions pipeline for our Manim Notebook extension, we succeeded to automatically install ManimGL on the latest macOS, Ubuntu, and Windows. So take inspiration from there, i.e. this [`tests.yml`](https://github.com/Manim-Notebook/manim-notebook/blob/main/.github/workflows/tests.yml) workflow, as well as [this `manimInstaller.ts`](https://github.com/Manim-Notebook/manim-notebook/blob/main/tests/utils/manimInstaller.ts). It might be worth it to search for keywords there if you encounter errors during installation. + +## πŸ’¨ Dependency installation guidance & quirks + +**Python `3.13` (any OS)** + +```py +# https://github.com/jiaaro/pydub/issues/815 +pip install audioop-lts +``` + +**Linux (e.g. Ubuntu)** + +You probably need the OpenGL Mesa Utils. + +```py +# Install OpenGL Mesa Utils +sudo add-apt-repository ppa:kisak/kisak-mesa +sudo apt-get update +sudo apt-get install mesa-utils -y + +# Install PyOpenGL +pip install PyOpenGL + +# Test your OpenGL version via: +xvfb-run -a glxinfo | grep "OpenGL version" + +# Install Pango +sudo apt-get install libpango1.0-dev -y +``` + +Only apply those if you encounter the respective errors: + +```py +# Work around 'NoneType' object has no attribute 'glGetError' +# https://github.com/MPI-IS/mesh/issues/23#issuecomment-607784234 +sudo apt-get install python3-opengl + +# Install copy-paste mechanism to avoid ClipboardUnavailable errors +# (python pyperclip makes use of xclip on Linux) +sudo apt-get install xclip -y +``` + + +**Windows** + +Windows itself only comes with OpenGL 1.1, which is not enough for ManimGL. We found that the easiest way to do so is via [this amazing repo](https://github.com/pal1000/mesa-dist-win), which serves precompiled Mesa3D drivers for Windows. In a PowerShell, run: + +```powershell +# Install OpenGL pre-built Mesa binaries from mesa-dist-win +Invoke-WebRequest -Uri https://github.com/pal1000/mesa-dist-win/releases/download/24.3.2/mesa3d-24.3.2-release-mingw.7z -OutFile mesa3d.7z + +# Extract (on purpose no space between -o and mesa3d) +7z x mesa3d.7z -omesa3d + +# Install system-wide (option 1: core desktop OpenGL drivers) +.\mesa3d\systemwidedeploy.cmd 1 +``` + +Test your OpenGL version: + +```bash +# Download wglinfo (analogous to glxinfo) +curl -L -O https://github.com/gkv311/wglinfo/releases/latest/download/wglinfo64.exe +chmod +x wglinfo64.exe +./wglinfo64.exe | grep "OpenGL version" +``` + +**macOS** + +Lucky you, macOS already came with everything that ManimGL needed out of the box in our tests. We don't know a way to retrieve the OpenGL version on macOS, if you happen to know one, please let us know [in a new issue](https://github.com/Manim-Notebook/manim-notebook/issues). + +## πŸ’¨ ManimGL installation + +Finally, installing ManimGL should be as easy as installing any other Python package. However, we recommend installing it in an isolated environment to avoid conflicts with other packages. You can do so by creating a new virtual environment and installing ManimGL there. ```bash -git clone https://github.com/3b1b/manim.git -cd manim -pip install -e . +# Clone Manim anywhere you like. +# Here, we assume you want to store it in `~/dev/manim/` +git clone https://github.com/3b1b/manim.git ~/dev/manim/ + +# Change into the directory where you want to use Manim, +# e.g. `~/dev/manim-videos/` +# and create a new virtual environment there, +# where you will install Manim and its Python dependencies. +cd ~/dev/manim-videos/ +python3 -m venv manim-venv +. manim-venv/bin/activate # source the activate script + +# Now `pip --version` should show its version and a path in your `manim-venv/` +# directory. That is, you are now in the virtual environment (venv) +# Finally, install ManimGL and its Python dependencies into that venv. +pip install -e ~/dev/manim/ ``` -This way, you can easily update Manim by pulling the latest commits from the repo (`git pull`) and don't have to wait for a new release. +Note that via this technique, the `manimgl` command is only available in the virtual environment (which is actually a good thing due to the isolation). If you want to upgrade Manim, it's as easy as pulling the latest commit from the repo: `git pull` (inside the `~/dev/manim/` folder). You might have to re-run `pip install -e ~/dev/manim/` afterwards (inside the virtual environment (!)). Note that the VSCode Python extension by Microsoft will also detect that you use a virtual environment: upon opening a new terminal, it will automatically source the `activate` script for you. -Check your Manim version by running `manimgl --version` or just click on the button on the left. +Finally, check your Manim version by running `manimgl --version`. If this shows the latest version, you have successfully installed ManimGL, congratulations! πŸŽ‰ This was the most difficult part, from now on it should be a breeze to use Manim. From fb95a3153079a7465c68622cd6b4f724cc6912c8 Mon Sep 17 00:00:00 2001 From: Splines Date: Sun, 19 Jan 2025 14:03:25 +0100 Subject: [PATCH 2/7] Make explicit that we don't install ffmpeg or latex --- src/walkthrough/manim-installation.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src/walkthrough/manim-installation.md b/src/walkthrough/manim-installation.md index 5041b0f1..5891c880 100644 --- a/src/walkthrough/manim-installation.md +++ b/src/walkthrough/manim-installation.md @@ -27,6 +27,9 @@ Unfortunately, installing 3Blue1Brown's Manim is not a trivial task due to its d ## πŸ’¨ Dependency installation guidance & quirks +- Note that we don't install ffmpeg in these steps. ManimGL will work without it as well if you just want to preview animations (it will just show a warning, that's it). To finally render your animations to an `.mp4` file, you will need ffmpeg, though. +- We also don't install LaTeX in these steps. If you want to use LaTeX in your animations, you will need to install LaTeX separately. + **Python `3.13` (any OS)** ```py @@ -54,7 +57,7 @@ xvfb-run -a glxinfo | grep "OpenGL version" sudo apt-get install libpango1.0-dev -y ``` -Only apply those if you encounter the respective errors: +Only apply those fixes in case you encounter the respective errors: ```py # Work around 'NoneType' object has no attribute 'glGetError' From 20e442c83a40b39fd6ecefa2da4dc039d7b50f1e Mon Sep 17 00:00:00 2001 From: Splines Date: Sun, 19 Jan 2025 14:14:17 +0100 Subject: [PATCH 3/7] Link to dev guide in the contributing file --- CONTRIBUTING.md | 20 +------------------- 1 file changed, 1 insertion(+), 19 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 867c19fb..4585c7db 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,21 +1,3 @@ # Contributing -1. Fork the repository and clone this fork -2. Create a new branch: `git checkout -b feature/your-feature-name` -3. Make your changes -4. Commit your changes: `git commit -m "Add your commit message"` -5. Push to the branch on your fork: `git push origin feature/your-feature-name` -6. Open a Pull Request - -## Style Guidelines - -Right now, the goal is to replicate Grant's sublime workflow in VSCode. Thus, we currently aim to keep things minimal and focused. - -- Most new functionality should be added to `src/extensions.ts` -- Use clear and descriptive variable/function names. -- As much as possible, minimize editing global state (e.g., the clipboard). This is already done a lot inside the manim πŸ™ˆ - -## Additional Guidelines - -- Before starting work on a new feature, please open an issue to introduce it and allow discussion -- There is currently no documentation. Keep your code clean and describe the functionality in the github issue as much as possible. +See the [Developing Guide](https://github.com/Manim-Notebook/manim-notebook/wiki/Developing) in our Wiki. From 9c050661370ca781ce9b0c35fcd0acd88b43be3d Mon Sep 17 00:00:00 2001 From: Splines Date: Sun, 19 Jan 2025 14:14:56 +0100 Subject: [PATCH 4/7] Update year of license file --- LICENSE.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE.txt b/LICENSE.txt index 3818ebaa..db22ce96 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2024 Manim Notebook Contributors +Copyright (c) 2024-2025 Manim Notebook Contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal From bc3c9d83cee0330e20721056494fd709d4cbdf9d Mon Sep 17 00:00:00 2001 From: Splines Date: Sun, 19 Jan 2025 14:16:14 +0100 Subject: [PATCH 5/7] Link to releases section in Changelog --- CHANGELOG.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c1d14b47..925f9635 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1 @@ -# Change Log - -All notable changes to the "Manim Notebook" extension will be documented in this file. - -Check [Keep a Changelog](http://keepachangelog.com/) for recommendations on how to structure this file. - -## [Unreleased] - -- Initial release \ No newline at end of file +Our [Releases section](https://github.com/Manim-Notebook/manim-notebook/releases) documents all changes made to the Manim Notebook extension. This includes new features, bug fixes, and other improvements. From c9d95802ef379764d2daa89d799fd7eb058db8d8 Mon Sep 17 00:00:00 2001 From: Splines Date: Sun, 19 Jan 2025 14:17:01 +0100 Subject: [PATCH 6/7] Add header to changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 925f9635..8b702f79 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1 +1,3 @@ +# Changelog + Our [Releases section](https://github.com/Manim-Notebook/manim-notebook/releases) documents all changes made to the Manim Notebook extension. This includes new features, bug fixes, and other improvements. From bd560f5d8a6df97132d7daa8eb667fef17a45312 Mon Sep 17 00:00:00 2001 From: Splines Date: Sun, 19 Jan 2025 14:20:22 +0100 Subject: [PATCH 7/7] Update mont/year of readme note --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d9329be6..fddff02b 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ > [!note] -> December 2024: Hey thereπŸ‘‹ We are currently working to ship the first release of Manim Notebook. The version already available on the VSCode Marketplace is outdated. If you are interested in the current state of the extension, just clone this repo and follow the [Developing guide](https://github.com/Manim-Notebook/manim-notebook/wiki/Developing). +> December 2024 / January 2025: Hey thereπŸ‘‹ We are currently working to ship the first release of Manim Notebook. The version already available on the VSCode Marketplace is outdated. If you are interested in the current state of the extension, just clone this repo and follow the [Developing guide](https://github.com/Manim-Notebook/manim-notebook/wiki/Developing). > [!warning] > This VSCode extension is specifically for [3b1b's original manim library](https://github.com/3b1b/manim)