Loris::Dilator Class Reference

#include <Dilator.h>

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)
void	insert (double i, double t)
void	dilate (Partial &p) const
void	operator() (Partial &p) const
	Function call operator: same as dilate( Partial & p ).
void	dilate (Marker &m) const
void	operator() (Marker &m) const
	Function call operator: same as dilate( Marker & p ).
template<typename Iter >
void	dilate (Iter dilate_begin, Iter dilate_end) const
template<typename Iter >
void	operator() (Iter dilate_begin, Iter dilate_end) const
double	warpTime (double currentTime) const
Static Public Member Functions
template<typename PartialsIter , typename TimeIter1 , typename TimeIter2 >
static void	dilate (PartialsIter dilate_begin, PartialsIter dilate_end, TimeIter1 ibegin, TimeIter1 iend, TimeIter2 tbegin)

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
	)			`[inline]`

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
	)			`[inline, static]`

Static member that constructs an instance and applies it to a sequence of Partials. Construct a Dilator using the specified initial and target times, and apply 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 `[inline]`

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 `[inline]`

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.