CLASS:: FoaXform
summary:: First Order Ambisonic (FOA) matrix transformer
categories:: Libraries>Ambisonic Toolkit>FOA>Transforming, UGens>Multichannel>Ambisonics
related:: Classes/FoaXformerMatrix, Classes/FoaTransform

DESCRIPTION::
Transforms (spatial domain filter) a first order ambisonic signal (B-format). link::Classes/FoaXform:: applies static transforms, for dynamic transforms see link::Classes/FoaTransform::.



CLASSMETHODS::

METHOD:: ar

argument:: in
The B-format signal, an array: [w, x, y, z]

argument:: xformer
link::Classes/FoaXformerMatrix:: instance.

argument:: mul
Output will be multiplied by this value.

argument:: add
This value will be added to the output.

returns::
An array of channels, the transformed B-format signal.



EXAMPLES::

The examples below are intended to briefly illustrate some of the first order tranform options made available in the Ambisonic Toolkit. The user is encouraged to carefully review the features of link::Classes/FoaXformerMatrix:: to gain a deeper understanding of the flexibility of these tools.

Available transformers include rotations, mirroring, directivity (spatial low pass fitering), dominance (image warping), and a variety of dominance related transforms.

As the Ambisonic technique is a hierarchal system, numerous options for playback are possible. These include two channel stereo, two channel binaural, pantophonic and full 3D periphonic. With the examples below, we'll take advantage of this by first choosing a suitable decoder with with to audition.

subsection:: Choose a decoder

Choose a decoder suitable for your system, as illustrated link::Guides/Intro-to-the-ATK#choose_a_decoder#here::. You'll end up definining code:: ~decoder :: and code:: ~renderDecode :: .

note:: If you choose a kernel decoder, link::Classes/FoaDecoderKernel::, be sure to free the kernel after use. ::


subsection:: Rotate

Rotation is one of the most used soundfield transforms. In this case we'll it to centre the subject of a field recording.

If you haven't already choose a code:: ~decoder:: and defined code:: ~renderDecode ::, do so link::#choose_a_decoder#now::.

note:: A matrix type transformer, see link::Classes/FoaXformerMatrix#*newRotate:: for further details.::

code::
// ------------------------------------------------------------
// rotate xformer
// b-format soundfile read from disk


// define xformer matrix
~xformer = FoaXformerMatrix.newRotate           // no rotation --> try this 1st
~xformer = FoaXformerMatrix.newRotate(110/180 * pi.neg) // by -110deg   --> try this 2nd


// inspect
~encoder.kind
~encoder.numChannels
~encoder.dirChannels * 180/pi


// read a whole sound into memory
// remember to free the buffer later!
// (boot the server, if you haven't!)
~sndbuf = Buffer.read(s, Atk.userSoundsDir ++ "/b-format/Leonard-Chinook.wav")


(
{
    var sig;                            // audio signal


    // display xformer & decoder
    "Ambisonic transforming via % xformer".format(~xformer.kind).postln;
    "Ambisonic decoding via % decoder".format(~decoder.kind).postln;

    // ------------------------------------------------------------
    // test sig
    sig = PlayBuf.ar(~sndbuf.numChannels, ~sndbuf, doneAction:2);   // soundfile

    // ------------------------------------------------------------
    // transform
    sig = FoaXform.ar(sig, ~xformer);


    // ------------------------------------------------------------
    // decode (via ~renderDecode)
    ~renderDecode.value(sig, ~decoder)

}.scope;
)

// free buffer
~sndbuf.free
// ------------------------------------------------------------
::

note:: strong::Soundfile Credits::

list::
## J. Leonard, "A couple of Chinook helicopters," Sound of Space: ambisonic surround sound, 20-Mar-2008. [Online]. Available: http://soundofspace.com/ambisonic_files/47 [Accessed: 03-Nov-2011].

::

::


subsection:: MirrorO

In mirroring through the origin and delaying the soundfield, we can generate a new set of echos in this fireworks field recording.

If you haven't already choose a code:: ~decoder:: and defined code:: ~renderDecode ::, do so link::#choose_a_decoder#now::.

note:: A matrix type transformer, see link::Classes/FoaXformerMatrix#*newMirrorO:: for further details.::


code::
// ------------------------------------------------------------
// mirrorO xformer
// b-format soundfile read from disk


// define xformer matrix
~xformer = FoaXformerMatrix.newMirrorO


// inspect
~encoder.kind
~encoder.numChannels
~encoder.dirChannels * 180/pi


// read a whole sound into memory
// remember to free the buffer later!
// (boot the server, if you haven't!)
~sndbuf = Buffer.read(s, Atk.userSoundsDir ++ "/b-format/Leonard-Fireworks.wav")


(
{
    var sig;                            // audio signal
    var delSig;                         // delayed signal
    var freq;                           // lp frequency
    var delay;                          // delay time
    var scale;                          // delay gain (as scale)

    // display xformer & decoder
    "Ambisonic transforming via % xformer".format(~xformer.kind).postln;
    "Ambisonic decoding via % decoder".format(~decoder.kind).postln;

    // ------------------------------------------------------------
    // parameters
    freq = 1200;                        // in Hz
    delay = 0.5;                        // in seconds
    scale = 9.neg.dbamp;

    // ------------------------------------------------------------
    // test sig
    sig = PlayBuf.ar(~sndbuf.numChannels, ~sndbuf, doneAction:2);   // soundfile

    // ------------------------------------------------------------
    // delay, lp and gain
    delSig = LPF.ar(DelayN.ar(sig, delay, delay), freq, scale);

    // ------------------------------------------------------------
    // transform
    delSig = FoaXform.ar(delSig, ~xformer);

    // ------------------------------------------------------------
    // sum (comment this out to hear original signal)
    sig = sig + delSig;
//    sig = delSig;                    // or listen to the mirrored sig

    // ------------------------------------------------------------
    // decode (via ~renderDecode)
    ~renderDecode.value(sig, ~decoder)

}.scope;
)

// free buffer
~sndbuf.free
// ------------------------------------------------------------
::

note:: strong::Soundfile Credits::

list::
## J. Leonard, "Fireworks," Sound of Space: ambisonic surround sound, 25-Aug-2009. [Online]. Available: http://soundofspace.com/ambisonic_files/37 [Accessed: 03-Nov-2011].

::

::


subsection:: DominateX

Dominance adjusts the gain of a soundfield in a particular direction. Here we'll increase the amount of reverberation in this natural soundfield recording. As the image is warped at the same time, we'll also hear the frontal stage widen.

If you haven't already choose a code:: ~decoder:: and defined code:: ~renderDecode ::, do so link::#choose_a_decoder#now::.

note:: A matrix type transformer, see link::Classes/FoaXformerMatrix#*newDominateX:: for further details.::


code::
// ------------------------------------------------------------
// dominateX xformer
// b-format soundfile read from disk


// define xformer matrix
~xformer = FoaXformerMatrix.newDominateX           // no dominance --> try this 1st
~xformer = FoaXformerMatrix.newDominateX(-3.0)    // increase gain at rear


// inspect
~encoder.kind
~encoder.numChannels
~encoder.dirChannels * 180/pi


// read a whole sound into memory
// remember to free the buffer later!
// (boot the server, if you haven't!)
~sndbuf = Buffer.read(s, Atk.userSoundsDir ++ "/b-format/Leonard-Orfeo_Trio.wav")


(
{
    var sig;                            // audio signal

    // display xformer & decoder
    "Ambisonic transforming via % xformer".format(~xformer.kind).postln;
    "Ambisonic decoding via % decoder".format(~decoder.kind).postln;

    // ------------------------------------------------------------
    // test sig
    sig = PlayBuf.ar(~sndbuf.numChannels, ~sndbuf, doneAction:2);   // soundfile

    // ------------------------------------------------------------
    // transform
    sig = FoaXform.ar(sig, ~xformer);


    // ------------------------------------------------------------
    // decode (via ~renderDecode)
    ~renderDecode.value(sig, ~decoder)

}.scope;
)

// free buffer
~sndbuf.free
// ------------------------------------------------------------
::

note:: strong::Soundfile Credits::

list::
## J. Leonard, "The Orfeo Trio & TetraMic," Sound of Space: ambisonic surround sound. [Online]. Available: http://soundofspace.com/ambisonic_files/41 [Accessed: 03-Nov-2011].

::

::


