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 anticlockwise 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. 
Aformat 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 ACNN3D to a variety of formats.
format 
An array of kewords designating component ordering and normalisation. E.g., target output format ACNSN3D 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  FurseMalham (FuMa) 
normalisation
\n3d  Orthonormal basis for 3D decomposition (N3D) 
\sn3d  Seminormalised basis for 3D decomposition (SN3D) 
\n2d  Orthonormal basis for 2D decomposition (N2D) 
\sn2d  Seminormalised basis for 2D decomposition (SN2D) 
\maxN  Maximum normalisation (maxN) 
\MaxN  Gerzon / FurseMalham (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  FurseMalham (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  Hypercardioid 
\energy  energy optimised  maximum energy rE  Supercardioid 
\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 3D 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  rolloff to ~3dB, in radians 
\hvc  rolloff 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: