Improve PitchDetection example and documentation

examples/Analysis/PitchDetection/PitchDetection.pde

@@ -1,9 +1,8 @@
 /**
  * This sketch shows how to use the PitchDetector class to detect the pitch 
  * (also known as the 'fundamental frequency') of a sound signal. For complex 
- * signals this is not a trivial task, so the analyzer only returns a frequency 
- * (measured in Hertz, or 'Hz') when its measurement exceeds a 'confidence level'
- * that can be specified by the user.
+ * signals this is not a trivial task, so the analyzer not only returns the pitch 
+ * (measured in Hertz, or 'Hz') but also a 'confidence level' in that measurement.
  */
 
 import processing.sound.*;
@@ -26,17 +25,18 @@ void draw() {
   fill(color(0));
   rect(i, 0, 1, height);
 
-  // require a minimum confidence level based on current mouse position
-  float confidence = map(mouseY, 0, height, 1.0, 0.0);
-  float frequency = pitchDetector.analyze(confidence);
-
-  // did we get a reading that had the required confidence level?
-  if (frequency != 0.0) {
-    // map the range of the human voice (40 - 1000Hz) to the height of the 
-    // sketch, and color the dot according to confidence that was required
-    // for this measurement
-    fill(lerpColor(color(255, 0, 0), color(0, 255, 0), confidence));
-    circle(i, int(map(frequency, 1000, 40, 0, height)), 4);
+  // the array version of analyze() returns the detected pitch as well
+  // as the confidence level in the correctness of that pitch
+  float[] pitchAndConfidence = new float[2];
+  pitchDetector.analyze(pitchAndConfidence);
+
+  // don't draw measurements when there is absolutely 0 confidence in them
+  if (pitchAndConfidence[1] > 0) {
+    // draw all others: map the range of a human whistle (~40 - 2000Hz) to the height
+    // of the sketch, and color the dot according to the confidence in this measurement
+    fill(lerpColor(color(255, 0, 0), color(0, 255, 0), pitchAndConfidence[1]));
+
+    circle(i, int(map(pitchAndConfidence[0], 2000, 40, 0, height)), 2);
   }
 
   i = (i+1) % width;

src/processing/sound/PitchDetector.java

@@ -16,22 +16,23 @@
 public class PitchDetector extends Analyzer {
   private final com.jsyn.unitgen.PitchDetector detector;
 
-  private float minimumConfidence = 0.8f;
+  private float minimumConfidence;
 
   /**
    * @param parent typically "this"
    * @param minimumConfidence the minimum confidence level required for 
-   * frequency measurements, between 0 (accept all measurements, no matter how 
-   * unreliable) to 1 (only accept perfect measurements). Defaults to 0.8.
+   * frequency measurements, between <code>0.0</code> (accept all measurements, 
+   * no matter how unreliable) to <code>1.0</code> (only accept perfect 
+   * measurements). Defaults to 0.8.
    */
   public PitchDetector(PApplet parent, float minimumConfidence) {
-    this(parent);
+    super(parent);
+    this.detector = new com.jsyn.unitgen.PitchDetector();
     this.minimumConfidence = minimumConfidence;
   }
 
   public PitchDetector(PApplet parent) {
-    super(parent);
-    this.detector = new com.jsyn.unitgen.PitchDetector();
+    this(parent, 0.8f);
   }
 
   @Override
@@ -53,7 +54,8 @@ public float analyze() {
   /**
    * Returns an estimate of the current pitch (or 'fundamental frequency') of 
    * the input sound signal, in Hertz. If the confidence in the current 
-   * measurement does not exceed the minimum confidence, this method returns 0.
+   * measurement does not exceed the minimum confidence, this method returns 
+   * <code>0.0</code>.
    * @webref Analysis:PitchDetector
    * @webBrief Detect the fundamental frequency of the input sound signal.
    * @param minimumConfidence the minimum confidence level required for 
@@ -70,6 +72,6 @@ public float analyze(float minimumConfidence) {
   public float analyze(float[] target) {
     target[0] = (float) this.detector.frequency.getValue();
     target[1] = (float) this.detector.confidence.getValue();
-    return target[0];
+    return (target[1] >= this.minimumConfidence ? target[0] : 0.0f);
   }
 }