#ifndef INCLUDE_SPECTRALSURFACE_H
#define INCLUDE_SPECTRALSURFACE_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
*
*
* SpectralSurface.h
*
* Definition of class SpectralSurface, a class representing
* a smoothed time-frequency surface that can be used to
* perform cross-synthesis, the filtering of one sound by the
* time-varying spectrum of another.
*
* Kelly Fitz, 21 Dec 2005
* loris@cerlsoundgroup.org
*
* http://www.cerlsoundgroup.org/Loris/
*
*/
#include "LorisExceptions.h"
#include "Partial.h"
#include "PartialList.h"
#include "PartialUtils.h" // for compareLabelLess
#include <algorithm> // for sort
#include <vector>
// begin namespace
namespace Loris {
// ---------------------------------------------------------------------------
// Class SpectralSurface
//
//! SpectralSurface represents a smoothed time-frequency surface that
//! can be used to perform cross-synthesis, the filtering of one sound
//! by the time-varying spectrum of another.
//
class SpectralSurface
{
// -- public interface --
public:
// -- lifecycle --
//! Contsruct a new SpectralSurface from a sequence of distilled
//! Partials.
//!
//! \pre the specified Partials must be channelized and distilled.
//! \param b the beginning of the sequence of Partials
//! \param e the end of the sequence of Partials
//!
//! If compiled with NO_TEMPLATE_MEMBERS defined, then b and e
//! 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>
SpectralSurface( Iter b, Iter e );
#else
inline
SpectralSurface( PartialList::iterator b, PartialList::iterator e );
#endif
// use compiler-generated copy/assign/destroy
// --- operations ---
//! Scale the amplitude of every Breakpoint in a Partial
//! according to the amplitude of the spectral surface
//! at the corresponding time and frequency.
//!
//! \param p the Partial to modify
void scaleAmplitudes( Partial & p );
//! Scale the amplitudes of a sequence of Partials
//! according to the amplitude of the spectral surface
//! at the corresponding times and frequencies,
//! performing cross-synthesis, the filtering of one
//! sound (the sequence of Partials) by the time-varying
//! spectrum of another sound (the Partials used to
//! construct the surface). The surface is stretched
//! in time and frequency according to the values of
//! the two stretch factors (default 1, no stretching)
//! and the amount of the effect is governed by the
//! `effect' parameter (default 1, full effect).
//!
//! \param b the beginning of the sequence of Partials
//! \param e the end of the sequence of Partials
//!
//! If compiled with NO_TEMPLATE_MEMBERS defined, then b and e
//! 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 scaleAmplitudes( Iter b, Iter e );
#else
inline
void scaleAmplitudes( PartialList::iterator b, PartialList::iterator e );
#endif
//! Set the amplitude of every Breakpoint in a Partial
//! equal to the amplitude of the spectral surface
//! at the corresponding time and frequency.
//!
//! \param p the Partial to modify
void setAmplitudes( Partial & p );
//! Set the amplitudes of a sequence of Partials
//! equal to the amplitude of the spectral surface
//! at the corresponding times and frequencies.
//! This can be used to perform formant-corrected
//! pitch shifting of a sound: construct the surface
//! from the unmodified Partials, perform the pitch
//! shift on the Partials, then apply the surface
//! to the shifted Partials using setAmplitudes.
//! The surface is stretched
//! in time and frequency according to the values of
//! the two stretch factors (default 1, no stretching)
//! and the amount of the effect is governed by the
//! `effect' parameter (default 1, full effect).
//!
//! \param b the beginning of the sequence of Partials
//! \param e the end of the sequence of Partials
//!
//! If compiled with NO_TEMPLATE_MEMBERS defined, then b and e
//! 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 setAmplitudes( Iter b, Iter e );
#else
inline
void setAmplitudes( PartialList::iterator b, PartialList::iterator e );
#endif
// --- access/mutation ---
//! Return the amount of strecthing in the frequency dimension
//! (default 1, no stretching). Values greater than 1 stretch
//! the surface in the frequency dimension, values less than 1
//! (but greater than 0) compress the surface in the frequency
//! dimension.
double frequencyStretch( void ) const;
//! Return the amount of strecthing in the time dimension
//! (default 1, no stretching). Values greater than 1 stretch
//! the surface in the time dimension, values less than 1
//! (but greater than 0) compress the surface in the time
//! dimension.
double timeStretch( void ) const;
//! Return the amount of effect applied by scaleAmplitudes
//! and setAmplitudes (default 1, full effect). Values
//! less than 1 (but greater than 0) reduce the amount of
//! amplitude modified performed by application of the
//! surface. (This is rarely a good way of controlling the
//! amount of the effect.)
double effect( void ) const;
//! Set the amount of strecthing in the frequency dimension
//! (default 1, no stretching). Values greater than 1 stretch
//! the surface in the frequency dimension, values less than 1
//! (but greater than 0) compress the surface in the frequency
//! dimension.
//!
//! \pre stretch must be positive
//! \param stretch the new stretch factor for the frequency dimension
void setFrequencyStretch( double stretch );
//! Set the amount of strecthing in the time dimension
//! (default 1, no stretching). Values greater than 1 stretch
//! the surface in the time dimension, values less than 1
//! (but greater than 0) compress the surface in the time
//! dimension.
//!
//! \pre stretch must be positive
//! \param stretch the new stretch factor for the time dimension
void setTimeStretch( double stretch );
//! Set the amount of effect applied by scaleAmplitudes
//! and setAmplitudes (default 1, full effect). Values
//! less than 1 (but greater than 0) reduce the amount of
//! amplitude modified performed by application of the
//! surface. (This is rarely a good way of controlling the
//! amount of the effect.)
//!
//! \pre effect must be between 0 and 1, inclusive
//! \param effect the new factor controlling the amount of
//! amplitude modification performed by scaleAmplitudes
//! and setAmplitudes
void setEffect( double effect );
private:
// -- instance variables --
std::vector< Partial > mPartials; //! the Partials comprising the surface are
//! stored in a vector for easy random access
double mStretchFreq; //! stretch factor for the frequency dimension
double mStretchTime; //! stretch factor for the time dimension
double mEffect; //! factor for controlling the amount of
//! of the effect applied in setAmplitudes and
//! scaleAmplitudes: 0 gives unmodified amplitudes
//! 1 gives fully modified amplitudes.
double mMaxSurfaceAmp; //! the maximum amplitude of any Breakpoint on
//! the surface, used for normalizing the surface
//! amplitude for scaleAmplitudes
// --- private helpers ---
// helper used by constructor for adding Partials one by one
void addPartialAux( const Partial & p );
};
// ---------------------------------------------------------------------------
// constructor
// ---------------------------------------------------------------------------
//! Contsruct a new SpectralSurface from a sequence of distilled
//! Partials.
//!
//! \pre the specified Partials must be channelized and distilled.
//! \param b the beginning of the sequence of Partials
//! \param e the end of the sequence of Partials
//!
//! If compiled with NO_TEMPLATE_MEMBERS defined, then b and e
//! 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>
SpectralSurface::SpectralSurface( Iter b, Iter e ) :
#else
inline
SpectralSurface::SpectralSurface( PartialList::iterator b,
PartialList::iterator e ) :
#endif
mStretchFreq( 1.0 ),
mStretchTime( 1.0 ),
mEffect( 1.0 ),
mMaxSurfaceAmp( 0.0 )
{
// add only labeled Partials:
while ( b != e )
{
if ( b->label() != 0 )
{
addPartialAux( *b );
}
++b;
}
// complain if the Partials were not distilled
if ( mPartials.empty() )
{
Throw( InvalidArgument, "Partals need to be distilled to build a SpectralSurface" );
}
if ( 0 == mMaxSurfaceAmp )
{
Throw( InvalidArgument, "The SpectralSurface is zero amplitude everywhere!" );
}
// sort by label
std::sort( mPartials.begin(), mPartials.end(), PartialUtils::compareLabelLess() );
}
// ---------------------------------------------------------------------------
// scaleAmplitudes
// ---------------------------------------------------------------------------
//! Scale the amplitudes of a sequence of Partials
//! according to the amplitude of the spectral surface
//! at the corresponding times and frequencies,
//! performing cross-synthesis, the filtering of one
//! sound (the sequence of Partials) by the time-varying
//! spectrum of another sound (the Partials used to
//! construct the surface). The surface is stretched
//! in time and frequency according to the values of
//! the two stretch factors (default 1, no stretching)
//! and the amount of the effect is governed by the
//! `effect' parameter (default 1, full effect).
//!
//! \param b the beginning of the sequence of Partials
//! \param e the end of the sequence of Partials
//!
//! If compiled with NO_TEMPLATE_MEMBERS defined, then b and e
//! 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 SpectralSurface::scaleAmplitudes( Iter b, Iter e )
#else
inline
void SpectralSurface::scaleAmplitudes( PartialList::iterator b,
PartialList::iterator e )
#endif
{
while ( b != e )
{
// debugger << b->label() << endl;
scaleAmplitudes( *b );
++b;
}
}
// ---------------------------------------------------------------------------
// setAmplitudes
// ---------------------------------------------------------------------------
//! Set the amplitudes of a sequence of Partials
//! equal to the amplitude of the spectral surface
//! at the corresponding times and frequencies.
//! This can be used to perform formant-corrected
//! pitch shifting of a sound: construct the surface
//! from the unmodified Partials, perform the pitch
//! shift on the Partials, then apply the surface
//! to the shifted Partials using setAmplitudes.
//! The surface is stretched
//! in time and frequency according to the values of
//! the two stretch factors (default 1, no stretching)
//! and the amount of the effect is governed by the
//! `effect' parameter (default 1, full effect).
//!
//! \param b the beginning of the sequence of Partials
//! \param e the end of the sequence of Partials
//!
//! If compiled with NO_TEMPLATE_MEMBERS defined, then b and e
//! 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 SpectralSurface::setAmplitudes( Iter b, Iter e )
#else
inline
void SpectralSurface::setAmplitudes( PartialList::iterator b,
PartialList::iterator e )
#endif
{
while ( b != e )
{
// debugger << b->label() << endl;
setAmplitudes( *b );
++b;
}
}
} // namespace Loris
#endif /* ndef INCLUDE_SPECTRALSURFACE_H */