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

1"Pictures on meshes: decoded pixels and live camera views." 

2 

3from pathlib import Path 

4from typing import TYPE_CHECKING, Self, Unpack 

5from warnings import deprecated 

6 

7import numpy as np 

8 

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 

22 

23__all__ = ["ImageMobject", "ImageMobjectFromCamera"] 

24 

25if TYPE_CHECKING: 

26 from manimgx.mobjects.annotations import FrameOptions 

27 from manimgx.scene import Camera 

28 

29 

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. 

33 

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. 

42 

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. 

59 

60 Examples: 

61 ```python 

62 import numpy as np 

63 

64 import manimgx as m 

65 

66 

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 ``` 

76 

77 ```python 

78 import numpy as np 

79 

80 import manimgx as m 

81 

82 

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 """ 

98 

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 

113 

114 from PIL import Image 

115 

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 

142 

143 self.add( 

144 Polygon( 

145 *self.points[[0, 1, 3, 2]], 

146 stroke_width=stroke_width, 

147 stroke_color=stroke_color, 

148 ) 

149 ) 

150 

151 @property 

152 def pixel_array(self) -> np.ndarray: 

153 """The current picture's (h, w, 4) RGBA pixels, from 0 to 255. 

154 

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 

161 

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) 

172 

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. 

181 

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 

194 

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. 

199 

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) 

208 

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. 

212 

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 

222 

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. 

226 

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()) 

231 

232 

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) 

241 

242 

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. 

246 

247 Beyond these, they take the [style keywords][manimgx.drawing.paint.Style]. 

248 """ 

249 

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).""" 

254 

255 

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. 

260 

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. 

265 

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. 

272 

273 Examples: 

274 ```python 

275 import manimgx as m 

276 

277 

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 """ 

290 

291 # a quad textured with the camera's view (a camera's view is a texture) 

292 

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 ) 

315 

316 def add_display_frame(self, **kwargs: "Unpack[FrameOptions]") -> Self: 

317 """Outline the picture: a surrounding rectangle, added as a submobject. 

318 

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 

325 

326 self.display_frame = SurroundingRectangle( 

327 self, **(self.default_display_frame_config | kwargs) 

328 ) 

329 return self.add(self.display_frame)