pyvale.render.blender package

Submodules

• pyvale.render.blender.adapter module
  • Blender
    • Blender.capabilities
    • Blender.__init__()
    • Blender.verify_input()
  • raise_if_blender_unavailable()
  • blender_available()
  • blender_gpu_available()
• pyvale.render.blender.blendertools module
  • blender_camera_from_resolution()
  • blender_field_of_view()
  • blender_mm_per_pixel()
  • focal_length_from_resolution()
• pyvale.render.blender.calibration module
  • BlenderCalibrationData
    • BlenderCalibrationData.angle_lims
    • BlenderCalibrationData.angle_step
    • BlenderCalibrationData.plunge_lims
    • BlenderCalibrationData.plunge_step
    • BlenderCalibrationData.x_limit
    • BlenderCalibrationData.y_limit
    • BlenderCalibrationData.max_images
    • BlenderCalibrationData.__init__()
  • BlenderCalibrationTarget
    • BlenderCalibrationTarget.size
    • BlenderCalibrationTarget.image_path
    • BlenderCalibrationTarget.millimetres_per_pixel
    • BlenderCalibrationTarget.material
    • BlenderCalibrationTarget.__init__()
  • calibration_image_count()
  • render_calibration_images()
• pyvale.render.blender.config module
  • EBlenderEngine
    • EBlenderEngine.CYCLES
    • EBlenderEngine.EEVEE
    • EBlenderEngine.WORKBENCH
  • EBlenderDevice
    • EBlenderDevice.CPU
    • EBlenderDevice.GPU
  • BlenderConfig
    • BlenderConfig.output_dir
    • BlenderConfig.engine
    • BlenderConfig.device
    • BlenderConfig.samples
    • BlenderConfig.max_bounces
    • BlenderConfig.threads
    • BlenderConfig.render_deformed
    • BlenderConfig.save_images
    • BlenderConfig.save_scene
    • BlenderConfig.seed
    • BlenderConfig.use_denoising
    • BlenderConfig.use_adaptive_sampling
    • BlenderConfig.__init__()
• pyvale.render.blender.shader module
  • BlenderMaterial
    • BlenderMaterial.roughness
    • BlenderMaterial.metallic
    • BlenderMaterial.interpolant
    • BlenderMaterial.__init__()
  • BlenderTextureShader
    • BlenderTextureShader.image_path
    • BlenderTextureShader.millimetres_per_pixel
    • BlenderTextureShader.material
    • BlenderTextureShader.__init__()
  • BlenderImageShader
    • BlenderImageShader.image
    • BlenderImageShader.millimetres_per_pixel
    • BlenderImageShader.material
    • BlenderImageShader.__init__()

Module contents

Blender implementation of pyvale’s unified renderer API.

class Blender(config)

Bases: IRenderer3D

Render common scene data and deformation frames in Blender.

capabilities = RenderCapabilities(element_types=frozenset({<EElemType.TRI3: 'tri3'>}), supports_lights=True, supports_camera_distortion=False, supports_psf=False)

__init__(config)

Store configuration used by subsequent requests.

verify_input(scene)

Validate a complete Blender request before scene construction.

class BlenderCalibrationData(angle_lims=(-10.0, 10.0), angle_step=5.0, plunge_lims=(-5.0, 5.0), plunge_step=5.0, x_limit=None, y_limit=None, max_images=None)

Bases: object

Describe the pose sweep used to render a camera calibration target.

Parameters:

• angle_lims (tuple[float, float], optional) – Inclusive lower and upper target-angle limits in degrees.

• angle_step (float, optional) – Angular increment in degrees.

• plunge_lims (tuple[float, float], optional) – Inclusive lower and upper target-depth limits.

• plunge_step (float, optional) – Target-depth increment.

• x_limit (float or None, optional) – Optional lateral target-position limits retained for calibration scene generation.

• y_limit (float or None, optional) – Optional lateral target-position limits retained for calibration scene generation.

• max_images (int or None, optional) – Maximum number of TIFF files to render. None renders every pose.

angle_lims

angle_step

plunge_lims

plunge_step

x_limit

y_limit

max_images

__init__(angle_lims=(-10.0, 10.0), angle_step=5.0, plunge_lims=(-5.0, 5.0), plunge_step=5.0, x_limit=None, y_limit=None, max_images=None)

class BlenderCalibrationTarget(size, image_path, millimetres_per_pixel, material=<factory>)

Bases: object

A textured planar target used to generate calibration images.

Parameters:

• size (numpy.ndarray) – Target width, height, and thickness in world units.

• image_path (pathlib.Path) – Calibration-target texture image.

• millimetres_per_pixel (float) – Texture resolution used by Blender UV unwrapping.

• material (BlenderMaterial, optional) – Backend-owned material controls for the target.

size

image_path

millimetres_per_pixel

material

__init__(size, image_path, millimetres_per_pixel, material=<factory>)

class BlenderConfig(output_dir, engine=EBlenderEngine.CYCLES, device=EBlenderDevice.CPU, samples=2, max_bounces=12, threads=1, render_deformed=False, save_images=False, save_scene=False, seed=0, use_denoising=True, use_adaptive_sampling=True)

Bases: object

Stable Blender controls accepted by the unified adapter.

Parameters:

• output_dir (pathlib.Path) – Directory used for optional TIFF and Blender-project outputs.

• engine (EBlenderEngine, optional) – Blender render engine.

• device (EBlenderDevice, optional) – Cycles compute device. CPU is the reproducible regression default.

• samples (int, optional) – Per-pixel render samples.

• max_bounces (int, optional) – Cycles maximum light-bounce count.

• threads (int, optional) – Blender render worker count.

• render_deformed (bool, optional) – Render each nodal-displacement frame instead of a static scene.

• save_images (bool, optional) – Persist TIFFs and return their paths rather than retaining image arrays.

• save_scene (bool, optional) – Persist the constructed Blender scene as a .blend project file.

• seed (int, optional) – Fixed Cycles sampling seed used for reproducible rendering.

• use_denoising (bool, optional) – Enable Cycles image denoising.

• use_adaptive_sampling (bool, optional) – Enable Cycles adaptive sampling.

output_dir

engine

device

samples

max_bounces

threads

render_deformed

save_images

save_scene

seed

use_denoising

use_adaptive_sampling

__init__(output_dir, engine=EBlenderEngine.CYCLES, device=EBlenderDevice.CPU, samples=2, max_bounces=12, threads=1, render_deformed=False, save_images=False, save_scene=False, seed=0, use_denoising=True, use_adaptive_sampling=True)

class BlenderImageShader(image, millimetres_per_pixel, material=BlenderMaterial(roughness=1.0, metallic=0.0, interpolant='Cubic'))

Bases: object

In-memory texture-image controls for a Blender mesh material.

Parameters:

• image (numpy.ndarray) – Greyscale or RGBA image texture supplied directly to Blender.

• millimetres_per_pixel (float) – Texture scale used by Blender UV unwrapping.

• material (BlenderMaterial, optional) – Backend-owned principled material controls.

image

millimetres_per_pixel

material

__init__(image, millimetres_per_pixel, material=BlenderMaterial(roughness=1.0, metallic=0.0, interpolant='Cubic'))

class BlenderMaterial(roughness=1.0, metallic=0.0, interpolant='Cubic')

Bases: object

Principled-material controls owned by the Blender backend.

Parameters:

• roughness (float, optional) – Blender principled-BSDF roughness.

• metallic (float, optional) – Blender principled-BSDF metallic weight.

• interpolant (str, optional) – Blender image-texture interpolation mode.

roughness

metallic

interpolant

__init__(roughness=1.0, metallic=0.0, interpolant='Cubic')

class BlenderTextureShader(image_path, millimetres_per_pixel, material=BlenderMaterial(roughness=1.0, metallic=0.0, interpolant='Cubic'))

Bases: object

Image texture controls for a Blender mesh material.

Parameters:

• image_path (pathlib.Path) – Speckle or surface texture image supplied to Blender.

• millimetres_per_pixel (float) – Texture scale used by Blender UV unwrapping.

• material (BlenderMaterial, optional) – Backend-owned principled material controls.

image_path

millimetres_per_pixel

material

__init__(image_path, millimetres_per_pixel, material=BlenderMaterial(roughness=1.0, metallic=0.0, interpolant='Cubic'))

class EBlenderDevice(*values)

Bases: Enum

Cycles compute devices supported by the unified adapter.

CPU = 'CPU'

GPU = 'GPU'

class EBlenderEngine(*values)

Bases: Enum

Blender render engines supported by the unified adapter.

CYCLES = 'CYCLES'

EEVEE = 'BLENDER_EEVEE'

WORKBENCH = 'BLENDER_WORKBENCH'

blender_available()

Return whether this interpreter can execute the Blender backend.

blender_camera_from_resolution(pixels_num, pixels_size, working_dist, resolution)

Create a perspective camera from working distance and resolution.

blender_field_of_view(camera)

Calculate Blender’s perspective field of view for a camera.

blender_gpu_available()

Return whether Blender reports a supported Cycles GPU device.

Returns:

bool – True when Blender’s Cycles preferences report a CUDA, OptiX, HIP, Metal, or oneAPI device. False if Blender is unavailable.

blender_mm_per_pixel(camera)

Calculate the horizontal world length represented by one pixel.

calibration_image_count(data)

Return the number of legacy Blender calibration-target images.

Parameters:

data (BlenderCalibrationData) – Calibration target pose-sweep configuration.

Returns:

int – Number of target poses in the historical nine-position lateral sweep.

focal_length_from_resolution(pixels_size, working_dist, resolution)

Calculate the focal length for a requested image resolution.

raise_if_blender_unavailable()

Raise RenderInputError if the optional Blender backend is missing.

render_calibration_images(target, cameras, config, data=None, lights=None)

Render a legacy-compatible Blender calibration-target pose sweep.

Parameters:

• target (BlenderCalibrationTarget) – Textured physical calibration target.

• cameras (Sequence[Camera]) – Exactly two perspective cameras defining the calibration rig.

• config (BlenderConfig) – Blender engine, image output, and sampling controls.

• data (BlenderCalibrationData, optional) – Target translation and rotation sweep controls.

• lights (Sequence[Light] or None, optional) – Optional scene lights. None preserves Blender’s dark default world.

Returns:

RenderResult – File-only result containing the calibration TIFF paths.

Raises:

RenderInputError – If input is invalid or the Blender backend is unavailable.