# HG changeset patch
# User Chris Cannam
# Date 1466689380 -3600
# Node ID f6998e304b36ac375bd67ebfdafa5dc271304e9f
# Parent  63b73a21bccd063cf3344143123c022940271f81
Comments and naming

diff -r 63b73a21bccd -r f6998e304b36 base/ColumnOp.h
--- a/base/ColumnOp.h	Thu Jun 23 08:45:52 2016 +0100
+++ b/base/ColumnOp.h	Thu Jun 23 14:43:00 2016 +0100
@@ -20,11 +20,30 @@
 
 #include <cmath>
 
+/**
+ * Class containing static functions for simple operations on data
+ * columns, for use by display layers.
+ */
 class ColumnOp
 {
 public:
+    /** 
+     * Column type. 
+     */
     typedef std::vector<float> Column;
 
+    /**
+     * Normalization types.
+     *
+     * NormalizeColumns means to normalize to max value = 1.
+     * NormalizeHybrid means normalize to max = 1 and then multiply by
+     * log10 of the max value, to retain some difference between
+     * levels of neighbouring columns.
+     *
+     * NormalizeVisibleArea is ignored here and is included only so as
+     * to match the set of normalization options historically provided
+     * in the SV spectrogram layer.
+     */
     enum Normalization {
         NoNormalization,
         NormalizeColumns,
@@ -32,6 +51,9 @@
         NormalizeHybrid
     };
 
+    /**
+     * Scale an FFT output by half the FFT size.
+     */
     static Column fftScale(const Column &in, int fftSize) {
 	
 	Column out;
@@ -44,6 +66,9 @@
 	return out;
     }
 
+    /**
+     * Determine whether an index points to a local peak.
+     */
     static bool isPeak(const Column &in, int ix) {
 	
 	if (!in_range_for(in, ix-1)) return false;
@@ -54,6 +79,10 @@
 	return true;
     }
 
+    /**
+     * Return a column containing only the local peak values (all
+     * others zero).
+     */
     static Column peakPick(const Column &in) {
 	
 	std::vector<float> out(in.size(), 0.f);
@@ -66,6 +95,10 @@
 	return out;
     }
 
+    /**
+     * Return a column normalized from the input column according to
+     * the given normalization scheme.
+     */
     static Column normalize(const Column &in, Normalization n) {
 
 	if (n == NoNormalization || n == NormalizeVisibleArea) {
@@ -98,6 +131,9 @@
 	return out;
     }
 
+    /**
+     * Scale the given column using the given gain multiplier.
+     */
     static Column applyGain(const Column &in, float gain) {
 	
 	if (gain == 1.f) {
@@ -111,6 +147,12 @@
 	return out;
     }
 
+    /**
+     * Distribute the given column into a target vector of a different
+     * size, optionally using linear interpolation. The binfory vector
+     * contains a mapping from y coordinate (i.e. index into the
+     * target vector) to bin (i.e. index into the source column).
+     */
     static Column distribute(const Column &in,
 			     int h,
 			     const std::vector<double> &binfory,
diff -r 63b73a21bccd -r f6998e304b36 data/model/Dense3DModelPeakCache.cpp
--- a/data/model/Dense3DModelPeakCache.cpp	Thu Jun 23 08:45:52 2016 +0100
+++ b/data/model/Dense3DModelPeakCache.cpp	Thu Jun 23 14:43:00 2016 +0100
@@ -20,7 +20,7 @@
 Dense3DModelPeakCache::Dense3DModelPeakCache(DenseThreeDimensionalModel *source,
 					     int columnsPerPeak) :
     m_source(source),
-    m_resolution(columnsPerPeak)
+    m_columnsPerPeak(columnsPerPeak)
 {
     m_cache = new EditableDenseThreeDimensionalModel
         (source->getSampleRate(),
@@ -95,8 +95,8 @@
 
     Column peak;
     int n = 0;
-    for (int i = 0; i < m_resolution; ++i) {
-        Column here = m_source->getColumn(column * m_resolution + i);
+    for (int i = 0; i < m_columnsPerPeak; ++i) {
+        Column here = m_source->getColumn(column * m_columnsPerPeak + i);
         if (i == 0) {
             peak = here;
             n = int(peak.size());
diff -r 63b73a21bccd -r f6998e304b36 data/model/Dense3DModelPeakCache.h
--- a/data/model/Dense3DModelPeakCache.h	Thu Jun 23 08:45:52 2016 +0100
+++ b/data/model/Dense3DModelPeakCache.h	Thu Jun 23 14:43:00 2016 +0100
@@ -45,11 +45,15 @@
     }
 
     virtual int getResolution() const {
-        return m_source->getResolution() * m_resolution;
+        return m_source->getResolution() * m_columnsPerPeak;
     }
 
+    virtual int getColumnsPerPeak() const {
+        return m_columnsPerPeak;
+    }
+    
     virtual int getWidth() const {
-        return m_source->getWidth() / m_resolution + 1;
+        return m_source->getWidth() / m_columnsPerPeak + 1;
     }
 
     virtual int getHeight() const {
@@ -91,7 +95,7 @@
     mutable EditableDenseThreeDimensionalModel *m_cache;
     mutable std::vector<bool> m_coverage; // must be bool, for space efficiency
                                           // (vector of bool uses 1-bit elements)
-    int m_resolution;
+    int m_columnsPerPeak;
 
     bool haveColumn(int column) const;
     void fillColumn(int column) const;