treble_tsdk.core.device_obj

Classes

DeviceObj

Object used to represent a device.

DeviceType

An enumeration.
class treble_tsdk.core.device_obj.DeviceDefinition

Unified device definition for legacy transfer functions and processed IR data.

__init__(device_microphones=None, name: str = '', reference_frequency: float | None = 100, description: str | None = None, group: str | None = None, measurement_radius: float = 1, apply_far_field_expansion: bool = False, linearize_phase: bool = False, sampling_rate: int | None = None, crossover_frequency: int | None = None, max_frequency: float = 0, metadata: dict | None = None, client: TSDKClient | None = None, device_sources: list[DeviceSourceData] | None = None, measurement_angles: DeviceMeasurementAngles | None = None, simulation: Simulation | None = None, parent_simulation_id: str | None = None, device_source_filters: SourceFilters | None = None, device_mic_filters: MicFilters | None = None, reference_microphones: list[DeviceMicrophoneData] | None = None, **kwargs)

Create either a legacy V1 or processed V2 device definition.

Parameters:

  • description (str) – An optional user-defined description of the device, defaults to None.

  • group (str) – An optional identifier for a collection of devices, defaults to None.

  • device_source_filters – Filters to apply to the impulse responses of the device’s source layers whenever they are fetched, keyed by source layer name. Layers not listed are left unfiltered. Stored with the device, see set_source_filters.

  • device_mic_filters – Filters to apply to the channel of each device microphone in every device impulse response, keyed by microphone label. Microphones not listed are left unfiltered. Stored with the device, see set_mic_filters.

clear_mic_filters(mic_label: str | None = None) → None

Remove the filters of one device microphone, or of every microphone when mic_label is omitted.

clear_source_filters(source_layer: str | None = None) → None

Remove the filters of one source layer, or of every source layer when source_layer is omitted.

classmethod from_measurements(device_microphones, name: str, **kwargs) → DeviceDefinition

Create a legacy definition from measurement helper objects.

classmethod from_simulation(simulation: Simulation, name, ambisonics_order: int = 16, linearize_phase: bool = False, device_source_filters: Mapping[str, Sequence[FilterDefinition] | FilterDefinition] | None = None, device_mic_filters: Mapping[str, Sequence[FilterDefinition] | FilterDefinition] | None = None, description: str | None = None, group: str | None = None, **kwargs) → DeviceDefinition

Create a device definition from a device characterization simulation’s results.

Parameters:

  • simulation (Simulation) – The completed device characterization simulation.

  • name (str) – Name of the device to be created.

  • ambisonics_order (int) – Ambisonic order of the device.

  • linearize_phase (bool) – If True, linearizes phase from the max valid frequency.

  • device_source_filters – Filters to apply to the impulse responses of the device’s source layers, keyed by source layer name. Layers not listed are left unfiltered.

  • device_mic_filters – Filters to apply to the channel of each device microphone, keyed by microphone label. Microphones not listed are left unfiltered.

  • description (str) – An optional user-defined description of the device, defaults to None.

  • group (str) – An optional identifier for a collection of devices, defaults to None.

classmethod from_sofa_file(sofa_filepath, device_name: str, **kwargs) → DeviceDefinition

Create a legacy definition from a SOFA measurement file.

get_on_axis_reference_filter(source_index: int = 0, crossover_frequency: float | None = None, regularization: float = 0.001) → FIRFilter

Create a correction FIR filter from the on-axis impulse response of a device source.

The returned filter spectrally inverts the on-axis IR so that convolving it with another IR effectively puts that IR “in reference to” the on-axis response of this device source.

Parameters:

  • source_index (int) – Index of the device source to use, defaults to 0.

  • crossover_frequency (float) – Crossover frequency for the bandpass envelope. Defaults to None, which uses the source’s max_valid_frequency.

  • regularization (float) – Regularization parameter for the spectral inversion, expressed as a fraction of the peak spectral magnitude. Defaults to 1e-3.

Return FIRFilter:

A reference filter that inverts the on-axis response.

Raises:

  • IndexError – If source_index is out of range.

  • ValueError – If measurement angles are not available.

get_reference_mic_reference_filter(source_index: int = 0, mic_label: str | None = None, crossover_frequency: float | None = None, regularization: float = 0.001) → FIRFilter

Create a correction FIR filter from a reference microphone impulse response.

The returned filter spectrally inverts the reference microphone IR so that convolving it with another IR effectively puts that IR “in reference to” the reference microphone response of this device source.

Parameters:

  • source_index (int) – Index of the device source to use, defaults to 0.

  • mic_label (str) – Label of the reference microphone to use. Defaults to None, which uses the first available reference microphone.

  • crossover_frequency (float) – Crossover frequency for the bandpass envelope. Defaults to None, which uses the source’s max_valid_frequency.

  • regularization (float) – Regularization parameter for the spectral inversion, expressed as a fraction of the peak spectral magnitude. Defaults to 1e-3.

Return FIRFilter:

A reference filter that inverts the reference mic response.

Raises:

  • IndexError – If source_index is out of range.

  • ValueError – If no reference microphone responses are available, or if the specified mic_label is not found.

plot()

Interactive overview of the device. Impulse responses are shown with the source_filters and mic_filters applied.

plot_geometry()

Plot the device geometry (room mesh and microphone placements) from the simulation.

Reuses the same source-receiver-device geometry widget as treble_tsdk.DeviceObj.plot_geometry(), sourcing the model from the simulation attached to this definition.

Raises:

ValueError – If this definition was not created from a simulation.

plot_transfer_function(angle=None, frequency_range=None)

Plot the transfer function of the device.

Parameters:

  • angle – The angle to plot the transfer function for. Required for legacy devices.

  • frequency_range – The frequency range to plot the transfer function for.

set_mic_filters(mic_label: str, filters: Sequence[FilterDefinition] | FilterDefinition | None) → None

Set the filters applied, in order, to the channel of one device microphone in every device impulse response, whether rendered from a spatial impulse response or simulated on the device. They run after the source filters and before any other filters. The filters are stored with the device and the solver results stay unfiltered, so they can be changed without re-running a simulation.

Parameters:

  • mic_label (str) – Label of the device microphone.

  • filters – One filter or a list of filters, e.g. treble.GainFilter(gain=0.5). None or an empty list removes the filters of the microphone.

set_source_filters(source_layer: str, filters: Sequence[FilterDefinition] | FilterDefinition | None) → None

Set the filters applied, in order, to the impulse responses of one source layer whenever they are fetched from simulation results. The filters are stored with the device and the solver results stay unfiltered, so they can be changed without re-running a simulation.

Parameters:

  • source_layer (str) – Source layer name (see source_layer_names) or source label.

  • filters – One filter or a list of filters, e.g. treble.ButterworthFilter(lp_order=4, lp_frequency=2000). None or an empty list removes the filters of the layer.

with_filters_applied() → DeviceDefinition

Shallow copy of this definition whose device sources and microphones have their source_filters and mic_filters applied to their impulse responses, i.e. the device as it behaves in a simulation. Returns self when there are no filters.

property ambisonics_order: int | None

Maximum HNM order reported by any device microphone.

max_ambisonics_order stores the minimum order shared by all microphones for legacy compatibility; this property reports the maximum order available from an individual microphone.

Returns None if no microphones have an HNM order.

property is_processed: bool
property mic_filters: dict[str, list[FilterDefinition]]

Filters applied to the channel of each device microphone in every device impulse response, keyed by microphone label. Microphones without filters are omitted.

property microphone_labels
property microphone_positions
property source_filters: dict[str, list[FilterDefinition]]

Filters applied to the impulse responses of each source layer when they are fetched, keyed by source layer name. Layers without filters are omitted.

property source_layer_names: list[str]

Source layer names of the device, in source order.

class treble_tsdk.core.device_obj.DeviceH5

Access to the H5 file of a device, transparently local or remote.

Metadata (root attributes, keys, attributes of groups and datasets) is read from the locally cached file when it is available and streamed from the remote file with RemoteH5File otherwise, so inspecting a device does not force a download of the full file. Dataset contents are always read from local disk, downloading the file first if it is not cached yet.

Download URLs are signed and expire, so a new one is requested from the client whenever the current one stops working.

Parameters:

  • device_id (str) – Id of the device the file belongs to.

  • client (TSDKClient) – Client used to request download URLs.

  • url (str) – Download URL to start with, a new one is requested when it is not given or no longer works.

  • name (str) – Device name, used in progress and error messages.

  • cache_manager (CacheManager) – Cache manager to resolve the cache path with, defaults to the global cache manager.

__init__(device_id: str, client, url: str | None = None, name: str = 'device', cache_manager=None)
close()

Release the remote reader, if one was created.

Cached metadata is kept, closing only gives up the remote connection.

data() → Iterator[h5py.File]

Open the file for data access, downloading it first when needed.

Returns h5py.File:

The opened local file, valid within the context.

Raises:

ValueError – If the file could not be downloaded.

download() → bool

Download the file to the local cache unless it is already there.

Returns bool:

True if the file is available locally afterwards.

get_attr(key: str, path: str = '/', default: Any | None = None) → Any

Read a single attribute, without downloading the file when avoidable.

Parameters:

  • key (str) – Attribute name.

  • path (str) – Path of the item holding the attribute, "/" for the root.

  • default (Any) – Value to return when the attribute is missing.

Returns Any:

The attribute value, or default.

item_attrs(path: str = '/') → dict

Attributes of a group or dataset, read locally when cached, remotely otherwise.

The attributes of each path are memoized, including missing ones, so repeatedly asking for an attribute that is not there costs nothing.

Parameters:

path (str) – Path of the item within the file, "/" for the root.

Returns dict:

The attributes of the item, empty if it does not exist.

item_keys(path: str) → list[str]

Names of the members of a group, read locally when cached, remotely otherwise.

Parameters:

path (str) – Path of the group within the file.

Returns list[str]:

The member names, empty if the group does not exist.

mic_filters() → dict[str, list[FilterDefinition]]

Filter chain of each device microphone keyed by microphone label, read from the filters attribute of the microphone groups without downloading the file when avoidable. Microphones without filters are omitted.

read(path: str) → numpy.ndarray

Read a full dataset from the file, downloading it first when needed.

Parameters:

path (str) – Path of the dataset within the file, e.g. "Hnm".

Returns np.ndarray:

The dataset contents.

refresh_url() → str

Request a new download URL, discarding the remote reader bound to the old one.

Returns str:

The new download URL.

source_filters() → dict[str, list[FilterDefinition]]

Filter chain of each source layer keyed by source layer name, read from the filters attribute of the device_sources/src_XXXX groups without downloading the file when avoidable. Layers without filters are omitted.

property attrs: dict

Root attributes of the file, read locally when cached, remotely otherwise.

property is_downloaded: bool

Whether the full file is available on local disk.

property local_path: Path

Path of the file in the local cache, whether or not it has been downloaded.

property url: str

Current download URL, requested from the client if there is none yet.

class treble_tsdk.core.device_obj.DeviceImpulseResponses

Time-domain impulse responses for device microphones.

__init__(impulse_responses: numpy.ndarray, sampling_rate: float)
class treble_tsdk.core.device_obj.DeviceMicrophone

Microphone input data for a legacy device definition.

Deprecated since version Use: DeviceMicrophoneData directly when constructing a DeviceDefinition. This class is retained only for backward compatibility with existing user code that builds V1 device definitions from measurement input.

This is a thin subclass of DeviceMicrophoneData that adds a convenience constructor accepting a recordings object (DeviceImpulseResponses or DeviceTransferFunctions) and unpacks it into the DeviceMicrophoneData fields. It shares the DeviceMicrophoneData data model, so instances are accepted wherever a DeviceMicrophoneData is.

__init__(source_locations: DeviceSourceLocations, recordings: DeviceImpulseResponses | DeviceTransferFunctions, max_ambisonics_order: int, label: str | None = None, **kwargs)
plot_transfer_function(angle: tuple[float, float] | None = None, frequency_range: tuple[float, float] | None = None)
with_filters_applied() → DeviceMicrophoneData

Copy of this microphone whose impulse responses (balloon and HNM) have filter_definitions applied, as its channel of a device impulse response has. The copy carries no filters of its own so they are not applied twice. Legacy (frequency-domain) microphones are returned unchanged.

filter_definitions: list[FilterDefinition]

Filters applied, in order, to the channel of this microphone in every device impulse response.

property frequency: numpy.ndarray

Frequency array corresponding to hnm, in Hz.

frequency_array: np.ndarray | None = None
property hnm: numpy.ndarray

Frequency-domain SH coefficients, shape (n_channels, n_freq), with phase referenced to t=0 (the hnm_ir zero-pad pre-delay is removed).

hnm_ir: SpatialIR | None = None
label: str = ''
legacy_hnm: np.ndarray | None = None
location: Point3d | None = None
property max_ambisonics_order: int

Maximum spherical-harmonics order for this microphone.

max_valid_frequency: float | None = None
project_to_mesh: bool | None = None
sampling_rate: float | None = None
source_locations: DeviceSourceLocations | None = None
sphere_mono_irs: list[MonoIR] | None = None
transfer_function: np.ndarray | None = None
class treble_tsdk.core.device_obj.DeviceObj

Object used to represent a device.

This is the unified device class that supports both regular DRTF devices (formerly DeviceObj) and source-receiver devices (formerly SourceReceiverDevice). The device_type property can be used to discriminate between the underlying types.

__init__(deviceDto: DeviceDto, client: TSDKClient)
device_definition_from_object() → DeviceDefinition

Create a device definition from the device file which the device object points to.

Deprecated since version Use: get_definition() instead.

get_definition() → DeviceDefinition

Get the device definition for this device.

Downloads the device file on first access and reads it as a unified DeviceDefinition, regardless of the underlying file layout. Processed (V2) files expose device sources, measurement angles and simulation-derived acoustic data; legacy (V1) files expose the frequency-domain measurement structure through the same interface.

Return DeviceDefinition:

The definition and specifications of the device

get_mic_filters(mic_label: str) → list[FilterDefinition]

Filters applied to the channel of one device microphone, in application order; empty when the microphone has none.

Parameters:

mic_label (str) – Label of the device microphone.

get_on_axis_reference_filter(source_index: int = 0, crossover_frequency: float | None = None, regularization: float = 0.001)

Create a correction FIR filter from the on-axis impulse response of a device source.

Parameters:

  • source_index (int) – Index of the device source to use, defaults to 0.

  • crossover_frequency (float) – Crossover frequency for the bandpass envelope. Defaults to None, which uses the source’s max_valid_frequency.

  • regularization (float) – Regularization parameter for the spectral inversion. Defaults to 1e-3.

Return FIRFilter:

A reference filter that inverts the on-axis response.

get_reference_mic_reference_filter(source_index: int = 0, mic_label: str | None = None, crossover_frequency: float | None = None, regularization: float = 0.001)

Create a correction FIR filter from a reference microphone impulse response.

Parameters:

  • source_index (int) – Index of the device source to use, defaults to 0.

  • mic_label (str) – Label of the reference microphone. Defaults to None (first available).

  • crossover_frequency (float) – Crossover frequency for the bandpass envelope. Defaults to None, which uses the source’s max_valid_frequency.

  • regularization (float) – Regularization parameter for the spectral inversion. Defaults to 1e-3.

Return FIRFilter:

A reference filter that inverts the reference mic response.

get_source_filters(source_layer: str) → list[FilterDefinition]

Filters applied to the impulse responses of one source layer whenever they are fetched, in application order; empty when the layer has none.

Parameters:

source_layer (str) – Source layer name (see source_layer_names).

get_source_receiver_device_definition()

Get the device definition for the device.

Deprecated since version Use: get_definition() instead, which handles all device file formats.

plot()

Make an overview plot of the device.

For V2 (source-receiver) devices, delegates to the V2 definition’s plot method. For V1 (DRTF) devices, uses the legacy plot_device method.

plot_geometry()

Plot the original device geometry used to create this device.

For V2 (source-receiver) devices, downloads the model file and uses the SRD geometry plot. For V1 (DRTF) devices, uses the legacy geometry plot.

plot_transfer_function(angle: tuple[float, float], frequency_range: tuple[float, float] | None = None)

Plot the frequency domain transfer function for a specific angle

Parameters:

  • angle (tuple[float, float]) – Azimuth angle and elevation angle corresponding to the ones in input

  • frequency_range (Optional[tuple[float, float]]) – Frequency range to plot, defaults to None

update_group(group: str)

Update the device group assignment.

Parameters:

group (str) – Group name to assign the device to.

property ambisonics_order: int | None

Ambisonics order for source-receiver devices.

Returns int | None:

Ambisonics order, or None for regular devices.

property crossover_frequency: float

Returns the upper bound frequency for the device free-field simulation

Returns float:

The crossover frequency (upper bound) for the simulation used to create this device

property description: str
property device_microphones: list[DeviceMicrophoneInfo]

List of microphone placement metadata for the device.

Returns DeviceMicrophoneInfo objects (label, location, project_to_mesh) for all device types. For source-receiver devices these are parsed from deviceMicrophonesJson; for V1 (ReceiverDevice) devices they are read from the H5 labels attribute and metadata positions without downloading the full device file.

For full acoustic data (transfer functions, HNM, IRs), use get_definition() and access definition.device_microphones which returns DeviceMicrophoneData objects.

Returns list[DeviceMicrophoneInfo]:

Device microphone placement objects.

property device_type: DeviceType

Device type.

Returns DeviceType:

Device type.

property extrapolated_frequency_range: bool

Whether frequency range extrapolation was applied during device creation.

Returns bool:

True if frequency range extrapolation was applied.

property far_field_expanded: bool

Whether far field expansion was applied during device creation.

Returns bool:

True if far field expansion applied.

property group: str

Device group for organization.

Returns str:

Group name.

property id: str
property linearized_phase: bool

Whether phase linearization at and above the maximum frequency was applied during device creation.

Returns bool:

True if phase linearization applied.

property max_ambisonics_order: int

Maximum ambisonics order supported by the device.

property max_crossover_frequency: int | None

Maximum crossover frequency for source-receiver devices.

Returns int | None:

Max crossover frequency, or None for regular devices.

property max_frequency: float

Maximum valid frequency for the device.

Returns float:

Maximum frequency in Hz.

property metadata: ObjectMetadata

Key-value metadata associated with the device.

property mic_filters: dict[str, list[FilterDefinition]]

Filters applied to the channel of each device microphone in every device impulse response, whether rendered from a spatial impulse response or simulated on the device, keyed by microphone label. Microphones without filters are omitted. Read from the device file on first use.

Returns dict[str, list[FilterDefinition]]:

Filter chain per microphone, in application order.

property microphone_labels: list[str] | None

Microphone labels.

Deprecated since version Use: device_microphones and read mic.label from each DeviceMicrophoneInfo instead.

Returns list[str] | None:

List of label strings, or None when no label data is available.

property name: str
property parent_simulation_id: str | None

Parent simulation ID for source-receiver devices.

Returns str | None:

Parent simulation ID, or None for regular devices.

property reference_microphones: list[DeviceMicrophoneInfo]

All reference microphone placements from the parent simulation.

Returns an empty list when the device has no parent simulation. These are all reference microphones of the parent simulation; they are renderable only if the simulation was run with render_reference_microphones=True.

property sampling_rate: float

Returns the sampling rate of the device free-field simulation

Returns float:

The sampling rate for the simulation used to create this device

property simulation: Simulation | None

Parent Simulation the device was created from, or None.

Resolved lazily from parent_simulation_id (falling back to the simulation stored in the device file) and cached, including the None result, so repeated access does not re-query the API.

property source_filters: dict[str, list[FilterDefinition]]

Filters applied to the impulse responses of each source layer of a source-receiver device whenever they are fetched from simulation results, keyed by source layer name (see source_layer_names). Layers without filters are omitted. Read from the device file on first use.

Returns dict[str, list[FilterDefinition]]:

Filter chain per source layer, in application order.

property source_layer_names: list[str]

Source layer names for source-receiver devices.

Returns list[str]:

List of source layer names, or None for regular devices.

class treble_tsdk.core.device_obj.DeviceSourceLocations

Source position coordinates for device measurements and simulations.

__init__(azimuth_deg: numpy.ndarray, elevation_deg: numpy.ndarray)
property azimuth_rad
property colatitude_deg
property colatitude_rad
property elevation_rad
class treble_tsdk.core.device_obj.DeviceTransferFunctions

Frequency-domain transfer functions for device microphones.

__init__(transfer_functions: numpy.ndarray, frequency_array: numpy.ndarray, sampling_rate: int)
class treble_tsdk.core.device_obj.DeviceType

An enumeration.

receiver_device = 'ReceiverDevice'
source_device = 'SourceDevice'
source_receiver_device = 'SourceReceiverDevice'