Generates decoding matrices required by the Ambisonic Toolkit's first order decoder, FoaDecode.
Virtual microphone monophonic decoder.
theta |
Azimuth angle, in radians: pi to pi.neg. | ||||||||||||
phi |
Elevation angle, in radians: pi/2 to pi.neg/2. | ||||||||||||
pattern |
Virtual microphone pattern, 0 to 1:
For equivalences to decoder k, please see Decoder k. |
The virtual microphone decoder returns a single monophonic channel, and can be used to "listen in" to the soundfield at the specified azimuth and elevation.
Virtual microphone stereophonic decoder.
angle |
The half angle of the stereo pair, in radians: 0 to pi., Default: pi/2 | ||||||||||||
pattern |
Virtual microphone pattern, 0 to 1:
For equivalences to decoder k, please see Decoder k. |
Standard coincident stereo microphone configurations1 :
Optimised quadraphonic decoder with variable loudspeaker angle.
angle |
The half angle of the front (and rear) loudspeaker pair. Defaults to pi/4, a square. In radians. |
k |
The k factor of the decoder. May be specified as a float: 0.5 to 1.0. Or more conviently by name:
|
The outputs are in anti-clockwise order. The position of the first speaker is left of centre. -dirChannels may be used to query resulting loudspeaker directions.
Varying angle allows a number of flexible quadraphonic decoders to be generated. E.g, angle = pi/6 returns a decoder with loudspeakers at [ 30, 150, -150, 30 ] degrees.
Please see Decoder k for further discussion on k.
Bruce Wiggins' optimised ITU 5.0 decoders.3
irregKind |
Three kinds are available:
|
The outputs are in anti-clockwise order. The position of the first speaker is centre. -dirChannels may be used to query resulting loudspeaker directions.
irregKind = 'focused'
returns a focused, but front weighted image. 'equal'
equalises the angles across the image. 'four'
is similar to 'equal'
, but doesn't use the centre speaker.
Pantophonic (2D) regular polygon decoder.
numChans |
number of loudspeaker feeds |
orientation |
|
k |
The k factor of the decoder. May be specified as a float: 0.5 to 1.0. Or more conviently by name:
|
The outputs are in anti-clockwise order. The position of the first speaker is either centre or left of centre. -dirChannels may be used to query resulting loudspeaker directions.
Used in conjunction with FoaDecode: *ar the resulting decoder is equivalent to DecodeB2: *ar (SuperCollider's inbuilt decoder), albeit with the addition of variable k and dual-band optimised psychoacoustic decoding. DecodeB2: *ar is a "controlled opposites" decoder ( k = 'controlled'
) with a gain of 6dB greater than *newPanto.
Please see Decoder k for further discussion on k.
Periphonic (3D) dual ring, regular cylindrical decoder.
numChanPairs |
Number of channel pairs. (Half the total number of loudspeaker feeds.) |
elevation |
Elevation of the upper ring, measured from the origin. In radians. |
orientation |
|
k |
The k factor of the decoder. May be specified as a float: 0.5 to 1.0. Or more conviently by name:
|
The outputs are in anti-clockwise 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.
Please see Decoder k for further discussion on k.
Gerzon's classic diametric decoder, suitable for varied periphonic and pantophonic loudspeaker arrays.4
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.,
|
k |
The k factor of the decoder. May be specified as a float: 0.5 to 1.0. Or more conviently by name:
|
directions specifies only half of the loudspeakers for the resulting array, the remaining loudspeakers are diametrically opposite (through the origin). -dirChannels may be used to query resulting loudspeaker directions.
Please see Decoder k for further discussion on k.
B-format to A-format decoder. Decodes to a variety of tetrahedral orientations and W channel weights.
orientation |
Orientation of the A-format tetrahedron.
| |||||||||||||||||||||||||||||||||||
weight |
The W weight factor. For convenience, equivalent virtual microphone pattern and decoding k are also listed.
|
The B-format to A-format decoder is primarily intended to be used in conjuction with the A-format to B-format encoder, FoaEncoderMatrix: *newAtoB. Though the use of BtoA/AtoB decoder/encoder pairs, signal processing networks can be constructed which preserve the spatial encoding found in the original input B-format signal.
In order to reconstruct the original B-format signal, matching orientation and weight for both decoding and encoding should be chosen. For most applications the default weight ('dec'
) is a good choice. This weight decodes to four planewaves. Setting weight to 'uns'
returns an energy optimised decoding. For Dynamic Range Control processing, 'uns'
is often a good choice.
A first order Ambisonic format exchange decoder. Decodes traditional B-format to a variety of formats.
ordering |
Input Ambisonic channel component ordering.
| ||||||
normalisation |
Spherical harmonic normalisation method.
|
Decoding means decoding from traditional B-format to another Ambisonic channel componenent orderding and normalisation. In other words, from Gerzon (aka Furse-Malham) ordering with MaxN normalisation to some other standard scheme.
Hoa1
in the method name *newHoa1 refers to Higher Order Ambisonic (HOA) encoding format, Ambisonic order = 1.A first order Ambisonic format exchange decoder. Decodes traditional B-format to AmbiX. A convenience alias to *newHoa1.
Decoding means decoding from traditional B-format to another Ambisonic channel componenent orderding and normalisation. In this case, from Gerzon (aka Furse-Malham) ordering, MaxN normalisation to the AmbiX encoding scheme (ACN ordering, SN3D normalisation).
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.,
|
Create an FoaDecoderMatrix by loading a matrix from a file.
filePathOrName |
Can be a path relative to your Otherwise a full path to your matrix file. |
See the Guide to ATK Matrix Files for more information.
The default k ( 'single'
), for decoders accepting k as an argument, returns an 'energy'
optimised (aka "maximum energy" or "max rE") decoder. 'dual'
returns a dual-band psychoacoustically optimised decoder.5 The 'dual'
decoder is the optimum choice for small scale studio or domestic settings. 'single'
is suitable for larger, mid-scale environments. 'velocity'
returns "strict soundfield" (aka "planewave" or "basic") decoding.6 'controlled'
returns "controlled opposites" decoding (aka "minimum energy" or "in phase"), which is often preferred in large-scale, concert environments.7 (SuperCollider's inbuilt decoder, DecodeB2: *ar, is a "controlled opposites" decoder. See this discussion.)
Given a uniform periphonic (3D) distribution of loudspeakers, e.g. a Platonic solid, some useful virtual microphone equivalences:
keyword | decoding | virtual microphone | pattern |
'velocity' | strict soundfield | Hyper-cardioid | 0.75 |
'energy' | energy optimised | Super-cardioid | (3-sqrt(3))/2 |
'controlled' | controlled opposites | Cardioid | 0.5 |
The k keywords translate to numerical values as follows:
keyword | k for pantophonic (2D) | k for periphonic (3D) |
'velocity' | 1 | 1 |
'energy' | 1/sqrt(2) | 1/sqrt(3) |
'controlled' | 1/2 | 1/3 |
'energy'
and 'controlled'
.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
.
Answers, \FOA
, aka traditional B-format:
Ambisonic Order | Component Ordering | Component Normalisation |
1st | Furse-Malham (FuMa) | Gerzon / Furse-Malham (MaxN) |
'decoder'
Answers 'matrix'
, i.e. the type of operation used to compute the resulting signals.
Answers the kind of decoder
Answers the number of decoder dimensions: 2D or 3D.
Answers the number of loudspeaker feeds (output channels).
Answers the direction of loudspeaker feeds, with angles in radians.
A rank 1 array for pantophonic, and rank 2 array for periphonic. E.g.,
Loudspeakers should be place at the angles returned (with equal radii).
A synonym for -dirChannels
Answers the number of inputs for the decoder. 3 for 2D and 4 for 3D.
A convenience method providing polymorphism with FoaEncoderMatrix: -dirInputs.
[ inf, inf, inf ]
[ inf, inf, inf, inf ]
A synonym for -numChannels
A synonym for -dirChannels
Returns the raw coefficient Matrix.
Returns the matrix as a new Array of rows.
If the decoder is dual-band psychoacoustically optimised, get or set the shelf filter frequency, in Hz.
shelfFreq defaults to 400Hz, which is suitable for a well aligned domestic or studio space. shelfFreq may be set up to 700Hz, for a tight sweet-spot, and very focused single user listening.
If the decoder is dual-band psychoacoustically optimised, get or set the shelf k.
If set, shelfK is optimised for the chosen decoder, and should be left at the assigned value unless one is an expert user.
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.