#ifndef INCLUDE_SIEVE_H
#define INCLUDE_SIEVE_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
*
*
* Sieve.h
*
* Definition of class Sieve.
*
* Lippold Haken, 20 Jan 2001
* loris@cerlsoundgroup.org
*
* http://www.cerlsoundgroup.org/Loris/
*
*/
#include "Distiller.h" // for default fade time and silent time
#if defined(NO_TEMPLATE_MEMBERS)
#include "PartialList.h"
#endif
#include "PartialPtrs.h"
// begin namespace
namespace Loris {
// ---------------------------------------------------------------------------
// class Sieve
//
//! A Sieve eliminating temporal overlap among Partials.
//!
//! Class Sieve represents an algorithm for identifying channelized (see also
//! Channelizer) Partials that overlap in time, and selecting the longer
//! one to represent the channel. The identification of overlap includes
//! the time needed for Partials to fade to and from zero amplitude in
//! synthesis (see also Synthesizer) or distillation. (see also Distiller)
//!
//! In some cases, the energy redistribution effected by the distiller
//! (see also Distiller) is undesirable. In such cases, the partials can be
//! sifted before distillation. The sifting process in Loris identifies
//! all the partials that would be rejected (and converted to noise
//! energy) by the distiller and assigns them a label of 0. These sifted
//! partials can then be identified and treated sepearately or removed
//! altogether, or they can be passed through the distiller unlabeled, and
//! crossfaded in the morphing process (see also Morpher).
//!
//! \sa Channelizer, Distiller, Morpher, Synthesizer
//
class Sieve
{
// -- instance variables --
double _fadeTime; //! extra time (in seconds) added to each end of
//! a Partial when determining overlap, to accomodate
//! the fade to and from zero amplitude.
// -- public interface --
public:
// -- global defaults and constants --
enum
{
//! Default time in milliseconds over which Partials joined by
//! distillation fade to and from zero amplitude. Divide by
//! 1000 to use as a member function parameter. This parameter
//! should be the same in Distiller, Sieve, and Collator.
DefaultFadeTimeMs = Distiller::DefaultFadeTimeMs,
//! Default minimum duration in milliseconds of the silent
//! (zero-amplitude) gap between two Partials joined by
//! distillation. Divide by 1000 to use as a member function
//! parameter. This parameter should be the same in Distiller,
//! Sieve, and Collator.
DefaultSilentTimeMs = Distiller::DefaultSilentTimeMs
};
// -- construction --
//! Construct a new Sieve using the specified partial fade
//! time. If unspecified, the default fade time (same as the
//! default fade time for the Distiller) is used.
//!
//! \param partialFadeTime is the extra time (in seconds)
//! added to each end of a Partial to accomodate
//! the fade to and from zero amplitude. Fade time
//! must be non-negative. A default value is used
//! if unspecified.
//! \throw InvalidArgument if partialFadeTime is negative.
explicit Sieve( double partialFadeTime = Sieve::DefaultFadeTimeMs/1000.0 );
// Use compiler-generated copy, assign, and destroy.
// -- sifting --
//! Sift labeled Partials on the specified half-open (STL-style)
//! range. If any two Partials having same label overlap in time, keep
//! only the longer of the two Partials. Set the label of the shorter
//! duration partial to zero. No Partials are removed from the
//! sequence and the sequence order is unaltered.
//!
//! \param sift_begin is the beginning of the range of Partials to sift
//! \param sift_end is (one-past) the end of the range of Partials to sift
//!
//! If compiled with NO_TEMPLATE_MEMBERS defined, then sift_begin and
//! sift_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 sift( Iter sift_begin, Iter sift_end );
#else
inline
void sift( PartialList::iterator sift_begin, PartialList::iterator sift_end );
#endif
//! Sift labeled Partials in the specified container
//! If any two Partials having same label overlap in time, keep
//! only the longer of the two Partials. Set the label of the shorter
//! duration partial to zero. No Partials are removed from the
//! container and the container order is unaltered.
//!
//! \param partials is the collection of Partials to sift in-place
//!
//! If compiled with NO_TEMPLATE_MEMBERS defined, then partials
//! must be a PartialList, otherwise it can be any container type
//! storing Partials that supports at least bidirectional iterators.
#if ! defined(NO_TEMPLATE_MEMBERS)
template< typename Container >
void sift( Container & partials )
#else
inline
void sift( PartialList & partials )
#endif
{
sift( partials.begin(), partials.end() );
}
// -- static members --
//! Static member that constructs an instance and applies
//! it to a sequence of Partials.
//! Construct a Sieve using the specified Partial
//! fade time (in seconds), and use it to sift a
//! sequence of Partials.
//!
//! \param sift_begin is the beginning of the range of Partials to sift
//! \param sift_end is (one-past) the end of the range of Partials to sift
//! \param partialFadeTime is the extra time (in seconds)
//! added to each end of a Partial to accomodate
//! the fade to and from zero amplitude. The Partial fade time
//! must be non-negative.
//! \throw InvalidArgument if partialFadeTime is negative.
//!
//! 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 sift( Iter sift_begin, Iter sift_end,
double partialFadeTime );
#else
static inline
void sift( PartialList::iterator sift_begin, PartialList::iterator sift_end,
double partialFadeTime );
#endif
// -- helper --
private:
//! Sift labeled Partials. If any two Partials having the same (non-zero)
//! label overlap in time (where overlap includes the fade time at both
//! ends of each Partial), then set the label of the Partial having the
//! shorter duration to zero. Sifting is performed on a collection of
//! pointers to Partials so that the it can be performed without changing
//! the order of the Partials in the sequence.
//!
//! \param ptrs is a collection of pointers to the Partials in the
//! sequence to be sifted.
void sift_ptrs( PartialPtrs & ptrs );
}; // end of class Sieve
// ---------------------------------------------------------------------------
// sift
// ---------------------------------------------------------------------------
//! Sift labeled Partials on the specified half-open (STL-style)
//! range. If any two Partials having same label overlap in time, keep
//! only the longer of the two Partials. Set the label of the shorter
//! duration partial to zero. No Partials are removed from the
//! sequence and the sequence order is unaltered.
//!
//! \param sift_begin is the beginning of the range of Partials to sift
//! \param sift_end is (one-past) the end of the range of Partials to sift
//!
//! If compiled with NO_TEMPLATE_MEMBERS defined, then sift_begin and
//! sift_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 Sieve::sift( Iter sift_begin, Iter sift_end )
#else
inline
void Sieve::sift( PartialList::iterator sift_begin, PartialList::iterator sift_end )
#endif
{
PartialPtrs ptrs;
fillPartialPtrs( sift_begin, sift_end, ptrs );
sift_ptrs( ptrs );
}
// ---------------------------------------------------------------------------
// sift (static)
// ---------------------------------------------------------------------------
//! Static member that constructs an instance and applies
//! it to a sequence of Partials.
//! Construct a Sieve using the specified Partial
//! fade time (in seconds), and use it to sift a
//! sequence of Partials.
//!
//! \param sift_begin is the beginning of the range of Partials to sift
//! \param sift_end is (one-past) the end of the range of Partials to sift
//! \param partialFadeTime is the extra time (in seconds)
//! added to each end of a Partial to accomodate
//! the fade to and from zero amplitude. The Partial fade time
//! must be non-negative.
//! \throw InvalidArgument if partialFadeTime is negative.
//!
//! 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 Sieve::sift( Iter sift_begin, Iter sift_end,
double partialFadeTime )
#else
inline
void Sieve::sift( PartialList::iterator sift_begin, PartialList::iterator sift_end,
double partialFadeTime )
#endif
{
Sieve instance( partialFadeTime );
instance.sift( sift_begin, sift_end );
}
} // end of namespace Loris
#endif /* ndef INCLUDE_SIEVE_H */