Generates encoding matrices required by the Ambisonic Toolkit's first order encoder, FoaEncode.
Omnidirectional encoder (monophonic).
An omnidirectional soundfield can be regarded in two ways: a soundfield with an infinite number of planewaves arriving in all directions, or a soundfield with no directions. In a well aligned, dampend studio environment, this usually sounds "in the head", while in concert hall listening usually appears as omnipresent.
To control the soundfield, FoaPush and FoaFocus can be applied to either "push" or "focus" an omnidirectional soundfield into a planewave, giving the soundfield an angle of arrival.^{1}
Planewave encoder (monophonic).
theta 
Azimuth angle, in radians: pi to pi 
phi 
Elevation anglein radians: pi/2 to pi/2 
This is the classic Ambisonic encoding (panning) function. SuperCollider's inbuilt PanB and the Ambisonic Toolkit's FoaPanB implement this encoder as a UGen, and allow dynamically changing theta and phi.
Stereophonic encoder.
angle 
Soundfield distortion angle, in radians: pi/2 to pi/2 
The stereophonic signal is encoded as two planewaves. When angle = 0, the left and right channels of the input signal arrive at [90, 90]
degrees. angle = pi/4 distorts the arrivals to [45, 45]
degrees. angle = pi/2, places both the left and right inputs at front centre, [0, 0]
degrees. This behaviour matches that of the Ambisonic Toolkit's first order image warping UGens: FoaFocus, FoaZoom, FoaPush, and FoaPress.
Quadraphonic encoder.
The quadraphonic signal is encoded as four planewaves arriving at [ 45, 135, 135, 45 ]
degrees. This encoding is equivalent to placing infinitely distant loudspeakers around a soundfield microphone in an anechoic chamber.
5.0 encoder.
The 5.0 signal is encoded as five planewaves arriving at [ 0, 30, 110, 110, 30 ]
degrees. This encoding is equivalent to placing infinitely distant loudspeakers around a soundfield microphone in an anechoic chamber.
7.0 encoder.
The 7.0 signal is encoded as seven planewaves arriving at [ 0, 30, 90, 135, 135, 90, 30 ]
degrees. This encoding is equivalent to placing infinitely distant loudspeakers around a soundfield microphone in an anechoic chamber.
Pantophonic (2D) regular polygon encoder.
numChans 
number of input channel feeds 
orientation 

Inputs are in anticlockwise order. The position of the first input channel is either centre or left of centre. dirChannels may be used to query resulting input channel directions. This encoding is equivalent to placing infinitely distant loudspeakers around a soundfield microphone in an anechoic chamber.
Periphonic (3D) dual ring, regular cylindrical encoder.
numChanPairs 
Number of channel pairs. (Half the total number of input channel feeds.) 
elevation 
Elevation of the upper ring, measured from the origin. In radians. 
orientation 

Inputs are in anticlockwise order, beginning with the top ring. The position of the first speaker is either centre or left of centre. dirChannels may be used to query resulting loudspeaker directions. This encoding is equivalent to placing infinitely distant loudspeakers around a soundfield microphone in an anechoic chamber.
Virtual loudspeaker or microphone encoder, suitable for varied periphonic and pantophonic arrays.
directions 
An array of directions of the virtual loudspeakers or microphones. Specify in radians. Rank 1 arrays return pantophonic, while rank 2 arrays return periphonic. E.g., // 2D: ~directions = [ theta0, theta1, ... thetaN ]; // 3D: ~directions = [ [ theta0, phi0 ], [ theta1, phi1 ], ... [ thetaN, phiN ] ];  
pattern 
Virtual microphone pattern,

newDirections is the Ambisonic Toolkit's most versatile first order encoder. Arbitrary input loudspeaker and/or microphone arrays may be specified.
// Periphonic (3D) encoder, a 1/2 dome of 13 loudspeakers // [[0, 0], [45, 0], [90, 0], [135, 0], [180, 0], [135, 0], [90, 0], [45, 0], // [45, 35.3], [135, 35.3], [135, 35.3], [45, 35.3], [0, 90]] ~directions = [[0, 0], [45, 0], [90, 0], [135, 0], [180, 0], [135, 0], [90, 0], [45, 0], [45, 35.3], [135, 35.3], [135, 35.3], [45, 35.3], [0, 90]].degrad; ~encoder = FoaEncoderMatrix.newDirections(~directions); // inspect ~encoder.dirChannels.raddeg;
// Periphonic (2D) encoder, 3 cardioid microphones // See: http://www.michaelgerzonphotos.org.uk/microphonescalrecs.html // [60, 180, 60] ~directions = [60, 180, 60].degrad; ~pattern = 0.5; ~encoder = FoaEncoderMatrix.newDirections(~directions, ~pattern); // inspect ~encoder.dirChannels.raddeg;
// Periphonic (2D) encoder, 1 omni and 2 cardioid microphones // [0, 45, 45] ~directions = [0, 45, 45].degrad; ~pattern = [0, 0.5, 0.5]; ~encoder = FoaEncoderMatrix.newDirections(~directions, ~pattern); // inspect ~encoder.dirChannels.raddeg;
ZoomH2 (pantophonic) encoder.
angles 
Angles for front left and back left microphones, in radians. (The corresponding right microphones are mirrored across the yaxis.) Defaults to NOTE: The encoder reverses the labels for front and back of the ZoomH2. This is done so that directions are are preserved from the point of view of a field recording operator. With the ZoomH2's display facing the operator (for ease of monitoring), sounds arriving in front of the operator will be encoded in the front of the soundfield. See also Discussion below.  
pattern 
Microphone pattern^{3} , 0 to 1:
 
k 
Postencoding Y scalar. NOTE: Please see further discussion of k here 
A four channel recording made by the ZoomH2 will be returned as two stereo .wav files named:
Presuming the ZoomH2 is oriented as described here, the following illustrates correct input for the encoder:
// ZoomH2 records two stereo .wav files: // SRxxxF.wav // SRxxxR.wav // correct input for FoaEncoderMatrix.newZoomH2 is: ~in = [ SRxxxR.at(0), SRxxxR.at(1), SRxxxF.at(0), SRxxxF.at(1) ]
The encoder includes a Y scalar, k, and an auditioned adjustment is usually necessary to improve the resulting image. As the ZoomH2's polar patterns are not consistent across frequency, and the capsules are not coincident, imaging is not always consistent. Touching k can go some way towards remedying this.
A first order Ambisonic format exchange encoder, for use with the ZoomH2n. Encodes from AmbiX to traditional Bformat. A convenience alias to *newHoa1.
Encoding means encoding from one Ambisonic channel componenent orderding and normalisation to that of traditional Bformat. In this case, from AmbiX encoding scheme (ACN ordering, SN3D normalisation) to Gerzon (aka FurseMalham) ordering, MaxN normalisation.
SPATIAL AUDIO
mode. Further details may be reviewed in the manual addendum found here.Aformat to Bformat encoder. Encodes to a variety of tetrahedral orientations and W channel weights.
orientation 
Orientation of the Aformat tetrahedron.
 
weight 
The W weight factor. For convenience, equivalent virtual microphone pattern and decoding k are also listed.

The Aformat encoder is often used in conjunction with the FoaDecoderMatrix: *newBtoA Bformat decoder to form signal processing networks which preserve the spatial encoding as is described here.
On its own, *newAtoB is often used to author immersive, periphonic (3D) decorrelated soundfields.
A first order Ambisonic format exchange encoder. Encodes a variety of formats to traditional Bformat.
ordering 
Input Ambisonic channel component ordering.
 
normalisation 
Spherical harmonic normalisation method.

Encoding means encoding from one Ambisonic channel componenent orderding and normalisation to that of traditional Bformat. In other words, from some standard scheme to Gerzon (aka FurseMalham) ordering with MaxN normalisation.
Hoa1
in the method name *newHoa1 refers to Higher Order Ambisonic (HOA) encoding format, Ambisonic order = 1. The input signal should have four channels, with the given encoding format as specified in the arguments.A first order Ambisonic format exchange encoder. Encodes from AmbiX to traditional Bformat. A convenience alias to *newHoa1.
Encoding means encoding from one Ambisonic channel componenent orderding and normalisation to that of traditional Bformat. In this case, from AmbiX encoding scheme (ACN ordering, SN3D normalisation) to Gerzon (aka FurseMalham) ordering, MaxN normalisation.
Create an FoaEncoderMatrix by loading a matrix from a file.
filePathOrName 
Can be a path relative to your Atk.getMatrixExtensionPath('encoders').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 
'encoder'
Answers 'matrix'
, i.e. the type of operation used to compute the resulting signals.
Answers the kind of encoder.
// encoder ~encoder = FoaEncoderMatrix.newQuad // inspect ~encoder.kind
// encoder ~encoder = FoaEncoderMatrix.newPeri // inspect ~encoder.kind
Answers the number of encoder dimensions: 2D or 3D.
// encoder ~encoder = FoaEncoderMatrix.newQuad // inspect ~encoder.dim
// encoder ~encoder = FoaEncoderMatrix.newPeri // inspect ~encoder.dim
Answers the number of input channels (virtual loudspeakers or microphones).
// encoder ~encoder = FoaEncoderMatrix.newQuad // inspect ~encoder.numChannels
// encoder (two rings of 6) ~encoder = FoaEncoderMatrix.newPeri(6) // inspect ~encoder.numChannels
Answers the direction of virtual loudspeaker or microphone feeds, with angles in radians.
A rank 1 array for pantophonic, and rank 2 array for periphonic. E.g.,
// 2D: [ theta0, theta1, ... thetaN ]
// 3D [ [ theta0, phi0 ], [ theta1, phi1 ], ... [ thetaN, phiN ] ]
// encoder ~encoder = FoaEncoderMatrix.newQuad // inspect ~encoder.dirChannels.raddeg
// encoder (two rings of 6) ~encoder = FoaEncoderMatrix.newPeri(6) // inspect ~encoder.dirChannels.raddeg
Answers the encoding matrix
Answers the number of outputs for the encoder. 3 for 2D and 4 for 3D.
A convenience method providing polymorphism with FoaEncoderMatrix: dirOutputs.
[ inf, inf, inf ]
[ inf, inf, inf , inf ]
A synonym for numChannels
A synonym for dirChannels
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 FoaEncode: Examples.