init

enriched-qwen3-coder-next/Common/DTS.Common/Classes/DTS.Viewer/TestMetadata.md

@@ -0,0 +1,316 @@
+---
+source_files:
+  - Common/DTS.Common/Classes/DTS.Viewer/TestMetadata/TestMetadata.cs
+  - Common/DTS.Common/Classes/DTS.Viewer/TestMetadata/TestGraphs.cs
+  - Common/DTS.Common/Classes/DTS.Viewer/TestMetadata/TestSetupMetadata.cs
+  - Common/DTS.Common/Classes/DTS.Viewer/TestMetadata/TestRunMetadata.cs
+  - Common/DTS.Common/Classes/DTS.Viewer/TestMetadata/TestSummary.cs
+  - Common/DTS.Common/Classes/DTS.Viewer/TestMetadata/TestModule.cs
+  - Common/DTS.Common/Classes/DTS.Viewer/TestMetadata/TestChannel.cs
+  - Common/DTS.Common/Classes/DTS.Viewer/TestMetadata/TestMetadataList.cs
+generated_at: "2026-04-16T03:19:21.354792+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "2276bf4d72ccc406"
+---
+
+# TestMetadata Module Documentation
+
+## 1. Purpose
+
+This module provides data structures and parsing logic for loading, representing, and managing test metadata from XML-based `.dts` files in the DTS Viewer system. It defines core domain models (`TestMetadata`, `TestRunMetadata`, `TestSetupMetadata`, `TestModule`, `TestChannel`, `TestGraphs`, `TestSummary`) that encapsulate test configuration, hardware setup, channel definitions, and summary information. The `TestMetadataList` class is responsible for deserializing `.dts` XML files into these strongly-typed objects and constructing `TestSummary` instances for UI binding. This module serves as the foundational data layer for test data browsing, selection, and visualization components.
+
+## 2. Public Interface
+
+### `TestMetadataList`
+
+- **`Task<ObservableCollection<ITestSummary>> GetTestSummaryListAsync(IBaseViewModel parent, string path, string file, string pattern = "")`**  
+  Async wrapper for `GetTestSummaryList`. Returns a list of `ITestSummary` objects built from `.dts` files in the specified directory.
+
+- **`ObservableCollection<ITestSummary> GetTestSummaryList(IBaseViewModel parent, string path, string file = "", string pattern = "")`**  
+  Loads `.dts` files (matching `pattern`, default `.dts`) from `path`, parses them into `ITestMetadata`, and returns a collection of `ITestSummary` objects. `parent` is used for command wiring in `TestSummary`.
+
+- **`ObservableCollection<ITestSummary> GetTestSummaryList(string path, string file = "", string pattern = "")`**  
+  Overload of `GetTestSummaryList` without a `parent` parameter (used when `Parent` property in `TestSummary` is not required).
+
+- **`List<ITestMetadata> GetTestMetadataList(XDocument xDoc, string path, string file)`**  
+  Parses an `XDocument` (representing a `.dts` XML file) into a list of `ITestMetadata` instances. Includes error handling, filtering for `TSRAIR_GO_TEST` when `RunTestVariables.IsTSRAIRGo` is true, and channel array pre-allocation.
+
+### `TestMetadata` (implements `ITestMetadata`)
+
+- **`ITestRunMetadata TestRun { get; set; }`**  
+  Contains test run-level metadata (e.g., test ID, description, modules, channels).
+
+- **`ITestSetupMetadata TestSetup { get; set; }`**  
+  Contains test setup-level metadata (e.g., setup name, timestamp, graphs, calibration behavior).
+
+### `TestRunMetadata` (implements `ITestRunMetadata`, `INotifyPropertyChanged`)
+
+- **`string Name { get; set; }`**  
+  Logical test name (from XML `Id` attribute).
+
+- **`string Id { get; set; }`**  
+  File name without extension (from XML `FilePath` attribute).
+
+- **`string Description { get; set; }`**  
+  Test description.
+
+- **`bool InlineSerializedData { get; set; }`**  
+  Indicates if raw data is embedded in the XML.
+
+- **`string TestGuid { get; set; }`**  
+  Unique test identifier.
+
+- **`int FaultFlags { get; set; }`**  
+  Bitmask of test fault conditions.
+
+- **`string Software { get; set; }`**, **`string SoftwareVersion { get; set; }`**  
+  Software name and version used for acquisition.
+
+- **`string DataType { get; set; }`**  
+  Type of data (e.g., "Acceleration", "Force").
+
+- **`DateTime FileDate { get; set; }`**  
+  File system modification date.
+
+- **`string FilePath { get; set; }`**  
+  Full path to the test data file.
+
+- **`List<ITestModule> Modules { get; set; }`**  
+  List of acquisition modules used.
+
+- **`List<ITestChannel> Channels { get; set; }`**  
+  List of physical channels.
+
+- **`List<ITestChannel> CalculatedChannels { get; set; }`**  
+  List of derived channels.
+
+- **`bool IsSelected { get; set; }`**  
+  UI selection state (raises `PropertyChanged`).
+
+- **`event PropertyChangedEventHandler PropertyChanged`**  
+  Implements `INotifyPropertyChanged`.
+
+### `TestSetupMetadata` (implements `ITestSetupMetadata`)
+
+- **`string SetupName { get; set; }`**  
+  Name of the test setup configuration.
+
+- **`DateTime TimeStamp { get; set; }`**  
+  Setup timestamp (fallback if module timestamps are invalid/zero).
+
+- **`List<ITestGraphs> TestGraphs { get; set; }`**  
+  List of graph definitions.
+
+- **`CalibrationBehaviors CalibrationBehavior { get; set; }`**  
+  Calibration strategy (e.g., `NonLinearIfAvailable`).
+
+### `TestGraphs` (implements `ITestGraphs`)
+
+- **`string Name { get; set; }`**  
+  Graph display name.
+
+- **`string HardwareChannelName { get; set; }`**  
+  Hardware channel name associated with the graph.
+
+- **`List<string> ChannelIds { get; set; }`**  
+  List of channel IDs included in the graph.
+
+- **`List<ITestChannel> Channels { get; set; }`**  
+  *Note: Not populated during XML parsing; likely for runtime use.*
+
+### `TestModule` (implements `ITestModule`, `INotifyPropertyChanged`)
+
+- **`string SerialNumber { get; set; }`**, **`string BaseSerialNumber { get; set; }`**  
+  Module serial and base serial numbers.
+
+- **`int Number { get; set; }`**, **`int NumberOfChannels { get; set; }`**  
+  Module number and channel count.
+
+- **`int SampleRateHz { get; set; }`**, **`int UnsubsampledSampleRateHz { get; set; }`**  
+  Sample rates (post- and pre-subsampling).
+
+- **`double RequestedPreTriggerSeconds { get; set; }`**, **`double PreTriggerSeconds { get; set; }`**, **`double RequestedPostTriggerSeconds { get; set; }`**, **`double PostTriggerSeconds { get; set; }`**  
+  Trigger timing parameters.
+
+- **`int StartRecordTimestampSec { get; set; }`**, **`int StartRecordTimestampNanoSec { get; set; }`**, **`int TriggerTimestampSec { get; set; }`**, **`int TriggerTimestampNanoSec { get; set; }`**  
+  High-precision timestamps (PTP1588).
+
+- **`List<ulong> TriggerSampleNumbers { get; set; }`**  
+  *Note: Always initialized as empty list; parsing logic returns empty list.*
+
+- **`bool PTPMasterSync { get; set; }`**  
+  Indicates PTP synchronization status.
+
+- **Tilt Sensor Angles (Pre/Post)**:  
+  `TiltSensorAxis{X,Y,Z}Degrees{Pre,Post}` — tilt sensor readings before/after test.
+
+- **Temperature Readings (Pre/Post)**:  
+  `TemperatureLocation{1-4}{Pre,Post}` — temperature sensor readings.
+
+- **`List<ITestChannel> Channels { get; set; }`**, **`List<ITestChannel> CalculatedChannels { get; set; }`**  
+  Channels associated with this module.
+
+- **`bool IsSelected { get; set; }`**  
+  Selection state (raises `PropertyChanged`).
+
+- **`event PropertyChangedEventHandler PropertyChanged`**  
+  Implements `INotifyPropertyChanged`.
+
+### `TestChannel` (implements `ITestChannel`, `IBasePropertyChanged`, `ISerializable`)
+
+- **`string Group { get; set; }`**, **`string SubGroup { get; set; }`**  
+  Logical grouping.
+
+- **`bool IsGraphChannel { get; set; }`**, **`string GraphName { get; set; }`**  
+  Indicates if channel is used in a graph.
+
+- **`string TestId { get; set; }`**, **`string TestSetupName { get; set; }`**, **`string ModuleSerialNumber { get; set; }`**  
+  Contextual identifiers.
+
+- **`string SerialNumber { get; set; }`**, **`string ChannelId { get; set; }`**  
+  Channel serial and ID.
+
+- **`string ChannelDisplayName { get; set; }`**, **`string ChannelDescriptionString { get; set; }`**  
+  Display name and description string.
+
+- **`string ChannelName2 { get; set; }`**, **`string HardwareChannelName { get; set; }`**  
+  Alternative channel names.
+
+- **`string ChannelType { get; set; }`**  
+  Channel type (e.g., "AnalogInput").
+
+- **`bool IsCalculatedChannel { get; set; }`**  
+  Indicates if channel is derived.
+
+- **`int Number { get; set; }`**, **`int ChannelNumber { get; set; }`**  
+  Channel numbers.
+
+- **`double Sensitivity { get; set; }`**, **`string SensitivityUnits { get; set; }`**, **`double DesiredRange { get; set; }`**, **`double ActualMaxRangeEu { get; set; }`**, **`double ActualMinRangeEu { get; set; }`**, **`double ActualMaxRangeMv { get; set; }`**, **`double ActualMinRangeMv { get; set; }`**  
+  Calibration and range parameters.
+
+- **`string Bridge { get; set; }`**, **`double BridgeResistanceOhms { get; set; }`**, **`double ZeroPoint { get; set; }`**  
+  Bridge configuration.
+
+- **`DateTime Start { get; set; }`**  
+  Channel start time.
+
+- **`string SoftwareFilter { get; set; }`**, **`bool ProportionalToExcitation { get; set; }`**, **`bool IsInverted { get; set; }`**, **`string LinearizationFormula { get; set; }`**, **`bool IsSubsampled { get; set; }`**  
+  Processing flags.
+
+- **`int AbsoluteDisplayOrder { get; set; }`**  
+  Display order index.
+
+- **`DateTime LastCalibrationDate { get; set; }`**  
+  Calibration date.
+
+- **`string SensorId { get; set; }`**  
+  Sensor identifier.
+
+- **`int OffsetToleranceLowMv { get; set; }`**, **`int OffsetToleranceHighMv { get; set; }`**, **`int DataFlag { get; set; }`**  
+  Tolerance and data quality flags.
+
+- **`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; }`**  
+  Excitation, units, and zeroing configuration.
+
+- **`int InitialEu { get; set; }`**, **`string InitialOffset { get; set; }`**  
+  Initial calibration values.
+
+- **`double MeasuredShuntDeflectionMv { get; set; }`**, **`double TargetShuntDeflectionMv { get; set; }`**, **`double MeasuredExcitationVoltage { get; set; }`**, **`double FactoryExcitationVoltage { get; set; }`**  
+  Shunt calibration parameters.
+
+- **`double TimeOfFirstSample { get; set; }`**, **`double Multiplier { get; set; }`**, **`double UserOffsetEu { get; set; }`**, **`int UnitConversion { get; set; }`**  
+  Timing, scaling, and unit conversion.
+
+- **`bool AtCapacity { get; set; }`**, **`int CapacityOutputIsBasedOn { get; set; }`**  
+  Capacity-related flags.
+
+- **`string SourceChannelNumber { get; set; }`**, **`string SourceModuleNumber { get; set; }`**, **`string SourceModuleSerialNumber { get; set; }`**, **`string Calculation { get; set; }`**  
+  For calculated channels: source and formula.
+
+- **`string BinaryFileName { get; set; }`**, **`string BinaryFilePath { get; set; }`**  
+  Binary data file info.
+
+- **`double Xmax { get; set; }`**, **`double Xmin { get; set; }`**  
+  X-axis range.
+
+- **`int SequentialNumbers { get; set; }`**  
+  Sequential index.
+
+- **`ITestSetupMetadata ParentTestSetup { get; set; }`**, **`ITestModule ParentModule { get; set; }`**, **`IBaseViewModel Parent { get; set; }`**  
+  Parent references.
+
+- **`Color ChannelColor { get; set; }`**, **`string ErrorMessage { get; set; }`**, **`bool IsError { get; set; }`**, **`Color? ErrorColor { get; set; }`**  
+  UI state properties.
+
+- **`bool IsLocked { get; set; }`**, **`bool CanLock { get; set; }`**, **`bool CanSelectChannel { get; set; }`**, **`bool IsExpanded { get; set; }`**, **`bool IsSelected { get; set; }`**  
+  Selection/locking state with side effects (e.g., updating graph view models).
+
+- **`double MinADC { get; set; }`**, **`double MaxADC { get; set; }`**, **`double AveADC { get; set; }`**, **`double StdDevADC { get; set; }`**, **`double T0ADC { get; set; }`**  
+  ADC statistics.
+
+- **`double MinMV { get; set; }`**, **`double MaxMV { get; set; }`**, **`double AveMV { get; set; }`**, **`double StdDevMV { get; set; }`**, **`double T0MV { get; set; }`**  
+  mV statistics.
+
+- **`double MinEU { get; set; }`**, **`double MaxEU { get; set; }`**, **`double AveEU { get; set; }`**, **`double StdDevEU { get; set; }`**, **`double T0EU { get; set; }`**  
+  Engineering Unit statistics.
+
+- **`double MinY { get; set; }`**, **`double MaxY { get; set; }`**, **`double AveY { get; set; }`**, **`double StdDevY { get; set; }`**, **`double T0Value { get; set; }`**  
+  Current unit statistics.
+
+- **`string SetupEID { get; set; }`**, **`string DataCollectionEID { get; set; }`**  
+  EID (likely Event ID) at setup and collection time.
+
+- **`void SetChannelDescriptionAndDisplayName(string channelDescription)`**  
+  Sets `ChannelDescriptionString` and `ChannelDisplayName`.
+
+- **`ITestChannel Copy()`**  
+  Shallow copy via `MemberwiseClone()`.
+
+- **`override string ToString()`**  
+  Returns `ChannelName2` if embedded test-specific; otherwise `ChannelDescriptionString`.
+
+### `TestSummary` (implements `ITestSummary`, `INotifyPropertyChanged`)
+
+- **`const string ROI_SUFFIX = @"_ROI Period"`**  
+  Suffix indicating ROI period data.
+
+- **`string Id { get; set; }`**  
+  Unique ID: `TestRun.Id + ParseEventNumber(TestRun.FilePath)`.
+
+- **`string SetupName { get; set; }`**, **`string Description { get; set; }`**, **`int ChannelCount { get; set; }`**, **`DateTime FileDate { get; set; }`**, **`DateTime TimeStamp { get; set; }`**, **`string DataType { get; set; }`**  
+  Summary metadata.
+
+- **`bool IsSelected { get; set; }`**  
+  Selection state with side effects via `SelectionChanged()`.
+
+- **`List<ITestGraphs> Graphs { get; set; }`**, **`List<ITestChannel> Channels { get; set; }`**, **`List<ITestChannel> CalculatedChannels { get; set; }`**  
+  References to metadata.
+
+- **`IBaseViewModel Parent { get; set; }`**  
+  Parent view model (for command binding).
+
+- **`CalibrationBehaviors CalibrationBehavior { get; set; } = CalibrationBehaviors.NonLinearIfAvailable`**  
+  Default calibration behavior.
+
+- **`ITestMetadata TestMetadata { get; set; }`**  
+  Full metadata object.
+
+- **`DelegateCommand IsSelectedCommand { get; }`**  
+  Command bound to `IsSelected` property.
+
+- **`void SelectionChanged()`**  
+  Updates `Parent.SelectedTestSummaryList` and publishes via `IEventAggregator`.
+
+- **`event PropertyChangedEventHandler PropertyChanged`**  
+  Implements `INotifyPropertyChanged`.
+
+## 3. Invariants
+
+- **`TestMetadata`** must always have non-null `TestRun` and `TestSetup` properties after construction (defaults are created on parse failure).
+- **`TestSummary.Id`** is constructed as `TestRun.Id + ParseEventNumber(TestRun.FilePath)`. `ParseEventNumber` extracts the segment starting with `DTS.Common.Constants.EventNumber` from the file path.
+- **`TestSummary.TimeStamp`** is determined by `TestMetadataList.GetTimestamp()`:
+  - Uses minimum PTP1588 timestamp from modules (trigger or start record).
+  - Falls back to `TestSetup.TimeStamp` if module timestamps are invalid (e.g., zero, before 1990).
+- **`TestChannel.ChannelId`** defaults to `GetHashCode().ToString()` if the XML attribute is missing or `-1`.
+- **`TestChannel.HardwareChannelName`** is set to `Strings.Strings.Table_NA` for calculated channels (per comment `//