diff hs.cpp @ 5:5f3c32dc6e17

* Adjust comment syntax to permit Doxygen to generate HTML documentation; add Doxyfile

--- a/hs.cpp	Tue Oct 05 17:03:27 2010 +0100
+++ b/hs.cpp	Wed Oct 06 15:19:49 2010 +0100
@@ -12,10 +12,12 @@
 #undef I
 #endif
 
+/** \file hs.h */
+
 //---------------------------------------------------------------------------
 //stiffcandid methods
 
-/*
+/**
   method stiffcandid::stiffcandid: creates a harmonic atom with minimal info, i.e. fundamantal frequency
   between 0 and Nyqvist frequency, stiffness coefficient between 0 and STIFF_B_MAX.
 
@@ -36,7 +38,7 @@
   f=NULL;
 }//stiffcandid
 
-/*
+/**
   method stiffcandid::stiffcandid: creates a harmonic atom with a frequency range for the $ap-th partial,
   without actually taking this partial as "known".
 
@@ -66,7 +68,7 @@
   cutcvpoly(N, F, G, -1, -k, g1);
 }//stiffcandid
 
-/*
+/**
   method stiffcandid::stiffcandid: creates a harmonic atom from one atom.
 
   In; Wid: DFT size
@@ -577,7 +579,7 @@
 //---------------------------------------------------------------------------
 //functions
 
-/*
+/**
   function areaandcentroid: calculates the area and centroid of a convex polygon.
 
   In: x[N], y[N]: x- and y-coordinates of vertices of a polygon
@@ -607,7 +609,7 @@
   cy=cy/6/A;
 }//areaandcentroid
 
-/*
+/**
   function AtomsToPartials: sort a list of atoms as a number of partials. It is assumed that the atoms
   are simply those from a harmonic sinusoid in arbitrary order with uniform timing and partial index
   clearly marked, so that it is easy to sort them into a list of partials. However, the sorting process
@@ -653,7 +655,7 @@
   else M=0, Fr=0;
 }//AtomsToPartials
 
-/*
+/**
   function conta: a continuity measure between two set of amplitudes
 
   In: a1[N], a2[N]: the amplitudes
@@ -674,7 +676,7 @@
   return 2*e12/(e11+e22);
 }//conta
 
-/*
+/**
   function cutcvpoly: severs a polygon by a straight line
 
   In: x[N], y[N]: x- and y-coordinates of vertices of a polygon, starting from the leftmost (x[0]=
@@ -823,7 +825,7 @@
   cutcvpoly(R->N, R->X, R->Y, -1, -k, g1, protect);         //
 }//CutR
 
-/*
+/**
   function DeleteByHalf: reduces a list of stiffcandid objects by half, retaining those with higher s
   and delete the others, freeing their memory.
 
@@ -847,7 +849,7 @@
   return k;
 }//DeleteByHalf
 
-/*
+/**
   function DeleteByHalf: reduces a list of TTempAtom objects by half, retaining those with higher s and
   delete the others, freeing their memory.
 
@@ -872,7 +874,7 @@
   return k;
 }//DeleteByHalf
 
-/*
+/**
   function ds0: atom score 0 - energy
 
   In: a: atom amplitude
@@ -885,7 +887,7 @@
   else return a*a;
 }//ds0
 
-/*
+/**
   function ds2: atom score 1 - cross-correlation coefficient with another HA, e.g. from previous frame
 
   In: a: atom amplitude
@@ -902,7 +904,7 @@
   else return (lparams->s*hs+a*a)/hsaa;
 }//ds1
 
-/*
+/**
   function ExBStiff: finds the minimal and maximal values of stiffness coefficient B given a F-G polygon
 
   In: F[N], G[N]: vertices of a F-G polygon
@@ -922,7 +924,7 @@
   }
 }//ExBStiff
 
-/*
+/**
   function ExFmStiff: finds the minimal and maximal frequecies of partial m given a F-G polygon
 
   In: F[N], G[N]: vertices of a F-G polygon
@@ -946,7 +948,7 @@
   testnn(vmax); Fmax=m*sqrt(vmax);
 }//ExFmStiff
 
-/*
+/**
   function ExtendR: extends a F-G polygon on the f axis (to allow a larger pitch range)
 
   In: R: the F-G polygon
@@ -1094,7 +1096,7 @@
   }
 }//ExtendR
 
-/*
+/**
   function FGFrom2: solves the following equation system given m[2], f[2], norm[2]. This is interpreted
   as searching from (F0, G0) down direction (dF, dG) until the first equation is satisfied, where
   k[*]=m[*]^2-1.
@@ -1179,7 +1181,7 @@
   }
 }//FGFrom2
 
-/*
+/**
   function FGFrom2: solves the following equation system given m[2], f[2], k[2]. This is interpreted as
   searching from (F0, G0) down direction (dF, dG) until the first equation is satisfied. Functionally
   this is the same as the version using norm[2], with m[] anf f[] normalized by norm[] beforehand so
@@ -1270,7 +1272,7 @@
   }
 }//FGFrom2
 
-/*
+/**
   function FGFrom3: solves the following equation system given m[3], f[3], norm[3].
 
     m[0](F+k[0]G)^0.5-f[0]       m[1](F+k[1]G)^0.5-f[1]       m[2](F+k[2]G)^0.5-f[2]
@@ -1358,7 +1360,7 @@
   }
 }//FGFrom3
 
-/*
+/**
   function FGFrom3: solves the following equation system given m[3], f[3], k[3]. Functionally this is
   the same as the version using norm[3], with m[] anf f[] normalized by norm[] beforehand so that norm[]
   is no longer needed. However, k[3] cannot be computed from normalized m[3] so that it must be
@@ -1466,7 +1468,7 @@
   }
 }//FGFrom3
 
-/*
+/**
   function FindNote: harmonic sinusoid tracking from a starting point in time-frequency plane forward
   and backward.
 
@@ -1521,7 +1523,7 @@
   return 0;
 }//Findnote*/
 
-/*
+/**
   function FindNoteConst: constant-pitch harmonic sinusoid tracking
 
   In: _t, _f: start time and frequency
@@ -1658,7 +1660,7 @@
   return 1;
 }//FindNoteConst
 
-/*
+/**
   function FindNoteF: forward harmonic sinusoid tracking starting from a given harmonic atom until an
   endpoint is detected or a search boundary is reached.
 
@@ -1705,7 +1707,7 @@
   return k;
 }//FindNoteF
 
-/*
+/**
   function FindNoteFB: forward-backward harmonic sinusid tracking.
 
   In: frst, fren: index of start and end frames
@@ -1858,7 +1860,7 @@
   return result;  //*/
 }//FindNoteFB
 
-/*
+/**
   function GetResultsSingleFr: used by NoteMatchStiff3 to obtain final note match results after harmonic
   grouping of peaks with rough frequency estimates, including a screening of found peaks based on shape
   and consistency with other peak frequencies, reestimating sinusoid parameters using LSE, estimating
@@ -1974,7 +1976,7 @@
   return result;
 }//GetResultsSingleFr
 
-/*
+/**
   function GetResultsMultiFr: the constant-pitch multi-frame version of GetResultsSingleFr.
 
   In: x[Fr][N]: spectrogram
@@ -2093,7 +2095,7 @@
   return result;
 }//GetResultsMultiFr
 
-/*
+/**
   function InitailizeR: initializes a F-G polygon with a fundamental frequency range and stiffness coefficient bound
 
   In: af, ef: centre and half width of the fundamental frequency range
@@ -2113,7 +2115,7 @@
   Y[0]=X[0]*maxB, Y[1]=X[1]*maxB, Y[2]=Y[3]=0;
 }//InitializeR
 
-/*
+/**
   function InitialzeR: initializes a F-G polygon with a frequency range for a given partial and
   stiffness coefficient bound
 
@@ -2137,7 +2139,7 @@
   Y[0]=X[0]*maxB, Y[1]=X[1]*maxB, Y[2]=Y[3]=0;
 }//InitializeR
 
-/*
+/**
   function maximalminimum: finds the point within a polygon that maximizes its minimal distance to the
   sides.
 
@@ -2246,7 +2248,7 @@
   return dm;
 }//maximalminimum
 
-/*
+/**
   function minimaxstiff: finds the point in polygon (N; F, G) that minimizes the maximal value of the
   function
 
@@ -3370,7 +3372,7 @@
   return vmax;
 }//minimaxstiff*/
 
-/*
+/**
   function NMResultToAtoms: converts the note-match result hosted in a NMResults structure, i.e.
   parameters of a harmonic atom, to a list of atoms. The process retrieves atom parameters from low
   partials until a required number of atoms have been retrieved or a non-positive frequency is
@@ -3398,7 +3400,7 @@
   return M;
 }//NMResultToAtoms
 
-/*
+/**
   function NMResultToPartials: reads atoms of a harmonic atom in a NMResult structure into HS partials.
 
   In: results: the NMResults structure hosting the harmonic atom
@@ -3424,7 +3426,7 @@
   return M;
 }//NMResultToPartials
 
-/*
+/**
   function NoteMatchStiff3: finds harmonic atom from spectrum if Fr=1, or constant-pitch harmonic
   sinusoid from spectrogram if Fr>1.
 
@@ -3695,7 +3697,7 @@
   return result;
 }//NoteMatchStiff3
 
-/*
+/**
   function NoteMatchStiff3: finds harmonic atom from spectrum if Fr=1, or constant-pitch harmonic
   sinusoid from spectrogram if Fr>1. This version uses residue-sinusoid ratio ("rsr") that measures how
   "good" a spectral peak is in terms of its shape. peaks with large rsr[] is likely to be contaminated
@@ -4012,7 +4014,7 @@
   return result;
 }//NoteMatchStiff3
 
-/*
+/**
   function NoteMatchStiff3: wrapper function of the above that does peak picking and HA grouping (or
   constant-pitch HS finding) in a single call.
 
@@ -4047,7 +4049,7 @@
   return result;
 }//NoteMatchStiff3
 
-/*
+/**
   function NoteMatchStiff3: finds harmonic atom from spectrum given the pitch as a (partial index,
   frequency) pair. This is used internally by NoteMatch3FB().
 
@@ -4185,7 +4187,7 @@
   return result;
 }//NoteMatchStiff3*/
 
-/*
+/**
   function NoteMatchStiff3FB: does one dynamic programming step in forward-background pitch tracking of
   harmonic sinusoids. This is used internally by FindNoteFB().
 
@@ -4294,7 +4296,7 @@
   pitchcount=newpc;
 }//NoteMatchStiff3FB
 
-/*
+/**
   function PeakShapeC: residue-sinusoid-ratio for a given (hypothesis) sinusoid frequency
 
   In: x[Fr][N/2+1]: spectrogram
@@ -4336,7 +4338,7 @@
   return 1-xw2/(xx.x*ww.x);
 }//PeakShapeC
 
-/*
+/**
   function QuickPeaks: finds rough peaks in the spectrum (peak picking)
 
   In: x[N/2+1]: spectrum
@@ -4390,7 +4392,7 @@
   return p;
 }//QuickPeaks
 
-/*
+/**
   function QuickPeaks: finds rough peaks in the spectrogram (peak picking) for constant-frequency
   sinusoids
 
@@ -4516,7 +4518,7 @@
   return pc;
 }//QuickPeaks
 
-/*
+/**
   function ReEstHS1: reestimates a harmonic sinusoid by one multiplicative reestimation using phasor
   multiplier
 
@@ -4542,7 +4544,7 @@
   delete[] fs;
 }//ReEstHS1
 
-/*
+/**
   function ReEstHS1: wrapper function.
 
   In: HS: a harmonic sinusoid
@@ -4556,7 +4558,7 @@
   ReEstHS1(HS->M, HS->Fr, 0, HS->Fr, HS->Partials, Data16);
 }//ReEstHS1
 
-/*
+/**
   function SortCandid: inserts a candid object into a listed of candid objects sorted first by f, then
   (for identical f's) by df.
 
@@ -4577,7 +4579,7 @@
   return lnN;
 }//SortCandid
 
-/*
+/**
   function SynthesisHS: synthesizes a harmonic sinusoid without aligning the phases
 
   In: partials[M][Fr]: HS partials
@@ -4633,7 +4635,7 @@
   return xrec;
 }//SynthesisHS
 
-/*
+/**
   function SynthesisHS: synthesizes a perfectly harmonic sinusoid without aligning the phases.
   Frequencies of partials above the fundamental are not used in this synthesis process.
 
@@ -4699,7 +4701,7 @@
   return xrec;
 }//SynthesisHS2
 
-/*
+/**
   function SynthesisHSp: synthesizes a harmonic sinusoid with phase alignment
 
   In: partials[pm][pfr]: HS partials
@@ -4782,7 +4784,7 @@
   return xrec;
 }//SynthesisHSp
 
-/*
+/**
   function SynthesisHSp: wrapper function.
 
   In: HS: a harmonic sinusoid.