SuperCollider CLASSES (extension)

# FoaXformerMatrixExtension

First Order Ambisonic (FOA) transformer matrices
Inherits from: AtkMatrix : Object

## Description

Generates transform matrices required by the Ambisonic Toolkit's first order (matrix) transformer, FoaXform.

## Class Methods

### *newRotate (angle: 0)

Rotate around the z-axis.

#### Discussion:

A rotation of pi/2 will rotate a source at `[0, 0]` to `[pi/2, 0]`.

NOTE: Corresponding UGen: FoaRotate

### *newTilt (angle: 0)

Rotate around the x-axis.

#### Discussion:

A rotation of pi/2 will rotate a source at `[pi/2, 0]` to `[0, pi/2]`.

NOTE: Corresponding UGen: FoaTilt

### *newTumble (angle: 0)

Rotate around the y-axis.

#### Discussion:

A rotation of pi/2 will rotate a source at `[0, 0]` to `[0, pi/2]`.

NOTE: Corresponding UGen: FoaTumble

### *newRTT (rotAngle: 0, tilAngle: 0, tumAngle: 0)

Rotate around the z, x and y axes.

#### Arguments:

 rotAngle Rotation angle around z-axis, in radians. tilAngle Rotation angle around x-axis, in radians. tumAngle Rotation angle around y-axis, in radians.

#### Discussion:

Rotate is followed by Tilt and then Tumble.

NOTE: Corresponding UGen: FoaRTT

### *newMirrorO

Mirror across the origin.

#### Discussion:

A source at `[pi/4, pi/6]` will be mirrored to `[-3/4*pi, -pi/6]`.

### *newMirrorX

Mirror in the x-axis (across the y-z plane).

#### Discussion:

A source at `[pi/4, pi/6]` will be mirrored to `[3/4*pi, pi/6]`.

### *newMirrorY

Mirror in the y-axis (across the x-z plane).

#### Discussion:

A source at `[pi/4, pi/6]` will be mirrored to `[-pi/4, pi/6]`.

### *newMirrorZ

Mirror in the y-axis (across the x-z plane).

#### Discussion:

A source at `[pi/4, pi/6]` will be mirrored to `[pi/4, -pi/6]`.

### *newMirror (theta: 0, phi: 0)

Mirror across an arbitrary plane.

#### Arguments:

 theta Azimuth for the normal to the plane, in radians. phi Elevation for the normal to the plane, in radians.

#### Discussion:

NOTE: Corresponding UGen: FoaMirror

### *newDirectO (angle: 0)

Adjust the soundfield directivity (across the origin).

#### Arguments:

 angle The distortion angle, in radians. 0 to pi/2

#### Discussion:

Angle = 0 retains the current directivity of the soundfield. Increasing angle towards pi/2 decreases the directivity, reducing the gains on the directional compenents to zero, and is equivalent to a spatial low-pass filter. The resulting image becomes omnidirectional or directionless.

Imaging is illustrated here.

### *newDirectX (angle: 0)

Adjust the soundfield directivity along the x-axis.

#### Arguments:

 angle The distortion angle, in radians. 0 to pi/2

#### Discussion:

Angle = 0 retains the current directivity of the soundfield. Increasing angle towards pi/2 decreases the directivity along the x-axis, reducing the gain on this axis to zero, and is equivalent to a spatial low-pass filter. The resulting image becomes directionless on the x-axis.

Imaging is illustrated here.

### *newDirectY (angle: 0)

Adjust the soundfield directivity along the y-axis.

#### Arguments:

 angle The distortion angle, in radians. 0 to pi/2

#### Discussion:

Angle = 0 retains the current directivity of the soundfield. Increasing angle towards pi/2 decreases the directivity along the y-axis, reducing the gain on this axis to zero, and is equivalent to a spatial low-pass filter. The resulting image becomes directionless on the y-axis.

Imaging is illustrated here.

### *newDirectZ (angle: 0)

Adjust the soundfield directivity along the z-axis.

#### Arguments:

 angle The distortion angle, in radians. 0 to pi/2

#### Discussion:

Angle = 0 retains the current directivity of the soundfield. Increasing angle towards pi/2 decreases the directivity along the z-axis, reducing the gain on this axis to zero, and is equivalent to a spatial low-pass filter. The resulting image becomes directionless on the z-axis.

### *newDirect (angle: 0, theta: 0, phi: 0)

Adjust the soundfield directivity across an arbitrary plane.

#### Arguments:

 angle The distortion angle, in radians. 0 to pi/2 theta Azimuth for the normal to the plane, in radians. phi Elevation for the normal to the plane, in radians.

#### Discussion:

Angle = 0 retains the current directivity of the soundfield. Increasing angle towards pi/2 decreases the directivity along the normal defined by theta and phi, reducing the gain on this normal to zero, and is equivalent to a spatial low-pass filter. The resulting image becomes directionless on the normal.

### *newDominateX (gain: 0)

Apply dominance along the x-axis.

#### Arguments:

 gain Dominance gain, in dB.

#### Discussion:

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

Imaging is illustrated here.

### *newDominateY (gain: 0)

Apply dominance along the y-axis.

#### Arguments:

 gain Dominance gain, in dB.

#### Discussion:

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

### *newDominateZ (gain: 0)

Apply dominance along the z-axis.

#### Arguments:

 gain Dominance gain, in dB.

#### Discussion:

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

### *newDominate (gain: 0, theta: 0, phi: 0)

Apply dominance along an arbitrary axis.

#### Arguments:

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

#### Discussion:

Applies dominance along the axis defined by theta and phi. See *newDominateX.

### *newZoomX (angle: 0)

Apply zoom along the x-axis.

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2

#### Discussion:

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

Imaging is illustrated here.

NOTE: Corresponding UGen: FoaZoomX

### *newZoomY (angle: 0)

Apply zoom along the y-axis.

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2

#### Discussion:

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

NOTE: Corresponding UGen: FoaZoomY

### *newZoomZ (angle: 0)

Apply zoom along the z-axis.

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2

#### Discussion:

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

NOTE: Corresponding UGen: FoaZoomZ

### *newZoom (angle: 0, theta: 0, phi: 0)

Apply zoom along an arbitrary axis.

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2 theta Azimuth, in radians. phi Elevation, in radians.

#### Discussion:

Applies zoom along the axis defined by theta and phi. See *newZoomX.

NOTE: Corresponding UGen: FoaZoom

### *newFocusX (angle: 0)

Apply focus along the x-axis.

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2

#### Discussion:

Focus is a normalised dominance variant, specified in terms of a distortion angle. Positive values of angle maintain gain at `[0, 0]`, while reducing at `[pi, 0]`. 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.

NOTE: Corresponding UGen: FoaFocusX

### *newFocusY (angle: 0)

Apply focus along the y-axis.

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2

#### Discussion:

Focus is a normalised dominance variant, specified in terms of a distortion angle. Positive values of angle maintain gain at `[pi/2, 0]`, while reducing at `[-pi/2, 0]`. 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.

NOTE: Corresponding UGen: FoaFocusY

### *newFocusZ (angle: 0)

Apply focus along the x-axis.

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2

#### Discussion:

Focus is a normalised dominance variant, specified in terms of a distortion angle. Positive values of angle maintain gain at `[0, pi/2]`, while reducing at `[0, -pi/2]`. 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.

NOTE: Corresponding UGen: FoaFocusZ

### *newFocus (angle: 0, theta: 0, phi: 0)

Apply focus along an arbitrary axis.

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2 theta Azimuth, in radians. phi Elevation, in radians.

#### Discussion:

Applies focus along the axis defined by theta and phi. See *newFocusX.

NOTE: Corresponding UGen: FoaFocus

### *newPushX (angle: 0)

Apply push along the x-axis.

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2

#### Discussion:

Push is a dominance related transform, specified in terms of a distortion angle. Positive values of angle push the image towards `[0, 0]`. Negative values push towards `[pi, 0]`. The default, 0, results in no change.

Imaging is illustrated here.

NOTE: Corresponding UGen: FoaPushX

### *newPushY (angle: 0)

Apply push along the y-axis.

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2

#### Discussion:

Push is a dominance related transform, specified in terms of a distortion angle. Positive values of angle push the image towards `[pi/2, 0]`. Negative values push towards `[-pi/2, 0]`. The default, 0, results in no change.

NOTE: Corresponding UGen: FoaPushY

### *newPushZ (angle: 0)

Apply push along the x-axis.

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2

#### Discussion:

Push is a dominance related transform, specified in terms of a distortion angle. Positive values of angle push the image towards `[0, pi/2]`. Negative values push towards `[0, -pi/2]`. The default, 0, results in no change.

NOTE: Corresponding UGen: FoaPushZ

### *newPush (angle: 0, theta: 0, phi: 0)

Apply push along an arbitrary axis.

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2 theta Azimuth, in radians. phi Elevation, in radians.

#### Discussion:

Applies push along the axis defined by theta and phi. See *PushX.

NOTE: Corresponding UGen: FoaPush

### *newPressX (angle: 0)

Apply press along the x-axis.

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2

#### Discussion:

Press is a dominance related transform, specified in terms of a distortion angle. Positive values of angle press the image towards `[0, 0]`. Negative values press towards `[pi, 0]`. The default, 0, results in no change.

Imaging is illustrated here.

NOTE: Corresponding UGen: FoaPressX

### *newPressY (angle: 0)

Apply press along the x-axis.

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2

#### Discussion:

Press is a dominance related transform, specified in terms of a distortion angle. Positive values of angle press the image towards `[pi/2, 0]`. Negative values press towards `[-pi/2, 0]`. The default, 0, results in no change.

NOTE: Corresponding UGen: FoaPressY

### *newPressZ (angle: 0)

Apply press along the z-axis.

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2

#### Discussion:

Press is a dominance related transform, specified in terms of a distortion angle. Positive values of angle press the image towards `[0, pi/2]`. Negative values press towards `[0, -pi/2]`. The default, 0, results in no change.

Imaging is illustrated here.

NOTE: Corresponding UGen: FoaPressZ

### *newPress (angle: 0, theta: 0, phi: 0)

Apply press along an arbitrary axis.

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2 theta Azimuth, in radians. phi Elevation, in radians.

#### Discussion:

Applies press along the axis defined by theta and phi. See *PressX.

NOTE: Corresponding UGen: FoaPress

### *newAsymmetry (angle: 0)

Apply soundfield asymmetry

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2

#### Discussion:

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

Imaging is illustrated here.

NOTE: Corresponding UGen: FoaAsymmetry

### *newBalance (angle: 0)

Soundfield balance. A synonym for ZoomY

#### Arguments:

 angle The distortion angle, in radians. -pi/2 to pi/2

#### Discussion:

See ZoomY.

Imaging is illustrated here.

NOTE: Corresponding UGen: FoaBalance

### *newFromFile (filePathOrName)

#### Arguments:

 filePathOrName Can be a path relative to your `/extensions/matrices/xformers` folder:`Atk.getMatrixExtensionPath('xformers').fullPath` Otherwise a full path to your matrix file.

### *newFromMatrix (aMatrix, set, type)

From superclass: AtkMatrix

Create an instance from a raw 2D Matrix.

#### Arguments:

 aMatrix A Matrix in the form of`Matrix.with([[row1],[row2],...[rowN]])` set `'FOA', 'HOA1', 'HOA2', ... etc`. Set describes both the signal set and the tool set, encompassing the Ambisonic order, as well as channel ordering and normalisation. type `'decoder', 'encoder', or 'xformer'`.NOTE: set and type will be required if the `AtkMatrix` will subsequently be written to a file.

## Instance Methods

### -set

From superclass: AtkMatrix

Describes both the signal set and the tool set, encompassing the Ambisonic order, as well as channel ordering and normalisation.

Answers `'FOA'`, aka traditional B-format:
 Ambisonic Order Channel Ordering Channel Normalisation 1st Gerzon (aka Furse-Malham) MaxN

### -type

#### Returns:

`'xformer'`

### -op

From superclass: AtkMatrix

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

### -kind

From superclass: AtkMatrix

#### Discussion:

```// encoder
~xformer = FoaXformerMatrix.newZoomX

// inspect
~encoder.kind```

### -dim

Answers the number of transformer dimensions: 3D.

### -numChannels

#### Discussion:

All Transformer matricies are square: 4.

### -dirChannels

A convenience method providing polymorphism with FoaEncoderMatrix: -dirChannels and FoaDecoderMatrix: -dirChannels.

#### Returns:

`[ inf, inf, inf , inf ]`

### -matrix

From superclass: AtkMatrix

### -numOutputs

A convenience method providing polymorphism with FoaEncoderMatrix: -numOutputs and FoaDecoderMatrix: -numOutputs.

### -dirOutputs

A convenience method providing polymorphism with FoaEncoderMatrix: -dirOutputs and FoaDecoderMatrix: -dirOutputs.

### -numInputs

A convenience method providing polymorphism with FoaEncoderMatrix: -numInputs and FoaDecoderMatrix: -numInputs.

### -dirInputs

A convenience method providing polymorphism with FoaEncoderMatrix: -dirInputs and FoaDecoderMatrix: -dirInputs.

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

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

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

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

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