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

.newProjection

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.

.newModeMatch

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.

.newDiametric

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

.newPanto

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

.newSphericalDesign

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.

.newDirection

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

.newDirections

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.

.newFormat

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

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.

Instance Methods

Information

Matrix

File handling

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

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)

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: HelpSource/Classes/HoaMatrixDecoder.schelp
link::atk-sc3/Classes/HoaMatrixDecoder::

HoaMatrixDecoderExtension

.newProjection

Arguments:

Discussion:

.newModeMatch

Arguments:

Discussion:

.newDiametric

Arguments:

Discussion:

.newPanto

Arguments:

Discussion:

.newSphericalDesign

Arguments:

Discussion:

.newDirection

Arguments:

Discussion:

.newDirections

Arguments:

Discussion:

.newFormat

Arguments:

Discussion:

.analyzeAverage

Returns:

Discussion:

.analyzeDirections

Arguments:

Returns:

HoaMatrixDecoder
Extension