init

enriched-qwen3-coder-next/Common/DTS.Common/Enums/DTS.Viewer/Reports/PowerSpectralDensity.md

@@ -0,0 +1,89 @@
+---
+source_files:
+  - Common/DTS.Common/Enums/DTS.Viewer/Reports/PowerSpectralDensity/WindowAveragingType.cs
+  - Common/DTS.Common/Enums/DTS.Viewer/Reports/PowerSpectralDensity/PassFilterType.cs
+  - Common/DTS.Common/Enums/DTS.Viewer/Reports/PowerSpectralDensity/WindowWidth.cs
+  - Common/DTS.Common/Enums/DTS.Viewer/Reports/PowerSpectralDensity/WindowType.cs
+generated_at: "2026-04-16T03:21:08.807677+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "e228857d6b62ca1f"
+---
+
+# PowerSpectralDensity
+
+## Documentation: Power Spectral Density Configuration Enums
+
+---
+
+### 1. Purpose  
+This module defines a set of strongly-typed enumerations used to configure parameters for Power Spectral Density (PSD) analysis in the DTS Viewer reporting system. These enums (`WindowAveragingType`, `PassFilterType`, `WindowWidth`, and `WindowType`) provide a standardized, validated set of options for controlling how spectral data is computed and displayed—specifically for windowing, filtering, and averaging strategies—ensuring consistency across UI, serialization, and backend processing layers.
+
+---
+
+### 2. Public Interface  
+
+All types are `public enum`s in the `DTS.Common.Enums.Viewer.Reports` namespace. Each enum value is annotated with a `[Description]` attribute (from `System.ComponentModel`) and uses the `EnumDescriptionTypeConverter` for UI/data binding scenarios.
+
+#### `WindowAveragingType`
+- **Values**:
+  - `Averaging` → Description: `"Averaging"`
+  - `PeakHoldMax` → Description: `"Peak Hold MAX"`
+  - `PeakHoldMin` → Description: `"Peak Hold MIN"`
+- **Purpose**: Specifies the method used to average spectral frames over time (e.g., for smoothing or peak tracking).
+
+#### `PassFilterType`
+- **Values**:
+  - `Bessel` → Description: `"Bessel"`
+  - `Butterworth` → Description: `"Butterworth"`
+  - `Chebyshev` → Description: `"Chebyshev"`
+- **Purpose**: Defines the digital filter type applied during signal preprocessing before FFT computation.  
+  *Note*: `CriticalDamping` is commented out and not available.
+
+#### `WindowWidth`
+- **Values** (with explicit integer values):
+  - `FiveTwelve` = 512 → Description: `"512"`
+  - `TenTwentyFour` = 1024 → Description: `"1024"`
+  - `TwentyFortyEight` = 2048 → Description: `"2048"`
+  - `FortyNinetySix` = 4096 → Description: `"4096"`
+  - `EightyOneNinetyTwo` = 8192 → Description: `"8192"`
+- **Purpose**: Specifies the FFT window size (in samples) used in PSD computation.
+
+#### `WindowType`
+- **Values**:
+  - `Rectangle` → Description: `"Rectangle"`
+  - `Hamming` → Description: `"Hamming"`
+  - `Hanning` → Description: `"Hanning"`
+  - `Blackman` → Description: `"Blackman"`
+  - `BlackmanHarris` → Description: `"Blackman-Harris"`
+  - `FlatTop` → Description: `"Flat Top"`
+- **Purpose**: Selects the time-domain window function applied to the signal prior to FFT to mitigate spectral leakage.
+
+---
+
+### 3. Invariants  
+- All enum values are **exhaustively documented** via `[Description]` attributes; no value lacks a description.
+- `WindowWidth` values are **strictly powers of two** (512, 1024, ..., 8192), consistent with FFT implementation constraints.
+- `PassFilterType` is **incomplete**: `CriticalDamping` is commented out and *not* part of the active API.
+- No runtime validation is performed by the enums themselves—validation (e.g., range checks on `WindowWidth`) must occur in consuming code.
+
+---
+
+### 4. Dependencies  
+- **Internal dependencies**:
+  - `DTS.Common.Converters.EnumDescriptionTypeConverter` — used via `[TypeConverter]` for deserialization/UI binding.
+  - `System.ComponentModel` — for `[Description]` attribute.
+- **Consumers** (inferred from namespace and naming):
+  - Likely used by reporting/UI components in `DTS.Viewer` (e.g., PSD report configuration models, settings dialogs).
+  - May be referenced by backend signal processing modules (e.g., FFT or filter pipeline classes) that accept these enums as configuration parameters.
+
+---
+
+### 5. Gotchas  
+- **`CriticalDamping` is disabled**: The commented-out `CriticalDamping` entry in `PassFilterType` includes a TODO comment (`// REMOVE THIS HACK / uncomment when implemented in exocortex`), indicating this enum is a placeholder for future functionality. **Do not assume `CriticalDamping` is supported.**
+- **Case-sensitive enum names**: `BlackmanHarris` (no hyphen) vs. `Blackman-Harris` (hyphen in description). UI or serialization logic may rely on the *description* text, not the name.
+- **`Hanning` vs. `Hanning`**: The enum uses `Hanning` (double *n*), which is a common misspelling of the correct term *Hann* (though *Hanning* is widely used in signal processing literature). Ensure downstream code matches this spelling.
+- **No validation on `WindowWidth` values**: While only powers of two are defined, the enum itself does not enforce this—consumers must validate if needed.
+- **No versioning or deprecation markers**: If enums evolve (e.g., new filter types added), consumers may break if deserializing from external sources (e.g., JSON) without fallback handling.
+
+None identified beyond these.