Receivers

All receivers define a point receiver at a given location, or locations in the case of a moving receiver. There are two basic receiver types: mono and spatial receivers. The following how-tos demonstrate how to create the primitive receiver types and create a receiver list for use in a simulation definition.

Simulations expect a list of receivers, even if only one receiver is calculated. To format a singular receiver in a list, please jump to receiver list definition.

info

You can use up to 30,000 receivers within a single simulation. A mono receiver counts as a single receiver within the simulation, while a spatial receiver with ambisonics order 32 will create $(32+1)^2$ or 1,089 receivers within a simulation.

Basic examples

Mono receiver definition

The mono receiver samples the soundfield in a point. This receiver has an omnidirectional pickup pattern. The result is a single channel impulse response per receiver. The following snippet creates a single mono receiver, and creates the receiver list which is required for a SimulationDefinition object's creation.

mono_receiver = treble.Receiver.make_mono(
            position=treble.Point3d(x=1.5, y=4, z=1.5),
            label="mono_receiver_1",
            )

Spatial receiver definition

A spatial receiver samples the sound field in the spherical harmonics domain. By default, a spatial receiver is set to 2nd-order ambisonics with an orientation towards the positive $x$ axis. You can change which order of ambisonics is used via the ambisonics_order property while creating the receiver. Treble supports ambisonics orders up to 32, with $(n+1)^2$ channels per order $n$. The data is formatted in ACN channel order with SN3D normalization.

spatial_receiver =  treble.Receiver.make_spatial(
            position=treble.Point3d(x=1.5, y=4, z=1.5),
            label="Spatial_receiver",
            ambisonics_order=16 # optional, defaults to 2
            )

Receiver list definition

The simulation definition expects a list of Treble receivers, even if there is only one receiver included in the simulation. In the case where your simulation has only one receiver, you may create the receiver list as follows:

receivers = [mono_receiver]

You can also programmatically create a reciver list with the following code:

receiver_list = [
    treble.Receiver.make_mono(
        position=treble.Point3d(x=1.5, y=rec, z=1.5),
        label=f"mono_receiver_i{rec}",
    )
    for rec in range(5)
]