HoaMatrixDecoder | SuperCollider 3.13.0 Help

Description

Generate matrix decoders required by the Ambisonic Toolkit's Higher Order Ambisonic (HOA) decoder, HoaDecodeMatrix.

Matrix decoding is offered via four different methods:

projection
mode matching
beamforming
format exchange

The first two, projection and mode matching, are suitable for designing decoders for loudspeaker arrays and apply a simple HOA degree truncation where the number of desired outputs is less than the number required for an input Ambisonic order.

The third, beamforming, returns (projection) spatial windows of the input Ambisonic order, without applying degree truncation. This decoding method is suitable for spherical decomposition and beamforming for signal processing.

Format exchange decoding offers interfacing with other Ambisonic formats and systems.

Class Methods

HoaMatrixDecoder.newProjection(directions, beamShape: 'basic', match: 'amp', order)

Decode a Higher Order Ambisonic signal (HOA) via the projection method.

Arguments:

directions	An array of directions. 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 ] ];
beamShape	Keyword argument for beam shape. See discussion below.
match	Keyword argument for gain matching. See discussion below.
order	Ambisonic order.

Discussion:

Also known as Simple Ambisonic Decoding, aka SAD.

NOTE: In order to return a valid reconstruction decoder, directions should be evenly distributed.

HoaMatrixDecoder.newModeMatch(directions, beamShape: 'basic', match: 'amp', order)

Decode a Higher Order Ambisonic signal (HOA) via the mode matching method.

Arguments:

directions	An array of directions. 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 ] ];
beamShape	Keyword argument for beam shape. See discussion below.
match	Keyword argument for gain matching. See discussion below.
order	Ambisonic order.

Discussion:

Also known as Pseudoinverse Decoding, aka Pinv.

NOTE: Comprehensive modal discarding is not applied. More evely distributed directions will return a more stable decoder.

HoaMatrixDecoder.newDiametric(directions, beamShape: 'basic', match: 'amp', order)

Decode a Higher Order Ambisonic signal (HOA) via the mode matching method, given diametrically matched loudspeaker pairs. Gerzon's classic diametric decoder.¹

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 ] ];
beamShape	Keyword argument for beam shape. See discussion below.
match	Keyword argument for gain matching. See discussion below.
order	Ambisonic order.

Discussion:

Also known as Diametric Decoding.

directions specifies only half of the loudspeakers for the resulting array, the remaining loudspeakers are diametrically opposite (through the origin). -directions 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 = HoaMatrixDecoder.newDiametric(~directions, order: 1); // inspect ~decoder.directions.raddeg // Periphonic (3D) decoder with eight channels arranged in a bi-rectangle: //[ [ 30.0, 0.0 ], [ -30.0, 0.0 ], [ 90.0, 35.3 ], [ 90.0, -35.3 ], // [ -150.0, -0.0 ], [ 150.0, -0.0 ], [ -90.0, -35.3 ], [ -90.0, 35.3 ] ] // specify 1/2 the desired directions ~directions = [[ 30, 0 ], [ -30, 0 ], [ 90, 35.3 ], [ 90, -35.3]].degrad; ~decoder = HoaMatrixDecoder.newDiametric(~directions, order: 1); // inspect ~decoder.directions.raddeg

HoaMatrixDecoder.newPanto(numChans: 4, orientation: 'flat', beamShape: 'basic', match: 'amp', order)

Decode a Higher Order Ambisonic signal (HOA) via the projection method to a Pantophonic (2D) regular polygon array.

Arguments:

numChans	number of outputs
orientation	`\vertex` or `\side`
beamShape	Keyword argument for beam shape. See discussion below.
match	Keyword argument for gain matching. See discussion below.
order	Ambisonic order.

Discussion:

The outputs are in anti-clockwise order. The position of the first speaker is either centre or left of centre. -directions may be used to query resulting loudspeaker directions.

Used in conjunction with HoaDecodeMatrix the resulting decoder is equivalent to DecodeB2 (SuperCollider's inbuilt decoder), albeit with the addition of variable beam shape and gain matching. DecodeB2 is a controlled opposites decoder.// Pantophonic (2D) decoder with nine channels arranged in a regular polygon: // [ 0.0, 40.0, 80.0, 120.0, 160.0, -160.0, -120.0, -80.0, -40.0 ] // specify parameters & design ~numChans = 9 ~orientation = \vertex ~orientation = \side ~order = 3 ~decoder = HoaMatrixDecoder.newPanto(~numChans, ~orientation, order: ~order) // inspect ~decoder.directions.raddeg

HoaMatrixDecoder.newSphericalDesign(design, beamShape: 'basic', order)

Beamform into a Higher Order Ambisonic signal (HOA), returning multiple beams evenly distributed in a SphericalDesign.

Arguments:

design	SphericalDesign instance
beamShape	Keyword argument for beam shape. See discussion below.
order	Ambisonic order.

Discussion:

A-format decoding, aka spherical decomposition, is offered by *newSphericalDesign.

Gain is matched to maximum beam amplitude.// HOA3 A-format spherical decomposition // specify parameters & design ~order = 3 ~numChans = 24 ~numChans = 32 ~numChans = 64 // design spherical design & decoder ~design = TDesign.newHoa(~numChans, order: ~order) ~decoder = HoaMatrixDecoder.newSphericalDesign(~design, order: ~order) // inspect ~decoder.directions.raddeg

NOTE: Matching spherical (re-)composition is provided by HoaMatrixEncoder: *newSphericalDesign.

HoaMatrixDecoder.newDirection(theta: 0, phi: 0, beamShape, order)

Beamform into a Higher Order Ambisonic signal (HOA), returning a single beam.

Arguments:

theta	Azimuth, in radians.
phi	Elevation, in radians.
beamShape	Keyword argument for beam shape. See discussion below.
order	Ambisonic order.

Discussion:

Returns a single beam, and can be used to "listen in" to the soundfield at the specified azimuth and elevation. Gain is matched to the beam. See discussion below

HoaMatrixDecoder.newDirections(directions, beamShape, match, order)

Beamform into a Higher Order Ambisonic signal (HOA), returning multiple beams.

Arguments:

directions	An array of directions. 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 ] ];
beamShape	Keyword argument for beam shape. See discussion below.
match	Keyword argument for gain matching. See discussion below.
order	Ambisonic order.

Discussion:

Returns a collection of beams, and can be used to "listen in" to the soundfield at the specified azimuths and elevations.

WARNING: As a projection beamformer, does not return a valid reconstruction decoder for arbitrary loudspeaker directions. Similarly, Ambisonic order is not truncated given an insufficient number of loudspeakers or distribution of directions.

HoaMatrixDecoder.newFormat(format: 'atk', order)

An Ambisonic format exchange decoder. Decodes from ACN-N3D to a variety of formats.

Arguments:

format

An array of kewords designating component ordering and normalisation.

E.g., target output format ACN-SN3D is expressed [ \acn, \sn3d ]. See discussion below.

order

Ambisonic order.

Discussion:

A variety of component ordering and normalisation schemes are supported. These are:

ordering

`\acn`	Ambisonic Channel Number (ACN)
`\sid`	Single Index Designation (SID)
`\fuma`	Furse-Malham (FuMa)

normalisation

`\n3d`	Orthonormal basis for 3D decomposition (N3D)
`\sn3d`	Semi-normalised basis for 3D decomposition (SN3D)
`\n2d`	Orthonormal basis for 2D decomposition (N2D)
`\sn2d`	Semi-normalised basis for 2D decomposition (SN2D)
`\maxN`	Maximum normalisation (maxN)
`\MaxN`	Gerzon / Furse-Malham (MaxN)
`\fuma`	Synonym for MaxN (FuMa)

Additionally, a number of common formats are available as a single keyword:

`\atk`	Ambisonic Toolkit (ATK)
`\ambix`	Ambisonics Exchangeable (AmbiX)
`\fuma`	Furse-Malham (FuMa)

Matrix & File

HoaMatrixDecoder.newFromMatrix(matrix, directions, order)

From superclass: HoaMatrix

Create an instance from a raw 2D Matrix.

Arguments:

matrix

A Matrix in the form ofMatrix.with([[row1],[row2],...[rowN]])

directions

An array of directions. 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 ] ];

order

Ambisonic order.

HoaMatrixDecoder.newFromFile(filePathOrName, searchExtensions: true, order)

From superclass: HoaMatrix

Create an instance by loading a matrix from a file.

Arguments:

filePathOrName

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

Otherwise a full path to your matrix file.

searchExtensions

Search extension paths.

order

Ambisonic order.

Discussion:

See the Guide to ATK Matrix Files for more information.

Beam shape

Three standard beam shapes are offered:

keyword	beam shape	localisation vector	virtual microphone
`\basic`	strict soundfield	maximum velocity rV	Hyper-cardioid
`\energy`	energy optimised	maximum energy rE	Super-cardioid
`\controlled`	controlled opposites	minimum diametric energy	Cardioid

NOTE: For large-scale concert presentation, the authors advise choosing the energy optimised beam shape.

Gain match

Decoder gains can be normalised, aka matched, via various criteria:

keyword	matching criteria	valid decoding methods
`\beam`	maximum beam amplitude	beamforming only
`\amp`	pressure (loudspeaker sum)	all methods
`\rms`	spherical harmonic energy	projection & mode matching only
`\energy`	loudspeaker energy	projection & mode matching only

Normalising gain to the beam amplitude is appropriate for a virtual microphone or spherical decomposition context. In this case, maximum amplitude of each returned beam is normalised to 0dB.

The other three criteria, pressure, total spherical harmonic energy, and total loudspeaker energy, are preferred for building decoders for loudspeaker audition.

Inherited class methods

Instance Methods

Information

.info

From superclass: AtkMatrix

A convenience method to post the properties of the matrix, including metadata if the matrix was loaded from a .yml file.

.order

From superclass: AtkMatrix

Ambisonic order.

.set

From superclass: HoaMatrix

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 3-D normalisation (N3D)

Matrix

.matrix

From superclass: AtkMatrix

Returns the raw coefficient Matrix.

.thresh2(thresh)

From superclass: HoaMatrix

Bilateral thresholding in place.

fileNameOrPath	A String of the file name. The file extension determines the format: `.yml` allows for additional user-specified metadata (recommended). `.txt` writes the matrix coefficients only, in rows. `.mosl.txt` creates basic matrix files compatible with the ATK for Reaper, a set of JSFX plugins for the Reaper DAW. You may provide a full path if you would like to save the file somewhere other than the default location in the Atk `extensions` folder. See the Discussion below for more information.
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.

Discussion:

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.

Analysis

.analyzeAverage

Return an average analysis of decoder amplitude and energies.

Returns:

Analysis is returned in an IdentityDictionary, with the following keys:

keyword	analysis
`\amp`	pressure (loudspeaker sum)
`\rms`	spherical harmonic energy
`\energy`	loudspeaker (angular) energy
`\meanE`	decoder reduced energy
`\matchWeight`	decoder matching weights (a Dictionary)

The required weights for gain matching are returned in the \matchWeight Dictionary:

keyword	analysis
`\amp`	match weight for pressure (loudspeaker sum)
`\rms`	match weight for spherical harmonic energy
`\energy`	match weight for loudspeaker energy

Discussion:

Offers a convenient way to check whether designed decoders meet the theoretical performance predicted by HoaOrder.

A regular array, evenly distributed loudspeakers:// Pantophonic (2D) decoder with nine channels arranged in a regular polygon // specify parameters & design ~numChans = 9 ~beamShape = \basic ~beamShape = \energy ~beamShape = \controlled ~match = \amp ~match = \rms ~match = \energy ~order = 3 ~decoder = HoaMatrixDecoder.newPanto(~numChans, beamShape: ~beamShape, match: ~match, order: ~order) // HoaOrder - theoretical values ~hoaOrder = HoaOrder.new(~order) // analyze average - 'reduced energy E' for an Ambisonic decoder ~decoder.analyzeAverage.meanE // compare to theoretical - 'reduced energy E' for an Ambisonic decoder ~hoaOrder.meanE(~beamShape, ~decoder.dim) // analyze average - measured amplitude ~decoder.analyzeAverage.amp // compare to theoretical - expected amplitude ~hoaOrder.matchWeight(~beamShape, ~decoder.dim, ~match, ~decoder.numChannels)

Unevenly distributed loudspeakers:// Pantophonic (2D) decoder with four channels arranged in a rectangle: // [ 30, -30, -150, 150 ] // specify parameters & design ~directions = [ 30, -30 ].degrad // 1/2 the desired directions ~beamShape = \basic ~beamShape = \energy ~beamShape = \controlled ~match = \amp ~match = \rms ~match = \energy ~order = 1 ~decoder = HoaMatrixDecoder.newDiametric(~directions, ~beamShape, ~match, ~order); // HoaOrder - theoretical values ~hoaOrder = HoaOrder.new(~order) // analyze average - 'reduced energy E' for an Ambisonic decoder ~decoder.analyzeAverage.meanE // compare to theoretical - 'reduced energy E' for an Ambisonic decoder ~hoaOrder.meanE(~beamShape, ~decoder.dim) // analyze average - measured amplitude ~decoder.analyzeAverage.amp // compare to theoretical - expected amplitude ~hoaOrder.matchWeight(~beamShape, ~decoder.dim, ~match, ~decoder.numChannels)

.analyzeDirections(directions)

Return a directional analysis of decoder performance.

Arguments:

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

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

Returns:

Analysis is returned in a an IdentityDictionary, with the following keys:

keyword	analysis
`\amp`	pressure (loudspeaker sum)
`\rms`	spherical harmonic energy
`\energy`	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`	roll-off to ~-3dB, in radians
`\hvc`	roll-off 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 decoder performance.

A regular array, evenly distributed loudspeakers:// Pantophonic (2D) decoder with seven channels arranged in a regular polygon // specify parameters & design ~numChans = 7 ~beamShape = \basic ~beamShape = \energy ~beamShape = \controlled ~match = \amp ~match = \rms ~match = \energy ~order = 2 ~order = 1 ~decoder = HoaMatrixDecoder.newPanto(~numChans, beamShape: ~beamShape, match: ~match, order: ~order) //---- // analysis ~numTestDirections = 16 ~testDirections = Array.regularPolygon(~numTestDirections) // analyze ~analysis = ~decoder.analyzeDirections(~testDirections) ~analysis.amp.abs.ampdb.round(0.01) ~analysis.rms.sqrt.ampdb.round(0.01) ~analysis.energy.sqrt.ampdb.round(0.01) ~analysis.spreadE.cos.raddeg ~analysis.rV.magnitudes ~analysis.rV.directions.raddeg.round(0.1) ~analysis.rV.warp.raddeg.round(0.1) ~analysis.rV.rEwarp.raddeg.round(0.1) ~analysis.rE.magnitudes ~analysis.rE.directions.raddeg.round(0.1) ~analysis.rE.warp.raddeg.round(0.1)

Unevenly distributed loudspeakers:// Pantophonic (2D) decoder with seven channels arranged in a consumer orientation // specify parameters & design ~directions = [ 0.0, 30.0, 110.0, 135.0, -135.0, -110.0, -30.0 ].degrad // 7.0 array ~beamShape = \basic ~beamShape = \energy ~beamShape = \controlled ~match = \amp ~match = \rms ~match = \energy ~order = 2 ~order = 1 ~decoder = HoaMatrixDecoder.newModeMatch(~directions, ~beamShape, ~match, ~order) //---- // analysis ~numTestDirections = 16 ~testDirections = Array.regularPolygon(~numTestDirections) // analyze ~analysis = ~decoder.analyzeDirections(~testDirections) ~analysis.amp.abs.ampdb.round(0.01) ~analysis.rms.sqrt.ampdb.round(0.01) ~analysis.energy.sqrt.ampdb.round(0.01) ~analysis.spreadE.cos.raddeg ~analysis.rV.magnitudes ~analysis.rV.directions.raddeg.round(0.1) ~analysis.rV.warp.raddeg.round(0.1) ~analysis.rV.rEwarp.raddeg.round(0.1) ~analysis.rE.magnitudes ~analysis.rE.directions.raddeg.round(0.1) ~analysis.rE.warp.raddeg.round(0.1)

Inherited instance methods

Examples

Designs

Analysis & plotting

A few functions useful for visualizing decoder performance.

Equatorial rV & rE

A function to plot the velocity and energy localisation vectors in the equatorial plane:( ~rVrEequator = { |decoder, size = 100, rVcolor = (Color.blue), rEcolor = (Color.red), bounds = (Rect.new(0.0, 0.0, 1000.0, 715.0))| // analysis var analysis = decoder.analyzeDirections( Array.regularPolygon(size) ); // directions - as spherical var lsDirs = decoder.directions.collect({ |angles| Spherical.new(1.0, angles.first, angles.last) }); var rVdirs = analysis.rV.xyz.collect({ |xyz| // rV xyz.asCartesian.asSpherical; }); var rEdirs = analysis.rE.xyz.collect({ |xyz| // rE xyz.asCartesian.asSpherical; }); // indices - for indexing & grouping var lsIndices = Array.series(lsDirs.size); var rVindices = Array.series(rVdirs.size, lsDirs.size); var rEindices = Array.series(rEdirs.size, lsDirs.size + rVindices.size); // Window & PointView var window = Window.new( "% (%D) %: rV & rE".format(decoder.set, decoder.dim, decoder.kind), bounds: bounds, resizable: false ); var pv = PointView.new(window, bounds: bounds); // set up / decorate pv.showIndices_(false); pv.setOrtho('-Z'); // orthographic projection down the Z axis pv.axisScale_(1.0); // loudspeakers pv.directions_(lsDirs); // set directions pv.pointColors_(pv.connectionColor); pv.connections_(\sequential, true); // update / add localisation dirs pv.directions_(lsDirs ++ rVdirs ++ rEdirs, false); // don't reset connections! // group points by color pv.colorGroups_([ lsIndices, rVindices, rEindices ]); pv.groupColors_([ pv.connectionColor, rVcolor, rEcolor ]); window.front // move to front } )

[1] - 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.

helpfile source: /Library/Application Support/SuperCollider/downloaded-quarks/atk-sc3/HelpSource/Classes/HoaMatrixDecoder.schelp
link::Classes/HoaMatrixDecoder::

HoaMatrixDecoder : HoaMatrix : AtkMatrix : Object Extension

HoaMatrixDecoder.newProjection(directions, beamShape: 'basic', match: 'amp', order)

Arguments:

Discussion:

HoaMatrixDecoder.newModeMatch(directions, beamShape: 'basic', match: 'amp', order)

Arguments:

Discussion:

HoaMatrixDecoder.newDiametric(directions, beamShape: 'basic', match: 'amp', order)

Arguments:

Discussion:

HoaMatrixDecoder.newPanto(numChans: 4, orientation: 'flat', beamShape: 'basic', match: 'amp', order)

Arguments:

Discussion:

HoaMatrixDecoder.newSphericalDesign(design, beamShape: 'basic', order)

Arguments:

Discussion:

HoaMatrixDecoder.newDirection(theta: 0, phi: 0, beamShape, order)

Arguments:

Discussion:

HoaMatrixDecoder.newDirections(directions, beamShape, match, order)

Arguments:

Discussion:

HoaMatrixDecoder.newFormat(format: 'atk', order)

Arguments:

Discussion:

HoaMatrixDecoder.newFromMatrix(matrix, directions, order)

Arguments:

HoaMatrixDecoder.newFromFile(filePathOrName, searchExtensions: true, order)

Arguments:

Discussion:

.info

.order

.set

.type

.op

.kind

.dim

.numChannels

.directions

.numInputs

.dirInputs

.numOutputs

.dirOutputs

.matrix

.thresh2(thresh)

Arguments:

.asArray

.fileName

.filePath

.fileParse

.writeToFile(fileNameOrPath, note, attributeDictionary, overwrite: false)

Arguments:

Discussion:

.analyzeAverage

Returns:

Discussion:

.analyzeDirections(directions)

Arguments:

Returns:

HoaMatrixDecoder : HoaMatrix : AtkMatrix : Object
Extension