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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| project_id | string | The 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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| name | string | Name 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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| client_id | string | Optional 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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| name | string | Name of project to search for | |
| description | string | Optional 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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| name | string | Name of project | |
| description | string | Optional 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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| project | string or Project object | Project 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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| category | MaterialCategory or string | Optional 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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| id | string | Project 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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| name | string | Name 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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| name | string | Optional. If provided the library will filter by geometry name. | |
| tag | string | Optional. If provided the library will filter by geometry tag. | |
| category | GeometryLibraryCategory or string | Optional. 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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| category | SourceDirectivityCategory | Optional. Source directivity type. | SourceDirectivityCategory.amplified |
| sub_category | SourceDirectivityAmplified, SourceDirectivityNatural or SourceDirectivityOther | Optional. Subcategory of the source directivity type. | SourceDirectivityAmplified.line_array |
| manufacturer | string | Optional. The source directivity manufacturer name. It is possible to search for parts of the manufacturer name, the search performed is not case-sensitive. | |
| name | string | Optional. Name of source directivity. It is possible to search for parts of the name, the search performed is not case-sensitive. | |
| sort_by | string | Optional. 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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| source_directivity_id | str | Unique 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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| name | str | Name of the source directivity | |
| source_directivity_file_path | str | Path to the source directivity file to upload. | |
| category | SourceDirectivityCategory | Category of the source directivity. | |
| sub_category | SourceDirectivityAmplified, SourceDirectivityNatural or SourceDirectivityOther | Optional, defaults to None. Please use SourceDirectivityAmplified if category is amplified, SourceDirectivityNatural if category is natural and SourceDirectivityOther if category is other. | |
| description | str | Optional, A short description of the source directivity. | |
| manufacturer | bool | Optional, Name of the manufacturer | |
| correct_ir_by_on_axis_spl_default | bool | When 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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| source_directivity | str, SourceDirectivityDto or SourceDirectivityObj | Source 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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| device_definition | DeviceDefinition | The 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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| device | str, DeviceObj or DeviceDto | A 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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| device | str, DeviceObj or DeviceDto | Identifier 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
| Parameter | Type | Description | Example value |
|---|---|---|---|
| download_dir | string | Directory 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 system | Credential 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