treble_tsdk.core.device_obj¶
Device definitions and device-related collections.
Exposes microphones, source locations, transfer functions and utilities to query and manage device data.
Classes
Complete device specification with multiple microphones. |
|
Time-domain impulse responses for device microphones. |
|
Microphone information for device measurements/simulations. |
|
Object used to represent the device for the device related transfer function (DRTF) |
|
Source position coordinates for device measurements/simulations. |
|
Frequency-domain transfer functions for device microphones. |
- 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: ndarray, sampling_rate: int)¶
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.DeviceSourceLocations¶
Source position coordinates for device measurements/simulations.
Defines azimuth and elevation angles for sources used in device response measurements.
- __init__(azimuth_deg: ndarray, elevation_deg: 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 elevation_rad¶
Elevation angles in radians.
- Returns np.ndarray:
Elevation in radians.
- 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.
- 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: ndarray, frequency_array: 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)
- 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
- 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_transfer_function(angle: tuple[float, float], frequency_range: tuple[float, float] | None = None)¶
Plot the frequency domain transfer function for a specific angle
- plot_geometry()¶
Plot the original device geometry used to create this DRTF device.
- 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)¶
- 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 max_frequency: float¶
Maximum valid frequency for the device.
- Returns float:
Maximum frequency in Hz.
- 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.
- update_group(group: str)¶
Update the device group assignment.
- Parameters:
group (str) – Group name to assign the device to.
- plot_transfer_function(angle: tuple[float, float], frequency_range: tuple[float, float] | None = None)¶
Plot the frequency domain transfer function for a specific angle
- plot()¶
Make an overview plot of the device
- plot_geometry()¶
Plot the original device geometry used to create this DRTF device.
- 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