core¶

Brayns core functionalities.

Provides high-level objects to wrap the raw JSON-RPC messages sent and received with an instance of Brayns service.

Include access to camera, renderer, models, materials, snapshots, etc…

geometry¶

class BoundedPlane(equation: PlaneEquation, bounds: Bounds)¶

Bases: Geometry

Axis-aligned bounded plane.

Parameters:

equation (PlaneEquation) – Plane equation coefficients.
bounds (Bounds) – Axis aligned bounds to limit the plane.

bounds: Bounds¶

equation: PlaneEquation¶

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶: Low level API to serialize to JSON.

class Box(min: Vector3, max: Vector3)¶

Bases: Geometry

3D box.

Parameters:

min (Vector3) – Minimum XYZ.
max (Vector3) – Maximum XYZ.

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

max: Vector3¶

min: Vector3¶

class property name: str¶: Low level API to serialize to JSON.

class Capsule(start_point: Vector3, start_radius: float, end_point: Vector3, end_radius: float)¶

Bases: Geometry

Capsule (cylinder with slope and half spheres at extremities).

Parameters:

start_point (Vector3) – Cylinder base XYZ.
start_radius (float) – Cylinder and sphere base radius.
end_point (Vector3) – Cylinder end XYZ.
end_radius (float) – Cylinder and sphere end radius.

end_point: Vector3¶

end_radius: float¶

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶: Low level API to serialize to JSON.

start_point: Vector3¶

start_radius: float¶

class Geometry¶

Bases: ABC

Base class of all geometry types.

abstract get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

abstract class property name: str¶: Low level API to serialize to JSON.

class Plane(equation: PlaneEquation)¶

Bases: Geometry

Infinite plane.

Parameters:: equation (PlaneEquation) – Plane equation coefficients.

equation: PlaneEquation¶

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶: Low level API to serialize to JSON.

class Sphere(radius: float, center: Vector3 = (0.0, 0.0, 0.0))¶

Bases: Geometry

Sphere with radius and position.

Parameters:

radius (float) – Radius.
center (Vector3) – Center XYZ, defaults to origin.

center: Vector3 = (0.0, 0.0, 0.0)¶

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶: Low level API to serialize to JSON.

radius: float¶

add_clipping_geometries(instance: Instance, geometries: list[T], invert_normals: bool = False) → Model¶

Create a model from a list of clipping geometries.

All geometries must have the same type.

Model witout geometries are not supported.

Parameters:

instance (Instance) – Instance.
geometries (list[T]) – Clipping geometries to add (boxes, capsules, etc…).
invert_normals (bool) – Invert shading normals to switch clipping side.

Raises:

ValueError – List is empty.

Returns:

Model created from the geometries.

Return type:

Model

add_geometries(instance: Instance, geometries: list[tuple[T, Color4]]) → Model¶

Create a model from a list of geometries with optional color.

All geometries must have the same type.

Model witout geometries are not supported.

Parameters:

instance (Instance) – Instance.
geometries (list[T]) – Geometries to add (boxes, capsules, etc…).

Raises:

ValueError – List is empty.

Returns:

Model created from the geometries.

Return type:

Model

clear_clipping_geometries(instance: Instance) → None¶

Clear all clipping geometries from the given instance.

Parameters:: instance (Instance) – Instance.

light¶

class AmbientLight(intensity: float = 1.0, color: Color3 = (1.0, 1.0, 1.0))¶

Bases: Light

Ambient light with no particular properties.

get_additional_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶

Get the light name.

Returns:: Light name.
Return type:: str

class DirectionalLight(intensity: float = 1.0, color: Color3 = (1.0, 1.0, 1.0), direction: Vector3 = (-0.0, -0.0, -1.0))¶

Bases: Light

Light shining in a given direction.

Parameters:: direction (Vector3, optional) – Light emission direction, defaults to -Z.

direction: Vector3 = (-0.0, -0.0, -1.0)¶

get_additional_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶

Get the light name.

Returns:: Light name.
Return type:: str

class Light(intensity: float = 1.0, color: Color3 = (1.0, 1.0, 1.0))¶

Bases: ABC

Base class for all light types.

Parameters:

intensity (float, optional) – Light intensity, defaults to 1.
color (Color3, optional) – Light color, defaults to white.

color: Color3 = (1.0, 1.0, 1.0)¶

abstract get_additional_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

intensity: float = 1.0¶

abstract class property name: str¶

Get the light name.

Returns:: Light name.
Return type:: str

class QuadLight(intensity: float = 1.0, color: Color3 = (1.0, 1.0, 1.0), bottom_left: Vector3 = (0.0, 0.0, 0.0), edge1: Vector3 = (1.0, 0.0, 0.0), edge2: Vector3 = (0.0, 1.0, 0.0))¶

Bases: Light

Rectangular light.

Emission direction is the positive side (see emission_direction).

Parameters:

bottom_left (Vector3) – Bottom left corner, defaults to origin.
edge1 (Vector3, optional) – First edge, defaults to +X.
edge2 (Vector3, optional) – Second edge, defaults to +Y.

bottom_left: Vector3 = (0.0, 0.0, 0.0)¶

edge1: Vector3 = (1.0, 0.0, 0.0)¶

edge2: Vector3 = (0.0, 1.0, 0.0)¶

property emission_direction: Vector3¶

Get the emission direction of the light.

Equal to edge1 x edge2 normalized.

Returns:: Emission direction.
Return type:: Vector3

get_additional_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶

Return light name.

Returns:: Light name.
Return type:: str

class SphereLight(intensity: float = 1.0, color: Color3 = (1.0, 1.0, 1.0), position: Vector3 = (0.0, 0.0, 0.0), radius: float = 0.0)¶

Bases: Light

Sphere light or point light if radius = 0.

Parameters:

position (Vector3, optional) – Light position, defaults to origin.
radius (float, optional) – Sphere radius, defaults to zero (point light).

get_additional_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶

Return light name.

Returns:: Light name.
Return type:: str

position: Vector3 = (0.0, 0.0, 0.0)¶

radius: float = 0.0¶

add_light(instance: Instance, light: Light) → Model¶

Add a given light to an instance and return its model.

Parameters:

instance (Instance) – Instance.
light (Light) – Light to add.

Returns:

Light model.

Return type:

Model

clear_lights(instance: Instance) → None¶

Remove all lights from an instance.

Parameters:: instance (Instance) – Instance.

application¶

class Application(resolution: Resolution)¶

Bases: object

Store the application parameters of an instance.

Parameters:: resolution (Resolution) – Framebuffer resolution.

resolution: Resolution¶

get_application(instance: Instance) → Application¶

Retreive the application parameters from an instance.

Parameters:: instance (Instance) – Instance.
Returns:: Current application parameters.
Return type:: Application

set_resolution(instance: Instance, resolution: Resolution) → None¶

Update the framebuffer resolution of the given instance.

Parameters:

instance (Instance) – Instance.
resolution (Resolution) – Framebuffer resolution.

stop(instance: Instance) → None¶

Stop a running instance.

Parameters:: instance (Instance) – Instance.

camera¶

class Camera(view: ~brayns.core.view.View = <factory>, projection: ~brayns.core.projection.Projection = <factory>, near_clipping_distance: float = 1e-06)¶

Bases: object

Camera used to render.

A camera is composed of a View, a Projection and a clipping distance.

property direction: Vector3¶

Get camera direction (vector.normalized).

Returns:: Normalized camera direction.
Return type:: Vector3

property distance: float¶

Get distance between camera position and target.

Returns:: Camera distance.
Return type:: float

property name: str¶

Get the camera name (can be compared with get_camera_name).

Returns:: Camera projection name.
Return type:: str

near_clipping_distance: float = 1e-06¶

property orientation: Rotation¶

Get camera orientation compared to the front one.

Returns:: Camera orientation.
Return type:: Rotation

property position: Vector3¶

Get camera position.

Returns:: Camera position.
Return type:: Vector3

projection: Projection¶

property real_up: Vector3¶

Get the camera effective up direction (right x direction).

Returns:: Camera up direction.
Return type:: Vector3

property right: Vector3¶

Get the camera right direction (direction x up).

Returns:: Camera right direction.
Return type:: Vector3

rotate_around_target(rotation: Rotation) → Camera¶

Rotate camera view around its target.

Parameters:: rotation (Rotation) – Rotation to apply on camera view.
Returns:: New rotated camera.
Return type:: Camera

property target: Vector3¶

Get camera target.

Returns:: Camera target.
Return type:: Vector3

translate(translation: Vector3) → Camera¶

Translate both camera position and target.

Parameters:: translation (Vector3) – Translation to apply.
Returns:: New translated camera.
Return type:: Camera

property up: Vector3¶

Get camera up direction.

Returns:: Camera up.
Return type:: Vector3

property vector: Vector3¶

Get camera vector (target - position).

Returns:: Camera vector.
Return type:: Vector3

view: View¶

get_camera(instance: Instance, projection_type: type[Projection]) → Camera¶

Shortcut to retreive the current camera of an instance.

Use get_camera_projection and get_camera_view.

projection_type must be of the same type as the current projection.

Parameters:

instance (Instance) – Instance.
projection_type (type[Projection]) – Current camera projection type of instance.

Returns:

Camera with current view and projection.

Return type:

Camera

set_camera(instance: Instance, camera: Camera) → None¶

Shortcut to update the camera view and projection.

Parameters:

instance (Instance) – Instance.
camera (Camera) – Current camera to use for instance.

camera_controller¶

class CameraController(target: ~brayns.utils.bounds.Bounds, aspect_ratio: float = 1.0, translation: ~brayns.utils.vector.Vector3 = (0.0, 0.0, 0.0), rotation: ~brayns.utils.rotation.Rotation = <brayns.utils.rotation.Rotation object>, projection: ~collections.abc.Callable[[], ~brayns.core.projection.Projection] = <class 'brayns.core.projection.PerspectiveProjection'>)¶

Bases: object

Helper to create a camera to look at a given target.

Aspect ratio is usually the one of the resolution of the final image.

Camera translation and rotation can be used to adjust the camera manually. They are applied in this order relatively to the front view (use X to move right, Y to move up and Z to move further from the target).

A new projection is created for each camera. It can be configured using the projection parameter, which is a callable returning a new projection.

A camera using the current settings can be built at any time using the camera property.

Parameters:

target (Bounds) – Camera target bounds.
aspect_ratio (float) – Viewport aspect ratio (width / height), defaults to 1.
translation (Vector3, optional) – Camera translation (before rotation), defaults to zero.
rotation (Rotation, optional) – Camera rotation, defaults to identity.
projection (Projection, optional) – Projection factory, defaults to PerspectiveProjection.

aspect_ratio: float = 1.0¶

property camera: Camera¶

Create a new camera using current controller settings.

Returns:: Camera focusing on controller target.
Return type:: Camera

projection¶: alias of PerspectiveProjection

rotation: Rotation = <brayns.utils.rotation.Rotation object>¶

target: Bounds¶

translation: Vector3 = (0.0, 0.0, 0.0)¶

material¶

class CarPaintMaterial(flake_density: float = 0.0)¶

Bases: Material

Car paint material.

Parameters:: flake_density (float, optional) – Flake density (0-1), defaults to no flakes.

flake_density: float = 0.0¶

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶

Get the material name.

Returns:: Material name
Return type:: str

update_properties(message: dict[str, Any]) → None¶: Low level API to deserialize from JSON.

class EmissiveMaterial(intensity: float = 1.0, color: Color3 = (1.0, 1.0, 1.0))¶

Bases: Material

Emissive material.

Parameters:

intensity (float, optional) – Light emission intensity, defaults to 1.
color (Color3, optional) – Light color, defaults to white.

color: Color3 = (1.0, 1.0, 1.0)¶

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

intensity: float = 1.0¶

class property name: str¶

Get the material name.

Returns:: Material name
Return type:: str

update_properties(message: dict[str, Any]) → None¶: Low level API to deserialize from JSON.

class GlassMaterial(refraction_index: float = 1.5)¶

Bases: Material

Glass material.

Parameters:: refraction_index (float, optional) – Refraction index, defaults to 1.5.

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶

Get the material name.

Returns:: Material name
Return type:: str

refraction_index: float = 1.5¶

update_properties(message: dict[str, Any]) → None¶: Low level API to deserialize from JSON.

class Material¶

Bases: ABC

Base class for all material types.

Material are applied on model to change their aspect (but not their color).

classmethod from_properties(message: dict[str, Any]) → T¶: Low level API to deserialize from JSON.

abstract get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

abstract class property name: str¶

Get the material name.

Returns:: Material name
Return type:: str

abstract update_properties(message: dict[str, Any]) → None¶: Low level API to deserialize from JSON.

class MatteMaterial(opacity: float = 1.0)¶

Bases: Material

Matte material.

Parameters:: opacity (float, optional) – Opacity (0-1), defaults to fully opaque.

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶

Get the material name.

Returns:: Material name
Return type:: str

opacity: float = 1.0¶

update_properties(message: dict[str, Any]) → None¶: Low level API to deserialize from JSON.

class MetalMaterial(roughness: float = 1.0)¶

Bases: Material

Metal material.

Parameters:: roughness (float, optional) – Roughness of the metal, defaults to 1.

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶

Get the material name.

Returns:: Material name
Return type:: str

roughness: float = 1.0¶

update_properties(message: dict[str, Any]) → None¶: Low level API to deserialize from JSON.

class PhongMaterial(opacity: float = 1.0)¶

Bases: Material

Phong material used by default, works with all renderers.

Parameters:: opacity (float, optional) – Opacity (0-1), defaults to fully opaque.

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶

Get the material name.

Returns:: Material name
Return type:: str

opacity: float = 1.0¶

update_properties(message: dict[str, Any]) → None¶: Low level API to deserialize from JSON.

class PlasticMaterial(opacity: float = 1.0)¶

Bases: Material

Plastic material.

Parameters:: opacity (float, optional) – Opacity (0-1), defaults to fully opaque.

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶

Get the material name.

Returns:: Material name
Return type:: str

opacity: float = 1.0¶

update_properties(message: dict[str, Any]) → None¶: Low level API to deserialize from JSON.

class PrincipledMaterial(edge_color: Color3 = (1, 1, 1), metallic: float = 0, diffuse: float = 1, specular: float = 1, ior: float = 1, transmission: float = 0, transmission_color: Color3 = (1, 1, 1), transmission_depth: float = 1, roughness: float = 1, anisotropy: float = 0, anisotropy_rotation: float = 0, thin: bool = False, thickness: float = 1, back_light: float = 0, coat: float = 0, coat_ior: float = 1.5, coat_color: Color3 = (1, 1, 1), coat_thickness: float = 1, coat_roughness: float = 0, sheen: float = 0, sheen_color: Color3 = (1, 1, 1), sheen_tint: float = 0, sheen_roughness: float = 0.2)¶

Bases: Material

Principled material.

Parameters:

edge_color (float, optional) – Surface edge tint for metallic surfaces.
metallic (float, optional) – Alpha parameter between dielectric and metallic.
diffuse (float, optional) – Diffuse reflection weight.
specular (float, optional) – Specular reflection/transmission weight.
ior (float, optional) – Dielectric index of refraction.
transmission (float, optional) – Specular transmission weight.
transmission_color (Color3, optional) – Transmission attenuation color.
transmission_depth (float, optional) – Surface distance for pure transmission color.
roughness (float, optional) – Diffuse and specular reflection roughness.
anisotropy (float, optional) – Specular anisotropy reflection weight.
anisotropy_rotation (float, optional) – Rotation of the specular anisotropy reflection.
thin (bool, optional) – Specified wether the object is solid or thin (hollow).
thickness (float, optional) – Thickness of the object if thin = True.
back_light (float, optional) – Weight of reflection and transmission if thin = True.
coat (float, optional) – Clear coat weight.
coat_ior (float, optional) – Clear coat index of refraction.
coat_color (Color3, optional) – Clear coat color.
coat_thickness (float, optional) – Clear coat thickness.
coat_roughness (float, optional) – Clear coat diffuse/specular reflection roughness.
sheen (float, optional) – Sheen effect weight.
sheen_color (Color3, optional) – Sheen color.
sheen_tint (float, optional) – Alpha from white to sheen color for sheen effect.
sheen_roughness (float, optional) – Sheen diffuse/specular reflection roughness.

anisotropy: float = 0¶

anisotropy_rotation: float = 0¶

back_light: float = 0¶

coat: float = 0¶

coat_color: Color3 = (1, 1, 1)¶

coat_ior: float = 1.5¶

coat_roughness: float = 0¶

coat_thickness: float = 1¶

diffuse: float = 1¶

edge_color: Color3 = (1, 1, 1)¶

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

ior: float = 1¶

metallic: float = 0¶

class property name: str¶

Get the material name.

Returns:: Material name
Return type:: str

roughness: float = 1¶

sheen: float = 0¶

sheen_color: Color3 = (1, 1, 1)¶

sheen_roughness: float = 0.2¶

sheen_tint: float = 0¶

specular: float = 1¶

thickness: float = 1¶

thin: bool = False¶

transmission: float = 0¶

transmission_color: Color3 = (1, 1, 1)¶

transmission_depth: float = 1¶

update_properties(message: dict[str, Any]) → None¶: Low level API to deserialize from JSON.

get_material(instance: Instance, model_id: int, material_type: type[T]) → T¶

Get the material applied on the given model.

material_type must be the current model material type.

Parameters:

instance (Instance) – Instance.
model_id (int) – ID of the model.
material_type (type[T]) – Material type.

Returns:

Material applied on model.

Return type:

T

get_material_name(instance: Instance, model_id: int) → str¶

Get the name of the material applied on the given model.

Can be used to check that a given material is applied on a model:

Parameters:

instance (Instance) – Instance.
model_id (int) – ID of the model to check.

Returns:

Material name.

Return type:

str

set_material(instance: Instance, model_id: int, material: Material) → None¶

Apply the given material to the given model.

Parameters:

instance (Instance) – Instance.
model_id (int) – Model ID.
material (Material) – Material to apply on model.

version¶

class Version(major: int, minor: int, patch: int, pre_release: str)¶

Bases: object

Instance version info.

Parameters:

major (int) – Major part.
minor (int) – Minor part.
patch (int) – Patch part.
pre_release (str) – Pre-release (empty in prod).

check(local: str = '4.0.0') → None¶

Check that self is compatible with local version.

Parameters:: local (str, optional) – API version, defaults to VERSION.
Raises:: VersionError – Version mismatch.

major: int¶

minor: int¶

patch: int¶

pre_release: str¶

property release: tuple[int, int, int]¶

Return a tuple with major, minor and patch.

Returns:: Release tuple.
Return type:: tuple[int, int, int]

property tag: str¶

Format version tag ‘major.minor.patch’.

Can be compared to package __version__.

Returns:: Version tag.
Return type:: str

exception VersionError(local: str, remote: str)¶

Bases: Error

Error raised when a version mismatch occurs.

Parameters:

local (str) – Local (Python API) version.
local – Remote (Binary) version.

local: str¶

remote: str¶

check_version(instance: Instance) → None¶

Check that the version of the instance is compatible with the API.

Parameters:: instance (Instance) – Instance to check.

get_version(instance: Instance) → Version¶

Retreive the version of a backend instance.

Parameters:: instance (Instance) – Instance.
Returns:: Version info.
Return type:: Version

model¶

class Model(id: int, type: str, bounds: Bounds, info: dict[str, Any], visible: bool, transform: Transform)¶

Bases: object

Loaded model.

All models are loaded without transform (identity) but it doesn’t mean that their center of mass is at the origin (depends on the source file).

Model metadata are a str -> str map and depends on the model type.

Parameters:

id (int) – Model ID.
type (str) – Model type.
bounds (Bounds) – Model bounding box.
info (dict[str, Any]) – Intrinsic nodel information.
visible (bool) – Check wether the model is rendered or not.
transform (Transform) – Model transform relative to the origin.

bounds: Bounds¶

id: int¶

info: dict[str, Any]¶

transform: Transform¶

type: str¶

visible: bool¶

class Scene(bounds: Bounds, models: list[Model])¶

Bases: object

Contains all existing models and scene boundaries.

Scene bounds take models and lights into account.

Parameters:

bounds (Bounds) – Global bounds.
models (list[Model]) – List of all existing models.

bounds: Bounds¶

models: list[Model]¶

clear_models(instance: Instance) → None¶

Clear all models from the given instance.

Parameters:: instance (Instance) – Instance.

clear_renderables(instance: Instance) → None¶

Clear all models that can be rendered from the given instance.

Renderables exclude lights and clipping geometries.

Parameters:: instance (Instance) – Instance.

get_bounds(instance: Instance) → Bounds¶

Retreive the scene boundary of an instance.

The scene boundaries are computed from all existing lights and models in the given instance.

Parameters:: instance (Instance) – Instance.
Returns:: Bounds of the current scene.
Return type:: Bounds

get_model(instance: Instance, id: int) → Model¶

Retreive the model with given ID from an instance.

Parameters:

instance (Instance) – Instance.
id (int) – Model ID.

Returns:

Model object.

Return type:

Model

get_models(instance: Instance) → list[Model]¶

Retreive all models from an instance.

Parameters:: instance (Instance) – Instance.
Returns:: List of models.
Return type:: list[Model]

get_scene(instance: Instance) → Scene¶

Retreive all models and the world boundaries from an instance.

Parameters:: instance (Instance) – Instance.
Returns:: Models and global bounds.
Return type:: Scene

instantiate_model(instance: Instance, model_id: int, transforms: list[Transform]) → list[Model]¶

Create instances of the given model and return them.

The amount of new instances is equal to the number of transforms passed.

Parameters:

instance (Instance) – Instance.
model_id (int) – ID of the model to instantiate.
transforms (list[Transform]) – List of new instances transformations.

Returns:

New instance model.

Return type:

Model

remove_models(instance: Instance, ids: list[int]) → None¶

Remove the given models from an instance.

Parameters:

instance (Instance) – Instance.
ids (list[int]) – ID(s) of the models to remove.

update_model(instance: Instance, model_id: int, transform: Transform | None = None, visible: bool | None = None) → Model¶

Modify the properties of a given model and return its updated version.

Parameters left as None will remain in their current state.

Parameters:

instance (Instance) – Instance.
model_id (int) – ID of the model to update.
transform (Transform | None, optional) – Model transformation, defaults to None
visible (bool | None, optional) – Model visibility, defaults to None

Returns:

Updated model.

Return type:

Model

coloring¶

class ColorMethod¶

Bases: object

Core coloring methods.

GEOMETRY: ClassVar[str] = 'primitive'¶

SOLID: ClassVar[str] = 'solid'¶

TRIANGLE: ClassVar[str] = 'triangle'¶

VERTEX: ClassVar[str] = 'vertex'¶

color_model(instance: Instance, model_id: int, method: str, colors: dict[str, Color4]) → None¶

Color a model by the given method.

This function needs a method name and a mapping to get a color from a method value.

See ColorMethod and CircuitColorMethod for available methods.

For example to color a circuit by GID the mapping can be:

colors = {
    '1': brayns.Color4.red,
    '2': brayns.Color4.blue,
}

Where 1 and 2 are the method values (here GIDs) mapped to the color that must be applied to them.

Supported methods depend on the plugins loaded and the model type. See get_color_methods and get_color_values for more details.

When coloring by ID (GIDs, triangle, geometry, …) the IDs start at zero and are incremented in the order of the loading. They can be concatenated in a single value using comma and dashes.

Example: ‘0,2,4-6,8’.

Parameters:

instance (Instance) – Instance.
model_id (int) – ID of the model to color.
method (str) – Coloring method to use.
colors (dict[str, Color4]) – Color to use per method value.

get_color_methods(instance: Instance, model_id: int) → list[str]¶

Get the available coloring methods for the given model.

Parameters:

instance (Instance) – Instance.
model_id (int) – Model ID.

Returns:

Color method names.

Return type:

list[str]

get_color_values(instance: Instance, model_id: int, method: str) → list[str]¶

Get available color values for a given method and model.

Color values are the name of the elements to color. For example, the color method ‘layer’ has values [‘1’, ‘2’, ‘3’] if the model has 3 layers.

Parameters:

instance (Instance) – Instance.
model_id (int) – Model ID.
method (str) – Coloring method name.

Returns:

Available color values.

Return type:

list[str]

set_model_color(instance: Instance, model_id: int, color: Color4) → None¶

Shortcut to color a model using a single color.

Parameters:

instance (Instance) – Instance.
model_id (int) – ID of the model to color.
color (Color4) – Color to apply on model.

color_ramp¶

class ColorRamp(value_range: ValueRange, colors: list[Color4])¶

Bases: object

Color ramp to map simulation values to colors.

Simulation values below value_range.min have colors[0].

Simulation values above value_range.max have colors[-1].

Otherwise, the two closest colors in the list are interpolated linearly.

Parameters:

value_range (ValueRange) – Simulation value range (usually voltages).
colors (list[Color4]) – List of colors mapped to value range.

colors: list[Color4]¶

value_range: ValueRange¶

class ValueRange(min: float, max: float)¶

Bases: Vector[float]

Specify color ramp value range.

Usually the simulation values are voltages but it can be anything.

Parameters:

min (float) – Minimal simulation value.
max (float) – Maximal simulation value.

property max: float¶

property min: float¶

normalize(value: float) → float¶

Normalize given value between min and max.

Result is not clamped between min and max.

For example a value of 5 with min = 0 and max = 10 gives 0.5.

Parameters:: value (float) – Simulation value.
Returns:: Normalized simulation value.
Return type:: float

property size: float¶

Get the difference between min and max.

Returns:: Value range.
Return type:: float

get_color_ramp(instance: Instance, model_id: int) → ColorRamp¶

Retreive the color ramp of the given model.

Model must have a color ramp attached (usually report loaded).

Parameters:

instance (Instance) – Instance.
model_id (int) – Model ID.

Returns:

Color ramp.

Return type:

ColorRamp

set_color_ramp(instance: Instance, model_id: int, ramp: ColorRamp) → None¶

Set the current color ramp of the given model.

Parameters:

instance (Instance) – Instance.
model_id (int) – Model ID.
color_ramp (ColorRamp) – Color ramp.

opacity_curve¶

class ControlPoint(normalized_value: float, opacity: float)¶

Bases: object

Control point used for opacity curves.

Normalized values are simulation values (usually voltages) normalized between the min and max of the color ramp value range.

Parameters:

normalized_value (float) – Simulation value, normalized.
opacity (float) – Color opacity at simulation value.

class property end: ControlPoint¶

Implicit last control point of the opacity curve [1, 1].

Returns:: Control point.
Return type:: ControlPoint

normalized_value: float¶

opacity: float¶

class property start: ControlPoint¶

Implicit first control point of the opacity curve [0, 0].

Returns:: Control point.
Return type:: ControlPoint

class OpacityCurve(control_points: list[ControlPoint])¶

Bases: object

Opacity curve to generate opacity from a list of color3.

Use control points to map simulation value (usually voltage) to opacity.

The simulation values are normalized so it is not necessary to know them.

If no control points are set at 0 or 1, implicit control points [0, 0] and [1, 1] will be used for the computations. Otherwise the user-defined ones are used.

Parameters:: control_points (list[ControlPoint]) – Control points of the curve.

apply(colors: list[Color3]) → list[Color4]¶

Create a from colors with opacities computed from the curve.

Works also with a list of Color4 as lists are covariant in Python.

Simulation normalized value range is inferred from len(colors).

Parameters:: colors (list[Color3]) – Input colors.
Returns:: Output colors.
Return type:: list[Color4]

control_points: list[ControlPoint]¶

simulation¶

class Simulation(start_frame: int, end_frame: int, current_frame: int, delta_time: float, time_unit: TimeUnit)¶

Bases: object

Simulation state.

Parameters:

start_frame (int) – Index of the first frame of the simulation.
end_frame (int) – Index of the last frame of the simulation.
current_frame (int) – Index of the current frame of the simulation.
delta_time (float) – Delta time in time_unit between two frames.
time_unit (TimeUnit) – Time unit, always milliseconds.

clamp(frame: int) → int¶

Clamp given frame index inside simulation limits.

Parameters:: frame (int) – Frame index.
Returns:: Clamped frame index.
Return type:: int

current_frame: int¶

delta_time: float¶

property duration: float¶

Simulation duration in time_unit.

Returns:: Duration.
Return type:: float

end_frame: int¶

property fps: float¶

Simulation FPS.

Returns:: FPS.
Return type:: float

property frame_count: int¶

Number of frames in the simulation.

Returns:: Frame count.
Return type:: int

get_frame(time: float) → int¶

Convert timestamp in time_unit to frame index.

Result is not clamped to simulation limits.

Parameters:: time (float) – Timestep in time_unit.
Returns:: Frame index.
Return type:: int

get_time(frame: int) → float¶

Convert frame index to a timestep in time_unit.

Result is not clamped to simulation limits.

Parameters:: frame (int) – Frame index.
Returns:: Timestep in time_unit.
Return type:: float

start_frame: int¶

time_unit: TimeUnit¶

class TimeUnit(value)¶

Bases: Enum

Simulation time unit.

Simulation time is always in milliseconds but this class is here to avoid making this assumption.

Parameters:: MILLISECOND – milliseconds (‘ms’).

MILLISECOND = 'ms'¶

property per_second: float¶

Get the number of time unit per second.

Returns:: Time unit count in one second.
Return type:: float

property seconds: float¶

Convert the time unit to seconds.

Returns:: Time unit in seconds.
Return type:: float

enable_simulation(instance: Instance, model_id: int, enabled: bool) → None¶

Enable the simulation coloring for the given model.

If enabled, the colors of the model are the one of the simulation at the current frame (see get_simulation and set_simulation_frame).

If disabled, the colors of the model are set manually or by default.

Parameters:

instance (Instance) – Instance.
model_id (int) – Model ID.
enabled (bool) – Simulation coloring enabled for given model.

get_simulation(instance: Instance) → Simulation¶

Retreive the current simulation state of an instance.

Parameters:: instance (Instance) – Instance.
Returns:: Current simulation state.
Return type:: Simulation

set_simulation_frame(instance: Instance, index: int) → None¶

Set the current simulation frame of an instance.

Parameters:

instance (Instance) – Instance.
index (int) – Index of the current frame.

entrypoint¶

class Entrypoint(method: str, description: str, plugin: str, asynchronous: bool, deprecated: bool, params: JsonSchema | None, result: JsonSchema | None)¶

Bases: object

Entrypoint (endpoint) of the JSON-RPC API.

Describes how a given entrypoint of the JSON-RPC API can be used.

Available entrypoints can be queried from an instance to inspect the Web API of a given instance.

Parameters:

method (str) – JSON-RPC method (ex: ‘get-camera-name’).
description (str) – Human readable description.
plugin (str) – Name of the plugin which loads the entrypoint.
asynchronous (bool) – Check wether progress and cancellation are supported.
deprecated (bool) – Indicate a removal / renaming in the next major release.
params (JsonSchema | None) – Schema of input if any, otherwise None.
result (JsonSchema | None) – Schema of output if any, otherwise None.

asynchronous: bool¶

deprecated: bool¶

description: str¶

method: str¶

params: JsonSchema | None¶

plugin: str¶

result: JsonSchema | None¶

get_entrypoint(instance: Instance, method: str) → Entrypoint¶

Retreive an entrypoint using its name (JSON-RPC method).

Parameters:

instance (Instance) – Instance to query the entrypoint.
method (str) – JSON-RPC method name.

Returns:

Deserialized entrypoint.

Return type:

Entrypoint

get_entrypoints(instance: Instance) → list[Entrypoint]¶

Retreive all available entrypoints from an instance.

Parameters:: instance (Instance) – Instance to query the entrypoints.
Returns:: List of available entrypoints (depends on plugins loaded).
Return type:: list[Entrypoint]

get_methods(instance: Instance) → list[str]¶

Retreive all JSON-RPC methods from an instance.

Parameters:: instance (Instance) – Instance to query the methods.
Returns:: List of available methods (depends on plugins loaded).
Return type:: list[str]

projection¶

class Fovy(angle: float, degrees: bool = False)¶

Bases: object

Field of view (angle) of a camera.

Construct with angle.

Parameters:

angle (float) – Angle value.
degrees (bool, optional) – True if angle is in degrees, defaults to False

property degrees: float¶

Get angle in degrees.

Returns:: Angle in degrees.
Return type:: float

get_distance(height: float) → float¶

Compute the distance to have a viewport with given height.

Parameters:: height (float) – Viewport height.
Returns:: Distance to have the given viewport height.
Return type:: float

property radians: float¶

Get angle in radians.

Returns:: Angle in radians.
Return type:: float

class OrthographicProjection(height: float = 0.0)¶

Bases: Projection

Orthographic camera projection.

Orthographic camera makes all objects having the same size regardless their distance from the camera.

The viewport width is computed using the aspect ratio of the current resolution of the instance (framebuffer size).

Parameters:: height (float) – Viewport height in world coordinates.

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

height: float = 0.0¶

look_at(height: float) → float¶

Update viewport height to given one.

Camera distance doesn’t matter in orthographic projections.

Parameters:: height – Target height.
Returns:: Distance to see target entirely.
Return type:: float

class property name: str¶

Projection name.

Returns:: Projection name.
Return type:: str

update_properties(message: dict[str, Any]) → None¶: Low level API to deserialize from JSON.

class PerspectiveProjection(fovy: ~brayns.core.projection.Fovy = <brayns.core.projection.Fovy object>, aperture_radius: float = 0.0, focus_distance: float = 1.0)¶

Bases: Projection

Perspective camera projection.

Perspective projection use a field of view angle to compute the size of the objects depending on their distance from the camera.

The field of view (fovy) can be used to compute full screen view of a given target object.

Parameters:

fovy (Fovy) – Field of view angle (45 degrees by default).
aperture_radius (float) – Optional aperture radius.
focus_distance (float) – Optional focus distance.

aperture_radius: float = 0.0¶

focus_distance: float = 1.0¶

fovy: Fovy = <brayns.core.projection.Fovy object>¶

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

look_at(height: float) → float¶

Compute camera distance using field of view.

Parameters:: height – Target height.
Returns:: Distance to see target entirely.
Return type:: float

class property name: str¶

Camera name.

Returns:: Camera name.
Return type:: str

update_properties(message: dict[str, Any]) → None¶: Low level API to deserialize from JSON.

class Projection¶

Bases: ABC

Base class of all supported camera projections.

All camera projections defined in the package inherit from this class.

Projections can be identified using a unique name (ex: ‘perspective’).

classmethod from_properties(message: dict[str, Any]) → T¶: Low level API to deserialize from JSON.

abstract get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

get_properties_with_name() → dict[str, Any]¶: Low level API to serialize to JSON.

abstract look_at(height: float) → float¶

Focus on a target with given height.

Update projection properties to look at a target of given height and return the minimal distance to see it entirely.

Parameters:: height – Target height.
Returns:: Distance to see target entirely.
Return type:: float

abstract class property name: str¶

Name of the projection to identify it.

Returns:: Camera name.
Return type:: str

abstract update_properties(message: dict[str, Any]) → None¶: Low level API to deserialize from JSON.

get_camera_name(instance: Instance) → str¶

Retreive the name of the current camera of an instance.

A camera name is the name of the projection it uses.

The returned name is the same as Camera.name and can be used to check if a given camera is the current one like this:

Parameters:: instance (Instance) – Instance.
Returns:: Current camera name.
Return type:: str

get_camera_projection(instance: Instance, projection_type: type[T]) → T¶

Retreive the current camera projection from an instance.

The provided projection type must be the same as the current one.

Returned projection is of type projection_type.

Parameters:

instance (Instance) – Instance.
projection_type (type[T]) – Projection type (ex: brayns.PerspectiveProjection).

Returns:

Current camera of instance.

Return type:

T

set_camera_projection(instance: Instance, camera: Projection) → None¶

Set the current camera of the given instance.

Parameters:

instance (Instance) – Instance.
camera (Camera) – Current camera.

framebuffer¶

class Framebuffer¶

Bases: ABC

Base class for all framebuffer types.

Framebuffers define how the rendered image is stored and processed.

abstract get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

abstract class property name: str¶

Get the framebuffer name.

Returns:: Framebuffer name
Return type:: str

class ProgressiveFramebuffer(scale: int = 4)¶

Bases: Framebuffer

Progressive resolution framebuffer.

Parameters:: scale (int, optional) – First-frame reduction factor over original resolution.

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶

Get the framebuffer name.

Returns:: Framebuffer name
Return type:: str

scale: int = 4¶

class StaticFramebuffer¶

Bases: Framebuffer

Static resolution framebuffer.

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶

Get the framebuffer name.

Returns:: Framebuffer name
Return type:: str

set_framebuffer(instance: Instance, framebuffer: Framebuffer) → None¶

Stablish the given framebuffer on the engine.

Parameters:

instance (Instance) – Instance.
framebuffer (Framebuffer) – Framebuffer to set on the engine.

gbuffer_exporter¶

class GBufferChannel(value)¶

Bases: Enum

All available channels to export.

ALBEDO = 'albedo'¶

COLOR = 'color'¶

DEPTH = 'depth'¶

NORMAL = 'normal'¶

class GBufferExporter(channels: list[GBufferChannel], resolution: Resolution | None = None, camera: Camera | None = None, renderer: Renderer | None = None, frame: int | None = None)¶

Bases: object

Helper class to export the G-Buffers of an instance as an EXR encoded image.

A temporary context will be created in the instance to avoid changing its state.

For None parameters, the current values of the instance are used.

Parameters:

channels (list[GBufferChannel]) – List of g-buffer channels to export.
resolution (Resolution | None, optional) – Image resolution, defaults to None.
camera (Camera | None, optional) – Camera used to render, defaults to None.
renderer (Renderer | None, optional) – Renderer used to render, defaults to None.
frame (int | None, optional) – Simulation index, defaults to None.

camera: Camera | None = None¶

channels: list[GBufferChannel]¶

download(instance: Instance) → bytes¶

Download the exported g-buffers as EXR encoded bytes.

Parameters:: instance (Instance) – Instance.
Returns:: Image data.
Return type:: bytes

download_task(instance: Instance) → Future[bytes]¶

Asynchronous version of download.

Parameters:: instance (Instance) – Instance.
Returns:: Future to monitor the task.
Return type:: Future[bytes]

frame: int | None = None¶

renderer: Renderer | None = None¶

resolution: Resolution | None = None¶

save(instance: Instance, path: str) → None¶

Download and save the g-buffers locally under given file.

Path is on the local machine (running current script).

The “.exr” extension will be appended automatically if not present.

Parameters:

instance (Instance) – Instance.
path (str) – Output file.

save_remotely(instance: Instance, path: str) → None¶

Exports the g-buffers remotely under given file.

Path is on the remote machine (running instance backend).

The “.exr” extension will be appended automatically if not present.

Parameters:

instance (Instance) – Instance.
path (str) – Output file.

save_remotely_task(instance: Instance, path: str) → Future[None]¶

Asynchronous version of save_remotely.

Parameters:

instance (Instance) – Instance.
path (str) – Output file.

Returns:

Future to monitor the task.

Return type:

Future[None]

save_task(instance: Instance, path: str) → Future[None]¶

Asynchronous version of save.

Parameters:

instance (Instance) – Instance.
path (str) – Output file.

Returns:

Future to monitor the task.

Return type:

Future[None]

near_clip¶

get_camera_near_clip(instance: Instance) → float¶

Get the current camera near clipping distance.

Parameters:: instance (Instance) – Instance.
Returns:: Near clipping distance.
Return type:: float

set_camera_near_clip(instance: Instance, distance: float) → None¶

Set the current camera near clipping distance.

Parameters:

instance (Instance) – Instance.
distance (float) – Near clipping distance.

view¶

class View(position: Vector3, target: Vector3, up: Vector3 = (0.0, 1.0, 0.0))¶

Bases: object

Represent a viewpoint with position and target.

Up and direction doesn’t need to be perpendicular. However, having direction equal to zero or colinear with up will make an invalid view.

Parameters:

position (Vector3) – Observation position.
target (Vector3) – Target position.
up (Vector3, optional) – Up vector, defaults to Axis.up.

property direction: Vector3¶

Get normalized view vector.

Returns:: View vector normalized.
Return type:: Vector3

property distance: float¶

Get the distance between the observator and the target.

Returns:: View vector norm.
Return type:: float

class property front: View¶

Front view with X right, Y up and Z front.

Returns:: Front view.
Return type:: View

get_orientation(reference: View) → Rotation¶

Get orientation from given reference.

The rotation obtained goes from reference.direction and reference.real_up to self.direction and self.real_up.

Returns:: Rotation from given view to self.
Return type:: Rotation

property orientation: Rotation¶

Get orientation compared to the front view.

Returns:: Rotation from front view to self.
Return type:: Rotation

position: Vector3¶

property real_up: Vector3¶

Get effective up direction (right x direction).

Equal to up if up is perpendicular to direction and normalized.

Returns:: Real up direction normalized.
Return type:: Vector3

property right: Vector3¶

Get right direction relative to view (direction x up).

Returns:: Right direction normalized.
Return type:: Vector3

rotate_around_target(rotation: Rotation) → View¶

Rotate observation position around target.

Parameters:: rotation (Rotation) – Rotation to apply on observer.
Returns:: New rotated view.
Return type:: View

target: Vector3¶

translate(translation: Vector3) → View¶

Translate position and target in given direction.

Parameters:: translation (Vector3) – Translation to apply on position and target.
Returns:: New translated view.
Return type:: View

up: Vector3 = (0.0, 1.0, 0.0)¶

property vector: Vector3¶

Get view vector (target - position).

Returns:: View vector.
Return type:: Vector3

get_camera_view(instance: Instance) → View¶

Get the current camera view of an instance.

Parameters:: instance (Instance) – Instance.
Returns:: Camera view.
Return type:: View

set_camera_view(instance: Instance, view: View) → None¶

Set the current camera view of an instance.

Parameters:

instance (Instance) – Instance.
view (View) – New camera view.

loader¶

class Loader¶

Bases: ABC

Base class for all loaders.

Loader are used to load models from files into an instance.

Available loaders for a given instance depends on the loaded plugins.

The list of available loaders and supported extensions for a given instance can be queried using get_loaders(instance).

abstract get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

load_models(instance: Instance, path: str) → list[Model]¶

Load the given file into an instance and return the models.

Parameters:

instance (Instance) – Instance.
path (str) – Model(s) file path.

Returns:

List of created models.

Return type:

list[Model]

load_models_task(instance: Instance, path: str) → Future[list[Model]]¶

Asynchronous version of load_models.

Parameters:

instance (Instance) – Instance.
path (str) – Model(s) file path.

Returns:

Future to monitor the task.

Return type:

Future[list[Model]]

abstract class property name: str¶

Get the loader name.

Can be compared with LoaderInfo.name.

Returns:: Loader name.
Return type:: str

upload_models(instance: Instance, format: str, data: bytes) → list[Model]¶

Load models from binary data.

As the model format cannot be deduced from a path, it must be specified.

The format is the file extension without the dot, check the class variables to see supported formats (ex: MeshLoader.PLY).

Parameters:

instance (Instance) – Instance.
format (str) – Model format (see loader class variables).
data (bytes) – Model binary data.

Returns:

List of created models.

Return type:

list[Model]

upload_models_task(instance: Instance, format: str, data: bytes) → Future[list[Model]]¶

Asynchronous version of upload_models.

Parameters:

instance (Instance) – Instance.
format (str) – Model format (see loader class variables).
data (bytes) – Model binary data.

Returns:

Future to monitor the task.

Return type:

Future[list[Model]]

class LoaderInfo(name: str, extensions: list[str], schema: JsonSchema, binary: bool = False, plugin: str = '')¶

Bases: object

Loader description.

Parameters:

name (str) – Loader name.
extensions (list[str]) – Supported extensions without the dot.
schema (str) – Parameters JSON schema (low level).
binary (bool) – Wether the loader can load binary data.
schema – Plugin required to have the loader available.

binary: bool = False¶

extensions: list[str]¶

name: str¶

plugin: str = ''¶

schema: JsonSchema¶

class MeshLoader¶

Bases: Loader

Mesh loader.

Main supported formats are OBJ, PLY, STL and OFF.

Format support can be queried using get_loaders(instance).

OBJ: ClassVar[str] = 'obj'¶

OFF: ClassVar[str] = 'off'¶

PLY: ClassVar[str] = 'ply'¶

STL: ClassVar[str] = 'stl'¶

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶

Get the loader name.

Returns:: Loader name.
Return type:: str

class MhdVolumeLoader¶

Bases: Loader

MDH volume loader.

Supports .mhd file format.

MHD: ClassVar[str] = 'mhd'¶

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶

Get the loader name.

Returns:: Loader name.
Return type:: str

class RawVolumeLoader(dimensions: Vector3, spacing: Vector3, data_type: VolumeDataType)¶

Bases: Loader

Raw volume loader.

Supports .raw file format.

Parameters:

dimensions (Vector3.) – Volume 3D grid dimensions.
spacing – World-space dimensions of a voxel.
data_type (str.) – Type of data to interpret the volume bytes.

RAW: ClassVar[str] = 'raw'¶

data_type: VolumeDataType¶

dimensions: Vector3¶

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶

Get the loader name.

Returns:: Loader name.
Return type:: str

spacing: Vector3¶

class VolumeDataType(value)¶

Bases: Enum

Supported volume voxel data types.

DOUBLE = 'double'¶

FLOAT = 'float'¶

HALF_FLOAT = 'half_float'¶

SHORT = 'short'¶

UNSIGNED_CHAR = 'unsigned_char'¶

UNSIGNED_SHORT = 'unsigned_short'¶

get_loaders(instance: Instance) → list[LoaderInfo]¶

Retreive all available loaders from an instance.

Parameters:: instance (Instance) – Instance.
Returns:: List of loader descriptions.
Return type:: list[LoaderInfo]

renderer¶

class InteractiveRenderer(samples_per_pixel: int = 1, max_ray_bounces: int = 3, background_color: Color4 = (0.004, 0.016, 0.102, 0.0), enable_shadows: bool = True, ambient_occlusion_samples: int = 0)¶

Bases: Renderer

Default renderer used for fast rendering (streaming, tests).

Parameters:

enable_shadows (bool, optional.) – Enable shadows, defaults to True.
ambient_occlusion_samples (int, optional.) – AO samples, defaults to 0.

ambient_occlusion_samples: int = 0¶

enable_shadows: bool = True¶

get_additional_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

class property name: str¶

Get renderer name.

Returns:: Renderer name.
Return type:: str

update_additional_properties(message: dict[str, Any]) → None¶: Low level API to deserialize from JSON.

class ProductionRenderer(samples_per_pixel: int = 128, max_ray_bounces: int = 7, background_color: Color4 = (0.004, 0.016, 0.102, 0.0))¶

Bases: Renderer

Production renderer for expensive quality rendering.

Overrides default parameters for higher quality.

Parameters:

samples_per_pixel (int, optional.) – Accumulation, defaults to 128.
max_ray_bounces (int, optional.) – Ray bounces, defaults to 7.

get_additional_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

max_ray_bounces: int = 7¶

class property name: str¶

Get renderer name.

Returns:: Renderer name.
Return type:: str

samples_per_pixel: int = 128¶

update_additional_properties(message: dict[str, Any]) → None¶: Low level API to deserialize from JSON.

class Renderer(samples_per_pixel: int = 1, max_ray_bounces: int = 3, background_color: Color4 = (0.004, 0.016, 0.102, 0.0))¶

Bases: ABC

Base class for all renderer types.

Accumulation reduce the aliasing but increase the computation time.

Ray bounces allow non-emissive objects to light other objects.

Parameters:

samples_per_pixel (int, optional.) – Accumulation, defaults to 1.
max_ray_bounces (int, optional.) – Ray bounces, defaults to 3.
background_color (Color4, optional.) – Background color, defaults to BBP transparent.

background_color: Color4 = (0.004, 0.016, 0.102, 0.0)¶

classmethod from_properties(message: dict[str, Any]) → T¶: Low level API to deserialize from JSON.

abstract get_additional_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

get_properties() → dict[str, Any]¶: Low level API to serialize to JSON.

get_properties_with_name() → dict[str, Any]¶: Low level API to serialize to JSON.

max_ray_bounces: int = 3¶

abstract class property name: str¶

Get renderer name.

Returns:: Renderer name.
Return type:: str

samples_per_pixel: int = 1¶

abstract update_additional_properties(message: dict[str, Any]) → None¶: Low level API to deserialize from JSON.

update_properties(message: dict[str, Any]) → None¶: Low level API to deserialize from JSON.

get_renderer(instance: Instance, renderer_type: type[T]) → T¶

Retreive the current renderer from an instance.

Current renderer and given renderer type must be the same.

Current renderer can be queried using get_rendere_name.

Parameters:

instance (Instance) – Instance.
renderer_type (type[T]) – Type of the current renderer.

Returns:

Current renderer.

Return type:

T

get_renderer_name(instance: Instance) → str¶

Retreive the name of the current renderer of an instance.

Parameters:: instance (Instance) – Instance.
Returns:: Renderer name.
Return type:: str

set_renderer(instance: Instance, renderer: Renderer) → None¶

Set the current renderer of an instance.

Parameters:

instance (Instance) – Instance.
renderer (Renderer) – New renderer.

image¶

class Image(accumulate: bool = True, force_download: bool = True, jpeg_quality: int = 100)¶

Bases: object

Helper class to take an image of an instance with current settings.

Note that no render will occur if nothing has changed since last call (same context and max accumulation reached).

If accumulate is True, the instance will render images and accumulate them until current renderer samples_per_pixel is reached. Otherwise only one image will be rendered.

If force_download is True, the framebuffer image will always be downloaded. Otherwise it will be downloaded only when something new has been rendered.

Check ImageInfo.data to see if something has been downloaded.

Parameters:

accumulate (bool, optional) – Render all samples at once, defaults to True.
force_download (bool, optional) – Force download, defaults to True.
jpeg_quality (int) – JPEG quality.

accumulate: bool = True¶

download(instance: Instance, format: ImageFormat = ImageFormat.PNG, render: bool = True) → ImageInfo¶

Try to render and download an image.

Parameters:

instance (Instance) – Instance.
format (bool, optional) – Image encoding format, defaults to ImageFormat.PNG
render – Render image(s) if needed, defaults to True

Returns:

Render status and image data.

Return type:

ImageInfo

force_download: bool = True¶

jpeg_quality: int = 100¶

render(instance: Instance) → ImageInfo¶

Try to render an image without downloading it.

Parameters:: instance (Instance) – Instance.
Returns:: Render status.
Return type:: ImageInfo

save(instance: Instance, path: str, render: bool = True) → ImageInfo¶

Try to render an image and save it if rendered.

Parameters:

instance (Instance) – Instance.
path (str) – Path to save image.

Returns:

Render status and image data.

Return type:

ImageInfo

class ImageInfo(accumulation: int, max_accumulation: int, data: bytes)¶

Bases: object

Result of an image rendering with status and encoded data.

If nothing has been downloaded, data is empty.

Parameters:

accumulation (int) – Current accumulation after render.
max_accumulation (int) – Accumulation limit to stop rendering.
data (bytes) – Encoded image data, can be empty.

accumulation: int¶

data: bytes¶

property full_quality: bool¶

Check if max accumulation has been reached.

Returns:: True if image is full quality.
Return type:: bool

max_accumulation: int¶

snapshot¶

class ImageMetadata(title: str, description: str, where_used: str, keywords: list[str])¶

Bases: object

Metadata information that will be embeded into the image.

Parameters:

title (str) – Image title.
description (str) – Image description.
where_used (str) – Event for which the image was created.
keywords (list[str]) – List of keywords that describe the image content.

description: str¶

keywords: list[str]¶

title: str¶

where_used: str¶

Bases: object

Helper class to take a snapshot of an instance with custom settings.

Snapshots create a temporary context in the instance to avoid changing current instance settings.

For None parameters, the current values of the instance are used.

Parameters:

resolution (Resolution | None, optional) – Image resolution, defaults to None.
camera (Camera | None, optional) – Camera used to render, defaults to None.
renderer (Renderer | None, optional) – Renderer used to render, defaults to None.
frame (int | None, optional) – Simulation index, defaults to None.
jpeg_quality (int, optional) – JPEG quality if format is JPEG, defaults to 100%.
metadata (ImageMetadata | None, optional) – Metadata information to embed into the image.

camera: Camera | None = None¶

download(instance: Instance, format: ImageFormat = ImageFormat.PNG) → bytes¶

Download the rendered image as bytes at given format.

Parameters:

instance (Instance) – Instance.
path (str) – Output file.

Returns:

Image data.

Return type:

bytes

download_task(instance: Instance, format: ImageFormat = ImageFormat.PNG) → Future[bytes]¶

Asynchronous version of download.

Parameters:

instance (Instance) – Instance.
path (str) – Output file.

Returns:

Future to monitor the task.

Return type:

Future[bytes]

frame: int | None = None¶

jpeg_quality: int = 100¶

metadata: ImageMetadata | None = None¶

renderer: Renderer | None = None¶

resolution: Resolution | None = None¶

save(instance: Instance, path: str) → None¶

Download and save the snapshot locally under given file.

Path is on the local machine (running current script).

Parameters:

instance (Instance) – Instance.
path (str) – Output file.

save_remotely(instance: Instance, path: str) → None¶

Save the snapshot remotely under given file.

Path is on the remote machine (running instance backend).

Parameters:

instance (Instance) – Instance.
path (str) – Output file.

save_remotely_task(instance: Instance, path: str) → Future[None]¶

Asynchronous version of save_remotely.

Parameters:

instance (Instance) – Instance.
path (str) – Output file.

Returns:

Future to monitor the task.

Return type:

Future[None]

save_task(instance: Instance, path: str) → Future[None]¶

Asynchronous version of save.

Parameters:

instance (Instance) – Instance.
path (str) – Output file.

Returns:

Future to monitor the task.

Return type:

Future[None]

pick¶

class PickResult(position: Vector3, model_id: int, metadata: Any)¶

Bases: object

Information about the model found at an inspected screen position.

Metadata depend on the kind of model found at given position and are specific to the primitive (subpart) hitted.

Parameters:

position (Vector3) – World position matching screen coordinates.
model_id (int) – ID of them model at screen position.
metadata (Any) – Information about the model primitive at given position.

metadata: Any¶

model_id: int¶

position: Vector3¶

pick(instance: Instance, position: Vector2) → PickResult | None¶

Pick a given screen position and inspect it.

Screen position must be normalized with [0, 0] being bottom-left of and [1, 1] top-right.

If a model is found on given coordinates, return its ID with the world position corresponding to the pixel where the model was rendered.

If no models are found, then None is returned.

Parameters:

instance (Instance) – Instance to inspect.
x (float) – Screen position X normalized.

Returns:

Information about model in given XY if any, otherwise None.

Return type:

PickResult | None