FoaDecoderMatrix | SuperCollider 3.13.0 Help

Description

Generates decoding matrices required by the Ambisonic Toolkit's first order decoder, FoaDecode.

NOTE: The ATK matrices are required for using some of the matrix decoders. Please see Atk: Installation of ATK dependencies for instructions.

Class Methods

.newMono

Virtual microphone monophonic decoder.

Arguments:

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:

pattern	virtual microphone
0.0	Omni
0.5	Cardioid
(3-sqrt(3))/2	Super-cardioid
0.75	Hyper-cardioid
1.0	Bi-directional

For equivalences to decoder k, please see Decoder k.

Discussion:

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.

.newStereo

Virtual microphone stereophonic decoder.

Arguments:

angle

The half angle of the stereo pair, in radians: 0 to pi., Default: pi/2

pattern

Virtual microphone pattern, 0 to 1:

pattern	virtual microphone
0.0	Omni
0.5	Cardioid
(3-sqrt(3))/2	Super-cardioid
0.75	Hyper-cardioid
1.0	Bi-directional

For equivalences to decoder k, please see Decoder k.

Discussion:

Standard coincident stereo microphone configurations¹ :// Default: Cardioids at 180 deg ~decoder = FoaDecoderMatrix.newStereo // Cardioids at 131 deg ~angle = (131/2).degrad ~pattern = 0.5 ~decoder = FoaDecoderMatrix.newStereo(~angle, ~pattern) // Super-cardioids at 115 deg ~angle = (115/2).degrad ~pattern = (3-sqrt(3))/2 ~decoder = FoaDecoderMatrix.newStereo(~angle, ~pattern) // Hyper-cardioids at 105 deg ~angle = (105/2).degrad ~pattern = 0.75 ~decoder = FoaDecoderMatrix.newStereo(~angle, ~pattern) // Blumlein ~angle = (90/2).degrad ~pattern = 1.0 ~decoder = FoaDecoderMatrix.newStereo(~angle, ~pattern)

NOTE: While the virtual microphone stereophonic decoder is very easy and convenient, for production work the authors advise using the UHJ ( FoaDecoderKernel: *newUHJ ) decoder.²

.newQuad

Optimised quadraphonic decoder with variable loudspeaker angle.

Arguments:

angle

The half angle of the front (and rear) loudspeaker pair. Defaults to pi/4, a square. In radians.

The k factor of the decoder. May be specified as a float: 0.5 to 1.0. Or more conviently by name:

'single'
'dual'
'velocity'
'energy'
'controlled'

Discussion:

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.

.new5_0

Bruce Wiggins' optimised ITU 5.0 decoders.³

Arguments:

irregKind

Three kinds are available:

'focused'
'equal'
'four'

Discussion:

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.

.newPanto

Pantophonic (2D) regular polygon decoder.

Arguments:

numChans

number of loudspeaker feeds

orientation

'flat' or 'point'

The k factor of the decoder. May be specified as a float: 0.5 to 1.0. Or more conviently by name:

'single'
'dual'
'velocity'
'energy'
'controlled'

Discussion:

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.

.newPeri

Periphonic (3D) dual ring, regular cylindrical decoder.

Arguments:

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	`'flat'` or `'point'`
k	The k factor of the decoder. May be specified as a float: 0.5 to 1.0. Or more conviently by name: `'single'` `'dual'` `'velocity'` `'energy'` `'controlled'`

Discussion:

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.

.newDiametric

Gerzon's classic diametric decoder, suitable for varied periphonic and pantophonic loudspeaker arrays.⁴

Arguments:

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.,// 2D: ~directions = [ theta0, theta1, ... thetaN ];

// 3D: ~directions = [ [ theta0, phi0 ], [ theta1, phi1 ], ... [ thetaN, phiN ] ];

The k factor of the decoder. May be specified as a float: 0.5 to 1.0. Or more conviently by name:

'single'
'dual'
'velocity'
'energy'
'controlled'

Discussion:

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.// Pantophonic (2D) decoder with four channels arranged in a rectangle: // [ 30, -30, -150, 150 ] // specify 1/2 the desired directions ~directions = [ 30, -30 ].degrad; ~decoder = FoaDecoderMatrix.newDiametric(~directions); // inspect ~decoder.dirChannels.raddeg

// Periphonic (3D) decoder with eight channels arranged in a bi-rectangle: // [ [ 30, 0 ], [ -30, 0 ], [ 90, 35.3 ], [ -90, 35.3 ], // [ -150, -0 ], [ 150, -0 ], [ -90, -35.3 ], [ 90, -35.3 ] ] // specify 1/2 the desired directions ~directions = [[ 30, 0 ], [ -30, 0 ], [ 90, 35.3 ], [ -90, 35.3]].degrad; ~decoder = FoaDecoderMatrix.newDiametric(~directions); // inspect ~decoder.dirChannels.raddeg

Please see Decoder k for further discussion on k.

.newBtoA

B-format to A-format decoder. Decodes to a variety of tetrahedral orientations and W channel weights.

Arguments:

orientation

Orientation of the A-format tetrahedron.

orientation	angles ([theta, phi] in degrees)
`'flu'`	`[[45.0, 35.3], [-45.0, -35.3], [135.0, -35.3], [-135.0, 35.3]]`
`'fld'`	`[[45.0, -35.3], [-45.0 , 35.3], [135.0, 35.3], [-135.0, -35.3]]`
`'flr'`	`[[54.7, 0.0], [-54.7, 0.0], [180.0, 54.7], [ 180.0, -54.7]]`
`'fud'`	`[[ 0.0, 54.7], [ 0.0, -54.7], [125.7, 0.0], [-125.7, 0.0]]`
`'fbd'`	`[[ 0.0, 0.0], [180.0, -70.5], [112.2, 28.1], [-112.2, 28.1]]`
`'fbu'`	`[[ 0.0, 0.0], [180.0, 70.5], [112.2, -28.1], [-112.2, -28.1]]`
`'flru'`	`[[67.8, 28.1], [-67.8, 28.1], [ 0.0, -70.5], [ 180.0, 0.0]]`
`'flrd'`	`[[67.8, -28.1], [-67.8, -28.1], [ 0.0, 70.5], [ 180.0, 0.0]]`

weight

The W weight factor.

For convenience, equivalent virtual microphone pattern and decoding k are also listed.

weight	kind	W scale	virtual microphone	pattern	decoding	k
`'dec'`	Decorrelated (on the sphere)	1/sqrt(3)	Hyper-cardioid	0.75	strict soundfield	`'velocity'`
`'can'`	Canonical (B-format)	1/sqrt(2)		sqrt(6)/(1+sqrt(6))		sqrt(2/3)
`'uns'`	Unscaled	1	Super-cardioid	(3-sqrt(3))/2	energy optimised	`'energy'`
`'car'`	Cardioid	sqrt(3)	Cardioid	0.5	controlled opposites	`'controlled'`

Discussion:

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.// ------------------------------------------------------------ // Single stage allpass ambience in A-format // // mono pink noise source // FoaPanB encoder // // quad decoder // decoder matrix ~decoder = FoaDecoderMatrix.newQuad // b-to-a, a-to-b matrices ~b2a = FoaDecoderMatrix.newBtoA ~a2b = FoaEncoderMatrix.newAtoB // inspect ~decoder.kind ~decoder.numChannels ~decoder.dirChannels.raddeg ( { var sig; // audio signal var azim; // azimuth control var fl, bl, br, fr; // quad output channels var delaytime, decaytime; // allpass parameters // display decoder "Ambisonic decoding via % decoder".format(~decoder.kind).postln; // ------------------------------------------------------------ // parameters delaytime = 0.1; decaytime = 0.2; // azimuth -> hard left = back // centre = centre // hard right = back azim = MouseX.kr(pi, -pi); // ------------------------------------------------------------ // test sig sig = PinkNoise.ar * LFPulse.ar(2.0); // enveloped mono pink noise // ------------------------------------------------------------ // encode to b-format sig = FoaPanB.ar(sig, azim); // ------------------------------------------------------------ // b-to-a --> allpass --> a-to-b sig = FoaDecode.ar(sig, ~b2a); sig = AllpassN.ar(sig, delaytime, Array.fill(4, {delaytime}).rand, decaytime); sig = FoaEncode.ar(sig, ~a2b); // ------------------------------------------------------------ // decode (to quad) #fl, bl, br, fr = FoaDecode.ar(sig, ~decoder); [fl, fr, bl, br] // reorder output to match speaker arrangement }.scope; ) // ------------------------------------------------------------

.newHoa1

A first order Ambisonic format exchange decoder. Decodes traditional B-format to a variety of formats.

Arguments:

ordering

Input Ambisonic channel component ordering.

ordering	kind
`'acn'`	Ambisonic Channel Number (ACN)
`'sid'`	Single Index Designation (SID)

normalisation

Spherical harmonic normalisation method.

normalisation	kind
`'n3d'`	Orthonormal basis for 3D decomposition (N3D)
`'sn3d'`	Semi-normalised basis for 3D decomposition (SN3D)

Discussion:

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.

NOTE: Hoa1 in the method name *newHoa1 refers to Higher Order Ambisonic (HOA) encoding format, Ambisonic order = 1.

.newAmbix1

A first order Ambisonic format exchange decoder. Decodes traditional B-format to AmbiX. A convenience alias to *newHoa1.

Discussion:

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).

Matrix & File

.newFromFile

Create an FoaDecoderMatrix by loading a matrix from a file.

Arguments:

filePathOrName

Can be a path relative to your /extensions/matrices/FOA/decoders folder:Atk.getMatrixExtensionSubPath(\FOA, \decoders).fullPath

Otherwise a full path to your matrix file.

Discussion:

See the Guide-to-ATK-Matrix-Files for more information.

Decoder k

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.⁵ 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.⁶ 'controlled' returns "controlled opposites" decoding (aka "minimum energy" or "in phase"), which is often preferred in large-scale, concert environments.⁷ (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

NOTE: For large-scale concert presentation, the authors advise auditioning values of k between those noted for 'energy' and 'controlled'.

Instance Methods

Information

.type

Returns:

'decoder'

.kind

Answers the kind of decoder

Discussion:

.dim

Answers the number of decoder dimensions: 2D or 3D.

Discussion:

.numChannels

Answers the number of loudspeaker feeds (output channels).

Discussion:

.dirChannels

Answers the direction of loudspeaker feeds, with angles in radians.

Returns:

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 ] ]

Discussion:

Loudspeakers should be place at the angles returned (with equal radii).// decoder (narrow quad) ~decoder = FoaDecoderMatrix.newQuad(pi/6) // inspect ~decoder.dirChannels.raddeg // decoder (two rings of 6) ~decoder = FoaDecoderMatrix.newPeri(6) // inspect ~decoder.dirChannels.raddeg // Pantophonic (2D) decoder with four channels arranged in a rectangle: ~directions = [ 30, -30 ].degrad ~decoder = FoaDecoderMatrix.newDiametric(~directions) // inspect ~decoder.dirChannels.raddeg // Periphonic (3D) decoder with eight channels arranged in a bi-rectangle: ~directions = [[ 30, 0 ], [ -30, 0 ], [ 90, 35.3 ], [ -90, 35.3]].degrad ~decoder = FoaDecoderMatrix.newDiametric(~directions) // inspect ~decoder.dirChannels.raddeg

.numInputs

Answers the number of inputs for the decoder. 3 for 2D and 4 for 3D.

.dirInputs

A convenience method providing polymorphism with FoaEncoderMatrix: -dirInputs.

Returns:

for 2D: [ inf, inf, inf ]
for 3D: [ inf, inf, inf, inf ]

.numOutputs

A synonym for -numChannels

.dirOutputs

A synonym for -dirChannels

Matrix

NFC

.shelfFreq

If the decoder is dual-band psychoacoustically optimised, get or set the shelf filter frequency, in Hz.

Discussion:

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.

.shelfK

If the decoder is dual-band psychoacoustically optimised, get or set the shelf k.

Discussion:

If set, shelfK is optimised for the chosen decoder, and should be left at the assigned value unless one is an expert user.

File handling

Examples

Decoding-FOA

[1] - Sengpiel Audio provides a useful tool to visualise resulting imaging: http://www.sengpielaudio.com/Visualization-Blumlein-E.htm

[2] - See http://en.wikipedia.org/wiki/Ambisonic_UHJ_format for further information.

[3] - Irregular decoders in the Ambisonic Toolkit are kindly provided by Bruce Wiggins: http://www.brucewiggins.co.uk/. See also: B. Wiggins, I. Paterson-Stephens, V. Lowndes, and S. Berry, "The design and optimisation of surround sound decoders using heuristic methods," in Proceedings of UKSIM 2003: Conference on Computer Simulation, Cambridge, England, 2003.

[4] - See: M. A. Gerzon, "Practical Periphony: The Reproduction of Full-Sphere Sound," in Proceedings of the 65th Audio Engineering Engineering Society Convention, London, 1980, p. 10.

[5] - See: E. Benjamin, R. Lee, and A. Heller, "Is My Decoder Ambisonic?," in Proceedings of the 125th Audio Engineering Society Convention, San Francisco, 2008.

[6] - While "strict soundfield" decoding is usually not preferred for first order Ambisonics audition, it is usually a good choice for use in signal processing networks.

[7] - See: D. G. Malham, "Experience with Large Area 3-D Ambisonic Sound Systems," Proceedings of the Institute of Acoustics, vol. 14, no. 5, pp. 209–215, Nov. 1992.

helpfile source: HelpSource/Classes/FoaDecoderMatrix.schelp
link::atk-sc3/Classes/FoaDecoderMatrix::

FoaDecoderMatrixExtension

.newMono

Arguments:

Discussion:

.newStereo

Arguments:

Discussion:

.newQuad

Arguments:

Discussion:

.new5_0

Arguments:

Discussion:

.newPanto

Arguments:

Discussion:

.newPeri

Arguments:

Discussion:

.newDiametric

Arguments:

Discussion:

.newBtoA

Arguments:

Discussion:

.newHoa1

Arguments:

Discussion:

.newAmbix1

Discussion:

.newFromFile

Arguments:

Discussion:

.type

Returns:

.kind

Discussion:

.dim

Discussion:

.numChannels

Discussion:

.dirChannels

Returns:

Discussion:

.numInputs

.dirInputs

Returns:

.numOutputs

.dirOutputs

.shelfFreq

Discussion:

.shelfK

Discussion:

FoaDecoderMatrix
Extension