Skip to main content

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:

  1. Using a model from our extensive geometry library
  2. Uploading custom geometries in the Rhino 3dm format (more formats coming soon)
  3. 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.

Here we will, for example, query the geometry library for every room which contains the tag meeting so we should end up with a collection of meeting rooms.

meeting_rooms = tsdk.geometry_library.query(category=treble.GeometryLibraryCategory.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])

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.

  __________
 |          | d
 |      ____|
 |     |  c
 |     |
 |     | b
 |_____|
    a
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 hexagon room:

edge_points_hexagon = [[0,2],[1,4],[3,4],[4,2],[3,0],[1,0]]
room = treble.GeometryGenerator.create_polygon_room(
    project=p, 
    model_name="hexagon", 
    points_xy=edge_points_hexagon,
    height_z=2.2,
    join_wall_layers=False,
)

Custom Geometry Upload​

Users can upload their own geometries into the SDK. Currently it is only possible using the Rhino 3dm format but we will implement more formats soon.

room = p.add_model(model_name="Uploaded Model", model_file_path=Path("Models/rhino_model.3dm"))

The model is inspected by our geometry checking service in the cloud and thus needs a bit of time (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)

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() methods.

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

We can then use the Id to retrieve the model using project.get_model(id)

room = p.get_model(models[2].id)

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.