Loris::Morpher Class Reference

#include <Morpher.h>

List of all members.

Classes
struct	MorphingPair
Public Member Functions
	Morpher (const Envelope &f)
	Morpher (const Envelope &ff, const Envelope &af, const Envelope &bwf)
	Morpher (const Morpher &rhs)
	~Morpher (void)
	Destroy this Morpher.
Morpher &	operator= (const Morpher &rhs)
Partial	morphPartials (Partial src, Partial tgt, int assignLabel)
Partial	morphPartial (Partial src, Partial tgt, int assignLabel)
void	morph (PartialList::const_iterator beginSrc, PartialList::const_iterator endSrc, PartialList::const_iterator beginTgt, PartialList::const_iterator endTgt)
void	crossfade (PartialList::const_iterator beginSrc, PartialList::const_iterator endSrc, PartialList::const_iterator beginTgt, PartialList::const_iterator endTgt, Partial::label_type label=0)
Breakpoint	morphBreakpoints (Breakpoint srcBkpt, Breakpoint tgtBkpt, double time) const
Breakpoint	morphSrcBreakpoint (const Breakpoint &bp, const Partial &tgtPartial, double time) const
Breakpoint	morphTgtBreakpoint (const Breakpoint &bp, const Partial &srcPartial, double time) const
Breakpoint	fadeSrcBreakpoint (Breakpoint bp, double time) const
Breakpoint	fadeTgtBreakpoint (Breakpoint bp, double time) const
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
	DEPRECATED.
void	setAmplitudeShape (double x)
	DEPRECATED.
void	enableLogAmpMorphing (bool enable=true)
void	enableLogFreqMorphing (bool enable=true)
double	minBreakpointGap (void) const
void	setMinBreakpointGap (double x)
const Partial &	sourceReferencePartial (void) const
Partial &	sourceReferencePartial (void)
const Partial &	targetReferencePartial (void) const
Partial &	targetReferencePartial (void)
void	setSourceReferencePartial (const Partial &p=Partial())
void	setSourceReferencePartial (const PartialList &partials, Partial::label_type refLabel)
void	setTargetReferencePartial (const Partial &p=Partial())
void	setTargetReferencePartial (const PartialList &partials, Partial::label_type refLabel)
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.
Static Public Attributes
static const double	DefaultFixThreshold
static const double	DefaultAmpShape
static const double	DefaultBreakpointGap

---

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

)

if true, frequencies are morphed in the log domain, if false (default) they are morphed in the linear domain. 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

DEPRECATED.

Return the shaping parameter for the amplitude moprhing function (only used in log-amplitude morphing).

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).

void Loris::Morpher::enableLogAmpMorphing

(

bool

enable = true

)

[inline]

Enable (or disable) log-domain amplitude and bandwidth morphing. Default is true.

void Loris::Morpher::enableLogFreqMorphing

(

bool

enable = true

)

[inline]

Enable (or disable) log-domain frequency morphing. Default is false.

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, morphPartials

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	(	Breakpoint	srcBkpt,
		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	(	Partial	src,
		Partial	tgt,
		int	assignLabel
	)			[inline]

Bad legacy name for morphPartials.

Deprecated:

Use morphPartials instead.

Partial Loris::Morpher::morphPartials	(	Partial	src,
		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).

DEPRECATED do not use.

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).

DEPRECATED do not use.

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

)

Make this Morpher a duplicate of rhs.

Parameters:

rhs

is the Morpher to duplicate

void Loris::Morpher::setAmplitudeShape

(

double

x

)

DEPRECATED.

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.

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::setSourceReferencePartial	(	const PartialList &	partials,
		Partial::label_type	refLabel
	)

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.

Parameters:

	partials	a sequence of Partials to search for the reference Partial
	refLabel	the label of the Partial in partials that should be selected as the reference

void Loris::Morpher::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. 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 Loris::Morpher::setTargetReferencePartial	(	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. A default (empty) Partial indicates that no reference Partial should be used for the target sequence.

Parameters:

	partials	a sequence of Partials to search for the reference Partial
	refLabel	the label of the Partial in partials that should be selected as the reference

void Loris::Morpher::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. 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.

Partial& Loris::Morpher::sourceReferencePartial

(

void

)

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& Loris::Morpher::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& Loris::Morpher::targetReferencePartial

(

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& Loris::Morpher::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.

---

Member Data Documentation

const double Loris::Morpher::DefaultAmpShape [static]

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.

const double Loris::Morpher::DefaultBreakpointGap [static]

Default minimum time (sec) between Breakpoints in morphed Partials. Change from default using setMinBreakpointGap.

const double Loris::Morpher::DefaultFixThreshold [static]

Amplitude threshold (dB) below which Partial frequencies are corrected using the reference Partial frequency envelope (if specified).

---

The documentation for this class was generated from the following file:

• /Users/kfitz/Projects/Loris/Loris development/src/Morpher.h