path: root/src/loris/Morpher.h

#ifndef INCLUDE_MORPHER_H
#define INCLUDE_MORPHER_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
 *
 *
 * Morpher.h
 *
 * Definition of class Morpher.
 *
 * Kelly Fitz, 15 Oct 1999
 * loris@cerlsoundgroup.org
 *
 * http://www.cerlsoundgroup.org/Loris/
 *
 */
#include "PartialList.h"
#include "Partial.h"

#include <memory>   // for auto_ptr

//  begin namespace
namespace Loris {

class Envelope;

// ---------------------------------------------------------------------------
//  Class Morpher
//
//! Class Morpher performs sound morphing and Partial parameter
//! envelope interpolation according to a trio of frequency, amplitude,
//! and bandwidth morphing functions, described by Envelopes.
//! Sound morphing is achieved by interpolating the time-varying 
//! frequencies, amplitudes, and bandwidths of corresponding partials 
//! obtained from reassigned bandwidth-enhanced analysis of the source 
//! and target sounds. Partial correspondences may be established by 
//! labeling, using instances of the Channelizer and Distiller classes.
//!
//! The Morpher collects morphed Partials in a PartialList, that is
//! accessible to clients.
//!
//! For more information about sound morphing using 
//! the Reassigned Bandwidth-Enhanced Additive Sound 
//! Model, refer to the Loris website: 
//! www.cerlsoundgroup.org/Loris/.
//! 
//! Morpher is a leaf class, do not subclass.
//
class Morpher
{
//  -- instance variables --

    std::auto_ptr< Envelope > _freqFunction;  //!   frequency morphing function
    std::auto_ptr< Envelope > _ampFunction;   //!   amplitude morphing function
    std::auto_ptr< Envelope > _bwFunction;    //!   bandwidth morphing function
    
    PartialList _partials;                    //!   collect Partials here
    
    Partial _srcRefPartial;         //! reference Partials
    Partial _tgtRefPartial;         //! for source and target sounds when 
                                    //! morphing sequences of labeled Partials,
                                    //! default (empty Partial) implies no 
                                    //! reference Partial is used

    double _freqFixThresholdDb;     //! amplitude threshold below which Partial
                                    //! frequencies are corrected according to
                                    //! a reference Partial, if specified.
    
    double _logMorphShape;          //! shaping parameter that controls the 
                                    //! shape of the logarithmic morphing function,
                                    //! mostly when one of the source values
                                    //! is equal to zero. 
                                    //! Only relevant when _doLogAmpMorphing is true.
                                    //!
                                    //! Don't use this for anything, just leave it 
                                    //! at the default.
                                                            
    double _minBreakpointGapSec;    //! the minimum time gap between two Breakpoints
                                    //! in the morphed Partials. Morphing two
                                    //! Partials can generate a third Partial having
                                    //! Breakpoints arbitrarily close together in time,
                                    //! and this makes morphs huge. Raising this 
                                    //! threshold limits the Breakpoint density in
                                    //! the morphed Partials. 
                                    //! Default is 1/10 ms.
                                    
                                    
    bool _doLogAmpMorphing;         //! if true (default), amplitudes and bandwidths 
                                    //! are morphed in the log domain, if false they 
                                    //! are morphed in the linear domain.
                                    
    bool _doLogFreqMorphing;        //! if true, frequencies are morphed in the log 
                                    //! domain, if false (default) they  are morphed  
                                    //! in the linear domain.
    
    
//  -- public interface --
public:
//  -- construction --

    //! Construct a new Morpher using the same morphing envelope for 
    //! frequency, amplitude, and bandwidth (noisiness).
    //! 
    //! \param  f is the Envelope to clone for all three morphing 
    //!            functions.
    Morpher( const Envelope & f );

    //! Construct a new Morpher using the specified morphing envelopes for
    //! frequency, amplitude, and bandwidth (noisiness).
    //!
    //! \param  ff is the Envelope to clone for the frequency morphing function
    //! \param  af is the Envelope to clone for the amplitude morphing function
    //! \param  bwf is the Envelope to clone for the bandwidth morphing function    
    Morpher( const Envelope & ff, const Envelope & af, const Envelope & bwf );

    //! Construct a new Morpher that is a duplicate of rhs.
    //!
    //! \param  rhs is the Morpher to duplicate
    Morpher( const Morpher & rhs );
    
    //! Destroy this Morpher.
    ~Morpher( void );
    
   //! Make this Morpher a duplicate of rhs.
    //!
    //! \param  rhs is the Morpher to duplicate
    Morpher & operator= ( const Morpher & rhs );

//  -- morphed parameter computation --

//  -- Partial morphing --

    //! Morph a pair of Partials to yield a new morphed Partial. 
    //! Dummy Partials (having no Breakpoints) don't contribute to the
    //! morph, except to cause their opposite to fade out. 
    //! Either (or neither) the source or target Partial may be a dummy 
    //! Partial (no Breakpoints), but not both. The morphed
    //! Partial has Breakpoints at times corresponding to every Breakpoint 
    //! in both source Partials, omitting Breakpoints that would be
    //!   closer than the minBreakpointGap to their predecessor. 
    //! The new morphed Partial is assigned the specified label and returned.
    //!
    //! \param  src is the Partial corresponding to a morph function
    //!         value of 0, evaluated at the specified time.
    //! \param  tgt is the Partial corresponding to a morph function
    //!         value of 1, evaluated at the specified time.
    //! \param  assignLabel is the label assigned to the morphed Partial
    //! \return the morphed Partial
    Partial morphPartials( Partial src, Partial tgt, int assignLabel );
    
    //! Bad legacy name for morphPartials.
    //! \deprecated Use morphPartials instead.
    Partial morphPartial( Partial src, Partial tgt, int assignLabel )
        { return morphPartials( src, tgt, assignLabel ); }

    //! Morph two sounds (collections of Partials labeled to indicate
    //! correspondences) into a single labeled collection of Partials.
    //! Unlabeled Partials (having label 0) are crossfaded. The morphed
    //! and crossfaded Partials are stored in the Morpher's PartialList.
    //!
    //! The Partials in the first range are treated as components of the 
    //! source sound, corresponding to a morph function value of 0, and  
    //! those in the second are treated as components of the target sound, 
    //! corresponding to a morph function value of 1.
    //!
    //! \sa     crossfade, morphPartials
    //!
    //! \param  beginSrc is the beginning of the sequence of Partials
    //!         corresponding to a morph function value of 0.
    //! \param  endSrc is (one past) the end of the sequence of Partials
    //!         corresponding to a morph function value of 0.
    //! \param  beginTgt is the beginning of the sequence of Partials
    //!         corresponding to a morph function value of 1.
    //! \param  endTgt is (one past) the end of the sequence of Partials
    //!         corresponding to a morph function value of 1.
    void morph( PartialList::const_iterator beginSrc, 
                PartialList::const_iterator endSrc,
                PartialList::const_iterator beginTgt, 
                PartialList::const_iterator endTgt );

    //! Crossfade Partials with no correspondences.
    //!
    //! Unlabeled Partials (having the specified label) are considered to 
    //! have no correspondences, so they are just faded out, and not 
    //! actually morphed. Consistent with the morphing behavior, 
    //! crossfaded Partials are thinned, if necssary, so that no
    //! two Breakpoints are closer in time than the minBreakpointGap.
    //!
    //! The Partials in the first range are treated as components of the 
    //! source sound, corresponding to a morph function value of 0, and  
    //! those in the second are treated as components of the target sound, 
    //! corresponding to a morph function value of 1.
    //!
    //! The crossfaded Partials are stored in the Morpher's PartialList.
    //!
    //! \param  beginSrc is the beginning of the sequence of Partials
    //!         corresponding to a morph function value of 0.
    //! \param  endSrc is (one past) the end of the sequence of Partials
    //!         corresponding to a morph function value of 0.
    //! \param  beginTgt is the beginning of the sequence of Partials
    //!         corresponding to a morph function value of 1.
    //! \param  endTgt is (one past) the end of the sequence of Partials
    //!         corresponding to a morph function value of 1.
    //! \param  label is the label to associate with unlabeled
    //!         Partials (default is 0).
    void crossfade( PartialList::const_iterator beginSrc, 
                    PartialList::const_iterator endSrc,
                    PartialList::const_iterator beginTgt, 
                    PartialList::const_iterator endTgt,
                    Partial::label_type label = 0 );


    //! Compute morphed parameter values at the specified time, using
    //! the source and target Breakpoints (assumed to correspond exactly
    //! to the specified time).
    //!
    //! \param  srcBkpt is the Breakpoint corresponding to a morph function
    //!         value of 0.
    //! \param  tgtBkpt is the Breakpoint corresponding to a morph function
    //!         value of 1.
    //! \param  time is the time corresponding to srcBkpt (used
    //!         to evaluate the morphing functions and tgtPartial).
    //! \return the morphed Breakpoint
    //
    Breakpoint
    morphBreakpoints( Breakpoint srcBkpt, Breakpoint tgtBkpt, 
                      double time  ) const;
                               
    //! Compute morphed parameter values at the specified time, using
    //! the source Breakpoint (assumed to correspond exactly to the
    //! specified time) and the target Partial (whose parameters are
    //! examined at the specified time).
    //!
    //! DEPRECATED do not use.
    //!
    //! \pre    the target Partial may not be a dummy Partial (no Breakpoints).
    //!
    //! \param  bp is the Breakpoint corresponding to a morph function
    //!         value of 0.
    //! \param  tgtPartial is the Partial corresponding to a morph function
    //!         value of 1, evaluated at the specified time.
    //! \param  time is the time corresponding to srcBkpt (used
    //!         to evaluate the morphing functions and tgtPartial).
    //! \return the morphed Breakpoint
    Breakpoint 
    morphSrcBreakpoint( const Breakpoint & bp, const Partial & tgtPartial, 
                        double time ) const;

    //! Compute morphed parameter values at the specified time, using
    //! the target Breakpoint (assumed to correspond exactly to the
    //! specified time) and the source Partial (whose parameters are
    //! examined at the specified time).
    //!
    //! DEPRECATED do not use.
    //!
    //! \pre    the source Partial may not be a dummy Partial (no Breakpoints).
    //!
    //! \param  bp is the Breakpoint corresponding to a morph function
    //!         value of 1.
    //! \param  srcPartial is the Partial corresponding to a morph function
    //!         value of 0, evaluated at the specified time.
    //! \param  time is the time corresponding to srcBkpt (used
    //!         to evaluate the morphing functions and tgtPartial).
    //! \return the morphed Breakpoint
    Breakpoint 
    morphTgtBreakpoint( const Breakpoint & bp, const Partial & srcPartial, 
                        double time ) const;

    //! Compute morphed parameter values at the specified time, using
    //! the source Breakpoint, assumed to correspond exactly to the
    //! specified time, and assuming that there is no corresponding 
    //! target Partial, so the source Breakpoint should be simply faded.
    //!
    //! \param  bp is the Breakpoint corresponding to a morph function
    //!         value of 0.
    //! \param  time is the time corresponding to bp (used
    //!         to evaluate the morphing functions).
    //! \return the faded Breakpoint
    Breakpoint fadeSrcBreakpoint( Breakpoint bp, double time ) const;

    //! Compute morphed parameter values at the specified time, using
    //! the target Breakpoint, assumed to correspond exactly to the
    //! specified time, and assuming that there is not corresponding 
    //! source Partial, so the target Breakpoint should be simply faded.
    //!
    //! \param  bp is the Breakpoint corresponding to a morph function
    //!         value of 1.
    //! \param  time is the time corresponding to bp (used
    //!         to evaluate the morphing functions).
    //! \return the faded Breakpoint
    Breakpoint fadeTgtBreakpoint( Breakpoint bp, double time ) const;
    
//  -- morphing function access/mutation --

    //! Assign a new frequency morphing envelope to this Morpher.
    void setFrequencyFunction( const Envelope & f );
    
    //! Assign a new amplitude morphing envelope to this Morpher.
    void setAmplitudeFunction( const Envelope & f );
    
    //! Assign a new bandwidth morphing envelope to this Morpher.
    void setBandwidthFunction( const Envelope & f );

    //! Return a reference to this Morpher's frequency morphing envelope.
    const Envelope & frequencyFunction( void ) const;
    
    //! Return a reference to this Morpher's amplitude morphing envelope.
    const Envelope & amplitudeFunction( void ) const;
    
    //! Return a reference to this Morpher's bandwidth morphing envelope.
    const Envelope & bandwidthFunction( void ) const;
    
    //! Return the shaping parameter for the amplitude moprhing
    //! function (only used in log-amplitude morphing).
	//!                                                           
    //! DEPRECATED
    double amplitudeShape( void ) const;
    
    //! Set the shaping parameter for the amplitude moprhing
    //! function (only used in log-amplitude morphing).
	//! Only relevant when _doLogAmpMorphing is true.
	//! Don't use this for anything, just leave it 
	//! at the default.
	//!                                                           
    //! DEPRECATED
    void setAmplitudeShape( double x );
    
    //!	Enable (or disable) log-domain amplitude and bandwidth morphing.
    //! Default is true.
    void enableLogAmpMorphing( bool enable = true ) { _doLogAmpMorphing = enable; }
    
    //!	Enable (or disable) log-domain frequency morphing.
    //! Default is false.
    void enableLogFreqMorphing( bool enable = true )  { _doLogFreqMorphing = enable; }
    
    
    //! Return the minimum time gap (secs) between two Breakpoints
    //! in the morphed Partials. Morphing two
    //! Partials can generate a third Partial having
    //! Breakpoints arbitrarily close together in time,
    //! and this makes morphs huge. Raising this 
    //! threshold limits the Breakpoint density in
    //! the morphed Partials. Default is 1/10 ms.
    double minBreakpointGap( void ) const;

    //! Set the minimum time gap (secs) between two Breakpoints
    //! in the morphed Partials. Morphing two
    //! Partials can generate a third Partial having
    //! Breakpoints arbitrarily close together in time,
    //! and this makes morphs huge. Raising this 
    //! threshold limits the Breakpoint density in
    //! the morphed Partials. Default is 1/10 ms.
    //!
    //! \param  x is the new minimum gap in seconds, it must be 
    //!         positive
    //! \throw  InvalidArgument if the specified gap is not positive
    void setMinBreakpointGap( double x );


//  -- reference Partial label access/mutation --
    
    //! Return the Partial to be used as a reference
    //! Partial for the source sequence in a morph of two Partial
    //! sequences. The reference partial is used to compute 
    //! frequencies for very low-amplitude Partials whose frequency
    //! estimates are not considered reliable. The reference Partial
    //! is considered to have good frequency estimates throughout.
    //! A default (empty) Partial indicates that no reference Partial
    //! should be used for the source sequence.
    const Partial & sourceReferencePartial( void ) const;
    
    //! Return the Partial to be used as a reference
    //! Partial for the source sequence in a morph of two Partial
    //! sequences. The reference partial is used to compute 
    //! frequencies for very low-amplitude Partials whose frequency
    //! estimates are not considered reliable. The reference Partial
    //! is considered to have good frequency estimates throughout.
    //! A default (empty) Partial indicates that no reference Partial
    //! should be used for the source sequence.
    Partial & sourceReferencePartial( void );
    
    //! Return the Partial to be used as a reference
    //! Partial for the target sequence in a morph of two Partial
    //! sequences. The reference partial is used to compute 
    //! frequencies for very low-amplitude Partials whose frequency
    //! estimates are not considered reliable. The reference Partial
    //! is considered to have good frequency estimates throughout.
    //! A default (empty) Partial indicates that no reference Partial
    //! should be used for the target sequence.
    const Partial & targetReferencePartial( void ) const;

    //! Return the Partial to be used as a reference
    //! Partial for the target sequence in a morph of two Partial
    //! sequences. The reference partial is used to compute 
    //! frequencies for very low-amplitude Partials whose frequency
    //! estimates are not considered reliable. The reference Partial
    //! is considered to have good frequency estimates throughout.
    //! A default (empty) Partial indicates that no reference Partial
    //! should be used for the target sequence.
    Partial & targetReferencePartial( void );
    
    //! Specify the Partial to be used as a reference
    //! Partial for the source sequence in a morph of two Partial
    //! sequences. The reference partial is used to compute 
    //! frequencies for very low-amplitude Partials whose frequency
    //! estimates are not considered reliable. The reference Partial
    //! is considered to have good frequency estimates throughout.
    //! The specified Partial must be labeled with its harmonic number.
    //! A default (empty) Partial indicates that no reference 
    //! Partial should be used for the source sequence.
    void setSourceReferencePartial( const Partial & p = Partial() );
    
    //! Specify the Partial to be used as a reference
    //! Partial for the source sequence in a morph of two Partial
    //! sequences. The reference partial is used to compute 
    //! frequencies for very low-amplitude Partials whose frequency
    //! estimates are not considered reliable. The reference Partial
    //! is considered to have good frequency estimates throughout.
    //! A default (empty) Partial indicates that no reference 
    //! Partial should be used for the source sequence.
    //!
    //! \param  partials a sequence of Partials to search
    //!         for the reference Partial
    //! \param  refLabel the label of the Partial in partials
    //!         that should be selected as the reference
    void setSourceReferencePartial( const PartialList & partials, 
                                    Partial::label_type refLabel );
    
    //! Specify the Partial to be used as a reference
    //! Partial for the target sequence in a morph of two Partial
    //! sequences. The reference partial is used to compute 
    //! frequencies for very low-amplitude Partials whose frequency
    //! estimates are not considered reliable. The reference Partial
    //! is considered to have good frequency estimates throughout.
    //! The specified Partial must be labeled with its harmonic number.
    //! A default (empty) Partial indicates that no reference 
    //! Partial should be used for the target sequence.
    void setTargetReferencePartial( const Partial & p = Partial() );

    //! Specify the Partial to be used as a reference
    //! Partial for the target sequence in a morph of two Partial
    //! sequences. The reference partial is used to compute 
    //! frequencies for very low-amplitude Partials whose frequency
    //! estimates are not considered reliable. The reference Partial
    //! is considered to have good frequency estimates throughout.
    //! A default (empty) Partial indicates that no reference 
    //! Partial should be used for the target sequence.
    //!
    //! \param  partials a sequence of Partials to search
    //!         for the reference Partial
    //! \param  refLabel the label of the Partial in partials
    //!         that should be selected as the reference
    void setTargetReferencePartial( const PartialList & partials, 
                                    Partial::label_type refLabel );
    
//  -- PartialList access --

    //! Return a reference to this Morpher's list of morphed Partials.
    PartialList & partials( void ); 

    //! Return a const reference to this Morpher's list of morphed Partials.
    const PartialList & partials( void ) const; 

//  -- global morphing defaults and constants --

    //! Amplitude threshold (dB) below which 
    //! Partial frequencies are corrected using
    //! the reference Partial frequency envelope
    //! (if specified).
    static const double DefaultFixThreshold;

    //! Default amplitude shaping parameter, used in
    //! interpolateLogAmplitudes to perform logarithmic 
    //! amplitude morphs. 
    //!
    //! Compile Loris with LINEAR_AMP_MORPHS defined for
    //! legacy-style linear amplitude morphs by default.
    //!
    //! Change from default using setAmplitudeShape.
    static const double DefaultAmpShape;    

    //! Default minimum time (sec) between Breakpoints in 
    //! morphed Partials. 
    //! Change from default using setMinBreakpointGap.
    static const double DefaultBreakpointGap;

private:
    
//  -- helper --

    //  PartialCorrespondence represents a map from non-zero Partial 
    //  labels to pairs of pointers to Partials that should be morphed 
    //  into a single Partial that is assigned that label. 
    //  MorphingPair is a pair of pointers to Partials that are
    //  initialized to zero, and it is the element type for the
    //  PartialCorrespondence map.
    struct MorphingPair
    {
        Partial src;
        Partial tgt;    
    };
    typedef std::map< Partial::label_type, MorphingPair > PartialCorrespondence;
    
    //! Helper function that performs the morph between corresponding pairs
    //! of Partials identified in a PartialCorrespondence. Called by the
    //! morph() implementation accepting two sequences of Partials.
    void morph_aux( PartialCorrespondence & correspondence );
    
    //! Compute morphed parameter values at the specified time, using
    //! the source Breakpoint (assumed to correspond exactly to the
    //! specified time) and the target Partial (whose parameters are
    //! examined at the specified time). Append the morphed Breakpoint
    //! to newp only if the target should contribute to the morph at
    //! the specified time.
    //!
    //! \pre    the target Partial may not be a dummy Partial (no Breakpoints).
    //!
    //! \param  srcBkpt is the Breakpoint corresponding to a morph function
    //!         value of 0.
    //! \param  tgtPartial is the Partial corresponding to a morph function
    //!         value of 1, evaluated at the specified time.
    //! \param  time is the time corresponding to srcBkpt (used
    //!         to evaluate the morphing functions and tgtPartial).
    //! \param  newp is the morphed Partial under construction, the morphed
    //!         Breakpoint is added to this Partial.
    //
    void appendMorphedSrc( Breakpoint srcBkpt, const Partial & tgtPartial, 
                           double time, Partial & newp  );
                           
    //! Compute morphed parameter values at the specified time, using
    //! the target Breakpoint (assumed to correspond exactly to the
    //! specified time) and the source Partial (whose parameters are
    //! examined at the specified time). Append the morphed Breakpoint
    //! to newp only if the target should contribute to the morph at
    //! the specified time.
    //!
    //! \pre    the source Partial may not be a dummy Partial (no Breakpoints).
    //!
    //! \param  tgtBkpt is the Breakpoint corresponding to a morph function
    //!         value of 1.
    //! \param  srcPartial is the Partial corresponding to a morph function
    //!         value of 0, evaluated at the specified time.
    //! \param  time is the time corresponding to srcBkpt (used
    //!         to evaluate the morphing functions and srcPartial).
    //! \param  newp is the morphed Partial under construction, the morphed
    //!         Breakpoint is added to this Partial.
    //
    void appendMorphedTgt( Breakpoint tgtBkpt, const Partial & srcPartial, 
                           double time, Partial & newp  );
                           
                           
	//!	Parameterinterpolation helpers.
	Breakpoint 
	interpolateParameters( const Breakpoint & srcBkpt, const Breakpoint & tgtBkpt,
                           double fweight, double aweight, double bweight ) const;

	double interpolateAmplitude( double srcAmp, double tgtAmp, double alpha ) const;
	double interpolateBandwidth( double srcBw, double tgtBw, double alpha ) const;
	double interpolateFrequency( double srcFreq, double tgtFreq, double alpha ) const;
	double interpolatePhase( double srcphase, double tgtphase, double alpha ) const;
	

	//	Recompute phases for a morphed Partial, so that the synthesized phases 
	//	match the source phases as closesly as possible at times when the 
	//	frequency morphing function is equal to 0 or 1. 
	void fixMorphedPhases( Partial & newp ) const;                           

};  //  end of class Morpher

}   //  end of namespace Loris

#endif /* ndef INCLUDE_MORPHER_H */