Loris::Distiller Class Reference

Class Distiller represents an algorithm for "distilling" a group of Partials that logically represent a single component into a single Partial. More...

#include <Distiller.h>

List of all members.

Public Member Functions
	Distiller (double partialFadeTime=0.001, double partialSilentTime=0.0001)
	Construct a new Distiller using the specified fade time for gaps between Partials.
template<typename Container> Container::iterator	distill (Container &partials)
	Distill labeled Partials in a collection leaving only a single Partial per non-zero label.
template<typename Container> Container::iterator	operator() (Container &partials)
	Function call operator: same as distill( PartialList & partials ).
Static Public Member Functions
template<typename Container> Container::iterator	distill (Container &partials, double partialFadeTime, double partialSilentTime=0.0001)
	Static member that constructs an instance and applies it to a sequence of Partials.

---

Detailed Description

Class Distiller represents an algorithm for "distilling" a group of Partials that logically represent a single component into a single Partial.

The sound morphing algorithm in Loris requires that Partials in a given source be labeled uniquely, that is, no two Partials can have the same label. The Distiller enforces this condition. All Partials identified with a particular frequency channel (see Channelizer), and, therefore, having a common label, are distilled into a single Partial, leaving at most a single Partial per frequency channel and label. Channels that contain no Partials are not represented in the distilled data. Partials that are not labeled, that is, Partials having label 0, are are "collated " into groups of non-overlapping (in time) Partials, assigned an unused label (greater than the label associated with any frequency channel), and fused into a single Partial per group. "Collating" is a bit like "sifting" but non-overlapping Partials are grouped without regard to frequency proximity. This algorithm produces the smallest-possible number of collated Partials. Thanks to Ulrike Axen for providing this optimal algorithm.

Distillation modifies the Partial container (a PartialList). All Partials in the distilled range having a common label are replaced by a single Partial in the distillation process.

---

Constructor & Destructor Documentation

Loris::Distiller::Distiller (  double  partialFadeTime = 0.001, double  partialSilentTime = 0.0001 )  [explicit]

Construct a new Distiller using the specified fade time for gaps between Partials. When two non-overlapping Partials are distilled into a single Partial, the distilled Partial fades out at the end of the earlier Partial and back in again at the onset of the later one. The fade time is the time over which these fades occur. By default, use a 1 ms fade time. The gap time is the additional time over which a Partial faded out must remain at zero amplitude before it can fade back in. By default, use a gap time of one tenth of a millisecond, to prevent a pair of arbitrarily close null Breakpoints being inserted. Parameters: partialFadeTime  is the time (in seconds) over which Partials joined by distillation fade to and from zero amplitude. Default is 0.001 (one millisecond). partialSilentTime  is the minimum duration (in seconds) of the silent (zero-amplitude) gap between two Partials joined by distillation. (Default is 0.0001 (one tenth of a millisecond).

---

Member Function Documentation

template<typename Container> Container::iterator Loris::Distiller::distill (  Container &  partials, double  partialFadeTime, double  partialSilentTime = 0.0001 )  [static]

Static member that constructs an instance and applies it to a sequence of Partials. Construct a Distiller using default parameters, and use it to distill a sequence of Partials. Postcondition: All Partials in the collection are uniquely-labeled Parameters: partials  is the collection of Partials to distill in-place partialFadeTime  is the time (in seconds) over which Partials joined by distillation fade to and from zero amplitude. partialSilentTime  is the minimum duration (in seconds) of the silent (zero-amplitude) gap between two Partials joined by distillation. (Default is 0.0001 (one tenth of a millisecond). Returns: the position of the end of the range of distilled Partials, which is either the end of the collection, oor the position of the first collated Partial, composed of unlabeled Partials in the original collection. If compiled with NO_TEMPLATE_MEMBERS defined, then partials must be a PartialList, otherwise it can be any container type storing Partials that supports at least bidirectional iterators.

template<typename Container> Container::iterator Loris::Distiller::distill (  Container &  partials  )

Distill labeled Partials in a collection leaving only a single Partial per non-zero label. See also: Distiller::distill( Container & partials )

template<typename Container> Container::iterator Loris::Distiller::operator() (  Container &  partials  )

Function call operator: same as distill( PartialList & partials ). See also: Distiller::distill( Container & partials )

---