Skip to main content

TSDK Reference

TSDK

When starting a SDK session you will need to create a TSDK object which will allow you to interface with the SDKs various features.

SDK Login

Most users that have followed the installation guide can take advantage of the automatic credential detection of the SDK and simply login using:

tsdk = TSDK()

For more details information on how the automatic credentials detection works please see Appendix I - Automatic credential detection

If for some reason you are not able to utilize the automatic credentials detections of the SDK. Then you can provide the path to your .cred file manually:

tsdk = TSDK(TSDKCredentials.from_file('/path/to/my_credentials.cred'))

SDK Single Sign-On (SSO) login

SSO users will need to login through the SSO portal at https://manage.treble.tech/ and follow the instructions there. In short the SDK will try and auto-detect SSO tokens stored in the TSDK_SSO_TOKEN environment variable, but users can also provide the token manually using:

# NOTE: We recommend storing your SSO token somewhere safe!
tsdk = TSDK(TSDKCredentials.sso('my_sso_token'))

Methods

Project methods

get_project

Get the project with the associated id.

Arguments

ParameterTypeDescriptionExample value
project_idstringThe unique id of the requested project.'380a3980-721a-4e80-95df-484f519c525c'

Returns

Project object if found, else None.

Examples

# Fetching a project results in a Project object
p = tsdk.get_project('8b84315d-e6c3-4cb5-813f-f1abf247bdb6')
assert p

# Fetching a project that does not exist returns None.
p = tsdk.get_project('00000000-0000-0000-0000-000000000000')
assert p is None

# Fetching project with an invalid id will return None and log out validation error.
p = tsdk.get_project('This is not a valid id')
assert p is None

get_project_by_name

Gets a project by name, if multiple projects match the name the one created the most recently is returned.

Arguments

ParameterTypeDescriptionExample value
namestringName of the requested project.

Returns

Project object if found, else None.

Examples

# Project found.
p = tsdk.get_project_by_name('My Project')
assert p

# Project not found
p = tsdk.get_project_by_name('Not found')
assert p is None

list_projects

Get a list of projects within your organization.

Arguments

ParameterTypeDescriptionExample value
client_idstringOptional parameter that can be used to filter the output to only include projects that this client_id created. (See list_my_projects)'380a3980-721a-4e80-95df-484f519c525c'

Returns

List[Project]

Examples

# Get a list of all project within organization.
projects = tsdk.list_projects()
assert projects

# This list can be visualized using the display_data module.
dd.as_table(projects)

list_my_projects

Get a list of projects within your organization that your account has created. (See list_projects)

Arguments

None

Returns

List[Project]

Examples

projects = tsdk.list_my_projects()
assert projects

get_or_create_project

Looks for a project with the given name, if it's not found it will create the project and return it.

Arguments

ParameterTypeDescriptionExample value
namestringName of project to search for
descriptionstringOptional argument, description of project if a new one is created.

Returns

Project object

Examples

project = tsdk.get_or_create_project('Example project')
assert project

create_project

Creates a new project.

Note: If a project with the same name already exists a new one with the same name will be created. See get_or_create_project.

Arguments

ParameterTypeDescriptionExample value
namestringName of project
descriptionstringOptional argument, description of project.

Returns

Project object

Examples

project = tsdk.create_project('CreateProjectTest', description='Project description')
assert project

delete_project

Deletes a project.

Note: Make sure you dispose of the project object after deleting it.

Arguments

ParameterTypeDescriptionExample value
projectstring or Project objectProject to delete.

Returns

bool - True if project was successfully deleted, False if project was not deleted.

Examples

# Delete a project from a project object.
res = tsdk.delete_project(project)
assert res is True

# Deleting a project by supplying it's id is also possible. In this case the project has already been
# deleted so the action will fail.
res = tsdk.delete_project(project.id)
assert res is False

# Deleting an already deleted project will return False and log a warning that the project was not found.
res = tsdk.delete_project(project)
assert res is False

# Trying to delete and non-existing project
res = tsdk.delete_project('00000000-0000-0000-0000-000000000000')
assert res is False

MaterialLibrary

The SDK includes an extensive library of predefined materials. Users are also able to create their own materials.

material_library.get

Fetches all materials available in the material library with the option to filter materials by a certain category.

Arguments

ParameterTypeDescriptionExample value
categoryMaterialCategory or stringOptional parameter that can contain a MaterialCategory to filter by.MaterialCategory.gypsum

Returns

List[MaterialDto] - A list of MaterialDto objects that can be used for simulation material assignment. (See Appendix II - Information on Dto classes)

Examples

# Fetch all available materials
all_materials = tsdk.material_library.get()
assert all_materials
# Visualize the material database as table.
dd.as_table(all_materials)

# Fetch all materials within a specific category.
gypsum_materials = tsdk.material_library.get(category=treble.MaterialCategory.gypsum)
assert gypsum_materials
dd.as_table(gypsum_materials)

# Material categories can also be specified as strings. See get_categories() for list of available category strings.
porous_materials = tsdk.material_library.get(category='Porous')
assert porous_materials
dd.as_table(porous_materials)

# If material does not exist then an empty list is returned.
no_materials = tsdk.material_library.get(category='Empty Category')
assert len(no_materials) == 0

material_library.get_by_id

Fetches a material by it's unique identifier.

Arguments

ParameterTypeDescriptionExample value
idstringProject to delete.'e2bf6da8-81ad-4e15-a5e6-8e87f72a0b27'

Returns

MaterialDto - A MaterialDto object or None if Material was not found. (See Appendix II - Information on Dto classes)

Examples

# Get a material by it's unique identifier.
flat_20p_absorption = tsdk.material_library.get_by_id('f155a4e5-47bf-41a8-9324-26548134db65')
assert flat_20p_absorption

# Display material information as tree.
dd.as_tree(flat_20p_absorption)

# If material is not found the method will return None.
res = tsdk.material_library.get_by_id('00000000-0000-0000-0000-000000000000')
assert res is None

material_library.get_categories

Fetches a list of all available material categories.

Arguments

No arguments

Returns

List[str] - List of available material categories as strings.

Examples

# Print out available categories.
print(tsdk.material_library.get_categories())

material_library.get_categories_with_count

Fetches a list of all available material categories.

Arguments

No arguments

Returns

List[CategoryInfoDto] - List of CategoryInfoDto objects. (See Appendix II - Information on Dto classes).

Examples

# Get categories with count.
categories = tsdk.material_library.get_categories_with_count()
assert categories

# Each CategoryInfoObject has a `name` and `count` property.
# We can visualize the results as a table.
dd.as_table(categories)

material_library.search

Searches for a material with a given name.

Note: The search is not case sensitive and you can search for parts of the name. See examples.

Arguments

ParameterTypeDescriptionExample value
namestringName of material to search for.

Returns

List[[MaterialDto](dtos/#materialdto)] - A list of MaterialDto objects that can be used for simulation material assignment. (See Appendix II - Information on Dto classes)

Examples

# Search for materials with 'Gypsum' in the name.
materials = tsdk.material_library.search(name='Gypsum')
assert materials
dd.as_table(materials)

# The search function does not care about upper- or lower-case letters.
materials2 = tsdk.material_library.search(name='GYPSUM')
assert len(materials) == len(materials2)

# You can also search for parts of word.
materials = tsdk.material_library.search(name='ypsum')
assert len(materials) == len(materials2)


GeometryLibrary

The geometry library provides geometry datasets that can be used for simulation purposes.

geometry_library.query

Query the Geometry library by name, tag, category or, if no arguments are provider, fetch all available geometries.

Arguments

ParameterTypeDescriptionExample value
namestringOptional. If provided the library will filter by geometry name.
tagstringOptional. If provided the library will filter by geometry tag.
categoryGeometryLibraryCategory or stringOptional. If provided the library will filter by geometry category.

Returns

List[GeometryLibraryObj]] - A list of GeometryLibraryObj objects that can be used as geometries in simulations. (See GeometryLibraryObj)

Examples

# Fetch all available geometries.
all_geometries = tsdk.geometry_library.query()
assert all_geometries

# Fetch by name
meeting_room_100 = tsdk.geometry_library.query(name='Meeting room 100')
assert len(meeting_room_100) == 1

# Fetch by tag
meeting_rooms = tsdk.geometry_library.query(tag='meeting_room')
assert meeting_rooms

# Fetch by category
meeting_rooms = tsdk.geometry_library.query(category=treble.GeometryLibraryCategory.meeting_room)
assert meeting_rooms

# Fetch category by string
meeting_rooms = tsdk.geometry_library.query(category='MeetingRoom')
assert meeting_rooms

# You can also fetch by a combination of parameters.
# F.ex. fetch a geometry in the meeting room category with tag 'medium'.
medium_meeting_rooms = tsdk.geometry_library.query(
category=treble.GeometryLibraryCategory.meeting_room,
tag='medium'
)
assert medium_meeting_rooms

# As with most collection results we can visualize them using dd.as_table.
dd.as_table(medium_meeting_rooms)

# No data returned.
no_data = tsdk.geometry_library.query(name='Non existing geometry')
assert len(no_data) == 0

geometry_library.get_categories

Get available geometry library categories.

Note: This method may return more categories than are available through treble.GeometryLibraryCategory since GeometryLibraryCategory is dependent on your SDK version but get_categories queries Trebles servers for an up-to-date category list.

Arguments

None

Returns

List[str]] - A list of category names.

Examples

# Print out available categories.
print(tsdk.geometry_library.get_categories())

geometry_library.get_categories_with_count

Get available geometry library categories with the number of geometries in each category.

Note: This method may return more categories than are available through treble.GeometryLibraryCategory since GeometryLibraryCategory is dependent on your SDK version but get_categories queries Trebles servers for an up-to-date category list.

Arguments

None

Returns

List[CategoryInfoDto] - A list of categories with geometry counts.

Examples

categories = tsdk.geometry_library.get_categories_with_count()

# Visualize data
dd.as_table(categories)

Source Directivity Library

source_directivity_library.query

Query the source directivity database.

Arguments

ParameterTypeDescriptionExample value
categorySourceDirectivityCategoryOptional. Source directivity type.SourceDirectivityCategory.amplified
sub_categorySourceDirectivityAmplified, SourceDirectivityNatural or SourceDirectivityOtherOptional. Subcategory of the source directivity type.SourceDirectivityAmplified.line_array
manufacturerstringOptional. The source directivity manufacturer name. It is possible to search for parts of the manufacturer name, the search performed is not case-sensitive.
namestringOptional. Name of source directivity. It is possible to search for parts of the name, the search performed is not case-sensitive.
sort_bystringOptional. Parameter to sort the list by, defaults to name. Allowed values: "name" or "manufacturer".

Returns

List[SourceDirectivityObj] - A list of source definition objects.

Examples

# Get all source directivities of type Amplified.
amplified_directivities = tsdk.source_directivity_library.query(category=treble.SourceDirectivityCategory.amplified)
assert amplified_directivities

# Search for directivity using multiple parameters.
genelec_80XX = (tsdk.source_directivity_library.query(name='80', manufacturer='genelec'))
assert genelec_80XX
# dd.as_table(genelec_80XX)
# Source directivity table
#┏━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
#┃ Index ┃ Name ┃ Description ┃ Category ┃ Sub category ┃ Manufacturer ┃
#┡━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
#│ 0 │ 8020A │ Two-way active loudspeaker │ Amplified │ Studio and Broadcast monitors │ Genelec Oy │
#│ 1 │ 8030A │ Two-way active loudspeaker │ Amplified │ Studio and Broadcast monitors │ Genelec Oy │
#│ 2 │ 8040A │ Two-way active loudspeaker │ Amplified │ Studio and Broadcast monitors │ Genelec Oy │
#└───────┴───────┴────────────────────────────┴───────────┴───────────────────────────────┴──────────────┘

source_directivity_library.query

Get a single source directivity by it's unique id.

Arguments

ParameterTypeDescriptionExample value
source_directivity_idstrUnique id of source directivity.'380a3980-721a-4e80-95df-484f519c525c'

Returns

SourceDirectivityObj - A source definition object.

Examples

directivity = tsdk.source_directivity_library.get_by_id('1fb312cc-fb7f-4e60-a646-dc8d0d876e7e')
assert directivity

source_directivity_library.create_source_directivity

Create a new source directivity object from file. Note, uploaded source directivities will be accessible to all users within your organization.

Arguments

ParameterTypeDescriptionExample value
namestrName of the source directivity
source_directivity_file_pathstrPath to the source directivity file to upload.
categorySourceDirectivityCategoryCategory of the source directivity.
sub_categorySourceDirectivityAmplified, SourceDirectivityNatural or SourceDirectivityOtherOptional, defaults to None. Please use SourceDirectivityAmplified if category is amplified, SourceDirectivityNatural if category is natural and SourceDirectivityOther if category is other.
descriptionstrOptional, A short description of the source directivity.
manufacturerboolOptional, Name of the manufacturer
correct_ir_by_on_axis_spl_defaultboolWhen enabled, the impulse response gets corrected with the on axis SPL levels. It is recommended to enable this for most amplified sources, but to disable it for sources where the response is embedded in the source signal. Note that the SPL parameter and frequency response plots in the results will always be corrected.

Returns

SourceDirectivityObj - A source directivity object which can be used to define directive sources.

Examples

my_source_directivity = tsdk.source_directivity_library.create_source_directivity(
name='My source directivity',
source_directivity_file_path='/path/to/directivity/test.CF2',
category=treble.SourceDirectivityCategory.amplified,
sub_category=treble.SourceDirectivityAmplified.portable,
description="Test source directivity",
correct_ir_by_on_axis_spl_default = True
)
assert my_source_directivity

source_directivity_library.delete_source_directivity

Delete an uploaded source directivity from your organization's library.

Arguments

ParameterTypeDescriptionExample value
source_directivitystr, SourceDirectivityDto or SourceDirectivityObjSource directivity to delete.

Returns

bool - True if source directivity was deleted successfully, false otherwise. If input was invalid it will log out an error.

Examples

res = tsdk.source_directivity_library.delete_source_directivity(source_directivity='00000000-0000-0000-0000-000000000000')
assert res is False

res = tsdk.source_directivity_library.delete_source_directivity(source_directivity=my_source_directivity)
assert res is True

Device library

device_library.add_device

Upload a device. TODO: Add ref to device guide.

Arguments

ParameterTypeDescriptionExample value
device_definitionDeviceDefinitionThe DeviceDefinition object.

Returns

DeviceObj object if device was added successfully, None if device creation failed.

Examples

# Create a device object from our device_definition.
device_obj = tsdk.device_library.add_device(device_definition)
assert device_obj

device_library.get_device

Get device information as DeviceObj.

Arguments

ParameterTypeDescriptionExample value
devicestr, DeviceObj or DeviceDtoA DeviceObj object.

Returns

DeviceObj object if device was added successfully, None if fetching device failed.

Examples

# Get device by object
device = tsdk.device_library.get_device(device_obj)
assert device

# Get device by id
device = tsdk.device_library.get_device('380a3980-721a-4e80-95df-484f519c525c')

# Device not found.
device = tsdk.device_library.get_device('00000000-0000-0000-0000-000000000000')
assert device is None

# Invalid input
device = tsdk.device_library.get_device('hello')
assert device is None

device_library.get_devices

Returns a list of DeviceDto objects belonging to the organization.

Arguments

None

Returns

list[DeviceDto] - Returns a list of organization's DeviceDto objects.

Examples

device_list = tsdk.device_library.get_devices()
# Visualize the device list as a table.
dd.as_table(device_list)

device_library.delete_device

Delete device.

Arguments

ParameterTypeDescriptionExample value
devicestr, DeviceObj or DeviceDtoIdentifier of device to delete.

Returns

bool True if device was deleted successfully, False otherwise.

Examples

# Remove device by id.
res = tsdk.device_library.delete_device('c302115c-d00f-4e22-a444-a969d872b7bc')
assert res is True

# Device not found.
res = tsdk.device_library.delete_device('00000000-0000-0000-0000-000000000000')
assert res is False

# Invalid input
res = tsdk.device_library.delete_device('hello')
assert res is False

Other methods

check_for_updates

Checks if there is an updated version of the SDK available and writes the patch notes to the console.

Arguments

None

Returns

A SdkVersionDto if it's able to check for updates, None otherwise.

Examples

update_dto = tsdk.check_for_updates()
assert update_dto
print(f'Is update available? {update_dto.update_available}')

download_update

Download update package .whl file to a directory. If no update is available it will not download anything.

Arguments

ParameterTypeDescriptionExample value
download_dirstringDirectory to download python package to.'/path/to/directory'

Returns

Nothing

Examples

import tempfile
import glob
with tempfile.TemporaryDirectory() as tmp_dir:
tsdk.download_update(tmp_dir)

get_update_url

Gets a url to the updated python package .whl file.

Arguments

None

Returns

The url to download the update as a string.

Examples

url = tsdk.get_update_url()

Appendix

Appendix I - Automatic credential detection

Depending on your operation system the SDK will search for a .cred file in the following directories:

Operating systemCredential search path
Windows%userprofile%/AppData/Local/treble/tsdk/tsdk.cred and %userprofile%/AppData/Roaming/treble/tsdk/tsdk.cred
Linux~/.config/treble/tsdk.cred
Macos~/.config/treble/tsdk.cred and ~/Library/Application Support/treble/tsdk.cred

If it can't find your credentials file it will search for your credentials in the TSDK_CREDENTIALS environment variable.

Appendix II - Information on Dto classes

Classes with Dto at the end are so called Data Transfer Objects and are classes that are created to hold certain type of data. These classes usually do not provide any functionality other than containing data of a specific type.

In many cases these classes can be used interchangeably with their non-Dto counterpart. F.ex. when creating a SimulationDefinition you can supply a ModelDto or ModelObj for the model parameter.

A list of available DTOs can be found here