treble_tsdk.core.model_obj

Model objects and geometry-related helpers.

Includes model metadata, material assignment, mesh sizing and geometry checking utilities used by simulations.

Classes

`GeometryCheckerSettings`	Settings for geometry validation and processing.
`LocalMeshSizing`	Custom mesh sizing for a specific geometry layer.
`MaterialAssignment`	Material assignment for a geometry layer.
`ModelObj`	3D geometry model for acoustic simulations.
`ModelUploadInfo`	Information for uploading a new model.

class treble_tsdk.core.model_obj.GeometryCheckerSettings

Settings for geometry validation and processing.

Controls simplification thresholds, animation handling, and solver-specific processing.

__init__(simplification_threshold: float = 0.005, animation_timecode: float | None = None, ga_only: bool = False, **kwargs)

Advanced settings for geometry processing.

Parameters:

simplification_threshold (float) – Simplification threshold in meters.
animation_timecode (float) – Animation timecode for USD processing.
ga_only (bool) – If True, the geometry is considered non-watertight and advanced geometry analysis is skipped. This can help when uploading very large models that will only be used with GA simulations.

property animation_timecode: float

Animation timecode for USD processing.

Returns float:: Timecode value.

property ga_only: bool

Whether to skip advanced geometry analysis for GA-only simulations.

Returns bool:: True if geometry is GA-only.

property simplification_threshold: float

Geometry simplification threshold in meters.

Returns float:: Simplification threshold in meters.

class treble_tsdk.core.model_obj.LocalMeshSizing

Custom mesh sizing for a specific geometry layer.

Controls mesh quality and edge preservation for individual elements in a simulation.

__init__(layer_name: str, mesh_sizing_m: float, keep_exterior_edges: bool = False)

Represents a custom local mesh sizing assignment. Makes it possible to control the mesh quality of individual elements in a simulation.

Parameters:

layer_name (str) – Name of model layer to assign custom mesh sizing to.
mesh_sizing_m (float) – Mesh sizing in meters.
keep_exterior_edges (bool) – If True, ensures that the outline of the object is never altered, regardless of the meshing settings (including mesh size). Defaults to false.

property keep_exterior_edges: bool

Whether to preserve exterior edges during meshing.

Returns bool:: True if exterior edges should be preserved.

property layer_name: str

Name of the model layer for this mesh sizing.

Returns str:: Model layer name.

property mesh_sizing_m: float

Mesh sizing in meters.

Returns float:: Mesh size in meters.

class treble_tsdk.core.model_obj.MaterialAssignment

Material assignment for a geometry layer.

Associates a material with a specific layer and optionally overrides scattering coefficients.

__init__(layer_name: str, material: Material, scattering_coefficient: list[float] | float | None = None)

Represents a layer material assignment.

Parameters:

layer_name (str) – Name of layer to assign material to.
material (Material) – Material to assign to layer.
scattering_coefficient (float|list[float]) – If None then the default scattering coefficient defined in the selected material is used. If set it can either be a single value or a list of 8 values, one per octave band. If this is a single value then the value will be used to calculate scattering for all octave bands.

static assign_multiple(layer_names: list[str], material: Material) → list[MaterialAssignment]

Assigns the same material to multiple layers.

Parameters:

layer_names (list[str]) – List of layer names to assign material to.
material (Material) – Material to assign to layers.

Returns list[MaterialAssignment]:

List of material assignments.

set_material(value: Material)

Update the assigned material.

Parameters:: value (Material) – New material to assign.

property layer_name: str

Name of the model layer this material is assigned to.

Returns str:: Layer name.

property material_id: str

property material_name: str

property scattering_coefficient: list[float] | float | None

Scattering coefficient. Can be a single value or a list of 8 values, one per octave band.

Returns list[float] | float | None:: Scattering coefficient per octave band or single value.

class treble_tsdk.core.model_obj.ModelObj

3D geometry model for acoustic simulations.

Provides methods for model processing, validation, layer management, and visualization.

__init__(modelDto: ModelDto, model_file_path: str, client: TSDKClient)

add_tags(tags: list[str] | str) → bool: Add tags to the model.

as_live_model_status(): Uses the display_data module to show model status automatically updated until model has been processed

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

clone_model(new_project: ProjectDto | 'Project' | str, new_name: str = None) → 'ModelObj' | None

Create a clone of the model in a different project.

Return ModelObj | None:: New model object

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 model samples interior seed points and casts rays to compute volume and per-layer equivalent absorbing area; the resulting Rt60Estimator is cached on the model. 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 model, 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 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).

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_geometry_processing_feedback_json(destination_file: str) → bool

Download result json from Geometry Checking Service.

Parameters:: destination_file (str) – Filepath to download to.
Returns bool:: True if it was able to download the file.

get_geometry_processing_feedback_png(destination_file: str) → bool

Get model feedback image from geometry processing.

Parameters:: destination_file (str) – Path to download feedback image file to. F.ex. ‘/home/user/feedback.png’
Returns bool:: True if it was able to download the file.

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, _debug: DebugOptions = {})

Uses the plot module to plot the model.

Parameters:: view_2d – Show a 2d view, choose between None, View2d.xy, View2d.xz, View2d.yz. Optional, defaults to false.

plot_geometry_feedback(): Uses the plot module to plot the geometry feedback.

remove_tags(tags: list[str] | str) → bool: Remove tags from the model.

rename(model_name: str)

Rename the model.

Parameters:: model_name (str) – New name for the model.
Returns bool:: True if rename succeeded, False otherwise.

update_tags_from_server() → bool: Get tags for the model from the server, note that this will overwrite any unsaved local changes to tags.

wait_for_layer_names(max_retries=1000) → list[str] | None

Wait for model processing to complete and return layer names.

Parameters:: max_retries (int) – Maximum number of retries before stopping.
Returns list[str] | None:: List of layer names once processing is complete.

wait_for_model_processing(max_retries=1000) → str | None

Waits until model has been processed and then returns the model status.

Parameters:: max_retries (int) – Maximum number of retries before stopping, each retry waits 3 seconds.
Returns:: Model status, “Valid”, “NotValid”, “Error” or “Processing” in case of timeout.

property description: str

property id: str

property is_watertight: str

Whether the model geometry is watertight.

Returns str:: Watertight status.

property layer_names: list[str] | None

Names of all layers in the model.

Returns list[str] | None:: List of layer names or None if not yet available.

property name: str

property status: str

Current processing status of the model.

Returns str:: Status value (Valid, Processing, NotValid, Error).

property status_message: str

Detailed status message for the model.

Returns str:: Status message.

property tags: list[str]

Tags associated with the model.

Returns list[str]:: List of tag strings.

class treble_tsdk.core.model_obj.ModelUploadInfo

Information for uploading a new model.

Contains model metadata including name, file path, and processing settings.

__init__(model_name: str, model_file_path: str | 'GeometryDefinition', model_description: str = None, geometry_checker_settings: GeometryCheckerSettings | GeometryCheckerSettingsDto = None, metadata: dict[str, str] | ObjectMetadataDto | ObjectMetadata = None, tags: list[str] = None)