TITLE:: FluidBufFlatten
summary:: Flatten a multichannel buffer on the server
categories:: FluidCorpusManipulation
related:: Classes/Buffer

DESCRIPTION::
Flatten a multichannel link::Classes/Buffer:: to a single channel. This can be useful for constructing n-dimensional data points for use with link::Classes/FluidDataSet::

The code::axis:: determines how the flattening is arranged. The default value, 1, flattens channel-wise, such that (if we imagine channels are rows, time positions are columns):

table::
    ## a 1 || a 2 || a 3
    ## b 1 || b 2 || b 3
    ## c 1 || c 2 || c 3
::

becomes

table::
##  a 1 || b 1 || c 1 || a 2 || b 2 || c 2 || a 3 || b 3 || c 3
::

whereas with code::axis = 0:: we get

table::
    ## a 1 || a 2 || a 3 || b 1 || b 2 || b 3 || c 1 || c 2 || c 3
::


CLASSMETHODS::

private::new1

METHOD:: process, processBlocking

Run the process on the given sever, and perfrom code::action:: when done

ARGUMENT:: server
The link::Classes/Server:: on which to run

ARGUMENT:: source
The link::Classes/Buffer:: to flatten

ARGUMENT:: destination
The link::Classes/Buffer:: to write the flattened data to

ARGUMENT:: axis
Whether to group points channel-wise or frame-wise

ARGUMENT:: action
Runs when processing is complete

METHOD:: kr
Run as a control rate link::Classes/UGen::

ARGUMENT:: source
The link::Classes/Buffer:: to flatten

ARGUMENT:: destination
The link::Classes/Buffer:: to write the flattened data to

ARGUMENT:: axis
Whether to group points channel-wise or frame-wise

ARGUMENT:: trig
Trigger signal to defer / retrigger processing

EXAMPLES::

code::
//FluidBufPitch is useful to illustrate the effect of this, because the pitch and confidence values are easily distinguishable

(
~path = File.realpath(FluidLoadFolder.class.filenameSymbol).dirname +/+ "../AudioFiles";
~randomsoundfile = SoundFile.collect(~path +/+ '*').choose;
b = Buffer.read(s,~randomsoundfile.path,action:{"Sound Loaded".postln});
~pitchdata = Buffer.new;
~flatdata = Buffer.new;
)

//Pitch analysis, writes pitches as frequecnies to chan 0, confidences [0-1] to chan 1
FluidBufPitch.process(s,b,numFrames:512 * 10,numChans:1,features:~pitchdata,action:{"Pitch Analysis Done".postln});

// Flatten and print the flat buffer. We expect to see larger numbers (20-2000) interleaved with smaller (0-1)
(
FluidBufFlatten.process(s,~pitchdata,~flatdata,action:{
	~flatdata.loadToFloatArray(action:{ |a|
		a.postln;
	})
})
)
::