#ifndef INCLUDE_CHANNELIZER_H
#define INCLUDE_CHANNELIZER_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
*
*
* Channelizer.h
*
* Definition of class Loris::Channelizer.
*
* Kelly Fitz, 21 July 2000
* loris@cerlsoundgroup.org
*
* http://www.cerlsoundgroup.org/Loris/
*
*/
#include "PartialList.h"
#include <memory>
// begin namespace
namespace Loris {
class Envelope;
class Partial;
// ---------------------------------------------------------------------------
// Channelizer
//
//! Class Channelizer represents an algorithm for automatic labeling of
//! a sequence of Partials. Partials must be labeled in
//! preparation for morphing (see Morpher) to establish correspondences
//! between Partials in the morph source and target sounds.
//!
//! Channelized partials are labeled according to their adherence to a
//! harmonic frequency structure with a time-varying fundamental
//! frequency. The frequency spectrum is partitioned into
//! non-overlapping channels having time-varying center frequencies that
//! are harmonic (integer) multiples of a specified reference frequency
//! envelope, and each channel is identified by a unique label equal to
//! its harmonic number. Each Partial is assigned the label
//! corresponding to the channel containing the greatest portion of its
//! (the Partial's) energy.
//!
//! A reference frequency Envelope for channelization and the channel
//! number to which it corresponds (1 for an Envelope that tracks the
//! Partial at the fundamental frequency) must be specified. The
//! reference Envelope can be constructed explcitly, point by point
//! (using, for example, the BreakpointEnvelope class), or constructed
//! automatically using the FrequencyReference class.
//!
//! The Channelizer can be configured with a stretch factor, to accomodate
//! detuned harmonics, as in the case of piano tones. The static member
//! computeStretchFactor can compute the apppropriate stretch factor, given
//! a pair of partials. This computation is based on formulae given in
//! "Understanding the complex nature of the piano tone" by Martin Keane
//! at the Acoustics Research Centre at the University of Aukland (Feb 2004).
//! The stretching factor must be non-negative (and is zero for perfectly
//! tunes harmonics). Even in the case of stretched harmonics, the
//! reference frequency envelope is assumed to track the frequency of
//! one of the partials, and the center frequency of the corresponding
//! channel, even though it may represent a stretched harmonic.
//!
//! Channelizer is a leaf class, do not subclass.
//
class Channelizer
{
// -- implementaion --
std::auto_ptr< Envelope > _refChannelFreq; //! the reference frequency envelope
int _refChannelLabel; //! the channel number corresponding to the
//! reference frequency (1 for the fundamental)
double _stretchFactor; //! stretching factor to account for
//! detuned harmonics, as in the case of the piano;
//! can be computed using the static member
//! computeStretchFactor. Should be 0 for most
//! (strongly harmonic) sounds.
double _ampWeighting; //! exponent for amplitude weighting in channel
//! computation, 0 for no weighting, 1 for linear
//! amplitude weighting, 2 for power weighting, etc.
//! default is 0, amplitude weighting is a bad idea
//! for many sounds
// -- public interface --
public:
// -- construction --
//! Construct a new Channelizer using the specified reference
//! Envelope to represent the a numbered channel. If the sound
//! being channelized is known to have detuned harmonics, a
//! stretching factor can be specified (defaults to 0 for no
//! stretching). The stretching factor can be computed using
//! the static member computeStretchFactor.
//!
//! \param refChanFreq is an Envelope representing the center frequency
//! of a channel.
//! \param refChanLabel is the corresponding channel number (i.e. 1
//! if refChanFreq is the lowest-frequency channel, and all
//! other channels are harmonics of refChanFreq, or 2 if
//! refChanFreq tracks the second harmonic, etc.).
//! \param stretchFactor is a stretching factor to account for detuned
//! harmonics, default is 0.
//!
//! \throw InvalidArgument if refChanLabel is not positive.
//! \throw InvalidArgument if stretchFactor is negative.
Channelizer( const Envelope & refChanFreq, int refChanLabel, double stretchFactor = 0 );
//! Construct a new Channelizer having a constant reference frequency.
//! The specified frequency is the center frequency of the lowest-frequency
//! channel (for a harmonic sound, the channel containing the fundamental
//! Partial.
//!
//! \param refFreq is the reference frequency (in Hz) corresponding
//! to the first frequency channel.
//! \param stretchFactor is a stretching factor to account for detuned
//! harmonics, default is 0.
//!
//! \throw InvalidArgument if refChanLabel is not positive.
//! \throw InvalidArgument if stretchFactor is negative.
Channelizer( double refFreq, double stretchFactor = 0 );
//! Construct a new Channelizer that is an exact copy of another.
//! The copy represents the same set of frequency channels, constructed
//! from the same reference Envelope and channel number.
//!
//! \param other is the Channelizer to copy
Channelizer( const Channelizer & other );
//! Assignment operator: make this Channelizer an exact copy of another.
//! This Channelizer is made to represent the same set of frequency channels,
//! constructed from the same reference Envelope and channel number as rhs.
//!
//! \param rhs is the Channelizer to copy
Channelizer & operator=( const Channelizer & rhs );
//! Destroy this Channelizer.
~Channelizer( void );
// -- channelizing --
//! Label a Partial with the number of the frequency channel containing
//! the greatest portion of its (the Partial's) energy.
//!
//! \param partial is the Partial to label.
void channelize( Partial & partial ) const;
//! Assign each Partial in the specified half-open (STL-style) range
//! the label corresponding to the frequency channel containing the
//! greatest portion of its (the Partial's) energy.
//!
//! \param begin is the beginning of the range of Partials to channelize
//! \param end is (one-past) the end of the range of Partials to channelize
//!
//! If compiled with NO_TEMPLATE_MEMBERS defined, then begin and end
//! must be PartialList::iterators, otherwise they can be any type
//! of iterators over a sequence of Partials.
#if ! defined(NO_TEMPLATE_MEMBERS)
template<typename Iter>
void channelize( Iter begin, Iter end ) const;
#else
void channelize( PartialList::iterator begin, PartialList::iterator end ) const;
#endif
//! Function call operator: same as channelize().
#if ! defined(NO_TEMPLATE_MEMBERS)
template<typename Iter>
void operator() ( Iter begin, Iter end ) const
#else
inline
void operator() ( PartialList::iterator begin, PartialList::iterator end ) const
#endif
{ channelize( begin, end ); }
//! Compute the center frequency of one a channel at the specified
//! time. For non-stretched harmonics, this is simply the value
//! of the reference envelope scaled by the ratio of the specified
//! channel number to the reference channel number. For stretched
//! harmonics, the channel center frequency is computed using the
//! stretch factor. See Martin Keane, "Understanding
//! the complex nature of the piano tone", 2004, for a discussion
//! and the source of the mode frequency stretching algorithms
//! implemented here.
//!
//! \param time is the time (in seconds) at which to evalute
//! the reference envelope
//! \param channel is the frequency channel (or harmonic, or vibrational
//! mode) number whose frequency is to be determined
//! \return the center frequency in Hz of the specified frequency channel
//! at the specified time
double channelFrequencyAt( double time, int channel ) const;
//! Compute the (fractional) channel number estimate for a Partial having a
//! given frequency at a specified time. For ordinary harmonics, this
//! is simply the ratio of the specified frequency to the reference
//! frequency at the specified time. For stretched harmonics (as in
//! a piano), the stretching factor is used to compute the frequency
//! of the corresponding modes of a massy string. See Martin Keane,
//! "Understanding the complex nature of the piano tone", 2004, for
//! the source of the mode frequency stretching algorithms
//! implemented here.
//!
//! \param time is the time (in seconds) at which to evalute
//! the reference envelope
//! \param frequency is the frequency (in Hz) for wihch the channel
//! number is to be determined
//! \return the channel number corresponding to the specified
//! frequency and time
int computeChannelNumber( double time, double frequency ) const;
//! Compute the (fractional) channel number estimate for a Partial having a
//! given frequency at a specified time. For ordinary harmonics, this
//! is simply the ratio of the specified frequency to the reference
//! frequency at the specified time. For stretched harmonics (as in
//! a piano), the stretching factor is used to compute the frequency
//! of the corresponding modes of a massy string. See Martin Keane,
//! "Understanding the complex nature of the piano tone", 2004, for
//! the source of the mode frequency stretching algorithms
//! implemented here.
//!
//! The fractional channel number is used internally to determine
//! a best estimate for the channel number (label) for a Partial
//! having time-varying frequency.
//!
//! \param time is the time (in seconds) at which to evalute
//! the reference envelope
//! \param frequency is the frequency (in Hz) for wihch the channel
//! number is to be determined
//! \return the fractional channel number corresponding to the specified
//! frequency and time
double computeFractionalChannelNumber( double time, double frequency ) const;
//! Compute the reference frequency at the specified time. For non-stretched
//! harmonics, this is simply the ratio of the reference envelope evaluated
//! at that time to the reference channel number, and is the center frequecy
//! for the lowest channel. For stretched harmonics, the reference frequency
//! is NOT equal to the center frequency of any of the channels, and is also
//! a function of the stretch factor.
//!
//! \param time is the time (in seconds) at which to evalute
//! the reference envelope
double referenceFrequencyAt( double time ) const;
// -- access/mutation --
//! Return the exponent applied to amplitude before weighting
//! the instantaneous estimate of the frequency channel number
//! for a Partial. zero (default) for no weighting, 1 for linear
//! amplitude weighting, 2 for power weighting, etc.
//! Amplitude weighting is a bad idea for many sounds, particularly
//! those with transients, for which it may emphasize the part of
//! the Partial having the least reliable frequency estimate.
double amplitudeWeighting( void ) const;
//! Set the exponent applied to amplitude before weighting
//! the instantaneous estimate of the frequency channel number
//! for a Partial. zero (default) for no weighting, 1 for linear
//! amplitude weighting, 2 for power weighting, etc.
//! Amplitude weighting is a bad idea for many sounds, particularly
//! those with transients, for which it may emphasize the part of
//! the Partial having the least reliable frequency estimate.
void setAmplitudeWeighting( double expon );
//! Return the stretching factor used to account for detuned
//! harmonics, as in a piano tone. Normally set to 0 for
//! in-tune harmonics.
//!
//! The stretching factor is a small positive number for
//! heavy vibrating strings (as in pianos) for which the
//! mass of the string significantly affects the frequency
//! of the vibrating modes. See Martin Keane, "Understanding
//! the complex nature of the piano tone", 2004, for a discussion
//! and the source of the mode frequency stretching algorithms
//! implemented here.
double stretchFactor( void ) const;
//! Set the stretching factor used to account for detuned
//! harmonics, as in a piano tone. Normally set to 0 for
//! in-tune harmonics. The stretching factor for massy
//! vibrating strings (like pianos) can be computed from
//! the physical characteristics of the string, or using
//! computeStretchFactor().
//!
//! The stretching factor is a small positive number for
//! heavy vibrating strings (as in pianos) for which the
//! mass of the string significantly affects the frequency
//! of the vibrating modes. See Martin Keane, "Understanding
//! the complex nature of the piano tone", 2004, for a discussion
//! and the source of the mode frequency stretching algorithms
//! implemented here.
//!
//! \throw InvalidArgument if stretch is negative.
void setStretchFactor( double stretch );
// -- static members --
//! Static member to compute the stretch factor for a sound having
//! (consistently) detuned harmonics, like piano tones.
//!
//! The stretching factor is a small positive number for
//! heavy vibrating strings (as in pianos) for which the
//! mass of the string significantly affects the frequency
//! of the vibrating modes. See Martin Keane, "Understanding
//! the complex nature of the piano tone", 2004, for a discussion
//! and the source of the mode frequency stretching algorithms
//! implemented here.
//!
//! The value returned by this function MAY NOT be a valid stretch
//! factor. If this function returns a negative stretch factor,
//! then the specified pair of frequencies and mode numbers cannot
//! be used to estimate the effects of string mass on mode frequency
//! (because the negative stretch factor implies a physical
//! impossibility, like negative mass or negative length).
//!
//! \param fm is the frequency of the Mth stretched harmonic
//! \param m is the harmonic number of the harmonic whose frequnecy is fm
//! \param fn is the frequency of the Nth stretched harmonic
//! \param n is the harmonic number of the harmonic whose frequnecy is fn
//! \returns the stretching factor, usually a very small positive
//! floating point number, or 0 for pefectly tuned harmonics
//! (that is, if fn = n*f1).
static double computeStretchFactor( double fm, int m, double fn, int n );
// -- simplified interface --
//! Static member that constructs an instance and applies
//! it to a PartialList (simplified interface).
//!
//! Construct a Channelizer using the specified Envelope
//! and reference label, and use it to channelize a
//! sequence of Partials.
//!
//! \param partials is the sequence of Partials to
//! channelize.
//! \param refChanFreq is an Envelope representing the center frequency
//! of a channel.
//! \param refChanLabel is the corresponding channel number (i.e. 1
//! if refChanFreq is the lowest-frequency channel, and all
//! other channels are harmonics of refChanFreq, or 2 if
//! refChanFreq tracks the second harmonic, etc.).
//! \throw InvalidArgument if refChanLabel is not positive.
static
void channelize( PartialList & partials,
const Envelope & refChanFreq, int refChanLabel );
// -- DEPRECATED members --
//! DEPRECATED
//!
//! Set the stretching factor used to account for (consistently)
//! detuned harmonics, as in a piano tone, from a pair of
//! mode (harmonic) frequencies and numbers.
//!
//! The stretching factor is a small positive number for
//! heavy vibrating strings (as in pianos) for which the
//! mass of the string significantly affects the frequency
//! of the vibrating modes. See Martin Keane, "Understanding
//! the complex nature of the piano tone", 2004, for a discussion
//! and the source of the mode frequency stretching algorithms
//! implemented here.
//!
//! The stretching factor is computed using computeStretchFactor,
//! but only a valid stretch factor will ever be assigned. If an
//! invalid (negative) stretching factor is computed for the
//! specified frequencies and mode numbers, the stretch factor
//! will be set to zero.
//!
//! \param fm is the frequency of the Mth stretched harmonic
//! \param m is the harmonic number of the harmonic whose frequnecy is fm
//! \param fn is the frequency of the Nth stretched harmonic
//! \param n is the harmonic number of the harmonic whose frequnecy is fn
void setStretchFactor( double fm, int m, double fn, int n );
//! DEPRECATED
//!
//! Static member that constructs an instance and applies
//! it to a sequence of Partials.
//! Construct a Channelizer using the specified Envelope
//! and reference label, and use it to channelize a
//! sequence of Partials.
//!
//! \param begin is the beginning of a sequence of Partials to
//! channelize.
//! \param end is the end of a sequence of Partials to
//! channelize.
//! \param refChanFreq is an Envelope representing the center frequency
//! of a channel.
//! \param refChanLabel is the corresponding channel number (i.e. 1
//! if refChanFreq is the lowest-frequency channel, and all
//! other channels are harmonics of refChanFreq, or 2 if
//! refChanFreq tracks the second harmonic, etc.).
//! \throw InvalidArgument if refChanLabel is not positive.
//!
//! If compiled with NO_TEMPLATE_MEMBERS defined, then begin and end
//! must be PartialList::iterators, otherwise they can be any type
//! of iterators over a sequence of Partials.
#if ! defined(NO_TEMPLATE_MEMBERS)
template< typename Iter >
static
void channelize( Iter begin, Iter end,
const Envelope & refChanFreq, int refChanLabel );
#else
static inline
void channelize( PartialList::iterator begin, PartialList::iterator end,
const Envelope & refChanFreq, int refChanLabel );
#endif
//! DEPRECATED
//!
//! Static member to compute the stretch factor for a sound having
//! (consistently) detuned harmonics, like piano tones. Legacy version
//! that assumes the first argument corresponds to the first partial.
//!
//! \param f1 is the frequency of the lowest numbered (1) partial.
//! \param fn is the frequency of the Nth stretched harmonic
//! \param n is the harmonic number of the harmonic whose frequnecy is fn
//! \returns the stretching factor, usually a very small positive
//! floating point number, or 0 for pefectly tuned harmonics
//! (that is, for harmonic frequencies fn = n*f1).
static double computeStretchFactor( double f1, double fn, double n );
}; // end of class Channelizer
// ---------------------------------------------------------------------------
// channelize (sequence of Partials)
// ---------------------------------------------------------------------------
//! Assign each Partial in the specified half-open (STL-style) range
//! the label corresponding to the frequency channel containing the
//! greatest portion of its (the Partial's) energy.
//!
//! \param begin is the beginning of the range of Partials to channelize
//! \param end is (one-past) the end of the range of Partials o channelize
//!
//! If compiled with NO_TEMPLATE_MEMBERS defined, then begin and end
//! must be PartialList::iterators, otherwise they can be any type
//! of iterators over a sequence of Partials.
//
#if ! defined(NO_TEMPLATE_MEMBERS)
template<typename Iter>
void Channelizer::channelize( Iter begin, Iter end ) const
#else
inline
void Channelizer::channelize( PartialList::iterator begin, PartialList::iterator end ) const
#endif
{
while ( begin != end )
{
channelize( *begin++ );
}
}
// ---------------------------------------------------------------------------
// channelize (static)
// ---------------------------------------------------------------------------
//! DEPRECATED
//!
//! Static member that constructs an instance and applies
//! it to a sequence of Partials.
//! Construct a Channelizer using the specified Envelope
//! and reference label, and use it to channelize a
//! sequence of Partials.
//!
//! \param begin is the beginning of a sequence of Partials to
//! channelize.
//! \param end is the end of a sequence of Partials to
//! channelize.
//! \param refChanFreq is an Envelope representing the center frequency
//! of a channel.
//! \param refChanLabel is the corresponding channel number (i.e. 1
//! if refChanFreq is the lowest-frequency channel, and all
//! other channels are harmonics of refChanFreq, or 2 if
//! refChanFreq tracks the second harmonic, etc.).
//! \throw InvalidArgument if refChanLabel is not positive.
//!
//! If compiled with NO_TEMPLATE_MEMBERS defined, then begin and end
//! must be PartialList::iterators, otherwise they can be any type
//! of iterators over a sequence of Partials.
//
#if ! defined(NO_TEMPLATE_MEMBERS)
template< typename Iter >
void Channelizer::channelize( Iter begin, Iter end,
const Envelope & refChanFreq, int refChanLabel )
#else
inline
void Channelizer::channelize( PartialList::iterator begin, PartialList::iterator end,
const Envelope & refChanFreq, int refChanLabel )
#endif
{
Channelizer instance( refChanFreq, refChanLabel );
while ( begin != end )
{
instance.channelize( *begin++ );
}
}
} // end of namespace Loris
#endif /* ndef INCLUDE_CHANNELIZER_H */