annotate Agent.h @ 6:02d388f98c23

Introduce a number of new classes derived from the Java

/* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */

/*
  Vamp feature extraction plugin for the BeatRoot beat tracker.

  Centre for Digital Music, Queen Mary, University of London.
  This file copyright 2011 Simon Dixon, Chris Cannam and QMUL.
    
  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.  See the file
  COPYING included with this distribution for more information.
*/

#ifndef _AGENT_H_
#define _AGENT_H_

#include "Event.h"

/** Agent is the central class for beat tracking.
 *  Each Agent object has a tempo hypothesis, a history of tracked beats, and
 *  a score evaluating the continuity, regularity and salience of its beat track.
 */
class Agent
{
public:

    typedef std::vector<Agent> AgentList;

    /** The maximum amount by which a beat can be later than the predicted beat time,
     *  expressed as a fraction of the beat period. */
    static double POST_MARGIN_FACTOR;

    /** The maximum amount by which a beat can be earlier than the predicted beat time,
     *  expressed as a fraction of the beat period. */
    static double PRE_MARGIN_FACTOR;
	
    /** The default value of innerMargin, which is the maximum time (in seconds) that a
     * 	beat can deviate from the predicted beat time without a fork occurring. */
    static const double INNER_MARGIN;
	
    /** The maximum allowed deviation from the initial tempo, expressed as a fraction of the initial beat period. */
    static double MAX_CHANGE;
		
    /** The slope of the penalty function for onsets which do not coincide precisely with predicted beat times. */
    static double CONF_FACTOR;
	
    /** The reactiveness/inertia balance, i.e. degree of change in the tempo, is controlled by the correctionFactor
     *  variable.  This constant defines its default value, which currently is not subsequently changed. The
     *  beat period is updated by the reciprocal of the correctionFactor multiplied by the difference between the
     *  predicted beat time and matching onset. */
    static const double DEFAULT_CORRECTION_FACTOR;
	
    /** The default value of expiryTime, which is the time (in seconds) after which an Agent that
     *  has no Event matching its beat predictions will be destroyed. */
    static const double DEFAULT_EXPIRY_TIME;

protected:
    /** The identity number of the next created Agent */
    static int idCounter;
	
    /** The maximum time (in seconds) that a beat can deviate from the predicted beat time
     *  without a fork occurring (i.e. a 2nd Agent being created). */
    static double innerMargin;

    /** Controls the reactiveness/inertia balance, i.e. degree of change in the tempo.  The
     *  beat period is updated by the reciprocal of the correctionFactor multiplied by the difference between the
     *  predicted beat time and matching onset. */
    static double correctionFactor;

    /** The time (in seconds) after which an Agent that
     *  has no Event matching its beat predictions will be destroyed. */
    static double expiryTime;
	
    /** For scoring Agents in a (non-existent) real-time version (otherwise not used). */
    static double decayFactor;

public:
    /** The size of the outer half-window before the predicted beat time. */
    double preMargin;

    /** The size of the outer half-window after the predicted beat time. */
    double postMargin;
	
    /** The Agent's unique identity number. */
    int idNumber;
	
    /** To be used in real-time version?? */
    double tempoScore;
	
    /** Sum of salience values of the Events which have been interpreted
     *  as beats by this Agent, weighted by their nearness to the predicted beat times. */
    double phaseScore;
	
    /** How long has this agent been the best?  For real-time version; otherwise not used. */
    double topScoreTime;
	
    /** The number of beats found by this Agent, including interpolated beats. */
    int beatCount;
	
    /** The current tempo hypothesis of the Agent, expressed as the beat period in seconds. */
    double beatInterval;

    /** The initial tempo hypothesis of the Agent, expressed as the beat period in seconds. */
    double initialBeatInterval;
	
    /** The time of the most recent beat accepted by this Agent. */
    double beatTime;
	
    /** The list of Events (onsets) accepted by this Agent as beats, plus interpolated beats. */
    EventList events;

    /** Constructor: the work is performed by init()
     *  @param ibi The beat period (inter-beat interval) of the Agent's tempo hypothesis.
     */
    Agent(double ibi) {
	init(ibi);
    } // constructor

    /** Copy constructor.
     *  @param clone The Agent to duplicate. */
    Agent(const Agent &clone) {
	idNumber = idCounter++;
	phaseScore = clone.phaseScore;
	tempoScore = clone.tempoScore;
	topScoreTime = clone.topScoreTime;
	beatCount = clone.beatCount;
	beatInterval = clone.beatInterval;
	initialBeatInterval = clone.initialBeatInterval;
	beatTime = clone.beatTime;
	events = EventList(clone.events);
	postMargin = clone.postMargin;
	preMargin = clone.preMargin;
    } // copy constructor

protected:
    /** Initialise all the fields of this Agent.
     *  @param ibi The initial tempo hypothesis of the Agent.
     */
    void init(double ibi) {
	innerMargin = INNER_MARGIN;
	correctionFactor = DEFAULT_CORRECTION_FACTOR;
	expiryTime = DEFAULT_EXPIRY_TIME;
	decayFactor = 0;
	beatInterval = ibi;
	initialBeatInterval = ibi;
	postMargin = ibi * POST_MARGIN_FACTOR;
	preMargin = ibi * PRE_MARGIN_FACTOR;
	idNumber = idCounter++;
	phaseScore = 0.0;
	tempoScore = 0.0;
	topScoreTime = 0.0;
	beatCount = 0;
	beatTime = -1.0;
	events.clear();
    } // init()


    double threshold(double value, double min, double max) {
	if (value < min)
	    return min;
	if (value > max)
	    return max;
	return value;
    }

    /** Accept a new Event as a beat time, and update the state of the Agent accordingly.
     *  @param e The Event which is accepted as being on the beat.
     *  @param err The difference between the predicted and actual beat times.
     *  @param beats The number of beats since the last beat that matched an Event.
     */
    void accept(Event e, double err, int beats) {
	beatTime = e.time;
	events.push_back(e);
	if (fabs(initialBeatInterval - beatInterval -
		 err / correctionFactor) < MAX_CHANGE * initialBeatInterval)
	    beatInterval += err / correctionFactor;// Adjust tempo
	beatCount += beats;
	double conFactor = 1.0 - CONF_FACTOR * err /
	    (err>0? postMargin: -preMargin);
	if (decayFactor > 0) {
	    double memFactor = 1. - 1. / threshold((double)beatCount,1,decayFactor);
	    phaseScore = memFactor * phaseScore +
		(1.0 - memFactor) * conFactor * e.salience;
	} else
	    phaseScore += conFactor * e.salience;
    } // accept()

    /** The given Event is tested for a possible beat time. The following situations can occur:
     *  1) The Agent has no beats yet; the Event is accepted as the first beat.
     *  2) The Event is beyond expiryTime seconds after the Agent's last 'confirming' beat; the Agent is terminated.
     *  3) The Event is within the innerMargin of the beat prediction; it is accepted as a beat.
     *  4) The Event is within the outerMargin's of the beat prediction; it is accepted as a beat by this Agent,
     *     and a new Agent is created which doesn't accept it as a beat.
     *  5) The Event is ignored because it is outside the windows around the Agent's predicted beat time.
     * @param e The Event to be tested
     * @param a The list of all agents, which is updated if a new agent is created.
     * @return Indicate whether the given Event was accepted as a beat by this Agent.
     */
    bool considerAsBeat(Event e, const AgentList &a);

    /** Interpolates missing beats in the Agent's beat track, starting from the beginning of the piece. */
    void fillBeats() {
	fillBeats(-1.0);
    } // fillBeats()/0

    /** Interpolates missing beats in the Agent's beat track.
     *  @param start Ignore beats earlier than this start time 
     */
    void fillBeats(double start);

}; // class Agent

typedef Agent::AgentList AgentList;

#endif