Skip to content

armgit / manim

Public Imported from GitHub
0

A community-maintained Python framework for creating mathematical animations.

add type annotations and docstrings for opengl_renderer.py (#4537)

Arnaudbbdcda1ff56d
diff --git a/manim/renderer/opengl_renderer.py b/manim/renderer/opengl_renderer.py
index 7284504cd..9c1c577c5 100644
--- a/manim/renderer/opengl_renderer.py
+++ b/manim/renderer/opengl_renderer.py
@@ -3,28 +3,31 @@ from __future__ import annotations
import contextlib
import itertools as it
import time
+import typing
from functools import cached_property
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Self
import moderngl
import numpy as np
+from moderngl import Framebuffer
from PIL import Image
+from typing_extensions import override
from manim import config, logger
from manim.mobject.opengl.opengl_mobject import (
OpenGLMobject,
OpenGLPoint,
- _AnimationBuilder,
)
from manim.mobject.opengl.opengl_vectorized_mobject import OpenGLVMobject
+from manim.typing import MatrixMN, Point3D
from manim.utils.caching import handle_caching_play
from manim.utils.color import color_to_rgba
from manim.utils.exceptions import EndSceneEarlyException
+from manim.utils.paths import straight_path
from ..constants import *
from ..scene.scene_file_writer import SceneFileWriter
from ..utils import opengl
-from ..utils.config_ops import _Data
from ..utils.simple_functions import clip
from ..utils.space_ops import (
angle_of_vector,
@@ -40,34 +43,108 @@ from .vectorized_mobject_rendering import (
)
if TYPE_CHECKING:
+ from collections.abc import Iterable
from typing import Self
from manim.animation.animation import Animation
- from manim.mobject.mobject import Mobject
+ from manim.mobject.mobject import Mobject, _AnimationBuilder
from manim.scene.scene import Scene
- from manim.typing import Point3D
+ from manim.typing import (
+ FloatRGBA,
+ PathFuncType,
+ Point3DLike,
+ RGBAPixelArray,
+ Vector3DLike,
+ )
+ from manim.utils.color.core import ParsableManimColor
+ from manim.utils.opengl import FlattenedMatrix4x4
+
+ from .opengl_renderer_window import Window
__all__ = ["OpenGLCamera", "OpenGLRenderer"]
class OpenGLCamera(OpenGLMobject):
- euler_angles = _Data()
+ """
+ An OpenGL-based camera for 3D scene rendering.
+
+
+ Attributes
+ ----------
+ frame_shape : tuple[float, float]
+ The width and height of the camera frame.
+ center_point : np.ndarray
+ The center point of the camera in 3D space.
+ euler_angles : np.ndarray
+ The Euler angles (theta, phi, gamma) representing the camera's orientation.
+ focal_distance : float
+ The focal distance of the camera.
+ light_source_position : np.ndarray
+ The position of the light source in 3D space.
+ orthographic : bool
+ Whether the camera uses orthographic projection instead of perspective.
+ minimum_polar_angle : float
+ The minimum polar angle for camera rotation.
+ maximum_polar_angle : float
+ The maximum polar angle for camera rotation.
+ inverse_rotation_matrix : np.ndarray
+ The inverse rotation matrix of the camera.
+ """
def __init__(
self,
- frame_shape=None,
- center_point=None,
+ frame_shape: tuple[float, float] | None = None,
+ center_point: Point3DLike | None = None,
# Theta, phi, gamma
- euler_angles=[0, 0, 0],
- focal_distance=2,
- light_source_position=[-10, 10, 10],
- orthographic=False,
- minimum_polar_angle=-PI / 2,
- maximum_polar_angle=PI / 2,
- model_matrix=None,
- **kwargs,
- ):
+ euler_angles: Point3DLike | None = None,
+ focal_distance: float = 2.0,
+ light_source_position: Point3DLike | None = None,
+ orthographic: bool = False,
+ minimum_polar_angle: float = -PI / 2,
+ maximum_polar_angle: float = PI / 2,
+ model_matrix: MatrixMN | None = None,
+ **kwargs: Any,
+ ) -> None:
+ """
+ Initializes an OpenGLCamera instance.
+
+ Parameters
+ ----------
+ frame_shape : tuple[float, float], optional
+ The width and height of the camera frame. If not provided, defaults to
+ the global manim config values `frame_width` and `frame_height`.
+ center_point : Point3DLike, optional
+ The center point of the camera in 3D space.
+ If not provided, defaults to the origin (0, 0, 0).
+ euler_angles : Point3DLike, optional
+ The Euler angles (theta, phi, gamma) representing the camera's orientation.
+ If not provided, defaults to (0, 0, 0) (i.e., no rotation).
+ focal_distance : float, optional
+ The focal distance of the camera. Default is 2.0.
+ light_source_position : Point3DLike, optional
+ The position of the light source in 3D space.
+ If not provided, defaults to (-10, 10, 10).
+ orthographic : bool, optional
+ Whether the camera uses orthographic projection instead of perspective.
+ Default is False (perspective).
+ minimum_polar_angle : float, optional
+ The minimum polar angle in radian for camera rotation. Default is -π/2,
+ i.e. no restriction.
+ maximum_polar_angle : float, optional
+ The maximum polar angle in radian for camera rotation. Default is π/2,
+ i.e. no restriction.
+ model_matrix : MatrixMN, optional
+ The initial model matrix [1]_ for the camera. If not provided,
+ defaults to a translation matrix that positions the camera at (0, 0, 11).
+ **kwargs : Any
+ Additional keyword arguments passed to the OpenGLMobject constructor.
+
+ References
+ ----------
+ .. [1] Wikipedia, "Camera matrix",
+ https://en.wikipedia.org/wiki/Camera_matrix
+ """
self.use_z_index = True
self.frame_rate = 60
self.orthographic = orthographic
@@ -92,51 +169,56 @@ class OpenGLCamera(OpenGLMobject):
if center_point is None:
self.center_point = ORIGIN
else:
- self.center_point = center_point
+ self.center_point = np.asarray(center_point, dtype=float)
if model_matrix is None:
model_matrix = opengl.translation_matrix(0, 0, 11)
self.focal_distance = focal_distance
- if light_source_position is None:
- self.light_source_position = [-10, 10, 10]
- else:
- self.light_source_position = light_source_position
+ self.light_source_position = np.asarray(
+ light_source_position or [-10, 10, 10], dtype=float
+ )
+
self.light_source = OpenGLPoint(self.light_source_position)
self.default_model_matrix = model_matrix
super().__init__(model_matrix=model_matrix, should_render=False, **kwargs)
- if euler_angles is None:
- euler_angles = [0, 0, 0]
- euler_angles = np.array(euler_angles, dtype=float)
+ euler_angles = np.asarray(euler_angles or [0, 0, 0], dtype=float)
- self.euler_angles = euler_angles
+ self.euler_angles: Point3D = euler_angles
self.refresh_rotation_matrix()
def get_position(self) -> Point3D:
+ """Retrieve the camera's position in 3D space."""
return self.model_matrix[:, 3][:3]
- def set_position(self, position):
+ def set_position(self, position: Point3D) -> Self:
+ """Set the camera's position in 3D space."""
self.model_matrix[:, 3][:3] = position
return self
@cached_property
- def formatted_view_matrix(self):
- return opengl.matrix_to_shader_input(np.linalg.inv(self.model_matrix))
+ def formatted_view_matrix(self) -> FlattenedMatrix4x4:
+ """The formatted view matrix for shader input."""
+ return opengl.matrix_to_shader_input(self.unformatted_view_matrix)
@cached_property
- def unformatted_view_matrix(self):
- return np.linalg.inv(self.model_matrix)
+ def unformatted_view_matrix(self) -> MatrixMN:
+ return typing.cast(MatrixMN, np.linalg.inv(self.model_matrix))
- def init_points(self):
+ def init_points(self) -> None:
+ """Initialize the camera's points based on frame shape and center point."""
self.set_points([ORIGIN, LEFT, RIGHT, DOWN, UP])
self.set_width(self.frame_shape[0], stretch=True)
self.set_height(self.frame_shape[1], stretch=True)
self.move_to(self.center_point)
def to_default_state(self) -> Self:
+ """Reset the camera to its default state
+ (config frame size, centered at origin, no rotation).
+ """
self.center()
self.set_height(config["frame_height"])
self.set_width(config["frame_width"])
@@ -144,7 +226,8 @@ class OpenGLCamera(OpenGLMobject):
self.model_matrix = self.default_model_matrix
return self
- def refresh_rotation_matrix(self):
+ def refresh_rotation_matrix(self) -> None:
+ """Refresh the camera's inverse rotation matrix based on its Euler angles."""
# Rotate based on camera orientation
theta, phi, gamma = self.euler_angles
quat = quaternion_mult(
@@ -152,9 +235,39 @@ class OpenGLCamera(OpenGLMobject):
quaternion_from_angle_axis(phi, RIGHT, axis_normalized=True),
quaternion_from_angle_axis(gamma, OUT, axis_normalized=True),
)
- self.inverse_rotation_matrix = rotation_matrix_transpose_from_quaternion(quat)
+ self.inverse_rotation_matrix = rotation_matrix_transpose_from_quaternion(
+ np.asarray(quat, dtype=float)
+ )
- def rotate(self, angle, axis=OUT, **kwargs):
+ @override
+ def rotate(
+ self,
+ angle: float,
+ axis: Vector3DLike = OUT,
+ about_point: Point3DLike | None = None,
+ **kwargs: Any,
+ ) -> Self:
+ """
+ Rotate the camera by a given angle around a specified axis.
+
+ Parameters
+ ----------
+ angle : float
+ The angle in radians to rotate the camera.
+ axis : Vector3DLike, optional
+ The axis around which to rotate the camera. Default is OUT (z-axis).
+ about_point : Point3DLike, optional
+ Ignored. For OpenGLCamera, rotation is always about the camera's center.
+
+ **kwargs : Any
+ Not used for OpenGLCamera. Passing additional keyword arguments
+ has no effect.
+
+ Returns
+ -------
+ Self
+ The rotated camera instance. Returned for chaining.
+ """
curr_rot_T = self.inverse_rotation_matrix
added_rot_T = rotation_matrix_transpose(angle, axis)
new_rot_T = np.dot(curr_rot_T, added_rot_T)
@@ -169,7 +282,43 @@ class OpenGLCamera(OpenGLMobject):
self.set_euler_angles(theta, phi, gamma)
return self
- def set_euler_angles(self, theta=None, phi=None, gamma=None):
+ def set_euler_angles(
+ self,
+ theta: float | None = None,
+ phi: float | None = None,
+ gamma: float | None = None,
+ ) -> Self:
+ """
+ Set the camera's Euler angles [1]_ (theta, phi, gamma).
+
+ Parameters
+ ----------
+ theta : float | None, optional
+ The angle in radians for rotation around the OUT (z) axis.
+ If None, the current theta value is retained.
+ phi : float | None, optional
+ The angle in radians for rotation around the RIGHT (x) axis.
+ If None, the current phi value is retained.
+ gamma : float | None, optional
+ The angle in radians for rotation around the OUT (z) axis.
+ If None, the current gamma value is retained.
+
+ Returns
+ -------
+ Self
+ The camera instance with updated Euler angles. Returned for chaining.
+
+ See Also
+ --------
+ set_theta : Set the theta Euler angle.
+ set_phi : Set the phi Euler angle.
+ set_gamma : Set the gamma Euler angle.
+
+ References
+ ----------
+ .. [1] Wikipedia, "Euler angles",
+ https://en.wikipedia.org/wiki/Euler_angles
+ """
if theta is not None:
self.euler_angles[0] = theta
if phi is not None:
@@ -180,20 +329,63 @@ class OpenGLCamera(OpenGLMobject):
return self
def set_theta(self, theta: float) -> Self:
+ """
+ Set the camera's theta Euler angle (in radians).
+
+ See Also
+ --------
+ set_euler_angles : Set all Euler angles at once.
+ set_phi : Set the phi Euler angle.
+ set_gamma : Set the gamma Euler angle.
+ """
return self.set_euler_angles(theta=theta)
def set_phi(self, phi: float) -> Self:
+ """
+ Set the camera's phi Euler angle (in radians).
+
+ See Also
+ --------
+ set_euler_angles : Set all Euler angles at once.
+ set_theta : Set the theta Euler angle.
+ set_gamma : Set the gamma Euler angle.
+ """
return self.set_euler_angles(phi=phi)
def set_gamma(self, gamma: float) -> Self:
+ """
+ Set the camera's gamma Euler angle (in radians).
+
+ See Also
+ --------
+ set_euler_angles : Set all Euler angles at once.
+ set_theta : Set the theta Euler angle.
+ set_phi : Set the phi Euler angle.
+ """
return self.set_euler_angles(gamma=gamma)
def increment_theta(self, dtheta: float) -> Self:
+ """
+ Increment the camera's theta Euler angle by a given amount (in radians).
+
+ See Also
+ --------
+ set_euler_angles : Set all Euler angles at once.
+ set_theta : Set the theta Euler angle.
+ """
self.euler_angles[0] += dtheta
self.refresh_rotation_matrix()
return self
def increment_phi(self, dphi: float) -> Self:
+ """
+ Increment the camera's phi Euler angle by a given amount (in radians).
+
+ See Also
+ --------
+ set_euler_angles : Set all Euler angles at once.
+ set_phi : Set the phi Euler angle.
+ """
phi = self.euler_angles[1]
new_phi = clip(phi + dphi, -PI / 2, PI / 2)
self.euler_angles[1] = new_phi
@@ -201,68 +393,150 @@ class OpenGLCamera(OpenGLMobject):
return self
def increment_gamma(self, dgamma: float) -> Self:
+ """
+ Increment the camera's gamma Euler angle by a given amount (in radians).
+
+ See Also
+ --------
+ set_euler_angles : Set all Euler angles at once.
+ set_gamma : Set the gamma Euler angle.
+ """
self.euler_angles[2] += dgamma
self.refresh_rotation_matrix()
return self
- def get_shape(self):
+ def get_shape(self) -> tuple[float, float]:
+ """Retrieve the width and height of the camera frame."""
return (self.get_width(), self.get_height())
- def get_center(self):
+ def get_center(self) -> Point3D:
+ """
+ Retrieve the center point of the camera in 3D space.
+
+ Notes
+ -----
+ The center point is assumed to be the first point in the camera's points array.
+ """
# Assumes first point is at the center
- return self.points[0]
+ return typing.cast(Point3D, self.points[0])
def get_width(self) -> float:
+ """Retrieve the width of the camera frame."""
points = self.points
- return points[2, 0] - points[1, 0]
+ out = points[2, 0] - points[1, 0]
+ return float(out)
def get_height(self) -> float:
+ """Retrieve the height of the camera frame."""
points = self.points
- return points[4, 1] - points[3, 1]
+ out = points[4, 1] - points[3, 1]
+ return float(out)
+ # return points[4, 1] - points[3, 1]
def get_focal_distance(self) -> float:
+ """Retrieve the focal distance of the camera."""
return self.focal_distance * self.get_height()
- def interpolate(self, *args, **kwargs):
- super().interpolate(*args, **kwargs)
+ @override
+ def interpolate(
+ self,
+ mobject1: OpenGLMobject,
+ mobject2: OpenGLMobject,
+ alpha: float,
+ path_func: PathFuncType = straight_path(),
+ ) -> Self:
+ super().interpolate(mobject1, mobject2, alpha, path_func)
self.refresh_rotation_matrix()
+ return self
class OpenGLRenderer:
+ """
+ An OpenGL-based renderer.
+
+ Attributes
+ ----------
+ animation_elapsed_time : float
+ The elapsed time of the current animation.
+ animation_start_time : float
+ The start time of the current animation.
+ animations_hashes : list[str | None]
+ List of animation hashes for caching.
+ anti_alias_width : float
+ The width used for anti-aliasing in pixel units.
+ background_color : FloatRGBA
+ The background color of the renderer.
+ camera : OpenGLCamera
+ The camera used for rendering.
+ num_plays : float
+ The number of animation plays executed.
+ path_to_texture_id : dict[str, int]
+ Mapping from texture file paths to OpenGL texture IDs.
+ pressed_keys : set[int]
+ Set of currently pressed key codes.
+ skip_animations : bool
+ Whether animations are currently being skipped.
+ time : float
+ The total elapsed time for the renderer.
+ window : Window | None
+ The window used for previewing, if any.
+ """
+
def __init__(
self,
file_writer_class: type[SceneFileWriter] = SceneFileWriter,
skip_animations: bool = False,
) -> None:
+ """Initializes the OpenGLRenderer.
+
+ Parameters
+ ----------
+ file_writer_class : type[SceneFileWriter], optional
+ The class to use for writing scene files, by default SceneFileWriter.
+ skip_animations : bool, optional
+ Whether to skip animations during rendering, by default False.
+ """
# Measured in pixel widths, used for vector graphics
self.anti_alias_width = 1.5
self._file_writer_class = file_writer_class
self._original_skipping_status = skip_animations
self.skip_animations = skip_animations
- self.animation_start_time = 0
- self.animation_elapsed_time = 0
- self.time = 0
- self.animations_hashes = []
+ self.animation_start_time = 0.0
+ self.animation_elapsed_time = 0.0
+ self.time = 0.0
+ self.animations_hashes: list[str | None] = []
self.num_plays = 0
self.camera = OpenGLCamera()
- self.pressed_keys = set()
-
- self.window = None
-
- # Initialize texture map.
- self.path_to_texture_id = {}
-
+ self.pressed_keys: set[int] = set()
+ self.window: Window | None = None
+ self.path_to_texture_id: dict[str, int] = {}
self.background_color = config["background_color"]
def init_scene(self, scene: Scene) -> None:
- self.partial_movie_files = []
- self.file_writer: Any = self._file_writer_class(
+ """
+ Initializes the OpenGL rendering context and related resources
+ for the given scene.
+
+ Set up:
+ - the file writer
+ - the background color
+ - the OpenGL context
+ - the window (if needed)
+
+ Parameters
+ ----------
+ scene : Scene
+ The scene to be rendered
+ """
+ self.partial_movie_files: list[str | None] = []
+ self.file_writer: SceneFileWriter = self._file_writer_class(
self,
scene.__class__.__name__,
)
self.scene = scene
+
self.background_color = config["background_color"]
if self.should_create_window():
from .opengl_renderer_window import Window
@@ -290,7 +564,15 @@ class OpenGLRenderer:
moderngl.ONE,
)
- def should_create_window(self):
+ def should_create_window(self) -> bool:
+ """
+ Determine whether a window should be created for rendering
+ based on the current configuration.
+
+ Notes
+ -----
+ A windows is always created if the 'force_window' configuration is enabled.
+ """
if config["force_window"]:
logger.warning(
"'--force_window' is enabled, this is intended for debugging purposes "
@@ -305,21 +587,51 @@ class OpenGLRenderer:
and not config["dry_run"]
)
- def get_pixel_shape(self):
- if hasattr(self, "frame_buffer_object"):
- return self.frame_buffer_object.viewport[2:4]
- else:
+ def get_pixel_shape(self) -> tuple[int, int] | None:
+ """
+ Retrieve the pixel dimensions of the current frame buffer object (2D).
+
+ Returns
+ -------
+ width : int
+ The width of the frame buffer in pixels.
+ height : int
+ The height of the frame buffer in pixels.
+ """
+ frame_buffer: Framebuffer | None = getattr(self, "frame_buffer_object", None)
+ if frame_buffer is None:
return None
+ _, _, pixel_width, pixel_height = frame_buffer.viewport
+ return pixel_width, pixel_height
- def refresh_perspective_uniforms(self, camera):
- pw, ph = self.get_pixel_shape()
- fw, fh = camera.get_shape()
+ def refresh_perspective_uniforms(self, camera: OpenGLCamera) -> None:
+ """
+ Update the perspective-related uniform variables used in the
+ OpenGL renderer based on the current camera settings.
+
+ Parameters
+ ----------
+ camera : OpenGLCamera
+ The camera object from which to extract perspective and lighting information.
+
+ Raises
+ ------
+ ValueError
+ If the renderer's pixel shape is not available.
+ """
+ pixel_shape = self.get_pixel_shape()
+ if pixel_shape is None:
+ msg = "Pixel shape is None, cannot refresh perspective uniforms."
+ raise ValueError(msg)
+
+ pixel_width, pixel_height = pixel_shape
+ frame_width, frame_height = camera.get_shape()
# TODO, this should probably be a mobject uniform, with
# the camera taking care of the conversion factor
- anti_alias_width = self.anti_alias_width / (ph / fh)
+ anti_alias_width = self.anti_alias_width / (pixel_height / frame_height)
# Orient light
rotation = camera.inverse_rotation_matrix
- light_pos = camera.light_source.get_location()
+ light_pos: Point3D = camera.light_source.get_location()
light_pos = np.dot(rotation, light_pos)
self.perspective_uniforms = {
@@ -331,7 +643,21 @@ class OpenGLRenderer:
"focal_distance": camera.get_focal_distance(),
}
- def render_mobject(self, mobject):
+ def render_mobject(self, mobject: OpenGLMobject | OpenGLVMobject) -> None:
+ """
+ Render an OpenGL mobject (either OpenGLMobject or OpenGLVMobject)
+ using the appropriate shaders and rendering pipeline.
+
+ Parameters
+ ----------
+ mobject : OpenGLMobject | OpenGLVMobject
+ The mobject to render. Must be an instance of OpenGLMobject or OpenGLVMobject.
+
+ Raises
+ ------
+ TypeError
+ If a shader texture is not a moderngl.Uniform or moderngl.UniformBlock.
+ """
if isinstance(mobject, OpenGLVMobject):
if config["use_projection_fill_shaders"]:
render_opengl_vectorized_mobject_fill(self, mobject)
@@ -340,15 +666,25 @@ class OpenGLRenderer:
render_opengl_vectorized_mobject_stroke(self, mobject)
shader_wrapper_list = mobject.get_shader_wrapper_list()
-
# Convert ShaderWrappers to Meshes.
for shader_wrapper in shader_wrapper_list:
- shader = Shader(self.context, shader_wrapper.shader_folder)
+ folder = shader_wrapper.shader_folder
+ shader = Shader(
+ context=self.context, name=str(folder) if folder is not None else None
+ )
# Set textures.
for name, path in shader_wrapper.texture_paths.items():
- tid = self.get_texture_id(path)
- shader.shader_program[name].value = tid
+ tid = self.get_texture_id(str(path))
+ shader_texture = shader.shader_program[name]
+ if not isinstance(
+ shader_texture, (moderngl.Uniform, moderngl.UniformBlock)
+ ):
+ msg = (
+ f"Shader texture must be a uniform, got {type(shader_texture)}"
+ )
+ raise TypeError(msg)
+ shader_texture.value = tid
# Set uniforms.
for name, value in it.chain(
@@ -358,13 +694,11 @@ class OpenGLRenderer:
with contextlib.suppress(KeyError):
shader.set_uniform(name, value)
try:
- shader.set_uniform(
- "u_view_matrix", self.scene.camera.formatted_view_matrix
- )
- shader.set_uniform(
- "u_projection_matrix",
- self.scene.camera.projection_matrix,
- )
+ # TODO: make the type of 'camera' generic in the 'Scene' class
+ # to avoid the cast here
+ cam = typing.cast("OpenGLCamera", self.scene.camera)
+ shader.set_uniform("u_view_matrix", cam.formatted_view_matrix)
+ shader.set_uniform("u_projection_matrix", cam.projection_matrix)
except KeyError:
pass
@@ -375,39 +709,93 @@ class OpenGLRenderer:
self.context.disable(moderngl.DEPTH_TEST)
# Render.
+ vert_indices = shader_wrapper.vert_indices
mesh = Mesh(
shader,
shader_wrapper.vert_data,
- indices=shader_wrapper.vert_indices,
+ indices=np.asarray(vert_indices) if vert_indices is not None else None,
use_depth_test=shader_wrapper.depth_test,
primitive=mobject.render_primitive,
)
mesh.set_uniforms(self)
mesh.render()
- def get_texture_id(self, path):
- if repr(path) not in self.path_to_texture_id:
+ def get_texture_id(self, path: str) -> int:
+ """
+ Retrieves the OpenGL texture ID associated with the given image file path.
+
+ Automatically creates a new texture it it has not been loaded before.
+
+ Parameters
+ ----------
+ path : str
+ The file path to the texture image.
+
+ Returns
+ -------
+ int
+ The OpenGL texture ID corresponding to the given path.
+ """
+ return (
+ self.path_to_texture_id[path]
+ if path in self.path_to_texture_id
+ else self._create_texture(path)
+ )
+
+ def _create_texture(self, image_path: str) -> int:
+ """
+ Create an OpenGL texture from the given image file path, get its texture ID,
+ and store it in `self.path_to_texture_id[image_path]`.
+
+ Parameters
+ ----------
+ image_path : str
+ The file path to the image to be loaded as a texture.
+
+ Returns
+ -------
+ int
+ The texture ID assigned to the newly created texture.
+ """
+ with Image.open(image_path) as img:
tid = len(self.path_to_texture_id)
+
+ # grayscale image
+ if img.mode == "L":
+ components = 1
+ swizzle = "RRR1"
+ else:
+ # convert everything to RGBA for consistency
+ img = img.convert("RGBA")
+ components = 4
+ swizzle = "RGBA"
+
texture = self.context.texture(
- size=path.size,
- components=len(path.getbands()),
- data=path.tobytes(),
+ size=img.size,
+ components=components,
+ data=img.tobytes(),
)
- texture.repeat_x = False
- texture.repeat_y = False
- texture.filter = (moderngl.NEAREST, moderngl.NEAREST)
- texture.swizzle = "RRR1" if path.mode == "L" else "RGBA"
- texture.use(location=tid)
- self.path_to_texture_id[repr(path)] = tid
-
- return self.path_to_texture_id[repr(path)]
+ texture.repeat_x = False
+ texture.repeat_y = False
+ texture.filter = (moderngl.NEAREST, moderngl.NEAREST)
+ texture.swizzle = swizzle
+ texture.use(location=tid)
+ self.path_to_texture_id[image_path] = tid
+ return tid
def update_skipping_status(self) -> None:
- """This method is used internally to check if the current
- animation needs to be skipped or not. It also checks if
- the number of animations that were played correspond to
- the number of animations that need to be played, and
- raises an EndSceneEarlyException if they don't correspond.
+ """
+ Check and update the skipping status for the current animation
+ (self.skip_animations flag) based on the configuration settings.
+
+ Parameters
+ ----------
+ None
+
+ Raises
+ ------
+ EndSceneEarlyException
+ If the number of played animations exceeds the configured upper bound.
"""
# there is always at least one section -> no out of bounds here
if self.file_writer.sections[-1].skip_animations:
@@ -428,14 +816,30 @@ class OpenGLRenderer:
def play(
self,
scene: Scene,
- *args: Animation | Mobject | _AnimationBuilder,
+ *animations: Animation | Mobject | _AnimationBuilder,
**kwargs: Any,
) -> None:
+ """
+ Plays the given animations or mobjects in the specified scene.
+
+ "Playing" here refers to the process of compiling animation data,
+ beginning the animations, updating frames, and finalizing the animation
+ in the context of the renderer.
+
+ Parameters
+ ----------
+ scene Scene
+ The scene in which to play the animations.
+ *animations Animation | Mobject | _AnimationBuilder
+ The animations, mobjects, or animation builders to play.
+ **kwargs Any
+ Additional keyword arguments to pass to the animation compilation.
+ """
# TODO: Handle data locking / unlocking.
self.animation_start_time = time.time()
self.file_writer.begin_animation(not self.skip_animations)
- scene.compile_animation_data(*args, **kwargs)
+ scene.compile_animation_data(*animations, **kwargs)
scene.begin_animations()
if scene.is_current_animation_frozen_frame():
self.update_frame(scene)
@@ -459,12 +863,44 @@ class OpenGLRenderer:
self.num_plays += 1
def clear_screen(self) -> None:
+ """
+ Clears the current frame buffer and updates the display window
+ accordingly.
+
+ The screen is cleared using the background color specified
+ in the renderer.
+ """
self.frame_buffer_object.clear(*self.background_color)
+ if self.window is None:
+ return
self.window.swap_buffers()
def render(
- self, scene: Scene, frame_offset, moving_mobjects: list[Mobject]
+ self, scene: Scene, frame_offset: float, moving_mobjects: list[Mobject]
) -> None:
+ """
+ Renders a single frame of the given scene using OpenGL.
+
+ Parameters
+ ----------
+ scene : Scene
+ The scene to render.
+ frame_offset : float
+ The time offset for the current frame in seconds. If no window is present,
+ this parameter is ignored, and a frame is a true snapshot of
+ the scene at the current time.
+ moving_mobjects : list[Mobject]
+ List of mobjects that are currently moving and need to be updated.
+ Not used at all, kept for compatibility with other renderers.
+
+ Notes
+ -----
+ - Updates the frame for the scene.
+ - If animations are skipped, the method returns early.
+ - Writes the current frame using the file writer.
+ - If a window is present, swaps buffers and continues
+ updating frames until the animation elapsed time reaches the frame offset.
+ """
self.update_frame(scene)
if self.skip_animations:
@@ -478,14 +914,37 @@ class OpenGLRenderer:
self.update_frame(scene)
self.window.swap_buffers()
- def update_frame(self, scene):
+ def update_frame(self, scene: Scene) -> None:
+ """
+ Update and render the current frame for the given scene.
+
+ Performs the following steps:
+ 1. Clear the frame buffer with the background color.
+ 2. Refresh camera perspective uniforms for rendering.
+ 3. Iterate through all mobjects in the scene, rendering those marked for display.
+ 4. Iterate through all mesh objects in the scene, setting their uniforms and rendering them.
+ 5. Update the elapsed animation time.
+
+ Parameters
+ ----------
+ scene : Scene
+ The scene to render the frame for.
+ """
self.frame_buffer_object.clear(*self.background_color)
- self.refresh_perspective_uniforms(scene.camera)
+
+ # TODO: make the type of 'camera' generic in the 'Scene' class
+ # to avoid the cast here
+ cam = typing.cast("OpenGLCamera", scene.camera)
+ self.refresh_perspective_uniforms(cam)
for mobject in scene.mobjects:
if not mobject.should_render:
continue
- self.render_mobject(mobject)
+
+ # TODO: make the type of 'mobject' generic in the 'Scene' class
+ # to avoid the cast here
+ mobj = typing.cast("OpenGLMobject | OpenGLVMobject", mobject)
+ self.render_mobject(mobj)
for obj in scene.meshes:
for mesh in obj.get_meshes():
@@ -494,7 +953,22 @@ class OpenGLRenderer:
self.animation_elapsed_time = time.time() - self.animation_start_time
- def scene_finished(self, scene):
+ def scene_finished(self, scene: Scene) -> None:
+ """
+ Handle the finalization process after a scene has finished rendering.
+
+ Performs the following actions:
+ - If any plays (animations) have occurred, finalizes the file writing process.
+ - If no plays have occurred but movie writing is enabled, disables
+ movie writing to avoid creating an empty movie file.
+ - If the configuration requires saving the last frame,
+ updates and saves the final image of the scene.
+
+ Parameters
+ ----------
+ scene : Scene
+ The scene that has finished rendering.
+ """
# When num_plays is 0, no images have been output, so output a single
# image in this case
if self.num_plays > 0:
@@ -507,7 +981,14 @@ class OpenGLRenderer:
self.update_frame(scene)
self.file_writer.save_image(self.get_image())
- def should_save_last_frame(self):
+ def should_save_last_frame(self) -> bool:
+ """
+ Determine whether the last frame of the scene should be saved,
+ i.e. if one of the following conditions is met:
+ - The configuration option 'save_last_frame' is enabled.
+ - The scene is not in interactive mode.
+ - This is the first play (i.e., num_plays == 0).
+ """
if config["save_last_frame"]:
return True
if self.scene.interactive_mode:
@@ -515,34 +996,80 @@ class OpenGLRenderer:
return self.num_plays == 0
def get_image(self) -> Image.Image:
- """Returns an image from the current frame. The first argument passed to image represents
- the mode RGB with the alpha channel A. The data we read is from the currently bound frame
- buffer. We pass in 'raw' as the name of the decoder, 0 and -1 args are specifically
- used for the decoder tand represent the stride and orientation. 0 means there is no
- padding expected between bytes and -1 represents the orientation and means the first
- line of the image is the bottom line on the screen.
+ """
+ Get the current OpenGL frame buffer as a PIL Image.
Returns
-------
- PIL.Image
- The PIL image of the array.
+ Image.Image
+ The image representation of the current frame buffer.
+
+ Raises
+ ------
+ ValueError
+ If the pixel shape cannot be determined.
+
+ Notes
+ -----
+ The image is constructed from raw RGBA buffer data, with the
+ origin at the bottom-left.
"""
raw_buffer_data = self.get_raw_frame_buffer_object_data()
+ pixel_shape = self.get_pixel_shape()
+ if pixel_shape is None:
+ msg = "Pixel shape is None, cannot get image."
+ raise ValueError(msg)
+
image = Image.frombytes(
- "RGBA",
- self.get_pixel_shape(),
- raw_buffer_data,
- "raw",
- "RGBA",
- 0,
- -1,
+ "RGBA", # mode (rgb, a for alpha (transparency)))
+ pixel_shape, # size
+ raw_buffer_data, # data
+ "raw", # decoder_name
+ # *args for the decoder
+ "RGBA", # raw mode
+ 0, # stride (O = no extra padding)
+ -1, # orientation (-1 = bottom to top, 1 = top to bottom)
)
return image
- def save_static_frame_data(self, scene, static_mobjects):
+ def save_static_frame_data(
+ self, scene: Scene, static_mobjects: Iterable[Mobject]
+ ) -> None:
pass
- def get_frame_buffer_object(self, context, samples=0):
+ def get_frame_buffer_object(
+ self, context: moderngl.Context, samples: int = 0
+ ) -> Framebuffer:
+ """
+ Creates and returns a framebuffer object configured with color
+ and depth attachments.
+
+ Parameters
+ ----------
+ context : moderngl.Context
+ The ModernGL context used to create the framebuffer and
+ its attachments.
+ samples : int, optional
+ The number of samples for multisample anti-aliasing (MSAA)[1]_.
+ Default is 0 (no MSAA).
+
+ Returns
+ -------
+ Framebuffer
+ A framebuffer object with a color texture attachment and
+ a depth renderbuffer attachment, both sized according to
+ the current configuration's pixel width and height.
+
+ Notes
+ -----
+ Framebuffer's color attachment is supposed RGBA.
+ Pixel dimensions are taken from the global config of Manim.
+
+ References
+ ----------
+ .. [1] Wikipedia, "Multisample anti-aliasing",
+ https://en.wikipedia.org/wiki/Multisample_anti-aliasing
+ """
pixel_width = config["pixel_width"]
pixel_height = config["pixel_height"]
num_channels = 4
@@ -558,7 +1085,20 @@ class OpenGLRenderer:
),
)
- def get_raw_frame_buffer_object_data(self, dtype="f1"):
+ def get_raw_frame_buffer_object_data(self, dtype: str = "f1") -> bytes:
+ """
+ Get the raw data from the current frame buffer object as bytes.
+
+ This method reads the pixel data from the frame buffer object using the specified data type.
+ The data is read with 4 color channels (typically RGBA).
+
+ Args:
+ dtype (str, optional): The data type to use when reading the buffer.
+ Defaults to "f1" (i.e., float with 1 byte).
+
+ Returns:
+ bytes: The raw pixel data from the frame buffer object.
+ """
# Copy blocks from the fbo_msaa to the drawn fbo using Blit
# pw, ph = self.get_pixel_shape()
# gl.glBindFramebuffer(gl.GL_READ_FRAMEBUFFER, self.fbo_msaa.glo)
@@ -567,17 +1107,35 @@ class OpenGLRenderer:
# 0, 0, pw, ph, 0, 0, pw, ph, gl.GL_COLOR_BUFFER_BIT, gl.GL_LINEAR
# )
num_channels = 4
- ret = self.frame_buffer_object.read(
+ ret: bytes = self.frame_buffer_object.read(
viewport=self.frame_buffer_object.viewport,
components=num_channels,
dtype=dtype,
)
return ret
- def get_frame(self):
+ def get_frame(self) -> RGBAPixelArray:
+ """
+ Get the current frame buffer as a Numpy array of RGBA pixel values.
+
+ Returns
+ -------
+ RGBAPixelArray
+ A Numpy array of shape (height, width, 4) containing the
+ RGBA pixel data of the current frame, with dtype uint8.
+
+ Raises
+ ------
+ ValueError
+ If the pixel shape cannot be determined.
+ """
# get current pixel values as numpy data in order to test output
raw = self.get_raw_frame_buffer_object_data(dtype="f1")
pixel_shape = self.get_pixel_shape()
+ if pixel_shape is None:
+ msg = "Pixel shape is None, cannot get frame."
+ raise ValueError(msg)
+
result_dimensions = (pixel_shape[1], pixel_shape[0], 4)
np_buf = np.frombuffer(raw, dtype="uint8").reshape(result_dimensions)
np_buf = np.flipud(np_buf)
@@ -589,25 +1147,61 @@ class OpenGLRenderer:
def pixel_coords_to_space_coords(
self, px: float, py: float, relative: bool = False, top_left: bool = False
) -> Point3D:
+ """
+ Converts pixel coordinates to space (scene) coordinates.
+
+ top_left flag should be set to True when using a GUI framework
+ where the (0,0) is at the top left: e.g. PySide6.
+
+ Parameters
+ ----------
+ px : float
+ The x-coordinate in pixel space.
+ py : float
+ The y-coordinate in pixel space.
+ relative : bool, optional
+ If True, returns coordinates relative to the frame (normalized to [-1, 1]).
+ If False, returns absolute space coordinates. Default is False.
+ top_left : bool, optional
+ If True, treats the origin (0, 0) as the top-left corner of the pixel space.
+ If False, treats the origin as the bottom-left. Default is False.
+
+ Returns
+ -------
+ Point3D
+ The corresponding coordinates in space as a NumPy array of shape (3,).
+
+ Notes
+ -----
+ If the pixel shape is not available, returns the origin [0, 0, 0].
+ """
pixel_shape = self.get_pixel_shape()
if pixel_shape is None:
- return np.array([0, 0, 0])
- pw, ph = pixel_shape
- fh = config["frame_height"]
- fc = self.camera.get_center()
+ return typing.cast(Point3D, np.array([0.0, 0.0, 0.0]))
+ pixel_width, pixel_height = pixel_shape
+ frame_height = config["frame_height"]
+ frame_center = self.camera.get_center()
if relative:
- return 2 * np.array([px / pw, py / ph, 0])
- else:
- # Only scale wrt one axis
- scale = fh / ph
- return fc + scale * np.array(
- [(px - pw / 2), (-1 if top_left else 1) * (py - ph / 2), 0]
- )
+ # relative -> just normalize to [-1, 1]
+ return 2 * np.array([px / pixel_width, py / pixel_height, 0])
+
+ scale = frame_height / pixel_height
+ y_direction = -1 if top_left else 1
+
+ return typing.cast(
+ Point3D,
+ frame_center
+ + scale
+ * np.array(
+ [(px - pixel_width / 2), y_direction * (py - pixel_height / 2), 0.0]
+ ),
+ )
@property
- def background_color(self):
+ def background_color(self) -> FloatRGBA:
+ """The background color of the renderer (RGBA format)."""
return self._background_color
@background_color.setter
- def background_color(self, value):
+ def background_color(self, value: ParsableManimColor) -> None:
self._background_color = color_to_rgba(value, 1.0)
diff --git a/mypy.ini b/mypy.ini
index 379400f82..ba90aad29 100644
--- a/mypy.ini
+++ b/mypy.ini
@@ -142,9 +142,6 @@ ignore_errors = True
[mypy-manim.mobject.vector_field]
ignore_errors = True
-[mypy-manim.renderer.opengl_renderer]
-ignore_errors = True
-
[mypy-manim.renderer.shader_wrapper]
ignore_errors = True