Scene

SceneBase and quaternion math utilities in WiTwin Core

Overview #

SceneBase is the abstract base class for all WiTwin scenes. Both witwin.channel.Scene and witwin.maxwell.Scene inherit from it. It manages lists of structures, sources, monitors, and metadata.

Users do not instantiate SceneBase directly — use witwin.channel.Scene or witwin.maxwell.Scene instead.

SceneBase #

Constructor #

SceneBase(
    structures=None,
    sources=None,
    monitors=None,
    metadata=None,
    device="cuda",
    verbose=False,
)

Parameter	Type	Default	Description
`structures`	`list \| None`	`None`	Initial list of `Structure` objects
`sources`	`list \| None`	`None`	Initial list of source objects
`monitors`	`list \| None`	`None`	Initial list of monitor objects
`metadata`	`dict \| None`	`None`	Optional metadata
`device`	`str`	`"cuda"`	PyTorch device string
`verbose`	`bool`	`False`	Enable verbose logging

Attributes #

Attribute	Description
`scene.structures`	List of `Structure` objects
`scene.sources`	List of source objects
`scene.monitors`	List of monitor objects
`scene.metadata`	Scene metadata dictionary
`scene.device`	Device string
`scene.verbose`	Verbose flag

Quaternion Math #

WiTwin Core provides quaternion utilities for rotation operations. These are used internally by geometry primitives and can be used directly for custom rotation workflows.

from witwin.core import (
    quat_identity,
    quat_from_euler,
    quat_multiply,
    quat_to_rotation_matrix,
    quat_to_rotation_matrix_np,
)

`quat_identity()`#

Returns the identity quaternion (0, 0, 0, 1).

`quat_from_euler(roll, pitch, yaw)`#

Construct a quaternion from Euler angles in radians.

q = quat_from_euler(roll=0.0, pitch=0.0, yaw=1.57)

`quat_multiply(q1, q2)`#

Multiply two quaternions — equivalent to composing two rotations.

q = quat_multiply(q1, q2)

`quat_to_rotation_matrix(q)`#

Convert a quaternion to a 3×3 rotation matrix as a PyTorch tensor.

R = quat_to_rotation_matrix(q)  # returns torch.Tensor of shape (3, 3)

`quat_to_rotation_matrix_np(q)`#

Convert a quaternion to a 3×3 rotation matrix as a NumPy array.

R = quat_to_rotation_matrix_np(q)  # returns np.ndarray of shape (3, 3)

Next Steps #

Mitsuba bridge — convert scenes to Mitsuba format
Geometry API — geometry primitive reference