Refactoring spectra adding decibel, gain and factor classes and making...

Refactoring spectra adding decibel, gain and factor classes and making spectrum and third octate spectrum partly abstract.

CMakeLists.txt

@@ -60,7 +60,6 @@ include_directories( "include" )
 # files
 set( ITABaseHeader
 	"include/ITAASCIITable.h"
-	"include/ITAAmplitudeSpectrum.h"
 	"include/ITAAudioSample.h"
 	"include/ITABaseDefinitions.h"
 	"include/ITABlockMath.h"
@@ -100,7 +99,6 @@ set( ITABaseHeader
 	)
 set( ITABaseSources
 	"src/ITAASCIITable.cpp"
-	"src/ITAAmplitudeSpectrum.cpp"
 	"src/ITABlockMath.cpp"
 	"src/ITABufferedAudioFileWriter.cpp"
 	"src/ITAClock.cpp"

include/ITAAmplitudeSpectrum.h

-/*
- * ----------------------------------------------------------------
- *
- *		ITA core libs
- *		(c) Copyright Institute of Technical Acoustics (ITA)
- *		RWTH Aachen University, Germany, 2015-2017
- *
- * ----------------------------------------------------------------
- *				    ____  __________  _______
- *				   //  / //__   ___/ //  _   |
- *				  //  /    //  /    //  /_|  |
- *				 //  /    //  /    //  ___   |
- *				//__/    //__/    //__/   |__|
- *
- * ----------------------------------------------------------------
- *
- */
-
-#ifndef INCLUDE_WATCHER_ITA_AMPLITUDE_SPECTRUM
-#define INCLUDE_WATCHER_ITA_AMPLITUDE_SPECTRUM
-
-#include <ITABaseDefinitions.h>
-#include <ITASpectrum.h>
-
-
-//! Amplitude spectrum of arbitrary size and base frequencies
-/**
-  * Class for amplitude spectra, that is intended to be used with linear values (gains).
-  *
-  * Will raise CITAException on errors.
-  *
-  * @sa CITAMAgnitudeSpectrum, CITAPhaseSpectrum, CITAHDFTSpectrum
-  *
-  */
-class ITA_BASE_API CITAAmplitudeSpectrum : public CITASpectrum
-{
-public:
-	CITAAmplitudeSpectrum( const int nNumBands );
-	virtual inline ~CITAAmplitudeSpectrum() {};
-	
-	std::vector< float > GetAmplitudesCopy() const;
-	const std::vector< float >& GetAmplitudes() const;
-
-	void SetAmplitudes( const std::vector< float >& vfAmplitudes );
-	void SetAmplitude( const int iFrequencyBandIndex, const float fAmplitudeValue );
-
-	void SetIdentity();
-	void SetZero();
-	bool IsIdentity() const;
-	bool IsZero() const;
-		
-	bool CompareEqualValues( const CITAAmplitudeSpectrum& oOtherSpectrum, const float fThreshold = 10.0e-10 ) const;
-};
-
-#endif // INCLUDE_WATCHER_ITA_AMPLITUDE_SPECTRUM

include/ITAMagnitudeSpectrum.h

@@ -22,14 +22,27 @@
 #include <ITABaseDefinitions.h>
 #include <ITASpectrum.h>
 
+// Forward for aliasing classes
+class CITAGainMagnitudeSpectrum;
+
+//! A factor magnitude spectrum with linear values that are greater zero and usually between 0..1, but can also exceed.
+/**
+  * This alias class is used to give the user a hint that the underlying data should be treated as linear values (factors)
+  * or gains, because a magnitude spectrum does not specify on that. It is used like a CITAMagnitudeSpectrum.
+  * There is no real difference between a factor and a gain except that gains are commonly used in DSP (i.e. for "gain" control
+  * of audio signal channels) and factors are more common in acoustic materials such as absorption and transmission "factor".
+  */
+typedef CITAGainMagnitudeSpectrum CITAFactorMagnitudeSpectrum;
 
 //! Magnitude spectrum of arbitrary size and base frequencies
 /**
-  * Class for magnitude spectra, that is intended to be used with decibel values (magnitudes).
+  * Implementation class for magnitude spectra, that does not specify on underlying data. To be more precise in your code and
+  * for validation of data it is recommended to use the alias classes CITADecibelMagnitudeSpectrum, CITAGainMagnitudeSpectrum or CITAFactorMagnitudeSpectrum,
+  * which implement the abstract methods and are ready to use.
   *
   * Will raise CITAException on errors.
   *
-  * @sa CITAAmplitudeSpectrum, CITAPhaseSpectrum, CITAHDFTSpectrum
+  * @sa CITAThirdOctaveSpectrum, CITAPhaseSpectrum, CITAHDFTSpectrum
   *
   */
 class ITA_BASE_API CITAMagnitudeSpectrum : public CITASpectrum
@@ -43,13 +56,42 @@ public:
 
 	void SetMagnitudes( const std::vector< float >& vfMagnitudes );
 	void SetMagnitude( const int iFrequencyBandIndex, const float fMagnitudeValue );
+			
+	bool CompareEqualValues( const CITAMagnitudeSpectrum& oOtherSpectrum, const float fThreshold = 10.0e-10 ) const;
+};
+
+
+//! A decibel magnitude spectrum with values that have been transformed into logarithmic scale. Values are mostly between -\infinity and 0, but can also exceed.
+/**
+* This alias class is used to give the user a hint that the underlying data should be treated as decibel values (log scale),
+* because a magnitude spectrum does not specify on that. It is used like a CITAMagnitudeSpectrum.
+*/
+class ITA_BASE_API CITADecibelMagnitudeSpectrum : public CITAMagnitudeSpectrum
+{
+public:
+	CITADecibelMagnitudeSpectrum( const int nNumBands );
+	virtual ~CITADecibelMagnitudeSpectrum();
+
+	void SetIdentity();
+	void SetZero();
+	bool IsIdentity() const;
+	bool IsZero() const;
+};
+
+//! A gain magnitude spectrum with linear values that are greater zero and usually between 0..1, but can also exceed.
+/**
+  * @sa CITAFactorMagnitudeSpectrum
+  */
+class ITA_BASE_API CITAGainMagnitudeSpectrum : public CITAMagnitudeSpectrum
+{
+public:
+	CITAGainMagnitudeSpectrum( const int nNumBands );
+	virtual ~CITAGainMagnitudeSpectrum();
 
 	void SetIdentity();
 	void SetZero();
 	bool IsIdentity() const;
 	bool IsZero() const;
-		
-	bool CompareEqualValues( const CITAMagnitudeSpectrum& oOtherSpectrum, const float fThreshold = 10.0e-10 ) const;
 };
 
 #endif // INCLUDE_WATCHER_ITA_MAGNITUDE_SPECTRUM

include/ITASpectrum.h

@@ -45,7 +45,7 @@ public:
 	std::string GetName() const;
 
 	std::string GetValueUnit() const;
-	void SetValueUnit( std::string sUnit );
+	void SetValueUnit( const std::string& sUnit );
 
 	int GetNumBands() const;
 

include/ITAThirdOctaveMagnitudeSpectrum.h

@@ -22,6 +22,8 @@
 #include <ITABaseDefinitions.h>
 #include <ITAMagnitudeSpectrum.h>
 
+#include <numeric>
+#include <limits>
 
 //! Third octave magnitude spectrum
 /**
@@ -66,4 +68,105 @@ protected:
 	void SetCenterFrequencies( const std::vector<float>& vfCenterFrequencies );
 };
 
+//! Implementation of magnitude spectrum for gain values
+class CITAThirdOctaveGainMagnitudeSpectrum : public CITAThirdOctaveMagnitudeSpectrum
+{
+public:
+	inline CITAThirdOctaveGainMagnitudeSpectrum()
+		: CITAThirdOctaveMagnitudeSpectrum()
+	{
+
+	};
+
+	virtual ~CITAThirdOctaveGainMagnitudeSpectrum() {};
+
+	inline void SetIdentity()
+	{
+		for( size_t n = 0; n < m_vfValues.size(); n++ )
+			m_vfValues[ n ] = 1.0f;
+	};
+
+	inline void SetZero()
+	{
+		for( size_t n = 0; n < m_vfValues.size(); n++ )
+			m_vfValues[ n ] = 0.0f;
+	};
+
+	inline bool IsIdentity() const
+	{
+		for( size_t n = 0; n < m_vfValues.size(); n++ )
+		{
+			if( m_vfValues[ n ] != 1.0f )
+				return false;
+		}
+	};
+
+	inline bool IsZero() const
+	{
+		for( size_t n = 0; n < m_vfValues.size(); n++ )
+		{
+			if( m_vfValues[ n ] != 0.0f )
+				return false;
+		}
+	};
+};
+
+
+//! A factor magnitude spectrum with linear values that are greater zero and usually between 0..1, but can also exceed.
+/**
+* This alias class is used to give the user a hint that the underlying data should be treated as linear values (factors)
+* or gains, because a magnitude spectrum does not specify on that. It is used like a CITAThirdOctaveMagnitudeSpectrum.
+* There is no real difference between a factor and a gain except that gains are commonly used in DSP (i.e. for "gain" control
+* of audio signal channels) and factors are more common in acoustic materials such as absorption and transmission "factor".
+*/
+typedef CITAThirdOctaveGainMagnitudeSpectrum CITAThirdOctaveFactorMagnitudeSpectrum;
+
+//! A decibel magnitude spectrum with values that have been transformed into logarithmic scale. Values are mostly between -\infinity and 0, but can also exceed.
+
+
+//! Implementation of magnitude spectrum for gain values
+class CITAThirdOctaveDecibelMagnitudeSpectrum : public CITAThirdOctaveMagnitudeSpectrum
+{
+public:
+	inline CITAThirdOctaveDecibelMagnitudeSpectrum()
+		: CITAThirdOctaveDecibelMagnitudeSpectrum()
+	{
+
+	};
+
+	virtual ~CITAThirdOctaveDecibelMagnitudeSpectrum() {};
+
+	inline void SetIdentity()
+	{
+		for( size_t n = 0; n < m_vfValues.size(); n++ )
+			m_vfValues[ n ] = 0.0f;
+	};
+
+	inline void SetZero()
+	{
+		for( size_t n = 0; n < m_vfValues.size(); n++ )
+			m_vfValues[ n ] = -std::numeric_limits< float >::infinity();
+	};
+
+	inline bool IsIdentity() const
+	{
+		for( size_t n = 0; n < m_vfValues.size(); n++ )
+		{
+			if( m_vfValues[ n ] != 0.0f )
+				return false;
+		}
+	};
+
+	inline bool IsZero() const
+	{
+		for( size_t n = 0; n < m_vfValues.size(); n++ )
+		{
+			if( m_vfValues[ n ] != -std::numeric_limits< float >::infinity() )
+				return false;
+		}
+	};
+};
+
+
+
 #endif // INCLUDE_WATCHER_ITA_THIRD_OCTAVE_MAGNITUDE_SPECTRUM

src/ITAAmplitudeSpectrum.cpp

-#include <ITAAmplitudeSpectrum.h>
-#include <ITAConstants.h>
-
-#include <numeric>
-
-CITAAmplitudeSpectrum::CITAAmplitudeSpectrum( const int nNumBands )
-	: CITASpectrum( nNumBands )
-{
-	SetValueUnit( "factor" );
-}
-
-std::vector< float > CITAAmplitudeSpectrum::GetAmplitudesCopy() const
-{
-	return CITASpectrum::GetValuesCopy();
-}
-
-const std::vector< float >& CITAAmplitudeSpectrum::GetAmplitudes() const
-{
-	return CITASpectrum::GetValues();
-}
-
-void CITAAmplitudeSpectrum::SetAmplitudes( const std::vector< float >& vfAmplitudes )
-{
-	CITASpectrum::SetValues( vfAmplitudes );
-}
-
-void CITAAmplitudeSpectrum::SetAmplitude( const int iFrequencyBandIndex, const float fAmplitudeValue )
-{
-	CITASpectrum::SetValue( iFrequencyBandIndex, fAmplitudeValue );
-}
-
-void CITAAmplitudeSpectrum::SetIdentity()
-{
-	std::fill( m_vfValues.begin(), m_vfValues.end(), 1.0f );
-}
-
-void CITAAmplitudeSpectrum::SetZero()
-{
-	std::fill( m_vfValues.begin(), m_vfValues.end(), 0.0f );
-}
-
-bool CITAAmplitudeSpectrum::IsIdentity() const
-{
-	for( size_t n = 0; n < m_vfValues.size(); n++ )
-	{
-		if( m_vfValues[ n ] != 1.0f )
-			return false;
-	}
-
-	return true;
-}
-
-bool CITAAmplitudeSpectrum::IsZero() const
-{
-	for( size_t n = 0; n < m_vfValues.size(); n++ )
-	{
-		if( m_vfValues[ n ] != 0.0f )
-			return false;
-	}
-
-	return true;
-}

src/ITAMagnitudeSpectrum.cpp

@@ -7,7 +7,6 @@
 CITAMagnitudeSpectrum::CITAMagnitudeSpectrum( const int nNumBands )
 	: CITASpectrum( nNumBands )
 {
-	SetValueUnit( "dB" );
 }
 
 std::vector< float > CITAMagnitudeSpectrum::GetMagnitudesCopy() const
@@ -30,17 +29,32 @@ void CITAMagnitudeSpectrum::SetMagnitude( const int iFrequencyBandIndex, const f
 	CITASpectrum::SetValue( iFrequencyBandIndex, fMagnitudeValue );
 }
 
-void CITAMagnitudeSpectrum::SetIdentity()
+// ----- ----------- -------------------
+
+CITADecibelMagnitudeSpectrum::CITADecibelMagnitudeSpectrum( const int iNumBands )
+	: CITAMagnitudeSpectrum( iNumBands )
+{
+	CITASpectrum::SetValueUnit( "dB" );
+}
+
+CITADecibelMagnitudeSpectrum::~CITADecibelMagnitudeSpectrum()
+{
+
+}
+
+void CITADecibelMagnitudeSpectrum::SetIdentity()
 {
-	std::fill( m_vfValues.begin(), m_vfValues.end(), 0.0f );
+	for( size_t n = 0; n < m_vfValues.size(); n++ )
+		m_vfValues[ n ] = 0;
 }
 
-void CITAMagnitudeSpectrum::SetZero()
+void CITADecibelMagnitudeSpectrum::SetZero()
 {
-	std::fill( m_vfValues.begin(), m_vfValues.end(), -std::numeric_limits< float >::infinity() );
+	for( size_t n = 0; n < m_vfValues.size(); n++ )
+		m_vfValues[ n ] = -std::numeric_limits< float >::infinity();
 }
 
-bool CITAMagnitudeSpectrum::IsIdentity() const
+bool CITADecibelMagnitudeSpectrum::IsIdentity() const
 {
 	for( size_t n = 0; n < m_vfValues.size(); n++ )
 	{
@@ -51,7 +65,7 @@ bool CITAMagnitudeSpectrum::IsIdentity() const
 	return true;
 }
 
-bool CITAMagnitudeSpectrum::IsZero() const
+bool CITADecibelMagnitudeSpectrum::IsZero() const
 {
 	for( size_t n = 0; n < m_vfValues.size(); n++ )
 	{
@@ -61,3 +75,50 @@ bool CITAMagnitudeSpectrum::IsZero() const
 
 	return true;
 }
+
+// ----- ----------- -------------------
+
+CITAGainMagnitudeSpectrum::CITAGainMagnitudeSpectrum( const int iNumBands )
+	: CITAMagnitudeSpectrum( iNumBands )
+{
+	CITASpectrum::SetValueUnit( "gain" );
+}
+
+CITAGainMagnitudeSpectrum::~CITAGainMagnitudeSpectrum()
+{
+
+}
+
+void CITAGainMagnitudeSpectrum::SetIdentity()
+{
+	for( size_t n = 0; n < m_vfValues.size(); n++ )
+		m_vfValues[ n ] = 1.0f;
+}
+
+void CITAGainMagnitudeSpectrum::SetZero()
+{
+	for( size_t n = 0; n < m_vfValues.size(); n++ )
+		m_vfValues[ n ] = 0.0f;
+}
+
+bool CITAGainMagnitudeSpectrum::IsIdentity() const
+{
+	for( size_t n = 0; n < m_vfValues.size(); n++ )
+	{
+		if( m_vfValues[ n ] != 1.0f )
+			return false;
+	}
+
+	return true;
+}
+
+bool CITAGainMagnitudeSpectrum::IsZero() const
+{
+	for( size_t n = 0; n < m_vfValues.size(); n++ )
+	{
+		if( m_vfValues[ n ] != 0.0f )
+			return false;
+	}
+
+	return true;
+}

src/ITASpectrum.cpp

@@ -21,7 +21,7 @@ std::string CITASpectrum::GetName() const
 	return m_sName;
 }
 
-void CITASpectrum::SetValueUnit( std::string sUnit )
+void CITASpectrum::SetValueUnit( const std::string& sUnit )
 {
 	m_sValueUnit = sUnit;
 }

tests/ITABaseSpectrumTests.cpp

@@ -27,7 +27,7 @@ int main( int, char** )
 
 void test_db_to_ration()
 {
-	CITAThirdOctaveMagnitudeSpectrum oTOSpectrumConvertToRatio;
+	CITAThirdOctaveDecibelMagnitudeSpectrum oTOSpectrumConvertToRatio;
 	oTOSpectrumConvertToRatio.SetName( "Test unit magnitude spectrum to ratio" );
 
 	oTOSpectrumConvertToRatio.SetIdentity();
@@ -47,7 +47,7 @@ void test_db_to_ration()
 
 void test_ratio_to_db()
 {
-	CITAThirdOctaveMagnitudeSpectrum oTOSpectrumConvertToRatio;
+	CITAThirdOctaveFactorMagnitudeSpectrum oTOSpectrumConvertToRatio;
 	oTOSpectrumConvertToRatio.SetName( "Test unit gain spectrum to db" );
 	oTOSpectrumConvertToRatio.SetValueUnit( "(gain)" );
 	oTOSpectrumConvertToRatio.SetIdentity(); // db -> all zeros
@@ -72,14 +72,14 @@ void test_ratio_to_db()
 
 void test_third_octave_spectrum()
 {
-	CITAThirdOctaveMagnitudeSpectrum oTOSpectrumIdent;
+	CITAThirdOctaveGainMagnitudeSpectrum oTOSpectrumIdent;
 	oTOSpectrumIdent.SetName( "Test unit magnitude spectrum" );
 	oTOSpectrumIdent.SetIdentity();
 
 	cout << "Third octave magnitude spectrum identity:" << endl;
 	cout << oTOSpectrumIdent << endl;
 	
-	CITAThirdOctaveMagnitudeSpectrum oTOSpectrumZero;
+	CITAThirdOctaveGainMagnitudeSpectrum oTOSpectrumZero;
 	oTOSpectrumZero.SetName( "Test unit zero spectrum" );
 	oTOSpectrumZero.SetZero();