Generates transform matrices required by the Ambisonic Toolkit's first order (matrix) transformer, FoaXform.
Rotate around the zaxis.
angle 
Rotation angle, in radians. 
A rotation of pi/2 will rotate a source at [0, 0]
to [pi/2, 0]
.
Rotate around the xaxis.
angle 
Rotation angle, in radians. 
A rotation of pi/2 will rotate a source at [pi/2, 0]
to [0, pi/2]
.
Rotate around the yaxis.
angle 
Rotation angle, in radians. 
A rotation of pi/2 will rotate a source at [0, 0]
to [0, pi/2]
.
Rotate around the z, x and y axes.
rotAngle 
Rotation angle around zaxis, in radians. 
tilAngle 
Rotation angle around xaxis, in radians. 
tumAngle 
Rotation angle around yaxis, in radians. 
Rotate is followed by Tilt and then Tumble.
Mirror across the origin.
A source at [pi/4, pi/6]
will be mirrored to [3/4*pi, pi/6]
.
Mirror in the xaxis (across the yz plane).
A source at [pi/4, pi/6]
will be mirrored to [3/4*pi, pi/6]
.
Mirror in the yaxis (across the xz plane).
A source at [pi/4, pi/6]
will be mirrored to [pi/4, pi/6]
.
Mirror in the yaxis (across the xz plane).
A source at [pi/4, pi/6]
will be mirrored to [pi/4, pi/6]
.
Mirror across an arbitrary plane.
theta 
Azimuth for the normal to the plane, in radians. 
phi 
Elevation for the normal to the plane, in radians. 
Adjust the soundfield directivity (across the origin).
angle 
The distortion angle, in radians. 0 to pi/2 
Angle = 0 retains the current directivity of the soundfield. Increasing angle towards pi/2 decreases the directivity, reducing the gains on the directional compenents to zero, and is equivalent to a spatial lowpass filter. The resulting image becomes omnidirectional or directionless.
Imaging is illustrated here.
Adjust the soundfield directivity along the xaxis.
angle 
The distortion angle, in radians. 0 to pi/2 
Angle = 0 retains the current directivity of the soundfield. Increasing angle towards pi/2 decreases the directivity along the xaxis, reducing the gain on this axis to zero, and is equivalent to a spatial lowpass filter. The resulting image becomes directionless on the xaxis.
Imaging is illustrated here.
Adjust the soundfield directivity along the yaxis.
angle 
The distortion angle, in radians. 0 to pi/2 
Angle = 0 retains the current directivity of the soundfield. Increasing angle towards pi/2 decreases the directivity along the yaxis, reducing the gain on this axis to zero, and is equivalent to a spatial lowpass filter. The resulting image becomes directionless on the yaxis.
Imaging is illustrated here.
Adjust the soundfield directivity along the zaxis.
angle 
The distortion angle, in radians. 0 to pi/2 
Angle = 0 retains the current directivity of the soundfield. Increasing angle towards pi/2 decreases the directivity along the zaxis, reducing the gain on this axis to zero, and is equivalent to a spatial lowpass filter. The resulting image becomes directionless on the zaxis.
Adjust the soundfield directivity across an arbitrary plane.
angle 
The distortion angle, in radians. 0 to pi/2 
theta 
Azimuth for the normal to the plane, in radians. 
phi 
Elevation for the normal to the plane, in radians. 
Angle = 0 retains the current directivity of the soundfield. Increasing angle towards pi/2 decreases the directivity along the normal defined by theta and phi, reducing the gain on this normal to zero, and is equivalent to a spatial lowpass filter. The resulting image becomes directionless on the normal.
Apply dominance along the xaxis.
gain 
Dominance gain, in dB. 
Positive values of gain increase the gain at [0, 0]
to +gain dB, while decreasing the gain at [pi, 0]
to gain. This simultaneously results in a distortion of the image towards [0, 0]
. Negative values of gain invert this distortion, distorting towards [pi, 0]
. The default, 0, results in no change.
Imaging is illustrated here.
Apply dominance along the yaxis.
gain 
Dominance gain, in dB. 
Positive values of gain increase the gain at [pi/2, 0]
to +gain dB, while decreasing the gain at [pi/2, 0]
to gain. This simultaneously results in a distortion of the image towards [pi/2, 0]
. Negative values of gain invert this distortion, distorting towards [pi/2, 0]
. The default, 0, results in no change.
Apply dominance along the zaxis.
gain 
Dominance gain, in dB. 
Positive values of gain increase the gain at [0, pi/2]
to +gain dB, while decreasing the gain at [0, pi/2]
to gain. This simultaneously results in a distortion of the image towards [0, pi/2]
. Negative values of gain invert this distortion, distorting towards [0, pi/2]
. The default, 0, results in no change.
Apply dominance along an arbitrary axis.
gain 
Dominance gain, in dB. 
theta 
Azimuth, in radians. 
phi 
Elevation, in radians. 
Applies dominance along the axis defined by theta and phi. See *newDominateX.
Apply zoom along the xaxis.
angle 
The distortion angle, in radians. pi/2 to pi/2 
Zoom is a normailised dominance variant, specified in terms of a distortion angle. Positive values of angle increase gain at [0, 0]
, while reducing at [pi, 0]
. Negative values do the inverse. The default, 0, results in no change.
Imaging is illustrated here.
Apply zoom along the yaxis.
angle 
The distortion angle, in radians. pi/2 to pi/2 
Zoom 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.
Apply zoom along the zaxis.
angle 
The distortion angle, in radians. pi/2 to pi/2 
Zoom is a normailised dominance variant, specified in terms of a distortion angle. Positive values of angle increase gain at [0, pi/2]
, while reducing at [0, pi/2]
. Negative values do the inverse. The default, 0, results in no change.
Apply zoom along an arbitrary axis.
angle 
The distortion angle, in radians. pi/2 to pi/2 
theta 
Azimuth, in radians. 
phi 
Elevation, in radians. 
Applies zoom along the axis defined by theta and phi. See *newZoomX.
Apply focus along the xaxis.
angle 
The distortion angle, in radians. pi/2 to pi/2 
Focus is a normalised dominance variant, specified in terms of a distortion angle. Positive values of angle maintain gain at [0, 0]
, while reducing at [pi, 0]
. 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 focus along the yaxis.
angle 
The distortion angle, in radians. pi/2 to pi/2 
Focus is a normalised dominance variant, specified in terms of a distortion angle. Positive values of angle maintain gain at [pi/2, 0]
, while reducing at [pi/2, 0]
. 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.
Apply focus along the xaxis.
angle 
The distortion angle, in radians. pi/2 to pi/2 
Focus is a normalised dominance variant, specified in terms of a distortion angle. Positive values of angle maintain gain at [0, pi/2]
, while reducing at [0, pi/2]
. 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.
Apply focus along an arbitrary axis.
angle 
The distortion angle, in radians. pi/2 to pi/2 
theta 
Azimuth, in radians. 
phi 
Elevation, in radians. 
Applies focus along the axis defined by theta and phi. See *newFocusX.
Apply push along the xaxis.
angle 
The distortion angle, in radians. pi/2 to pi/2 
Push is a dominance related transform, specified in terms of a distortion angle. Positive values of angle push the image towards [0, 0]
. Negative values push towards [pi, 0]
. The default, 0, results in no change.
Imaging is illustrated here.
Apply push along the yaxis.
angle 
The distortion angle, in radians. pi/2 to pi/2 
Push is a dominance related transform, specified in terms of a distortion angle. Positive values of angle push the image towards [pi/2, 0]
. Negative values push towards [pi/2, 0]
. The default, 0, results in no change.
Apply push along the xaxis.
angle 
The distortion angle, in radians. pi/2 to pi/2 
Push is a dominance related transform, specified in terms of a distortion angle. Positive values of angle push the image towards [0, pi/2]
. Negative values push towards [0, pi/2]
. The default, 0, results in no change.
Apply push along an arbitrary axis.
angle 
The distortion angle, in radians. pi/2 to pi/2 
theta 
Azimuth, in radians. 
phi 
Elevation, in radians. 
Applies push along the axis defined by theta and phi. See *PushX.
Apply press along the xaxis.
angle 
The distortion angle, in radians. pi/2 to pi/2 
Press is a dominance related transform, specified in terms of a distortion angle. Positive values of angle press the image towards [0, 0]
. Negative values press towards [pi, 0]
. The default, 0, results in no change.
Imaging is illustrated here.
Apply press along the xaxis.
angle 
The distortion angle, in radians. pi/2 to pi/2 
Press is a dominance related transform, specified in terms of a distortion angle. Positive values of angle press the image towards [pi/2, 0]
. Negative values press towards [pi/2, 0]
. The default, 0, results in no change.
Apply press along the zaxis.
angle 
The distortion angle, in radians. pi/2 to pi/2 
Press is a dominance related transform, specified in terms of a distortion angle. Positive values of angle press the image towards [0, pi/2]
. Negative values press towards [0, pi/2]
. The default, 0, results in no change.
Imaging is illustrated here.
Apply press along an arbitrary axis.
angle 
The distortion angle, in radians. pi/2 to pi/2 
theta 
Azimuth, in radians. 
phi 
Elevation, in radians. 
Applies press along the axis defined by theta and phi. See *PressX.
Apply soundfield asymmetry
angle 
The distortion angle, in radians. pi/2 to pi/2 
Positive values of angle rotate [0, pi/2]
towards [0, 0]
, and at pi/2 collapse the soundfield to a planewave. Negative values rotate [0, pi/2]
toowards [0, 0]
. The default, 0, results in no change.
Imaging is illustrated here.
Soundfield balance. A synonym for ZoomY
angle 
The distortion angle, in radians. pi/2 to pi/2 
See ZoomY.
Imaging is illustrated here.
Create an FoaEncoderMatrix by loading a matrix from a file.
filePathOrName 
Can be a path relative to your Atk.getMatrixExtensionPath('xformers').fullPath Otherwise a full path to your matrix file. 
See the Guide to ATK Matrix Files for more information.
Create an instance from a raw 2D Matrix.
aMatrix 
A Matrix in the form of Matrix.with([[row1],[row2],...[rowN]]) 
set 

type 
NOTE: set and type will be required if the AtkMatrix will subsequently be written to a file. 
Describes both the signal set and the tool set, encompassing the Ambisonic order, as well as channel ordering and normalisation.
Answers 'FOA'
, aka traditional Bformat:
Ambisonic Order  Channel Ordering  Channel Normalisation 
1st  Gerzon (aka FurseMalham)  MaxN 
'xformer'
Answers 'matrix'
, i.e. the type of operation used to compute the resulting signals.
Answers the kind of encoder
// encoder ~xformer = FoaXformerMatrix.newZoomX // inspect ~encoder.kind
Answers the number of transformer dimensions: 3D.
Answers the number of channels.
All Transformer matricies are square: 4.
A convenience method providing polymorphism with FoaEncoderMatrix: dirChannels and FoaDecoderMatrix: dirChannels.
[ inf, inf, inf , inf ]
Answers the transform matrix
A convenience method providing polymorphism with FoaEncoderMatrix: numOutputs and FoaDecoderMatrix: numOutputs.
A convenience method providing polymorphism with FoaEncoderMatrix: dirOutputs and FoaDecoderMatrix: dirOutputs.
A convenience method providing polymorphism with FoaEncoderMatrix: numInputs and FoaDecoderMatrix: numInputs.
A convenience method providing polymorphism with FoaEncoderMatrix: dirInputs and FoaDecoderMatrix: dirInputs.
A convenience method to post the properties of the matrix, including metadata if the matrix was loaded from a .yml
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.
Answers the path of the file used to create the instance, or nil
if not created by loading a matrix from a file.
Answers the name of the file used to create the instance, or nil
if not created by loading a matrix from a file.
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.
Please see FoaXform: Examples.