Add renderer.animation

Author: kostrykin

docs/carna.rst

@@ -10,18 +10,41 @@ Example
 These can be used to, for example, quickly assemble a scene of multiple objects, and then render it into a NumPy array:
 
 .. literalinclude:: ../test/test_integration.py
-   :start-after: # .. OpaqueRenderingStage: example-start
-   :end-before: # .. OpaqueRenderingStage: example-end
+   :start-after: # .. OpaqueRenderingStage: example-setup-start
+   :end-before: # .. OpaqueRenderingStage: example-setup-end
    :dedent: 8
 
 Note on ``GEOMETRY_TYPE_OPAQUE``: A *geometry type* is an arbitrary integer constant, that establishes a relation
 between the geometry nodes of a scene graph, and the corresponding rendering stages (see below for details).
 
+It is very easy to just render the scene into a NumPy array:
+
+.. literalinclude:: ../test/test_integration.py
+   :start-after: # .. OpaqueRenderingStage: example-single-frame-start
+   :end-before: # .. OpaqueRenderingStage: example-single-frame-end
+   :dedent: 8
+
 This is the image ``array`` rendered in the example:
 
 .. image:: ../test/results/expected/test_integration.OpaqueRenderingStage.test.png
    :width: 400
 
+However, it is much easier to visually grasp the information in a 3D scene by looking at it from different angles. For
+this reason, there is a set of convenience functions that fascilitates creating animations, by rendering multiple
+frames at once:
+
+.. literalinclude:: ../test/test_integration.py
+   :start-after: # .. OpaqueRenderingStage: example-animation-start
+   :end-before: # .. OpaqueRenderingStage: example-animation-end
+   :dedent: 8
+
+In this example, the camera is rotated around the *center of the scene* (more precisely: around it's parent node, that
+happens to be the ``root`` node of the scene). The scene is rendered from 50 different angles. For each angle, the
+result is a NumPy array, that is stored in the list of ``frames``. This is our example animation:
+
+.. image:: ../test/results/expected/test_integration.OpaqueRenderingStage.test__animated.png
+   :width: 400
+
 Geometry Types
 --------------
 

environment.yml

@@ -17,4 +17,8 @@ dependencies:
   - pyyaml
   - setuptools
   - matplotlib-base  # for tests
-  - scipy  # for tests
+  - scipy  # for tests
+  - pip
+  - pip:
+    - numpngw ==0.1.4  # for tests and docs (writes APNG)
+    - apng ==0.3.4  # for tests and docs (reads APNG)

misc/py.py

@@ -1,5 +1,10 @@
 import re
-from typing import Iterable
+from typing import (
+    Callable,
+    Iterable,
+    Literal,
+    Sequence,
+)
 
 import numpy as np
 
@@ -9,6 +14,27 @@
 import carna.helpers
 
 
+AxisLiteral = Literal['x', 'y', 'z']
+AxisHint = AxisLiteral | tuple[float, float, float] | list[float, float, float]
+
+
+def _resolve_axis_hint(axis: AxisHint) -> tuple[float, float, float]:
+    if isinstance(axis, str):
+        match axis:
+            case 'x':
+                return (1, 0, 0)
+            case 'y':
+                return (0, 1, 0)
+            case 'z':
+                return (0, 0, 1)
+            case _:
+                raise ValueError(f'Invalid axis hint: {axis}')
+    elif len(axis) == 3:
+        return tuple(axis)
+    else:
+        raise ValueError(f'Invalid axis hint: {axis}')
+
+
 def _camel_to_snake(name):
     s = re.sub(r'(.)([A-Z][a-z]+)', r'\1_\2', name)
     return re.sub(r'([a-z0-9])([A-Z])', r'\1_\2', s).lower()
@@ -189,6 +215,38 @@ def frustum(self, fov: float, z_near: float, z_far: float) -> np.ndarray:
         ...
 
 
+class animation:
+    """
+    Create an animation that can be rendered.
+
+    Arguments:
+        step: Function that is called for each frame of the animation. The function is called with a single
+            argument `t`, which is a float in the range [0, 1]. The function should modify the scene in place.
+        n_frames: Number of frames to be rendered.
+    """
+
+    def __init__(self, step_functions: list[Callable[[float], None]], n_frames: int = 25):
+        self.step_functions = step_functions
+        self.n_frames = n_frames
+
+    def render(self, r: renderer, *args, **kwargs) -> Iterable[np.ndarray]:
+        for t in np.linspace(0, 1, num=self.n_frames):
+            for step in self.step_functions:
+                step(t)
+            yield r.render(*args, **kwargs)
+
+    @staticmethod
+    def rotate_local(spatial: carna.base.Spatial, axis: AxisHint = 'y') -> Callable[[float], None]:
+        """
+        Create a step function for rotating an object's local coordinate system.
+        """
+        base_transform = spatial.local_transform
+        axis = _resolve_axis_hint(axis)
+        def step(t: float):
+            spatial.local_transform = carna.math.rotation(axis, radians=2 * np.pi * t) @ base_transform
+        return step
+
+
 def volume(
         geometry_type: int,
         array: np.ndarray,

src/py/presets.cpp

@@ -103,13 +103,13 @@ PYBIND11_MODULE( presets, m )
         .doc() = R"(Implements rendering stage that renders opaque meshes.
 
         .. literalinclude:: ../test/test_integration.py
-           :start-after: # .. OpaqueRenderingStage: example-start
-           :end-before: # .. OpaqueRenderingStage: example-end
+           :start-after: # .. OpaqueRenderingStage: example-setup-start
+           :end-before: # .. OpaqueRenderingStage: example-setup-end
            :dedent: 8
 
-        This is the image ``array`` rendered in the example:
+        Rendering the scene as an animation:
 
-        .. image:: ../test/results/expected/test_integration.OpaqueRenderingStage.test.png
+        .. image:: ../test/results/expected/test_integration.OpaqueRenderingStage.test__animated.png
            :width: 400)";
 
     /* VolumeRenderingStage
@@ -156,13 +156,13 @@ PYBIND11_MODULE( presets, m )
         .doc() = R"(Renders 3D masks.
 
         .. literalinclude:: ../test/test_integration.py
-           :start-after: # .. MaskRenderingStage: example-start
-           :end-before: # .. MaskRenderingStage: example-end
+           :start-after: # .. MaskRenderingStage: example-setup-start
+           :end-before: # .. MaskRenderingStage: example-setup-end
            :dedent: 8
 
-        This is the image ``array`` rendered in the example:
+        Rendering the scene as an animation:
 
-        .. image:: ../test/results/expected/test_integration.MaskRenderingStage.test.png
+        .. image:: ../test/results/expected/test_integration.MaskRenderingStage.test__animated.png
            :width: 400)";
 
 /*

test/results/expected/test_integration.MaskRenderingStage.test__animated.png

@@ -79,8 +79,8 @@ def test__render(self):
 
 class OpaqueRenderingStage(testsuite.CarnaRenderingTestCase):
 
-    def test(self):
-        # .. OpaqueRenderingStage: example-start
+    def setUp(self):
+        # .. OpaqueRenderingStage: example-setup-start
         GEOMETRY_TYPE_OPAQUE = 1
 
         # Create and configure frame renderer
@@ -119,19 +119,45 @@ def test(self):
             projection=r.frustum(fov=np.pi / 2, z_near=1, z_far=1e3),
             local_transform=carna.math.translation(0, 0, 250),
         )
+        # .. OpaqueRenderingStage: example-setup-end
 
-        # Render scene
+        self.r, self.camera = r, camera
+
+    def test(self):
+        r, camera = self.r, self.camera
+
+        # .. OpaqueRenderingStage: example-single-frame-start
         array = r.render(camera)
-        # .. OpaqueRenderingStage: example-end
+        # .. OpaqueRenderingStage: example-single-frame-end
 
         # Verify result
         self.assert_image_almost_expected(array)
 
+    def test__animated(self):
+        r, camera = self.r, self.camera
+
+        # Render the scene once
+        # .. OpaqueRenderingStage: example-animation-start
+        # Define animation
+        animation = carna.animation(
+            [
+                carna.animation.rotate_local(camera)
+            ],
+            n_frames=50,
+        )
+
+        # Render animation
+        frames = list(animation.render(r, camera))
+        # .. OpaqueRenderingStage: example-animation-end
+
+        # Verify result
+        self.assert_image_almost_expected(np.array(frames))
+
 
 class MaskRenderingStage(testsuite.CarnaRenderingTestCase):
 
-    def test(self):
-        # .. MaskRenderingStage: example-start
+    def setUp(self):
+        # .. MaskRenderingStage: example-setup-start
         GEOMETRY_TYPE_VOLUME = 2
 
         # Create and configure frame renderer
@@ -158,10 +184,32 @@ def test(self):
             projection=r.frustum(fov=np.pi / 2, z_near=1, z_far=500),
             local_transform=carna.math.translation(0, 0, 100),
         )
+        # .. MaskRenderingStage: example-setup-end
+
+        self.r, self.camera = r, camera
+
+    def test(self):
+        r, camera = self.r, self.camera
 
         # Render scene
         array = r.render(camera)
-        # .. MaskRenderingStage: example-end
 
         # Verify result
-        self.assert_image_almost_expected(array)
+        self.assert_image_almost_expected(array)
+
+    def test__animated(self):
+        r, camera = self.r, self.camera
+
+        # Define animation
+        animation = carna.animation(
+            [
+                carna.animation.rotate_local(camera)
+            ],
+            n_frames=50,
+        )
+
+        # Render animation
+        frames = list(animation.render(r, camera))
+
+        # Verify result
+        self.assert_image_almost_expected(np.array(frames))

test/results/expected/test_integration.OpaqueRenderingStage.test__animated.png

@@ -1,3 +1,4 @@
+import io
 import pathlib
 import unittest
 
@@ -6,6 +7,45 @@
 
 import matplotlib.pyplot as plt
 import numpy as np
+from apng import APNG
+from numpngw import write_apng
+from PIL import Image
+
+
+def _imread(path: str) -> np.ndarray:
+    """
+    Reads a PNG as a `YXC` array, and APNG as a `TYXC` array.
+    """
+
+    def read_png_frame(buf) -> np.ndarray:
+        with Image.open(io.BytesIO(buf)) as im:
+            array = np.array(im)
+            array = array[:, :, :3]  # Ignore alpha channel if present
+            return array
+
+    im = APNG.open(path)
+    array = np.array(
+        [
+            read_png_frame(frame[0].to_bytes())
+            for frame in im.frames
+        ]
+    )
+
+    # Convert `TYXC` to `YXC` format (APNG -> PNG)
+    if array.shape[0] == 1 and array.ndim == 4:
+        array = array[0]
+
+    return array
+
+
+def _imsave(path: str, array: np.ndarray):
+    if array.ndim == 4:
+
+        # Palette APNG cannot be read proplery by the apng library
+        write_apng(path, array, delay=40, use_palette=False)
+
+    else:
+        plt.imsave(path, array)
 
 
 class CarnaTestCase(unittest.TestCase):
@@ -17,11 +57,10 @@ class CarnaRenderingTestCase(CarnaTestCase):
 
     def assert_image_almost_equal(self, actual, expected, decimal=5):
         if isinstance(actual, str):
-            actual = plt.imread(actual)
+            actual = _imread(actual)
         if isinstance(expected, str):
             expected = pathlib.Path('test/results/expected') / expected
-            expected = plt.imread(str(expected))
-            expected = expected[:, :, :3]  # Ignore alpha channel if present
+            expected = _imread(str(expected))
             if np.issubdtype(expected.dtype, np.floating):
                 expected = (expected * 255).astype(np.uint8)
         np.testing.assert_array_almost_equal(actual, expected, decimal=decimal)
@@ -33,6 +72,6 @@ def assert_image_almost_expected(self, actual, **kwargs):
         except:
             actual_path = pathlib.Path('test/results/actual') / f'{expected}'
             actual_path.parent.mkdir(parents=True, exist_ok=True)
-            plt.imsave(actual_path, actual)
+            _imsave(actual_path, actual)
             print(f'Test result was written to: {actual_path.resolve()}')
             raise