Chris@26: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
Chris@26: 
Chris@26: /*
Chris@26:     Vamp feature extraction plugin using the MATCH audio alignment
Chris@26:     algorithm.
Chris@26: 
Chris@26:     Centre for Digital Music, Queen Mary, University of London.
Chris@236:     Copyright (c) 2007-2020 Simon Dixon, Chris Cannam, and Queen Mary
Chris@230:     University of London, Copyright (c) 2014-2015 Tido GmbH.
Chris@26:     
Chris@26:     This program is free software; you can redistribute it and/or
Chris@26:     modify it under the terms of the GNU General Public License as
Chris@26:     published by the Free Software Foundation; either version 2 of the
Chris@26:     License, or (at your option) any later version.  See the file
Chris@26:     COPYING included with this distribution for more information.
Chris@26: */
Chris@26: 
Chris@26: #ifndef DISTANCE_METRIC_H
Chris@26: #define DISTANCE_METRIC_H
Chris@26: 
Chris@187: #include "MatchTypes.h"
Chris@26: 
Chris@26: class DistanceMetric
Chris@26: {
Chris@26: public:
Chris@156:     enum Metric {
Chris@156: 
Chris@157:         /** Calculate the Manhattan distance between feature
Chris@157:          *  vectors. If the vectors contain energy, as the default
Chris@157:          *  MATCH feature does, this could be considered as a squared
Chris@157:          *  Euclidean distance metric. */
Chris@157:         Manhattan,
Chris@157: 
Chris@156:         /** Calculate the Euclidean distance between feature vectors. */
Chris@156:         Euclidean,
Chris@156: 
Chris@156:         /** Calculate the cosine distance between feature vectors. The
Chris@156:          *  normalisation setting will be ignored as the result is
Chris@156:          *  already magnitude-independent. */
Chris@156:         Cosine,
Chris@156:     };
Chris@156: 
Chris@26:     enum DistanceNormalisation {
Chris@26:             
Chris@26:         /** Do not normalise distance metrics */
Chris@26:         NoDistanceNormalisation,
Chris@26: 
Chris@26:         /** Normalise distance metric for pairs of frames by the sum
Chris@26:          *  of the two frames. */
Chris@26:         NormaliseDistanceToSum,
Chris@26: 
Chris@26:         /** Normalise distance metric for pairs of frames by the log
Chris@26:          *  of the sum of the frames. */
Chris@26:         NormaliseDistanceToLogSum,
Chris@26:     };
Chris@156:     
Chris@150:     enum NoiseAddition {
Chris@150: 
Chris@150:         /** Don't add noise. */
Chris@150:         NoNoise,
Chris@150: 
Chris@150:         /** Add a constant noise term. This can help avoid
Chris@150:          *  mis-tracking when one file contains a lot of silence. */
Chris@150:         AddNoise,
Chris@150:     };
Chris@150:     
Chris@143:     struct Parameters {
Chris@143: 
Chris@143:         Parameters() :
Chris@157:             metric(Manhattan),
Chris@150:             norm(NormaliseDistanceToLogSum),
Chris@184:             noise(AddNoise),
Chris@213:             scale(150.)
Chris@143:         {}
Chris@143: 
Chris@156:         Metric metric;
Chris@143:         DistanceNormalisation norm;
Chris@150:         NoiseAddition noise;
Chris@184:         double scale;
Chris@143:     };
Chris@143:     
Chris@143:     DistanceMetric(Parameters params);
Chris@190: 
Chris@190:     ~DistanceMetric();
Chris@26:     
Chris@157:     /** Calculates the distance in some metric between two vectors,
Chris@157:      *  with an optional normalisation by the combined values in the
Chris@157:      *  vectors. Note that normalisation assumes the values are all
Chris@157:      *  non-negative.
Chris@26:      *
Chris@26:      *  @param f1 one of the vectors involved in the distance calculation
Chris@26:      *  @param f2 one of the vectors involved in the distance calculation
Chris@26:      *  @return the distance
Chris@26:      */
Chris@183:     distance_t calcDistance(const feature_t &f1,
Chris@183:                             const feature_t &f2);
Chris@186: 
Chris@186:     /**
Chris@186:      * Mostly for internal use and testing
Chris@186:      */
Chris@186:     distance_t scaleValueIntoDistanceRange(double value);
Chris@26:     
Chris@26: private:
Chris@143:     Parameters m_params;
Chris@185: 
Chris@190:     distance_t scaleAndTally(double);
Chris@185:     template <typename T> T scaleIntoRange(double);
Chris@190: 
Chris@190:     distance_t m_max;
Chris@190:     int m_overcount;
Chris@26: };
Chris@26: 
Chris@26: #endif