Loris::Dilator Class Reference

Class Dilator represents an algorithm for non-uniformly expanding and contracting the Partial parameter envelopes according to the initial and target (desired) times of temporal features. More...

#include <Dilator.h>

List of all members.

Public Member Functions
	Dilator (void)
	Construct a new Dilator with no time points.
template<typename Iter1, typename Iter2>	Dilator (Iter1 ibegin, Iter1 iend, Iter2 tbegin)
	Construct a new Dilator using a range of initial time points and a range of target (desired) time points.
void	insert (double i, double t)
	Insert a pair of initial and target time points.
void	dilate (Partial &p) const
	Replace the Partial envelope with a new envelope having the same Breakpoints at times computed to align temporal features in the sorted sequence of initial time points with their counterparts the sorted sequence of target time points.
void	operator() (Partial &p) const
	Function call operator: same as dilate( Partial & p ).
void	dilate (Marker &m) const
	Compute a new time for the specified Marker using warpTime(), exactly as Partial Breakpoint times are recomputed.
void	operator() (Marker &m) const
	Function call operator: same as dilate( Marker & m ).
template<typename Iter> void	dilate (Iter dilate_begin, Iter dilate_end) const
	Non-uniformly expand and contract the parameter envelopes of the each Partial in the specified half-open range according to this Dilator's stored initial and target (desired) times.
template<typename Iter> void	operator() (Iter dilate_begin, Iter dilate_end) const
	Function call operator: same as dilate( Iter dilate_begin, Iter dilate_end ).
double	warpTime (double currentTime) const
	Return the dilated time value corresponding to the specified initial time.
Static Public Member Functions
template<typename PartialsIter, typename TimeIter1, typename TimeIter2> void	dilate (PartialsIter dilate_begin, PartialsIter dilate_end, TimeIter1 ibegin, TimeIter1 iend, TimeIter2 tbegin)
	Static member that constructs an instance and applies it to a sequence of Partials.

---

Detailed Description

Class Dilator represents an algorithm for non-uniformly expanding and contracting the Partial parameter envelopes according to the initial and target (desired) times of temporal features.

It is frequently necessary to redistribute temporal events in this way in preparation for a sound morph. For example, when morphing instrument tones, it is common to align the attack, sustain, and release portions of the source sounds by dilating or contracting those temporal regions.

This same procedure can be applied to the Markers stored in AiffFile, SdifFile, and SpcFile (see Marker.h).

---

Constructor & Destructor Documentation

template<typename Iter1, typename Iter2> Loris::Dilator::Dilator (  Iter1  ibegin, Iter1  iend, Iter2  tbegin )

Construct a new Dilator using a range of initial time points and a range of target (desired) time points. The client must ensure that the target range has at least as many elements as the initial range. Parameters: ibegin  is the beginning of a sequence of initial, or source, time points. iend  is (one-past) the end of a sequence of initial, or source, time points. tbegin  is the beginning of a sequence of target time points; this sequence must be as long as the sequence of initial time point described by ibegin and iend. If compiled with NO_TEMPLATE_MEMBERS defined, this member accepts only const double * arguments.

---

Member Function Documentation

template<typename PartialsIter, typename TimeIter1, typename TimeIter2> void Loris::Dilator::dilate (  PartialsIter  dilate_begin, PartialsIter  dilate_end, TimeIter1  ibegin, TimeIter1  iend, TimeIter2  tbegin )  [static]

Static member that constructs an instance and applies it to a sequence of Partials. Parameters: dilate_begin  is the beginning of a sequence of Partials to dilate. dilate_end  is (one-past) the end of a sequence of Partials to dilate. ibegin  is the beginning of a sequence of initial, or source, time points. iend  is (one-past) the end of a sequence of initial, or source, time points. tbegin  is the beginning of a sequence of target time points; this sequence must be as long as the sequence of initial time point described by ibegin and iend. If compiled with NO_TEMPLATE_MEMBERS defined, this member accepts only PartialList::const_iterator arguments. Otherwise, this member also works for sequences of Markers. If compiled with NO_TEMPLATE_MEMBERS defined, this member accepts only const double * arguments for the times, otherwise, any iterator will do.. See also: Dilator::dilate( Partial & p ) const Dilator::dilate( Marker & m ) const

template<typename Iter> void Loris::Dilator::dilate (  Iter  dilate_begin, Iter  dilate_end )  const

Non-uniformly expand and contract the parameter envelopes of the each Partial in the specified half-open range according to this Dilator's stored initial and target (desired) times. Parameters: dilate_begin  is the beginning of a sequence of Partials to dilate. dilate_end  is (one-past) the end of a sequence of Partials to dilate. If compiled with NO_TEMPLATE_MEMBERS defined, this member accepts only PartialList::const_iterator arguments. Otherwise, this member also works for sequences of Markers. See also: Dilator::dilate( Partial & p ) const Dilator::dilate( Marker & m ) const

void Loris::Dilator::dilate (  Marker &  m  )  const

Compute a new time for the specified Marker using warpTime(), exactly as Partial Breakpoint times are recomputed. This can be used to dilate the Markers corresponding to a collection of Partials. Parameters: m  is the Marker whose time should be recomputed.

void Loris::Dilator::dilate (  Partial &  p  )  const

Replace the Partial envelope with a new envelope having the same Breakpoints at times computed to align temporal features in the sorted sequence of initial time points with their counterparts the sorted sequence of target time points. Depending on the specification of initial and target time points, the dilated Partial may have Breakpoints at times less than 0, even if the original Partial did not. It is possible to have duplicate time points in either sequence. Duplicate initial time points result in very localized stretching. Duplicate target time points result in very localized compression. If all initial time points are greater than 0, then an implicit time point at 0 is assumed in both initial and target sequences, so the onset of a sound can be stretched without explcitly specifying a zero point in each vector. (This seems most intuitive, and only looks like an inconsistency if clients are using negative time points in their Dilator, or Partials having Breakpoints before time 0, both of which are probably unusual circumstances.) Parameters: p  is the Partial to dilate.

void Loris::Dilator::insert (  double  i, double  t )

Insert a pair of initial and target time points. Specify a pair of initial and target time points to be used by this Dilator, corresponding, for example, to the initial and desired time of a particular temporal feature in an analyzed sound. Parameters: i  is an initial, or source, time point t  is a target time point The time points will be sorted before they are used. If, in the sequences of initial and target time points, there are exactly the same number of initial time points preceding i as target time points preceding t, then time i will be warped to time t in the dilation process.

template<typename Iter> void Loris::Dilator::operator() (  Iter  dilate_begin, Iter  dilate_end )  const

Function call operator: same as dilate( Iter dilate_begin, Iter dilate_end ). If compiled with NO_TEMPLATE_MEMBERS defined, this member accepts only PartialList::const_iterator arguments. Otherwise, this member also works for sequences of Markers. See also: Dilator::dilate( Partial & p ) const Dilator::dilate( Marker & m ) const

void Loris::Dilator::operator() (  Marker &  m  )  const

Function call operator: same as dilate( Marker & m ). See also: Dilator::dilate( Marker & m ) const

void Loris::Dilator::operator() (  Partial &  p  )  const

Function call operator: same as dilate( Partial & p ). See also: Dilator::dilate( Partial & p ) const

double Loris::Dilator::warpTime (  double  currentTime  )  const

Return the dilated time value corresponding to the specified initial time. Parameters: currentTime  is a pre-dilated time. Returns: the dilated time corresponding to the initial time currentTime

---