Loris::Morpher Class Reference

Class Morpher performs sound morphing and Partial parameter envelope interpolation according to a trio of frequency, amplitude, and bandwidth morphing functions, described by Envelopes. More...

#include <Morpher.h>

List of all members.

Public Member Functions
	Morpher (const Envelope &f)
	Construct a new Morpher using the same morphing envelope for frequency, amplitude, and bandwidth (noisiness).
	Morpher (const Envelope &ff, const Envelope &af, const Envelope &bwf)
	Construct a new Morpher using the specified morphing envelopes for frequency, amplitude, and bandwidth (noisiness).
	Morpher (const Morpher &rhs)
	Construct a new Morpher that is a duplicate of rhs.
	~Morpher (void)
	Destroy this Morpher.
Morpher &	operator= (const Morpher &rhs)
Partial	morphPartial (const Partial &src, const Partial &tgt, int assignLabel)
	Morph a pair of Partials to yield a new morphed Partial.
void	morph (PartialList::const_iterator beginSrc, PartialList::const_iterator endSrc, PartialList::const_iterator beginTgt, PartialList::const_iterator endTgt)
	Morph two sounds (collections of Partials labeled to indicate correspondences) into a single labeled collection of Partials.
void	crossfade (PartialList::const_iterator beginSrc, PartialList::const_iterator endSrc, PartialList::const_iterator beginTgt, PartialList::const_iterator endTgt, Partial::label_type label=0)
	Crossfade Partials with no correspondences.
Breakpoint	morphBreakpoints (const Breakpoint &srcBkpt, const Breakpoint &tgtBkpt, double time) const
	Compute morphed parameter values at the specified time, using the source and target Breakpoints (assumed to correspond exactly to the specified time).
Breakpoint	morphSrcBreakpoint (const Breakpoint &bp, const Partial &tgtPartial, 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).
Breakpoint	morphTgtBreakpoint (const Breakpoint &bp, const Partial &srcPartial, 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).
Breakpoint	fadeSrcBreakpoint (Breakpoint bp, 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.
Breakpoint	fadeTgtBreakpoint (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.
void	setFrequencyFunction (const Envelope &f)
	Assign a new frequency morphing envelope to this Morpher.
void	setAmplitudeFunction (const Envelope &f)
	Assign a new amplitude morphing envelope to this Morpher.
void	setBandwidthFunction (const Envelope &f)
	Assign a new bandwidth morphing envelope to this Morpher.
const Envelope &	frequencyFunction (void) const
	Return a reference to this Morpher's frequency morphing envelope.
const Envelope &	amplitudeFunction (void) const
	Return a reference to this Morpher's amplitude morphing envelope.
const Envelope &	bandwidthFunction (void) const
	Return a reference to this Morpher's bandwidth morphing envelope.
double	amplitudeShape (void) const
	Return the shaping parameter for the amplitude moprhing function (only used in new log-amplitude morphing).
void	setAmplitudeShape (double x)
	Set the shaping parameter for the amplitude moprhing function (only used in new log-amplitude morphing).
double	minBreakpointGap (void) const
	Return the minimum time gap (secs) between two Breakpoints in the morphed Partials.
void	setMinBreakpointGap (double x)
	Set the minimum time gap (secs) between two Breakpoints in the morphed Partials.
Partial::label_type	sourceReferenceLabel (void) const
	Return the label of the Partial to be used as a reference Partial for the source sequence in a morph of two Partial sequences.
Partial::label_type	targetReferenceLabel (void) const
	Return the label of the Partial to be used as a reference Partial for the target sequence in a morph of two Partial sequences.
void	setSourceReferenceLabel (Partial::label_type l)
	Set the label of the Partial to be used as a reference Partial for the source sequence in a morph of two Partial sequences.
void	setTargetReferenceLabel (Partial::label_type l)
	Set the label of the Partial to be used as a reference Partial for the target sequence in a morph of two Partial sequences.
PartialList &	partials (void)
	Return a reference to this Morpher's list of morphed Partials.
const PartialList &	partials (void) const
	Return a const reference to this Morpher's list of morphed Partials.

---

Detailed Description

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.

---

Constructor & Destructor Documentation

Loris::Morpher::Morpher (  const Envelope &  f  )

Construct a new Morpher using the same morphing envelope for frequency, amplitude, and bandwidth (noisiness). Parameters: f  is the Envelope to clone for all three morphing functions.

Loris::Morpher::Morpher (  const Envelope &  ff, const Envelope &  af, const Envelope &  bwf )

Construct a new Morpher using the specified morphing envelopes for frequency, amplitude, and bandwidth (noisiness). Parameters: ff  is the Envelope to clone for the frequency morphing function af  is the Envelope to clone for the amplitude morphing function bwf  is the Envelope to clone for the bandwidth morphing function

Loris::Morpher::Morpher (  const Morpher &  rhs  )

Construct a new Morpher that is a duplicate of rhs. Parameters: rhs  is the Morpher to duplicate

---

Member Function Documentation

double Loris::Morpher::amplitudeShape (  void   )  const

Return the shaping parameter for the amplitude moprhing function (only used in new log-amplitude morphing). This shaping parameter controls the slope of the amplitude morphing function, for values greater than 1, this function gets nearly linear (like the old amplitude morphing function), for values much less than 1 (e.g. 1E-5) the slope is gently curved and sounds pretty "linear", for very small values (e.g. 1E-12) the curve is very steep and sounds un-natural because of the huge jump from zero amplitude to very small amplitude.

void Loris::Morpher::crossfade (  PartialList::const_iterator  beginSrc, PartialList::const_iterator  endSrc, PartialList::const_iterator  beginTgt, PartialList::const_iterator  endTgt, Partial::label_type  label = 0 )

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. Parameters: beginSrc  is the beginning of the sequence of Partials corresponding to a morph function value of 0. endSrc  is (one past) the end of the sequence of Partials corresponding to a morph function value of 0. beginTgt  is the beginning of the sequence of Partials corresponding to a morph function value of 1. endTgt  is (one past) the end of the sequence of Partials corresponding to a morph function value of 1. label  is the label to associate with unlabeled Partials (default is 0).

Breakpoint Loris::Morpher::fadeSrcBreakpoint (  Breakpoint  bp, 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. Parameters: bp  is the Breakpoint corresponding to a morph function value of 0. time  is the time corresponding to bp (used to evaluate the morphing functions). Returns: the faded Breakpoint

Breakpoint Loris::Morpher::fadeTgtBreakpoint (  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. Parameters: bp  is the Breakpoint corresponding to a morph function value of 1. time  is the time corresponding to bp (used to evaluate the morphing functions). Returns: the faded Breakpoint

double Loris::Morpher::minBreakpointGap (  void   )  const

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.

void Loris::Morpher::morph (  PartialList::const_iterator  beginSrc, PartialList::const_iterator  endSrc, PartialList::const_iterator  beginTgt, PartialList::const_iterator  endTgt )

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. See also: crossfade, morphPartial Parameters: beginSrc  is the beginning of the sequence of Partials corresponding to a morph function value of 0. endSrc  is (one past) the end of the sequence of Partials corresponding to a morph function value of 0. beginTgt  is the beginning of the sequence of Partials corresponding to a morph function value of 1. endTgt  is (one past) the end of the sequence of Partials corresponding to a morph function value of 1.

Breakpoint Loris::Morpher::morphBreakpoints (  const Breakpoint &  srcBkpt, const Breakpoint &  tgtBkpt, double  time )  const

Compute morphed parameter values at the specified time, using the source and target Breakpoints (assumed to correspond exactly to the specified time). Parameters: srcBkpt  is the Breakpoint corresponding to a morph function value of 0. tgtBkpt  is the Breakpoint corresponding to a morph function value of 1. time  is the time corresponding to srcBkpt (used to evaluate the morphing functions and tgtPartial). Returns: the morphed Breakpoint

Partial Loris::Morpher::morphPartial (  const Partial &  src, const Partial &  tgt, int  assignLabel )

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. Parameters: src  is the Partial corresponding to a morph function value of 0, evaluated at the specified time. tgt  is the Partial corresponding to a morph function value of 1, evaluated at the specified time. assignLabel  is the label assigned to the morphed Partial Returns: the morphed Partial

Breakpoint Loris::Morpher::morphSrcBreakpoint (  const Breakpoint &  bp, const Partial &  tgtPartial, 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). Precondition: the target Partial may not be a dummy Partial (no Breakpoints). Parameters: bp  is the Breakpoint corresponding to a morph function value of 0. tgtPartial  is the Partial corresponding to a morph function value of 1, evaluated at the specified time. time  is the time corresponding to srcBkpt (used to evaluate the morphing functions and tgtPartial). Returns: the morphed Breakpoint

Breakpoint Loris::Morpher::morphTgtBreakpoint (  const Breakpoint &  bp, const Partial &  srcPartial, 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). Precondition: the source Partial may not be a dummy Partial (no Breakpoints). Parameters: bp  is the Breakpoint corresponding to a morph function value of 1. srcPartial  is the Partial corresponding to a morph function value of 0, evaluated at the specified time. time  is the time corresponding to srcBkpt (used to evaluate the morphing functions and tgtPartial). Returns: the morphed Breakpoint

Morpher& Loris::Morpher::operator= (  const Morpher &  rhs  )

Parameters: rhs  is the Morpher to duplicate

void Loris::Morpher::setAmplitudeShape (  double  x  )

Set the shaping parameter for the amplitude moprhing function (only used in new log-amplitude morphing). This shaping parameter controls the slope of the amplitude morphing function, for values greater than 1, this function gets nearly linear (like the old amplitude morphing function), for values much less than 1 (e.g. 1E-5) the slope is gently curved and sounds pretty "linear", for very small values (e.g. 1E-12) the curve is very steep and sounds un-natural because of the huge jump from zero amplitude to very small amplitude. Parameters: x  is the new shaping parameter, it must be positive.

void Loris::Morpher::setMinBreakpointGap (  double  x  )

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. Parameters: x  is the new minimum gap in seconds, it must be positive Exceptions: InvalidArgument  if the specified gap is not positive

void Loris::Morpher::setSourceReferenceLabel (  Partial::label_type  l  )

Set the label of 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. Setting the reference label to 0 indicates that no reference Partial should be used for the source sequence.

void Loris::Morpher::setTargetReferenceLabel (  Partial::label_type  l  )

Set the label of 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. Setting the reference label to 0 indicates that no reference Partial should be used for the target sequence.

Partial::label_type Loris::Morpher::sourceReferenceLabel (  void   )  const

Return the label of 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 default label of 0 indicates that no reference Partial should be used for the source sequence.

Partial::label_type Loris::Morpher::targetReferenceLabel (  void   )  const

Return the label of 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 default label of 0 indicates that no reference Partial should be used for the target sequence.

---