utils¶

Brayns utilities.

This subpackage contains all functionalities that are commonly used inside and outside the main package and are not directly related to the Web API.

It includes helpers for algebra, imaging or coloring and the base exception.

vector¶

class Axis¶

Bases: object

Helper class to store the principal axes of Brayns coordinate system.

class property back: Vector3¶

3D vector with XYZ components.

Provides dot and cross product in addition to Vector operators.

Parameters:

x (float) – X component.
y (float) – Y component.
z (float) – Z component.

class property down: Vector3¶

3D vector with XYZ components.

Provides dot and cross product in addition to Vector operators.

Parameters:

x (float) – X component.
y (float) – Y component.
z (float) – Z component.

class property front: Vector3¶

3D vector with XYZ components.

Provides dot and cross product in addition to Vector operators.

Parameters:

x (float) – X component.
y (float) – Y component.
z (float) – Z component.

class property left: Vector3¶

3D vector with XYZ components.

Provides dot and cross product in addition to Vector operators.

Parameters:

x (float) – X component.
y (float) – Y component.
z (float) – Z component.

class property right: Vector3¶

3D vector with XYZ components.

Provides dot and cross product in addition to Vector operators.

Parameters:

x (float) – X component.
y (float) – Y component.
z (float) – Z component.

class property up: Vector3¶

3D vector with XYZ components.

Provides dot and cross product in addition to Vector operators.

Parameters:

x (float) – X component.
y (float) – Y component.
z (float) – Z component.

class property x: Vector3¶

3D vector with XYZ components.

Provides dot and cross product in addition to Vector operators.

Parameters:

x (float) – X component.
y (float) – Y component.
z (float) – Z component.

class property y: Vector3¶

3D vector with XYZ components.

Provides dot and cross product in addition to Vector operators.

Parameters:

x (float) – X component.
y (float) – Y component.
z (float) – Z component.

class property z: Vector3¶

3D vector with XYZ components.

Provides dot and cross product in addition to Vector operators.

Parameters:

x (float) – X component.
y (float) – Y component.
z (float) – Z component.

class Vector2(x: float = 0.0, y: float = 0.0)¶

Bases: Vector[float]

2D vector with XY components.

Provides dot product in addition to Vector operators.

Parameters:

x (float) – X component.
y (float) – Y component.

property x: float¶

property y: float¶

class Vector3(x: float = 0.0, y: float = 0.0, z: float = 0.0)¶

Bases: Vector2

3D vector with XYZ components.

Provides dot and cross product in addition to Vector operators.

Parameters:

x (float) – X component.
y (float) – Y component.
z (float) – Z component.

cross(other: Vector3) → Vector3¶

static from_vector2(value: Vector2, z: float = 0.0) → Vector3¶

class property one: Vector3¶

3D vector with XYZ components.

Provides dot and cross product in addition to Vector operators.

Parameters:

x (float) – X component.
y (float) – Y component.
z (float) – Z component.

property x: float¶

property xy: Vector2¶

property xz: Vector2¶

property y: float¶

property yz: Vector2¶

property z: float¶

class property zero: Vector3¶

3D vector with XYZ components.

Provides dot and cross product in addition to Vector operators.

Parameters:

x (float) – X component.
y (float) – Y component.
z (float) – Z component.

componentwise_max(values: list[Vector3]) → Vector3¶

Return maximum of each component among values.

If values is empty, zero is returned.

Parameters:: values (list[Vector3]) – List of vectors.
Returns:: Max value for each component.
Return type:: Vector3

componentwise_min(values: list[Vector3]) → Vector3¶

Return minimum of each component among values.

If values is empty, zero is returned.

Parameters:: values (list[Vector3]) – List of vectors.
Returns:: Min value for each component.
Return type:: Vector3

bounds¶

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

Bases: object

Axis aligned bounding box.

Parameters:

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

property center: Vector3¶

Compute the center point of the bounds.

Returns:: 3D point of the center.
Return type:: Vector3

property corners: list[Vector3]¶

List the 8 corners of the box.

Returns:: List of corner points.
Return type:: list[Vector3]

property depth: float¶

Compute the depth of the bounds.

Returns:: size.z.
Return type:: float

class property empty: Bounds¶

Create empty bounds.

Returns:: Empty bounds in [0, 0, 0].
Return type:: Bounds

property height: float¶

Compute the height of the bounds.

Returns:: size.y.
Return type:: float

max: Vector3¶

min: Vector3¶

static of(values: list[Vector3]) → Bounds¶

Compute the bounds of given 3D points.

Parameters:: values (list[Vector3]) – List of points to include in bounds.
Returns:: Points boundary
Return type:: Bounds

rescale(scale: Vector3) → Bounds¶

Multiply limits by given scale componentwise.

Parameters:: scale (Vector3) – Scale XYZ.
Returns:: Rescaled bounds.
Return type:: Bounds

rotate(rotation: Rotation, center: Vector3 = (0.0, 0.0, 0.0)) → Bounds¶

Rotate bounds by given value around optional center.

Parameters:

rotation (Rotation) – Rotation to apply.
center (Vector3, optional) – Rotation center, defaults to Vector3.zero.

Returns:

New axis aligned bounds after rotation.

Return type:

Bounds

property size: Vector3¶

Compute the size of the bounds.

Returns:: Size XYZ (width, height, depth).
Return type:: Vector3

translate(translation: Vector3) → Bounds¶

Translate bounds by given value.

Parameters:: translation (Vector3) – Translation for min and max.
Returns:: Translated bounds.
Return type:: Bounds

class property unit: Bounds¶

Create unit bounds (size = [1, 1, 1]).

Returns:: Unit bounds centered in [0, 0, 0].
Return type:: Bounds

property width: float¶

Compute the width of the bounds.

Returns:: size.x.
Return type:: float

merge_bounds(values: list[Bounds]) → Bounds¶

Compute the union of all given bounds.

Returns Bounds.empty if values are empty.

Assume that all bounds are valid (ie min <= max for each component).

Parameters:: values (list[Bounds]) – Bounds to merge.
Returns:: Union of all bounds in values.
Return type:: Bounds

rotation¶

class CameraRotation¶

Bases: object

Helper class to store camera rotations to reach different views.

All rotations are relative to front view (X-right, Y-up, Z-front).

class property back: Rotation¶: Arbitrary 3D rotation using normalized quaternion internally.

class property bottom: Rotation¶: Arbitrary 3D rotation using normalized quaternion internally.

class property front: Rotation¶: Arbitrary 3D rotation using normalized quaternion internally.

class property left: Rotation¶: Arbitrary 3D rotation using normalized quaternion internally.

class property right: Rotation¶: Arbitrary 3D rotation using normalized quaternion internally.

class property top: Rotation¶: Arbitrary 3D rotation using normalized quaternion internally.

class ModelRotation¶

Bases: object

Helper class to store model rotations to reach different views.

All rotations are relative to front view (X-right, Y-up, Z-front).

class property back: Rotation¶: Arbitrary 3D rotation using normalized quaternion internally.

class property bottom: Rotation¶: Arbitrary 3D rotation using normalized quaternion internally.

class property front: Rotation¶: Arbitrary 3D rotation using normalized quaternion internally.

class property left: Rotation¶: Arbitrary 3D rotation using normalized quaternion internally.

class property right: Rotation¶: Arbitrary 3D rotation using normalized quaternion internally.

class property top: Rotation¶: Arbitrary 3D rotation using normalized quaternion internally.

class Rotation(quaternion: Quaternion)¶

Bases: object

Arbitrary 3D rotation using normalized quaternion internally.

Direct construction, prefer from_quaternion.

property angle_degrees: float¶

Get rotation angle in degrees.

Returns:: Rotation angle.
Return type:: Vector3

property angle_radians: float¶

Get rotation angle in radians.

Returns:: Rotation angle.
Return type:: Vector3

apply(value: Vector3, center: Vector3 = (0.0, 0.0, 0.0)) → Vector3¶

Apply rotation on value around center.

Parameters:

value (Vector3) – Vector to rotate.
center (Vector3, optional) – Rotation center, defaults to Vector3.zero.

Returns:

Rotated value.

Return type:

Vector3

property axis: Vector3¶

Get rotation axis.

Returns:: Normalized rotation axis.
Return type:: Vector3

static between(source: Vector3, destination: Vector3) → Rotation¶

Compute the minimal arc rotation between two vectors.

Vectors must not be zero.

Parameters:

source (Vector3) – Original direction.
destination (Vector3) – Final direction.

Returns:

Rotation object.

Return type:

Rotation

property euler_degrees: Vector3¶

Get rotation as euler angles XYZ in degrees.

Returns:: Euler angles.
Return type:: Vector3

property euler_radians: Vector3¶

Get rotation as euler angles XYZ in radians.

Returns:: Euler angles.
Return type:: Vector3

static from_axis_angle(axis: Vector3, angle: float, degrees: bool = False) → Rotation¶

Construct a rotation of angle around axis.

Axis must not be zero.

Parameters:

axis (Vector3) – Rotation axis (will be normalized).
angle (float) – Rotation angle.
degrees (bool, optional) – Angle is provided in degrees, defaults to False.

Returns:

Rotation object.

Return type:

Rotation

static from_euler(euler: Vector3, degrees: bool = False) → Rotation¶

Construct a rotation from euler angle in XYZ order.

Parameters:

euler (Vector3) – XYZ euler angles.
degrees (bool, optional) – Euler are provided in degrees, defaults to False.

Returns:

Rotation object.

Return type:

Rotation

static from_quaternion(quaternion: Quaternion) → Rotation¶

Construct a rotation using a quaternion (will be normalized).

Parameters:: quaternion (Quaternion) – Quaternion representing rotation.
Returns:: Rotation object.
Return type:: Rotation

class property identity: Rotation¶

Construct a rotation with no effects.

Returns:: Identity rotation.
Return type:: Rotation

property inverse: Rotation¶

Get rotation such as self * self.inverse == Rotation.identity.

Returns:: Inverse rotation.
Return type:: Rotation

property quaternion: Quaternion¶

Get rotation as normalized quaternion.

Returns:: Normalized quaternion.
Return type:: Quaternion

then(other: Rotation) → Rotation¶

Combine rotations to be equivalent to self then other.

Parameters:: other (Rotation) – Rotation to apply after self.
Returns:: Rotation object.
Return type:: Rotation

euler(x: float, y: float, z: float, degrees: bool = False) → Rotation¶

Shortcut to build a rotation from euler angles.

Parameters:

x (float) – X rotation.
y (float) – Y rotation.
z (float) – Z rotation.
degrees (bool, optional) – Wether given angles are in degrees, defaults to False

Returns:

Rotation corresponding to angles.

Return type:

Rotation

color¶

class Color3(r: float = 0.0, g: float = 0.0, b: float = 0.0)¶

Bases: Vector[float]

Color with RGB normalized components.

Color3 are vectors and can be manipulated as such.

Parameters:

r (float) – Red component 0-1.
g (float) – Green component 0-1.
b (float) – Blue component 0-1.

property b: float¶

class property bbp_background: T¶

Create a color of the BBP standard background (~blue).

Returns:: BBP background color [0.004, 0.016, 0.102].
Return type:: Color3

class property black: T¶

Create a black color.

Returns:: Black color [0, 0, 0].
Return type:: Color3

class property blue: T¶

Create a blue color.

Returns:: blue color [0, 0, 1].
Return type:: Color3

property g: float¶

class property green: T¶

Create a green color.

Returns:: green color [0, 1, 0].
Return type:: Color3

property r: float¶

class property red: T¶

Create a red color.

Returns:: red color [1, 0, 0].
Return type:: Color3

class property white: T¶

Create a white color.

Returns:: White color [1, 1, 1].
Return type:: Color3

class Color4(r: float = 0.0, g: float = 0.0, b: float = 0.0, a: float = 1.0)¶

Bases: Color3

Color with RGBA normalized components.

Color4 are Color3 and can be manipulated as such but with alpha channel.

Opaque is alpha = 1 and fully transparent is alpha = 0.

Color3 standard colors, if used from Color4, will have an alpha of 1.

Parameters:: a (float, optional) – Alpha component, defaults to 1.0.

property a: float¶

static from_color3(color: Color3, alpha: float = 1.0) → Color4¶

Helper to build a Color4 from a Color3.

Parameters:

color (Color3) – Color3 to convert.
alpha (float, optional) – Alpha channel, defaults to 1.0

Returns:

Color4 converted.

Return type:

Color4

property opaque: Color4¶

Create an identical color but with alpha = 1.

Returns:: Color but fully opaque.
Return type:: Color4

property transparent: Color4¶

Create an identical color but with alpha = 0.

Returns:: Color but fully transparent.
Return type:: Color4

property without_alpha: Color3¶

Helper class to create a Color3 from a Color4.

Returns:: Color3 converted.
Return type:: Color3

parse_hex_color(value: str) → Color3¶

Parse an hexadecimal color string to Color3.

The string can be just digits (0a12f5), prefixed with a hash (#0a12f5) or with 0x (0x0a12f5).

Parameters:: value (str) – Color code.
Returns:: Color parsed.
Return type:: Color3

json_schema¶

class JsonSchema(title: str = '', description: str = '', type: JsonType = JsonType.UNDEFINED, read_only: bool = False, write_only: bool = False, default: Any = None, minimum: float | None = None, maximum: float | None = None, items: JsonSchema | None = None, min_items: int | None = None, max_items: int | None = None, properties: dict[str, JsonSchema] = <factory>, required: list[str] = <factory>, additional_properties: bool | JsonSchema | None = None, one_of: list[JsonSchema] = <factory>, enum: list[Any] = <factory>)¶

Bases: object

JSON schema describing JSON-RPC message format.

Parameters:

title (str) – Title (class name).
description (str) – Human readable description.
type (JsonType) – JSON type (null, boolean, number, string, object, …).
read_only (bool) – If true, this field cannot be assigned.
write_only (bool) – If true, this field cannot get retreived.
default (Any) – Optional default value.
minimum (float | None) – Optional minimum value for numbers.
maximum (float | None) – Optional maximum value for numbers.
items (JsonSchema | None) – Optional item schema value for arrays.
min_items (int | None) – Optional minimum item count for arrays.
max_items (int | None) – Optional maximum item count for arrays.
properties (dict[str, JsonSchema]) – Optional fixed properties schema for objects.
required (list[str]) – Optional list of required properties for objects.
additional_properties (bool | JsonSchema | None) – Schema of additional properties for objects. If False then no additional properties are allowed (only fixed). If None then any additional properties are allowed (usually ignored).
one_of (list[JsonSchema]) – If not empty, the schema is a union of several schemas.
enum (list[Any]) – If not empty, the message must be in these values.

additional_properties: bool | JsonSchema | None = None¶

default: Any = None¶

description: str = ''¶

enum: list[Any]¶

items: JsonSchema | None = None¶

max_items: int | None = None¶

maximum: float | None = None¶

min_items: int | None = None¶

minimum: float | None = None¶

one_of: list[JsonSchema]¶

properties: dict[str, JsonSchema]¶

read_only: bool = False¶

required: list[str]¶

title: str = ''¶

type: JsonType = 'undefined'¶

write_only: bool = False¶

class JsonType(value)¶

Bases: Enum

Enumeration of available JSON types.

The value is the string from the JSON schema standard.

Parameters:

UNDEFINED – Any type is allowed.
NULL – No types are allowed.
BOOLEAN – Boolean.
INTEGER – Integral number.
NUMBER – Any number.
STRING – String.
ARRAY – Array.
OBJECT – Object.

ARRAY = 'array'¶

BOOLEAN = 'boolean'¶

INTEGER = 'integer'¶

NULL = 'null'¶

NUMBER = 'number'¶

OBJECT = 'object'¶

STRING = 'string'¶

UNDEFINED = 'undefined'¶

deserialize_schema(message: dict[str, Any]) → JsonSchema¶

Deserialize dictionary to JSON schema.

Parameters:: message (dict[str, Any]) – Parsed JSON object.
Returns:: JSON schema with supported fields.
Return type:: JsonSchema

serialize_schema(schema: JsonSchema) → dict[str, Any]¶

Serialize JSON schema to dictionary.

Parameters:: schema (JsonSchema) – JSON schema.
Returns:: Dictionary that can be stringified to raw JSON.
Return type:: dict[str, Any]

error¶

exception Error¶

Bases: Exception

Base class of all Brayns exceptions.

Can be used to catch only brayns specific errors.

image¶

class ImageFormat(value)¶

Bases: Enum

Enumeration of all supported image format.

Values are the image format file extension without the dot.

Parameters:

JPEG – JPEG format, smaller but lose quality.
PNG – PNG format, bigger but lossless.

JPEG = 'jpg'¶

PNG = 'png'¶

class Resolution(width: int, height: int)¶

Bases: Vector[int]

Image resolution.

Resolution is a Vector of integers and can be handled as such.

Parameters:

width (int) – Image width in pixels.
height (int) – Image height in pixels.

property aspect_ratio: float¶

Get aspect ratio.

Returns:: Width / height.
Return type:: float

class property full_hd: Resolution¶

Create a full HD (1920x1080) resolution.

Returns:: Full HD resolution.
Return type:: Resolution

property height: int¶

class property production: Resolution¶

Create a production (15360x8640) resolution.

Returns:: Production resolution.
Return type:: Resolution

class property ultra_hd: Resolution¶

Create a 4K (3840x2160) resolution.

Returns:: Ultra HD resolution.
Return type:: Resolution

property width: int¶

parse_image_format(filename: str | Path) → ImageFormat¶

Parse the image format from a file path using its extension.

Supports both string and Path input.

Parameters:: filename (str | Path) – Image file path.
Returns:: Image format.
Return type:: ImageFormat

plane_equation¶

class PlaneEquation(a: float, b: float, c: float, d: float = 0.0)¶

Bases: Vector[float]

Plane equation satisfying ax + by + cz + d = 0.

Normal and direction point to the upper side of the plane.

Parameters:

a (float) – A component.
b (float) – B component.
c (float) – C component.
d (float) – D component.

property a: float¶

property b: float¶

property c: float¶

property d: float¶

property direction: Vector3¶

property normal: Vector3¶

static of(normal: Vector3, point: Vector3) → PlaneEquation¶

Compute the equation of a plane from its normal and a point.

Parameters:

normal (Vector3) – Plane normal vector.
point (Vector3) – Any point of the plane.

Returns:

Plane equation.

Return type:

PlaneEquation

quaternion¶

class Quaternion(x: float = 0.0, y: float = 0.0, z: float = 0.0, w: float = 1.0)¶

Bases: Vector[float]

Quaternion with XYZW components.

Provides vector operations (componentwise) and quaternion special operators (multiplication, conjugate, etc).

Parameters:

x (float, optional) – X component, defaults to 0.
y (float, optional) – Y component, defaults to 0.
z (float, optional) – Z component, defaults to 0.
w (float, optional) – W component, defaults to 1.

property angle_degrees: float¶

property angle_radians: float¶

property axis: Vector3¶

property conjugate: Quaternion¶

class property identity: Quaternion¶

Quaternion with XYZW components.

Provides vector operations (componentwise) and quaternion special operators (multiplication, conjugate, etc).

Parameters:

x (float, optional) – X component, defaults to 0.
y (float, optional) – Y component, defaults to 0.
z (float, optional) – Z component, defaults to 0.
w (float, optional) – W component, defaults to 1.

property inverse: Quaternion¶

property w: float¶

property x: float¶

property xyz: Vector3¶

property y: float¶

property z: float¶

transform¶

class Transform(translation: ~brayns.utils.vector.Vector3 = (0.0, 0.0, 0.0), rotation: ~brayns.utils.rotation.Rotation = <brayns.utils.rotation.Rotation object>, scale: ~brayns.utils.vector.Vector3 = (1.0, 1.0, 1.0))¶

Bases: object

3D transformation.

Used to move models in 3D space.

It is equivalent to a TRS matrix multiplication.

It means we first scale the point at the origin, then rotate around the same origin and finally we translate it to its position.

Parameters:

translation (Vector3, optional) – Translation, defaults to zero.
rotation (Rotation, optional) – Rotation, defaults to identity.
scale (Vector3, optional) – Scaling, defaults to one.

apply(value: Vector3) → Vector3¶

Apply the transform to the given value.

Parameters:: value (Vector3) – 3D position to transform.
Returns:: Transformed value.
Return type:: Vector3

class property identity: Transform¶

Create an identity transform (doesn’t do anything).

Returns:: Identity transform.
Return type:: Transform

static rotate(rotation: Rotation, center: Vector3 = (0.0, 0.0, 0.0)) → Transform¶

Create a transform to rotate around a given center.

Rotation around a center is equivalent to a rotation around the origin and a translation of center - rotation.apply(center).

Parameters:

rotation (Rotation) – Rotation to apply.
center (Vector3, optional) – Rotation center, defaults to zero.

Returns:

Transform.

Return type:

Transform

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

scale: Vector3 = (1.0, 1.0, 1.0)¶

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