Coverage for src/manimgx/mobjects/images.py: 99%
78 statements
« prev ^ index » next coverage.py v7.16.1, created at 2026-10-26 05:52 +0000
« prev ^ index » next coverage.py v7.16.1, created at 2026-10-26 05:52 +0000
1"Pictures on meshes: decoded pixels and live camera views."
3from pathlib import Path
4from typing import TYPE_CHECKING, Self, Unpack
5from warnings import deprecated
7import numpy as np
9from manimgx.constants import DOWN, LEFT, RIGHT, UP, Resampling
10from manimgx.drawing.paint import (
11 WHITE,
12 YELLOW_C,
13 Fill,
14 Look,
15 ManimColor,
16 ParsableManimColor,
17 Style,
18 _Style,
19)
20from manimgx.mobject import MeshMobject
21from manimgx.settings import config
23__all__ = ["ImageMobject", "ImageMobjectFromCamera"]
25if TYPE_CHECKING:
26 from manimgx.mobjects.annotations import FrameOptions
27 from manimgx.scene import Camera
30class ImageMobject(MeshMobject):
31 """A picture: an image file or an array of pixels, on a rectangle as tall as its
32 pixels make it.
34 An image `scale_to_resolution` pixels tall (1080 unless given) is as tall as the
35 frame's short side (8 scene units by default), and any other in proportion. Shown
36 larger than its pixels, the picture is reconstructed from them by
37 `resampling_algorithm`: by default a smooth cubic through every pixel; linear blends
38 neighboring pixels; nearest shows each pixel as a square of its color. Shown smaller,
39 each pixel of the video shows the mean of the picture's pixels it covers, whatever
40 the algorithm, so thin lines and small text stay whole at any size. The mobject's
41 opacity multiplies its pixels' own.
43 Args:
44 filename_or_array: The picture: an image file's path, the file's contents
45 (bytes), or an array of pixel values from 0 to 255: (h, w) gray, (h, w, 3)
46 RGB or (h, w, 4) RGBA.
47 scale_to_resolution: How many pixels tall an image as tall as the frame's
48 short side is; 0 for an image 3 units tall, whatever its size.
49 invert: Whether its colors are inverted (not its transparency).
50 image_mode: The mode, as the Pillow library names them, a file is read in:
51 "RGBA", or "L" for gray.
52 resampling_algorithm: How the picture is reconstructed from its pixels, by the
53 Pillow library's number: 0, nearest; 2, linear; 3, cubic (Keys' cubic
54 convolution, Pillow's bicubic);
55 [RESAMPLING_ALGORITHMS][manimgx.RESAMPLING_ALGORITHMS] gives them by name.
56 stroke_width: The width of a border around the picture, in hundredths of a
57 scene unit; 0 for none.
58 stroke_color: The border's color.
60 Examples:
61 ```python
62 import numpy as np
64 import manimgx as m
67 class ImageMobjectExample(m.Scene):
68 def construct(self) -> None:
69 ramp = np.linspace(0, 255, 256)
70 pixels = np.zeros((256, 256, 3), dtype=np.uint8)
71 pixels[..., 0] = ramp # red grows to the right
72 pixels[..., 2] = ramp[:, np.newaxis] # blue grows downward
73 image = m.ImageMobject(pixels, scale_to_resolution=400)
74 self.play(m.FadeIn(image))
75 ```
77 ```python
78 import numpy as np
80 import manimgx as m
83 class ImageMobjectResamplingExample(m.Scene):
84 def construct(self) -> None:
85 pixels = np.full((3, 3), 60, dtype=np.uint8)
86 pixels[1, 1] = 255 # one white pixel, amid gray ones
87 images = m.Group()
88 for name in ("nearest", "linear", "cubic"):
89 image = m.ImageMobject(
90 pixels,
91 scale_to_resolution=6,
92 resampling_algorithm=m.RESAMPLING_ALGORITHMS[name],
93 )
94 images.add(m.Group(image, m.Text(name).next_to(image, m.DOWN)))
95 self.add(images.arrange(buff=0.5))
96 ```
97 """
99 # a textured quad, CE's four corners (UL, UR, DL, DR) its vertices; the opacity lives
100 # in the paint, a multiplier
101 def __init__(
102 self,
103 filename_or_array: str | Path | bytes | np.ndarray,
104 scale_to_resolution: int = 1080,
105 invert: bool = False,
106 image_mode: str = "RGBA",
107 resampling_algorithm: Resampling = 3,
108 stroke_width: float = 0, # a border's (the picture is the texture)
109 stroke_color: ParsableManimColor = WHITE,
110 **kwargs: Unpack[Look],
111 ) -> None:
112 import io
114 from PIL import Image
116 if isinstance(filename_or_array, (str, Path, bytes)):
117 source = (
118 io.BytesIO(filename_or_array)
119 if isinstance(filename_or_array, bytes)
120 else filename_or_array
121 )
122 pixels = np.array(Image.open(source).convert(image_mode))
123 else:
124 pixels = np.array(filename_or_array)
125 pixels = _to_rgba(pixels)
126 if invert:
127 pixels[:, :, :3] = 255 - pixels[:, :, :3]
128 pixels.flags.writeable = False
129 self.scale_to_resolution = scale_to_resolution
130 self.resampling_algorithm = resampling_algorithm
131 super().__init__(
132 np.array([UP + LEFT, UP + RIGHT, DOWN + LEFT, DOWN + RIGHT], dtype=float),
133 np.array([[0, 1, 2], [1, 3, 2]]),
134 uvs=np.array([[0, 0], [1, 0], [0, 1], [1, 1]], dtype=float),
135 texture=pixels,
136 **kwargs,
137 )
138 if (
139 stroke_width > 0
140 ): # a border is just a rectangle child that follows every transform
141 from manimgx.mobjects.shapes import Polygon
143 self.add(
144 Polygon(
145 *self.points[[0, 1, 3, 2]],
146 stroke_width=stroke_width,
147 stroke_color=stroke_color,
148 )
149 )
151 @property
152 def pixel_array(self) -> np.ndarray:
153 """The current picture's (h, w, 4) RGBA pixels, from 0 to 255.
155 Pictures decoded or tinted by this image are read-only. Becoming another
156 textured mesh adopts its texture, including whether it is writable.
157 """
158 texture = self.paint.texture
159 assert isinstance(texture, np.ndarray)
160 return texture
162 def generate_points(self) -> Self:
163 super().generate_points()
164 self.center()
165 texture = self._texture
166 assert isinstance(texture, np.ndarray)
167 h, w = texture.shape[:2]
168 # an image `scale_to_resolution` pixels high spans the frame's short side
169 short = min(config.frame_width, config.frame_height)
170 height = h / self.scale_to_resolution * short if self.scale_to_resolution else 3
171 return self.stretch_to_fit_height(height).stretch_to_fit_width(height * w / h)
173 def set_color( # ty: ignore[invalid-method-override] # CE's: an image's tint, then its alpha
174 self,
175 color: ParsableManimColor = YELLOW_C,
176 alpha: float | None = None,
177 family: bool = True,
178 ) -> Self:
179 """Paint every pixel `color`, keeping its opacity: the picture becomes a
180 silhouette in that color.
182 Args:
183 alpha: Every pixel's opacity too, from 0 to 1; None keeps each one's.
184 family: Accepted for Manim compatibility; ignored: the picture alone is
185 painted.
186 """
187 pixels = self.pixel_array.copy()
188 pixels[:, :, :3] = (ManimColor(color).to_rgb() * 255).astype(np.uint8)
189 if alpha is not None:
190 pixels[:, :, 3] = int(255 * alpha)
191 pixels.flags.writeable = False
192 self.paint = self.paint.but(texture=pixels)
193 return self
195 def set_opacity(
196 self, opacity: float = 1.0, family: bool = True, *, alpha: float | None = None
197 ) -> Self:
198 """Set the picture's opacity, which multiplies its pixels' own.
200 Args:
201 opacity: The opacity, from 0 to 1.
202 family: Whether its whole family is set (a border too), or the picture
203 alone.
204 alpha: The opacity, by the name Manim's images give it; given, it wins over
205 `opacity`.
206 """
207 return super().set_opacity(opacity if alpha is None else alpha, family)
209 def set_resampling_algorithm(self, resampling_algorithm: Resampling) -> Self:
210 """Set how the picture is reconstructed from its pixels where it is shown larger
211 than they are.
213 Args:
214 resampling_algorithm: The filter, by the Pillow library's number: 0, nearest
215 (each pixel a square of its color); 2, linear; 3, cubic (smooth, and
216 through every pixel);
217 [RESAMPLING_ALGORITHMS][manimgx.RESAMPLING_ALGORITHMS] gives them by
218 name.
219 """
220 self.resampling_algorithm = resampling_algorithm
221 return self
223 @deprecated("Manim CE's machinery: ManimGX calls it itself", category=None)
224 def get_style(self) -> Fill:
225 """The picture's style, as fill keywords: its color and its opacity.
227 Returns:
228 A dict of `fill_color` and `fill_opacity`.
229 """
230 return Fill(fill_color=self.get_color(), fill_opacity=self.get_fill_opacity())
233def _to_rgba(pixels: np.ndarray) -> np.ndarray:
234 if pixels.ndim == 2:
235 pixels = np.stack([pixels] * 3, axis=-1)
236 if pixels.shape[2] == 3:
237 pixels = np.concatenate(
238 [pixels, np.full((*pixels.shape[:2], 1), 255, dtype=pixels.dtype)], axis=2
239 )
240 return pixels.astype(np.uint8)
243class ImageCameraOptions(_Style, total=False):
244 """A camera picture's keywords, for the scenes that pass them on: a
245 [ZoomedScene][manimgx.ZoomedScene]'s display.
247 Beyond these, they take the [style keywords][manimgx.drawing.paint.Style].
248 """
250 default_display_frame_config: "FrameOptions | None"
251 """[Surrounding rectangle
252 keywords][manimgx.mobjects.annotations.FrameOptions] for the picture's
253 outline, over a white outline 3 wide with no margin (default None)."""
256@deprecated("Manim CE's machinery for ZoomedScene: use ZoomedScene", category=None)
257class ImageMobjectFromCamera(MeshMobject):
258 """What a camera sees, as a picture: a rectangle showing the camera's view, drawn
259 anew every frame.
261 The picture is 3 units tall, in the frame's proportions. Move the camera's
262 [frame][manimgx.Camera.frame] to look elsewhere, scale it to zoom: the picture
263 follows. The camera sees everything but this picture; a
264 [ZoomedScene][manimgx.ZoomedScene] shows its zoomed camera's view with one.
266 Args:
267 camera: The camera whose view the picture shows.
268 default_display_frame_config: [Surrounding rectangle
269 keywords][manimgx.mobjects.annotations.FrameOptions] for the
270 outline [add_display_frame][manimgx.ImageMobjectFromCamera.add_display_frame]
271 draws, over a white outline 3 wide with no margin.
273 Examples:
274 ```python
275 import manimgx as m
278 class ImageMobjectFromCameraExample(m.Scene):
279 def construct(self) -> None:
280 square = m.Square(side_length=4, color=m.BLUE, fill_opacity=0.5)
281 self.add(square.shift(2 * m.LEFT + 0.5 * m.DOWN))
282 camera = m.Camera()
283 frame = camera.frame.scale(0.25).move_to(square.get_corner(m.UL))
284 frame.set_stroke(m.YELLOW, 3)
285 picture = m.ImageMobjectFromCamera(camera).add_display_frame()
286 self.add(frame, picture.to_corner(m.UR))
287 self.play(frame.animate.move_to(square.get_corner(m.DR)), run_time=3)
288 ```
289 """
291 # a quad textured with the camera's view (a camera's view is a texture)
293 def __init__(
294 self,
295 camera: "Camera",
296 default_display_frame_config: "FrameOptions | None" = None,
297 **kwargs: Unpack[Style],
298 ) -> None:
299 self.camera = camera
300 """The camera whose view the picture shows."""
301 frame: FrameOptions = {"stroke_width": 3, "stroke_color": WHITE, "buff": 0}
302 self.default_display_frame_config = frame | (default_display_frame_config or {})
303 w = (
304 1.5 * config.frame_width / config.frame_height
305 ) # CE: 3 units high, the frame's aspect
306 super().__init__(
307 np.array(
308 [[-w, 1.5, 0], [w, 1.5, 0], [-w, -1.5, 0], [w, -1.5, 0]], dtype=float
309 ),
310 np.array([[0, 1, 2], [1, 3, 2]]),
311 uvs=np.array([[0, 0], [1, 0], [0, 1], [1, 1]], dtype=float),
312 texture=camera,
313 **kwargs,
314 )
316 def add_display_frame(self, **kwargs: "Unpack[FrameOptions]") -> Self:
317 """Outline the picture: a surrounding rectangle, added as a submobject.
319 Args:
320 **kwargs: [Surrounding rectangle
321 keywords][manimgx.mobjects.annotations.FrameOptions], over
322 `default_display_frame_config`.
323 """
324 from manimgx.mobjects.annotations import SurroundingRectangle
326 self.display_frame = SurroundingRectangle(
327 self, **(self.default_display_frame_config | kwargs)
328 )
329 return self.add(self.display_frame)