SuperCollider CLASSES (extension)

FoaDecoderKernel

First Order Ambisonic (FOA) decoder kernels
Source: /Users/joshp/Library/Application Support/SuperCollider/Extensions/SC3plugins/ATK/Classes/ATKMatrix.sc
Inherits from: Object

Description

Generates decoding kernels required by the Ambisonic Toolkit's first order decoder, FoaDecode.

Class Methods

*newUHJ (kernelSize = 512, server)

Ambisonic UHJ stereo decoder.1

Arguments:

kernelSize

256, 512, 1024, 2048, 4096, 8192

server

Server on which to load kernel.

Discussion:

For production work targeting stereo output, the authors advise using UHJ, as Ambisonic UHJ stereo is the native Ambisonic stereo format.

*newSpherical (subjectID = 4, kernelSize = 512, server)

Synthetic spherical head model HRTF decoder.2

Arguments:

subjectID

0 to 9

kernelSize

256, 512, 1024, 2048, 4096, 8192

server

Server on which to load kernel.

Discussion:

-newSpherical models a sphere only, and is equivalent to placing a pair of spaced, sphere baffled microphones in the soundfield. With no pinnae and no body, elevation cues are not present.

The subjectID argument varies to suit listener head width, with 0 the smallest and 9 the largest head. The user is advised to audition to find a suitable choice.

*newListen (subjectID = 1002, server)

Measured HRTF decoder, with measurements from IRCAM's Listen HRTF database.3

Arguments:

subjectID

1002 to 1059 (51 in total)

WARNING: subjectIDs are not entirely contiguous.
server

Server on which to load kernel.

Discussion:

The user is advised to audition subjectIDs to find a suitable choice. If an invalid subjectID is chosen, valid choices are returned. 

// Boot desired server first...
// ... choose an invalid subject
~encoder = FoaDecoderKernel.newListen(0)

// make sure you scroll up to see the resulting valid subjects!
WARNING: The Listen HRTF database is measured at SampleRate = 44.1kHz. Make sure your Server is set to this rate.

*newCIPIC (subjectID = 21, server)

Measured HRTF decoder, with measurements from the University of California Davis' CIPIC HRTF database.4

Arguments:

subjectID

3 to 165 (45 in total)

WARNING: subjectIDs are not entirely contiguous.
server

Server on which to load kernel.

Discussion:

The CIPIC HRTF database provides two KEMAR dummy measurements. subjectID = 21 is the large pinnae dummy and subjectID = 165 is the small pinnae dummy.

The user is advised to audition subjectIDs to find a suitable choice. If an invalid subjectID is chosen, valid choices are returned. 

// Boot desired server first...
// ... choose an invalid subject
~encoder = FoaDecoderKernel.newCIPIC(0)

// make sure you scroll up to see the resulting valid subjects!
NOTE: The HRIRs from the CIPIC HRTF database have been equalised (by inspection) to match the frequency response of *newSpherical and *newListen .
WARNING: The Listen HRTF database is measured at SampleRate = 44.1kHz. Make sure your Server is set to this rate.

Inherited class methods

Instance Methods

-kind

Answers the kind of decoder

Discussion:

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.kind

// don't forget to free!!
~decoder.free


// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.kind

// don't forget to free!!
~decoder.free

-subjectID

Answers the subjectID of the decoder

Discussion:

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.subjectID

// don't forget to free!!
~decoder.free


// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.subjectID

// don't forget to free!!
~decoder.free

-dim

Answers the number of decoder dimensions: 2D or 3D.

Discussion:

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newSpherical

// inspect
~decoder.dim

// don't forget to free!!
~decoder.free


// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.dim

// don't forget to free!!
~decoder.free

-numChannels

Answers the number of loudspeaker (or headphone) feeds (output channels).

Discussion:

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.numChannels

// don't forget to free!!
~decoder.free

-dirChannels

Answers the direction of loudspeaker (or headphone) feeds, with angles in radians.

Discussion:

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.dirChannels * 180/pi

// don't forget to free!!
~decoder.free


// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.dirChannels * 180/pi

// don't forget to free!!
~decoder.free

-kernel

Answers the decoder kernel.

Discussion:

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.kernel

// don't forget to free!!
~decoder.free


// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.kernel

// don't forget to free!!
~decoder.free

-kernelSize

Answers the kernelSize.

Discussion:

// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newUHJ

// inspect
~decoder.kernelSize

// don't forget to free!!
~decoder.free


// decoder - make sure you boot the server first!!
~decoder = FoaDecoderKernel.newCIPIC

// inspect
~decoder.kernelSize

// don't forget to free!!
~decoder.free

-free

Free the kernel.

Discussion:

Release the kernel buffer's memory on the server and return the bufferID back to the server's buffer number allocator for future reuse.

WARNING: Only free the kernel when the FoaDecode: *ar is no longer in use!

-numOutputs

A synonym for -numChannels

-dirOutputs

A synonym for -dirChannels

-numInputs

Answers the number of inputs for the decoder. 3 for 2D and 4 for 3D.

-dirInputs

A convenience method providing polymorphism with FoaEncoderKernel: -dirInputs.

Returns:

  • for 2D: [ inf, inf, inf ]
  • for 3D: [ inf, inf, inf , inf ]

Inherited instance methods

Undocumented instance methods

-kernelInfo

-buffers

-kernelBundle

Examples

Please see FoaDecode: Examples.

[1] - See: http://en.wikipedia.org/wiki/Ambisonic_UHJ_format
[2] - See: R. O. Duda, "Modeling head related transfer functions," in Proceedings of the Twenty-Seventh Annual Asilomar Conference on Signals, Systems and Computers, Asilomar, CA, 1993.
[3] - See: http://recherche.ircam.fr/equipes/salles/listen/
[4] - See: http://interface.cipic.ucdavis.edu/sound/hrtf.html
source: /Users/joshp/Library/Application Support/SuperCollider/Extensions/SC3plugins/ATK/HelpSource/Classes/FoaDecoderKernel.schelp
link::Classes/FoaDecoderKernel::