Base class for Non-Stationary Gabor Filterbank Constant-Q Transform (NSGF-CQT) operations. More...

#include <CQT.hpp>

Inheritance diagram for jsa::cicuetea::NsgfCqtCommon:

Classes
struct	BandInfo
	Holds information about the number of bands in the filterbank. More...

Public Member Functions
	NsgfCqtCommon (double sampleRate, Eigen::Index numSamples, double fraction, double minFrequency, double maxFrequency, double refFrequency)
	Constructor for NsgfCqtCommon.
bool	isValid () const
	True when the object is usable: the configuration passed validate() and the constructed frame passed the measured health check (see checkFrameHealth()).
double	getFrameConditionNumber () const
	Condition number of the painless frame operator, max(d)/min(d) up to Nyquist. Advisory: reconstruction error amplifies by roughly cond·ε, so values ≲ 1e6 keep double-precision round trips near 1e-10. Returns +inf when the object is invalid.
double	getSampleRate () const
Eigen::Index	getBlockSize () const
	Synonym of getNumSamps().
Eigen::Index	getNumSamps () const
	Synonym of getBlockSize().
double	getFraction () const
double	getPpo () const
double	getMinFreq () const
double	getMaxFreq () const
double	getRefFreq () const
Eigen::Index	getNumFreqs () const
Eigen::Index	getNumBands () const
const Eigen::ArrayXd &	getFrequencyAxis () const
const Eigen::ArrayXd &	getBandAxis () const
const Eigen::ArrayXd &	getDiagonalization () const

Protected Member Functions
bool	checkFrameHealth () const
	Measured frame-health check on the constructed frame operator.

Static Protected Member Functions
static bool	validate (double fs, Eigen::Index nSamps, double frac, double fMin, double fMax, double fRef)
	Checks the structural validity conditions for a configuration.
static BandInfo	computeBandInfo (double frac, double fMin, double fMax, double fRef)
	Computes band information for the filterbank.

Protected Attributes
const bool	valid
	Structural validity: result of validate().
bool	frameOk = true
	Measured frame health; set by derived ctors.
const double	fs
	Sampling rate (Hz).
const Eigen::Index	nSamps
	Number of samples in a block (0 when invalid).
const double	frac
	Reciprocal of bands per octave.
const double	fMin
	Minimum frequency (Hz).
const double	fMax
	Maximum frequency (Hz).
const double	fRef
	Reference frequency (Hz).
const BandInfo	bandInfo
	Band information.
const Eigen::Index	nBands
	Total number of bands.
const Eigen::Index	nFreqs
	Number of frequencies.
Eigen::ArrayXd	bax
	Band axis.
Eigen::ArrayXd	fax
	Frequency axis.
Eigen::ArrayXd	d
	Diagonalization array.
Eigen::ArrayXcd	Xdft
	DFT of the signal.
DFT	dft
	Discrete Fourier Transform object.

Static Protected Attributes
static constexpr double	dHealthTol = 1e-6
static constexpr double	th = 1e-6
static constexpr Eigen::Index	minAtomSupport = 4

Detailed Description

Base class for Non-Stationary Gabor Filterbank Constant-Q Transform (NSGF-CQT) operations.

This class provides common functionality and data members for NSGF-CQT operations, including frequency axis computation, band information, and diagonalization.

Construction never throws and never crashes: a configuration that fails validate() produces an inert object — isValid() returns false, the processing methods output silence, and accessors return empty data. This supports host lifecycles (e.g. DAWs) that construct with a placeholder sample rate before the real one is known; since the whole design depends on the sample rate, the correct response to a new rate is constructing a new object.

Constructor & Destructor Documentation

◆ NsgfCqtCommon()

NsgfCqtCommon::NsgfCqtCommon	(	double	sampleRate,
		Eigen::Index	numSamples,
		double	fraction,
		double	minFrequency,
		double	maxFrequency,
		double	refFrequency )

Constructor for NsgfCqtCommon.

Parameters

sampleRate	Sampling rate of the signal (Hz).
numSamples	Number of samples in a block.
fraction	Reciprocal of bands per octave (e.g. 1.0/12 for 12 bands/octave); fractional values allowed.
minFrequency	Minimum frequency of the filterbank (Hz).
maxFrequency	Maximum frequency of the filterbank (Hz).
refFrequency	Reference frequency for the filterbank (Hz).

Member Function Documentation

◆ checkFrameHealth()

bool NsgfCqtCommon::checkFrameHealth ( ) const

protected

Measured frame-health check on the constructed frame operator.

The painless frame operator is diagonal with entries d(f); the transform is invertible iff min(d) > 0 on the covered range, and numerically trustworthy iff the condition number max(d)/min(d) is moderate. Requiring min(d) > dHealthTol·max(d) bounds the condition number by 1/dHealthTol. Called by the derived constructors once d is available; every "Q too high for this block" failure mode lands here, whatever combination of parameters caused it.

◆ computeBandInfo()

NsgfCqtCommon::BandInfo NsgfCqtCommon::computeBandInfo	(	double	frac,
		double	fMin,
		double	fMax,
		double	fRef )

staticprotected

Computes band information for the filterbank.

Parameters

frac	Reciprocal of bands per octave.
fMin	Minimum frequency of the filterbank (Hz).
fMax	Maximum frequency of the filterbank (Hz).
fRef	Reference frequency for the filterbank (Hz).

Returns: BandInfo Struct containing band information.

◆ isValid()

bool jsa::cicuetea::NsgfCqtCommon::isValid ( ) const

inline

True when the object is usable: the configuration passed validate() and the constructed frame passed the measured health check (see checkFrameHealth()).

Two tiers on purpose: parameter rules catch the provable absurdities, but the fuzzy boundary — a convergence of factors with no closed-form criterion — is decided by inspecting the frame that was actually built, not by predicting from parameters. Two measured modes: coverage gaps (bins no atom reaches: frame-operator condition number, checkFrameHealth()) and unresolved atoms (bands too narrow for the grid: per-atom support ≥ minAtomSupport).

An invalid object is inert: forward()/inverse() write zeros to their outputs and return, and accessors return empty or unusable data. Parameter getters (getSampleRate() etc.) still report what was passed.

◆ validate()

bool NsgfCqtCommon::validate	(	double	fs,
		Eigen::Index	nSamps,
		double	frac,
		double	fMin,
		double	fMax,
		double	fRef )

staticprotected

Checks the structural validity conditions for a configuration.

Deliberately limited to conditions under which the transform is provably meaningless: positive sample rate, power-of-two block size (a structural assumption of the per-band span logic, see NsgfCqtSparse::getIdx — independent of what a backend could handle), positive fraction and reference frequency, 0 < fMin < fMax, and fMax strictly below Nyquist. Nothing about the extent of the range is gated (sub-octave ranges are legitimate): feasibility is measured on the constructed frame instead (checkFrameHealth(), atom support).

Member Data Documentation

◆ dHealthTol

double jsa::cicuetea::NsgfCqtCommon::dHealthTol = 1e-6

staticconstexprprotected

Relative floor for the frame-operator diagonal: bounds the frame condition number by 1e6, keeping double-precision round trips ~1e-10.

◆ minAtomSupport

Eigen::Index jsa::cicuetea::NsgfCqtCommon::minAtomSupport = 4

staticconstexprprotected

Minimum number of bins above th an atom must occupy to count as resolved by the frequency grid. The fuzzy "Q too big for the block" failure mode is invisible in d — with many bands per octave every bin is still covered — so it is caught from the atom side instead: unresolved atoms are the measured, warp-agnostic equivalent of the parametric Q check. 4 matches the smallest FFT span getIdx will build (and min_bw in the Python reference).

◆ th

double jsa::cicuetea::NsgfCqtCommon::th = 1e-6

staticconstexprprotected

Atom magnitude threshold: below it a bin does not count as support (and, in the sparse variant, is zeroed for efficiency).

The documentation for this class was generated from the following files:

/home/runner/work/CiCueTea/CiCueTea/Include/CQT.hpp
/home/runner/work/CiCueTea/CiCueTea/Source/CQT.cpp

Classes

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ NsgfCqtCommon()

Member Function Documentation

◆ checkFrameHealth()

◆ computeBandInfo()

◆ isValid()

◆ validate()

Member Data Documentation

◆ dHealthTol

◆ minAtomSupport

◆ th