DP44/enriched-qwen3-coder-next/Common/DTS.Common.Serialization/TDM.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.Serialization/TDM/File.cs Common/DTS.Common.Serialization/TDM/TDMParameterDlg.cs Common/DTS.Common.Serialization/TDM/Writer.cs Common/DTS.Common.Serialization/TDM/TestHeader.cs Common/DTS.Common.Serialization/TDM/TDMParameterDlg.Designer.cs Common/DTS.Common.Serialization/TDM/ChannelHeader.cs	2026-04-16T03:39:24.855976+00:00	Qwen/Qwen3-Coder-Next-FP8	1	3ac6639dcd230dd5

TDM Serialization Module Documentation

1. Purpose

This module provides serialization support for exporting test data to the TDM (Test Data Manager) CSV format, specifically targeting the CFC1000 specification. It enables conversion of internal Test objects into structured CSV files containing test metadata, channel headers, and sampled data, with support for time-range filtering (start/stop), subsampling, and optional filtering. The module exists to interface with external tools or systems (e.g., TTS, TEMA, TDAS) that consume TDM-formatted data, ensuring compatibility through precise adherence to the expected file structure and field semantics.

2. Public Interface

DTS.Serialization.TDM.File

• File()
  Constructor. Initializes the file type with the fixed format name "TDM CFC1000" (passed to base("TDM CFC1000")).
• Exporter (property, IWriter<Test>)
  Returns a lazily-initialized Writer instance configured with this File instance and DefaultEncoding. Sets the Start and Stop properties on the writer before returning.
• Start (property, double)
  Gets/sets the start time (in seconds) for export filtering.
• Stop (property, double)
  Gets/sets the stop time (in seconds) for export filtering.

DTS.Serialization.TDM.Writer

• Writer(File fileType, int encoding) (internal constructor)
  Initializes the writer with the specified File type and encoding.
• AllowTTSExportFiltering (property, bool, default false)
  Controls whether filtered data export is enabled.
• Start, Stop (properties, double)
  Get/set the time range (in seconds) to export. Rounded to 3 decimal places internally during Write.
• FilteredData (property, List<FilteredData>)
  Holds precomputed filtered data (used when AllowTTSExportFiltering is true).
• Test (property, Test)
  The test object being exported.
• IncrementLevel (property, ulong, read-only)
  Controls granularity of progress updates during export (set dynamically based on estimated sample count).
• SubSampleInterval (property, ushort)
  Subsampling factor applied during export.
• ExtensionPrefix (property, string, default "")
  Optional string appended to the output filename before .csv.
• Write(string pathname, string id, string dataFolder, Test target, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler, CancelEventHandler, EndEventHandler, TickEventHandler, ErrorEventHandler, CancelRequested, double minStartTime, int dataCollectionLength)
  Primary export method. Serializes the Test to a CSV file at pathname. Performs rounding of Start/Stop to 3 decimal places, computes progress increments, and invokes DoExport. Notable: pathname is used as a directory; the actual file path is Path.Combine(pathname, Test.Id) with optional suffixes.
• DoExport(bool bFiltered, string pathname, double start, double stop, bool allowTTSFilteredExport) (private)
  Core export logic: constructs the output filename, opens a StreamWriter with UTF-8 encoding (or fallback), and writes test header, channel header, and channel data via TestHeader.WriteTestHeader, ChannelHeader.WriteChannelHeaderToString, and ChannelData.GenerateChannelData/WriteChannelData.
• Initialize(...)
  Empty stub method (no-op). Present to satisfy IWriter<Test> interface but performs no initialization.

DTS.Serialization.TDM.TestHeader

• WriteTestHeader(Writer writer, TextWriter tw, bool bFiltered, UInt16 subSampleInterval, ulong numSamples, int preTriggerSamples)
  Writes the test header section to the CSV. Includes test ID, impact parameters (hardcoded to 0), date/time, device sections (dummies, barriers, groups), sample counts, sample rate, channel count, and description. Device section writing is partially implemented (dummies use UserValue3 from first channel; barriers/groups are written as blank lines).

DTS.Serialization.TDM.ChannelHeader

• WriteChannelHeaderToString(Writer writer, TextWriter tw, bool bFiltered, double start, double end)
  Writes the channel header section (15 lines) to the CSV. For each non-squib-voltage channel, populates fields: DAS name, capacity, engineering units, sensor SN, sensitivity, excitation, min/max values (computed over requested range), Toyota calc fields (hardcoded), knee point (from SoftwareFilter), data flag, channel code, and channel description. Squib voltage channels are skipped.

DTS.Serialization.TDM.TDMParameterDlg

• TDMParameterDlg(string testName, double testStart, double testEnd)
  Constructor. Initializes the dialog with test metadata. Sets default location to TDMFolder setting + {testName}.csv. Sets tbStart/tbStop text to either provided values (converted to ms) or user defaults, enforcing min/max constraints from testStart/testEnd.
• FileName (property, string)
  Gets the selected output file path from tbLocation.Text.
• Start (property, double)
  Gets the parsed start time in seconds (value in tbStart is in ms, divided by 1000).
• Stop (property, double)
  Gets the parsed stop time in seconds (value in tbStop is in ms, divided by 1000).
• btnBrowse_Click
  Opens a SaveFileDialog to select the output .csv file.
• btnOK_Click
  Validates inputs: parses tbStart/tbStop as doubles, checks Stop > Start, ensures values are within [testStart*1000, testEnd*1000] ms range, saves settings, and sets DialogResult = OK.
• btnCancel_Click
  Sets DialogResult = Cancel and closes the dialog.

3. Invariants

• File format: Output is always a .csv file named {Test.Id}[optional suffix].csv.
• Time units: Start/Stop in File, Writer, and TDMParameterDlg properties are in seconds, except TDMParameterDlg UI fields (tbStart, tbStop) which display and parse values in milliseconds.
• Rounding: Start and Stop passed to DoExport are rounded to 3 decimal places (milliseconds precision) before use.
• Channel filtering: Squib voltage channels (IsSquibVoltage() == true) are excluded from channel header and data export.
• Sample bounds: Exported sample indices are clamped to [StartRecordSampleNumber, StartRecordSampleNumber + NumberOfSamples) per module. Invalid ranges are silently adjusted.
• Encoding: Output uses UTF-8 with BOM by default; falls back to Encoding.Default on encoding errors.
• Device section constraints: TestHeader enforces MAX_DEVICE_LINES = 23 total device lines (dummies, barriers, groups), with specific max counts (MAX_DUMMY_DISPLAY=16, MAX_BARRIER_DISPLAY=3, MAX_OLD_GROUP_LINES=4). Device lists are padded with empty lines to fill allocated space.
• Progress reporting: IncrementLevel is dynamically set to 10, 1000, or 10000 based on estimated sample count to ensure progress ticks fit within uint limits.

4. Dependencies

Internal Dependencies

• DTS.Common.DAS.Concepts: Provides Test, Test.Module, Test.Module.Channel, Test.Module.AnalogInputChannel, FilteredData, DataScaler.
• DTS.Common.Utilities.Logging: Provides APILogger.
• DTS.Common.Serialization: Base classes Serialization.File, Serialization.File.Writer<File>, IWriter<Test>, event handlers (BeginEventHandler, EndEventHandler, TickEventHandler, ErrorEventHandler, CancelEventHandler, CancelRequested).
• DTS.Common.Enums.Sensors: SensorConstants (e.g., BridgeType.IEPE, BridgeType.DigitalInput).
• DTS.Common.Utilities: DescriptionAttributeCoder<T>.
• System: Core types (System.IO, System.Text, System.Linq, System.Globalization).
• System.Windows.Forms: Used by TDMParameterDlg (Form, SaveFileDialog, ErrorProvider, TableLayoutPanel, Button, TextBox, Label).

External Dependencies

• Settings: Relies on Properties.Settings1.Default.TDMFolder, DefaultStart, DefaultStop.
• File system: Requires write access to the output directory.

5. Gotchas

• Time unit confusion: TDMParameterDlg UI uses milliseconds, but File.Start/Stop and Writer.Start/Stop use seconds. Conversion is handled only in TDMParameterDlg's Start/Stop properties (divide ms by 1000).
• Rounding hack: Start/Stop are rounded to 3 decimal places in Writer.Write to mitigate floating-point precision issues from SLICE/TDAS download discrepancies. This may alter user-specified ranges slightly.
• Sample index calculation: ChannelHeader.WriteChannelHeaderToString computes sample indices using TriggerSampleNumbers[0] and StartRecordSampleNumber. If these values are inconsistent across modules, sample ranges may be misaligned.
• Device section underutilization: TestHeader.WriteDeviceSection writes dummies/barrriers/groups but often leaves many lines blank (e.g., dummies use only UserValue3 from first channel; barriers/groups are hardcoded to 0 count). This is noted as "not completely implemented equivalent to TDM".
• Squib channel handling: Squib voltage channels are skipped entirely in export. Squib channels (non-voltage) are included but with hardcoded capacity (10) and sensitivity (1).
• Min/max calculation: ChannelHeader.WriteChannelHeaderToString computes min/max over the requested start/end range. If the range extends beyond available data, IndexOutOfRangeException is caught and logged, but min/max may be incomplete.
• Encoding fallback: If DefaultEncoding is invalid, Encoding.Default is used silently (after logging), which may cause non-ASCII characters to be mangled.
• No-op Initialize: The Writer.Initialize method is present but empty. Any initialization logic must be done elsewhere (e.g., in Write).
• Hardcoded values: Several fields are hardcoded (e.g., impact speed/weight = 0, capacity for squib = 10, cable multiplier = 1, excitation for digital = 1V). These may not match all TDM variants.
• Filename construction: Output filename is Path.Combine(pathname, Test.Id), where pathname is treated as a directory. If pathname is a file path, behavior is undefined (likely creates nested path).