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.pyindex 7284504cd..9c1c577c5 100644--- a/manim/renderer/opengl_renderer.py+++ b/manim/renderer/opengl_renderer.py@@ -3,28 +3,31 @@ from __future__ import annotationsimport contextlibimport itertools as itimport time+import typingfrom functools import cached_property-from typing import TYPE_CHECKING, Any+from typing import TYPE_CHECKING, Any, Selfimport modernglimport numpy as np+from moderngl import Framebufferfrom PIL import Image+from typing_extensions import overridefrom manim import config, loggerfrom manim.mobject.opengl.opengl_mobject import (OpenGLMobject,OpenGLPoint,- _AnimationBuilder,)from manim.mobject.opengl.opengl_vectorized_mobject import OpenGLVMobject+from manim.typing import MatrixMN, Point3Dfrom manim.utils.caching import handle_caching_playfrom manim.utils.color import color_to_rgbafrom manim.utils.exceptions import EndSceneEarlyException+from manim.utils.paths import straight_pathfrom ..constants import *from ..scene.scene_file_writer import SceneFileWriterfrom ..utils import opengl-from ..utils.config_ops import _Datafrom ..utils.simple_functions import clipfrom ..utils.space_ops import (angle_of_vector,@@ -40,34 +43,108 @@ from .vectorized_mobject_rendering import ()if TYPE_CHECKING:+ from collections.abc import Iterablefrom typing import Selffrom manim.animation.animation import Animation- from manim.mobject.mobject import Mobject+ from manim.mobject.mobject import Mobject, _AnimationBuilderfrom 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 = Trueself.frame_rate = 60self.orthographic = orthographic@@ -92,51 +169,56 @@ class OpenGLCamera(OpenGLMobject):if center_point is None:self.center_point = ORIGINelse:- 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_matrixsuper().__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_anglesself.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] = positionreturn 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_matrixreturn 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 orientationtheta, phi, gamma = self.euler_anglesquat = 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_matrixadded_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] = thetaif phi is not None:@@ -180,20 +329,63 @@ class OpenGLCamera(OpenGLMobject):return selfdef 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] += dthetaself.refresh_rotation_matrix()return selfdef 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 selfdef 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] += dgammaself.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 selfclass 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 graphicsself.anti_alias_width = 1.5self._file_writer_class = file_writer_classself._original_skipping_status = skip_animationsself.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 = 0self.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 lightrotation = 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_indicesmesh = 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 tiddef 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 hereif 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 += 1def 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:+ returnself.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 caseif 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 Trueif self.scene.interactive_mode:@@ -515,34 +996,80 @@ class OpenGLRenderer:return self.num_plays == 0def 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 outputraw = 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.iniindex 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