Generate grids

In the Treble SDK, you can generate uniform grids of source or receiver positions. At the same time, you can set up certain rules that the generated grid points must fulfil. For example, you can generate grids, where all positions have a minimum distance from all surfaces in the model. The grid points can also be generated such that they have a minimum distance from specified points, allowing you to generate a receiver grid around a set of sound sources, while maintaining a minimum source-receiver distance. The grid positions can either be drawn randomly from inside the model, or from within a specified $x$-, $y$-, or $z$-coordinate range. The grid resolution is customizable in all dimensions.

This page walks you through all necessary steps to generate source or receiver grids with the Treble SDK.

Generating points

In this example, we will work with a polygonal room that already includes two sound sources.

# Set up a polygonal room
polygon_points = [
    [3.5, 0],
    [2.5, 0],
    [2.5, 2.5],
    [0, 2.5],
    [0, 3.5],
    [2.5, 3.5],
    [3, 6],
    [3.5, 3.5],
    [6, 3.5],
    [6, 2.5],
    [4.5, 1.5],
]
poly_room = treble.GeometryDefinitionGenerator.create_polygon_room(
    points_xy=polygon_points,
    height_z=2.2,
    join_wall_layers=False,
)
poly_model = project.add_model("Polygon room", poly_room)

# Place two sound sources in the room
source_height = 1.1
source_pos = [treble.Point3d(3, 3, source_height), treble.Point3d(3, 1, source_height)]
source = [treble.Source.make_omni(pos, label=f"Src{idx}") for idx, pos in enumerate(source_pos)]

Further, we want to generate a receiver grid having the following properties:

• The grid resolution along the $x$- and $y$- axis (i.e., on the horizontal plane) should be $0.2$ m.
• The grid resolution along the $z$-axis should be $0.5$ m.
• The grid should fill the entire room along the $x$- and $y$- axis.
• The grid should only include positions for a limited height range, where the $z$-coordinate is between $0.75$ m and $1.75$ m.
• The grid points must have a minimum distance of $0.25$ m from all surfaces in the model.
• The grid points must have a minimum distance of $0.5$ m from the sources in the model. In other words, the source-receiver distance must be at least $0.5$ m for all source-receiver configurations.

To generate the receiver positions, we use the PointsGenerator and its function generate_valid_grid(). This function returns coordinates as Point3d objects that match the specified grid properties.

# Generate a grid of valid receivers in the room
pg = treble.PointsGenerator()
receiver_pos = pg.generate_valid_grid(
    model=poly_model,
    x_res=0.2,
    y_res=0.2,
    z_res=0.5,
    z_range=(0.75, 1.75 + 1e-10),
    existing_points=source_pos,
    min_dist_surf=0.25,
    min_dist_existing_points=0.5,
)

caution

Note: The coordinate ranges specified by the x_range, y_range, and z_range arguments of generate_valid_grid() are half-open intervals, i.e., they exclude the upper limits. For example, specifying z_range=(0.75, 1.75) and z_res=0.5 would only generate positions with $z=0.75$ and $z=1.25$, thus excluding the upper limit, $z=1.75$. This is analogous to numpy.arange(). If the upper limit should be included in the grid, a small value should be added to the second item of the tuple specifying the range. This approach was also pursued in the example above.

In a last step, we initialize Treble receivers from the generated coordinates, so they can be added to a simulation definition.

# Set up receivers
receivers = [treble.Receiver.make_mono(pos, label=f"Rcv{idx}") for idx, pos in enumerate(receiver_pos)]

Finally, let us have a look at the result. Below, you can see the two sound sources in yellow and the generated receivers in blue. The plots show the simulation definition, which can be set up using the model, sources, and receivers, as elaborated here.

$xy$ - view	3D view

We can see that the receiver positions fill the entire geometry on the $xy$-plane, while being constrained to a limited range along the $z$-axis. All receivers fulfill the requirements regarding the minimum surface-receiver and source-receiver distance.