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

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 lowest-frequency 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:
InvalidArgument if refChanLabel is not positive.
InvalidArgument if stretchFactor is negative.
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 lowest-frequency 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:
InvalidArgument if refChanLabel is not positive.
InvalidArgument if stretchFactor is negative.
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:
other is the Channelizer to copy

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

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 lowest-frequency channel, and all other channels are harmonics of refChanFreq, or 2 if refChanFreq tracks the second harmonic, etc.).
Exceptions:
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.

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 lowest-frequency channel, and all other channels are harmonics of refChanFreq, or 2 if refChanFreq tracks the second harmonic, etc.).
Exceptions:
InvalidArgument if refChanLabel is not positive.
template<typename Iter >
void Loris::Channelizer::channelize ( Iter  begin,
Iter  end 
) const [inline]

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.

Parameters:
begin is the beginning of the range of Partials to channelize
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.

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.

Parameters:
begin is the beginning of the range of Partials to channelize
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.

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:
partial is the Partial to label.
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 time-varying 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).
Channelizer& Loris::Channelizer::operator= ( const Channelizer &  rhs  ) 

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:
rhs is the Channelizer to copy
double Loris::Channelizer::referenceFrequencyAt ( double  time  )  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.

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

Exceptions:
InvalidArgument if stretch is negative.
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 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.

The documentation for this class was generated from the following file:
Generated by  doxygen 1.6.2