CLASS:: FoaXformerMatrix summary:: First Order Ambisonic (FOA) transformer matrices categories:: Libraries>Ambisonic Toolkit>Matrix & Kernel>FOA related:: Classes/FoaXform DESCRIPTION:: Generates transform matrices required by the Ambisonic Toolkit's first order (matrix) transformer, link::Classes/FoaXform::. You may wish to explore the visualizations of the available transforms via link::Classes/FoaXformDisplay::. note:: The ATK matrices are required for using some of the matrix transformers. Please see link::Classes/Atk#Installation of ATK dependencies:: for instructions.:: CLASSMETHODS:: SUBSECTION:: Rotations METHOD:: newRotate Rotate around the z-axis. argument:: angle Rotation angle, in radians. discussion:: A rotation of pi/2 will rotate a source at code:: [0, 0] :: to code:: [pi/2, 0] ::. note:: Corresponding UGen: link::Classes/FoaRotate:: :: METHOD:: newTilt Rotate around the x-axis. argument:: angle Rotation angle, in radians. discussion:: A rotation of pi/2 will rotate a source at code:: [pi/2, 0] :: to code:: [0, pi/2] ::. note:: Corresponding UGen: link::Classes/FoaTilt:: :: METHOD:: newTumble Rotate around the y-axis. argument:: angle Rotation angle, in radians. discussion:: A rotation of pi/2 will rotate a source at code:: [0, 0] :: to code:: [0, pi/2] ::. note:: Corresponding UGen: link::Classes/FoaTumble:: :: METHOD:: newRTT Rotate around the z, x and y axes. argument:: rotAngle Rotation angle around z-axis, in radians. argument:: tilAngle Rotation angle around x-axis, in radians. argument:: tumAngle Rotation angle around y-axis, in radians. discussion:: link::#*newRotate#Rotate:: is followed by link::#*newTilt#Tilt:: and then link::#*newTumble#Tumble::. note:: Corresponding UGen: link::Classes/FoaRTT:: :: SUBSECTION:: Reflections METHOD:: newMirrorO Mirror across the origin. discussion:: A source at code:: [pi/4, pi/6] :: will be mirrored to code:: [-3/4*pi, -pi/6] ::. METHOD:: newMirrorX Mirror in the x-axis (across the y-z plane). discussion:: A source at code:: [pi/4, pi/6] :: will be mirrored to code:: [3/4*pi, pi/6] ::. METHOD:: newMirrorY Mirror in the y-axis (across the x-z plane). discussion:: A source at code:: [pi/4, pi/6] :: will be mirrored to code:: [-pi/4, pi/6] ::. METHOD:: newMirrorZ Mirror in the y-axis (across the x-z plane). discussion:: A source at code:: [pi/4, pi/6] :: will be mirrored to code:: [pi/4, -pi/6] ::. METHOD:: newMirror Mirror across an arbitrary plane. argument:: theta Azimuth for the normal to the plane, in radians. argument:: phi Elevation for the normal to the plane, in radians. discussion:: note:: Corresponding UGen: link::Classes/FoaMirror:: :: SUBSECTION:: Directivity METHOD:: newDirectO Adjust the soundfield directivity (across the origin). argument:: angle The distortion angle, in radians. 0 to pi/2 discussion:: strong::Angle:: = 0 retains the current directivity of the soundfield. Increasing strong::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 link::Classes/FoaDirectO#figure#here::. note:: Corresponding UGen: link::Classes/FoaDirectO:: :: METHOD:: newDirectX Adjust the soundfield directivity along the x-axis. argument:: angle The distortion angle, in radians. 0 to pi/2 discussion:: strong::Angle:: = 0 retains the current directivity of the soundfield. Increasing strong::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 link::Classes/FoaDirectX#figure#here::. note:: Corresponding UGen: link::Classes/FoaDirectX:: :: METHOD:: newDirectY Adjust the soundfield directivity along the y-axis. argument:: angle The distortion angle, in radians. 0 to pi/2 discussion:: strong::Angle:: = 0 retains the current directivity of the soundfield. Increasing strong::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 link::Classes/FoaDirectY#figure#here::. note:: Corresponding UGen: link::Classes/FoaDirectY:: :: METHOD:: newDirectZ Adjust the soundfield directivity along the z-axis. argument:: angle The distortion angle, in radians. 0 to pi/2 discussion:: strong::Angle:: = 0 retains the current directivity of the soundfield. Increasing strong::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: link::Classes/FoaDirectZ:: :: METHOD:: newDirect Adjust the soundfield directivity across an arbitrary plane. argument:: angle The distortion angle, in radians. 0 to pi/2 argument:: theta Azimuth for the normal to the plane, in radians. argument:: phi Elevation for the normal to the plane, in radians. discussion:: strong::Angle:: = 0 retains the current directivity of the soundfield. Increasing strong::angle:: towards pi/2 decreases the directivity along the normal defined by strong::theta:: and strong::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: link::Classes/FoaDirect:: :: SUBSECTION:: Dominance METHOD:: newDominateX Apply dominance along the x-axis. argument:: gain Dominance gain, in dB. discussion:: Positive values of strong::gain:: increase the gain at code:: [0, 0] :: to strong::+gain:: dB, while decreasing the gain at code:: [pi, 0] :: to strong::-gain::. This simultaneously results in a distortion of the image towards code:: [0, 0] ::. Negative values of gain invert this distortion, distorting towards code:: [pi, 0] :: . The default, 0, results in no change. Imaging is illustrated link::Classes/FoaDominateX#figure#here::. note:: Corresponding UGen: link::Classes/FoaDominateX:: :: METHOD:: newDominateY Apply dominance along the y-axis. argument:: gain Dominance gain, in dB. discussion:: Positive values of strong::gain:: increase the gain at code:: [pi/2, 0] :: to strong::+gain:: dB, while decreasing the gain at code:: [-pi/2, 0] :: to strong::-gain::. This simultaneously results in a distortion of the image towards code:: [pi/2, 0] ::. Negative values of gain invert this distortion, distorting towards code:: [-pi/2, 0] :: . The default, 0, results in no change. note:: Corresponding UGen: link::Classes/FoaDominateY:: :: METHOD:: newDominateZ Apply dominance along the z-axis. argument:: gain Dominance gain, in dB. discussion:: Positive values of strong::gain:: increase the gain at code:: [0, pi/2] :: to strong::+gain:: dB, while decreasing the gain at code:: [0, -pi/2] :: to strong::-gain::. This simultaneously results in a distortion of the image towards code:: [0, pi/2] ::. Negative values of gain invert this distortion, distorting towards code:: [0, -pi/2] :: . The default, 0, results in no change. note:: Corresponding UGen: link::Classes/FoaDominateZ:: :: METHOD:: newDominate Apply dominance along an arbitrary axis. argument:: gain Dominance gain, in dB. argument:: theta Azimuth, in radians. argument:: phi Elevation, in radians. discussion:: Applies dominance along the axis defined by strong::theta:: and strong::phi::. See link::#*newDominateX::. note:: Corresponding UGen: link::Classes/FoaDominate:: :: SUBSECTION:: Zoom METHOD:: newZoomX Apply zoom along the x-axis. argument:: 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 strong::angle:: increase gain at code:: [0, 0] ::, while reducing at code:: [pi, 0] ::. Negative values do the inverse. The default, 0, results in no change. Imaging is illustrated link::Classes/FoaZoomX#figure#here::. note:: Corresponding UGen: link::Classes/FoaZoomX:: :: METHOD:: newZoomY Apply zoom along the y-axis. argument:: 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 strong::angle:: increase gain at code:: [pi/2, 0] ::, while reducing at code:: [-pi/2, 0] ::. Negative values do the inverse. The default, 0, results in no change. Imaging is illustrated link::Classes/FoaZoomY#figure#here::. note:: Corresponding UGen: link::Classes/FoaZoomY:: :: METHOD:: newZoomZ Apply zoom along the z-axis. argument:: 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 strong::angle:: increase gain at code:: [0, pi/2] ::, while reducing at code:: [0, -pi/2] ::. Negative values do the inverse. The default, 0, results in no change. note:: Corresponding UGen: link::Classes/FoaZoomZ:: :: METHOD:: newZoom Apply zoom along an arbitrary axis. argument:: angle The distortion angle, in radians. -pi/2 to pi/2 argument:: theta Azimuth, in radians. argument:: phi Elevation, in radians. discussion:: Applies zoom along the axis defined by strong::theta:: and strong::phi::. See link::#*newZoomX::. note:: Corresponding UGen: link::Classes/FoaZoom:: :: SUBSECTION:: Focus METHOD:: newFocusX Apply focus along the x-axis. argument:: 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 strong::angle:: maintain gain at code:: [0, 0] ::, while reducing at code:: [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 link::Classes/FoaFocusX#figure#here::. note:: Corresponding UGen: link::Classes/FoaFocusX:: :: METHOD:: newFocusY Apply focus along the y-axis. argument:: 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 strong::angle:: maintain gain at code:: [pi/2, 0] ::, while reducing at code:: [-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: link::Classes/FoaFocusY:: :: METHOD:: newFocusZ Apply focus along the x-axis. argument:: 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 strong::angle:: maintain gain at code:: [0, pi/2] ::, while reducing at code:: [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: link::Classes/FoaFocusZ:: :: METHOD:: newFocus Apply focus along an arbitrary axis. argument:: angle The distortion angle, in radians. -pi/2 to pi/2 argument:: theta Azimuth, in radians. argument:: phi Elevation, in radians. discussion:: Applies focus along the axis defined by strong::theta:: and strong::phi::. See link::#*newFocusX::. note:: Corresponding UGen: link::Classes/FoaFocus:: :: SUBSECTION:: Push METHOD:: newPushX Apply push along the x-axis. argument:: 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 strong::angle:: push the image towards code:: [0, 0] ::. Negative values push towards code:: [pi, 0] ::. The default, 0, results in no change. Imaging is illustrated link::Classes/FoaPushX#figure#here::. note:: Corresponding UGen: link::Classes/FoaPushX:: :: METHOD:: newPushY Apply push along the y-axis. argument:: 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 strong::angle:: push the image towards code:: [pi/2, 0] ::. Negative values push towards code:: [-pi/2, 0] ::. The default, 0, results in no change. note:: Corresponding UGen: link::Classes/FoaPushY:: :: METHOD:: newPushZ Apply push along the x-axis. argument:: 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 strong::angle:: push the image towards code:: [0, pi/2] ::. Negative values push towards code:: [0, -pi/2] ::. The default, 0, results in no change. note:: Corresponding UGen: link::Classes/FoaPushZ:: :: METHOD:: newPush Apply push along an arbitrary axis. argument:: angle The distortion angle, in radians. -pi/2 to pi/2 argument:: theta Azimuth, in radians. argument:: phi Elevation, in radians. discussion:: Applies push along the axis defined by strong::theta:: and strong::phi::. See link::#*PushX::. note:: Corresponding UGen: link::Classes/FoaPush:: :: SUBSECTION:: Press METHOD:: newPressX Apply press along the x-axis. argument:: 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 strong::angle:: press the image towards code:: [0, 0] ::. Negative values press towards code:: [pi, 0] ::. The default, 0, results in no change. Imaging is illustrated link::Classes/FoaPressX#figure#here::. note:: Corresponding UGen: link::Classes/FoaPressX:: :: METHOD:: newPressY Apply press along the x-axis. argument:: 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 strong::angle:: press the image towards code:: [pi/2, 0] ::. Negative values press towards code:: [-pi/2, 0] ::. The default, 0, results in no change. note:: Corresponding UGen: link::Classes/FoaPressY:: :: METHOD:: newPressZ Apply press along the z-axis. argument:: 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 strong::angle:: press the image towards code:: [0, pi/2] ::. Negative values press towards code:: [0, -pi/2] ::. The default, 0, results in no change. Imaging is illustrated link::Classes/FoaPressZ##here::. note:: Corresponding UGen: link::Classes/FoaPressZ:: :: METHOD:: newPress Apply press along an arbitrary axis. argument:: angle The distortion angle, in radians. -pi/2 to pi/2 argument:: theta Azimuth, in radians. argument:: phi Elevation, in radians. discussion:: Applies press along the axis defined by strong::theta:: and strong::phi::. See link::#*PressX::. note:: Corresponding UGen: link::Classes/FoaPress:: :: SUBSECTION:: Asymmetry & Balance METHOD:: newAsymmetry Apply soundfield asymmetry argument:: angle The distortion angle, in radians. -pi/2 to pi/2 discussion:: Positive values of strong::angle:: rotate code:: [-pi/2, 0] :: towards code:: [0, 0] ::, and at pi/2 collapse the soundfield to a planewave. Negative values rotate code:: [pi/2, 0] :: toowards code:: [0, 0] ::. The default, 0, results in no change. Imaging is illustrated link::Classes/FoaAsymmetry#figure#here::. note:: Corresponding UGen: link::Classes/FoaAsymmetry:: :: METHOD:: newBalance Apply soundfield balance. A synonym for link::#*newZoomY#ZoomY:: argument:: angle The distortion angle, in radians. -pi/2 to pi/2 discussion:: See link::#*newZoomY#ZoomY::. Imaging is illustrated link::Classes/FoaBalance#figure#here::. note:: Corresponding UGen: link::Classes/FoaBalance:: :: SUBSECTION:: Matrix & File METHOD:: newFromMatrix Create an instance from a raw 2D link::Classes/Matrix::. ARGUMENT:: matrix A link::Classes/Matrix:: in the form of code:: Matrix.with([[row1],[row2],...[rowN]]) :: METHOD:: newFromFile Create an FoaXformerMatrix by loading a matrix from a file. argument:: filePathOrName Can be a path relative to your code::/extensions/matrices/FOA/xformers:: folder: code:: Atk.getMatrixExtensionSubPath(\FOA, \xformers).fullPath :: Otherwise a full path to your matrix file. discussion:: See the link::Guides/Guide-to-ATK-Matrix-Files:: for more information. INSTANCEMETHODS:: private:: initMirrorChan, initMirrorX, initMirrorY, initMirrorZ, initMirrorO, initRotate, initTilt, initTumble, initDirectO, initDirectX, initDirectY, initDirectZ, initDominateX, initDominateY, initDominateZ, initZoomX, initZoomY, initZoomZ, initFocusX, initFocusY, initFocusZ, initPushX, initPushY, initPushZ, initPressX, initPressY, initPressZ, initAsymmetry, initRTT, initMirror, initDirect, initDominate, initZoom, initFocus, initPush, initPress, printOn SUBSECTION:: Information COPYMETHOD:: FoaMatrix, -info COPYMETHOD:: FoaMatrix, -order COPYMETHOD:: FoaMatrix, -set METHOD:: type returns:: code::'xformer':: COPYMETHOD:: AtkMatrix, -op METHOD:: kind Answers the kind of transformer. discussion:: code:: // xformer ~xformer = FoaXformerMatrix.newZoomX // inspect ~encoder.kind :: METHOD:: dim Answers the number of transformer dimensions: 3D. METHOD:: numChannels Answers the number of channels. discussion:: All Transformer matricies are square: 4. METHOD:: dirChannels A convenience method providing polymorphism with link::Classes/FoaEncoderMatrix#-dirChannels:: and link::Classes/FoaDecoderMatrix#-dirChannels::. returns:: code:: [ inf, inf, inf , inf ] :: COPYMETHOD:: FoaMatrix, -directions METHOD:: numInputs A convenience method providing polymorphism with link::Classes/FoaEncoderMatrix#-numInputs:: and link::Classes/FoaDecoderMatrix#-numInputs::. METHOD:: dirInputs A convenience method providing polymorphism with link::Classes/FoaEncoderMatrix#-dirInputs:: and link::Classes/FoaDecoderMatrix#-dirInputs::. METHOD:: numOutputs A convenience method providing polymorphism with link::Classes/FoaEncoderMatrix#-numOutputs:: and link::Classes/FoaDecoderMatrix#-numOutputs::. METHOD:: dirOutputs A convenience method providing polymorphism with link::Classes/FoaEncoderMatrix#-dirOutputs:: and link::Classes/FoaDecoderMatrix#-dirOutputs::. SUBSECTION:: Matrix COPYMETHOD:: AtkMatrix, -matrix COPYMETHOD:: AtkMatrix, -asArray SUBSECTION:: File handling COPYMETHOD:: AtkMatrix, -fileName COPYMETHOD:: AtkMatrix, -filePath COPYMETHOD:: AtkMatrix, -fileParse COPYMETHOD:: AtkMatrix, -writeToFile EXAMPLES:: link::Guides/Transforming-FOA::