Loris::Channelizer Class Reference
#include <Channelizer.h>
List of all members.
Public Member Functions 
 Channelizer (const Envelope &refChanFreq, int refChanLabel, double stretchFactor=0) 
 Channelizer (double refFreq, double stretchFactor=0) 
 Channelizer (const Channelizer &other) 
Channelizer &  operator= (const Channelizer &rhs) 
 ~Channelizer (void) 
 Destroy this Channelizer.

void  channelize (Partial &partial) const 
template<typename Iter > 
void  channelize (Iter begin, Iter end) const 
template<typename Iter > 
void  operator() (Iter begin, Iter end) const 
 Function call operator: same as channelize().

double  channelFrequencyAt (double time, int channel) const 
int  computeChannelNumber (double time, double frequency) const 
double  computeFractionalChannelNumber (double time, double frequency) const 
double  referenceFrequencyAt (double time) const 
double  amplitudeWeighting (void) const 
void  setAmplitudeWeighting (double expon) 
double  stretchFactor (void) const 
void  setStretchFactor (double stretch) 
void  setStretchFactor (double fm, int m, double fn, int n) 
Static Public Member Functions 
static double  computeStretchFactor (double fm, int m, double fn, int n) 
static void  channelize (PartialList &partials, const Envelope &refChanFreq, int refChanLabel) 
template<typename Iter > 
static void  channelize (Iter begin, Iter end, const Envelope &refChanFreq, int refChanLabel) 
static double  computeStretchFactor (double f1, double fn, double n) 
Detailed Description
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 timevarying fundamental frequency. The frequency spectrum is partitioned into nonoverlapping channels having timevarying 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 nonnegative (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.
Constructor & Destructor Documentation
Loris::Channelizer::Channelizer 
( 
const Envelope & 
refChanFreq, 


int 
refChanLabel, 


double 
stretchFactor = 0  

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

 refChanFreq  is an Envelope representing the center frequency of a channel. 
 refChanLabel  is the corresponding channel number (i.e. 1 if refChanFreq is the lowestfrequency channel, and all other channels are harmonics of refChanFreq, or 2 if refChanFreq tracks the second harmonic, etc.). 
 stretchFactor  is a stretching factor to account for detuned harmonics, default is 0. 
 Exceptions:

Loris::Channelizer::Channelizer 
( 
double 
refFreq, 


double 
stretchFactor = 0  

) 
  
Construct a new Channelizer having a constant reference frequency. The specified frequency is the center frequency of the lowestfrequency channel (for a harmonic sound, the channel containing the fundamental Partial.
 Parameters:

 refFreq  is the reference frequency (in Hz) corresponding to the first frequency channel. 
 stretchFactor  is a stretching factor to account for detuned harmonics, default is 0. 
 Exceptions:

Loris::Channelizer::Channelizer 
( 
const Channelizer & 
other 
) 

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.
 Parameters:

Member Function Documentation
double Loris::Channelizer::amplitudeWeighting 
( 
void 

) 
const 
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 Loris::Channelizer::channelFrequencyAt 
( 
double 
time, 


int 
channel  

) 
  const 
Compute the center frequency of one a channel at the specified time. For nonstretched 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.
 Parameters:

 time  is the time (in seconds) at which to evalute the reference envelope 
 channel  is the frequency channel (or harmonic, or vibrational mode) number whose frequency is to be determined 
 Returns:
 the center frequency in Hz of the specified frequency channel at the specified time
template<typename Iter >
void Loris::Channelizer::channelize 
( 
Iter 
begin, 


Iter 
end, 


const Envelope & 
refChanFreq, 


int 
refChanLabel  

) 
  [inline, 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.
 Parameters:

 begin  is the beginning of a sequence of Partials to channelize. 
 end  is the end of a sequence of Partials to channelize. 
 refChanFreq  is an Envelope representing the center frequency of a channel. 
 refChanLabel  is the corresponding channel number (i.e. 1 if refChanFreq is the lowestfrequency channel, and all other channels are harmonics of refChanFreq, or 2 if refChanFreq tracks the second harmonic, etc.). 
 Exceptions:

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.
static void Loris::Channelizer::channelize 
( 
PartialList & 
partials, 


const Envelope & 
refChanFreq, 


int 
refChanLabel  

) 
  [static] 
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.
 Parameters:

 partials  is the sequence of Partials to channelize. 
 refChanFreq  is an Envelope representing the center frequency of a channel. 
 refChanLabel  is the corresponding channel number (i.e. 1 if refChanFreq is the lowestfrequency channel, and all other channels are harmonics of refChanFreq, or 2 if refChanFreq tracks the second harmonic, etc.). 
 Exceptions:

template<typename Iter >
void Loris::Channelizer::channelize 
( 
Iter 
begin, 


Iter 
end  

) 
  const [inline] 
Assign each Partial in the specified halfopen (STLstyle) range the label corresponding to the frequency channel containing the greatest portion of its (the Partial's) energy.
 Parameters:

 begin  is the beginning of the range of Partials to channelize 
 end  is (onepast) 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.
Assign each Partial in the specified halfopen (STLstyle) range the label corresponding to the frequency channel containing the greatest portion of its (the Partial's) energy.
 Parameters:

 begin  is the beginning of the range of Partials to channelize 
 end  is (onepast) 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.
void Loris::Channelizer::channelize 
( 
Partial & 
partial 
) 
const 
Label a Partial with the number of the frequency channel containing the greatest portion of its (the Partial's) energy.
 Parameters:

int Loris::Channelizer::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.
 Parameters:

 time  is the time (in seconds) at which to evalute the reference envelope 
 frequency  is the frequency (in Hz) for wihch the channel number is to be determined 
 Returns:
 the channel number corresponding to the specified frequency and time
double Loris::Channelizer::computeFractionalChannelNumber 
( 
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 timevarying frequency.
 Parameters:

 time  is the time (in seconds) at which to evalute the reference envelope 
 frequency  is the frequency (in Hz) for wihch the channel number is to be determined 
 Returns:
 the fractional channel number corresponding to the specified frequency and time
static double Loris::Channelizer::computeStretchFactor 
( 
double 
f1, 


double 
fn, 


double 
n  

) 
  [static] 
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.
 Parameters:

 f1  is the frequency of the lowest numbered (1) partial. 
 fn  is the frequency of the Nth stretched harmonic 
 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 Loris::Channelizer::computeStretchFactor 
( 
double 
fm, 


int 
m, 


double 
fn, 


int 
n  

) 
  [static] 
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).
 Parameters:

 fm  is the frequency of the Mth stretched harmonic 
 m  is the harmonic number of the harmonic whose frequnecy is fm 
 fn  is the frequency of the Nth stretched harmonic 
 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).
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.
 Parameters:

double Loris::Channelizer::referenceFrequencyAt 
( 
double 
time 
) 
const 
Compute the reference frequency at the specified time. For nonstretched 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.
 Parameters:

 time  is the time (in seconds) at which to evalute the reference envelope 
void Loris::Channelizer::setAmplitudeWeighting 
( 
double 
expon 
) 

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 Loris::Channelizer::setStretchFactor 
( 
double 
fm, 


int 
m, 


double 
fn, 


int 
n  

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

 fm  is the frequency of the Mth stretched harmonic 
 m  is the harmonic number of the harmonic whose frequnecy is fm 
 fn  is the frequency of the Nth stretched harmonic 
 n  is the harmonic number of the harmonic whose frequnecy is fn 
void Loris::Channelizer::setStretchFactor 
( 
double 
stretch 
) 

Set the stretching factor used to account for detuned harmonics, as in a piano tone. Normally set to 0 for intune 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.
 Exceptions:

double Loris::Channelizer::stretchFactor 
( 
void 

) 
const 
Return the stretching factor used to account for detuned harmonics, as in a piano tone. Normally set to 0 for intune 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.
The documentation for this class was generated from the following file: