Skip to content

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.rs
index 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.py
index 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.py
index 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, Unpack
import numpy as np
from manimgx import _engine
+from manimgx.caches import forgets
from manimgx.constants import LEFT, ORIGIN, OUT, PI, RIGHT, UP
from manimgx.drawing.paint import WHITE, Look, ManimColor, ParsableManimColor
from 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 = shadows
super().__init__(ORIGIN, color, intensity, **kwargs)
# its picture's right and up, a unit from its point: turned with it
diff --git a/tests/integration/test_environment_inputs.py b/tests/integration/test_environment_inputs.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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))