blenderproc.renderer package

Module contents

blenderproc.renderer.enable_depth_output(activate_antialiasing, output_dir=None, file_prefix='depth_', output_key='depth', antialiasing_distance_max=None, convert_to_distance=False)

Enables writing depth images.

Depth images will be written in the form of .exr files during the next rendering.

Parameters:

• activate_antialiasing (bool) – If this is True the final image will be antialiased

• output_dir (Optional[str]) – The directory to write files to, if this is None the temporary directory is used.

• file_prefix (str) – The prefix to use for writing the files.

• output_key (str) – The key to use for registering the depth output.

• antialiasing_distance_max (Optional[float]) – Max distance in which the distance is measured. Only if activate_antialiasing is True.

• convert_to_distance (bool) – If this is true, while loading a postprocessing step is executed to convert this depth image to a distance image

blenderproc.renderer.enable_diffuse_color_output(output_dir=None, file_prefix='diffuse_', output_key='diffuse')

Enables writing diffuse color (albedo) images.

Diffuse color images will be written in the form of .png files during the next rendering.

Parameters:

• output_dir (Optional[str]) – The directory to write files to, if this is None the temporary directory is used.

• file_prefix (str) – The prefix to use for writing the files.

• output_key (str) – The key to use for registering the diffuse color output.

blenderproc.renderer.enable_distance_output(activate_antialiasing, output_dir=None, file_prefix='distance_', output_key='distance', antialiasing_distance_max=None, convert_to_depth=False)

Enables writing distance images.

Parameters:

• activate_antialiasing (bool) – If this is True the final image will be anti-aliased

• output_dir (Optional[str]) – The directory to write files to, if this is None the temporary directory is used.

• file_prefix (str) – The prefix to use for writing the files.

• output_key (str) – The key to use for registering the distance output.

• antialiasing_distance_max (Optional[float]) – Max distance in which the distance is measured. Resolution decreases antiproportionally. Only if activate_antialiasing is True.

• convert_to_depth (bool) – If this is true, while loading a postprocessing step is executed to convert this distance image to a depth image

blenderproc.renderer.enable_experimental_features()

Enables experimental cycles features.

blenderproc.renderer.enable_motion_blur(motion_blur_length=0.5, rolling_shutter_type='NONE', rolling_shutter_length=0.1)

Enables motion blur and sets rolling shutter.

Parameters:

• motion_blur_length (float) – Time taken in frames between shutter open and close.

• rolling_shutter_type (str) – Type of rolling shutter effect. If “NONE”, rolling shutter is disabled.

• rolling_shutter_length (float) – Scanline “exposure” time for the rolling shutter effect.

blenderproc.renderer.enable_normals_output(output_dir=None, file_prefix='normals_', output_key='normals')

Enables writing normal images.

Normal images will be written in the form of .exr files during the next rendering.

Parameters:

• output_dir (Optional[str]) – The directory to write files to, if this is None the temporary directory is used.

• file_prefix (str) – The prefix to use for writing the files.

• output_key (str) – The key to use for registering the normal output.

blenderproc.renderer.enable_segmentation_output(map_by='category_id', default_values=None, pass_alpha_threshold=0.05, output_dir=None, file_prefix='segmap_', output_key='segmap')

Enables segmentation output by certain keys.

The key instances is used, if a mapping of every object in the scene to an integer is requested. These integers are assigned randomly and do not follow any system. They are consisted for one rendering call.

By default, the custom property category_id is used. It has to be set for every visible object in the scene, including the background (world). One can provide a default_value for it to avoid errors: {“category_id”: 0}.

Map by keys can be all custom properties or the attributes of an object such as location or name. If the value can not be stored in the image itself an instance image has to be generated. The output then will contain a dictionary mapping the instance ids to the attributes of the objects.

Parameters:

• map_by (Union[str, List[str]]) – Map by keys, either a single str or a list of str.

• default_values (Optional[Dict[str, Any]]) – A dictionary offering a default value for objects which do not provide a value for a certain key

• pass_alpha_threshold (float) – This alpha threshold is used to decide which object to use a low value means that an object has to be nearly completely transparent to be considered transparent, while materials such as frosted class with an alpha value of 0.5 would be considered opaque

• output_dir (Optional[str]) – The temporary output dir in which the resulting .exr images are saved

• file_prefix (str) – The prefix to use for writing the files.

• output_key (str) – The key to use for registering the segmentation output.

blenderproc.renderer.map_file_format_to_file_ending(file_format)

Returns the files endings for a given blender output format.

Parameters:

file_format (str) – The blender file format.

Return type:

str

Returns:

The file ending.

blenderproc.renderer.render(output_dir=None, file_prefix='rgb_', output_key='colors', load_keys=None, return_data=True, keys_with_alpha_channel=None, verbose=False)

Render all frames.

This will go through all frames from scene.frame_start to scene.frame_end and render each of them.

Parameters:

• output_dir (Optional[str]) – The directory to write files to, if this is None the temporary directory is used. The temporary directory is usually in the shared memory (only true for linux).

• file_prefix (str) – The prefix to use for writing the images.

• output_key (Optional[str]) – The key to use for registering the output.

• load_keys (Optional[Set[str]]) – Set of output keys to load when available

• return_data (bool) – Whether to load and return generated data.

• keys_with_alpha_channel (Optional[Set[str]]) – A set containing all keys whose alpha channels should be loaded.

• verbose (bool) – If True, more details about the rendering process are printed.

Return type:

Dict[str, Union[ndarray, List[ndarray]]]

Returns:

dict of lists of raw renderer output. Keys can be ‘distance’, ‘colors’, ‘normals’

blenderproc.renderer.render_nocs(output_dir=None, file_prefix='nocs_', output_key='nocs', return_data=True, verbose=False)

Renders the Normalized Object Coordinate Space (NOCS).

Colors each object based on its local coordinates. The coordinates [-1, 1] are mapped into the [0, 1] colorspace. It is therefore, recommended that all local vertex coordinates are in range [-1, 1]. The world background is rendered transparent.

Parameters:

• output_dir (Optional[str]) – The directory to write images to. If None is given, the temp dir is used.

• file_prefix (str) – The prefix to use for writing the images.

• output_key (str) – The key to use for registering the output.

• return_data (bool) – Whether to load and return generated data.

• verbose (bool) – If True, more details about the rendering process are printed.

Return type:

Dict[str, List[ndarray]]

Returns:

A dict containing one entry “nocs” which points to the list of rendered frames.

blenderproc.renderer.render_optical_flow(output_dir=None, temp_dir=None, get_forward_flow=True, get_backward_flow=True, blender_image_coordinate_style=False, forward_flow_output_file_prefix='forward_flow_', forward_flow_output_key='forward_flow', backward_flow_output_file_prefix='backward_flow_', backward_flow_output_key='backward_flow', return_data=True, verbose=False)

Renders the optical flow (forward and backward) for all frames.

Parameters:

• output_dir (Optional[str]) – The directory to write images to.

• temp_dir (Optional[str]) – The directory to write intermediate data to.

• get_forward_flow (bool) – Whether to render forward optical flow.

• get_backward_flow (bool) – Whether to render backward optical flow.

• blender_image_coordinate_style (bool) – Whether to specify the image coordinate system at the bottom left (blender default; True) or top left (standard convention; False).

• forward_flow_output_file_prefix (str) – The file prefix that should be used when writing forward flow to a file.

• forward_flow_output_key (str) – The key which should be used for storing forward optical flow values.

• backward_flow_output_file_prefix (str) – The file prefix that should be used when writing backward flow to a file.

• backward_flow_output_key (str) – The key which should be used for storing backward optical flow values.

• return_data (bool) – Whether to load and return generated data.

• verbose (bool) – If True, more details about the rendering process are printed.

Return type:

Dict[str, Union[ndarray, List[ndarray]]]

Returns:

dict of lists of raw renderer outputs. Keys can be ‘forward_flow’, ‘backward_flow’

blenderproc.renderer.render_segmap(output_dir=None, temp_dir=None, map_by='class', default_values=None, file_prefix='segmap_', output_key='segmap', segcolormap_output_file_prefix='instance_attribute_map_', segcolormap_output_key='segcolormap', use_alpha_channel=False, render_colorspace_size_per_dimension=2048)

Renders segmentation maps for all frames

Parameters:

• output_dir (Optional[str]) – The directory to write images to.

• temp_dir (Optional[str]) – The directory to write intermediate data to.

• map_by (Union[str, List[str]]) – The attributes to be used for color mapping.

• default_values (Optional[Dict[str, int]]) – The default values used for the keys used in attributes, if None is {“class”: 0}.

• file_prefix (str) – The prefix to use for writing the images.

• output_key (str) – The key to use for registering the output.

• segcolormap_output_file_prefix (str) – The prefix to use for writing the segmentation-color map csv.

• segcolormap_output_key (str) – The key to use for registering the segmentation-color map output.

• use_alpha_channel (bool) – If true, the alpha channel stored in .png textures is used.

• render_colorspace_size_per_dimension (int) – As we use float16 for storing the rendering, the interval of integers which can be precisely stored is [-2048, 2048]. As blender does not allow negative values for colors, we use [0, 2048] ** 3 as our color space which allows ~8 billion different colors/objects. This should be enough.

Return type:

Dict[str, Union[ndarray, List[ndarray]]]

Returns:

dict of lists of segmaps and (for instance segmentation) segcolormaps

blenderproc.renderer.set_cpu_threads(num_threads)

Sets the number of CPU cores to use simultaneously while rendering.

Parameters:

num_threads (int) – The number of threads to use. If 0 is given the number is automatically detected based on the cpu cores.

blenderproc.renderer.set_denoiser(denoiser)

Enables the specified denoiser.

Automatically disables all previously activated denoiser.

Parameters:

denoiser (Optional[str]) – The name of the denoiser which should be enabled. Options are “INTEL”, “OPTIX” and None. If None is given, then no denoiser will be active.

blenderproc.renderer.set_light_bounces(diffuse_bounces=None, glossy_bounces=None, ao_bounces_render=None, max_bounces=None, transmission_bounces=None, transparent_max_bounces=None, volume_bounces=None)

Sets the number of light bounces that should be used by the raytracing renderer. Default values are defined in DefaultConfig.py

Parameters:

• diffuse_bounces (Optional[int]) – Maximum number of diffuse reflection bounces, bounded by total maximum.

• glossy_bounces (Optional[int]) – Maximum number of glossy reflection bounces, bounded by total maximum.

• ao_bounces_render (Optional[int]) – Approximate indirect light with background tinted ambient occlusion at the specified bounce, 0 disables this feature.

• max_bounces (Optional[int]) – Total maximum number of bounces.

• transmission_bounces (Optional[int]) – Maximum number of transmission bounces, bounded by total maximum.

• transparent_max_bounces (Optional[int]) – Maximum number of transparent bounces.

• volume_bounces (Optional[int]) – Maximum number of volumetric scattering events.

blenderproc.renderer.set_max_amount_of_samples(samples)

Sets the maximum number of samples to render for each pixel. This maximum amount is usually not reached if the noise threshold is low enough. If the noise threshold was set to 0, then only the maximum number of samples is used (We do not recommend this).

Parameters:

samples (int) – The maximum number of samples per pixel

blenderproc.renderer.set_noise_threshold(noise_threshold)

Configures the adaptive sampling, the noise threshold is typically between 0.1 and 0.001. Adaptive sampling automatically decreases the number of samples per pixel based on estimated level of noise.

We do not recommend setting the noise threshold value to zero and therefore turning off the adaptive sampling.

For more information see the official documentation: https://docs.blender.org/manual/en/latest/render/cycles/render_settings/sampling.html#adaptive-sampling

Parameters:

noise_threshold (float) – Noise level to stop sampling at. If 0 is given, adaptive sampling is disabled and only the max amount of samples is used.

blenderproc.renderer.set_output_format(file_format=None, color_depth=None, enable_transparency=None, jpg_quality=None)

Sets the output format to use for rendering. Default values defined in DefaultConfig.py.

Parameters:

• file_format (Optional[str]) – The file format to use, e.q. “PNG”, “JPEG” or “OPEN_EXR”.

• color_depth (Optional[int]) – The color depth.

• enable_transparency (Optional[bool]) – If true, the output will contain a alpha channel and the background will be set transparent.

• jpg_quality (Optional[int]) – The quality to use, if file format is set to “JPEG”.

blenderproc.renderer.set_render_devices(use_only_cpu=False, desired_gpu_device_type=None, desired_gpu_ids=None)

Configures the devices to use for rendering.

Parameters:

• use_only_cpu (bool) – If True, only the cpu is used for rendering.

• desired_gpu_device_type (Union[str, List[str], None]) – One or multiple GPU device types to consider. If multiple are given, the first available is used. Possible choices are [“OPTIX”, “CUDA”, “METAL”, “HIP”]. Default is [“OPTIX”, “CUDA”, “HIP”] on linux/windows and [“METAL”] on supported Mac devices.

• desired_gpu_ids (Union[int, List[int], None]) – One or multiple GPU ids to specifically use. If none is given, all suitable GPUs are used.

blenderproc.renderer.set_simplify_subdivision_render(simplify_subdivision_render)

Sets global maximum subdivision level during rendering to speedup rendering.

Parameters:

simplify_subdivision_render (int) – The maximum subdivision level. If 0 is given, simplification of scene is disabled.

blenderproc.renderer.set_world_background(color, strength=1)

Sets the color of blenders world background

Parameters:

• color (List[float]) – A three-dimensional list specifying the new color in floats.

• strength (float) – The strength of the emitted background light.

blenderproc.renderer.toggle_light_tree(enable)

Enables/Disables blender’s light tree for rendering.

Enabling the light tree reduces the noise in scenes with many point lights, however it increases the render time per sample. See https://wiki.blender.org/wiki/Reference/Release_Notes/3.5/Cycles

Parameters:

enable (bool) – True, if light tree should be enabled.

blenderproc.renderer.toggle_stereo(enable)

Enables/Disables stereoscopy.

Parameters:

enable (bool) – True, if stereoscopy should be enabled.