Geometries

The following documentation is presented as Python code running inside a Jupyter Notebook. To run it yourself you can copy/type each individual cell or directly download the full notebook, including all required files.

Download Jupyter Notebook

Acoustic wave propagation simulations are mainly governed by their media (geometries) and the boundaries of the media (materials - covered in the next tutorial).

The SDK offers a variety of ways to work with geometries, such as:

Using a model from our extensive geometry library
Uploading custom geometries in multiple formats (f.ex. 3dm, obj)
Generating rooms by describing a 2D surface and extruding it along the 3rd dimension

We'll first fetch our project from before and then look at geometries.

from pathlib import Path
from treble_tsdk.tsdk import TSDK
from treble_tsdk import tsdk_namespace as treble
from treble_tsdk import display_data as dd

tsdk = TSDK()
project_name = "Tutorial"
p = tsdk.get_or_create_project(name=project_name)

The Geometry Library

The SDK comes with a library of geometries which contain metadata on boundary layers and tags which can be used to query certain subsets of the geometry library. We aim to continuously expand the geometry library and welcome requests on types of geometries to include.

The geometry library is accessed on a dataset level. Here we will, for example, get the "MeetingRoom" dataset and continue working with it.

from pathlib import Path
from treble_tsdk.tsdk import TSDK, TSDKCredentials
from treble_tsdk import tsdk_namespace as treble
from treble_tsdk import display_data as dd

%env STAPI_DISABLE_SSL_VERIFY=1
tsdk = TSDK(TSDKCredentials.from_file('/home/nonni/.config/treble/tsdk_local.cred'))
p = tsdk.get_or_create_project('hello')

meeting_rooms = tsdk.geometry_library.get_dataset(treble.GeometryLibraryDataset.meeting_room)

The display_data module can be used to get information on geometries. Either in table view or in tree view. First, we'll display information on the first 5 rooms in a table,

dd.as_table(meeting_rooms[:5])

and then we can decide to request further details on a certain room in tree view.

dd.as_tree(meeting_rooms[3])

we can also visualize the geometry and it's geometry by using the plot function.

meeting_rooms[3].plot()

Custom Geometry Generation

There are a selection of geometry generation functions which can be used to generate custom geometries with code. These are all relatively simplistic and we aim to keep expanding on this functionality, for example, by adding optional inclusion of furnishing and source/receiver suggestions.

The simplest option is the shoebox room generation where width, depth, and height are imported in the unit of meters.

room = treble.GeometryGenerator.create_shoebox_room(
    project=p,
    model_name="shoebox", 
    width_x=4, 
    depth_y=5, 
    height_z=2.2, 
    join_wall_layers=False
)

We can also create more complex rooms, such as L-shaped rooms where we input lengths of four sides in meters and then the height.

room = treble.GeometryGenerator.create_l_shaped_room(
    project=p, 
    model_name="l-shaped", 
    a_side=3, 
    b_side=3, 
    c_side=1, 
    d_side=1, 
    height_z=2.2
)

Finally, we can create a room where we simply provide a vector of X,Y coordinates to define the edge points of the room and then the walls will be interpolated between these points and they can then be extruded to some fixed height.

Here we create a polygon room:

edge_points_hexagon = [[6.4, 2.2],[4.2, 4.4],[2.8, 6.6],[0.2, 4],[0, 3.4],[0.7, 1.9],[2.4, 0.6]]
room = treble.GeometryGenerator.create_polygon_room(
    project=p, 
    model_name="hexagon", 
    points_xy=edge_points_hexagon,
    height_z=2.2,
    join_wall_layers=False,
)

geometries generated this way also have a plot() function.

room.plot()

Custom Geometry Upload

Users can upload their own geometries into the SDK.

room = p.add_model(model_name="Uploaded Model", model_file_path='/home/nonni/tmp/tsdk/boundary_source/input/model_1_0.3dm')

The model is inspected by our geometry checking service in the cloud and thus needs a few seconds before it will be usable in the project. The progress can be be followed using the display_data module.

dd.as_live_model_status(room)

If your model is valid (Status: Valid) then it's compatible with our simulation engine.

Get Models in Project

After a model has been created, it does not need to be created again and can be accessed in case it needs to be used/inspected again.

It can be beneficial to use a model again as every time a model is used in a simulation, a mesh is generated (which takes time depending on transition frequency), but if the model has been used previously with the same transition frequency, the mesh gets re-used.

Retrieving models can be done using the project.get_models() / project.get_model() / project.get_model_by_name() methods.

The get_models() method returns all models that belongs to the project in question.

models = p.get_models()
dd.as_table(models)

We can fetch single models using a few different methods shown in the code example below.

# Fetch model by index from the array received from p.get_models()
room = models[0]

# Fetch model by Id where Id is the unique identifier generated by the SDK for the model.
room = p.get_model(models[0].id)

# Fetch model by name.
room = p.get_model_by_name(models[0].name)

Now we know how to add geometries into an SDK project and retrieve them for later usage.

In the next tutorial we will show how materials can be attached to the boundaries of our models to prepare them for running simulations.