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
Development for the editable install and the test suite.
Architecture for how the client/server split works.