HoaMatrixXformer | SuperCollider 3.13.0 Help

Description

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

Class Methods

HoaMatrixXformer.newBeam(theta: 0, phi: 0, beamShape: 'basic', order)

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.

HoaMatrixXformer.newNull(theta: 0, phi: 0, beamShape: 'basic', order)

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.

HoaMatrixXformer.newReflect(mirror: 'reflect', order)

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

HoaMatrixXformer.newRotateAxis(axis: 'z', angle: 0, order)

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

HoaMatrixXformer.newRTT(rotate: 0, tilt: 0, tumble: 0, order)

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.

HoaMatrixXformer.newYPR(yaw: 0, pitch: 0, roll: 0, order)

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.

HoaMatrixXformer.newRotate(r1: 0, r2: 0, r3: 0, axes: 'xyz', order)

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.

HoaMatrixXformer.newSwapAxes(axes: 'yz', order)

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.

HoaMatrixXformer.newDominate(gain: 0, theta: 0, phi: 0, order)

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.

HoaMatrixXformer.newZoom(angle: 0, theta: 0, phi: 0, order)

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.

HoaMatrixXformer.newFocus(angle: 0, theta: 0, phi: 0, order)

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.

HoaMatrixXformer.newAsymmetry(angle: 0, order)

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.

HoaMatrixXformer.newBalance(angle: 0, order)

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

HoaMatrixXformer.newFromMatrix(matrix, order)

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

Arguments:

matrix	A Matrix instance.
order	Ambisonic order.

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

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)

.type

From superclass: HoaMatrix

Ambisonic Toolkit soundfield operation designation. E.g., \encode, \xform, \decode.

.op

From superclass: AtkMatrix

Answers 'matrix', i.e. the type of operation used to compute the resulting signals.

.kind

From superclass: AtkMatrix

Answers the kind.

.dim

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

.numChannels

From superclass: HoaMatrix

Answers the number of input or output channels, depending on -type.

.directions

From superclass: HoaMatrix

Answers the directions of input or output channels, depending on -type.

.numInputs

From superclass: AtkMatrix

Number of inputs.

.dirInputs

From superclass: HoaMatrix

A convenience method providing polymorphism with -directions, depending on -type.

.numOutputs

From superclass: AtkMatrix

Number of outputs.

.dirOutputs

From superclass: HoaMatrix

A convenience method providing polymorphism with -directions, depending on -type.

Matrix

.matrix

From superclass: AtkMatrix

Returns the raw coefficient Matrix.

.thresh2(thresh)

From superclass: HoaMatrix

Bilateral thresholding in place.

Arguments:

thresh

When the input.abs < thresh, the output is forced to 0. Should be a positive value.

.asArray

From superclass: AtkMatrix

Returns the matrix as a new Array of rows.

File handling

.fileName

From superclass: AtkMatrix

Answers the name of the file used to create the instance, or nil if not created by loading a matrix from a file.

.filePath

From superclass: AtkMatrix

Answers the path of the file used to create the instance, or nil if not created by loading a matrix from a file.

.fileParse

From superclass: AtkMatrix

If the instance was created by loading a .yml file, this method returns the IdentityDictionary containing the parsed metadata. This can be useful if anything was stored in the metadata that can be subsequently used once reloaded, such as encoding directions, rotations, etc.

NOTE: For simply a quick glance at the metadata, it's recommended to use -info.

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

From superclass: AtkMatrix

Write the matrix to a file

Arguments:

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 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(directions)

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)

Inherited instance methods

Undocumented instance methods

.initBLT(angle)

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: /Library/Application Support/SuperCollider/downloaded-quarks/atk-sc3/HelpSource/Classes/HoaMatrixXformer.schelp
link::Classes/HoaMatrixXformer::

HoaMatrixXformer : HoaMatrix : AtkMatrix : Object Extension

HoaMatrixXformer.newBeam(theta: 0, phi: 0, beamShape: 'basic', order)

Arguments:

HoaMatrixXformer.newNull(theta: 0, phi: 0, beamShape: 'basic', order)

Arguments:

HoaMatrixXformer.newReflect(mirror: 'reflect', order)

Arguments:

Discussion:

HoaMatrixXformer.newRotateAxis(axis: 'z', angle: 0, order)

Arguments:

Discussion:

HoaMatrixXformer.newRTT(rotate: 0, tilt: 0, tumble: 0, order)

Arguments:

HoaMatrixXformer.newYPR(yaw: 0, pitch: 0, roll: 0, order)

Arguments:

HoaMatrixXformer.newRotate(r1: 0, r2: 0, r3: 0, axes: 'xyz', order)

Arguments:

HoaMatrixXformer.newSwapAxes(axes: 'yz', order)

Arguments:

HoaMatrixXformer.newDominate(gain: 0, theta: 0, phi: 0, order)

Arguments:

Discussion:

HoaMatrixXformer.newZoom(angle: 0, theta: 0, phi: 0, order)

Arguments:

Discussion:

HoaMatrixXformer.newFocus(angle: 0, theta: 0, phi: 0, order)

Arguments:

Discussion:

HoaMatrixXformer.newAsymmetry(angle: 0, order)

Arguments:

Discussion:

HoaMatrixXformer.newBalance(angle: 0, order)

Arguments:

Discussion:

HoaMatrixXformer.newFromMatrix(matrix, order)

Arguments:

HoaMatrixXformer.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:

.initBLT(angle)

HoaMatrixXformer : HoaMatrix : AtkMatrix : Object
Extension