Guide to ATK Matrix Files

Extension

Directory Structure

The ATK store assets in its Application Support directory:Atk.userSupportDir

This includes three default directories:

• kernels (FIR filters for kernel en/decoders),
• sounds (example sound files in A-format, B-format, &c.),
• matrices (for encoding, decoding, xforming).

These folders store the files shipped with the ATK. We can also optionally add our own extensions folder, in which we can store kernels and matrices of our own design. Note this is different from SuperCollider's Extensions folder. If we haven't yet added an extensions directory, we can see where to put it by executing the following method:Atk.userExtensionsDir // view it Atk.userExtensionsDir.openOS // open it... if it exists!

There's a handy method that will build it for we in the expected structure:Atk.createExtensionsDir

This will create a directory structure that lives in our next to our default ATK assets. Note this creates both a matrices folder structure, and an identical kernels folder structure for storing our custom kernels. The full structure will look like this:

• Application Support
  • ATK
    • kernels (ATK default)
    • matrices (ATK default)
    • sounds (ATK default)
    • extensions (our custom additions)
      • kernels
      • matrices
        • FOA
          • decoders
            • myDecoderMatrix.txt
            • myDecoderMatrixForReaper.mosl.txt
            • myDecoderMatrixWithMetadata.yml

          • encoders
          • xformers

        • HOA1
        • HOA2
        • ...
        • HOAN

Each of the folders (FOA>encoders, HOA5>decoders, etc.) are empty and ready to store matrices (and kernels) for use with the ATK-SC3 (this package) and ATK-Reaper (more on that later). When we write a matrix using the ATK, it will store it in this directory structure by default, and will look here by default when asked to read in a matrix from file.

We can view this structure and any files you've stored there using the following method:Atk.postMyMatrices(); // All sets, all matrices types Atk.postMyMatrices('FOA'); // FOA matrices hierarchy Atk.postMyMatrices('FOA', 'encoders'); // FOA encoders only Atk.postMyMatrices('FOA', 'decoders'); // FOA decoders only Atk.postMyMatrices('FOA', 'xformers'); // FOA xformers only

Each of these matrix subdirectories can have further subdirectories at your discretion, e.g. for particular projects or categories of matrices.

Writing Matrices

We'll start by writing a matrix file.

Let's create a first order A-format encoding matrix from a nine-point spherical t-design. For our purposes, we'll use a spherical designs with d = 2, giving a collection of uniformly distributed points on a sphere. The t-design we're using below can be found in Hardin and Sloan's Library of 3-D Designs. ¹ ( // Spherical coordinates of the nine-point t-design. ~directions = [ [ 0, 45 ], [ 120, 45 ], [ -120, 45 ], [ 0, 0 ], [ 120, 0 ], [ -120, 0 ], [ 0, -45 ], [ 120, -45 ], [ -120, -45 ] ].degrad; // Here's our 9-point A-format to B-format (planewave, aka velocity) encoder: ~encoder = FoaEncoderMatrix.newDirections(~directions); )

This FoaEncoderMatrix is now ready to be used for encoding planewaves arriving from those nine uniformly distributed incidences. Within the ATK's classification hierarchy, ~encoder looks like this:

For fun, let's inspect:( var methodsToInspect = ['class', 'set', 'type', 'op', 'kind' ]; methodsToInspect.do({arg item; (item.asString ++ " : " ++ ~encoder.perform(item)).postln;}) )

After all that hard work (thanks ATK!), we want to store the result to a file for use in the future, and to use in ATK-Reaper plugins! ²

There are three available file formats, each with a special purpose:

• .txt : the most basic text file, writing the raw matrix only.
• .yml : store the matrix along with metadata in a human readable format.
• .mosl.txt : a text file formatted for use with ATK-Reaper JSFX-plugins.

Let's write this encoder matrix out in all three formats:// .txt extension writes the matrix only ~encoder.writeToFile("my9PointEncoder.txt"); // .yml writes metadata as well ~encoder.writeToFile("my9PointEncoder.yml"); // .mosl.txt writes matrix only, single lines for Reaper to read ~encoder.writeToFile("my9PointEncoder.mosl.txt");

Because we only specified a file name, not a full path, the ATK will store the matrix in the default location. As we're writing an FoaEncoderMatrix, ATK can infer that it's an encoder in the FOA set. (We also know, we're dealing with a matrix operation.) Therefore, the ATK knows to put it in: ../extensions/matrices/FOA/encoders.

Had we specified a full path instead, it would have saved to that location.// Here are our encoders (defaults to showing the FOA set) Atk.postMyMatrices('FOA', 'encoders');

Writing Metadata

Because this matrix encoder is somewhat unique, it would be helpful to provide a bit more information about it for future reference. This is where the .yml file format comes in.

Note that the AtkMatrix: -writeToFile method has some optional arguments: note and attributeDictionary. A note can be a brief description, while an attributeDictionary is a Dictionary for storing any info you'd like in the form of key:value pairs. Information found in the attributeDictionary can be retrieved via AtkMatrix: -fileParse. An example of this is illustrated below.( // A 'note': a description or note about the matrix. ~note = "This is a nine-point t-design encoder made for a matrix file writing demo."; // A Dictionary of more metadata to add. ~properties = ( author: "Me, the Reader", dateCreated: Date.getDate.stamp, ordering: AtkFoa.ordering, // Furse-Malham (FuMa) normalisation: AtkFoa.normalisation, // Gerzon / Furse-Malham (MaxN) ); )

Now write this matrix and metadata to file... Be sure to specify the .yml extension in order to write the metadata. Set overwrite = true to force overwrite the file we wrote before with the same name and extension.( ~encoder.writeToFile( "my9PointEncoder.yml", note: ~note, attributeDictionary: ~properties, overwrite: true ) )

Writing Raw Matrices

In the above examples, we've been reading/writing matrices encapsulated in the AtkMatrix subclasses. When writing from these objects, some the information can be inferred from them, such as the set (Ambisonic order, channel ordering, channel normalisation, e.g. 'FOA', 'HOA3', etc.) and type of matrix (e.g. 'encoder', 'decoder', 'xformer'). In the case of a raw matrix, the appropriate subclass must be called explicitly.( // Here's a raw (FOA) A-to-B encoder matrix: ~matrix = Matrix.with([ [ 0.61237243569579, 0.61237243569579, 0.61237243569579, 0.61237243569579 ], [ 0.5, 0.5, -0.5, -0.5 ], [ 0.5, -0.5, 0.5, -0.5 ], [ 0.5, -0.5, -0.5, 0.5 ] ]); // along with associated encoding directions ~aToBdirections = [ [ 0.78539816339745, 0.61547970867039 ], [ -0.78539816339745, -0.61547970867039 ], [ 2.3561944901923, -0.61547970867039 ], [ -2.3561944901923, 0.61547970867039 ] ]; )

Metadata is useful to record more information about the matrix:( ~note = "A 4-channel A-to-B encoder matrix, in Front-Left-Up orientation."; // A Dictionary of more metadata to add. ~properties = ( author: "Me, the Reader", dateCreated: Date.getDate.stamp, ordering: AtkFoa.ordering, // Furse-Malham (FuMa) normalisation: AtkFoa.normalisation, // Gerzon / Furse-Malham (MaxN) ); )

Now, given the matrix, a subclass instance can be created using the *newFromMatrix class method. In this case we'll be using FoaEncoderMatrix: *newFromMatrix, as we're making an encoder.( ~encoder = FoaEncoderMatrix.newFromMatrix(~matrix, ~aToBdirections); // let's see info! ~encoder.info; // be sure to use .yml extension for metadata ~encoder.writeToFile("myA2B_flu_Matrix.yml", ~note, ~properties, overwrite: true); )

There it is:Atk.postMyMatrices('FOA', 'encoders');

Subfolders: Organizing our matrices

If you'll be generating many matrices, it's advisable to organize our matrices into subfolders. For example, if you're algorithmically generating hundreds of matrices for a particular project or process, it makes sense to store them in a subfolder.

To do this, we can create subfolders inside our /encoders, /decoders, and /xformers folders.// Store our encoder matrix with the other encoders, which live here: Atk.getMatrixExtensionSubPath('FOA', 'encoders'); // We can make subfolder for a group of matrices, say, for a particular project: ( ~projSubFolderName = "myProject"; File.mkdir( Atk.getMatrixExtensionSubPath('FOA', 'encoders').fullPath +/+ ~projSubFolderName ) ) // For convenience, we'll write the 9-point ~encoder matrix, // which we created above, to a new file in our new project folder. // (We'll need to reset ~note and ~properties, as we clobbered them above!) ( // A 'note': a description or note about the matrix. ~note = "This is a nine-point t-design encoder made for a matrix file writing demo."; // A Dictionary of more metadata to add. ~properties =  (     author: "Me, the Reader",     dateCreated: Date.getDate.stamp,     ordering: 'FuMa',     normalisation: 'MaxN',     dirInputs: ~directions ); ~encoder.writeToFile(~projSubFolderName +/+ "projectEncoder1.yml", note: ~note, attributeDictionary: ~properties ) )

FoaEncoderMatrix: *newFromMatrix can be used to read the file back in. The ATK will know where to look (extensions/matrices/enocoders/FOA) so we can simply specify the relative path of our subfolder/file.yml:~projectEncoder1 = FoaEncoderMatrix.newFromFile(~projSubFolderName +/+ "projectEncoder1.yml"); ~projectEncoder1.info;

Reading Matrices

We wrote three encoder matrix files earlier. Let's now read them in. As when writing, the ATK looks in the extensions/matrices directory by default. Unless the matrix file is somewhere outside the default location, a filename will suffice to read it in. The type ('encoder', 'decoder', 'xformer') is inferred from the object being instantiated.

We can even omit the file extension if we don't expect multiple file formats (.txt, .yml, .mosl.txt) stored under the same name:~encoder = FoaEncoderMatrix.newFromFile("my9PointEncoder") // >> ERROR: It sees we have more than one file with that name.

So, we'll need to specify the extension. As mentioned before, each file format determines what kind of information is stored in the file.

Lets have a look at what each file format gives us back:

.txt format:// Reading the .txt file, we just get a matrix and basic info. ~encoder = FoaEncoderMatrix.newFromFile("my9PointEncoder.txt"); // All the standard instance vars are preserved. ~encoder.matrix; ~encoder.kind; // Defaults to filename ~encoder.dirOutputs; // Outputs are inf, becuase the output is b-format, i.e "all directions". ~encoder.dirInputs; // With no metadata, we can't know input directions, so 'unspecified' ~encoder.dirInputs.size;// ...but knowing how large the array is tells us how many inputs the matrix expects ~encoder.dim; // We see it's a 3-D matrix

.mosl.txt format:// reading the mosl.txt file, we just get a matrix and basic info ~encoder = FoaEncoderMatrix.newFromFile("my9PointEncoder.mosl.txt"); // all the standard instance vars are preserved ~encoder.matrix; ~encoder.kind; // Defaults to filename ~encoder.dirOutputs; // inf, by nature of encoding to b-format ~encoder.dirInputs; // With no metadata, we can't know input directions ~encoder.dim;

.yml format:// reading the .yml file, we get the matrix plus metadata ~encoder = FoaEncoderMatrix.newFromFile("my9PointEncoder.yml"); // all the standard instance vars are preserved ~encoder.matrix; ~encoder.kind; ~encoder.dirOutputs; ~encoder.dim; // NOTE: because .yml files are verbose, we now have that info for reference. Useful! ~encoder.dirInputs; // Plus the other data written to it: ~encoder.info; // Formatted post // Metadata is loaded as an IndentityDictionary, so values // from the attributeDictionary can be accessed by their // keys as pseudo-methods. ~encoder.fileParse; // For direct access to the dictionary of values ~encoder.fileParse.note; // What was this matrix again?? Oh yea... ~encoder.fileParse.ordering; ~encoder.fileParse.keysValuesDo{|k,v| postf("% : %\n", k, v)};

Test case: Creating a decoder from an FoaEncoderMatrix

We've now instantiated a new ~encoder by reading in the file that stored the matrix that we originally built using the planewave encoder: FoaEncoderMatrix: *newDirections (using the points of a nine-point t-design). As it turns out, a matrix encoder created by FoaEncoderMatrix: *newDirections can be used to build a decoder of the same geometry.³ Doing so just involves performing the Matrix: -pseudoInverse on the encoder's Matrix.⁴ // Retrieve the Matrix object stored in the FoaEncoderMatrix // (Should be the 9-point t-design from above!) ~encoderMatrix = ~encoder.matrix; // Perform the pseudoinverse on that matrix to find decoding coefficients ~decoderMatrix = ~encoderMatrix.pseudoInverse;

Using these coefficients will return a 'velocity' decode (aka "strict soundfield" or "basic"). Loudspeakers should be positioned in the following directions (and in this order):~encoder.dirInputs.do{|azElPairs, i| postf("chan %: %\n", i, azElPairs.raddeg) }

Let's go ahead and finish off the job and use the resulting raw matrix to create a decoder instance:~decoder = FoaDecoderMatrix.newFromMatrix(~decoderMatrix, ~encoder.dirInputs); ~decoder.info; // have a look!

And... have a go!( ~decoderDef = SynthDef(\pinv_decoder, { arg outbus=0, amp=1 var foa, out; // Test signal: panning noise foa = FoaPanB.ar( PinkNoise.ar, LFSaw.kr( 12.reciprocal, 1, pi/2 ), 0 ); out = FoaDecode.ar(foa, ~decoder); Out.ar(outbus, out); }).load(Server.default); ) ~decoderSynth = Synth(\pinv_decoder, [\outbus, 0, \amp, -8.dbamp]); // Scope the 9 channels of the decoded output s.scope(9, 0); // Clean up ~decoderSynth.free;