path: root/src/loris/PartialUtils.C

/*
 * 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
 *
 *
 * PartialUtils.C
 *
 *	A group of Partial utility function objects for use with STL 
 *	searching and sorting algorithms. PartialUtils is a namespace
 *	within the Loris namespace.
 *
 * Kelly Fitz, 17 June 2003
 * loris@cerlsoundgroup.org
 *
 * http://www.cerlsoundgroup.org/Loris/
 *
 */

#if HAVE_CONFIG_H
	#include "config.h"
#endif

#include "PartialUtils.h"

#include "Breakpoint.h"
#include "BreakpointEnvelope.h"
#include "BreakpointUtils.h"
#include "Envelope.h"
#include "Partial.h"

#include "phasefix.h"

#include <algorithm>
#include <cmath>
#include <functional>
#include <utility>

//	begin namespace
namespace Loris {

namespace PartialUtils {


// -- base class --

// ---------------------------------------------------------------------------
//	PartialMutator constructor from double
// ---------------------------------------------------------------------------
PartialMutator::PartialMutator( double x ) : 
	env( new BreakpointEnvelope( x ) ) 
{
}
	
// ---------------------------------------------------------------------------
//	PartialMutator constructor from envelope
// ---------------------------------------------------------------------------
PartialMutator::PartialMutator( const Envelope & e ) : 
	env( e.clone() ) 
{
}

// ---------------------------------------------------------------------------
//	PartialMutator copy constructor
// ---------------------------------------------------------------------------
PartialMutator::PartialMutator( const PartialMutator & rhs ) : 
	env( rhs.env->clone() ) 
{
}

// ---------------------------------------------------------------------------
//	PartialMutator destructor
// ---------------------------------------------------------------------------
PartialMutator::~PartialMutator( void )
{
	delete env;
}

// ---------------------------------------------------------------------------
//	PartialMutator assignment operator
// ---------------------------------------------------------------------------
PartialMutator &
PartialMutator::operator=( const PartialMutator & rhs )
{
	if ( this != &rhs )
	{	
		delete env;
		env = rhs.env->clone();
	}
	return *this;
}
	
// -- amplitude scaling --
	
// ---------------------------------------------------------------------------
//	AmplitudeScaler function call operator
// ---------------------------------------------------------------------------
//	Scale the amplitude of the specified Partial according to
//	an envelope representing a time-varying amplitude scale value.
//
void 
AmplitudeScaler::operator()( Partial & p ) const
{
	for ( Partial::iterator pos = p.begin(); pos != p.end(); ++pos ) 
	{		
		pos.breakpoint().setAmplitude( pos.breakpoint().amplitude() * 
									          env->valueAt( pos.time() ) );
	}	
}

// ---------------------------------------------------------------------------
//	BandwidthScaler function call operator
// ---------------------------------------------------------------------------
//	Scale the bandwidth of the specified Partial according to
//	an envelope representing a time-varying bandwidth scale value.
//
void 
BandwidthScaler::operator()( Partial & p ) const
{
	for ( Partial::iterator pos = p.begin(); pos != p.end(); ++pos ) 
	{		
		pos.breakpoint().setBandwidth( pos.breakpoint().bandwidth() * 
									   env->valueAt( pos.time() ) );
	}	
}

// ---------------------------------------------------------------------------
//	BandwidthSetter function call operator
// ---------------------------------------------------------------------------
//	Set the bandwidth of the specified Partial according to
//	an envelope representing a time-varying bandwidth value.
//
void 
BandwidthSetter::operator()( Partial & p ) const
{
	for ( Partial::iterator pos = p.begin(); pos != p.end(); ++pos ) 
	{		
		pos.breakpoint().setBandwidth( env->valueAt( pos.time() ) );
	}	
}

// ---------------------------------------------------------------------------
//	FrequencyScaler function call operator
// ---------------------------------------------------------------------------
//	Scale the frequency of the specified Partial according to
//	an envelope representing a time-varying frequency scale value.
//
void 
FrequencyScaler::operator()( Partial & p ) const
{
	for ( Partial::iterator pos = p.begin(); pos != p.end(); ++pos ) 
	{		
		pos.breakpoint().setFrequency( pos.breakpoint().frequency() * 
									   env->valueAt( pos.time() ) );
	}	
}

// ---------------------------------------------------------------------------
//	NoiseRatioScaler function call operator
// ---------------------------------------------------------------------------
//	Scale the relative noise content of the specified Partial according 
//	to an envelope representing a (time-varying) noise energy 
//	scale value.
//
void 
NoiseRatioScaler::operator()( Partial & p ) const
{
	for ( Partial::iterator pos = p.begin(); pos != p.end(); ++pos ) 
	{		
		//	compute new bandwidth value:
		double bw = pos.breakpoint().bandwidth();
		if ( bw < 1. ) 
		{
			double ratio = bw  / (1. - bw);
			ratio *= env->valueAt( pos.time() );
			bw = ratio / ( 1. + ratio );
		}
		else 
		{
			bw = 1.;
		}		
		pos.breakpoint().setBandwidth( bw );
	}	
}

// ---------------------------------------------------------------------------
//	PitchShifter function call operator
// ---------------------------------------------------------------------------
//	Shift the pitch of the specified Partial according to 
//	the given pitch envelope. The pitch envelope is assumed to have 
//	units of cents (1/100 of a halfstep).
//
void 
PitchShifter::operator()( Partial & p ) const
{
	for ( Partial::iterator pos = p.begin(); pos != p.end(); ++pos ) 
	{		
		//	compute frequency scale:
		double scale = 
			std::pow( 2., ( 0.01 * env->valueAt( pos.time() ) ) / 12. );				
		pos.breakpoint().setFrequency( pos.breakpoint().frequency() * scale );
	}	
}

// ---------------------------------------------------------------------------
//	Cropper function call operator
// ---------------------------------------------------------------------------
//	Trim a Partial by removing Breakpoints outside a specified time span.
//	Insert a Breakpoint at the boundary when cropping occurs.
//
void 
Cropper::operator()( Partial & p ) const
{
	//	crop beginning of Partial
	Partial::iterator it = p.findAfter( minTime );
	if ( it != p.begin() )    // Partial begins earlier than minTime
	{
	    if ( it != p.end() ) // Partial ends later than minTime
	    {
            Breakpoint bp = p.parametersAt( minTime );
            it = p.insert( minTime, bp );
        }
		it = p.erase( p.begin(), it );
	}
	
	//	crop end of Partial
	it = p.findAfter( maxTime );
	if ( it != p.end() ) // Partial ends later than maxTime
	{
	    if ( it != p.begin() )   // Partial begins earlier than maxTime
	    {
	    	Breakpoint bp = p.parametersAt( maxTime );
    		it = p.insert( maxTime, bp );
    		++it;   //  advance, we don't want to cut this one off
		}
		it = p.erase( it, p.end() );
	}
}

// ---------------------------------------------------------------------------
//	TimeShifter function call operator
// ---------------------------------------------------------------------------
//	Shift the time of all the Breakpoints in a Partial by a constant amount.
//
void 
TimeShifter::operator()( Partial & p ) const
{
	//	Since the Breakpoint times are immutable, the only way to 
	//	shift the Partial in time is to construct a new Partial and
	//	assign it to the argument p.
	Partial result;
	result.setLabel( p.label() );
	
	for ( Partial::iterator pos = p.begin(); pos != p.end(); ++pos ) 
	{		
		result.insert( pos.time() + offset, pos.breakpoint() );
	}	
	p = result;
}

// ---------------------------------------------------------------------------
//	peakAmplitude
// ---------------------------------------------------------------------------
//! Return the maximum amplitude achieved by a partial. 
//!  
//! \param  p is the Partial to evaluate
//! \return the maximum (absolute) amplitude achieved by 
//!         the partial p
//
double peakAmplitude( const Partial & p )
{
    double peak = 0;
    for ( Partial::const_iterator it = p.begin();
          it != p.end();
          ++it )
    {
        peak = std::max( peak, it->amplitude() );
    }
    return peak;
}

// ---------------------------------------------------------------------------
//	avgAmplitude
// ---------------------------------------------------------------------------
//! Return the average amplitude over all Breakpoints in this Partial.
//! Return zero if the Partial has no Breakpoints.
//!  
//! \param  p is the Partial to evaluate
//! \return the average amplitude of Breakpoints in the Partial p
//
double avgAmplitude( const Partial & p )
{
    double avg = 0;
    for ( Partial::const_iterator it = p.begin();
          it != p.end();
          ++it )
    {
        avg += it->amplitude();
    }
    
    if ( avg != 0 )
    {
        avg /= p.numBreakpoints();
    }
    
    return avg;
}


// ---------------------------------------------------------------------------
//	avgFrequency
// ---------------------------------------------------------------------------
//! Return the average frequency over all Breakpoints in this Partial.
//! Return zero if the Partial has no Breakpoints.
//!  
//! \param  p is the Partial to evaluate
//! \return the average frequency (Hz) of Breakpoints in the Partial p
//
double avgFrequency( const Partial & p )
{
    double avg = 0;
    for ( Partial::const_iterator it = p.begin();
          it != p.end();
          ++it )
    {
        avg += it->frequency();
    }
    
    if ( avg != 0 )
    {
        avg /= p.numBreakpoints();
    }
    
    return avg;
}


// ---------------------------------------------------------------------------
//	weightedAvgFrequency
// ---------------------------------------------------------------------------
//! Return the average frequency over all Breakpoints in this Partial, 
//! weighted by the Breakpoint amplitudes.
//! Return zero if the Partial has no Breakpoints.
//!  
//! \param  p is the Partial to evaluate
//! \return the average frequency (Hz) of Breakpoints in the Partial p
//
double weightedAvgFrequency( const Partial & p )
{
    double avg = 0;
    double ampsum = 0;
    for ( Partial::const_iterator it = p.begin();
          it != p.end();
          ++it )
    {
        avg += it->amplitude() * it->frequency();
        ampsum += it->amplitude();
    }
    
    if ( avg != 0 && ampsum != 0 )
    {
        avg /= ampsum;
    }
    else
    {
        avg = 0;
    }
    
    return avg;
}

//	-- phase maintenance functions --

// ---------------------------------------------------------------------------
//	fixPhaseBefore
//
//! Recompute phases of all Breakpoints earlier than the specified time 
//! so that the synthesize phases of those earlier Breakpoints matches 
//! the stored phase, and the synthesized phase at the specified
//! time matches the stored (not recomputed) phase.
//! 
//! Backward phase-fixing stops if a null (zero-amplitude) Breakpoint
//! is encountered, because nulls are interpreted as phase reset points
//! in Loris. If a null is encountered, the remainder of the Partial
//! (the front part) is fixed in the forward direction, beginning at
//! the start of the Partial.
//!
//! \param p    The Partial whose phases should be fixed.
//! \param t    The time before which phases should be adjusted.
//
void fixPhaseBefore( Partial & p, double t )
{
    if ( 1 < p.numBreakpoints() )
    {
        Partial::iterator pos = p.findNearest( t );
        Assert( pos != p.end() );

        fixPhaseBackward( p.begin(), pos );
    }
}

// ---------------------------------------------------------------------------
//	fixPhaseAfter
//
//! Recompute phases of all Breakpoints later than the specified time 
//! so that the synthesize phases of those later Breakpoints matches 
//! the stored phase, as long as the synthesized phase at the specified
//! time matches the stored (not recomputed) phase.
//! 
//! Phase fixing is only applied to non-null (nonzero-amplitude) Breakpoints,
//! because null Breakpoints are interpreted as phase reset points in 
//! Loris. If a null is encountered, its phase is simply left unmodified,
//! and future phases wil be recomputed from that one.
//!
//! \param p    The Partial whose phases should be fixed.
//! \param t    The time after which phases should be adjusted.
//
void fixPhaseAfter( Partial & p, double t )
{
    //  nothing to do it there are not at least
    //  two Breakpoints in the Partial   
    if ( 1 < p.numBreakpoints() )
    {
        Partial::iterator pos = p.findNearest( t );
        Assert( pos != p.end() );

        fixPhaseForward( pos, --p.end() );
    }
}

// ---------------------------------------------------------------------------
//	fixPhaseForward
//
//! Recompute phases of all Breakpoints later than the specified time 
//! so that the synthesize phases of those later Breakpoints matches 
//! the stored phase, as long as the synthesized phase at the specified
//! time matches the stored (not recomputed) phase. Breakpoints later than
//! tend are unmodified.
//! 
//! Phase fixing is only applied to non-null (nonzero-amplitude) Breakpoints,
//! because null Breakpoints are interpreted as phase reset points in 
//! Loris. If a null is encountered, its phase is simply left unmodified,
//! and future phases wil be recomputed from that one.
//!
//! HEY Is this interesting, in general? Why would you want to do this?
//!
//! \param p    The Partial whose phases should be fixed.
//! \param tbeg The phases and frequencies of Breakpoints later than the 
//!             one nearest this time will be modified.
//! \param tend The phases and frequencies of Breakpoints earlier than the 
//!             one nearest this time will be modified. Should be greater 
//!             than tbeg, or else they will be swapped.
//
void fixPhaseForward( Partial & p, double tbeg, double tend )
{
    if ( tbeg > tend )
    {
        std::swap( tbeg, tend );
    }
    
    //  nothing to do it there are not at least
    //  two Breakpoints in the Partial   
    if ( 1 < p.numBreakpoints() )
    {
        //  find the positions nearest tbeg and tend
        Partial::iterator posbeg = p.findNearest( tbeg );
        Partial::iterator posend = p.findNearest( tend );
        
        //  if the positions are different, and tend is
        //  the end, back it up
        if ( posbeg != posend && posend == p.end() )
        {
            --posend;
        }
        fixPhaseForward( posbeg, posend );
    }
}

// ---------------------------------------------------------------------------
//	fixPhaseAt
//
//! Recompute phases of all Breakpoints in a Partial
//! so that the synthesize phases match the stored phases, 
//! and the synthesized phase at (nearest) the specified
//! time matches the stored (not recomputed) phase.
//! 
//! Backward phase-fixing stops if a null (zero-amplitude) Breakpoint
//! is encountered, because nulls are interpreted as phase reset points
//! in Loris. If a null is encountered, the remainder of the Partial
//! (the front part) is fixed in the forward direction, beginning at
//! the start of the Partial. Forward phase fixing is only applied 
//! to non-null (nonzero-amplitude) Breakpoints. If a null is encountered, 
//! its phase is simply left unmodified, and future phases wil be 
//! recomputed from that one.
//!
//! \param p    The Partial whose phases should be fixed.
//! \param t    The time at which phases should be made correct.
//
void fixPhaseAt( Partial & p, double t )
{
    if ( 1 < p.numBreakpoints() )
    {
        Partial::iterator pos = p.findNearest( t );
        Assert( pos != p.end() );

        fixPhaseForward( pos, --p.end() );
        fixPhaseBackward( p.begin(), pos );
    }
}

// ---------------------------------------------------------------------------
//  fixPhaseBetween
//
//!	Fix the phase travel between two times by adjusting the
//!	frequency and phase of Breakpoints between those two times.
//!
//!	This algorithm assumes that there is nothing interesting about the
//!	phases of the intervening Breakpoints, and modifies their frequencies 
//!	as little as possible to achieve the correct amount of phase travel 
//!	such that the frequencies and phases at the specified times
//!	match the stored values. The phases of all the Breakpoints between 
//! the specified times are recomputed.
//!
//! THIS DOES NOT YET TREAT NULL BREAKPOINTS DIFFERENTLY FROM OTHERS.
//!
//! \pre        There must be at least one Breakpoint in the
//!             Partial between the specified times tbeg and tend.
//! \post       The phases and frequencies of the Breakpoints in the 
//!             range have been recomputed such that an oscillator
//!             initialized to the parameters of the first Breakpoint
//!             will arrive at the parameters of the last Breakpoint,
//!             and all the intervening Breakpoints will be matched.
//!	\param p    The partial whose phases and frequencies will be recomputed. 
//!             The Breakpoint at this position is unaltered.
//! \param tbeg The phases and frequencies of Breakpoints later than the 
//!             one nearest this time will be modified.
//! \param tend The phases and frequencies of Breakpoints earlier than the 
//!             one nearest this time will be modified. Should be greater 
//!             than tbeg, or else they will be swapped.
//
void fixPhaseBetween( Partial & p, double tbeg, double tend )
{
    if ( tbeg > tend )
    {
        std::swap( tbeg, tend );
    }

    // for Partials that do not extend over the entire
    // specified time range, just recompute phases from
    // beginning or end of the range:
    if ( p.endTime() < tend )
    {
        // OK if start time is also after tbeg, will
        // just recompute phases from start of p.
        fixPhaseAfter( p, tbeg );
    }
    else if ( p.startTime() > tbeg )
    {
        fixPhaseBefore( p, tend );
    }
    else
    {
        // invariant:
        // p begins before tbeg and ends after tend.
        Partial::iterator b = p.findNearest( tbeg );
        Partial::iterator e = p.findNearest( tend );

        // if there is a null Breakpoint n between b and e, then
        // should fix forward from b to n, and backward from
        // e to n. Otherwise, do this complicated thing.
        Partial::iterator nullbp = std::find_if( b, e, BreakpointUtils::isNull );
        if ( nullbp != e )
        {
            fixPhaseForward( b, nullbp );
            fixPhaseBackward( nullbp, e );
        }
        else
        {
            fixPhaseBetween( b, e );
        }
    }
}

}	//	end of namespace PartialUtils

}	//	end of namespace Loris