HoaOrder:
Filter:
atk-sc3/Classes (extension) | Libraries > Ambisonic Toolkit > Coefficients & Theory

HoaOrder
ExtensionExtension

Higher Order Ambisonic (HOA) indexing & coefficients

Description

Higher Order Ambisonic (HOA) component indexing, coefficients and performance, by order.

Class Methods

.new

Create a new instance.

Arguments:

order

Ambisonic order. Def: AtkHoa.defaultOrder

Instance Methods

.order

Return higher order ambisonic order.

(ℓ, m) & HOA indices

.lm

Return an array of Associated Legendre degrees (ℓ) and indices (m).

.l

Return an array of Associated Legendre degrees (ℓ).

.m

Return an array of Associated Legendre indices (m).

.indices

Return Higher Order Ambisonic (HOA) indices.

Arguments:

ordering

Component ordering scheme:

\acnAmbisonic Channel Number (ACN)
\sidSingle Index Designation (SID)
\fumaFurse-Malham (FuMa)
subset
\allAll indices
\zonalZonal
\sectoralSectoral
\tesseralTesseral
\rotateRotation around z-axis, aka yaw

Coefficients

.size

Return number of ambisonic components.

.sph

Return N3D normalized angular encoding coefficients.

Arguments:

theta

Azimuth, in radians.

phi

Elevation, in radians.

.normalisation

Return component normalisation coefficients.

Arguments:

scheme

Component normalisation schemes:

\n3dOrthonormal basis for 3D decomposition (N3D)
\sn3dSemi-normalised basis for 3D decomposition (SN3D)
\n2dOrthonormal basis for 2D decomposition (N2D)
\sn2dSemi-normalised basis for 2D decomposition (SN2D)
\maxNMaximum normalisation (maxN)
\MaxNGerzon / Furse-Malham (MaxN)
\fumaSynonym for MaxN (FuMa)

.reflection

Return component reflection coefficients.

Arguments:

mirror
\reflectMirror across the origin.

Equivalent to: \flip * \flop * \flap.

\flipMirror in the y-axis.
\flopMirror in the x-axis.
\flapMirror in the z-axis.
\CondonShortleyPhaseCondon-Shortley Phase.

Equivalent to: \flip * \flop.

\originSynonym for \reflect.
\xSynonym for \flop.
\ySynonym for \flip.
\zSynonym for \flap.

Radial & NFE

.radiusAtFreq

Return the effective decoding radius, in meters.

Arguments:

freq

Frequency, in Hz.

speedOfSound

Speed of sound, in meters per second. Def: AtkHoa.speedOfSound

.freqAtRadius

Return the effective decoding frequency, in Hz.

Arguments:

radius

Radius, in meters. Def: AtkHoa.refRadius

speedOfSound

Speed of sound, in meters per second. Def: AtkHoa.speedOfSound

.proxWeights

Return complex near-field effect proximity radial filtering coefficients, collected by Associated Legendre degree (ℓ).

Arguments:

freq

Frequency, in Hz.

radius

Radius, in meters. Def: AtkHoa.refRadius

speedOfSound

Speed of sound, in meters per second. Def: AtkHoa.speedOfSound

Discussion:

These complex weights represent the magnitude and phase change of each degree when encoding an otherwise far-field source at a distance of radius.

See further discussion on The Near-Field Effect (NFE).

.distWeights

Return complex near-field effect distance radial filtering coefficients, collected by Associated Legendre degree (ℓ).

Arguments:

freq

Frequency, in Hz.

radius

Radius, in meters. Def: AtkHoa.refRadius

speedOfSound

Speed of sound, in meters per second. Def: AtkHoa.speedOfSound

Discussion:

These complex weights are the reciprocal of -proxWeights.

See further discussion on The Near-Field Effect (NFE).

.ctrlWeights

Return complex near-field effect control radial filtering coefficients, collected by Associated Legendre degree (ℓ).

Arguments:

freq

Frequency, in Hz.

encRadius

Encoding radius, in meters. Def: AtkHoa.refRadius

decRadius

Decoding radius, in meters. Def: AtkHoa.refRadius

speedOfSound

Speed of sound, in meters per second. Def: AtkHoa.speedOfSound

Discussion:

These complex weights represent a ratio of the -proxWeights of the encoding radius to the decoding radius, i.e. proxWeights(encRadius) / proxWeights(decRadius).

See further discussion on The Near-Field Effect (NFE).

.foclWeights

Return real near-field effect focalisation radial filtering coefficients, collected by Associated Legendre degree (ℓ).

Arguments:

freq

Frequency, in Hz.

radius

Radius, in meters. Def: AtkHoa.refRadius

window

Angular weighting window.

\regRegularised1
\hp(Butterworth) High Pass2
\cosCosine3
\sinSine4
speedOfSound

Speed of sound, in meters per second. Def: AtkHoa.speedOfSound

Beaming & Decoder matching

Three standard beam shapes are offered:

keywordbeam shapelocalisation vectorvirtual microphone
\basicstrict soundfieldmaximum velocity rVHyper-cardioid
\energyenergy optimisedmaximum energy rESuper-cardioid
\controlledcontrolled oppositesminimum diametric energyCardioid

.beamWeights

Return beamforming coefficients, collected by Associated Legendre degree (ℓ).

Arguments:

beamShape

Keyword argument for beam shape. See above.

dim

The number of dimensions: 2D or 3D.

.matchWeight

Return matching weight for an ambisonic decoder.

Arguments:

beamShape

Keyword argument for beam shape. See above.

dim

The number of dimensions: 2D or 3D.

match

Matching criteria:

\amppressure (loudspeaker sum)
\rmsspherical harmonic energy
\energyloudspeaker energy
numChans

Number of loudspeakers.

NOTE: Must be set when choosing match: \energy.

Decoder performance

.spreadE

Return the half angle of the maximum average energy spread for an ambisonic decoder.

Arguments:

beamShape

Keyword argument for beam shape. See above.

dim

The number of dimensions: 2D or 3D.

Returns:

An IdentityDictionary of values:

\cosroll-off to ~-3dB, in radians
\hvcroll-off to ~-6dB, in radians

.meanE

Return reduced energy for an ambisonic decoder.

Arguments:

beamShape

Keyword argument for beam shape. See above.

dim

The number of dimensions: 2D or 3D.

.rV

Return maximum average magnitude of the velocity localisation vector (rV) for an ambisonic decoder.

Arguments:

beamShape

Keyword argument for beam shape. See above.

dim

The number of dimensions: 2D or 3D.

.rE

Return maximum average magnitude of the energy localisation vector (rE) for an ambisonic decoder.

Arguments:

beamShape

Keyword argument for beam shape. See above.

dim

The number of dimensions: 2D or 3D.

Examples

TBD

[1] - S. Favrot and J. Buchholz. 2010. “Impact of Regularization of near Field Coding Filters for 2D and 3D Higher-Order Ambisonics on Auditory Distance Cues.” in Proc. of the 2nd International Symposium on Ambisonics and Spherical Acoustics. Paris.
[2] - J. Daniel. 2003. “Spatial sound encoding including near field effect: Introducing distance coding filters and a viable, new ambisonic format,” in Proc. of the 23rd International Conference of the Audio Engineering Society.
[3] - J. Ahrens and S. Spors. 2009. “Spatial encoding and decoding of focused virtual sound sources,” in Proc. of the 1st Ambisonics Symposium. Paris.
[4] - A sine function variation of the window proposed by Ahrens & Spors.