FoaXformerMatrix
Extension
ExtensionDescription
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.
Class Methods
Rotations
.newRotate
Rotate around the z-axis.
Arguments:
| angle |
Rotation angle, in radians. |
Discussion:
A rotation of pi/2 will rotate a source at [0, 0] to [pi/2, 0].
.newTilt
Rotate around the x-axis.
Arguments:
| angle |
Rotation angle, in radians. |
Discussion:
A rotation of pi/2 will rotate a source at [pi/2, 0] to [0, pi/2].
.newTumble
Rotate around the y-axis.
Arguments:
| angle |
Rotation angle, in radians. |
Discussion:
A rotation of pi/2 will rotate a source at [0, 0] to [0, pi/2].
.newRTT
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.
Reflections
.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
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:
Directivity
.newDirectO
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
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
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
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
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.
Dominance
.newDominateX
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
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
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
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.
Zoom
.newZoomX
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.
.newZoomY
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.
.newZoomZ
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.
.newZoom
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.
Focus
.newFocusX
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.
.newFocusY
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.
.newFocusZ
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.
.newFocus
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.
Push
.newPushX
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.
.newPushY
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.
.newPushZ
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.
.newPush
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.
Press
.newPressX
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.
.newPressY
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.
.newPressZ
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.
.newPress
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.
Asymmetry & Balance
.newAsymmetry
Apply soundfield asymmetry
Arguments:
| angle |
The distortion angle, in radians. -pi/2 to pi/2 |
Discussion:
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.
.newBalance
Apply 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.
Matrix & File
.newFromMatrix
.newFromFile
Create an FoaXformerMatrix by loading a matrix from a file.
Arguments:
| filePathOrName |
Can be a path relative to your Otherwise a full path to your matrix file. |
Discussion:
See the Guide-to-ATK-Matrix-Files for more information.
Instance Methods
Information
.type
Returns:
'xformer'
.kind
Answers the kind of transformer.
Discussion:
.dim
Answers the number of transformer dimensions: 3D.
.numChannels
Answers the number of channels.
Discussion:
All Transformer matricies are square: 4.
.dirChannels
A convenience method providing polymorphism with FoaEncoderMatrix: -dirChannels and FoaDecoderMatrix: -dirChannels.
Returns:
[ inf, inf, inf , inf ]
.numInputs
A convenience method providing polymorphism with FoaEncoderMatrix: -numInputs and FoaDecoderMatrix: -numInputs.
.dirInputs
A convenience method providing polymorphism with FoaEncoderMatrix: -dirInputs and FoaDecoderMatrix: -dirInputs.
.numOutputs
A convenience method providing polymorphism with FoaEncoderMatrix: -numOutputs and FoaDecoderMatrix: -numOutputs.
.dirOutputs
A convenience method providing polymorphism with FoaEncoderMatrix: -dirOutputs and FoaDecoderMatrix: -dirOutputs.