CLASS:: Atk
summary:: a class that stores some global variables for the Ambisonic Toolkit
categories:: Libraries>Ambisonic Toolkit>ATK Platform & Configuration
related:: Classes/AtkFoa, Classes/AtkHoa, Tutorials/ABCs-of-the-ATK

DESCRIPTION::
The Atk class defines variables that may be used by the rest of the ATK library, including resources for kernel encoding and decoding and sample soundfile paths.


CLASSMETHODS::

METHOD:: sets

returns:: an Array listing valid ATK sets.

SUBSECTION:: Installation of ATK dependencies

Kernels, Matrices, and Soundfiles can be installed using following methods:
code::
Atk.downloadKernels;
Atk.downloadMatrices;
Atk.downloadSounds;
::

note::On code::Windows:: there is no feedback on download progress. Please wait until the message confirming decompressing of the downloaded archive is posted.::

In case the automatic installation fails, please see the Ambisonic Toolkit webpage to proceed with manual installation:
code::
"http://ambisonictoolkit.net/download/kernels/".openOS; //kernels
"http://ambisonictoolkit.net/download/matrices/".openOS; //matrices
"http://ambisonictoolkit.net/download/recordings/".openOS; //soundfiles
::


METHOD:: downloadKernels
Download Atk Kernels, required by kernel encoders/decoders

METHOD:: downloadMatrices
Download Atk Matrices, required by matrix encoders/decoders/transformers

METHOD:: downloadSounds
Download Atk Example Soundfiles


SUBSECTION:: ATK's default asset directories

NOTE:: The following methods have both strong::user:: and
strong::system:: versions. Which version you should use will depend on whether
you have the ATK assets installed at the user level:
code::
Platform.userAppSupportDir
::
or the system level:
code::
Platform.systemAppSupportDir
::
::

METHOD:: userSupportDir
set the user support dir where ATK resources are located

argument:: userSupportDirIn
the path to the ATK folder containing your ATK support files

METHOD:: userSupportDir

returns::the path to the ATK support dir. Defaults to:
code::Platform.userAppSupportDir.dirname ++ "/ATK";::

METHOD:: userSoundsDir

returns:: a path to the 'sounds' dir inside the ATK support dir

METHOD:: userMatrixDir

returns:: a path to the 'matrices' dir inside the ATK support dir

METHOD:: userKernelDir

returns:: a path to the 'kernel' dir inside the ATK support dir

METHOD:: openUserSupportDir
runs a link::Classes/String#-unixCmd:: to open the userAppSupport dir. Uses
'open' (OS X only)

METHOD:: createUserSupportDir
runs a unix command to create the user support dir for ATK

METHOD:: systemSupportDir

returns::the path to the ATK support dir. Defaults to:
code::Platform.systemAppSupportDir.dirname ++ "/ATK";::

METHOD:: systemSoundsDir

returns:: a path to the 'sounds' dir inside the ATK system support dir

METHOD:: systemMatrixDir

returns:: a path to the 'matrices' dir inside the ATK system support dir

METHOD:: systemKernelDir

returns:: a path to the 'kernel' dir inside the ATK system support dir

METHOD:: openSystemSupportDir
runs a link::Classes/String#-unixCmd:: to open the systemAppSupport dir. Uses
'open' (OS X only)

METHOD:: createSystemSupportDir
runs a unix command to create the system support dir for ATK


SUBSECTION:: User asset /extensions directory

The code::extensions:: directory is where the ATK looks for assets generated or
added by you, such as your own matrices or kernels.  It is located in
code::
Atk.userExtensionsDir
::
or if the ATK assets are installed system-wide, in:
code::
Atk.systemExtensionsDir
::
It is strong::not installed by default::.  It can be
created by running
code::
Atk.createExtensionsDir
::
You can find out more about the directory structure in the
link::Guides/Guide-to-ATK-Matrix-Files::.

METHOD:: userExtensionsDir

returns:: a path to the 'extensions' dir inside the ATK support dir. This is where
user-generated matrices and kernels are stored to and rerieved from by default.

METHOD:: systemExtensionsDir

returns:: a path to the 'extensions' dir inside the ATK support dir. This is where
user-generated matrices and kernels are stored to and rerieved from by default.

METHOD:: postMyMatrices
Displays a formatted list the matrices stored in your
code::ATK/extensions/matrices:: directory.  The strong::set:: and
strong::type:: arguments are optional filters to display only matrices of a the
specified strong::set:: and strong::type::.
NOTE:: This method first searches the code::Atk.userExtensionsDir:: and if no
directory is found, it proceeds to check for a system-wide installation in
code::Atk.systemExtensionsDir::.
::

METHOD:: createExtensionsDir
Creates the code::extensions:: folder, along with numerous subdirectories in a
pre-defined structure, in your ATK assets folder. This is where the ATK looks
for assets generated or added by you, such as your own matrices or kernels.
You can find out more about the directory structure and its use in the
link::Guides/Guide-to-ATK-Matrix-Files::.


SUBSECTION:: Convenience methods for accessing subdirectories

The following methods are used by ATK internally but listed here in the case
you find them useful.

METHOD:: getAtkOpPath
Get the Link::Classes/PathName:: of the strong::op:: directory (code::'kernels':: or
code::'matrices'::), in either the "built-in" ATK support directory or
the user code::extension:: subdirectory (strong::isExtension:: = true).

METHOD:: getAtkOpSubPath

Get the Link::Classes/PathName:: of the subdirectory within the
code::ATK/'op'/'set'/'type':: folder.
NOTE:: This method first searches the code::Atk.userExtensionsDir:: and if no
directory is found, it proceeds to check the code::Atk.systemExtensionsDir::.
::

METHOD:: getAtkMatrixSubPath
A shortcut for code::Atk.getAtkOpSubPath(set, op, 'matrices')::

METHOD:: getAtkKernelSubPath
A shortcut for code::Atk.getAtkOpSubPath(set, op, 'kernels')::

METHOD:: getExtensionSubPath
Get the Link::Classes/PathName:: of the subdirectory within the
code::ATK/extensions/'op'/'set'/'type':: folder.
NOTE:: This method first searches the code::Atk.userExtensionsDir:: and if no
directory is found, it proceeds to check the code::Atk.systemExtensionsDir::.
::

METHOD:: getMatrixExtensionSubPath
A shortcut for code::Atk.getExtensionSubPath(set, op, 'matrices')::

METHOD:: getKernelExtensionSubPath
A shortcut for code::Atk.getExtensionSubPath(set, op, 'kernels')::



PRIVATE:: checkSet, sets, getAtkLibSubPath, getKernelExtensionPath, getBuiltInPath, getMatrixBuiltInPath, resolveMtxPath, folderExists, checkSupportDirsExist, downloadAndUnzip, downloadFile, kernelsDownloadUrl, matricesDownloadUrl, soundsDownloadUrl, unzipFile
