HoaMatrixEncoder : HoaMatrix : AtkMatrix : Object
Extension
ExtensionDescription
Generate matrix encoders required by the Ambisonic Toolkit's Higher Order Ambisonic (HOA) encoder, HoaEncodeMatrix.
Matrix encoding is offered via three different methods:
- beamforming
- mode matching
- format exchange
As implemented here, beamforming offers familiar angular encoding with the added opportunity to apply matching beaming weights for reciprocal decoding / encoding signal processing.
Mode matching is suitable for designing encoders from various spatial sampling distributions.
Format exchange encoding offers interfacing with other Ambisonic formats and systems.
Class Methods
HoaMatrixEncoder.newDirection(theta: 0, phi: 0, beamShape, order)
Encode a single beam into a Higher Order Ambisonic signal (HOA).
Arguments:
| theta |
Azimuth, in radians. |
| phi |
Elevation, in radians. |
| beamShape |
Keyword argument for beam shape.
See discussion here. |
| order |
Ambisonic order. |
Discussion:
Gain is matched to pressure. See discussion here
HoaMatrixEncoder.newDirections(directions, beamShape, match, order)
Encode multipe beams into a Higher Order Ambisonic signal (HOA).
Arguments:
| directions |
An array of directions. Specify in radians. Rank 1 arrays return pantophonic, while rank 2 arrays return periphonic. E.g.,
|
| beamShape |
Keyword argument for beam shape.
See discussion here. |
| match |
Keyword argument for gain matching. See discussion here. |
| order |
Ambisonic order. |
HoaMatrixEncoder.newModeMatch(directions, beamShape: 'basic', match: 'beam', order)
Encode a Higher Order Ambisonic signal (HOA) via the mode matching method.
Arguments:
| directions |
An array of directions. Specify in radians. Rank 1 arrays return pantophonic, while rank 2 arrays return periphonic. E.g.,
|
| beamShape |
Keyword argument for beam shape. See discussion here. |
| match |
Keyword argument for gain matching. See discussion here. |
| order |
Ambisonic order. |
Discussion:
Also known as Pseudoinverse Encoding, aka Pinv.
HoaMatrixEncoder.newSphericalDesign(design, beamShape: 'basic', order)
Encode multiple beams evenly distributed in a SphericalDesign as a Higher Order Ambisonic signal (HOA).
Arguments:
| design |
SphericalDesign instance |
| beamShape |
Keyword argument for beam shape. See discussion here. |
| order |
Ambisonic order. |
Discussion:
A-format encoding, aka spherical (re-)composition, is offered by *newSphericalDesign.
Gain is matched to maximum beam amplitude.
HoaMatrixEncoder.newFormat(format: 'atk', order)
An Ambisonic format exchange encoder. Encodes from a variety of formats to ACN-N3D.
Arguments:
| format |
An array of kewords designating component ordering and normalisation. E.g., source input format ACN-SN3D is expressed |
| order |
Ambisonic order. |
Discussion:
A variety of component ordering and normalisation schemes are supported. Please review the discussion found here: HoaMatrixDecoder: *newFormat
Matrix & File
HoaMatrixEncoder.newFromMatrix(matrix, directions, order)
Create an instance from a raw 2D Matrix.
Arguments:
| matrix |
A Matrix in the form of |
| directions |
An array of directions. Specify in radians. Rank 1 arrays return pantophonic, while rank 2 arrays return periphonic. E.g.,
|
| order |
Ambisonic order. |
HoaMatrixEncoder.newFromFile(filePathOrName, searchExtensions: true, order)
Create an instance by loading a matrix from a file.
Arguments:
| filePathOrName |
Can be a path relative to your Otherwise a full path to your matrix file. |
| searchExtensions |
Search extension paths. |
| order |
Ambisonic order. |
Discussion:
See the Guide to ATK Matrix Files for more information.
Inherited class methods
Instance Methods
Information
.info
A convenience method to post the properties of the matrix, including metadata if the matrix was loaded from a .yml file.
.order
Ambisonic order.
.set
Describes both the signal set and the tool set, encompassing the Ambisonic order, as well as channel ordering and normalisation.
Ambisonic Toolkit designation indicating Ambisonic order and encoding format. E.g., \FOA, \HOA3.
For instance, \HOA3:
| Ambisonic Order | Component Ordering | Component Normalisation |
| 3rd | Ambisonic Channel Number (ACN) | Full 3-D normalisation (N3D) |
.type
Ambisonic Toolkit soundfield operation designation. E.g., \encode, \xform, \decode.
.op
Answers 'matrix', i.e. the type of operation used to compute the resulting signals.
.kind
Answers the kind.
.dim
Answers the number of encoder dimensions: 2D or 3D.
.numChannels
Answers the number of input or output channels, depending on -type.
.directions
Answers the directions of input or output channels, depending on -type.
.numInputs
Number of inputs.
.dirInputs
A convenience method providing polymorphism with -directions, depending on -type.
.numOutputs
Number of outputs.
.dirOutputs
A convenience method providing polymorphism with -directions, depending on -type.
Matrix
.matrix
Returns the raw coefficient Matrix.
.thresh2(thresh)
Bilateral thresholding in place.
Arguments:
| thresh |
When the |
.asArray
Returns the matrix as a new Array of rows.
File handling
.fileName
Answers the name of the file used to create the instance, or nil if not created by loading a matrix from a file.
.filePath
Answers the path of the file used to create the instance, or nil if not created by loading a matrix from a file.
.fileParse
If the instance was created by loading a .yml file, this method returns the 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.
.writeToFile(fileNameOrPath, note, attributeDictionary, overwrite: false)
Write the matrix to a file
Arguments:
| fileNameOrPath |
A String of the file name. The file extension determines the format:
You may provide a full path if you would like to save the file somewhere other than the default location in the Atk |
| note |
A String that is a short description or bit of info about the matrix to store for future reference. |
| 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. |
| overwrite |
A boolean specifying whether you'd like to force overwriting an existing file of the same name and extension. |
Discussion:
The 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.
Inherited instance methods
Examples
TBD
link::Classes/HoaMatrixEncoder::