init

enriched-qwen3-coder-next/Common/DTS.Common/Interface/DTS.Viewer/TestDefinition.md

@@ -0,0 +1,180 @@
+---
+source_files:
+  - Common/DTS.Common/Interface/DTS.Viewer/TestDefinition/ITestMetadata.cs
+  - Common/DTS.Common/Interface/DTS.Viewer/TestDefinition/ITestGraphs.cs
+  - Common/DTS.Common/Interface/DTS.Viewer/TestDefinition/ITestSetupMetadata.cs
+  - Common/DTS.Common/Interface/DTS.Viewer/TestDefinition/ITestEvent.cs
+  - Common/DTS.Common/Interface/DTS.Viewer/TestDefinition/ITestSummary.cs
+  - Common/DTS.Common/Interface/DTS.Viewer/TestDefinition/ITestRunMetadata.cs
+  - Common/DTS.Common/Interface/DTS.Viewer/TestDefinition/ITestModule.cs
+  - Common/DTS.Common/Interface/DTS.Viewer/TestDefinition/ITestCalculatedChannel.cs
+  - Common/DTS.Common/Interface/DTS.Viewer/TestDefinition/ITestChannel.cs
+generated_at: "2026-04-16T03:09:25.548414+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "ba5d335a6c532c10"
+---
+
+# Documentation: Test Definition Interfaces
+
+## 1. Purpose  
+This module defines a set of interfaces that model the metadata and structure of test data within the DTS (Dynamic Test System) viewer. It serves as the foundational data contract between data acquisition systems and the viewer application, enabling structured representation of test runs, setups, modules, channels (both physical and calculated), events, and associated metadata. These interfaces support UI binding (via `INotifyPropertyChanged`), serialization, and hierarchical navigation (e.g., `Parent` references), forming the backbone for test data visualization, analysis, and reporting.
+
+## 2. Public Interface  
+
+### `ITestMetadata`
+- **Namespace**: `DTS.Common.Interface.TestDefinition`
+- **Properties**:
+  - `ITestRunMetadata TestRun { get; set; }`: Top-level metadata for the test run.
+  - `ITestSetupMetadata TestSetup { get; set; }`: Metadata describing the physical setup during the test.
+
+### `ITestGraphs`
+- **Namespace**: `DTS.Common.Interface`
+- **Properties**:
+  - `string Name { get; set; }`: Human-readable name of the graph group.
+  - `string HardwareChannelName { get; set; }`: Original hardware channel name (e.g., "CH1").
+  - `List<string> ChannelIds { get; set; }`: List of logical channel IDs associated with this graph.
+  - `List<ITestChannel> Channels { get; set; }`: List of `ITestChannel` instances assigned to this graph.
+
+### `ITestSetupMetadata`
+- **Namespace**: `DTS.Common.Interface`
+- **Properties**:
+  - `string SetupName { get; set; }`: Name of the test setup configuration.
+  - `DateTime TimeStamp { get; set; }`: Timestamp when the setup was created/recorded.
+  - `List<ITestGraphs> TestGraphs { get; set; }`: Collection of graph groupings used in the test.
+  - `CalibrationBehaviors CalibrationBehavior { get; set; }`: Enumerated calibration behavior settings (type defined in `DTS.Common.Enums.Sensors`).
+
+### `ITestEvent`
+- **Namespace**: `DTS.Common.Interface`
+- **Properties**:
+  - `string TestId { get; set; }`: Unique identifier for the test.
+  - `string TestItem { get; set; }`: Name of the test item (e.g., part number).
+  - `string DTSFile { get; set; }`: Path or name of the associated `.dts` file.
+  - `bool IsLocked { get; set; }`: Indicates if the event is locked (e.g., read-only).
+  - `bool IsSelected { get; set; }`: Selection state in UI.
+  - `bool CanLock { get; set; }`: Whether locking is permitted.
+  - `IBaseViewModel Parent { get; set; }`: Parent view model in the UI hierarchy.
+  - `string Name { get; set; }`: Display name of the event.
+  - `int TreeIndex { get; set; }`: Position in a tree view hierarchy.
+
+### `ITestSummary`
+- **Namespace**: `DTS.Common.Interface.TestDefinition`
+- **Inherits**: `IBaseClass`
+- **Properties**:
+  - `string Id { get; set; }`: Unique identifier for the summary.
+  - `string Name { get; set; }`: Human-readable name of the test.
+  - `string Description { get; set; }`: Free-text description.
+  - `int ChannelCount { get; set; }`: Total number of channels.
+  - `DateTime TestDate { get; set; }`: Date/time of the test.
+  - `string DataType { get; set; }`: Type of data (e.g., "Raw", "Processed").
+  - `bool IsSelected { get; set; }`: Selection state.
+  - `List<ITestGraphs> Graphs { get; set; }`: Graph groupings.
+  - `List<ITestChannel> Channels { get; set; }`: Physical channels.
+  - `List<ITestChannel> CalculatedChannels { get; set; }`: Calculated channels.
+  - `IBaseViewModel Parent { get; set; }`: Parent view model.
+
+### `ITestRunMetadata`
+- **Namespace**: `DTS.Common.Interface`
+- **Properties**:
+  - `string Name { get; set; }`: Name of the test run.
+  - `string Id { get; set; }`: Unique identifier.
+  - `string Description { get; set; }`: Free-text description.
+  - `bool InlineSerializedData { get; set; }`: Whether raw data is embedded in metadata.
+  - `string TestGuid { get; set; }`: Globally unique test identifier.
+  - `int FaultFlags { get; set; }`: Bitmask of fault conditions.
+  - `string Software { get; set; }`: Software name used (e.g., "DTS Viewer").
+  - `string SoftwareVersion { get; set; }`: Version string.
+  - `string DataType { get; set; }`: Data type classification.
+  - `DateTime FileDate { get; set; }`: File creation/modification timestamp.
+  - `string FilePath { get; set; }`: Full path to the data file.
+  - `List<ITestModule> Modules { get; set; }`: Collection of acquisition modules.
+  - `List<ITestChannel> Channels { get; set; }`: Physical channels.
+  - `List<ITestChannel> CalculatedChannels { get; set; }`: Calculated channels.
+
+### `ITestModule`
+- **Namespace**: `DTS.Common.Interface`
+- **Properties**:
+  - `string SerialNumber { get; set; }`: Module serial number.
+  - `string BaseSerialNumber { get; set; }`: Base unit serial number (if applicable).
+  - `int AaFilterRateHz { get; set; }`: Anti-aliasing filter rate.
+  - `int Number { get; set; }`: Module index/number.
+  - `int NumberOfSamples { get; set; }`: Number of samples after subsampling.
+  - `int UnsubsampledNumberOfSamples { get; set; }`: Raw sample count.
+  - `double RequestedPostTriggerSeconds { get; set; }`: Requested post-trigger time.
+  - `double RequestedPreTriggerSeconds { get; set; }`: Requested pre-trigger time.
+  - `double PostTriggerSeconds { get; set; }`: Actual post-trigger time.
+  - `double PreTriggerSeconds { get; set; }`: Actual pre-trigger time.
+  - `string RecordingMode { get; set; }`: e.g., "Continuous", "Triggered".
+  - `int SampleRateHz { get; set; }`: Effective sample rate.
+  - `int StartRecordSampleNumber { get; set; }`: Sample index where recording started.
+  - `int NumberOfChannels { get; set; }`: Number of active channels on module.
+  - `bool InlineSerializedData { get; set; }`: Whether raw data is embedded.
+  - `int StartRecordTimestampSec { get; set; }` & `int StartRecordTimestampNanoSec { get; set; }`: Start time (POSIX seconds + nanoseconds).
+  - `int TriggerTimestampSec { get; set; }` & `int TriggerTimestampNanoSec { get; set; }`: Trigger time.
+  - `List<ulong> TriggerSampleNumbers { get; set; }`: Sample indices where triggers occurred.
+  - `bool PTPMasterSync { get; set; }`: Precision Time Protocol master sync status.
+  - `TiltSensorAxisX/Y/ZDegreesPre/Post { get; set; }`: Tilt sensor readings before/after test.
+  - `TemperatureLocation1-4Pre/Post { get; set; }`: Temperature readings before/after test.
+  - `List<ITestChannel> Channels { get; set; }`: Physical channels on this module.
+  - `List<ITestChannel> CalculatedChannels { get; set; }`: Calculated channels on this module.
+
+### `ITestCalculatedChannel`
+- **Namespace**: `DTS.Common.Interface`
+- **Properties**:
+  - All properties of `ITestChannel` (see below), plus:
+  - `string SourceChannelNumber { get; set; }`: Source channel number(s) used in calculation.
+  - `string SourceModuleNumber { get; set; }`: Source module number(s).
+  - `string SourceModuleSerialNumber { get; set; }`: Source module serial number(s).
+  - `string Calculation { get; set; }`: Formula or operation used (e.g., "CH1 + CH2").
+  - `string SensitivityUnits { get; set; }`: Units for sensitivity (e.g., "mV/V").
+  - `int SensorCapacity { get; set; }`: Sensor full-scale capacity.
+
+### `ITestChannel`
+- **Namespace**: `DTS.Common.Interface`
+- **Properties**:
+  - **Identification & Hierarchy**:
+    - `string Group { get; set; }`, `string SubGroup { get; set; }`: Logical grouping.
+    - `string TestId { get; set; }`, `string TestSetupName { get; set; }`, `string ModuleSerialNumber { get; set; }`, `string SerialNumber { get; set; }`, `string ChannelId { get; set; }`, `string ChannelDisplayName { get; set; }`, `string Description { get; set; }`, `string IsoCode { get; set; }`, `string IsoChannelName { get; set; }`, `string UserCode { get; set; }`, `string UserChannelName { get; set; }`, `string ChannelGroupName { get; set; }`, `string ChannelType { get; set; }`, `bool IsCalculatedChannel { get; set; }`, `int Number { get; set; }`.
+  - **Configuration & Calibration**:
+    - `string DigitalMultiplier { get; set; }`, `string DigitalMode { get; set; }`, `DateTime Start { get; set; }`, `string Bridge { get; set; }`, `double BridgeResistanceOhms { get; set; }`, `double ZeroPoint { get; set; }`, `string ChannelDescriptionString { get; set; }`, `void SetChannelDescriptionAndDisplayName(string channelDescriptionString)`, `string ChannelName2 { get; set; }`, `string HardwareChannelName { get; set; }`, `double DesiredRange { get; set; }`, `double ActualMaxRangeEu { get; set; }`, `double ActualMinRangeEu { get; set; }`, `double ActualMaxRangeAdc { get; }`, `double ActualMinRangeAdc { get; }`, `double ActualMaxRangeMv { get; set; }`, `double ActualMinRangeMv { get; set; }`, `double Sensitivity { get; set; }`, `string SoftwareFilter { get; set; }`, `bool ProportionalToExcitation { get; set; }`, `bool IsInverted { get; set; }`, `string LinearizationFormula { get; set; }`, `bool IsSubsampled { get; set; }`, `int AbsoluteDisplayOrder { get; set; }`, `DateTime LastCalibrationDate { get; set; }`, `string SensorId { get; set; }`, `int OffsetToleranceLowMv { get; set; }`, `int OffsetToleranceHighMv { get; set; }`, `int DataFlag { get; set; }`, `string ExcitationVoltage { get; set; }`, `string Eu { get; set; }`, `bool CalSignalEnabled { get; set; }`, `bool ShuntEnabled { get; set; }`, `bool VoltageInsertionCheckEnabled { get; set; }`, `bool RemoveOffset { get; set; }`, `string ZeroMethod { get; set; }`, `double ZeroAverageWindowBegin { get; set; }`, `double ZeroAverageWindowEnd { get; set; }`, `int InitialEu { get; set; }`, `string InitialOffset { get; set; }`, `int UnsubsampledSampleRateHz { get; set; }`, `double MeasuredShuntDeflectionMv { get; set; }`, `double TargetShuntDeflectionMv { get; set; }`, `double MeasuredExcitationVoltage { get; set; }`, `double FactoryExcitationVoltage { get; set; }`, `double TimeOfFirstSample { get; set; }`, `double Multiplier { get; set; }`, `double UserOffsetEu { get; set; }`, `int UnitConversion { get; set; }`, `bool AtCapacity { get; set; }`, `int CapacityOutputIsBasedOn { get; set; }`, `string SourceChannelNumber { get; set; }`, `string SourceModuleNumber { get; set; }`, `string SourceModuleSerialNumber { get; set; }`, `string Calculation { get; set; }`, `int SampleRateHz { get; set; }`, `string SensitivityUnits { get; set; }`, `int SensorCapacity { get; set; }`, `string SensorPolarity { get; set; }`, `int ChannelNumber { get; set; }`, `string BinaryFileName { get; set; }`, `string BinaryFilePath { get; set; }`, `double Xmax { get; set; }`, `double Xmin { get; set; }`, `int SequentialNumbers { get; set; }`, `ITestSetupMetadata ParentTestSetup { get; set; }`, `ITestModule ParentModule { get; set; }`, `IBaseViewModel Parent { get; set; }`.
+  - **UI & Interaction**:
+    - `Color ChannelColor { get; set; }`, `string ErrorMessage { get; set; }`, `bool IsError { get; set; }`, `Color? ErrorColor { get; set; }`, `bool IsSelected { get; set; }`, `bool CanSelectChannel { get; set; }`, `bool IsLocked { get; set; }`, `bool CanLock { get; set; }`, `ITestChannel Copy()`.
+  - **Time/Trigger Markers**:
+    - `ulong T1Sample { get; set; }`, `ulong T2Sample { get; set; }`, `double HIC { get; set; }`.
+  - **User Scaling**:
+    - `bool UseEUScaler { get; set; }`, `double ScaleFactorEU { get; set; }`.
+  - **Dataset Statistics (ADC/mV/EU/Current Units)**:
+    - `MinADC`, `MaxADC`, `AveADC`, `StdDevADC`, `T0ADC` (ADC domain).
+    - `MinMV`, `MaxMV`, `AveMV`, `StdDevMV`, `T0MV` (mV domain).
+    - `MinEU`, `MaxEU`, `AveEU`, `StdDevEU`, `T0EU` (Engineering Units).
+    - `MinY`, `MaxY`, `AveY`, `StdDevY`, `T0Value` (current display units).
+  - **EID (Electronic Identification)**:
+    - `string SetupEID { get; set; }`, `string DataCollectionEID { get; set; }`.
+
+## 3. Invariants  
+- `ITestChannel` and `ITestCalculatedChannel` implement `INotifyPropertyChanged`, indicating they support data binding and must raise `PropertyChanged` events on property changes.
+- `ITestRunMetadata`, `ITestModule`, `ITestChannel`, and `ITestCalculatedChannel` all implement `INotifyPropertyChanged`.
+- `ITestChannel.ParentModule` and `ITestChannel.ParentTestSetup` must be non-null for channels associated with a module/test setup.
+- `ITestChannel.IsCalculatedChannel` must be `true` for instances of `ITestCalculatedChannel` (though not enforced by interface alone).
+- `ITestChannel.ChannelId` is expected to be unique within a given test context (not strictly enforced by interface).
+- `ITestEvent.CanLock` implies whether `IsLocked` can be changed; if `false`, `IsLocked` should be treated as read-only.
+- `ITestSummary.Graphs`, `Channels`, and `CalculatedChannels` are expected to be consistent with `ITestRunMetadata`'s corresponding collections (e.g., `Graphs` may aggregate `ITestGraphs` from `ITestRunMetadata.Modules`).
+
+## 4. Dependencies  
+- **External Dependencies**:
+  - `System.Collections.Generic`, `System.ComponentModel`, `System` (core .NET types).
+  - `DTS.Common.Base` (for `IBaseViewModel`, `IBaseClass`).
+  - `DTS.Common.Enums.Sensors` (for `CalibrationBehaviors` enum).
+  - `System.Windows.Media` (for `Color` type used in `ITestChannel.ChannelColor`).
+- **Depended Upon By**:
+  - UI layers (e.g., WPF view models, views) that bind to these interfaces for test data display and editing.
+  - Data parsers (e.g., `.dts` file readers) that populate instances of types implementing these interfaces.
+  - Serialization/deserialization logic (e.g., for `InlineSerializedData` handling).
+  - Analysis modules that consume channel statistics (e.g., `MinADC`, `MaxEU`, `HIC`).
+
+## 5. Gotchas  
+- **Ambiguous `ITestCalculatedChannel` inheritance**: `ITestCalculatedChannel` does *not* explicitly inherit from `ITestChannel`, but its property list duplicates all members of `ITestChannel` (and adds extra fields). This suggests a design where calculated channels are treated as a distinct type, but consumers must be aware that `ITestCalculatedChannel` instances should be usable wherever `ITestChannel` is expected (e.g., via casting or pattern matching).  
+- **Redundant properties**: `ITestChannel` and `ITestCalculatedChannel` both contain `SourceChannelNumber`, `SourceModuleNumber`, etc., but only `ITestCalculatedChannel`’s are semantically meaningful. Consumers should check `IsCalculatedChannel` before relying on these fields.  
+- **`ActualMaxRangeAdc`/`ActualMinRangeAdc` are read-only**: These are `get;` only in `ITestChannel`, implying they are computed from other properties (e.g., `ActualMaxRangeMv`, `Sensitivity`, etc.). Modifying them directly is impossible.  
+- **`ChannelColor` and `ChannelDisplayName` may be mutable post-creation**: Since they are `set;` properties, UI code may update them dynamically (e.g., for highlighting), but this could affect serialization if not handled.  
+- **`IT