Client
This guide explains how to use the voraus 3D Visualization Python and Rust client to interact with the server. The clients can add 3D objects using standard web requests (HTTP protocol) to the server’s REST API, while live updates are handled using WebSockets.
Installation
If not already done, install the voraus 3D Visualization client as explained in the Server section.
Adding objects to the Server
It is assumed that the server is running. First import the client with
from voraus_3d_visu import Visu
use voraus_3d_visu::obj::text_panel::TextPanelOptions;
use voraus_3d_visu::{Result, Visu};
then create an instance of the Visu:
visu = Visu("http://localhost:8077/")
let mut visu = Visu::new("http://localhost:8077/", true, false, false, None)?;
Each client instance can be configured on how to interact with the server on its initialization.
By default, each client requests the deletion of all objects (except models) and all materials
associated with this client. To change this behavior, set the parameters clear to False.
If one likes to delete everything regardless of the client origin, set the parameter clear_all to True.
Additionally, if the client is part of a multi-client setup, one can use the identifier parameter to distinguish
between the objects and materials added by different clients.
Adding different 3D objects to the scene, e.g., a text panel, can be done as follows:
text_panel = visu.add_text_panel(text="Hello World!")
let text_panel = visu.add_text_panel("Hello World!", TextPanelOptions::default())?;
Currently, we support the following 3D objects:
Models based on GLB, glTF, or OBJ files created with any 3D modeling tool, including Draco or meshopt compressed glTF and GLB files
Geometric primitives: Box, Sphere and Cylinder
Text panels
Axes helpers (coordinate system arrows)
Lines
Point clouds based on pld or ply files
Each object can be added using its respective method, more information can be found in the voraus_3d_visu (Python) and voraus_3d_visu (Rust) documentation.
Some objects, e.g., geometric primitives can accept an explicit material on initialization. These materials can also be added using their respective methods.
Updating object properties
Once an object is added to the server, its properties can be updated with instructions, for this a WebSocket connection needs to be established:
with visu.connection():
let mut connection = visu.connection()?;
and then the desired properties can be updated, e.g., scaling the text panel:
visu.update(text_panel.scale.xyz(2, 2, 2))
connection.update(vec![text_panel.scale().xyz(2.0, 2.0, 2.0)])?;
Note
Multiple properties can be updated at once by passing multiple instructions into the update method.
Hash Instructions
Hash instructions are instructions that the server stores under an anchor name. A web client applies them when
its URL hash names the anchor, e.g. http://localhost:8077/#top, without reloading the page. They only affect
that web client. The live data on the server and other clients stay unchanged. Several anchors can be combined,
e.g. #dark,top, later ones win on conflicts. No WebSocket connection is needed to add them.
To switch between perspectives, add one camera per perspective and let the hash only set the active camera:
# One camera per perspective. The hash only switches the active camera.
top = visu.add_camera(identifier="top", position=[0, 0, 6], fov=60)
visu.add_hash_instruction("top", visu.config.scene.active_camera(top))
// One camera per perspective. The hash only switches the active camera.
let top = visu.add_camera(CameraOptions {
transform: Transform {
position: Some([0.0, 0.0, 6.0]),
..Transform::default()
},
fov: Some(60.0),
identifier: Some("top".to_string()),
..CameraOptions::default()
})?;
visu.add_hash_instruction("top", vec![visu.config().scene().active_camera(&top)])?;
Object and material instructions can be used as well:
box = visu.add_box(identifier="box")
visu.add_hash_instruction("hidden", box.visible(False))
let cube = visu.add_box(BoxOptions {
identifier: Some("box".to_string()),
..BoxOptions::default()
})?;
visu.add_hash_instruction("hidden", vec![cube.visible(false)])?;
Only the values contained in a hash instruction are overridden, and they behave differently:
Configuration values (the active camera, the scene color, the grid and the logo) take precedence over the live data as long as the anchor is set and fall back to the live values once it is removed.
Object and material values are applied when the anchor is set. Later live updates of the same values overwrite them, and removing the anchor does not restore the previous values.
The light and dark themes are hash instructions as well, see the
configuration example.
Next Step
Check out the Object Instructions to get an overview of the different properties to update.