Generate matrix transformers required by the Ambisonic Toolkit's Higher Order Ambisonic (HOA) transformer, HoaXformMatrix.
Beamform into a Higher Order Ambisonic signal (HOA).
theta 
Azimuth, in radians. 
phi 
Elevation, in radians. 
beamShape 
Keyword argument for beam shape. See discussion here. 
order 
Ambisonic order. 
Nullform into a Higher Order Ambisonic signal (HOA).
theta 
Azimuth, in radians. 
phi 
Elevation, in radians. 
beamShape 
Keyword argument for beam shape. See discussion here. 
order 
Ambisonic order. 
Mirror a Higher Order Ambisonic signal (HOA).
mirror 
Keyword argument for reflection. See discussion below. 
order 
Ambisonic order. 
A variety of reflection transforms are offered:
keyword  mirror 
\reflect  Mirror across the origin. Equivalent to: \flip * \flop * \flap .^{1} 
\flip  Mirror in the yaxis.^{2} 
\flop  Mirror in the xaxis.^{3} 
\flap  Mirror in the zaxis.^{4} 
\CondonShortleyPhase  CondonShortley Phase. Equivalent to: \flip * \flop . 
\origin  Synonym for \reflect . 
\x  Synonym for \flop . 
\y  Synonym for \flip . 
\z  Synonym for \flap . 
Rotate a Higher Order Ambisonic signal (HOA) around an axis.
axis 
Keyword argument for axis of rotation. See discussion below. 
angle 
Rotation angle, in radians. 
order 
Ambisonic order. 
Rotation about one of the three cartesian axes are offered via these keywords:
keyword  axis of rotation 
\x  xaxis 
\y  yaxis 
\z  zaxis 
\rotate  Synonym for \z . 
\tilt  Synonym for \x . 
\tumble  Synonym for \y . 
\yaw  Synonym for \z . 
\pitch  Synonym for \y . 
\roll  Synonym for \x . 
Compound rotation around the z, x and y axes, applied in sequential order: rotate, tilt, tumble.
rotate 
Rotation angle around zaxis, in radians. 
tilt 
Rotation angle around xaxis, in radians. 
tumble 
Rotation angle around yaxis, in radians. 
order 
Ambisonic order. 
Compound rotation around the z, y' and x" axes: yaw, pitch, roll.
yaw 
Rotation angle around zaxis, in radians. 
pitch 
Rotation angle around y'axis, in radians. 
roll 
Rotation angle around x"axis, in radians. 
order 
Ambisonic order. 
Compound rotation around the cartesian axes, applied in sequential order.
r1 
Rotation angle around axis1, in radians. 
r2 
Rotation angle around axis2, in radians. 
r3 
Rotation angle around axis2, in radians. 
axes 
Individual axes are specified via the axial keywords for *newRotateAxis. Specify order of rotations via concatenation. E.g., rotate, tilt, tumble: 
order 
Ambisonic order. 
Swap two axes of a Higher Order Ambisonic signal (HOA).
axes 
Individual axes are specified via the axial keywords for *newRotateAxis. Specify swap via concatenation. E.g., swap yaxis with zazis: 
order 
Ambisonic order. 
Apply dominance along an arbitrary axis.
gain 
Dominance gain, in dB. 
theta 
Azimuth, in radians. 
phi 
Elevation, in radians. 
order 
Ambisonic order. 
Applies dominance along the axis defined by theta and phi.
Positive values of gain increase the gain at [theta, phi]
to +gain dB, while decreasing the gain at [theta.neg, phi.neg]
to gain. This simultaneously results in a distortion of the image towards [theta, phi]
. Negative values of gain invert this distortion, distorting towards [theta.neg, phi.neg]
. The default, 0, results in no change.
Imaging is illustrated here.
Apply zoom along an arbitrary axis.
angle 
Distortion angle, in radians. pi/2 to pi/2 
theta 
Azimuth, in radians. 
phi 
Elevation, in radians. 
order 
Ambisonic order. 
Applies zoom along the axis defined by theta and phi.
Zoom is a normailised dominance variant, specified in terms of a distortion angle. Positive values of angle increase gain at [theta, phi]
, while reducing at [theta.neg, phi.neg]
. Negative values do the inverse. The default, 0, results in no change.
Imaging is illustrated here.
Apply focus along an arbitrary axis.
angle 
Distortion angle, in radians. pi/2 to pi/2 
theta 
Azimuth, in radians. 
phi 
Elevation, in radians. 
order 
Ambisonic order. 
Applies focus along the axis defined by theta and phi.
Focus is a normalised dominance variant, specified in terms of a distortion angle. Positive values of angle maintain gain at [theta, phi]
, while reducing at [theta.neg, phi.neg]
. Negative values do the inverse. The default, 0, results in no change.
In contrast with zoom, gain is maintained at 0dB in the direction of distortion.
Imaging is illustrated here.
Apply soundfield asymmetry
angle 
Distortion angle, in radians. pi/2 to pi/2 
order 
Ambisonic order. 
Positive values of angle rotate [pi/2, 0]
towards [0, 0]
, and at pi/2 collapse the soundfield to a travelling wave. Negative values rotate [pi/2, 0]
towards [0, 0]
. The default, 0, results in no change.
Imaging is illustrated here.
Apply soundfield balance.
angle 
Distortion angle, in radians. pi/2 to pi/2 
order 
Ambisonic order. 
A synonym for apply zoom along the yaxis.
Balance is a normailised dominance variant, specified in terms of a distortion angle. Positive values of angle increase gain at [pi/2, 0]
, while reducing at [pi/2, 0]
. Negative values do the inverse. The default, 0, results in no change.
Imaging is illustrated here.
Transform a Higher Order Ambisonic signal (HOA) via a directly designed spatial filter.
matrix 
A Matrix instance. 
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.
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 transformer amplitude and energies.
Analysis is returned in an IdentityDictionary, with the following keys:
keyword  analysis 
\amp  pressure (virtual loudspeaker sum) 
\rms  spherical harmonic energy 
\energy  virtual loudspeaker (angular) energy 
\meanE  transformer reduced energy 
\matchWeight  transformer matching weights (a Dictionary) 
The required weights for gain matching are returned in the \matchWeight
Dictionary:
keyword  analysis 
\amp  match weight for pressure (virtual loudspeaker sum) 
\rms  match weight for spherical harmonic energy 
\energy  match weight for virtual loudspeaker (angular) energy 
Offers a convenient way to review modifications to the soundfield.
Rotation:
Beamforming:
Return a directional analysis of modifications to the soundfield.
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 an IdentityDictionary, with the following keys:
keyword  analysis 
\amp  pressure (virtual loudspeaker sum) 
\rms  spherical harmonic energy 
\energy  virtual 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 transformer performance.
Rotation:
Beamforming:
Nullforming:
TBD