path: root/src/loris/Dilator.h

#ifndef INCLUDE_DILATOR_H
#define INCLUDE_DILATOR_H
/*
 * This is the Loris C++ Class Library, implementing analysis, 
 * manipulation, and synthesis of digitized sounds using the Reassigned 
 * Bandwidth-Enhanced Additive Sound Model.
 *
 * Loris is Copyright (c) 1999-2010 by Kelly Fitz and Lippold Haken
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY, without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 *
 * Dilator.h
 *
 * Definition of class Dilator.
 *
 * Kelly Fitz, 26 Oct 1999
 * loris@cerlsoundgroup.org
 *
 * http://www.cerlsoundgroup.org/Loris/
 *
 */

#if defined(NO_TEMPLATE_MEMBERS)
#include "PartialList.h"
#endif

#include <vector>

//	begin namespace
namespace Loris {

class Marker;
class Partial;

// ---------------------------------------------------------------------------
//	class Dilator
//
//!	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).
//
class Dilator
{
//	-- instance variables --

	std::vector< double > _initial, _target;	//	time points
	
//	-- public interface --
public:
//	-- construction --

	//!	Construct a new Dilator with no time points.
	Dilator( void );
	 	
	//!	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.
	//!	
	//!	\param 	ibegin is the beginning of a sequence of initial, or source,
	//!	         time points.
	//!	\param 	iend is (one-past) the end of a sequence of initial, or
	//!	         source, time points.
	//!	\param 	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.
#if ! defined(NO_TEMPLATE_MEMBERS)
	template<typename Iter1, typename Iter2>
	Dilator( Iter1 ibegin, Iter1 iend, Iter2 tbegin );
#else
    inline
	Dilator( const double * ibegin, const double * iend, const double * tbegin );
#endif

	//	Use compiler-generated copy, assign, and destroy.
	
//	-- mutation --
	
	//!	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.
	//!	
	//!	\param 	i is an initial, or source, time point
	//!	\param 	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.	
	void insert( double i, double t );
	
//	-- dilation --

	//!	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.)
	//!
	//!	\param	p is the Partial to dilate.
	void dilate( Partial & p ) const;
	 
	//!	Function call operator: same as dilate( Partial & p ).
	void operator() ( Partial & p ) 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. 
	//!
	//!	\param	m is the Marker whose time should be recomputed.
	void dilate( Marker & m ) const;
	 
	//!	Function call operator: same as dilate( Marker & p ).
	void operator() ( Marker & m ) 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. 
	//!
	//!	\param dilate_begin is the beginning of a sequence of Partials to dilate.
	//!	\param 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.
	//!	
	//!	\sa Dilator::dilate( Partial & p ) const
	//!	\sa Dilator::dilate( Marker & m ) const
#if ! defined(NO_TEMPLATE_MEMBERS)
	template<typename Iter>
	void dilate( Iter dilate_begin, Iter dilate_end  ) const;
#else
    inline
	void dilate( PartialList::iterator dilate_begin, 
				    PartialList::iterator dilate_end  ) const;
#endif
	 
	//!	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.
	//!	
	//!	\sa Dilator::dilate( Partial & p ) const
	//!	\sa Dilator::dilate( Marker & m ) const
#if ! defined(NO_TEMPLATE_MEMBERS)
	template<typename Iter>
	void operator() ( Iter dilate_begin, Iter dilate_end  ) const;
#else
    inline
	void operator() ( PartialList::iterator dilate_begin, 
					      PartialList::iterator dilate_end ) const;
#endif
	 
	//!	Return the dilated time value corresponding to the specified initial time.
	//! 
	//!	\param currentTime is a pre-dilated time.
	//! \return the dilated time corresponding to the initial time currentTime
    double warpTime( double currentTime ) const;

// -- static members --

   //!   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.
  	//!
	//!	\param   dilate_begin is the beginning of a sequence of Partials to dilate.
	//!	\param   dilate_end is (one-past) the end of a sequence of Partials to dilate.
	//!	\param 	ibegin is the beginning of a sequence of initial, or source,
	//!	         time points.
	//!	\param 	iend is (one-past) the end of a sequence of initial, or
	//!	         source, time points.
	//!	\param 	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..
	//!	
	//!	\sa Dilator::dilate( Partial & p ) const
	//!	\sa Dilator::dilate( Marker & m ) const
#if ! defined(NO_TEMPLATE_MEMBERS)
	template< typename PartialsIter, typename TimeIter1, typename TimeIter2 >
	static 
	void dilate( PartialsIter dilate_begin, PartialsIter dilate_end,
	             TimeIter1 ibegin, TimeIter1 iend, TimeIter2 tbegin  );
#else
    static inline
 	void dilate( PartialList::iterator dilate_begin, 
				 PartialList::iterator dilate_end,
		   		 const double * ibegin, const double * iend, 
				 const double * tbegin  );
#endif

};	//	end of class Dilator


// ---------------------------------------------------------------------------
//	constructor (sequences of time points)
// ---------------------------------------------------------------------------
//!	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.
//!	
//!	\param 	ibegin is the beginning of a sequence of initial, or source,
//!	        time points.
//!	\param 	iend is (one-past) the end of a sequence of initial, or
//!	        source, time points.
//!	\param 	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.
//
#if ! defined(NO_TEMPLATE_MEMBERS)
template<typename Iter1, typename Iter2>
Dilator::Dilator( Iter1 ibegin, Iter1 iend, Iter2 tbegin )
#else
inline
Dilator::Dilator( const double * ibegin, const double * iend, const double * tbegin )
#endif
{
	while ( ibegin != iend )
	{
		insert( *ibegin++, *tbegin++ );
	}
}

// ---------------------------------------------------------------------------
//	dilate (sequence of Partials or Markers)
// ---------------------------------------------------------------------------
//!	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. 
//!
//!	\param dilate_begin is the beginning of a sequence of Partials to dilate.
//!	\param 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.
//!	
//!	\sa Dilator::dilate( Partial & p ) const
//!	\sa Dilator::dilate( Marker & m ) const
//
#if ! defined(NO_TEMPLATE_MEMBERS)
template<typename Iter>
void Dilator::dilate( Iter dilate_begin, Iter dilate_end  ) const
#else
inline
void Dilator::dilate( PartialList::iterator dilate_begin, 
					  PartialList::iterator dilate_end  ) const
#endif
{
	while ( dilate_begin != dilate_end )
	{
		dilate( *(dilate_begin++) );
	}
}

// ---------------------------------------------------------------------------
//	Function call operator (sequence of Partials or Markers)
// ---------------------------------------------------------------------------
//!	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.
//!	
//!	\sa Dilator::dilate( Partial & p ) const
//!	\sa Dilator::dilate( Marker & m ) const
//	 
#if ! defined(NO_TEMPLATE_MEMBERS)
template<typename Iter>
void Dilator::operator() ( Iter dilate_begin, Iter dilate_end  ) const
#else
inline
void Dilator::operator() ( PartialList::iterator dilate_begin, 
						   PartialList::iterator dilate_end ) const
#endif
{ 
	dilate( dilate_begin, dilate_end ); 
}

// ---------------------------------------------------------------------------
//	Function call operator (single Partial)
// ---------------------------------------------------------------------------
//!	Function call operator: same as dilate( Partial & p ).
//!	
//!	\sa Dilator::dilate( Partial & p ) const
//
inline 
void Dilator::operator() ( Partial & p ) const
{ 
	dilate( p ); 
}

// ---------------------------------------------------------------------------
//	Function call operator (single Marker)
// ---------------------------------------------------------------------------
//!	Function call operator: same as dilate( Marker & m ).
//!	
//!	\sa Dilator::dilate( Marker & m ) const
//
inline 
void Dilator::operator() ( Marker & m ) const
{ 
	dilate( m ); 
}

// ---------------------------------------------------------------------------
//	dilate (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.
//!
//!	\param   dilate_begin is the beginning of a sequence of Partials to dilate.
//!	\param   dilate_end is (one-past) the end of a sequence of Partials to dilate.
//!	\param 	ibegin is the beginning of a sequence of initial, or source,
//!	         time points.
//!	\param 	iend is (one-past) the end of a sequence of initial, or
//!	         source, time points.
//!	\param 	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..
//!	
//!	\sa Dilator::dilate( Partial & p ) const
//!	\sa Dilator::dilate( Marker & m ) const
//
#if ! defined(NO_TEMPLATE_MEMBERS)
template< typename PartialsIter, typename TimeIter1, typename TimeIter2 >
void Dilator::dilate( PartialsIter dilate_begin, PartialsIter dilate_end,
			 		  TimeIter1 ibegin, TimeIter1 iend, TimeIter2 tbegin  )
#else
inline
void Dilator::dilate( PartialList::iterator dilate_begin, 
			 		  PartialList::iterator dilate_end,
			 		  const double * ibegin, const double * iend, 
			 		  const double * tbegin  )
#endif
{ 
  	Dilator instance( ibegin, iend, tbegin );
	instance.dilate( dilate_begin, dilate_end ); 
}

}	//	end of namespace Loris

#endif /* ndef INCLUDE_DILATOR_H */