treble_tsdk.geometry.generator

Classes

GeometryComponentGenerator	Generator for creating reusable geometry components.
GeometryDefinitionGenerator	Generator for creating parametric room geometries.
PointsGenerator	Generator for creating valid source and receiver point locations.

class treble_tsdk.geometry.generator.GeometryComponentGenerator

Generator for creating reusable geometry components.

Provides methods to create basic shapes (boxes, planes, triangles) and loudspeaker models as geometry components.

static create_box(bounding_box: BoundingBox = BoundingBox(min=Point3d(x=-1.0, y=-1.0, z=-1.0), max=Point3d(x=1.0, y=1.0, z=1.0)), layer_name: str = 'box') → GeometryComponent

Create a box mesh with the given dimensions

Parameters:

• bounding_box – BoundingBox object with the min and max coordinates of the box

• layer_name – name of the layer of the box

static create_component_from_model(model: ModelObj, component_name: str | None = None, layer_names: list[str] | None = None, transform: Transform3d | None = None, move_to_origin: bool = True) → GeometryComponent

Create a geometry component from a model

Parameters:

• model – ModelObj object to create the component from

• component_name – name of the component

• layer_names – list of layer names to create the component from, if None, all layers will be used

• transform – The transform to applied to the data before creating the component

• move_to_origin – if True, the component will be moved to the origin (0,0,0), if transform is provided, this will be ignored

static create_loudspeaker(width: float, depth: float, height: float, membrane_diameter: float, membrane_center_height: float, membrane_resolution: int = 12, enclosure_layer_name: str = 'enclosure', membrane_layer_name: str = 'membrane') → GeometryComponent

Create a speaker mesh with the given dimensions

Parameters:

• width – width of the speaker in meters

• depth – depth of the speaker in meters

• height – height of the speaker in meters

• membrane_diameter – diameter of the membrane

• membrane_center_height – height of the membrane center from the bottom of the enclosure

• membrane_resolution – Number of points to use for the membrane

static create_plane(length: float = 1.0, width: float = 1.0, layer_name: str = 'plane')

Create a plane mesh with the given dimensions

Parameters:

• length – length of the plane in meters

• width – width of the plane in meters

• layer_name – name of the layer of the plane

static create_triangle(point0: Point3d = Point3d(x=0.0, y=0.0, z=0.0), point1: Point3d = Point3d(x=0.0, y=1.0, z=0.0), point2: Point3d = Point3d(x=0.0, y=0.0, z=1.0), layer_name: str = 'triangle') → GeometryComponent

Create a plane mesh with the given dimensions

Parameters:

• point0 – first point of the triangle

• point1 – second point of the triangle

• point2 – third point of the triangle

• layer_name – name of the layer of the triangle

class treble_tsdk.geometry.generator.GeometryDefinitionGenerator

Generator for creating parametric room geometries.

Provides methods to create shoebox, L-shaped, T-shaped, U-shaped, and polygon rooms with configurable dimensions.

static create_L_shaped_room(a_side: float, b_side: float, c_side: float, d_side: float, height_z: float, join_wall_layers: bool = True) → GeometryDefinition

Create L-shaped room with sides as shown in the drawing below:

  __________
 |          | d
 |      ____|
 |     |  c
 |     |
 |     | b
 |_____|
0,0  a

Parameters:

join_wall_layers – if True, walls will be put on a single layer, if False, the model will have a layer for each wall in the room.

static create_T_shaped_room(a_side: float, b_side: float, c_side: float, d_side: float, height_z: float, join_wall_layers: bool = True) → GeometryDefinition

Create T-shaped room with sides as shown in the drawing below:

           d
        _______
       |       |                  ^
     b |       |                  |
       |       |                  |
       |       | c              length
   ____|       |____              |
a |                 |             |
  |_________________|             v
 0,0

 <------ width ------>

a+b   = length
2*c+d = width

Parameters:

join_wall_layers – if True, walls will be put on a single layer, if False, the model will have a layer for each wall in the room.

static create_U_shaped_room(a_side: float, b_side: float, c_side: float, d_side: float, height_z: float, join_wall_layers: bool = True) → GeometryDefinition

Create U-shaped room with sides as shown in the drawing below:

   c
  ___          ___
 |   |        |   |         ^
 |   |        |   |         |
 |   |        |   |         | b
 |   |   d    |   |         |
 |   |________|   |    ^    v
 |                |    | a
 |________________|    v
0,0

Parameters:

• a_side – length of the lower part of the U in meters

• b_side – length of the upper part of the U in meters

• c_side – width of the upper part of the U in meters

• d_side – width of the inside part of the U in meters

• height_z – height of room in meters

• join_wall_layers – if True, walls will be put on a single layer, if False, the model will have a layer for each wall in the room.

static create_angled_shoebox_room(base_side: float, depth_y: float, left_angle: float, right_angle: float, height_z: float, join_wall_layers: bool = True) → GeometryDefinition

Create shoebox room with angled side walls (= trapezoid room) as shown in the drawing below. For more information see: https://docs.treble.tech/treble-sdk/geometry/create-room#create_angled_shoebox_room

static create_polygon_room(points_xy: list[Point2d], height_z: float, join_wall_layers=True, object_name=None) → GeometryDefinition

Generate a polygon shaped room.

Parameters:

• points_xy – List of points defining the polygon in the xy-plane.

• height_z – height of room (z axis)

• join_wall_layers – if True, walls will be put on a single layer, if False, the model will have a layer for each wall in the room.

static create_random_L_shaped_rooms(n_rooms: int, a_side_range: tuple[float, float], b_side_range: tuple[float, float], c_side_range: tuple[float, float], d_side_range: tuple[float, float], height_range: tuple[float, float], join_wall_layers: bool = True) → list[GeometryDefinition]

Generate multiple random L-shaped rooms. The dimensions are randomly drawn from a specified range according to a uniform probability. For details on how to specify each side of the room, please refer to create_L_shaped_room().

Parameters:

• n_rooms – Number of rooms to create

• a_side_range – The lengths of the a_side for all generated rooms are randomly drawn from this range.

• b_side_range – The lengths of the b_side for all generated rooms are randomly drawn from this range.

• c_side_range – The lengths of the c_side for all generated rooms are randomly drawn from this range.

• d_side_range – The lengths of the d_side for all generated rooms are randomly drawn from this range.

• height_range – The heights for all generated rooms are randomly drawn from this range.

• join_wall_layers – if True, walls will be put on a single layer, if False, the model will have a layer for each wall in the room.

static create_random_T_shaped_rooms(n_rooms: int, a_side_range: tuple[float, float], b_side_range: tuple[float, float], c_side_range: tuple[float, float], d_side_range: tuple[float, float], height_range: tuple[float, float], join_wall_layers: bool = True) → list[GeometryDefinition]

Generate multiple random T-shaped rooms. The dimensions are randomly drawn from a specified range according to a uniform probability. For details on how to specify each side of the room, please refer to create_T_shaped_room().

Parameters:

• n_rooms – Number of rooms to create

• a_side_range – The lengths of the a_side for all generated rooms are randomly drawn from this range.

• b_side_range – The lengths of the b_side for all generated rooms are randomly drawn from this range.

• c_side_range – The lengths of the c_side for all generated rooms are randomly drawn from this range.

• d_side_range – The lengths of the d_side for all generated rooms are randomly drawn from this range.

• height_range – The heights for all generated rooms are randomly drawn from this range.

• join_wall_layers – if True, walls will be put on a single layer, if False, the model will have a layer for each wall in the room.

static create_random_U_shaped_rooms(n_rooms: int, a_side_range: tuple[float, float], b_side_range: tuple[float, float], c_side_range: tuple[float, float], d_side_range: tuple[float, float], height_range: tuple[float, float], join_wall_layers: bool = True) → list[GeometryDefinition]

Generate multiple random U-shaped rooms. The dimensions are randomly drawn from a specified range according to a uniform probability. For details on how to specify each side of the room, please refer to create_U_shaped_room().

Parameters:

• n_rooms – Number of rooms to create

• a_side_range – The lengths of the a_side for all generated rooms are randomly drawn from this range.

• b_side_range – The lengths of the b_side for all generated rooms are randomly drawn from this range.

• c_side_range – The lengths of the c_side for all generated rooms are randomly drawn from this range.

• d_side_range – The lengths of the d_side for all generated rooms are randomly drawn from this range.

• height_range – The heights for all generated rooms are randomly drawn from this range.

• join_wall_layers – if True, walls will be put on a single layer, if False, the model will have a layer for each wall in the room.

static create_random_angled_shoebox_rooms(n_rooms: int, base_side_range: tuple[float, float], depth_range: tuple[float, float], left_angle_range: tuple[float, float], right_angle_range: tuple[float, float], height_range: tuple[float, float], join_wall_layers: bool = True, parallel: bool = True, max_workers: int | None = None) → list[GeometryDefinition]

Generate multiple random angled shoebox rooms. The dimensions are randomly drawn from a specified range according to a uniform probability. For details on how to specify each side of the room, please refer to create_angled_shoebox_room().

Parameters:

• n_rooms – Number of rooms to create

• base_side_range – The lengths of the base_side for all generated rooms are randomly drawn from this range.

• depth_range – The depths for all generated rooms are randomly drawn from this range.

• left_angle_range – The left angles (in degrees) for all generated rooms are randomly drawn from this range.

• right_angle_range – The right angles (in degrees) for all generated rooms are randomly drawn from this range.

• height_range – The heights for all generated rooms are randomly drawn from this range.

• join_wall_layers – if True, walls will be put on a single layer, if False, the model will have a layer for each wall in the room.

• parallel – if True, use parallel processing for faster generation

• max_workers – Maximum number of worker processes (None = auto-detect)

static create_random_shoebox_rooms(n_rooms: int, x_range: tuple[float, float], y_range: tuple[float, float], z_range: tuple[float, float], join_wall_layers: bool = True, parallel: bool = True, max_workers: int | None = None) → list[GeometryDefinition]

Generate multiple random shoebox rooms. The dimensions are randomly drawn from a specified range according to a uniform probability.

Parameters:

• n_rooms – Number of rooms to create

• x_range – The x length of all generated rooms are randomly drawn from this range.

• y_range – The y length of all generated rooms are randomly drawn from this range.

• z_range – The z length of all generated rooms are randomly drawn from this range.

• join_wall_layers – if True, walls will be put on a single layer, if False, the model will have a layer for each wall in the room.

• parallel – if True, use parallel processing for faster generation

• max_workers – Maximum number of worker processes (None = auto-detect)

static create_shoebox_room(width_x: float, depth_y: float, height_z: float, join_wall_layers: bool = True) → GeometryDefinition

Generate a shoebox room.

Parameters:

• width_x – width of room in meters (x axis)

• depth_y – depth of room in meters (y axis)

• height_z – height of room in meters (z axis)

• join_wall_layers – if True, walls will be put on a single layer, if False, the model will have a layer for each wall in the room. Example with join_wall_layers set to True: [“shoebox_walls”, “shoebox_floor”, “shoebox_ceiling”] Example with join_wall_layers set to False: [“shoebox_wall_0”, “shoebox_wall_1”, “shoebox_wall_2”, “shoebox_wall_3”, “shoebox_floor”, “shoebox_ceiling”] The walls are ordered counter-clockwise beginning with the wall coinciding with the x-axis.

class treble_tsdk.geometry.generator.PointsGenerator

Generator for creating valid source and receiver point locations.

Provides methods to generate points within geometry bounds that satisfy validation rules.

static generate_valid_grid(model: ModelObj | GeometryLibraryObj, x_res: float | None = None, y_res: float | None = None, z_res: float | None = None, x_range: tuple[float, float] | None = None, y_range: tuple[float, float] | None = None, z_range: tuple[float, float] | None = None, existing_points: list[Point3d] | list[list[float]] | None = None, min_dist_surf: float = 0.1, min_dist_existing_points: float = 0.1, n_grid_points_x: int | None = None, n_grid_points_y: int | None = None, n_grid_points_z: int | None = None) → list[Point3d]

Generates a grid of points within bounds of the model or within the specified range. Grid points follow rules regarding minimum distance from surfaces of the model or minimum distance to other points (e.g. when generating a receiver grid and all receivers should have a minimum distance from the sources).

Parameters:

• model – Either a ModelObj, GeometryObj or a path to a valid 3dm model file.

• x_res – Grid resolution in x, in meters. If this argument is not provided, the grid resolution can also be specified by n_grid_points_x. If neither are specified, the grid includes only a single point at half of the x_range.

• y_res – Grid resolution in y, in meters. If this argument is not provided, the grid resolution can also be specified by n_grid_points_y. If neither are specified, the grid includes only a single point at half of the y_range.

• z_res – Grid resolution in z, in meters. If this argument is not provided, the grid resolution can also be specified by n_grid_points_z. If neither are specified, the grid includes only a single point at half of the z_range.

• x_range – min-max x values of the grid. Grid excludes max if max-min fits integer number of points. If nothing given the bounding box will be taken.

• y_range – min-max y values of the grid. Grid excludes max if max-min fits integer number of points. If nothing given the bounding box will be taken.

• z_range – min-max z values of the grid. Grid excludes max if max-min fits integer number of points. If nothing given the bounding box will be taken.

• existing_points – Grid points can be generated to have a minimum distance from these points.

• min_dist_surf – Minimum distance between generated grid points and surfaces of the model.

• min_dist_existing_points – Minimum distance between generated grid points and existing_points.

• n_grid_points_x – Number of grid points in x. If this argument is not provided, the grid resolution can also be specified by x_res. If neither are specified, the grid includes only a single point at half of the x_range.

• n_grid_points_y – Number of grid points in y. If this argument is not provided, the grid resolution can also be specified by y_res. If neither are specified, the grid includes only a single point at half of the y_range.

• n_grid_points_z – Number of grid points in z. If this argument is not provided, the grid resolution can also be specified by z_res. If neither are specified, the grid includes only a single point at half of the z_range.

static generate_valid_points(model: ModelObj | GeometryLibraryObj, max_count: int, ruleset: PointRuleset, existing_receiver_points: list[Point3d] | list[list[float]] | None = None, existing_source_points: list[Point3d] | list[list[float]] | None = None, x_range: tuple[float, float] | None = None, y_range: tuple[float, float] | None = None, z_range: tuple[float, float] | None = None) → list[Point3d]

Tries to generate max_count valid points within bounds of the model and within the rules of the provided ruleset.

Parameters:

• model – Either a ModelObj, GeometryObj or a path to a valid 3dm model file.

• max_count – Maximum number of points you can receive.

• ruleset – What ruleset to use when validating points.

• existing_receiver_points – Validate as if these receivers were in the model.

• existing_source_points – Validate as if these sources were in the model.

• x_range – min-max x values to search within, if nothing given the bounding box will be taken

• y_range – min-max y values to search within, if nothing given the bounding box will be taken

• z_range – min-max z values to search within, if nothing given the bounding box will be taken