init
This commit is contained in:
126
docs/ai/Common/DTS.Common.Serialization/TSV.md
Normal file
126
docs/ai/Common/DTS.Common.Serialization/TSV.md
Normal file
@@ -0,0 +1,126 @@
|
||||
---
|
||||
source_files:
|
||||
- Common/DTS.Common.Serialization/TSV/TSV.File.cs
|
||||
- Common/DTS.Common.Serialization/TSV/TSVTest.cs
|
||||
- Common/DTS.Common.Serialization/TSV/TSVSettingsWindow.cs
|
||||
- Common/DTS.Common.Serialization/TSV/TSV.File.Writer.cs
|
||||
- Common/DTS.Common.Serialization/TSV/TSVChannel.cs
|
||||
- Common/DTS.Common.Serialization/TSV/TSVSettingsWindow.Designer.cs
|
||||
generated_at: "2026-04-17T15:35:48.983406+00:00"
|
||||
model: "zai-org/GLM-5-FP8"
|
||||
schema_version: 1
|
||||
sha256: "a3b01c62359ae1fc"
|
||||
---
|
||||
|
||||
# TSV Serialization Module Documentation
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This module provides Tab-Separated Values (TSV) serialization for `Test` objects within the DTS serialization framework. It enables exporting test data and metadata to human-readable TSV files, supporting multiple data types (Raw ADC, Converted, and Processed/Filtered). The module includes a Windows Forms UI (`TSVSettingsWindow`) for configuring export parameters at both global and per-channel levels, and persists user preferences via application settings.
|
||||
|
||||
---
|
||||
|
||||
## 2. Public Interface
|
||||
|
||||
### `DTS.Serialization.TSV.File` (partial class)
|
||||
**Inherits:** `Serialization.File`
|
||||
**Implements:** `IWritable<Test>`
|
||||
|
||||
| Member | Signature | Description |
|
||||
|--------|-----------|-------------|
|
||||
| Constructor | `File()` | Initializes a new instance with format name "TSV". |
|
||||
| `Extension` | `static string Extension => ".tsv"` | Returns the file extension for this format. |
|
||||
| `Exporter` | `IWriter<Test> Exporter { get; }` | Lazily initializes and returns a `Writer` instance for exporting tests. Throws `Exception` on failure. |
|
||||
|
||||
---
|
||||
|
||||
### `DTS.Serialization.TSV.TSVTest`
|
||||
|
||||
| Member | Signature | Description |
|
||||
|--------|-----------|-------------|
|
||||
| `Fields` | `public enum Fields` | Enumeration of metadata fields: `LabName`, `POCName`, `POCPhoneAndEmail`, `TestDate`, `TestTime`, `TestNumber`, `TestType`, `TestObject`, `DataType`, `SensorMakeModelSerial`, `SensorLocation`, `SensorAxis`, `SensorMountType`, `EngineeringUnits`, `ChannelErrors`, `SamplingRate`, `AAFilterCutoffDescription`, `BitResolution`, `DigitalFilterType`, `Notes`. |
|
||||
| `GetValue` | `string GetValue(Fields field)` | Returns the value for the specified field. Adds `"#NOVALUE"` to the dictionary if the field is not present. |
|
||||
| `SetValue` | `void SetValue(Fields field, string value)` | Sets a field value, propagates it to all channels in `_channels`, and persists specific fields (`POCName`, `POCPhoneAndEmail`, `DataType`, `LabName`, `TestObject`, `TestType`) to `Properties.Settings1.Default`. |
|
||||
| `Channels` | `TSVChannel[] Channels { get; set; }` | Gets or sets the array of channels. Setting clears and repopulates the internal list. |
|
||||
| `Test` | `Test Test { get; }` | The source test object. |
|
||||
| `DataFilteredEU` | `FilteredData[] DataFilteredEU { get; }` | Filtered engineering unit data. |
|
||||
| `DataUnfilteredEU` | `FilteredData[] DataUnfilteredEU { get; }` | Unfiltered engineering unit data. |
|
||||
| `DataADC` | `FilteredData[] DataADC { get; }` | Raw ADC data. |
|
||||
| `ActualRangesEUFiltered` | `double[] ActualRangesEUFiltered { get; }` | Actual ranges for filtered EU data. |
|
||||
| `ActualRangesEUUnfiltered` | `double[] ActualRangesEUUnfiltered { get; }` | Actual ranges for unfiltered EU data. |
|
||||
| `ActualRangesADC` | `double[] ActualRangesADC { get; }` | Actual ranges for ADC data. |
|
||||
| Constructor | `TSVTest(Test test, FilteredData[] euFiltered, FilteredData[] adc, FilteredData[] euUnfiltered, string path, double[] actualRangesEUFiltered, double[] actualRangesEUUnfiltered, double[] actualRAngesADC)` | Initializes the test, data arrays, creates `TSVChannel` instances, and populates fields from test data and persisted settings. |
|
||||
|
||||
---
|
||||
|
||||
### `DTS.Serialization.TSV.TSVChannel`
|
||||
|
||||
| Member | Signature | Description |
|
||||
|--------|-----------|-------------|
|
||||
| `GetValue` | `string GetValue(TSVTest.Fields field)` | Returns the value for the specified field. Adds `"#NOVALUE"` if not present. |
|
||||
| `SetValue` | `void SetValue(TSVTest.Fields field, string value)` | Sets a field value. Special handling for `DataType`: `"Raw"`, `"Processed"`, or `"Converted"` triggers recalculation of `EngineeringUnits`, `DigitalFilterType`, `BitResolution`, and `FileName`. |
|
||||
| `FileName` | `string FileName { get; set; }` | The output file path for this channel. |
|
||||
| `Serialize` | `void Serialize(TickEventHandler tickHandler)` | Creates the output directory if needed, writes metadata header lines, then writes time-value data pairs. Reports progress via `tickHandler`. |
|
||||
| `ChannelNumber` | `int ChannelNumber => 1 + _channelIndex` | 1-based channel number. |
|
||||
| Constructor | `TSVChannel(TSVTest parentTest, int channelIndex, string path)` | Initializes from parent test and channel index. Sets initial values for `EngineeringUnits`, `SensorMakeModelSerial`, `SensorLocation`, `DigitalFilterType`, `BitResolution`, and default `FileName`. |
|
||||
|
||||
---
|
||||
|
||||
### `DTS.Serialization.TSV.File.Writer` (nested class)
|
||||
**Inherits:** `Writer<File>`
|
||||
**Implements:** `IWriter<Test>`
|
||||
|
||||
| Member | Signature | Description |
|
||||
|--------|-----------|-------------|
|
||||
| `ExportMode` | `public enum ExportMode` | Values: `FtssExcel`, `Ttc`, `Standard`. |
|
||||
| `CurrentExportMode` | `ExportMode CurrentExportMode { get; set; }` | Gets/sets the current export mode. Defaults to `ExportMode.FtssExcel`. Persisted via `Property<ExportMode>`. |
|
||||
| `FilteredChannelData` | `List<FilteredData> FilteredChannelData { get; set; }` | Optional filtered channel data list. |
|
||||
| `MyTSVTest` | `TSVTest MyTSVTest { get; set; }` | The `TSVTest` instance to write. |
|
||||
| `Start` | `double Start { get; set; }` | Default: `0D`. |
|
||||
| `Stop` | `double Stop { get; set; }` | Default: `0D`. |
|
||||
| `SubSampleInterval` | `ushort SubSampleInterval { get; set; }` | Subsample interval. |
|
||||
| `Filtered` | `bool Filtered { get; set; }` | Filtered flag. |
|
||||
| Constructor | `internal Writer(File fileType, int encoding)` | Internal constructor. |
|
||||
| `Write` (overload 1) | `void Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)` | **Throws `NotSupportedException`.** |
|
||||
| `Write` (overload 2) | `void Write(string pathname, string id, string dataFolder, Test test, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler, TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler, CancelRequested cancelRequested, double minStartTime, int dataCollectionLength)` | Invokes `beginEventHandler`, serializes each channel via `channel.Serialize(tickEventHandler)`, handles exceptions, and invokes `endEventHandler`/`errorEventHandler` as appropriate. |
|
||||
| `Initialize` | `void Initialize(string pathname, string id, string dataFolder, Test test, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler, TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler, CancelRequested cancelRequested)` | Empty implementation. |
|
||||
|
||||
---
|
||||
|
||||
### `DTS.Serialization.TSV.TSVSettingsWindow`
|
||||
**Inherits:** `Form`
|
||||
|
||||
| Member | Signature | Description |
|
||||
|--------|-----------|-------------|
|
||||
| Constructor | `TSVSettingsWindow(TSVTest test)` | Initializes the form, populates `c1GridGlobal` with non-excluded fields, populates `c1GridChannels` with channel data. Excluded fields: `AAFilterCutoffDescription`, `BitResolution`, `ChannelErrors`, `DataType`, `DigitalFilterType`, `EngineeringUnits`, `SensorAxis`, `SensorLocation`, `SensorMakeModelSerial`, `SensorMountType`. |
|
||||
| `button1_Click` | `void button1_Click(object sender, EventArgs e)` | Sets `DialogResult.OK` and closes the form. |
|
||||
| `c1GridGlobal_AfterEdit` | `void c1GridGlobal_AfterEdit(object sender, RowColEventArgs e)` | Updates `_test.SetValue()` and refreshes corresponding column in `c1GridChannels`. |
|
||||
| `c1GridChannels_AfterEdit` | `void c1GridChannels_AfterEdit(object sender, RowColEventArgs e)` | Updates the `TSVChannel.SetValue()` for the edited cell. |
|
||||
|
||||
---
|
||||
|
||||
## 3. Invariants
|
||||
|
||||
1. **Channel Index Bounds:** `_channelIndex` in `TSVChannel` must be a valid index into `_parentTest.Test.Channels`, `_parentTest.DataADC`, `_parentTest.DataFilteredEU`, `_parentTest.DataUnfilteredEU`, and corresponding `ActualRanges*` arrays.
|
||||
|
||||
2. **DataType Values:** When setting `Fields.DataType` on a `TSVChannel`, the value must be one of: `"Raw"`, `"Processed"`, or `"Converted"`. Other values will not trigger file path or metadata recalculation.
|
||||
|
||||
3. **File Extension:** `File.Extension` always returns `".tsv"`.
|
||||
|
||||
4. **Default Value:** `GetValue` on both `TSVTest` and `TSVChannel` returns `"#NOVALUE"` for any field not explicitly set.
|
||||
|
||||
5. **Channel Number:** `TSVChannel.ChannelNumber` is always 1-based (`1 + _channelIndex`).
|
||||
|
||||
6. **Writer Export Mode:** `Writer.CurrentExportMode` defaults to `ExportMode.FtssExcel` and is persisted across sessions via the `Property<ExportMode>` mechanism.
|
||||
|
||||
---
|
||||
|
||||
## 4. Dependencies
|
||||
|
||||
### This module depends on:
|
||||
- `DTS.Serialization` — Base `Serialization.File`, `Test` model, `FilteredData`, `IWriter<T>`, `IWritable<T>`, delegate types (`BeginEventHandler`, `CancelEventHandler`, `EndEventHandler`, `TickEventHandler`, `ErrorEventHandler`, `CancelRequested`)
|
||||
- `DTS.Common.Utilities.DotNetProgrammingConstructs` — `Property<T>` class
|
||||
- `DTS.Common.Utilities.Logging` — `APILogger`
|
||||
- `C1.Win.C1FlexGrid` — Third-party grid control used in `TSVSettingsWindow`
|
||||
- `System.Windows.Forms` — Windows Forms infrastructure
|
||||
- `Properties.Settings1` — Application settings for persisting last-used values (`
|
||||
Reference in New Issue
Block a user