treble_tsdk.core.geometry_library_obj

Geometry library access and querying.

Helpers for working with the geometry library datasets, categories and position suggestions.

Classes

`GeometryLibraryDataset`	Available categories for geometry library.
`GeometryLibraryObj`	Object used for representing geometries from the geometry library.
`PositionSuggestion`	Suggested position and orientation for placing sources or receivers in a geometry.

class treble_tsdk.core.geometry_library_obj.GeometryLibraryDataset

Available categories for geometry library.

classmethod list()

classmethod print()

apartments = 'Apartments'

atrium = 'Atrium'

auditorium = 'Auditorium'

bathrooms = 'Bathrooms'

bedrooms = 'Bedrooms'

cafe = 'Cafe'

classrooms = 'Classrooms'

listening_room = 'ListeningRoom'

living_rooms = 'LivingRooms'

living_rooms_with_hallway = 'LivingRoomsWithHallway'

meeting_room = 'MeetingRoom'

office = 'Office'

restaurants = 'Restaurants'

swimming_pool = 'SwimmingPool'

class treble_tsdk.core.geometry_library_obj.GeometryLibraryObj

Object used for representing geometries from the geometry library.

__init__(geometryDto: GeometryLibraryDto, client: TSDKClient, lazy: bool = True)

as_tree(): Uses the display_data module to model object info as tree.

calculate_sabine_estimate(material_assignments: list[MaterialAssignment | MaterialAssignmentDto], model_volume: float | None = None) → list[float]

Calculates the sabine estimate of the reverberation time based on layer material assignment.

Parameters:

material_assignment (list[MaterialAssignment|MaterialAssignmentDto]) – Layer material assignment for model to calculate the estimate on.
model_volume (float) – Optional, If no model volume is input the model volume will be computed from the input objects. If a geometry without a closed shell is input the model_volume has to be specified.

Returns list[float]:

List of the sabine estimated RT for each frequency range valid for materials (63, 125, 250, 500, 1k, 2k, 4k, 8k).

calculate_schroeder_frequency(material_assignments: list[MaterialAssignment | MaterialAssignmentDto], model_volume: float | None = None) → float

Calculates the Schroeder frequency 2000 * sqrt(T / V) of the model, where T is the longest Sabine reverberation time estimate across the octave bands and V the air volume of the model. Above this frequency the sound field is diffuse enough for geometrical acoustics to be a good approximation.

Parameters:

material_assignments (list[MaterialAssignment|MaterialAssignmentDto]) – Layer material assignment used for the Sabine estimate.
model_volume (float) – Optional, air volume in m³. Computed from the model if not given.

Returns float:

Schroeder frequency in Hz.

filter_visible_points(point: Point3d | Receiver | Source, candidates: list[Point3d | Receiver | Source]) → list[Point3d]

Keep the candidates that have line-of-sight to point within the model.

Useful together with Rotation.look_at_random() to orient a source towards something it can actually see, e.g. a talker facing another guest at a restaurant table.

Parameters:

point (Point3d) – The viewpoint.
candidates (list[Point3d]) – Points to test for line-of-sight from point.

Return list[Point3d]:

The visible candidate locations, in the order given.

generate_flat_absorption_material_assignment(absorption: float) → list[MaterialAssignment]

Generate a flat material assignment for all layers in the model.

Looks up a material named "<pct>% Absorption" in the material library (where pct is absorption rounded to two decimal places and expressed as a percentage, e.g. absorption=0.2 -> "20% Absorption") and assigns it to every layer of the model.

Parameters:: absorption (float) – Absorption coefficient in [0, 1]. Rounded to 2 decimal places to derive the percentage.
Returns list[MaterialAssignment]:: Material assignments covering all layers of the model.
Raises:: ValueError – If the model is not in Valid status, has no layers, or no matching material exists in the library (e.g. absorption > 0.95).

generate_material_assignment(reverb_factor: float | None = None, seed: float | None = None, max_retries: int = 100, acceptance_range: float = 0.1) → list[MaterialAssignment]

Build a material assignment for this geometry by sampling one material per layer.

For each layer present in this model, a material is sampled from the per-layer candidate pool defined in treble_tsdk/material/dataset_layer_materials.json for this geometry’s dataset.

When reverb_factor is None (default), each layer is sampled uniformly at random. When reverb_factor is in [0.0, 1.0], the method targets a reverberation time linearly interpolated between this geometry’s most-absorbing and most-reverberant Sabine RT estimates (computed once and cached on the object). reverb_factor=0 returns the most-absorbing pick deterministically; reverb_factor=1 returns the most-reverberant pick deterministically; values in between sample up to max_retries random configurations and return the first whose mean Sabine RT is within ±acceptance_range seconds of the target. If none qualify, the closest fit is returned.

Parameters:

reverb_factor (float) – Optional, value in [0.0, 1.0] biasing the sampled configuration toward more reverberant (1.0) or more damped (0.0) acoustics.
seed (float) – Optional, seed for the random sampler.
max_retries (int) – Maximum random configurations to try before returning the closest fit. Defaults to 100.
acceptance_range (float) – Absolute Sabine-RT tolerance in seconds around the target. A sampled configuration is accepted if |sabine_rt - target| <= acceptance_range. Defaults to 0.1.

Returns list[MaterialAssignment]:

One MaterialAssignment per model layer.

get_bounding_box() → BoundingBox | None: Get the bounding box of the model. :returns BoundingBox | None: Bounding box of the model or None if unable to get bounding box.

get_min_distance_to_layer(point: Point3d | Receiver | Source, layer_names: list[str] | str) → float | None

Calculate the minimum distance from a point to a layer in layer_names in meters.

Parameters:

point (Point3d) – The point to measure distance from
layer_names (list[str]) – The names of the layers to measure distance to. Supports wildcard matching using fnmatch.

Return float | None:

The minimum distance from the point to the layer in meters, None if the layer has no geometry

get_surface_area_of_layers_m2() → dict[str, float]

Get the surface area of the layers in the model.

Returns dict[str, float]:: Dictionary with layer names as keys and surface area in m^2 as values.

has_line_of_sight(point_a: Point3d | Receiver | Source, point_b: Point3d | Receiver | Source) → bool

Check if two points have line-of-sight to each other within the model.

Parameters:

point_a (Point3d) – The first point
point_b (Point3d) – The second point

Return bool:

True if the points have line-of-sight (no mesh occlusion), False otherwise

plot(view_2d: View2d | None = None): Uses the plot module to plot the geometry object. :param view_2d: Show a 2d view, choose between None, View2d.xy, View2d.xz, View2d.yz. Optional, defaults to false.

suggest_crossover_frequency(material_assignments: list[MaterialAssignment | MaterialAssignmentDto], multiplier: float = 4.0, model_volume: float | None = None) → int

Suggests a DG/GA crossover frequency for a hybrid simulation as a multiple of the Schroeder frequency. Common practice is one to four times the Schroeder frequency; Treble defaults to four.

Parameters:

material_assignments (list[MaterialAssignment|MaterialAssignmentDto]) – Layer material assignment used for the Sabine estimate.
multiplier (float) – Factor applied to the Schroeder frequency, defaults to 4.
model_volume (float) – Optional, air volume in m³. Computed from the model if not given.

Returns int:

Suggested crossover frequency in Hz, rounded up and clamped to the accepted range [25, 44000].

validate_points_in_model(points: list[Point3d | Source | Receiver]) → PointsValidationResult

Validate that a list of points, sources, or receivers is inside the model.

Sources and receivers are checked at their positions.

property dataset: str

Dataset name for the geometry.

Returns str:: Dataset name.

property description: str

property id: str

property is_watertight: bool

property layer_names: list[str] | None

List of layer names in the geometry.

Returns list[str] | None:: Layer names or None if not available.

property layers: dict[str, ModelLayer]

Layer geometry of the model, keyed by layer name.

Each ModelLayer exposes its surfaces (sorted by Rhino object order), bounding box, area-weighted centroid, area in m², a unit normal when the layer is planar, and point_on() for parametrized positions in the surface plane.

property metadata: dict

Metadata dictionary for the geometry.

Returns dict:: Metadata key-value pairs.

property name: str

property position_suggestions: list[PositionSuggestion]

Suggested positions for placing sources or receivers in the geometry.

Returns list[PositionSuggestion]:: List of position suggestions.

property volume: float

largest outer shell minus inner volumes.

Type:: Air volume of the model in m³

property volumeM3: float

Volume of the geometry in cubic meters.

Returns float:: Volume in m³.

class treble_tsdk.core.geometry_library_obj.PositionSuggestion

Suggested position and orientation for placing sources or receivers in a geometry.

Provides recommended placement locations based on geometry analysis.

__init__(dto: PositionSuggestionDto)

property azimuth_angle: float | None

Azimuth angle in degrees.

Returns float | None:: Azimuth angle or None if not specified.

property elevation_angle: float | None

Elevation angle in degrees.

Returns float | None:: Elevation angle or None if not specified.

property name: str

property orientation: Rotation | None: Returns rotation if available, otherwise None.

property position: Point3d

3D position for the suggested placement.

Returns Point3d:: Position coordinates.

property roll_angle: float | None

Roll angle in degrees.

Returns float | None:: Roll angle or None if not specified.

property space: str

Space identifier for the position.

Returns str:: Space name.