Generate matrix decoders required by the Ambisonic Toolkit's Higher Order Ambisonic (HOA) decoder, HoaDecodeMatrix.
Matrix decoding is offered via four different methods:
The first two, projection and mode matching, are suitable for designing decoders for loudspeaker arrays and apply a simple HOA degree truncation where the number of desired outputs is less than the number required for an input Ambisonic order.
The third, beamforming, returns (projection) spatial windows of the input Ambisonic order, without applying degree truncation. This decoding method is suitable for spherical decomposition and beamforming for signal processing.
Format exchange decoding offers interfacing with other Ambisonic formats and systems.
Decode a Higher Order Ambisonic signal (HOA) via the projection method.
directions |
An array of directions. Specify in radians. Rank 1 arrays return pantophonic, while rank 2 arrays return periphonic. E.g.,
|
beamShape |
Keyword argument for beam shape. See discussion below. |
match |
Keyword argument for gain matching. See discussion below. |
order |
Ambisonic order. |
Also known as Simple Ambisonic Decoding, aka SAD.
Decode a Higher Order Ambisonic signal (HOA) via the mode matching method.
directions |
An array of directions. Specify in radians. Rank 1 arrays return pantophonic, while rank 2 arrays return periphonic. E.g.,
|
beamShape |
Keyword argument for beam shape. See discussion below. |
match |
Keyword argument for gain matching. See discussion below. |
order |
Ambisonic order. |
Also known as Pseudoinverse Decoding, aka Pinv.
Decode a Higher Order Ambisonic signal (HOA) via the mode matching method, given diametrically matched loudspeaker pairs. Gerzon's classic diametric decoder.1
directions |
An array of directions for half of the loudspeaker feeds for the desired decoder. Specify in radians. Rank 1 arrays return pantophonic, while rank 2 arrays return periphonic. E.g.,
|
beamShape |
Keyword argument for beam shape. See discussion below. |
match |
Keyword argument for gain matching. See discussion below. |
order |
Ambisonic order. |
Also known as Diametric Decoding.
directions specifies only half of the loudspeakers for the resulting array, the remaining loudspeakers are diametrically opposite (through the origin). -directions may be used to query resulting loudspeaker directions.
Decode a Higher Order Ambisonic signal (HOA) via the projection method to a Pantophonic (2D) regular polygon array.
numChans |
number of outputs |
orientation |
|
beamShape |
Keyword argument for beam shape. See discussion below. |
match |
Keyword argument for gain matching. See discussion below. |
order |
Ambisonic order. |
The outputs are in anti-clockwise order. The position of the first speaker is either centre or left of centre. -directions may be used to query resulting loudspeaker directions.
Used in conjunction with HoaDecodeMatrix the resulting decoder is equivalent to DecodeB2 (SuperCollider's inbuilt decoder), albeit with the addition of variable beam shape and gain matching. DecodeB2 is a controlled opposites decoder.
Beamform into a Higher Order Ambisonic signal (HOA), returning multiple beams evenly distributed in a SphericalDesign.
design |
SphericalDesign instance |
beamShape |
Keyword argument for beam shape. See discussion below. |
order |
Ambisonic order. |
A-format decoding, aka spherical decomposition, is offered by *newSphericalDesign.
Gain is matched to maximum beam amplitude.
Beamform into a Higher Order Ambisonic signal (HOA), returning a single beam.
theta |
Azimuth, in radians. |
phi |
Elevation, in radians. |
beamShape |
Keyword argument for beam shape. See discussion below. |
order |
Ambisonic order. |
Returns a single beam, and can be used to "listen in" to the soundfield at the specified azimuth and elevation. Gain is matched to the beam. See discussion below
Beamform into a Higher Order Ambisonic signal (HOA), returning multiple beams.
directions |
An array of directions. Specify in radians. Rank 1 arrays return pantophonic, while rank 2 arrays return periphonic. E.g.,
|
beamShape |
Keyword argument for beam shape. See discussion below. |
match |
Keyword argument for gain matching. See discussion below. |
order |
Ambisonic order. |
Returns a collection of beams, and can be used to "listen in" to the soundfield at the specified azimuths and elevations.
An Ambisonic format exchange decoder. Decodes from ACN-N3D to a variety of formats.
format |
An array of kewords designating component ordering and normalisation. E.g., target output format ACN-SN3D is expressed |
order |
Ambisonic order. |
A variety of component ordering and normalisation schemes are supported. These are:
ordering
\acn | Ambisonic Channel Number (ACN) |
\sid | Single Index Designation (SID) |
\fuma | Furse-Malham (FuMa) |
normalisation
\n3d | Orthonormal basis for 3D decomposition (N3D) |
\sn3d | Semi-normalised basis for 3D decomposition (SN3D) |
\n2d | Orthonormal basis for 2D decomposition (N2D) |
\sn2d | Semi-normalised basis for 2D decomposition (SN2D) |
\maxN | Maximum normalisation (maxN) |
\MaxN | Gerzon / Furse-Malham (MaxN) |
\fuma | Synonym for MaxN (FuMa) |
Additionally, a number of common formats are available as a single keyword:
\atk | Ambisonic Toolkit (ATK) |
\ambix | Ambisonics Exchangeable (AmbiX) |
\fuma | Furse-Malham (FuMa) |
Create an instance from a raw 2D Matrix.
matrix |
A Matrix in the form of |
directions |
An array of directions. Specify in radians. Rank 1 arrays return pantophonic, while rank 2 arrays return periphonic. E.g.,
|
order |
Ambisonic order. |
Create an instance by loading a matrix from a file.
filePathOrName |
Can be a path relative to your Otherwise a full path to your matrix file. |
searchExtensions |
Search extension paths. |
order |
Ambisonic order. |
See the Guide to ATK Matrix Files for more information.
Three standard beam shapes are offered:
keyword | beam shape | localisation vector | virtual microphone |
\basic | strict soundfield | maximum velocity rV | Hyper-cardioid |
\energy | energy optimised | maximum energy rE | Super-cardioid |
\controlled | controlled opposites | minimum diametric energy | Cardioid |
Decoder gains can be normalised, aka matched, via various criteria:
keyword | matching criteria | valid decoding methods |
\beam | maximum beam amplitude | beamforming only |
\amp | pressure (loudspeaker sum) | all methods |
\rms | spherical harmonic energy | projection & mode matching only |
\energy | loudspeaker energy | projection & mode matching only |
Normalising gain to the beam amplitude is appropriate for a virtual microphone or spherical decomposition context. In this case, maximum amplitude of each returned beam is normalised to 0dB.
The other three criteria, pressure, total spherical harmonic energy, and total loudspeaker energy, are preferred for building decoders for loudspeaker audition.
A convenience method to post the properties of the matrix, including metadata if the matrix was loaded from a .yml
file.
Ambisonic order.
Describes both the signal set and the tool set, encompassing the Ambisonic order, as well as channel ordering and normalisation.
Ambisonic Toolkit designation indicating Ambisonic order and encoding format. E.g., \FOA
, \HOA3
.
For instance, \HOA3
:
Ambisonic Order | Component Ordering | Component Normalisation |
3rd | Ambisonic Channel Number (ACN) | Full 3-D normalisation (N3D) |
Ambisonic Toolkit soundfield operation designation. E.g., \encode
, \xform
, \decode
.
Answers 'matrix'
, i.e. the type of operation used to compute the resulting signals.
Answers the kind.
Answers the number of encoder dimensions: 2D or 3D.
Answers the number of input or output channels, depending on -type.
Answers the directions of input or output channels, depending on -type.
Number of inputs.
A convenience method providing polymorphism with -directions, depending on -type.
Number of outputs.
A convenience method providing polymorphism with -directions, depending on -type.
Returns the raw coefficient Matrix.
Bilateral thresholding in place.
thresh |
When the |
Returns the matrix as a new Array of rows.
Answers the name of the file used to create the instance, or nil
if not created by loading a matrix from a file.
Answers the path of the file used to create the instance, or nil
if not created by loading a matrix from a file.
If the instance was created by loading a .yml
file, this method returns the IdentityDictionary containing the parsed metadata. This can be useful if anything was stored in the metadata that can be subsequently used once reloaded, such as encoding directions, rotations, etc.
Write the matrix to a file
fileNameOrPath |
A String of the file name. The file extension determines the format:
You may provide a full path if you would like to save the file somewhere other than the default location in the Atk |
note |
A String that is a short description or bit of info about the matrix to store for future reference. |
attributeDictionary |
A Dictionary containing any information that's useful to store in key:value pairs. Keys that match getters in the AtkMatrix will take precedence over the defaults. See the Discussion for more details. |
overwrite |
A boolean specifying whether you'd like to force overwriting an existing file of the same name and extension. |
The Guide to ATK Matrix Files offers examples and more discussion regarding writing and reading matrices and metadata, including how to generate matrices for use in Reaper.
Return an average analysis of decoder amplitude and energies.
Analysis is returned in an IdentityDictionary, with the following keys:
keyword | analysis |
\amp | pressure (loudspeaker sum) |
\rms | spherical harmonic energy |
\energy | loudspeaker (angular) energy |
\meanE | decoder reduced energy |
\matchWeight | decoder matching weights (a Dictionary) |
The required weights for gain matching are returned in the \matchWeight
Dictionary:
keyword | analysis |
\amp | match weight for pressure (loudspeaker sum) |
\rms | match weight for spherical harmonic energy |
\energy | match weight for loudspeaker energy |
Offers a convenient way to check whether designed decoders meet the theoretical performance predicted by HoaOrder.
A regular array, evenly distributed loudspeakers:
Unevenly distributed loudspeakers:
Return a directional analysis of decoder performance.
directions |
A single azimuth value, or an array of test directions. Specify in radians. Rank 1 arrays return pantophonic, while rank 2 arrays return periphonic. E.g.,
|
Analysis is returned in a an IdentityDictionary, with the following keys:
keyword | analysis |
\amp | pressure (loudspeaker sum) |
\rms | spherical harmonic energy |
\energy | loudspeaker energy |
\spreadE | energy spread (a Dictionary) |
\rV | velocity localisation vector, rV (a Dictionary) |
\rE | energy localisation vector, rE (a Dictionary) |
Two measures of energy spread are offered in the \spreadE
Dictionary:
keyword | analysis |
\cos | roll-off to ~-3dB, in radians |
\hvc | roll-off to ~-6dB, in radians |
Information regarding rV, the velocity localisation vector, is returned in the \rV
Dictionary:
keyword | analysis |
\magnitudes | vector magnitudes |
\directions | vector directions, in radians |
\warp | angle distortion from test directions, in radians |
\rEwarp | angle distortion from rE, in radians |
\xyz | rV, in cartesian coordinates |
Similarly, information regarding rE, the energy localisation vector, is returned in the \rE
Dictionary:
keyword | analysis |
\magnitudes | vector magnitudes |
\directions | vector directions, in radians |
\warp | angle distortion from test directions, in radians |
\rVwarp | angle distortion from rV, in radians |
\xyz | rE, in cartesian coordinates |
Offers detailed analysis of decoder performance.
A regular array, evenly distributed loudspeakers:
Unevenly distributed loudspeakers:
A few functions useful for visualizing decoder performance.
A function to plot the velocity and energy localisation vectors in the equatorial plane:
A function to plot velocity and energy localisation vector error in the equatorial plane:
A function to plot energy spread in the equatorial plane:
A function to plot amplitude and energy in the equatorial plane: