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 display geometry library object 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).

estimate_rt(material_assignments: list[MaterialAssignment], output_std: bool = False) → list[float] | tuple[list[float], list[float]]

Estimate RT60 per octave band using a quick ray-cast + Sabine estimator.

On the first call the geometry samples interior seed points and casts rays to compute volume and per-layer equivalent absorbing area; the resulting Rt60Estimator is cached on the object. Subsequent calls reuse the cached geometry analysis and only re-apply the Sabine formula, so trying multiple material configurations is cheap.

Any MaterialAssignment that does not already carry a Material object is resolved via the SDK client attached to this geometry, so the caller can pass id-only assignments without supplying a separate client.

Parameters:

material_assignments (list[MaterialAssignment]) – Material per layer.
output_std (bool) – If True, also return the sample standard deviation across seeds for each octave band — useful as an uncertainty bound on the mean.

Returns:

When output_std is False (default), a single list[float] of mean RT60 [s] per octave band in the order (63, 125, 250, 500, 1000, 2000, 4000, 8000) Hz. When output_std is True, a tuple (mean, std) of two list[float] aligned to the same band order. For the full estimator output (per-seed RT60s, per-layer absorbing area, classification counts), use self._rt60_estimator directly after calling this method.

generate_flat_absorption_material_assignment(absorption: float) → list[MaterialAssignment]

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

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 geometry.

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 geometry.
Raises:: ValueError – If the geometry 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 geometry. :returns BoundingBox | None: Bounding box of the model or None if unable to get bounding box.

get_min_distance_to_layer(point: Point3d, 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

has_line_of_sight(point_a: Point3d, point_b: Point3d) → bool: Check if two points have line-of-sight to each other within the model. :param Point3d point_a: The first point :param Point3d point_b: 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.

property dataset: str

Dataset name for the geometry.

Returns str:: Dataset name.

property description: str

property id: str

property is_watertight: bool

Whether the geometry is watertight (closed volume).

Returns bool:: True if watertight.

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 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 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.