Loris::Analyzer Class Reference
#include <Analyzer.h>
List of all members.
Public Types 
enum  { Default_ResidueBandwidth_RegionWidth = 2000,
Default_ConvergenceBandwidth_TolerancePct = 10
} 
enum  { Default_FundamentalEnv_ThreshDb = 60,
Default_FundamentalEnv_ThreshHz = 8000
} 
Public Member Functions 
 Analyzer (double resolutionHz) 
 Analyzer (double resolutionHz, double windowWidthHz) 
 Analyzer (const Envelope &resolutionEnv, double windowWidthHz) 
 Analyzer (const Analyzer &other) 
 ~Analyzer (void) 
 Destroy this Analyzer.

Analyzer &  operator= (const Analyzer &rhs) 
void  configure (double resolutionHz) 
void  configure (double resolutionHz, double windowWidthHz) 
void  configure (const Envelope &resolutionEnv, double windowWidthHz) 
void  analyze (const std::vector< double > &vec, double srate) 
void  analyze (const double *bufBegin, const double *bufEnd, double srate) 
void  analyze (const std::vector< double > &vec, double srate, const Envelope &reference) 
void  analyze (const double *bufBegin, const double *bufEnd, double srate, const Envelope &reference) 
double  ampFloor (void) const 
double  cropTime (void) const 
double  freqDrift (void) const 
double  freqFloor (void) const 
double  freqResolution (double time=0.0) const 
double  hopTime (void) const 
double  sidelobeLevel (void) const 
double  windowWidth (void) const 
bool  phaseCorrect (void) const 
void  setAmpFloor (double x) 
void  setCropTime (double x) 
void  setFreqDrift (double x) 
void  setFreqFloor (double x) 
void  setFreqResolution (double x) 
void  setFreqResolution (const Envelope &e) 
void  setHopTime (double x) 
void  setSidelobeLevel (double x) 
void  setWindowWidth (double x) 
void  setPhaseCorrect (bool TF=true) 
void  storeResidueBandwidth (double regionWidth=Default_ResidueBandwidth_RegionWidth) 
void  storeConvergenceBandwidth (double tolerancePct=0.01 *(double) Default_ConvergenceBandwidth_TolerancePct) 
void  storeNoBandwidth (void) 
bool  bandwidthIsResidue (void) const 
bool  bandwidthIsConvergence (void) const 
double  bwRegionWidth (void) const 
double  bwConvergenceTolerance (void) const 
bool  associateBandwidth (void) const 
void  setBwRegionWidth (double x) 
 Deprecated, use storeResidueBandwidth or storeNoBandwidth instead.

PartialList &  partials (void) 
const PartialList &  partials (void) const 
void  buildFundamentalEnv (double fmin, double fmax, double threshDb=Default_FundamentalEnv_ThreshDb, double threshHz=Default_FundamentalEnv_ThreshHz) 
const LinearEnvelope &  fundamentalEnv (void) const 
const LinearEnvelope &  ampEnv (void) const 
void  buildAmpEnv (bool TF=true) 
void  buildFundamentalEnv (bool TF=true) 
Detailed Description
Class Analyzer represents a configuration of parameters for performing Reassigned BandwidthEnhanced Additive Analysis of sampled sounds. The analysis process yields a collection of Partials, each having a trio of synchronous, nonuniformly sampled breakpoint envelopes representing the timevarying frequency, amplitude, and noisiness of a single bandwidth enhanced sinusoid. These Partials are accumulated in the Analyzer.
The core analysis parameter is the frequency resolution, the minimum instantaneous frequency spacing between partials. Most other parameters are initially configured according to this parameter (and the analysis window width, if specified). Subsequent parameter mutations are independent.
Bandwidth enhancement: Two different strategies are available for computing bandwidth (or noisiness) envelope:
One strategy is to construct bandwidth envelopes during analysis by associating residual energy in the spectrum (after peak extraction) with the selected spectral peaks that are used to construct Partials. This is the original bandwidth enhancement algorithm, and bandwidth envelopes constructed in this way may be suitable for use in bandwidthenhanced synthesis.
Another stategy is to construct bandwidth envelopes during analysis by storing the mixed derivative of shorttime phase, scaled and shifted so that a value of 0 corresponds to a pure sinusoid, and a value of 1 corresponds to a bandwidthenhanced sinusoid with maximal energy spread (minimum convergence in frequency). These bandwidth envelopes are not suitable for bandwidthenhanced synthesis, be sure to set the bandwidth to 0, or to disable bandwidth enhancement before rendering.
The Analyzer may be configured to use either of these two strategies for bandwidthenhanced analysis, or to construct no bandwidth envelopes at all. If unspecified, the default Analyzer configuration uses spectral residue to construct bandwidth envelopes.
 See also:
 storeResidueBandwidth, storeConvergenceBandwidth, storeNoBandwidth
For more information about Reassigned BandwidthEnhanced Analysis and the Reassigned BandwidthEnhanced Additive Sound Model, refer to the Loris website: www.cerlsoundgroup.org/Loris/.
Constructor & Destructor Documentation
Loris::Analyzer::Analyzer 
( 
double 
resolutionHz 
) 
[explicit] 
Construct a new Analyzer configured with the given frequency resolution (minimum instantaneous frequency difference between Partials). All other Analyzer parameters are computed from the specified frequency resolution.
 Parameters:

 resolutionHz  is the frequency resolution in Hz. 
Loris::Analyzer::Analyzer 
( 
double 
resolutionHz, 


double 
windowWidthHz  

) 
  
Construct a new Analyzer configured with the given frequency resolution (minimum instantaneous frequency difference between Partials) and analysis window width (main lobe, zerotozero). All other Analyzer parameters are computed from the specified resolution and window width.
 Parameters:

 resolutionHz  is the frequency resolution in Hz. 
 windowWidthHz  is the main lobe width of the Kaiser analysis window in Hz. 
Loris::Analyzer::Analyzer 
( 
const Envelope & 
resolutionEnv, 


double 
windowWidthHz  

) 
  
Construct a new Analyzer configured with the given timevarying frequency resolution (minimum instantaneous frequency difference between Partials) and analysis window width (main lobe, zerotozero). All other Analyzer parameters are computed from the specified resolution and window width.
 Parameters:

 resolutionHz  is the frequency resolution in Hz. 
 windowWidthHz  is the main lobe width of the Kaiser analysis window in Hz. 
Loris::Analyzer::Analyzer 
( 
const Analyzer & 
other 
) 

Construct a new Analyzer having identical parameter configuration to another Analyzer. The list of collected Partials is not copied.
 Parameters:

Member Function Documentation
Return the overall amplitude estimate envelope constructed during the most recent analysis performed by this Analyzer.
double Loris::Analyzer::ampFloor 
( 
void 

) 
const 
Return the amplitude floor (lowest detected spectral amplitude), in (negative) dB, for this Analyzer.
void Loris::Analyzer::analyze 
( 
const double * 
bufBegin, 


const double * 
bufEnd, 


double 
srate, 


const Envelope & 
reference  

) 
  
Analyze a range of (mono) samples at the given sample rate (in Hz) and store the extracted Partials in the Analyzer's PartialList (std::list of Partials). Use the specified envelope as a frequency reference for Partial tracking.
 Parameters:

 bufBegin  is a pointer to a buffer of floating point samples 
 bufEnd  is (onepast) the end of a buffer of floating point samples 
 srate  is the sample rate of the samples in the buffer 
 reference  is an Envelope having the approximate frequency contour expected of the resulting Partials. 
void Loris::Analyzer::analyze 
( 
const std::vector< double > & 
vec, 


double 
srate, 


const Envelope & 
reference  

) 
  
Analyze a vector of (mono) samples at the given sample rate (in Hz) and store the extracted Partials in the Analyzer's PartialList (std::list of Partials). Use the specified envelope as a frequency reference for Partial tracking.
 Parameters:

 vec  is a vector of floating point samples 
 srate  is the sample rate of the samples in the vector 
 reference  is an Envelope having the approximate frequency contour expected of the resulting Partials. 
void Loris::Analyzer::analyze 
( 
const double * 
bufBegin, 


const double * 
bufEnd, 


double 
srate  

) 
  
Analyze a range of (mono) samples at the given sample rate (in Hz) and store the extracted Partials in the Analyzer's PartialList (std::list of Partials).
 Parameters:

 bufBegin  is a pointer to a buffer of floating point samples 
 bufEnd  is (onepast) the end of a buffer of floating point samples 
 srate  is the sample rate of the samples in the buffer 
void Loris::Analyzer::analyze 
( 
const std::vector< double > & 
vec, 


double 
srate  

) 
  
Analyze a vector of (mono) samples at the given sample rate (in Hz) and store the extracted Partials in the Analyzer's PartialList (std::list of Partials).
 Parameters:

 vec  is a vector of floating point samples 
 srate  is the sample rate of the samples in the vector 
bool Loris::Analyzer::associateBandwidth 
( 
void 

) 
const [inline] 
bool Loris::Analyzer::bandwidthIsConvergence 
( 
void 

) 
const 
Return true if this Analyzer is configured to compute bandwidth envelopes using the mixed derivative convergence indicator, and false otherwise.
bool Loris::Analyzer::bandwidthIsResidue 
( 
void 

) 
const 
Return true if this Analyzer is configured to compute bandwidth envelopes using the spectral residue after peaks have been identified, and false otherwise.
void Loris::Analyzer::buildFundamentalEnv 
( 
double 
fmin, 


double 
fmax, 


double 
threshDb = Default_FundamentalEnv_ThreshDb , 


double 
threshHz = Default_FundamentalEnv_ThreshHz  

) 
  
Specify parameters for constructing a fundamental frequency envelope for the analyzed sound during analysis. The fundamental frequency estimate can be accessed by fundamentalEnv() after the analysis is complete.
By default, a fundamental envelope is estimated during analysis between the frequency resolution and 1.5 times the resolution.
 Parameters:

 fmin  is the lower bound on the fundamental frequency estimate 
 fmax  is the upper bound on the fundamental frequency estimate 
 threshDb  is the lower bound on the amplitude of a spectral peak that will constribute to the fundamental frequency estimate (very low amplitude peaks tend to have less reliable frequency estimates). Default is 60 dB. 
 threshHz  is the upper bound on the frequency of a spectral peak that will constribute to the fundamental frequency estimate. Default is 8 kHz. 
double Loris::Analyzer::bwConvergenceTolerance 
( 
void 

) 
const 
Return the mixed derivative convergence tolerance (percent) only if the convergence indicator is used to compute bandwidth envelopes. Return zero if the spectral residue method is used or if no bandwidth is computed.
double Loris::Analyzer::bwRegionWidth 
( 
void 

) 
const 
Return the width (in Hz) of the Bandwidth Association regions used by this Analyzer, only if the spectral residue method is used to compute bandwidth envelopes. Return zero if the mixed derivative method is used, or if no bandwidth is computed.
void Loris::Analyzer::configure 
( 
const Envelope & 
resolutionEnv, 


double 
windowWidthHz  

) 
  
Configure this Analyzer with the given timevarying frequency resolution (minimum instantaneous frequency difference between Partials) and analysis window width (main lobe, zerotozero, in Hz). All other Analyzer parameters are (re)computed from the frequency resolution and window width.
 Parameters:

 resolutionEnv  is the timevarying frequency resolution in Hz. 
 windowWidthHz  is the main lobe width of the Kaiser analysis window in Hz. 
There are three categories of analysis parameters:
 the resolution, and params that are usually related to (or identical to) the resolution (frequency floor and drift)
 the window width and params that are usually related to (or identical to) the window width (hop and crop times)
 independent parameters (bw region width and amp floor)
void Loris::Analyzer::configure 
( 
double 
resolutionHz, 


double 
windowWidthHz  

) 
  
Configure this Analyzer with the given frequency resolution (minimum instantaneous frequency difference between Partials) and analysis window width (main lobe, zerotozero, in Hz). All other Analyzer parameters are (re)computed from the frequency resolution and window width.
 Parameters:

 resolutionHz  is the frequency resolution in Hz. 
 windowWidthHz  is the main lobe width of the Kaiser analysis window in Hz. 
There are three categories of analysis parameters:
 the resolution, and params that are usually related to (or identical to) the resolution (frequency floor and drift)
 the window width and params that are usually related to (or identical to) the window width (hop and crop times)
 independent parameters (bw region width and amp floor)
void Loris::Analyzer::configure 
( 
double 
resolutionHz 
) 

Configure this Analyzer with the given frequency resolution (minimum instantaneous frequency difference between Partials, in Hz). All other Analyzer parameters are (re)computed from the frequency resolution, including the window width, which is twice the resolution.
 Parameters:

 resolutionHz  is the frequency resolution in Hz. 
double Loris::Analyzer::cropTime 
( 
void 

) 
const 
Return the crop time (maximum temporal displacement of a time frequency data point from the timedomain center of the analysis window, beyond which data points are considered "unreliable") for this Analyzer.
double Loris::Analyzer::freqDrift 
( 
void 

) 
const 
Return the maximum allowable frequency difference between consecutive Breakpoints in a Partial envelope for this Analyzer.
double Loris::Analyzer::freqFloor 
( 
void 

) 
const 
Return the frequency floor (minimum instantaneous Partial frequency), in Hz, for this Analyzer.
double Loris::Analyzer::freqResolution 
( 
double 
time = 0.0 
) 
const 
Return the frequency resolution (minimum instantaneous frequency difference between Partials) for this Analyzer at the specified time in seconds. If no time is specified, then the initial resolution (at 0 seconds) is returned.
 Parameters:

 time  is the time in seconds at which to evaluate the frequency resolution 
Return the fundamental frequency estimate envelope constructed during the most recent analysis performed by this Analyzer.
By default, a fundamental envelope is estimated during analysis between the frequency resolution and 1.5 times the resolution.
double Loris::Analyzer::hopTime 
( 
void 

) 
const 
Return the hop time (which corresponds approximately to the average density of Partial envelope Breakpoint data) for this Analyzer.
Construct a new Analyzer having identical parameter configuration to another Analyzer. The list of collected Partials is not copied.
 Parameters:

const PartialList& Loris::Analyzer::partials 
( 
void 

) 
const 
Return an immutable (const) reference to this Analyzer's list of analyzed Partials.
PartialList& Loris::Analyzer::partials 
( 
void 

) 

Return a mutable reference to this Analyzer's list of analyzed Partials.
bool Loris::Analyzer::phaseCorrect 
( 
void 

) 
const 
Return true if the phases and frequencies of the constructed partials should be modified to be consistent at the end of the analysis, and false otherwise. (Default is true.)
void Loris::Analyzer::setAmpFloor 
( 
double 
x 
) 

Set the amplitude floor (lowest detected spectral amplitude), in (negative) dB, for this Analyzer.
 Parameters:

 x  is the new value of this parameter. 
void Loris::Analyzer::setCropTime 
( 
double 
x 
) 

Set the crop time (maximum temporal displacement of a time frequency data point from the timedomain center of the analysis window, beyond which data points are considered "unreliable") for this Analyzer.
 Parameters:

 x  is the new value of this parameter. 
void Loris::Analyzer::setFreqDrift 
( 
double 
x 
) 

Set the maximum allowable frequency difference between consecutive Breakpoints in a Partial envelope for this Analyzer.
 Parameters:

 x  is the new value of this parameter. 
void Loris::Analyzer::setFreqFloor 
( 
double 
x 
) 

Set the frequency floor (minimum instantaneous Partial frequency), in Hz, for this Analyzer.
 Parameters:

 x  is the new value of this parameter. 
void Loris::Analyzer::setFreqResolution 
( 
const Envelope & 
e 
) 

Set the timevarying frequency resolution (minimum instantaneous frequency difference between Partials) for this Analyzer. (Does not cause other parameters to be recomputed.)
 Parameters:

 e  is the envelope to copy for this parameter. 
void Loris::Analyzer::setFreqResolution 
( 
double 
x 
) 

Set the frequency resolution (minimum instantaneous frequency difference between Partials) for this Analyzer. (Does not cause other parameters to be recomputed.)
 Parameters:

 x  is the new value of this parameter. 
void Loris::Analyzer::setHopTime 
( 
double 
x 
) 

Set the hop time (which corresponds approximately to the average density of Partial envelope Breakpoint data) for this Analyzer.
 Parameters:

 x  is the new value of this parameter. 
void Loris::Analyzer::setPhaseCorrect 
( 
bool 
TF = true 
) 

Indicate whether the phases and frequencies of the constructed partials should be modified to be consistent at the end of the analysis. (Default is true.)
 Parameters:

 TF  is a flag indicating whether or not to construct phasecorrected Partials 
void Loris::Analyzer::setSidelobeLevel 
( 
double 
x 
) 

Set the sidelobe attenutation level for the Kaiser analysis window in positive dB. More negative numbers (e.g. 90) give very good sidelobe rejection but cause the window to be longer in time. Less negative numbers raise the level of the sidelobes, increasing the likelihood of frequencydomain interference, but allow the window to be shorter in time.
 Parameters:

 x  is the new value of this parameter. 
void Loris::Analyzer::setWindowWidth 
( 
double 
x 
) 

Set the frequencydomain main lobe width (measured between zerocrossings) of the analysis window used by this Analyzer.
 Parameters:

 x  is the new value of this parameter. 
double Loris::Analyzer::sidelobeLevel 
( 
void 

) 
const 
Return the sidelobe attenutation level for the Kaiser analysis window in positive dB. Larger numbers (e.g. 90) give very good sidelobe rejection but cause the window to be longer in time. Smaller numbers (like 60) raise the level of the sidelobes, increasing the likelihood of frequencydomain interference, but allow the window to be shorter in time.
void Loris::Analyzer::storeConvergenceBandwidth 
( 
double 
tolerancePct = 0.01 *(double) Default_ConvergenceBandwidth_TolerancePct 
) 

Construct Partial bandwidth envelopes during analysis by storing the mixed derivative of shorttime phase, scaled and shifted so that a value of 0 corresponds to a pure sinusoid, and a value of 1 corresponds to a bandwidthenhanced sinusoid with maximal energy spread (minimum sinusoidal convergence).
 Parameters:

 tolerance  is the amount of range over which the mixed derivative indicator should be allowed to drift away from a pure sinusoid before saturating. This range is mapped to bandwidth values on the range [0,1]. Must be positive and not greater than 1. If unspecified, a default value is used. 
void Loris::Analyzer::storeNoBandwidth 
( 
void 

) 

Disable bandwidth envelope construction. Bandwidth will be zero for all Breakpoints in all Partials.
void Loris::Analyzer::storeResidueBandwidth 
( 
double 
regionWidth = Default_ResidueBandwidth_RegionWidth 
) 

Construct Partial bandwidth envelopes during analysis by associating residual energy in the spectrum (after peak extraction) with the selected spectral peaks that are used to construct Partials.
This is the default bandwidthenhancement strategy.
 Parameters:

 regionWidth  is the width (in Hz) of the bandwidth association regions used by this process, must be positive. If unspecified, a default value is used. 
double Loris::Analyzer::windowWidth 
( 
void 

) 
const 
Return the frequencydomain main lobe width (measured between zerocrossings) of the analysis window used by this Analyzer.
The documentation for this class was generated from the following file:
 /Users/kfitz/Projects/Loris/Loris development/src/Analyzer.h