comparison hs.cpp @ 5:5f3c32dc6e17

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

 #include "xcomplex.h"
 #ifdef I
 #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.
 
   In: Wid: DFT size (frame size, frequency resolution)
 */

   s=0;
   p=NULL;
   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".
 
   In; Wid: DFT size
       ap: partial index

   //apply constraints F+kG-g2<0 and -F-kG+g1<0
   cutcvpoly(N, F, G, 1, k, -g2);
   cutcvpoly(N, F, G, -1, -k, g1);
 }//stiffcandid
 
-/*
+/**
   method stiffcandid::stiffcandid: creates a harmonic atom from one atom.
 
   In; Wid: DFT size
       ap: partial index of the atom.
       af, errf: centre and half-width of the frequency range of the atom, in bins.

 
 
 //---------------------------------------------------------------------------
 //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
   Out: A: area
        (cx, cy): coordinate of the centroid

   A/=2;
   cx=cx/6/A;
   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
   does not check for harmonicity, missing or duplicate atoms, uniformity of timing, etc.
 

     else M=0, Fr=0;
   }
   else M=0, Fr=0;
 }//AtomsToPartials
 
-/*
+/**
   function conta: a continuity measure between two set of amplitudes
 
   In: a1[N], a2[N]: the amplitudes
 
   Return the continuity measure, between 0 and 1

     e22+=la2*la2;
   }
   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]=
         min x[n]) point clockwise; in case of two leftmost points, x[0] is the upper one and x[N-1] is
         the lower one.

   //apply constraints F+kG-g2<0 and -F-kG+g1<0
   cutcvpoly(R->N, R->X, R->Y, 1, k, -g2, protect);          //  update R
   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.
 
   In: cands[pcs]: the list of stiffcandid objects
   Out: cands[return value]: the list of retained ones

     else delete cands[j];
   }
   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.
 
   In: cands[pcs]: the list of TTempAtom objects
   Out: cands[return value]: the list of retained ones

   }
   delete[] tmp;
   return k;
 }//DeleteByHalf
 
-/*
+/**
   function ds0: atom score 0 - energy
 
   In: a: atom amplitude
 
   Returns a^2, or s[0]+a^2 is s is not NULL, as atom score.

 {
   if (s) return	*(double*)s+a*a;
   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
       params: pointer to dsprams1 structure supplying other inputs.
   Out: cross-correlation coefficient as atom score.

   double hs=lparams->lastene+lparams->currentacce, hsaa=hs+a*a;
   if (lparams->p<=lparams->lastP) return (lparams->s*hs+a*lparams->lastvfp[lparams->p-1])/hsaa;
   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
   Out: Bmin, Bmax: minimal and maximal values of the stiffness coefficient
 

     if (Bmin>vi) Bmin=vi;
     else if (Bmax<vi) Bmax=vi;
   }
 }//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
       m: partial index, fundamental=1
   Out: Fmin, Fmax: minimal and maximal frequencies of partial m

   }
   testnn(vmin); Fmin=m*sqrt(vmin);
   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
       delp1: amount of extension to the low end, in semitones
       delpe: amount of extension to the high end, in semitones

       memcpy(&G[1], &G[n], sizeof(double)*(N-n));
     }
   }
 }//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.
 
     m[0](F+k[0]G)^0.5-f[0]     m[1](F+k[1]G)^0.5-f[1]

       return roots;
     }
   }
 }//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
   that norm[] is no longer needed. However, k[2] cannot be computed from normalized m[2] so that it must
   be specified explicitly.

       return roots;
     }
   }
 }//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]
    ------------------------  =  ------------------------  =  ------------------------ > 0
            norm[0]                      norm[1]                      norm[2]

       return roots;
     }
   }
 }//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
   specified explicitly.
 

       return roots;
     }
   }
 }//FGFrom3
 
-/*
+/**
   function FindNote: harmonic sinusoid tracking from a starting point in time-frequency plane forward
   and backward.
 
   In: _t, _f: start time and frequency
       frst, fren: tracking range, in frames

   //	ReEst1(M, frst, fren, partials, WV->Data16[channel], wid, offst);
 
   return 0;
 }//Findnote*/
 
-/*
+/**
   function FindNoteConst: constant-pitch harmonic sinusoid tracking
 
   In: _t, _f: start time and frequency
       frst, fren: tracking range, in frames
       Spec: spectrogram

   delete R; delete[] x; delete[] as; DeAlloc2(xx);
   delete[] starts;
   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.
 
   In: starts: harmonic atom score of the start HA
       startvfp[startp]: amplitudes of partials of start HA

   }
   delete RR; delete[] lastvfp; delete[] x; delete[] fpp;
   return k;
 }//FindNoteF
 
-/*
+/**
   function FindNoteFB: forward-backward harmonic sinusid tracking.
 
   In: frst, fren: index of start and end frames
       Rst, Ren: F-G polygons of start and end harmonic atoms
       vfpst[M], vfpen[M]: amplitude vectors of start and end harmonic atoms

   DeAlloc2(pitches); DeAlloc2(prev);
   delete[] pitchres; delete[] pc;
   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
   atoms without peaks by inferring their frequencies, and translating internal peak type to atom type.
 

       delete[] f1; delete[] values; delete[] indices;
   }
   return result;
 }//GetResultsSingleFr
 
-/*
+/**
   function GetResultsMultiFr: the constant-pitch multi-frame version of GetResultsSingleFr.
 
   In: x[Fr][N]: spectrogram
       ps[P], fs[P]; partial indices and frequencies, may miss partials
       psb[P]: peak type flags, related to atom::ptype.

   }
   delete[] pclass;
   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
       maxB: maximal value of stiffness coefficient (the minimal is set to 0)
   Out: R: the initialized F-G polygon.

   g1=g1*g1, g2=g2*g2;
   X[0]=X[3]=g1, X[1]=X[2]=g2;
   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
 
   In: apind: partial index
       af, ef: centre and half width of the frequency range of the apind-th partial

   double kb1=1+k*maxB;
   X[0]=g1/kb1, X[1]=g2/kb1, X[2]=g2, X[3]=g1;
   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.
 
   In: sx[N], sy[N]: x- and y-coordinates of vertices of a polygon
   Out: (x, y): point within the polygon with maximal minimal distance to the sides

 
   delete[] A;
   return dm;
 }//maximalminimum
 
-/*
+/**
   function minimaxstiff: finds the point in polygon (N; F, G) that minimizes the maximal value of the
   function
 
         | m[l]sqrt(F+(m[l]^2-1)*G)-f[l] |
   e_l = | ----------------------------- | regarding l=0, ..., L-1

   delete[] vmnl;
 
   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
   encountered (non-positive frequencies are returned by note-match to indicate high partials for which
   no informative estimates can be obtained).

     HP[i].p=pfpp[i]; HP[i].type=ptype[i]; HP[i].pin=i+1;
   }
   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
       M: number of atoms to request from &results
       fr: frame index of this harmonic atom

     part->p=pfpp[i]; part->type=ptype[i]; part->pin=i+1;
   }
   return M;
 }//NMResultToPartials
 
-/*
+/**
   function NoteMatchStiff3: finds harmonic atom from spectrum if Fr=1, or constant-pitch harmonic
   sinusoid from spectrogram if Fr>1.
 
   In: x[Fr][N/2+1]: spectrogram
       fps[pc], vps[pc]: primitive (rough) peak frequencies and amplitudes

   delete[] psb;
 
   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
   and their frequency estimates are regarded unreliable.
 

   delete[] psb;
 
   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.
 
   In: x[Fr][N/2+1]: spectrogram
       N, offst: atom scale and hop size

   double result=NoteMatchStiff3(R, f0, B, pc, fps, vps, rsr, Fr, x, N, offst, settings, results, lastp, lastvfp, computes, forceinputlocalfr?startfr:-1);
   free8(fps);
   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().
 
   In: x[N/2+1]: spectrum
       fps[pc], vps[pc]: primitive (rough) peak frequencies and amplitudes

   double result=0;
   if (f0>0) for (int i=0; i<numsam; i++) result+=vfp[i]*vfp[i];
   return result;
 }//NoteMatchStiff3*/
 
-/*
+/**
   function NoteMatchStiff3FB: does one dynamic programming step in forward-background pitch tracking of
   harmonic sinusoids. This is used internally by FindNoteFB().
 
   In: R[pitchcount]: initial F-G polygons associated with pitch candidates at last frame
       vfp[pitchcount][maxp]: amplitude vectors associated with pitch candidates at last frame

   DeAlloc2(vfp); vfp=newvfp;
   delete[] sc; sc=newsc;
   pitchcount=newpc;
 }//NoteMatchStiff3FB
 
-/*
+/**
   function PeakShapeC: residue-sinusoid-ratio for a given (hypothesis) sinusoid frequency
 
   In: x[Fr][N/2+1]: spectrogram
       M, c[], iH2: cosine-family window specifiers
       f: reference frequency, in bins

   delete[] w;
   if (xx.x==0) return 1;
   return 1-xw2/(xx.x*ww.x);
 }//PeakShapeC
 
-/*
+/**
   function QuickPeaks: finds rough peaks in the spectrum (peak picking)
 
   In: x[N/2+1]: spectrum
       M, c[], iH2: cosine-family window function specifiers
       mina: minimal amplitude to spot a spectral peak

   }
   delete[] w;
   return p;
 }//QuickPeaks
 
-/*
+/**
   function QuickPeaks: finds rough peaks in the spectrogram (peak picking) for constant-frequency
   sinusoids
 
   In: x[Fr][N/2+1]: spectrogram
       fr0, r0: centre and half width of interval (in frames) to use for peak picking

   delete[] frc;
   DeAlloc2(frs);
   return pc;
 }//QuickPeaks
 
-/*
+/**
   function ReEstHS1: reestimates a harmonic sinusoid by one multiplicative reestimation using phasor
   multiplier
 
   In: partials[M][Fr]: HS partials
       [frst, fren): frame (measurement point) range on which to do reestimation

     for (int fr=0; fr<Fr; fr++) partials[m][fr].f=fs[fr], partials[m][fr].a=as[fr], partials[m][fr].p=phs[fr];
   }
   delete[] fs;
 }//ReEstHS1
 
-/*
+/**
   function ReEstHS1: wrapper function.
 
   In: HS: a harmonic sinusoid
       Data16: its waveform data
   Out: HS: updated harmonic sinusoid

 void ReEstHS1(THS* HS, __int16* Data16)
 {
   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.
 
   In: cand: the candid object to insert to the list
       cands[newN]: the sorted list of candid objects

   memmove(&cands[lnN+1], &cands[lnN], sizeof(candid)*(newN-lnN));
   cands[lnN]=cand;
   return lnN;
 }//SortCandid
 
-/*
+/**
   function SynthesisHS: synthesizes a harmonic sinusoid without aligning the phases
 
   In: partials[M][Fr]: HS partials
       terminatetag: external termination flag. Function SynthesisHS() polls *terminatetag and exits with
       0 when it is set.

   }
   free8(as);
   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.
 
   In: partials[M][Fr]: HS partials
       terminatetag: external termination flag. This function polls *terminatetag and exits with 0 when

   }
   free8(as); free8(ph); free8(a0[0]); delete[] a0;
   return xrec;
 }//SynthesisHS2
 
-/*
+/**
   function SynthesisHSp: synthesizes a harmonic sinusoid with phase alignment
 
   In: partials[pm][pfr]: HS partials
       startamp[pm][st_count]: onset amplifiers, optional
       st_start, st_offst: start of and interval between onset amplifying points, optional

 
   delete[] a1;
   return xrec;
 }//SynthesisHSp
 
-/*
+/**
   function SynthesisHSp: wrapper function.
 
   In: HS: a harmonic sinusoid.
   Out: [dst, den): time interval synthesized
        xrec[den-dst]: resynthesized harmonic sinusoid