treble_tsdk.core.device_obj

Classes

DeviceDefinition

Complete device specification with multiple microphones.

DeviceImpulseResponses

Time-domain impulse responses for device microphones.

DeviceMicrophone

Microphone information for device measurements/simulations.

DeviceObj

Object used to represent the device for the device related transfer function (DRTF)

DeviceSourceLocations

Source position coordinates for device measurements/simulations.

DeviceTransferFunctions

Frequency-domain transfer functions for device microphones.
class treble_tsdk.core.device_obj.DeviceDefinition

Complete device specification with multiple microphones.

Defines a device as a collection of microphones with associated transfer functions and metadata.

__init__(device_microphones: list[DeviceMicrophone], 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, extrapolate_frequency_range: bool = False, sampling_rate: int = 32000, crossover_frequency: int | None = None, max_frequency: float = 0, metadata: dict | None = None, client: TSDKClient | None = None, **kwargs)

Define a device as a list of DeviceMicrophone objects along with a name

Parameters:

  • device_microphones (list[DeviceMicrophone]) – An ordered list of the microphones on the device

  • name (str) – The name of the device

  • reference_frequency (float | None) – Reference frequency for the device. If None is given the transfer functions will not be normalized, defaults to 100 The median transfer function at the reference frequency is scaled to 0 dB, defaults to 100

  • description (str | None) – An optional description of the device, defaults to None

  • group (str | None) – An optional group of the device, defaults to None

  • measurement_radius (float | None) – The reference distance for the far field expansion, defaults to 1

  • apply_far_field_expansion (bool | None) – If True the far field expansion will be applied during device creation, defaults to False

  • linearize_phase (bool) – If True the phase will be or has been linearized during device creation from the max frequency, defaults to False

  • extrapolate_frequency_range (bool) – If True the frequency response will be extrapolated past the simulation crossover frequency and phase will be linearized, defaults to False

  • sampling_rate (int) – Sampling rate for the device transfer function, defaults to 32000

  • crossover_frequency (int | None) – Crossover frequency of the simulation the device was created from, if applicable, defaults to None

  • max_frequency (float) – The maximum valid frequency of the device, defaults to 0 which means that the maximum frequency is not known

  • metadata (dict | None) – The metadata of the device

  • client (TSDKClient | None) – The TSDK client.

plot_geometry(device_id: str | None = None)

Plot the original device geometry used to create this DRTF device.

Parameters:

device_id (str) – Optional device ID, used to retrieve the model via device-level access when the user does not have access to the original project.

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, if left empty, will plot all angles

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

property microphone_labels: list[str] | None

Microphone labels from device metadata.

Returns list[str] | None:

List of label strings, or None when no label data is stored in the metadata.

property microphone_positions: list[list[float]] | None

Microphone placement coordinates from device metadata.

Returns list[list[float]] | None:

List of [x, y, z] positions, or None when no placement data is stored in the metadata.

class treble_tsdk.core.device_obj.DeviceImpulseResponses

Time-domain impulse responses for device microphones.

Represents impulse responses measured at microphone locations from multiple source positions.

__init__(impulse_responses: numpy.ndarray, sampling_rate: float)

Class to define impulse responses at microphone location with respect to impulses from sources which are defined in DeviceSourceLocations

Parameters:

  • impulse_responses (np.ndarray) – An array of impulse responses where source number is the first axis and time the second one.

  • sampling_rate (float) – Temporal sampling rate (samples per second)

class treble_tsdk.core.device_obj.DeviceMicrophone

Microphone information for device measurements/simulations.

Combines source locations with impulse responses or transfer functions for a single microphone channel. This can be used to create a device definition for a device with multiple microphones.

__init__(source_locations: DeviceSourceLocations, recordings: DeviceImpulseResponses | DeviceTransferFunctions, max_ambisonics_order: int, label: str | None = None, **kwargs)

Class to define a microphone on a device for a device related transfer function It takes in the source locations and the respective impulse responses

Parameters:

  • source_locations (DeviceSourceLocations) – Location coordinates of sources

  • recordings (DeviceImpulseResponses | DeviceTransferFunctions) – Impulse responses (time domain) or the transfer functions (frequency domain) of the sources

  • max_ambisonics_order (int) – Maximum ambisonics order to use when rendering device

  • label (str) – Label of the microphone, optional

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

Plot the frequency domain transfer function, either for all angles or for a given azimuth and/or elevation

Parameters:

  • angle (Optional[tuple[float, float]]) – Azimuth angle and elevation angle corresponding to the ones in input, if left empty, will plot all angles, defaults to None

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

class treble_tsdk.core.device_obj.DeviceObj

Object used to represent the device for the device related transfer function (DRTF)

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

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

Return DeviceDefinition:

The definition and specifications of the device

plot()

Make an overview plot of the device

plot_geometry()

Plot the original device geometry used to create this DRTF device.

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 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[DeviceMicrophone]

List of microphones in the device.

Returns list[DeviceMicrophone]:

Device microphone objects.

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 kind: DeviceKind
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_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 microphone_labels: list[str] | None

Microphone labels from device metadata.

Returns the labels without downloading the device file.

Returns list[str] | None:

List of label strings, or None when no label data is stored in the device metadata.

property microphone_positions: list[list[float]] | None

Microphone placement coordinates from device metadata.

Returns the positions without downloading the device file.

Returns list[list[float]] | None:

List of [x, y, z] positions, or None when no placement data is stored in the device metadata.

property name: str
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

class treble_tsdk.core.device_obj.DeviceSourceLocations

Source position coordinates for device measurements/simulations.

Defines azimuth and elevation angles for sources used in device response measurements.

__init__(azimuth_deg: numpy.ndarray, elevation_deg: numpy.ndarray)

Define the source positions of the sources used to create the DRTF. They are defined in azimuthal degrees (rotation around z axis) and elevation/latitude degrees (rotation around y axis after applying the azimuthal rotation of the coordinate system).

We expect the azimuth degrees and the elevation degrees to have the same length

Parameters:

  • azimuth_deg (np.ndarray) – Azimuth degrees from center to sources

  • elevation_deg (np.ndarray) – Elevation degrees from center to sources

property azimuth_rad

Azimuth angles in radians.

Returns np.ndarray:

Azimuth in radians.

property colatitude_deg

Colatitude angles in degrees (90 - elevation).

Returns np.ndarray:

Colatitude in degrees.

property colatitude_rad

Colatitude angles in radians (π/2 - elevation).

Returns np.ndarray:

Colatitude in radians.

property elevation_rad

Elevation angles in radians.

Returns np.ndarray:

Elevation in radians.

class treble_tsdk.core.device_obj.DeviceTransferFunctions

Frequency-domain transfer functions for device microphones.

Represents transfer functions measured at microphone locations from multiple source positions.

__init__(transfer_functions: numpy.ndarray, frequency_array: numpy.ndarray, sampling_rate: int)

Class to define impulse responses at microphone location with respect to impulses from sources which are defined in DeviceSourceLocations

Parameters:

  • transfer_functions (np.ndarray) – An array of transfer functions where source number is the first axis and frequency on the second. If computed via FFT of impulse responses we expect that the FFT is scaled by time step

  • frequency_array (np.ndarray) – The frequencies associated with the second axis of the transfer_functions

  • sampling_rate (int) – Temporal sampling rate (samples per second)