The animation engine for agents: blazingly fast math and 3D videos with Manim's Python API, on a Rust GPU core.
Python
Validate environment images and retain lighting boundaries
Sina Atalay90cfed0a76e9
diff --git a/rust/engine/src/environment.rs b/rust/engine/src/environment.rsindex 63fc5465..57733690 100644--- a/rust/engine/src/environment.rs+++ b/rust/engine/src/environment.rs@@ -44,17 +44,34 @@ pub(crate) fn read_hdr(data: &[u8]) -> Result<(u32, u32, Vec<u8>), String> {["-Y", h, "+X", w] => (h.parse::<u32>().map_err(|e| e.to_string())?, w.parse::<u32>().map_err(|e| e.to_string())?),_ => return Err(format!("a Radiance file's orientation that is not \"-Y height +X width\": {size}")),};- let mut out = vec![0u8; (width * height * 4) as usize];+ if width == 0 || height == 0 {+ return Err("a Radiance picture's dimensions must be positive".into());+ }+ let length = (width as usize).checked_mul(height as usize).and_then(|n| n.checked_mul(4))+ .filter(|&n| n <= isize::MAX as usize).ok_or("a Radiance picture is too large to address")?;+ let row_bytes = length / height as usize;+ // A header is not evidence that its pixels exist. A flat picture needs all its+ // bytes; an RLE row needs its four-byte header and, for each of four components,+ // at least two encoded bytes per 127 decoded bytes (the longest repeated run).+ let minimum = if (8..0x8000).contains(&width) { (4 + 8 * width.div_ceil(127)) as usize * height as usize } else { length };+ if data.len() - at < minimum {+ return Err("a Radiance file ends early".into());+ }+ let mut out = vec![0u8; length];let byte = |at: &mut usize| -> Result<u8, String> {let b = *data.get(*at).ok_or("a Radiance file ends early")?;*at += 1;Ok(b)};for y in 0..height as usize {- let row = &mut out[y * width as usize * 4..(y + 1) * width as usize * 4];+ let row = &mut out[y * row_bytes..(y + 1) * row_bytes];let head = [data.get(at).copied(), data.get(at + 1).copied(), data.get(at + 2).copied()];if (8..0x8000).contains(&width) && head[0] == Some(2) && head[1] == Some(2) && head[2].is_some_and(|b| b & 0x80 == 0) {// run-length encoded: four header bytes, then each component's runs across the row+ let scanline = data.get(at..).and_then(|rest| rest.get(..4)).ok_or("a Radiance file ends early")?;+ if u16::from_be_bytes([scanline[2], scanline[3]]) as u32 != width {+ return Err("a Radiance scanline's width does not match its picture".into());+ }at += 4;for c in 0..4 {let mut x = 0;@@ -76,9 +93,9 @@ pub(crate) fn read_hdr(data: &[u8]) -> Result<(u32, u32, Vec<u8>), String> {}} else {// flat: four bytes a pixel- let bytes = data.get(at..at + row.len()).ok_or("a Radiance file ends early")?;+ let bytes = data.get(at..).and_then(|rest| rest.get(..row_bytes)).ok_or("a Radiance file ends early")?;row.copy_from_slice(bytes);- at += row.len();+ at += row_bytes;}}Ok((width, height, out))@@ -110,18 +127,22 @@ fn rgbe(c: [f64; 3]) -> [u8; 4] {pub(crate) const WIDEST: u32 = 4096;#[cfg(any(feature = "python", test))]-/// A picture no wider than `WIDEST`: each halving the average of four pixels' light.+/// A picture no wider than `WIDEST`: each halving averages the available pixels' light+/// in each 2x2 block, including an odd edge or a picture only one pixel high.pub(crate) fn narrowed(mut width: u32, mut height: u32, mut pixels: Vec<u8>) -> (u32, u32, Vec<u8>) {while width > WIDEST {- let (w, h) = (width / 2, height / 2);- let mut out = Vec::with_capacity((w * h * 4) as usize);+ let (w, h) = (width.div_ceil(2), height.div_ceil(2));+ let mut out = Vec::with_capacity(w as usize * h as usize * 4);for y in 0..h {for x in 0..w {let mut sum = [0.0; 3];+ let (columns, rows) = ((width - 2 * x).min(2), (height - 2 * y).min(2));+ let weight = 1.0 / (columns * rows) as f64;for (dx, dy) in [(0, 0), (1, 0), (0, 1), (1, 1)] {- let at = (((2 * y + dy) * width + 2 * x + dx) * 4) as usize;+ if dx >= columns || dy >= rows { continue; }+ let at = ((2 * y + dy) as usize * width as usize + (2 * x + dx) as usize) * 4;let l = light(&pixels[at..at + 4]);- (0..3).for_each(|c| sum[c] += l[c] / 4.0);+ (0..3).for_each(|c| sum[c] += l[c] * weight);}out.extend(rgbe(sum));}@@ -467,6 +488,70 @@ impl Prefilter {mod tests {use super::*;+ #[test]+ fn malformed_radiance_shapes_fail_without_panicking_or_allocating_the_header() {+ for (width, height) in [(0, 1), (1, 0), (65536, 16384), (8, 1 << 29), (u32::MAX, u32::MAX)] {+ let header = format!("#?RADIANCE\n\n-Y {height} +X {width}\n");+ assert!(read_hdr(header.as_bytes()).is_err(), "{width} x {height}");+ }+ }++ #[test]+ fn radiance_flat_and_encoded_rows_preserve_their_pixels() {+ let pixels: Vec<u8> = (0..64).collect();+ let mut flat = b"#?RADIANCE\n\n-Y 1 +X 16\n".to_vec();+ flat.extend_from_slice(&pixels);+ assert_eq!(read_hdr(&flat).unwrap(), (16, 1, pixels.clone()));+ let mut encoded = b"#?RADIANCE\n\n-Y 1 +X 16\n".to_vec();+ let start = encoded.len();+ encoded.extend_from_slice(&[2, 2, 0, 16]);+ for c in 0..4 {+ encoded.push(16);+ encoded.extend(pixels.iter().skip(c).step_by(4));+ }+ assert_eq!(read_hdr(&encoded).unwrap(), (16, 1, pixels));+ for end in 0..encoded.len() {+ assert!(read_hdr(&encoded[..end]).is_err(), "truncated at {end}");+ }+ encoded[start + 3] = 15;+ assert!(read_hdr(&encoded).unwrap_err().contains("width"));+ }++ #[test]+ fn the_shortest_radiance_runs_meet_the_allocation_bound() {+ for width in [8u32, 127, 128, 129, 32767] {+ let mut file = format!("#?RADIANCE\n\n-Y 2 +X {width}\n").into_bytes();+ let header = file.len();+ for _ in 0..2 {+ file.extend([2, 2, (width >> 8) as u8, width as u8]);+ for value in [128, 64, 32, 129] {+ let mut left = width;+ while left > 0 {+ let count = left.min(127);+ file.extend([128 + count as u8, value]);+ left -= count;+ }+ }+ }+ assert_eq!(file.len() - header, (4 + 8 * width.div_ceil(127)) as usize * 2);+ assert_eq!(read_hdr(&file).unwrap(), (width, 2, [128, 64, 32, 129].repeat(width as usize * 2)));+ }+ }++ #[test]+ fn narrowing_preserves_a_single_row_and_the_pixels_of_odd_edges() {+ let pixels = [128, 64, 32, 129].repeat(8192);+ let (w, h, out) = narrowed(8192, 1, pixels);+ assert_eq!((w, h), (4096, 1));+ assert_eq!(out, [128, 64, 32, 129].repeat(4096));+ let mut pixels = vec![0; 4097 * 3 * 4];+ pixels[4097 * 3 * 4 - 4..].copy_from_slice(&[128, 0, 0, 133]);+ let (w, h, out) = narrowed(4097, 3, pixels);+ assert_eq!((w, h), (2049, 2));+ assert!(out[..out.len() - 4].iter().all(|&b| b == 0));+ assert_eq!(&out[out.len() - 4..], &[128, 0, 0, 133]);+ }+#[cfg(feature = "render")]/// A uniform picture's diffuse light is its light alone, from every side: c0 is the light, the rest nothing.#[test]diff --git a/src/manimgx/mobjects/images.py b/src/manimgx/mobjects/images.pyindex 31be0d84..675148fc 100644--- a/src/manimgx/mobjects/images.py+++ b/src/manimgx/mobjects/images.py@@ -16,6 +16,7 @@ from manimgx.drawing.paint import (ManimColor,ParsableManimColor,Style,+ _Style,)from manimgx.mobject import MeshMobject@@ -31,11 +32,11 @@ class ImageMobject(MeshMobject):pixels make it.An image `scale_to_resolution` pixels tall (1080 unless given) is as tall as the- frame's short side, 8 scene units, and any other in proportion. Shown larger than its- pixels, the picture is reconstructed from them by `resampling_algorithm`: by default- a smooth cubic through every pixel; linear blends neighboring pixels; nearest shows- each pixel as a square of its color. Shown smaller, it is sampled, not averaged. The- mobject's opacity multiplies its pixels' own.+ frame's short side (8 scene units by default), and any other in proportion. Shown+ larger than its pixels, the picture is reconstructed from them by+ `resampling_algorithm`: by default a smooth cubic through every pixel; linear blends+ neighboring pixels; nearest shows each pixel as a square of its color. Shown smaller,+ it is sampled, not averaged. The mobject's opacity multiplies its pixels' own.Args:filename_or_array: The picture: an image file's path, the file's contents@@ -237,7 +238,7 @@ def _to_rgba(pixels: np.ndarray) -> np.ndarray:return pixels.astype(np.uint8)-class ImageCameraOptions(Style, total=False):+class ImageCameraOptions(_Style, total=False):"""A camera picture's keywords, for the scenes that pass them on: a[ZoomedScene][manimgx.ZoomedScene]'s display.diff --git a/src/manimgx/mobjects/lights.py b/src/manimgx/mobjects/lights.pyindex 94311a34..6ff6d721 100644--- a/src/manimgx/mobjects/lights.py+++ b/src/manimgx/mobjects/lights.py@@ -25,6 +25,7 @@ from typing import TYPE_CHECKING, ClassVar, Unpackimport numpy as npfrom manimgx import _engine+from manimgx.caches import forgetsfrom manimgx.constants import LEFT, ORIGIN, OUT, PI, RIGHT, UPfrom manimgx.drawing.paint import WHITE, Look, ManimColor, ParsableManimColorfrom manimgx.mobject import VectorizedPoint@@ -249,11 +250,12 @@ class Picture:_PICTURE_IDS = itertools.count(1) # (0: the studio; a view carries an id as a float32)-def _picture(path: str) -> Picture:- """The picture of a Radiance (.hdr) file at `path` (an absolute path), read once (by the- engine: halved until no wider than 4096)."""- width, height, rgbe = _engine.read_hdr(Path(path).read_bytes())+@forgets[email protected]_cache(maxsize=4)+def _picture(data: bytes) -> Picture:+ """A Radiance picture's immutable contents, decoded once while remembered (the engine+ halves it until no wider than 4096)."""+ width, height, rgbe = _engine.read_hdr(data)return Picture(next(_PICTURE_IDS), width, height, bytes(rgbe))@@ -310,9 +312,7 @@ class EnvironmentLight(Light):**kwargs: Unpack[Look],) -> None:# (None: the studio, which the engine makes)- self.picture = (- None if picture is None else _picture(str(Path(picture).resolve()))- )+ self.picture = None if picture is None else _picture(Path(picture).read_bytes())self.shadows = shadowssuper().__init__(ORIGIN, color, intensity, **kwargs)# its picture's right and up, a unit from its point: turned with itdiff --git a/tests/integration/test_environment_inputs.py b/tests/integration/test_environment_inputs.pynew file mode 100644index 00000000..beeed7e2--- /dev/null+++ b/tests/integration/test_environment_inputs.py@@ -0,0 +1,49 @@+"""New lights read current files; live lights own immutable decoded pictures."""++import os+from pathlib import Path++import numpy as np+from tests.integration.test_light import radiance_file++import manimgx as m+from manimgx.caches import clear+++def test_replacing_an_environment_preserves_existing_lights_only(+ tmp_path: Path,+) -> None:+ path = radiance_file(tmp_path / "room.hdr", np.full((2, 4), 0.25))+ original = m.EnvironmentLight(path).picture+ assert original is not None+ before = original.rgbe+ metadata = path.stat()+ radiance_file(path, np.full((2, 4), 0.5))+ os.utime(path, ns=(metadata.st_atime_ns, metadata.st_mtime_ns))+ assert path.stat().st_size == metadata.st_size+ current = m.EnvironmentLight(path).picture+ assert current is not None+ assert current.rgbe != before+ assert original.rgbe == before+++def test_identical_environment_contents_share_their_decoding(tmp_path: Path) -> None:+ first = radiance_file(tmp_path / "first.hdr", np.full((2, 4), 0.25))+ second = tmp_path / "second.hdr"+ second.write_bytes(first.read_bytes())+ assert m.EnvironmentLight(first).picture is m.EnvironmentLight(second).picture+++def test_forgetting_pictures_preserves_their_contents(tmp_path: Path) -> None:+ path = radiance_file(tmp_path / "room.hdr", np.full((2, 4), 0.25))+ original = m.EnvironmentLight(path).picture+ clear()+ current = m.EnvironmentLight(path).picture+ assert original is not None+ assert current is not None+ assert current is not original+ assert (current.width, current.height, current.rgbe) == (+ original.width,+ original.height,+ original.rgbe,+ )diff --git a/tests/integration/test_hdr.py b/tests/integration/test_hdr.pynew file mode 100644index 00000000..137dd628--- /dev/null+++ b/tests/integration/test_hdr.py@@ -0,0 +1,43 @@+"""Malformed Radiance dimensions report ordinary errors at the native decoder boundary."""++from pathlib import Path++import pytest++import manimgx as m+from manimgx import _engine+++ ("width", "height"),+ [(0, 1), (1, 0), (65536, 16384), (8, 2**29), (2**32 - 1, 2**32 - 1)],+)+def test_invalid_hdr_dimensions_are_value_errors(+ width: int, height: int, tmp_path: Path+) -> None:+ data = f"#?RADIANCE\n\n-Y {height} +X {width}\n".encode()+ with pytest.raises(ValueError, match="Radiance"):+ _engine.read_hdr(data)+ path = tmp_path / "invalid.hdr"+ path.write_bytes(data)+ with pytest.raises(ValueError, match="Radiance"):+ m.EnvironmentLight(path)+++def test_decoded_hdr_pixels_keep_their_bytes() -> None:+ pixels = bytes(range(64))+ header = b"#?RADIANCE\n\n-Y 1 +X 16\n"+ encoded = header + bytes([2, 2, 0, 16])+ for channel in range(4):+ encoded += bytes([16]) + pixels[channel::4]+ for data in (header + pixels, encoded):+ assert _engine.read_hdr(data) == (16, 1, pixels)+++def test_narrowing_keeps_a_single_row_and_the_last_odd_pixel() -> None:+ pixel = bytes([128, 64, 32, 129])+ data = b"#?RADIANCE\n\n-Y 1 +X 8192\n" + pixel * 8192+ assert _engine.read_hdr(data) == (4096, 1, pixel * 4096)+ edge = bytes([128, 0, 0, 133])+ data = b"#?RADIANCE\n\n-Y 3 +X 4097\n" + bytes(4097 * 3 * 4 - 4) + edge+ assert _engine.read_hdr(data) == (2049, 2, bytes(2049 * 2 * 4 - 4) + edge)diff --git a/tests/integration/test_light.py b/tests/integration/test_light.pyindex 69252404..9246eda7 100644--- a/tests/integration/test_light.py+++ b/tests/integration/test_light.py@@ -67,6 +67,27 @@ def linear(value: float) -> float:return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4+ ("light", "level"),+ [((0.0, 0.0, 1e8), 255), ((0.0, 0.0, -1e8), 64), ((0.0, 0.0, 0.0), 128)],+)+def test_a_surface_without_a_material_keeps_signed_camera_shading(+ light: tuple[float, float, float], level: int+) -> None:+ # Along the normal, shading adds 1/2; from behind, it subtracts 1/4. The distant+ # light makes the cosine round to exactly ±1 at every vertex: grey 128 becomes+ # clipped white 255 or round(128 - 255/4) = 64. A light in the plane adds nothing,+ # including at its coincident vertex, where the light has no direction.+ def build(scene: m.ThreeDScene) -> None:+ surface = plane(None).set_color("#808080")+ assert (surface.get_all_points() == m.ORIGIN).all(axis=1).any()+ scene.camera.light_source.move_to(light)+ scene.add(surface)+ scene.wait(0.1)++ assert (frames(build)[0] == level).all()++def test_a_white_matte_surface_facing_a_light_of_intensity_one_shows_white() -> None:def build(scene: m.ThreeDScene) -> None:scene.add(plane(), m.SunLight(5 * m.OUT, intensity=1.0))