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, 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 | None) – If True the phase will be or has been linearized during device creation from the max frequency, defaults to False

  • max_frequency (float | None) – 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()

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

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

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 (int) – 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

Parameters:

device (DeviceObj) – The device object for that specific device

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 description: str
property device_microphones: list[DeviceMicrophone]

List of microphones in the device.

Returns list[DeviceMicrophone]:

Device microphone objects.

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_frequency: float

Maximum valid frequency for the device.

Returns float:

Maximum frequency in Hz.

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