FoaXformerMatrix:

Filter: - Description
- Class methods
- Rotations
- Reflections
- Directivity
- Dominance
- Zoom
- Focus
- Push
- Press
- Asymmetry & Balance
- Matrix & File
- Inherited class methods
- Instance methods
- Information
- info
- order
- set
- type
- op
- kind
- dim
- numChannels
- dirChannels
- directions
- numInputs
- dirInputs
- numOutputs
- dirOutputs
- Matrix
- File handling
- Inherited instance methods
- Examples

Classes (extension)
| Libraries > Ambisonic Toolkit > Matrix & Kernel > FOA

Extension

First Order Ambisonic (FOA) transformer matrices

Source: FoaMatrix.sc

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

You may wish to explore the visualizations of the available transforms via FoaXformDisplay.

NOTE: The ATK matrices are required for using some of the matrix transformers. Please see Atk: Installation of ATK dependencies for instructions.

Rotate around the z-axis.

angle |
Rotation angle, in radians. |

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

to `[pi/2, 0]`

.

NOTE: Corresponding UGen: FoaRotate

Rotate around the x-axis.

angle |
Rotation angle, in radians. |

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

to `[0, pi/2]`

.

NOTE: Corresponding UGen: FoaTilt

Rotate around the y-axis.

angle |
Rotation angle, in radians. |

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

to `[0, pi/2]`

.

NOTE: Corresponding UGen: FoaTumble

Rotate around the z, x and y axes.

rotAngle |
Rotation angle around z-axis, in radians. |

tilAngle |
Rotation angle around x-axis, in radians. |

tumAngle |
Rotation angle around y-axis, in radians. |

Rotate is followed by Tilt and then Tumble.

NOTE: Corresponding UGen: FoaRTT

Mirror across the origin.

A source at `[pi/4, pi/6]`

will be mirrored to `[-3/4*pi, -pi/6]`

.

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

A source at `[pi/4, pi/6]`

will be mirrored to `[3/4*pi, pi/6]`

.

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

A source at `[pi/4, pi/6]`

will be mirrored to `[-pi/4, pi/6]`

.

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

A source at `[pi/4, pi/6]`

will be mirrored to `[pi/4, -pi/6]`

.

Mirror across an arbitrary plane.

theta |
Azimuth for the normal to the plane, in radians. |

phi |
Elevation for the normal to the plane, in radians. |

NOTE: Corresponding UGen: FoaMirror

Adjust the soundfield directivity (across the origin).

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

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

NOTE: Corresponding UGen: FoaDirectO

Adjust the soundfield directivity along the x-axis.

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

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

NOTE: Corresponding UGen: FoaDirectX

Adjust the soundfield directivity along the y-axis.

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

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

NOTE: Corresponding UGen: FoaDirectY

Adjust the soundfield directivity along the z-axis.

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

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

NOTE: Corresponding UGen: FoaDirectZ

Adjust the soundfield directivity across an arbitrary plane.

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

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

NOTE: Corresponding UGen: FoaDirect

Apply dominance along the x-axis.

gain |
Dominance gain, in dB. |

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.

NOTE: Corresponding UGen: FoaDominateX

Apply dominance along the y-axis.

gain |
Dominance gain, in dB. |

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.

NOTE: Corresponding UGen: FoaDominateY

Apply dominance along the z-axis.

gain |
Dominance gain, in dB. |

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.

NOTE: Corresponding UGen: FoaDominateZ

Apply dominance along an arbitrary axis.

gain |
Dominance gain, in dB. |

theta |
Azimuth, in radians. |

phi |
Elevation, in radians. |

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

NOTE: Corresponding UGen: FoaDominate

Apply zoom along the x-axis.

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

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

Apply zoom along the y-axis.

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

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

Apply zoom along the z-axis.

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

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

Apply zoom along an arbitrary axis.

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

theta |
Azimuth, in radians. |

phi |
Elevation, in radians. |

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

NOTE: Corresponding UGen: FoaZoom

Apply focus along the x-axis.

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

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

Apply focus along the y-axis.

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

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

Apply focus along the x-axis.

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

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

Apply focus along an arbitrary axis.

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

theta |
Azimuth, in radians. |

phi |
Elevation, in radians. |

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

NOTE: Corresponding UGen: FoaFocus

Apply push along the x-axis.

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

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

Apply push along the y-axis.

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

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

Apply push along the x-axis.

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

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

Apply push along an arbitrary axis.

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

theta |
Azimuth, in radians. |

phi |
Elevation, in radians. |

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

NOTE: Corresponding UGen: FoaPush

Apply press along the x-axis.

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

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

Apply press along the x-axis.

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

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

Apply press along the z-axis.

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

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

Apply press along an arbitrary axis.

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

theta |
Azimuth, in radians. |

phi |
Elevation, in radians. |

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

NOTE: Corresponding UGen: FoaPress

Apply soundfield asymmetry

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

Positive values of **angle** rotate `[-pi/2, 0]`

towards `[0, 0]`

, and at pi/2 collapse the soundfield to a planewave. Negative values rotate `[pi/2, 0]`

toowards `[0, 0]`

. The default, 0, results in no change.

Imaging is illustrated here.

NOTE: Corresponding UGen: FoaAsymmetry

Apply soundfield balance. A synonym for ZoomY

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

See ZoomY.

Imaging is illustrated here.

NOTE: Corresponding UGen: FoaBalance

Create an FoaXformerMatrix by loading a matrix from a file.

filePathOrName |
Can be a path relative to your Otherwise a full path to your matrix file. |

See the Guide to ATK Matrix Files for more information.

From superclass: AtkMatrix

A convenience method to post the properties of the matrix, including metadata if the matrix was loaded from a `.yml`

file.

From superclass: AtkMatrix

Ambisonic order.

From superclass: FoaMatrix

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`

.

Answers, `\FOA`

, aka traditional B-format:

Ambisonic Order | Component Ordering | Component Normalisation |

1st | Furse-Malham (FuMa) | Gerzon / Furse-Malham (MaxN) |

From superclass: FoaMatrix

`'xformer'`

From superclass: AtkMatrix

Answers `'matrix'`

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

From superclass: AtkMatrix

Answers the kind of transformer.

From superclass: FoaMatrix

Answers the number of transformer dimensions: 3D.

From superclass: FoaMatrix

Answers the number of channels.

All Transformer matricies are square: 4.

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

`[ inf, inf, inf , inf ]`

From superclass: FoaMatrix

A synonym for -dirChannels

From superclass: AtkMatrix

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

From superclass: FoaMatrix

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

From superclass: AtkMatrix

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

From superclass: FoaMatrix

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

From superclass: AtkMatrix

Returns the raw coefficient Matrix.

From superclass: AtkMatrix

Returns the matrix as a new Array of rows.

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.

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.

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.

From superclass: AtkMatrix

Write the matrix to a file

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 |

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

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.

helpfile source: /Library/Application Support/SuperCollider/downloaded-quarks/atk-sc3/HelpSource/Classes/FoaXformerMatrix.schelp

link::Classes/FoaXformerMatrix::

link::Classes/FoaXformerMatrix::