Extending the Simulator

The BlenderService API, as typically accessed through a BlenderClient instance, handles most rendering tasks. When you need finer control, subclass BlenderService to reach Blender’s internal bpy API.

Here we create a custom ExtendedService which allows for axis-aligned bounding box (AABB) calculations, and listing out any missing textures:

from pathlib import Path

import bpy
import numpy as np
from mathutils import Vector

from visionsim.simulate.blender import BlenderServer, BlenderService


class ExtendedService(BlenderService):
    def exposed_scene_aabb(self):
        aabb_min = np.array([np.inf, np.inf, np.inf])
        aabb_max = -np.array([np.inf, np.inf, np.inf])

        for obj in self.scene.objects:
            bbox = np.array(obj.bound_box)
            bbox_min = obj.matrix_world @ Vector(np.min(bbox, axis=0))
            bbox_max = obj.matrix_world @ Vector(np.max(bbox, axis=0))
            aabb_min = np.minimum(aabb_min, bbox_min)
            aabb_max = np.maximum(aabb_max, bbox_max)
        return aabb_min, aabb_max

    def exposed_missing_textures(self):
        paths = []

        for image in bpy.data.images.values():
            if image.source == "FILE" and not (path := Path(image.filepath_from_user()).resolve()).exists():
                paths.append(path)

        return paths


if __name__ == "__main__":
    server = BlenderServer(service=ExtendedService, port=0)
    server.start()

Pass the service’s location to BlenderClient.spawn as either a dotted module:ClassName path or a /path/to/service.py:ClassName file. The spawned Blender gets the same command as the default service, --python-use-system-env included:

with BlenderClient.spawn(service="my_package.services:ExtendedService", timeout=30) as client:
    client.initialize("cube.blend", "renders/")
    print(client.scene_aabb())

Note

A dotted path is imported inside Blender, which first executes the __init__ of every package on the way to the module. The blender runtime might not have your project’s dependencies installed and would otherwise fail, even when the service itself needs none of them. The file form is run as a script and never imports a package, exactly like handing the file to blender --python, so prefer it for a service that lives inside one. Give it an absolute path: the spawned Blender inherits the spawning process’s working directory.

Pass factory_startup=True when the render must not depend on the machine’s Blender preferences and startup file, and env=... to modify the environment the blender subprocess runs in.

The same arguments are available on BlenderServer.spawn, BlenderClients.spawn and BlenderClients.pool if you need to manage the process yourself or spawn several. Omitted, service defaults to the base BlenderService.

To connect to a service you started yourself, launch it manually and use BlenderClient.auto_connect:

blender --background --python-use-system-env --python examples/blender/extended_service.py
with BlenderClient.auto_connect(timeout=30) as client:
    client.initialize("cube.blend", "renders/")
    print(client.scene_aabb())

examples/blender/imu_preview_service.py and examples/blender/imu_preview.py are a fuller example of the same split: the service exposes a method that draws camera trajectories into the loaded scene, and the script spawns it through the same service file target and drives it as a client. The IMU tutorial walks through what it renders.


See also