treble_tsdk.free_field.results¶
Classes
- class treble_tsdk.free_field.results.FreeFieldResults¶
- __init__(simulation: Simulation, data_reader: DataReaderBase, result_type: SimulationType | None = None)¶
A class which is designed to contain the results of a simulation.
- Parameters:
simulation (Simulation) – The relevant simulation object
data_reader (DataReaderBase) – The data reader to read the results from
result_type (ResultType | None) – The type of results to be used, defaults to the simulation type
- create_boundary_velocity_submodel(source_name: str, source_description: str, source: str | Source | None = None) BoundaryVelocitySubmodel¶
- create_drtf(device_name: str, ambisonics_order: int, device_description: str | None = None, microphone_labels: list[str] | None = None, apply_far_field_expansion: bool = True, linearize_phase: bool = False) DeviceDefinition¶
Create the directivity response transfer function
- Parameters:
device_name (str) – Name of the device
ambisonics_order (int) – Ambisonics order of the device
device_description (str | None) – Description of the device, defaults to None
microphone_labels (list[str] | None) – Labels of the microphones. Can be useful to keep track of the microphones, defaults to None
apply_far_field_expansion (bool) – If True the far field expansion will be applied during device creation, defaults to True
linearize_phase (bool) – If True the phase will be linearized during device creation from the max valid frequency. The max valid frequency is when spherical harmonics fits start to deviate from the input data. Linearizing the phase is a good way of making device response sound perceptually plausible for lower ambisonics orders, defaults to False
- Return DRTF.DeviceDefinition:
The device definition
- create_source_directivity(category: SourceDirectivityCategory, sub_category: SourceDirectivityAmplified | SourceDirectivityNatural | SourceDirectivityOther, name: str, source: str | Source | None = None, manufacturer: str | None = None, description: str | None = None) SourceDirectivityObj¶
- get_acoustic_parameters(source: SourceDto | str, receiver: ReceiverDto | str) AcousticParameters¶
Get acoustic result parameters for a particular source and receiver, if receiver is not given
- Parameters:
source (SourceDto) – A source associated with the simulation
receiver (ReceiverDto | None) – A receiver associated with the simulation and source, defaults to None
- Returns:
Acoustic parameters for the source and receiver. If device is true, the parameters for each microphone on the device are returned as a list of AcousticParameters.
- get_device_ir(source: SourceDto | str, receiver: ReceiverDto | str) DeviceIR¶
Receive a device rendered impulse response object from the simulation for a specific source and receiver. If receiver is not a device type, an exception will be raised.
- Parameters:
source (SourceDto) – A source associated with the simulation
receiver (ReceiverDto) – A receiver associated with the simulation and source
- Return DeviceIR:
A device IR object corresponding to the input specifications
- get_mono_ir(source: SourceDto | str, receiver: ReceiverDto | str) MonoIR¶
Receive a mono impulse response object from the simulation for a specific source and receiver
- Parameters:
source (SourceDto) – A source associated with the simulation
receiver (ReceiverDto) – A receiver associated with the simulation and source
- Return MonoIR:
A MonoIR object corresponding to the input specifications
- get_moving_ir(source: SourceDto | str, receiver: ReceiverDto | str) MovingIR¶
Receive a moving impulse response object from the simulation for a specific source and receiver.
- get_source_result_metadata(source: SourceDto | str) dict¶
Get the source result metadata for a source
- get_spatial_ir(source: SourceDto | str, receiver: ReceiverDto | str) SpatialIR¶
Receive a spatial impulse response object from the simulation for a specific source and receiver. If receiver type was mono, will raise an exception
- interpolate_directivity_balloon_third_octave(source: str | Source | None = None, n_azi: int = 72, n_colat: int = 37, pad_to_full_frequency_range: bool = True) tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]¶
Interpolates the directivity balloon onto a top pole response in third octave bands
- Parameters:
- Return tuple[np.ndarray, np.ndarray]:
returns the frequency vector and the interpolated frequency responses
- interpolate_fr(azimuth_deg: float, elevation_deg: float, source: str | Source | None = None, scaling: FrScaling = FrScaling.on_axis_normalized, include_hplp_filters: bool = False) tuple[numpy.ndarray, numpy.ndarray]¶
Interpolate an frequency response at the given azimuth and elevation
- Parameters:
azimuth_deg (float) – Azimuth angle in degrees
elevation_deg (float) – Elevation angle in degrees
scaling (ff_utils.FrScaling) – Scaling of the frequency response, defaults to ff_utils.FrScaling.on_axis_normalized
include_hplp_filters (bool) – Whether to include the time domain hp lp filters, if this is false, the frequency axis will be limited to the valid range of the simulation and the filters that are normally applied in the time domain will be compensated for, defaults to False
- Return tuple[np.ndarray, np.ndarray]:
The frequency vector and the interpolated frequency response.
- interpolate_polar_azimuth(source: str | Source | None = None, n_azi: int = 360, elevation_deg: float = 0, scaling: FrScaling = FrScaling.on_axis_normalized, include_hp_lp_filters: bool = False) tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]¶
Interpolate the azimuth response at the given elevation
- Parameters:
n_azi (int) – number of azimuth points, defaults to 360
elevation_deg (float) – the elevation in degrees, defaults to 0
third_octave_average (bool) – Choose whether to output the third octave averages, defaults to False
scaling (ff_utils.FrScaling) – scaling of the frequency responses, defaults to ff_utils.FrScaling.on_axis_normalized
include_hp_lp_filters (bool) – Whether to include the time domain hp lp filters, if this is false, the frequency axis will be limited to the valid range of the simulation and the filters that are normally applied in the time domain will be compensated for, defaults to False
- Return tuple[np.ndarray, np.ndarray, np.ndarray]:
the azimuth angles, the frequency vector and the interpolated frequency responses
- interpolate_polar_elevation(source: str | Source | None = None, n_ele: int = 360, azimuth_deg: float = 0, scaling: FrScaling = FrScaling.on_axis_normalized, include_hp_lp_filters: bool = False)¶
Interpolate the elevation response at the given azimuth angle
- Parameters:
n_ele (int) – number of elevation points, defaults to 360
azimuth_deg (float) – the azimuth in degrees, defaults to 0
third_octave_average (bool) – Choose whether to output the third octave averages, defaults to False
scaling (ff_utils.FrScaling) – scaling of the frequency response, defaults to ff_utils.FrScaling.on_axis_normalized
include_hp_lp_filters (bool) – Whether to include the time domain hp lp filters, if this is false, the frequency axis will be limited to the valid range of the simulation and the filters that are normally applied in the time domain will be compensated for, defaults to False
- Return tuple[np.ndarray, np.ndarray, np.ndarray]:
the elevation angles, the frequency vector and the interpolated frequency responses
- on_axis_fr(source: str | Source | None = None, scaling: FrScaling = FrScaling.velocity, include_hplp_filters=False) tuple[numpy.ndarray, numpy.ndarray]¶
Get the on axis frequency response
- Parameters:
scaling (ff_utils.FrScaling) – Choose the scaling of the frequency response, defaults to ff_utils.FrScaling.velocity
include_hplp_filters (bool) – Whether to include the time domain hp lp filters, if this is false, the frequency axis will be limited to the valid range of the simulation and the filters that are normally applied in the time domain will be compensated for, defaults to False
- Return tuple[np.ndarray, np.ndarray]:
The frequency vector and the on axis frequency response
- plot()¶
Open an interactive widget to visualize simulation results.
- plot_acoustic_parameters()¶
Open an interactive widget to visualize acoustic parameters across multiple source-receiver pairs.
- plot_directivity_balloon(selected_frequency: int, source: str | Source | None = None, scaling: FrScaling = FrScaling.on_axis_normalized, plot_amplitude_scaling_factor: float = 10)¶
Plot the directivity response on a sphere at the given frequency
- plot_interpolated_fr(azimuth_deg: float, elevation_deg: float, source: str | Source | None = None, scaling: FrScaling = FrScaling.velocity)¶
Plot the interpolated frequency response at the given azimuth and elevation
- plot_mono_dipole_sphere(frequency: float, source: str | Source | None = None, plot_amplitude_scaling_factor=10)¶
Plot the mono dipole sphere response at the given frequency
- Parameters:
frequency (_type_) – selected frequency to plot
plot_amplitude_scaling_factor (int) – scaling factor for the deformation of the plot, defaults to 10
- plot_on_axis_fr(source: str | Source | None = None, scaling: FrScaling = FrScaling.velocity)¶
Plot the on-axis frequency response
- Parameters:
scaling (FrScaling) – Scaling, defaults to FrScaling.velocity
- plot_polar_azimuth(frequency: float, source: str | Source | None = None, n_azi: int = 360, elevation_deg: float = 0, scaling: FrScaling = FrScaling.on_axis_normalized)¶
Plot the interpolated response as a function of the azimuth angle at a given frequency
- plot_polar_elevation(frequency: float, source: str | Source | None = None, n_ele: int = 360, azimuth_deg: float = 0, scaling: FrScaling = FrScaling.on_axis_normalized)¶
Plot the interpolated response as a function of the elevation angle at a given frequency
- source_center_fr(source: str | Source | None = None, scaling: FrScaling = FrScaling.velocity, include_hplp_filters=False) tuple[numpy.ndarray, numpy.ndarray]¶
Get the source center frequency response
- Parameters:
scaling (ff_utils.FrScaling) – Choose the scaling of the frequency response, defaults to ff_utils.FrScaling.velocity
include_hplp_filters (bool) – Whether to include the time domain hp lp filters, if this is false, the frequency axis will be limited to the valid range of the simulation and the filters that are normally applied in the time domain will be compensated for, defaults to False
- Return tuple[np.ndarray, np.ndarray]:
The frequency vector and the source center frequency response.
- sphere_points_fr(source: str | Source | None = None, scaling: FrScaling = FrScaling.on_axis_normalized, include_hp_lp_filters: bool = False) tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray]¶
The frequency responses at the sphere points
- Parameters:
scaling (ff_utils.FrScaling) – scaling of the frequency responses, defaults to ff_utils.FrScaling.on_axis_normalized
include_hp_lp_filters (bool) – Whether to include the time domain hp lp filters, if this is false, the frequency axis will be limited to the valid range of the simulation and the filters that are normally applied in the time domain will be compensated for, defaults to False
- Return tuple[np.ndarray, np.ndarray, np.ndarray]:
unit vectors of the points, the frequency vector and the frequency responses.