TITLE:: AtkMatrix
summary:: A superclass to the Atk's various matrix classes.
categories:: Libraries>Ambisonic Toolkit>Matrix & Kernel>Internals
related:: Classes/FoaEncoderMatrix, Classes/FoaDecoderMatrix, Classes/FoaXformerMatrix, Classes/HoaMatrixEncoder, Classes/HoaMatrixDecoder, Classes/HoaMatrixXformer, Classes/Matrix, Guides/Guide-to-ATK-Matrix-Files

DESCRIPTION::
An AtkMatrix is not typically instantiated directly, but rather through one of its subclasses:
link::Classes/FoaEncoderMatrix::,  link::Classes/FoaDecoderMatrix::, link::Classes/FoaXformerMatrix::, link::Classes/HoaMatrixEncoder::,  link::Classes/HoaMatrixDecoder::, and link::Classes/HoaMatrixXformer::.


CLASSMETHODS::

METHOD:: new
code::*new:: should not be called directly from AtkMatrix but rather is called from the various creation methods of its subclasses:
link::Classes/FoaEncoderMatrix::, link::Classes/FoaDecoderMatrix::, link::Classes/FoaXformerMatrix::, link::Classes/HoaMatrixEncoder::,  link::Classes/HoaMatrixDecoder::, or link::Classes/HoaMatrixXformer::.


INSTANCEMETHODS::

PRIVATE:: set, type, kind, prWriteMatrixToMOSL, prWriteMatrixToTXT, prWriteToFile

SUBSECTION:: Information

METHOD:: info
A convenience method to post the properties of the matrix, including metadata
if the matrix was loaded from a code::.yml:: file.

METHOD:: order
Ambisonic order.

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

METHOD:: kind
Answers the kind.

METHOD:: numInputs
Number of inputs.

METHOD:: numOutputs
Number of outputs.


SUBSECTION:: Matrix

METHOD:: matrix
Returns the raw coefficient Matrix.

METHOD:: asArray
Returns the matrix as a new link::Classes/Array:: of rows.



SUBSECTION:: File handling

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

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

METHOD:: fileParse
If the instance was created by loading a code::.yml:: file, this method returns
the link::Classes/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 link::#-info::.::

METHOD:: writeToFile
Write the matrix to a file

ARGUMENT:: fileNameOrPath
A String of the file name. The file extension determines the format:
list::
## code::.yml:: allows for additional user-specified metadata (recommended).
## code::.txt:: writes the matrix coefficients only, in rows.
## code::.mosl.txt:: creates basic matrix files compatible with the link::http://www.ambisonictoolkit.net/download/reaper/##ATK for Reaper::, a set of link::http://www.reaper.fm/sdk/js/js.php##JSFX plugins:: for the link::http://www.reaper.fm/##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 code::extensions:: folder. See the
Discussion below for more information.

ARGUMENT:: note
A String that is a short description or bit of info about the matrix to store for future reference.

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

ARGUMENT:: overwrite
A boolean specifying whether you'd like to force overwriting an existing file of the same name and extension.

DISCUSSION::

The link::Guides/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.
