mirror of
https://github.com/ManimCommunity/manim.git
synced 2026-06-22 10:01:47 +00:00
bd844f46d8* remove unused constants * remove deprecated --use_opengl_renderer flag * remove unnecessary workaround with class initialization * add OpenGLMobject.name to get rid of one renderer check * add VMobject.n_points_per_curve property to get rid of more renderer checks * replace renderer string checks with enum check * added mobject.utils module with renderer-dependent class getters * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * ensure that capitalization of passed renderer type is irrelevant * remove unused entries from mobject.utils.__all__ * fixed isort ignore in manim.__init__ * fixed lower-case casting of passed renderer * fixed doctests * more documentation + doctests for mobject.utils * removed incorrect paragraph about ConverToOpenGL metaclass * added docstring for RendererType enum * renderer compatibility section in plugin dev documentation * added mobject.utils to reference manual * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Remove actual doctest (it ran the compatibility code) Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Naveen M K <naveen521kk@gmail.com>
154 lines
4.7 KiB
ReStructuredText
154 lines
4.7 KiB
ReStructuredText
.. _plugins:
|
|
|
|
=======
|
|
Plugins
|
|
=======
|
|
|
|
Plugins are features that extend Manim's core functionality. Since Manim is
|
|
extensible and not everything belongs in its core, we'll go over how to
|
|
install, use, and create your own plugins.
|
|
|
|
.. note::
|
|
|
|
The standard naming convention for plugins is to prefix the plugin with
|
|
``manim-``. This makes them easy for users to find on package
|
|
repositories such as PyPI.
|
|
|
|
.. WARNING::
|
|
|
|
The plugin feature is new and under active development. Expect updates
|
|
for the best practices on installing, using, and creating plugins; as
|
|
well as new subcommands/flags for ``manim plugins``
|
|
|
|
.. tip::
|
|
|
|
See https://plugins.manim.community/ for the list of plugins available.
|
|
|
|
Installing Plugins
|
|
******************
|
|
Plugins can be easily installed via the ``pip``
|
|
command:
|
|
|
|
.. code-block:: bash
|
|
|
|
pip install manim-*
|
|
|
|
After installing a plugin, you may use the ``manim plugins`` command to list
|
|
your available plugins, see the following help output:
|
|
|
|
.. code-block:: bash
|
|
|
|
manim plugins -h
|
|
Usage: manim plugins [OPTIONS]
|
|
|
|
Manages Manim plugins.
|
|
|
|
Options:
|
|
-l, --list List available plugins
|
|
-h, --help Show this message and exit.
|
|
|
|
Made with <3 by Manim Community developers.
|
|
|
|
You can list plugins as such:
|
|
|
|
.. code-block:: bash
|
|
|
|
manim plugins -l
|
|
Plugins:
|
|
• manim_plugintemplate
|
|
|
|
Using Plugins in Projects
|
|
*************************
|
|
For enabling a plugin ``manim.cfg`` or command line parameters should be used.
|
|
|
|
.. important::
|
|
|
|
The plugins should be module name of the plugin and not PyPi name.
|
|
|
|
Enabling plugins through ``manim.cfg``
|
|
|
|
.. code-block:: ini
|
|
|
|
[CLI]
|
|
plugins = manim_rubikscube
|
|
|
|
For specifying multiple plugins, comma-separated values must be used.
|
|
|
|
.. code-block:: ini
|
|
|
|
[CLI]
|
|
plugins = manim_rubikscube, manim_plugintemplate
|
|
|
|
Creating Plugins
|
|
****************
|
|
|
|
Plugins are intended to extend Manim's core functionality. If you aren't sure
|
|
whether a feature should be included in Manim's core, feel free to ask over
|
|
on the `Discord server <https://www.manim.community/discord/>`_. Visit
|
|
`manim-plugintemplate <https://pypi.org/project/manim-plugintemplate/>`_
|
|
on PyPI.org which serves as an in-depth tutorial for creating plugins.
|
|
|
|
.. code-block:: bash
|
|
|
|
pip install manim-plugintemplate
|
|
|
|
The only requirement of manim plugins is that they specify an entry point
|
|
with the group, ``"manim.plugins"``. This allows Manim to discover plugins
|
|
available in the user's environment. Everything regarding the plugin's
|
|
directory structure, build system, and naming are completely up to your
|
|
discretion as an author. The aforementioned template plugin is only a model
|
|
using Poetry since this is the build system Manim uses. The plugin's `entry
|
|
point <https://packaging.python.org/specifications/entry-points/>`_ can be
|
|
specified in poetry as:
|
|
|
|
.. code-block:: toml
|
|
|
|
[tool.poetry.plugins."manim.plugins"]
|
|
"name" = "object_reference"
|
|
|
|
Here ``name`` is the name of the module of the plugin.
|
|
|
|
Here ``object_reference`` can point to either a function in a module or a module
|
|
itself. For example,
|
|
|
|
.. code-block:: toml
|
|
|
|
[tool.poetry.plugins."manim.plugins"]
|
|
"manim_plugintemplate" = "manim_plugintemplate"
|
|
|
|
Here a module is used as ``object_reference``, and when this plugin is enabled,
|
|
Manim will look for ``__all__`` keyword defined in ``manim_plugintemplate`` and
|
|
everything as a global variable one by one.
|
|
|
|
If ``object_reference`` is a function, Manim calls the function and expects the
|
|
function to return a list of modules or functions that need to be defined globally.
|
|
|
|
For example,
|
|
|
|
.. code-block:: toml
|
|
|
|
[tool.poetry.plugins."manim.plugins"]
|
|
"manim_plugintemplate" = "manim_awesomeplugin.imports:setup_things"
|
|
|
|
Here, Manim will call the function ``setup_things`` defined in
|
|
``manim_awesomeplugin.imports`` and calls that. It returns a list of function or
|
|
modules which will be imported globally.
|
|
|
|
A note on Renderer Compatibility
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Depending on which renderer is currently active, custom mobjects
|
|
created in your plugin might want to behave differently as the
|
|
corresponding mobject base classes are (unfortunately) not fully
|
|
compatible.
|
|
|
|
The currently active renderer can be queried by checking the value
|
|
of ``manim.config.renderer``. All possible renderer types are given
|
|
by :class:`.constants.RendererType`. The module :mod:`.manim.mobject.utils`
|
|
contains utility functions that return the base class for the currently
|
|
active renderer.
|
|
|
|
A simple form of renderer compatibility (by hot-swapping the class
|
|
inheritance chain) for Mobjects directly inheriting from
|
|
:class:`.Mobject` or :class:`.VMobject` can be achieved by using the
|
|
:class:`.mobject.opengl.opengl_compatibility.ConvertToOpenGL` metaclass.
|