voraus_3d_visu (Python)
A Python package for creating web-based 3D visualizations.
- class voraus_3d_visu.Visu(http_uri, clear=True, ignore_meta_check=False, clear_all=False, identifier=None)
Bases:
MeshStandardMaterialTrait,MeshBasicMaterialTrait,LineBasicMaterialTrait,PointsMaterialTrait,BoxTrait,SphereTrait,LineTrait,CylinderTrait,CameraTrait,AxesTrait,ModelTrait,TextPanelTrait,ConfigTrait,AnchorInstructionsTrait,LiveTrait,ObjTrait,PointCloudTraitDefines the client for the 3D visualization service.
Initializes the client for the 3D visualization service.
- Parameters:
http_uri (
str) – The Uniform Resource Identifier of the server to connect to.clear (
bool) – Whether to send a clear request for all objects and materials (not models) with the identifier associated to this client to the server. Defaults to True.ignore_meta_check (
bool) – Ignore server version and name check.clear_all (
bool) – Whether to send a clear request to clear everything to the server.identifier (
str|None) – A client identifier which marks the originating source of objects and materials. Defaults to None.
- delete(obj)
Deletes an object from the 3D visualization.
- Parameters:
obj (
Obj) – The object to delete.- Return type:
None
- connection()
A context manager for the 3D visualization connection.
- Yields:
An empty generator guarding a connection.
- Return type:
Generator[None,None,None]
- add_axes(position=None, rotation=None, quaternion=None, scale=None, visible=True, identifier=None)
Adds an axes helper object.
- Parameters:
position (
list[float] |None) – The initial position of the object to add. Defaults to None.rotation (
list[float] |None) – The initial rotation (Euler(XYZ) in radian) of the object to add. Defaults to None.quaternion (
list[float] |None) – The initial quaternion (XYZW) of the object to add. Defaults to None.scale (
list[float] |None) – The initial scale of the object to add. Defaults to None.visible (
bool) – The initial visibility of the object to add. Defaults to True.identifier (
int|str|None) – The identifier of the axes. If None the identifier gets assigned by the server. Defaults to None.
- Return type:
- Returns:
The added object.
- add_box(position=None, rotation=None, quaternion=None, scale=None, visible=True, width=1.0, height=1.0, depth=1.0, width_segments=1, height_segments=1, depth_segments=1, material=None, identifier=None)
Adds a box object.
- Parameters:
position (
list[float] |None) – The initial position of the object to add. Defaults to None.rotation (
list[float] |None) – The initial rotation (Euler(XYZ) in radian) of the object to add. Defaults to None.quaternion (
list[float] |None) – The initial quaternion (XYZW) of the object to add. Defaults to None.scale (
list[float] |None) – The initial scale of the object to add. Defaults to None.visible (
bool) – The initial visibility of the object to add. Defaults to True.width (
float) – The width of the object. Defaults to 1.0.height (
float) – The height of the object. Defaults to 1.0.depth (
float) – The depth of the object. Defaults to 1.0.width_segments (
int) – The number of width segments. Defaults to 1.height_segments (
int) – The number of height segments. Defaults to 1.depth_segments (
int) – The number of depth segments. Defaults to 1.material (
MeshStandardMaterial|MeshBasicMaterial|None) – The material of the object. Defaults to None.identifier (
int|str|None) – The identifier of the box. If None the identifier gets assigned by the server. Defaults to None.
- Return type:
- Returns:
The added object.
- add_camera(position=None, rotation=None, quaternion=None, scale=None, visible=True, fov=None, distance_min=None, distance_max=None, screen_space_panning=None, target=None, active=False, identifier=None)
Adds a camera object.
- Parameters:
position (
list[float] |None) – The initial position of the object to add. Defaults to None.rotation (
list[float] |None) – The initial rotation (Euler(XYZ) in radian) of the object to add. Defaults to None.quaternion (
list[float] |None) – The initial quaternion (XYZW) of the object to add. Defaults to None.scale (
list[float] |None) – The initial scale of the object to add. Defaults to None.visible (
bool) – The initial visibility of the object to add. Defaults to True.fov (
float|None) – The field of view of the camera. Defaults to None.distance_min (
float|None) – The minimum orbit distance. Defaults to None.distance_max (
float|None) – The maximum orbit distance. Defaults to None.screen_space_panning (
bool|None) – Whether screen space panning is enabled. Defaults to None.target (
list[float] |None) – The orbit target as [x, y, z]. Defaults to None.active (
bool) – Whether the camera becomes the active camera. Defaults to False.identifier (
int|str|None) – The identifier of the camera. If None the identifier gets assigned by the server. Defaults to None.
- Return type:
Camera- Returns:
The added object.
- add_cylinder(position=None, rotation=None, quaternion=None, scale=None, visible=True, radius_top=1.0, radius_bottom=1.0, height=1.0, radial_segments=32, height_segments=1, open_ended=False, theta_start=0, theta_length=6.283185307179586, material=None, identifier=None)
Adds a cylinder object.
- Parameters:
position (
list[float] |None) – The initial position of the object to add. Defaults to None.rotation (
list[float] |None) – The initial rotation (Euler(XYZ) in radian) of the object to add. Defaults to None.quaternion (
list[float] |None) – The initial quaternion (XYZW) of the object to add. Defaults to None.scale (
list[float] |None) – The initial scale of the object to add. Defaults to None.visible (
bool) – The initial visibility of the object to add. Defaults to True.radius_top (
float) – The top radius of the cylinder. Defaults to 1.0.radius_bottom (
float) – The bottom radius of the cylinder. Defaults to 1.0.height (
float) – The height of the cylinder. Defaults to 1.0.radial_segments (
int) – The radial segments of the cylinder. Defaults to 32.height_segments (
int) – The height segments of the cylinder. Defaults to 1.open_ended (
bool) – The open ended flag of the cylinder. Defaults to False.theta_start (
float) – The Theta start of the cylinder. Defaults to 0.theta_length (
float) – The Theta length of the cylinder. Defaults to 2*math.pi.material (
MeshStandardMaterial|MeshBasicMaterial|None) – The material of the object. Defaults to None.identifier (
int|str|None) – The identifier of the cylinder. If None the identifier gets assigned by the server. Defaults to None.
- Return type:
- Returns:
The added object.
- add_hash_instruction(anchor, *instructions)
Adds a client hash anchor instruction.
- Parameters:
anchor (
str) – The anchor name which triggers the instructions.instructions (
tuple[tuple[str,float|bool|str|Sequence[tuple[float,float,float]] |Sequence[tuple[int,int,int]]],...] |tuple[tuple[str,float],...] |tuple[tuple[str,str],...] |tuple[tuple[str,bool],...] |tuple[tuple[str,Sequence[tuple[float,float,float]] |Sequence[tuple[int,int,int]]],...]) – The instructions to trigger.
- Return type:
None
- add_line(points, position=None, rotation=None, quaternion=None, scale=None, visible=True, material=None, segments=False, identifier=None)
Adds a line object.
- Parameters:
points (
Sequence[tuple[float,float,float]] |Sequence[tuple[int,int,int]]) – The points of the line. If connected is False, two points for each segment are required.position (
list[float] |None) – The initial position of the object to add. Defaults to None.rotation (
list[float] |None) – The initial rotation (Euler(XYZ) in radian) of the object to add. Defaults to None.quaternion (
list[float] |None) – The initial quaternion (XYZW) of the object to add. Defaults to None.scale (
list[float] |None) – The initial scale of the object to add. Defaults to None.visible (
bool) – The initial visibility of the object to add. Defaults to True.material (
LineBasicMaterial|None) – The material of the object. Defaults to None.segments (
bool) – Whether to create separate line segments. Defaults to False.identifier (
int|str|None) – The identifier of the line. If None the identifier gets assigned by the server. Defaults to None.
- Return type:
- Returns:
The added object.
- add_line_basic_material(color, opacity=1.0, transparent=False, depth_test=True, linewidth=1, identifier=None)
Adds a line basic material.
- Parameters:
color (
list[float]) – The color of the material.opacity (
float) – The opacity of the material. Defaults to 1.0.transparent (
bool) – The transparent flag of the material. Defaults to False.depth_test (
bool) – The depth test flag of the material. Defaults to True.linewidth (
int) – The linewidth of the material. Defaults to 1.identifier (
int|str|None) – The identifier of the basic material. If None the identifier gets assigned by the server. Defaults to None.
- Return type:
- Returns:
The line basic material.
- add_mesh_basic_material(color, opacity=1.0, transparent=False, depth_test=True, wireframe=False, identifier=None)
Adds a mesh basic material.
Unlike a mesh standard material, a mesh basic material is not affected by lights: it always renders its flat, unlit color.
- Parameters:
color (
list[float]) – The color of the material.opacity (
float) – The opacity of the material. Defaults to 1.0.transparent (
bool) – The transparent flag of the material. Defaults to False.depth_test (
bool) – The depth test flag of the material. Defaults to True.wireframe (
bool) – The wireframe flag of the material. Defaults to False.identifier (
int|str|None) – The identifier of the mesh material. If None the identifier gets assigned by the server. Defaults to None.
- Return type:
- Returns:
The mesh basic material.
- add_mesh_standard_material(color, opacity=1.0, transparent=False, depth_test=True, emissive=None, flat_shading=False, metalness=0.0, roughness=1.0, wireframe=False, identifier=None)
Adds a mesh standard material.
- Parameters:
color (
list[float]) – The color of the material.opacity (
float) – The opacity of the material. Defaults to 1.0.transparent (
bool) – The transparent flag of the material. Defaults to False.depth_test (
bool) – The depth test flag of the material. Defaults to True.emissive (
list[float] |None) – The emissive color of the material. Defaults to [0, 0, 0].flat_shading (
bool) – The flat shading flag of the material. Defaults to False.metalness (
float) – The metalness of the material. Defaults to 0.0.roughness (
float) – The roughness of the material. Defaults to 1.0.wireframe (
bool) – The wireframe flag of the material. Defaults to False.identifier (
int|str|None) – The identifier of the mesh material. If None the identifier gets assigned by the server. Defaults to None.
- Return type:
- Returns:
The mesh standard material.
- add_model(model_path=None, model_url=None, position=None, rotation=None, quaternion=None, scale=None, visible=True, unique_material=None, material=None, identifier=None)
Adds an object to the 3D visualization by loading a model from a path or URL.
- Behavior:
Local files are cached by content hash (re-upload only when modified)
Remote URLs are cached by URL (subsequent calls reuse the server copy)
- Parameters:
model_path (
Path|None) – Load model from a local file. Defaults to None.model_url (
str|None) – Load model from a remote location. Defaults to None.position (
list[float] |None) – Initial object position. Defaults to None.rotation (
list[float] |None) – Euler rotation (XYZ) in radians. Defaults to None.quaternion (
list[float] |None) – Quaternion rotation (XYZW). Defaults to None.scale (
list[float] |None) – Initial scale. Defaults to None.visible (
bool) – Whether the object is initially visible. Defaults to True.unique_material (
bool|None) – Results in additional copying of material properties. Defaults to None. When False or None, material changes apply to all objects referencing the same model. When True, materials are not shared. Ignored when material is set.material (
MeshStandardMaterial|MeshBasicMaterial|None) – A separately created material to apply recursively to every mesh in the model, replacing whatever materials are baked into the model asset itself (including their texture maps and side/double-sided setting). Defaults to None.identifier (
int|str|None) – Explicit object identifier. If None, the server assigns one. Defaults to None.
- Raises:
ValueError – If both or neither of model_path/model_url are provided.
ValueError – If rotation and quaternion are both provided.
- Return type:
- Returns:
The added object.
- add_point_cloud(data_format, data=None, position=None, rotation=None, quaternion=None, scale=None, visible=True, material=None, identifier=None)
Adds a point cloud object.
- Parameters:
data_format (
Literal['ply','pcd']) – The point cloud format, either ‘ply’ or ‘pcd’.data (
bytes|None) – The point cloud bytes.position (
list[float] |None) – The initial position of the object to add. Defaults to None.rotation (
list[float] |None) – The initial rotation (Euler(XYZ) in radian) of the object to add. Defaults to None.quaternion (
list[float] |None) – The initial quaternion (XYZW) of the object to add. Defaults to None.scale (
list[float] |None) – The initial scale of the object to add. Defaults to None.visible (
bool) – The initial visibility of the object to add. Defaults to True.material (
PointsMaterial|None) – The material of the object. Defaults to None.identifier (
int|str|None) – The identifier of the point cloud. If None, the identifier gets assigned by the server. Defaults to None.
- Return type:
- Returns:
The added object.
- add_points_material(color, size=1.0, opacity=1.0, transparent=False, depth_test=True, identifier=None)
Adds a points material.
- Parameters:
color (
list[float]) – The color of the material.size (
float) – The size of the points in pixels. Defaults to 1.0.opacity (
float) – The opacity of the material. Defaults to 1.0.transparent (
bool) – The transparent flag of the material. Defaults to False.depth_test (
bool) – The depth test flag of the material. Defaults to True.identifier (
int|str|None) – The identifier of the mesh material. If None the identifier gets assigned by the server. Defaults to None.
- Return type:
- Returns:
The points material.
- add_sphere(position=None, rotation=None, quaternion=None, scale=None, visible=True, radius=1.0, width_segments=32, height_segments=16, phi_start=0, phi_length=6.283185307179586, theta_start=0, theta_length=3.141592653589793, material=None, identifier=None)
Adds a sphere object.
- Parameters:
position (
list[float] |None) – The initial position of the object to add. Defaults to None.rotation (
list[float] |None) – The initial rotation (Euler(XYZ) in radian) of the object to add. Defaults to None.quaternion (
list[float] |None) – The initial quaternion (XYZW) of the object to add. Defaults to None.scale (
list[float] |None) – The initial scale of the object to add. Defaults to None.visible (
bool) – The initial visibility of the object to add. Defaults to True.radius (
float) – The radius of the sphere. Defaults to 1.0.width_segments (
int) – The width segments of the sphere. Defaults to 32.height_segments (
int) – The height segments of the sphere. Defaults to 16.phi_start (
float) – The Phi start value of the sphere. Defaults to 0.phi_length (
float) – The Phi length value of the sphere. Defaults to math.pi*2.theta_start (
float) – The Theta start value of the sphere. Defaults to 0.theta_length (
float) – The Theta length value of the sphere. Defaults to math.pi.material (
MeshStandardMaterial|MeshBasicMaterial|None) – The material of the object. Defaults to None.identifier (
int|str|None) – The identifier of the sphere. If None the identifier gets assigned by the server. Defaults to None.
- Return type:
- Returns:
The added object.
- add_text_panel(text, position=None, rotation=None, quaternion=None, scale=None, visible=True, identifier=None)
Adds a text panel object.
- Parameters:
text (
str) – Text to visualize on the panel.position (
list[float] |None) – The initial position of the panel to add. Defaults to None.rotation (
list[float] |None) – The initial rotation (Euler(XYZ) in radian) of the panel to add. Defaults to None.quaternion (
list[float] |None) – The initial quaternion (XYZW) of the panel to add. Defaults to None.scale (
list[float] |None) – The initial scale of the panel to add. Defaults to None.visible (
bool) – The initial visibility of the panel to add. Defaults to True.identifier (
int|str|None) – The identifier of the panel. If None the identifier gets assigned by the server. Defaults to None.
- Return type:
- Returns:
The added panel.
- property config: Config
Access the UI configuration write-access helper.
The returned helper builds live instructions for the scene, grid and logo settings, e.g.
visu.config.scene.grid.section_size(2).- Returns:
The configuration write-access helper.
- get_axes(identifier)
Gets the axes object for the provided identifier.
- Parameters:
identifier (
str|int) – The identifier of the axes to get.- Return type:
- Returns:
The axes.
- get_box(identifier)
Gets the box object for the provided identifier.
- Parameters:
identifier (
str|int) – The identifier of the box to get.- Return type:
- Returns:
The box.
- get_camera(identifier)
Gets the camera object for the provided identifier.
- Parameters:
identifier (
str|int) – The identifier of the camera to get.- Return type:
Camera- Returns:
The camera.
- get_cylinder(identifier)
Gets the cylinder object for the provided identifier.
- Parameters:
identifier (
str|int) – The identifier of the cylinder to get.- Return type:
- Returns:
The cylinder.
- get_line(identifier)
Gets the line object for the provided identifier.
- Parameters:
identifier (
str|int) – The identifier of the line to get.- Return type:
- Returns:
The line.
- get_model(identifier)
Gets the model object for the provided identifier.
- Parameters:
identifier (
str|int) – The identifier of the model to get.- Return type:
- Returns:
The model.
- get_object(identifier)
Gets the object for the provided identifier.
- Parameters:
identifier (
str|int) – The identifier if the object to get.- Return type:
- Returns:
The found object.
- get_objects()
Gets all objects from the visu.
- Return type:
list[Obj]- Returns:
All objects.
- get_point_cloud(identifier)
Gets the point cloud object for the provided identifier.
- Parameters:
identifier (
str|int) – The identifier of the point cloud to get.- Return type:
- Returns:
The point cloud.
- get_sphere(identifier)
Gets the sphere object for the provided identifier.
- Parameters:
identifier (
str|int) – The identifier of the sphere to get.- Return type:
- Returns:
The sphere.
- get_text_panel(identifier)
Gets the text panel object for the provided identifier.
- Parameters:
identifier (
str|int) – The identifier of the text panel to get.- Return type:
- Returns:
The text panel.
- update(*values)
Updates the provided object properties for the 3D visualization.
- Parameters:
values (
tuple[tuple[str,float|bool|str|Sequence[tuple[float,float,float]] |Sequence[tuple[int,int,int]]],...] |tuple[tuple[str,float],...] |tuple[tuple[str,str],...] |tuple[tuple[str,bool],...] |tuple[tuple[str,Sequence[tuple[float,float,float]] |Sequence[tuple[int,int,int]]],...]) – The identifier value pair of the object properties to update.- Return type:
None