pyblenderSDIC.BlenderExperiment#

class BlenderExperiment(Nb_frames: int = 1)[source]#

Bases: object

Represents a Blender experiment with a defined scene and objects.

The BlenderExperiment class provides methods to add and configure cameras, spot lights, and objects (mesh + material) in a Blender scene. The class also allows setting the properties of the scene such as resolution and pixel aspect ratio. Then the class provides methods to render the scene and save the rendered images.

The number of frames in the experiment can be set using the end_frame parameter. This parameters can not be updated after the experiment is created.

from pyblenderSDIC import BlenderExperiment

# Example instantiation
experiment = BlenderExperiment(Nb_frames=10)
Parameters:

Nb_frames (int, optional) – The number of frames for the experiment (default is 1).

_reset_blender() → None[source]#

Resets the Blender environment.

  • Removes all objects in the active scene.

  • Deletes all meshes, materials, textures, armatures, cameras, lights, and collections.

  • Initializes a new scene for the experiment.

  • Resets the 3D cursor to the origin.

  • Sets the start and end frames to 1.

add_camera(name: str, camera: Camera, frames: List[bool] | None = None) → None[source]#

Add a camera to the experiment.

The frames parameter indicates which frames the camera will be active. If None, the camera will be active for all frames. Else a list of booleans must be provided, where each boolean indicates if the camera is active for that frame.

# Example usage
experiment = BlenderExperiment(Nb_frames=10)
camera = Camera()
# Define the camera properties here
# ...
experiment.add_camera(name="Camera1", camera=camera, frames=[True, False, True, False, True, False, True, False, True, False])

Note

The name of the camera must be unique in the experiment and in Blender data. Furthemore, because Blender limits the name of the objects to 63 characters and pyblenderSDIC add prefixe for sub-dependant object of the camera, the name of the camera must be less than 50 characters.

See also

Parameters:

  • name (str) – The name of the camera with less than 50 characters.

  • camera (Camera) – The camera object to be added.

  • frames (List[bool], optional) – A list of booleans indicating which frames the camera will be active. If None, the camera will be active for all frames (default is None).

Raises:

  • TypeError – If name is not a string or camera is not an instance of Camera.

  • ValueError – If a camera with the same name already exists in the experiment or in Blender data. If the length of frames is not equal to the number of frames in the experiment (end_frame). If the camera is not completely defined.

  • Blender Details –

  • --------------- –

  • The camera is created in the Blender scene and linked to the experiment scene with the name {name}. –

add_mesh(name: str, mesh: TriangleMesh3D, frames: List[bool] | None = None) → None[source]#

Add a mesh to the experiment.

The mesh must be an instance of TriangleMesh3D.

The frames parameter indicates which frames the mesh will be active. If None, the mesh will be active for all frames. Else a list of booleans must be provided, where each boolean indicates if the mesh is active for that frame.

Note

The name of the mesh must be unique in the experiment and in Blender data. Furthemore, because Blender limits the name of the objects to 63 characters and pyblenderSDIC add prefixe for sub-dependant object of the mesh, the name of the mesh must be less than 50 characters.

# Example usage
experiment = BlenderExperiment(Nb_frames=10)
# Define the mesh properties here
# ...
mesh = TriangleMesh3D(vertices=..., triangles=...)
experiment.add_mesh(name="Mesh1", mesh=mesh, frames=[True, False, True, False, True, False, True, False, True, False])

See also

Parameters:

  • name (str) – The name of the mesh with less than 50 characters.

  • mesh (TriangleMesh3D) – The mesh object to be added. It must be an instance of TriangleMesh3D.

  • frames (List[bool], optional) – A list of booleans indicating which frames the mesh will be active. If None, the mesh will be active for all frames (default is None).

Raises:

  • TypeError – If name is not a string or mesh is not an instance of TriangleMesh3D.

  • ValueError – If a mesh with the same name already exists in the experiment or in Blender data. If the length of frames is not equal to the number of frames in the experiment (end_frame). If the mesh is not completely defined.

  • Blender Details –

  • --------------- –

  • The mesh is created in the Blender scene and linked to the experiment scene. –

  • The mesh name is set to the provided name. –

  • A material is created for the mesh with the name [pbSDIC]_{name}_mat. –

  • The material uses a Principled BSDF shader and is set to use_nodes = True. –

  • The material is located at the first index of the mesh data materials. –

  • A MixRGB node is created at the input of the Principled BSDF Base Color node. –

  • The MixRGB node name is set to [pbSDIC]_{name}_mbp for "Mix BaseColor Pattern". –

  • The first input of the MixRGB node is the default base color of the material (white). –

  • It can be setted to any color using the add_mesh_material method. –

  • The second input of the MixRGB node is the default pattern of the material (white). –

  • It can be setted to any pattern using the add_mesh_pattern method. –

  • The output of the MixRGB node is connected to the Base Color input of the Principled BSDF node. –

add_mesh_material(name: str, material: MaterialBSDF) → None[source]#

Add a material to the mesh.

The material must be an instance of MaterialBSDF.

# Example usage
experiment = BlenderExperiment(Nb_frames=10)
# Define the mesh properties here
# ...
mesh = TriangleMesh3D(points, cells_dict={"triangle": elements}, point_data={"uvmap": texture_coordinates})
experiment.set_mesh(name="Mesh1", mesh=mesh, frames=[True, False, True, False, True, False, True, False, True, False])
material = MaterialBSDF()
# Define the material properties here
# ...
experiment.add_mesh_material(name="Mesh1", material=material)

See also

Note

The material is not updated when the mesh is updated. To update the material, you must call this method again with the new material.

Parameters:

  • name (str) – The name of the mesh.

  • material (MaterialBSDF) – The material object to be added.

Raises:

  • TypeError – If name is not a string or material is not an instance of MaterialBSDF.

  • ValueError – If a mesh with the same name does not exist in the experiment or in Blender data.

add_mesh_pattern(name: str, pattern_path: str) → None[source]#

Add a pattern to the mesh material.

The pattern must be a valid image file path (e.g., PNG, JPEG). The pattern will be applied to the mesh material as a texture.

# Example usage
experiment = BlenderExperiment(Nb_frames=10)
# Define the mesh properties here
# ...
mesh = TriangleMesh3D(vertices=..., triangles=...)
mesh.uvmap = ...
experiment.add_mesh(name="Mesh1", mesh=mesh, frames=[True, False, True, False, True, False, True, False, True, False])
experiment.add_mesh_pattern(name="Mesh1", pattern_path="path/to/pattern.png")

Warning

The UV coordinates of the mesh must be defined in the TriangleMesh3D object. as “uvmap” in the point_data dictionary.

See also

Parameters:

  • name (str) – The name of the mesh.

  • pattern_path (str) – The path to the pattern image file.

Raises:

  • TypeError – If name is not a string or pattern_path is not a string.

  • ValueError – If a mesh with the same name does not exist in the experiment or in Blender data. If the pattern path is not valid or the image format is not supported. If the mesh does not have a UVMAP defined.

  • Blender Details –

  • --------------- –

  • A uv_layer is created for the mesh and the UVMAP is set to the texture coordinates defined in the mesh. –

  • The uv_layer is named [pbSDIC]_{name}_uvm. –

  • A node is created in the material node tree to load the image texture. –

  • The node is named [pbSDIC]_{name}_imt. –

  • This node is in CLIP mode to avoid stretching the image. –

  • The color output of the image texture node is connected to the second input of the MixRGB node. –

  • The MixRGB node is connected to the Base Color input of the Principled BSDF node in multiply mode. –

add_spotlight(name: str, spotlight: SpotLight, frames: List[bool] | None = None) → None[source]#

Add a spotlight to the experiment.

The spotlight must be an instance of SpotLight.

Note

The name of the light must be unique in the experiment and in Blender data. Furthemore, because Blender limits the name of the objects to 63 characters and pyblenderSDIC add prefixe for sub-dependant object of the light, the name of the light must be less than 50 characters.

# Example usage
experiment = BlenderExperiment(Nb_frames=10)
spotlight = SpotLight()
# Define the SpotLight properties here
# ...
experiment.add_spotlight(name="Spotlight1", spotlight=SpotLight, frames=[True, False, True, False, True, False, True, False, True, False])

See also

Parameters:

  • name (str) – The name of the spotlight with less than 50 characters.

  • spotlight (SpotLight) – The spotlight object to be added.

  • frames (List[bool], optional) – A list of booleans indicating which frames the spotlight will be active. If None, the spotlight will be active for all frames (default is None).

Raises:

  • TypeError – If name is not a string or spotlight is not an instance of SpotLight.

  • ValueError – If a spotlight with the same name already exists in the experiment or in Blender data. If the length of frames is not equal to the number of frames in the experiment (end_frame).

change_mesh_pattern(name: str, pattern_path: str) → None[source]#

Change the pattern of the mesh material.

The pattern must be a valid image file path (e.g., PNG, JPEG). The pattern will be applied to the mesh material as a texture.

# Example usage
experiment = BlenderExperiment(Nb_frames=10)
# Define the mesh properties here
# ...
mesh = TriangleMesh3D(points, cells_dict={"triangle": elements}, point_data={"uvmap": texture_coordinates})
experiment.add_mesh(name="Mesh1", mesh=mesh, frames=[True, False, True, False, True, False, True, False, True, False])
experiment.add_mesh_pattern(name="Mesh1", pattern_path="path/to/pattern.png")
experiment.change_mesh_pattern(name="Mesh1", pattern_path="path/to/new_pattern.png")

See also

Parameters:

  • name (str) – The name of the mesh.

  • pattern_path (str) – The path to the new pattern image file.

Raises:

  • TypeError – If name is not a string or pattern_path is not a string.

  • ValueError – If a mesh with the same name does not exist in the experiment or in Blender data. If the pattern path is not valid or the image format is not supported.

get_active_camera() → str[source]#

Get the name of the active camera.

Returns:

The name of the active camera.

Return type:

str

Raises:

ValueError – If no active camera is set.

get_camera(name: str) → Tuple[Camera, None][source]#

Get the camera object and its Blender object.

Parameters:

name (str) – The name of the camera to retrieve.

Returns:

A tuple containing the Camera object and its corresponding Blender object.

Return type:

Tuple[Camera, Object]

get_camera_frames(name: str) → List[bool][source]#

Get the frames for which the camera is active.

Parameters:

name (str) – The name of the camera.

Returns:

A list of booleans indicating which frames the camera is active.

Return type:

List[bool]

Raises:

  • TypeError – If name is not a string.

  • ValueError – If a camera with the same name does not exist in the experiment or in Blender data.

get_camera_names() → List[str][source]#

Get the names of all cameras in the experiment.

Returns:

A list of camera names.

Return type:

List[str]

get_mesh(name: str) → Tuple[TriangleMesh3D, None][source]#

Get the mesh object and its Blender object.

Parameters:

name (str) – The name of the mesh to retrieve.

Returns:

A tuple containing the TriangleMesh3D object and its corresponding Blender object.

Return type:

Tuple[TriangleMesh3D, Object]

get_mesh_frames(name: str) → List[bool][source]#

Get the frames for which the mesh is active.

Parameters:

name (str) – The name of the mesh.

Returns:

A list of booleans indicating which frames the mesh is active.

Return type:

List[bool]

Raises:

  • TypeError – If name is not a string.

  • ValueError – If a mesh with the same name does not exist in the experiment or in Blender data.

get_mesh_names() → List[str][source]#

Get the names of all meshes in the experiment.

Returns:

A list of mesh names.

Return type:

List[str]

get_spotlight(name: str) → Tuple[SpotLight, None][source]#

Get the spotlight object and its Blender object.

Parameters:

name (str) – The name of the spotlight to retrieve.

Returns:

A tuple containing the SpotLight object and its corresponding Blender object.

Return type:

Tuple[SpotLight, Object]

get_spotlight_frames(name: str) → List[bool][source]#

Get the frames for which the spotlight is active.

Parameters:

name (str) – The name of the spotlight.

Returns:

A list of booleans indicating which frames the spotlight is active.

Return type:

List[bool]

Raises:

  • TypeError – If name is not a string.

  • ValueError – If a spotlight with the same name does not exist in the experiment or in Blender data.

remove_camera(name: str) → None[source]#

Remove a camera from the experiment.

Parameters:

name (str) – The name of the camera to remove.

Raises:

  • TypeError – If name is not a string.

  • ValueError – If a camera with the same name does not exist in the experiment or in Blender data.

remove_mesh(name: str) → None[source]#

Remove a mesh from the experiment.

Parameters:

name (str) – The name of the mesh to remove.

Raises:

  • TypeError – If name is not a string.

  • ValueError – If a mesh with the same name does not exist in the experiment or in Blender data.

  • Blender Details –

  • --------------- –

  • When removing a mesh, the following actions are performed: –

  • - The mesh {name} is removed from the Blender scene. –

  • - The material [pbSDIC]_{name}_mat is removed from the Blender data. –

  • - The MixRGB node [pbSDIC]_{name}_mbp is removed from the material node tree. –

  • - The uv_layer [pbSDIC]_{name}_uvm is removed from the mesh data. –

  • - The node texture [pbSDIC]_{name}_imt is removed from the material node tree. –

remove_spotlight(name: str) → None[source]#

Remove a spotlight from the experiment.

Parameters:

name (str) – The name of the spotlight to remove.

Raises:

  • TypeError – If name is not a string.

  • ValueError – If a spotlight with the same name does not exist in the experiment or in Blender data.

render(output_path: str, output_format: str = 'TIFF', color_mode: str = 'BW', color_depth: str = '8', N_samples: int = 200) → None[source]#

Render the experiment scene.

Parameters:

  • output_path (str) – The path to save the rendered image.

  • output_format (str, optional) – The output format of the rendered image (default is “TIFF”).

  • color_mode (str, optional) – The color mode of the rendered image (default is “BW”).

  • color_depth (str, optional) – The color depth of the rendered image (default is “8”).

  • N_samples (int, optional) – The number of samples for rendering (default is 200).

Raises:

  • TypeError – If name or output_path is not a string.

  • ValueError – If the output format is not supported. If the frame or the camera is not set.

set_active_camera(name: str) → None[source]#

Set the active camera for the experiment.

Parameters:

name (str) – The name of the camera to set as active.

Raises:

  • TypeError – If name is not a string.

  • ValueError – If a camera with the same name does not exist in the experiment or in Blender data.

set_active_frame(frame: int) → None[source]#

Set the current frame of the Blender scene.

Parameters:

frame (int) – The frame number to set.

Raises:

  • TypeError – If frame is not an integer.

  • ValueError – If frame is out of range.

set_camera_frames(name: str, frames: List[bool] | None = None) → None[source]#

Set the frames for which the camera will be active. If None, the camera will be active for all frames. Else a list of booleans must be provided, where each boolean indicates if the camera is active for that frame.

Parameters:

  • name (str) – The name of the camera.

  • frames (List[bool], optional) – A list of booleans indicating which frames the camera will be active. If None, the camera will be active for all frames (default is None).

Raises:

  • TypeError – If name is not a string or frames is not a list of booleans.

  • ValueError – If a camera with the same name does not exist in the experiment or in Blender data. If the length of frames is not equal to the number of frames in the experiment (end_frame).

set_default_background() → None[source]#

Set the default background for the experiment scene.

set_mesh_frames(name: str, frames: List[bool] | None = None) → None[source]#

Set the frames for which the mesh will be active. If None, the mesh will be active for all frames. Else a list of booleans must be provided, where each boolean indicates if the mesh is active for that frame.

Parameters:

  • name (str) – The name of the mesh.

  • frames (List[bool], optional) – A list of booleans indicating which frames the mesh will be active. If None, the mesh will be active for all frames (default is None).

Raises:

  • TypeError – If name is not a string or frames is not a list of booleans.

  • ValueError – If a mesh with the same name does not exist in the experiment or in Blender data. If the length of frames is not equal to the number of frames in the experiment (end_frame).

set_spotlight_frames(name: str, frames: List[bool] | None = None) → None[source]#

Set the frames for which the spotlight will be active. If None, the spotlight will be active for all frames. Else a list of booleans must be provided, where each boolean indicates if the spotlight is active for that frame.

Parameters:

  • name (str) – The name of the spotlight.

  • frames (List[bool], optional) – A list of booleans indicating which frames the spotlight will be active. If None, the spotlight will be active for all frames (default is None).

Raises:

  • TypeError – If name is not a string or frames is not a list of booleans.

  • ValueError – If a spotlight with the same name does not exist in the experiment or in Blender data. If the length of frames is not equal to the number of frames in the experiment (end_frame).

update_camera(name: str) → None[source]#

Update the camera properties in the Blender scene. This method must be called after updating the camera properties in the Camera object.

# Example usage
experiment = BlenderExperiment(Nb_frames=10)
camera = Camera()
# Define the camera properties here
# ...
experiment.add_camera(name="Camera1", camera=camera, frames=[True, False, True, False, True, False, True, False, True, False])
# Update some properties of the camera here
# ...
experiment.update_camera(name="Camera1") # To set active the modifications in the Blender scene
Parameters:

name (str) – The name of the camera to update.

update_mesh(name: str) → None[source]#

Update the mesh properties in the Blender scene. This method must be called after updating the mesh properties in the TriangleMesh3D object.

# Example usage
experiment = BlenderExperiment(Nb_frames=10)
# Define the mesh properties here
# ...
mesh = TriangleMesh3D(points, cells_dict={"triangle": elements}, point_data={"uvmap": texture_coordinates})
experiment.add_mesh(name="Mesh1", mesh=mesh, frames=[True, False, True, False, True, False, True, False, True, False])
# Update some nodes of the mesh here
# ...
experiment.update_mesh(name="Mesh1") # To set active the modifications in the Blender scene

Note

If a pattern is setted to the mesh, the uvmap are also updated.

Warning

The number of nodes must be unchanged !!!

Furthermore, this method does not update the material properties of the mesh and the pattern image:

Parameters:

name (str) – The name of the mesh to update.

update_scene() → None[source]#

Update the Blender scene. This method must be called after adding or modifying any objects in the scene.

update_spotlight(name: str) → None[source]#

Update the spotlight properties in the Blender scene. This method must be called after updating the spotlight properties in the SpotLight object.

# Example usage
experiment = BlenderExperiment(Nb_frames=10)
spotlight = SpotLight()
# Define the SpotLight properties here
# ...
experiment.add_spotlight(name="Spotlight1", spotlight=spotlight, frames=[True, False, True, False, True, False, True, False, True, False])
# Update some nodes of the spotlight here
# ...
experiment.update_spotlight(name="Spotlight1") # To set active the modifications in the Blender scene

Warning

This method does not update the material properties of the spotlight. Only the position and rotation are updated. The number of nodes mustnot be changed.

Parameters:

name (str) – The name of the spotlight to update.