HoaMatrixXformer | SuperCollider 3.13.0 Help

Description

Generate matrix transformers required by the Ambisonic Toolkit's Higher Order Ambisonic (HOA) transformer, HoaXformMatrix.

Class Methods

.newBeam

Beamform into a Higher Order Ambisonic signal (HOA).

Arguments:

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

.newNull

Nullform into a Higher Order Ambisonic signal (HOA).

Arguments:

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

.newReflect

Mirror a Higher Order Ambisonic signal (HOA).

Arguments:

mirror	Keyword argument for reflection. See discussion below.
order	Ambisonic order.

Discussion:

A variety of reflection transforms are offered:

keyword	mirror
`\reflect`	Mirror across the origin. Equivalent to: `\flip * \flop * \flap`.¹
`\flip`	Mirror in the y-axis.²
`\flop`	Mirror in the x-axis.³
`\flap`	Mirror in the z-axis.⁴
`\CondonShortleyPhase`	Condon-Shortley Phase. Equivalent to: `\flip * \flop`.
`\origin`	Synonym for `\reflect`.
`\x`	Synonym for `\flop`.
`\y`	Synonym for `\flip`.
`\z`	Synonym for `\flap`.

.newRotateAxis

Rotate a Higher Order Ambisonic signal (HOA) around an axis.

Arguments:

axis	Keyword argument for axis of rotation. See discussion below.
angle	Rotation angle, in radians.
order	Ambisonic order.

Discussion:

Rotation about one of the three cartesian axes are offered via these keywords:

keyword	axis of rotation
`\x`	x-axis
`\y`	y-axis
`\z`	z-axis
`\rotate`	Synonym for `\z`.
`\tilt`	Synonym for `\x`.
`\tumble`	Synonym for `\y`.
`\yaw`	Synonym for `\z`.
`\pitch`	Synonym for `\y`.
`\roll`	Synonym for `\x`.

.newRTT

Compound rotation around the z, x and y axes, applied in sequential order: rotate, tilt, tumble.

NOTE: Extrinsic, "laboratory-fixed" axes.

Arguments:

rotate	Rotation angle around z-axis, in radians.
tilt	Rotation angle around x-axis, in radians.
tumble	Rotation angle around y-axis, in radians.
order	Ambisonic order.

.newYPR

Compound rotation around the z, y' and x" axes: yaw, pitch, roll.

NOTE: Mixed extrinsic (z-axis), intrinsic (y' & x"-axes) rotations. This rotation differs from *newRTT, which is extrinsic.

Arguments:

yaw	Rotation angle around z-axis, in radians.
pitch	Rotation angle around y'-axis, in radians.
roll	Rotation angle around x"-axis, in radians.
order	Ambisonic order.

.newRotate

Compound rotation around the cartesian axes, applied in sequential order.

NOTE: Extrinsic, "laboratory-fixed" axes.

Arguments:

r1	Rotation angle around axis-1, in radians.
r2	Rotation angle around axis-2, in radians.
r3	Rotation angle around axis-2, in radians.
axes	Individual axes are specified via the axial keywords for *newRotateAxis. Specify order of rotations via concatenation. E.g., rotate, tilt, tumble: `\zxy`
order	Ambisonic order.

.newSwapAxes

Swap two axes of a Higher Order Ambisonic signal (HOA).

Arguments:

axes

Individual axes are specified via the axial keywords for *newRotateAxis.

Specify swap via concatenation. E.g., swap y-axis with z-azis: \yz

order

Ambisonic order.

.newDominate

Apply dominance along an arbitrary axis.

Arguments:

gain	Dominance gain, in dB.
theta	Azimuth, in radians.
phi	Elevation, in radians.
order	Ambisonic order.

Discussion:

Applies dominance along the axis defined by theta and phi.

Positive values of gain increase the gain at [theta, phi] to +gain dB, while decreasing the gain at [theta.neg, phi.neg] to -gain. This simultaneously results in a distortion of the image towards [theta, phi]. Negative values of gain invert this distortion, distorting towards [theta.neg, phi.neg] . The default, 0, results in no change.

Imaging is illustrated here.

.newZoom

Apply zoom along an arbitrary axis.

Arguments:

angle	Distortion angle, in radians. -pi/2 to pi/2
theta	Azimuth, in radians.
phi	Elevation, in radians.
order	Ambisonic order.

Discussion:

Applies zoom along the axis defined by theta and phi.

Zoom is a normailised dominance variant, specified in terms of a distortion angle. Positive values of angle increase gain at [theta, phi], while reducing at [theta.neg, phi.neg]. Negative values do the inverse. The default, 0, results in no change.

Imaging is illustrated here.

.newFocus

Apply focus along an arbitrary axis.

Arguments:

angle	Distortion angle, in radians. -pi/2 to pi/2
theta	Azimuth, in radians.
phi	Elevation, in radians.
order	Ambisonic order.

Discussion:

Applies focus along the axis defined by theta and phi.

Focus is a normalised dominance variant, specified in terms of a distortion angle. Positive values of angle maintain gain at [theta, phi], while reducing at [theta.neg, phi.neg]. Negative values do the inverse. The default, 0, results in no change.

In contrast with zoom, gain is maintained at 0dB in the direction of distortion.

Imaging is illustrated here.

.newAsymmetry

Apply soundfield asymmetry

Arguments:

angle	Distortion angle, in radians. -pi/2 to pi/2
order	Ambisonic order.

Discussion:

Positive values of angle rotate [-pi/2, 0] towards [0, 0], and at pi/2 collapse the soundfield to a travelling wave. Negative values rotate [pi/2, 0] towards [0, 0]. The default, 0, results in no change.

Imaging is illustrated here.

.newBalance

Apply soundfield balance.

Arguments:

angle	Distortion angle, in radians. -pi/2 to pi/2
order	Ambisonic order.

Discussion:

A synonym for apply zoom along the y-axis.

Balance is a normailised dominance variant, specified in terms of a distortion angle. Positive values of angle increase gain at [pi/2, 0], while reducing at [-pi/2, 0]. Negative values do the inverse. The default, 0, results in no change.

Imaging is illustrated here.

Matrix & File

.newFromMatrix

Transform a Higher Order Ambisonic signal (HOA) via a directly designed spatial filter.

Arguments:

matrix	A Matrix instance.
order	Ambisonic order.

Instance Methods

Information

Matrix

File handling

Analysis

.analyzeAverage

Return an average analysis of transformer amplitude and energies.

Returns:

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

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

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

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

Discussion:

Offers a convenient way to review modifications to the soundfield.

Rotation:// Axial rotation // specify parameters & design ~axis = \z ~angle = pi/3 ~order = 3 ~xformer = HoaMatrixXformer.newRotateAxis(~axis, ~angle, ~order) // analyze average - matching weights ~xformer.analyzeAverage.matchWeight

Beamforming:// Beamforming // specify parameters & design ~theta = 0.0 ~phi = 0.0 ~beamShape = \basic ~order = 3 ~xformer = HoaMatrixXformer.newBeam(~theta, ~phi, ~beamShape, ~order) // analyze average - matching weights ~xformer.analyzeAverage.matchWeight

.analyzeDirections

Return a directional analysis of modifications to the soundfield.

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 an IdentityDictionary, with the following keys:

keyword	analysis
`\amp`	pressure (virtual loudspeaker sum)
`\rms`	spherical harmonic energy
`\energy`	virtual 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 transformer performance.

Rotation:// Axial rotation // specify parameters & design ~axis = \z ~angle = pi/3 ~order = 3 ~xformer = HoaMatrixXformer.newRotateAxis(~axis, ~angle, ~order) //---- // analysis ~numTestDirections = 16 ~testDirections = Array.regularPolygon(~numTestDirections) // analyze ~analysis = ~xformer.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)

Beamforming:// Beamforming // specify parameters & design ~theta = 0.0 ~phi = 0.0 ~beamShape = \controlled ~order = 3 ~xformer = HoaMatrixXformer.newBeam(~theta, ~phi, ~beamShape, ~order) //---- // analysis ~numTestDirections = 16 ~testDirections = Array.regularPolygon(~numTestDirections) // analyze ~analysis = ~xformer.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)

Nullforming:// Nullforming // specify parameters & design ~theta = 0.0 ~phi = 0.0 ~beamShape = \controlled ~order = 3 ~xformer = HoaMatrixXformer.newNull(~theta, ~phi, ~beamShape, ~order) //---- // analysis ~numTestDirections = 16 ~testDirections = Array.regularPolygon(~numTestDirections) // analyze ~analysis = ~xformer.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

TBD

[1] - HOA transform equivalent to FoaXformerMatrix: *newMirrorO.

[2] - HOA transform equivalent to FoaXformerMatrix: *newMirrorY.

[3] - HOA transform equivalent to FoaXformerMatrix: *newMirrorX.

[4] - HOA transform equivalent to FoaXformerMatrix: *newMirrorZ.

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

HoaMatrixXformerExtension

.newBeam

Arguments:

.newNull

Arguments:

.newReflect

Arguments:

Discussion:

.newRotateAxis

Arguments:

Discussion:

.newRTT

Arguments:

.newYPR

Arguments:

.newRotate

Arguments:

.newSwapAxes

Arguments:

.newDominate

Arguments:

Discussion:

.newZoom

Arguments:

Discussion:

.newFocus

Arguments:

Discussion:

.newAsymmetry

Arguments:

Discussion:

.newBalance

Arguments:

Discussion:

.newFromMatrix

Arguments:

.analyzeAverage

Returns:

Discussion:

.analyzeDirections

Arguments:

Returns:

HoaMatrixXformer
Extension