treble_tsdk.collections.ir_info

Functions

compute_ir_unique_id(source_id, receiver_id)

Compute the canonical unique id for an IR.

Classes

DeviceRenderParams	Parameters describing how to render an IR through a device.
IRInfo	One row of an IRCollection: a source/receiver pair of a simulation plus optional device-render and processing info.
IRProcessingInfo	IRProcessingInfo(ir_id: 'str', task_id: 'str')
ProcessingRecipe	ProcessingRecipe(filters: 'list[FilterDefinition]' = None, filter_structs: 'list[dict]' = None)

class treble_tsdk.collections.ir_info.DeviceRenderParams

Parameters describing how to render an IR through a device.

Parameters:

• device (DeviceObj) – The device to render the IR through.

• device_orientation (Rotation) – The orientation of the device.

__init__(device: DeviceObj, device_orientation: Rotation) → None

device: DeviceObj

device_orientation: Rotation

class treble_tsdk.collections.ir_info.IRInfo

One row of an IRCollection: a source/receiver pair of a simulation plus optional device-render and processing info.

A device source (Source.make_device) is one row with ir_type == IRType.device_source whose source is the parent device source; its per-layer results are addressed through get_device_source_ir(). IRCollection.fan_out_device_source expands such rows into one row per source layer, on which parent_source and source_layer are set.

The filters the device prescribes for a source layer (DeviceObj.source_filters of source_device) are part of the layer’s impulse response and are applied whenever it is fetched, before the processing filters and regardless of apply_filters; pass apply_device_filters=False to skip them. Remote IR processing reads them from the device itself and applies them first as well, so remotely processed IRs are returned as they are.

Likewise the filters a device prescribes for its microphones (DeviceObj.mic_filters) are applied to the corresponding channels of every device IR fetched on the fly, after the source filters and before the processing filters: those of device when rendering through it, those of receiver_device for a device receiver. Remote IR processing applies them in the same place. apply_device_filters=False skips them too.

__init__(source: Source, receiver: Receiver, simulation: Simulation, device: DeviceObj | None = None, device_orientation: Rotation | None = None, processing: ProcessingRecipe | None = None, ir_processing_info: IRProcessingInfo | None = None, dataframe_row: dict | None = None, source_device: DeviceObj | None = None, receiver_device: DeviceObj | None = None) → None

get_device_ir(data_loader: IRDataLoader | None = None, apply_filters: bool = True, include_spatial_ir: bool = False, source_layer: Source | str | Sequence[Source | str] | None = None, apply_device_filters: bool = True) → DeviceIR

Get DeviceIR object from IRInfo. If apply_filters is True, the filters are applied to the resulting IR. :param data_loader: Optional but recommended. IRDataLoader object to use for loading the IR data to/from cache. If None, a new lazy IRDataLoader will be created which will load data to a temporary directory. :param apply_filters: If True, the filters are applied to the resulting IR. Defaults to True. :param include_spatial_ir: If set and IR has been processed remotely the spatial IR part can be skipped. If IR needs to be rendered on-the-fly the SpatialIR is always included. Ignored for source-receiver-device (SRD) IRs, which have no spatial IR component. :param source_layer: For a device-source row, the source layer(s) to get the IR of: one layer by layer name, sub-source label/id or sub-source, or a list of those to sum. When omitted the IRs of all layers are summed into the IR of the whole device. :param apply_device_filters: Apply the filters the device prescribes for each source layer (DeviceObj.source_filters) and, for a device receiver, for each of its microphones (DeviceObj.mic_filters). Set to False to get the unfiltered solver output. Defaults to True.

get_device_source_ir(data_loader: IRDataLoader | None = None, apply_device_filters: bool = True) → DeviceSourceIR

Get a DeviceSourceIR (per-layer IRs of a device source to this receiver) from IRInfo. The source may be the parent device source or one of its layers. :param data_loader: Optional but recommended. IRDataLoader object to use for loading the IR data to/from cache. If None, a new lazy IRDataLoader will be created which will load data to a temporary directory. :param apply_device_filters: Apply the filters the device prescribes for each source layer (DeviceObj.source_filters) and, for a device receiver, for each of its microphones (DeviceObj.mic_filters), as every other get_*_ir does. Set to False to get the unfiltered solver output of the layers. Defaults to True.

get_mono_ir(data_loader: IRDataLoader | None = None, apply_filters: bool = True, source_layer: Source | str | Sequence[Source | str] | None = None, apply_device_filters: bool = True) → MonoIR

Get MonoIR object from IRInfo. If apply_filters is True, the filters are applied to the resulting IR. :param data_loader: Optional but recommended. IRDataLoader object to use for loading the IR data to/from cache. If None, a new lazy IRDataLoader will be created which will load data to a temporary directory. :param apply_filters: If True, the filters are applied to the resulting IR. Defaults to True. :param source_layer: For a device-source row, the source layer(s) to get the IR of: one layer by layer name, sub-source label/id or sub-source, or a list of those to sum. When omitted the IRs of all layers are summed into the IR of the whole device. :param apply_device_filters: Apply the filters the device prescribes for each source layer (DeviceObj.source_filters). Set to False to get the unfiltered solver output. Defaults to True.

get_moving_ir(data_loader: IRDataLoader | None = None) → MovingIR

Get MovingIR object from IRInfo. :param data_loader: Optional but recommended. IRDataLoader object to use for loading the IR data to/from cache. If None, a new lazy IRDataLoader will be created which will load data to a temporary directory.

get_reference_mic_ir(device: DeviceObj, orientation: Rotation = Rotation(azimuth=0.0, elevation=0.0, roll=0.0), data_loader: IRDataLoader | None = None) → DeviceIR

Render this impulse response using a device’s reference microphones locally.

Parameters:

• device (DeviceObj) – Device whose reference microphones receive the rendered IR.

• orientation (Rotation) – Orientation to use for the device, defaults to no rotation.

• data_loader (IRDataLoader | None) – Optional loader used to fetch and cache the spatial IR.

Returns:

The rendered impulse response as a DeviceIR.

Raises:

ValueError – If this IR uses a source-receiver device receiver, or if the device has no renderable reference microphones (simulated with render_reference_microphones=True).

get_spatial_ir(data_loader: IRDataLoader | None = None, apply_filters: bool = True, source_layer: Source | str | Sequence[Source | str] | None = None, apply_device_filters: bool = True) → SpatialIR

Get SpatialIR object from IRInfo. If apply_filters is True, the filters are applied to the resulting IR. :param data_loader: Optional but recommended. IRDataLoader object to use for loading the IR data to/from cache. If None, a new lazy IRDataLoader will be created which will load data to a temporary directory. :param apply_filters: If True, the filters are applied to the resulting IR. Defaults to True. :param source_layer: For a device-source row, the source layer(s) to get the IR of: one layer by layer name, sub-source label/id or sub-source, or a list of those to sum. When omitted the IRs of all layers are summed into the IR of the whole device. :param apply_device_filters: Apply the filters the device prescribes for each source layer (DeviceObj.source_filters). Set to False to get the unfiltered solver output. Defaults to True.

dataframe_row: dict | None = None

device: DeviceObj | None = None

device_orientation: Rotation | None = None

property id: str

ir_processing_info: IRProcessingInfo | None = None

property ir_type: IRType

Get the IRType of the IR.

property parent_source: Source | None

The parent device source when source is one of its source layers, otherwise None.

processing: ProcessingRecipe | None = None

receiver: Receiver

receiver_device: DeviceObj | None = None

The device a device receiver belongs to (see receiver_device_id), resolved by the collection from the simulation. Without it no microphone filters are applied to its device IRs.

property receiver_device_id: str | None

Id of the device a device receiver belongs to (the device of the device source it was created with), otherwise None.

simulation: Simulation

source: Source

source_device: DeviceObj | None = None

The device source was created from (see source_device_id), resolved by the collection like device. Without it no device filters are applied.

property source_device_id: str | None

Id of the device source was created from (device sources and their layers), otherwise None. Not to be confused with device, which is the device an IR is rendered through.

property source_layer: str | None

Name of the source layer source represents when it is a layer of a device source, otherwise None.

class treble_tsdk.collections.ir_info.IRProcessingInfo

IRProcessingInfo(ir_id: ‘str’, task_id: ‘str’)

__init__(ir_id: str, task_id: str) → None

static dtype() → polars.Struct

classmethod from_struct(s: dict[str, str | None]) → IRProcessingInfo

static pl_empty() → polars.Expr

Return a pl.Expr that represents an empty IRProcessingInfo.

to_struct() → dict[str, str | None]

ir_id: str

task_id: str

class treble_tsdk.collections.ir_info.ProcessingRecipe

ProcessingRecipe(filters: ‘list[FilterDefinition]’ = None, filter_structs: ‘list[dict]’ = None)

__init__(filters: list[FilterDefinition] | None = None, filter_structs: list[dict] | None = None) → None

get_filters() → list[FilterDefinition] | None

Return the live filter definitions, reconstructing them from filter_structs if they haven’t been populated yet. Returns None when no filters are specified.

filters is only set when filters are prescribed in-memory; a recipe rebuilt from a dataframe only carries filter_structs. This back-fills filters from those structs so both stay in sync.

filter_structs: list[dict] = None

filters: list[FilterDefinition] = None

treble_tsdk.collections.ir_info.compute_ir_unique_id(source_id: str, receiver_id: str, device_id: str | None = None, device_orientation: Rotation | list[float] | None = None, filter_structs: list[dict] | None = None) → str

Compute the canonical unique id for an IR.

Single source of truth for hashing an IR’s identifying fields into a stable string id.

Parameters:

• source_id (str) – The id of the source.

• receiver_id (str) – The id of the receiver.

• device_id (str | None) – The id of the device, if any.

• device_orientation (Rotation | list[float] | None) – The device orientation. Lists are converted to Rotation so the id is stable regardless of the input shape.

• filter_structs (list[dict] | None) – The processing filter chain, if any.

Return str:

The hex MD5 digest used as the IR’s stable id.