DP44/docs/ai/Common/DTS.Common.Serialization/TDM.md

---
source_files:
  - 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
generated_at: "2026-04-17T15:34:32.846343+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "0fe61a89fffa2819"
---

# TDM Serialization Module Documentation

## 1. Purpose

This module provides TDM (Test Data Management) CSV export functionality for test data objects. It serializes `Test` objects into a legacy CSV format compatible with TDM, THF, and TEMA analysis systems. The module handles the complete export pipeline including test headers, channel headers, and channel data, with support for time range selection, subsampling, and optional data filtering. A Windows Forms dialog (`TDMParameterDlg`) provides user configuration for export parameters.

---

## 2. Public Interface

### `DTS.Serialization.TDM.File`

A file type definition for TDM exports, inheriting from `Serialization.File` and implementing `IWritable<Test>`.

| Member | Signature | Description |
|--------|-----------|-------------|
| Constructor | `File()` | Initializes with format name "TDM CFC1000" |
| `Exporter` | `IWriter<Test>` (get) | Lazy-initializes and returns a `Writer` instance, configuring it with `Start` and `Stop` values |
| `Start` | `double` (get/set) | Export start time in seconds |
| `Stop` | `double` (get/set) | Export stop time in seconds |

### `DTS.Serialization.TDM.TDMParameterDlg`

A Windows Forms dialog for collecting TDM export parameters from the user.

| Member | Signature | Description |
|--------|-----------|-------------|
| Constructor | `TDMParameterDlg(string testName, double testStart, double testEnd)` | Initializes dialog with test name and valid time bounds; sets default file path and populates start/stop fields from settings or test bounds |
| `FileName` | `string` (get) | Returns the user-selected output file path |
| `Start` | `double` (get) | Returns start time in seconds (divides textbox value by 1000) |
| `Stop` | `double` (get) | Returns stop time in seconds (divides textbox value by 1000) |

### `DTS.Serialization.TDM.Writer`

Handles the actual serialization of `Test` objects to TDM CSV format.

| Member | Signature | Description |
|--------|-----------|-------------|
| `AllowTTSExportFiltering` | `bool` (get/set) | Enables/disables filtered data export; default `false` |
| `Start` | `double` (get/set) | Export start time |
| `Stop` | `double` (get/set) | Export stop time |
| `FilteredData` | `List<FilteredData>` (get/set) | Filtered channel data for export |
| `Test` | `Test` (get/set) | The test object being exported |
| `IncrementLevel` | `ulong` (get) | Calculated tick increment for progress reporting |
| `SubSampleInterval` | `ushort` (get/set) | Subsampling interval; default behavior uses 1 |
| `ExtensionPrefix` | `string` (get/set) | Optional prefix for output filename |
| `Write` | `void Write(string pathname, string id, Test target, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)` | **Throws `NotSupportedException`** |
| `Write` | `void Write(string pathname, string id, string dataFolder, Test target, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler onBeginEvent, CancelEventHandler onCancelEvent, EndEventHandler onEndEvent, TickEventHandler onTickEvent, ErrorEventHandler onErrorEvent, CancelRequested cancelRequested, double minStartTime, int dataCollectionLength)` | Main export method; rounds `Start`/`Stop` to 3 decimal places, calculates progress increments, invokes begin event, and calls `DoExport` |
| `Initialize` | `void Initialize(...)` | Empty implementation (no-op) |
| `IncrementDone` | `void IncrementDone(double amount)` | Invokes the tick event handler with progress amount |

### `DTS.Serialization.TDM.TestHeader`

Writes the test header section of the TDM CSV file.

| Member | Signature | Description |
|--------|-----------|-------------|
| `WriteTestHeader` | `void WriteTestHeader(Writer writer, System.IO.TextWriter tw, bool bFiltered, ushort subSampleInterval, ulong numSamples, int preTriggerSamples)` | Writes test metadata including ID, impact data, timestamps, device sections, sample counts, and channel count |

**Constants:**
- `MAX_TESTDEVICES = 1000`
- `MAX_DUMMY_DISPLAY = 16`
- `MAX_BARRIER_DISPLAY = 3`
- `MAX_GROUP_DISPLAY = 20`
- `MAX_DEVICE_DISPLAY = 40` (sum of above + 1)
- `DEV_TYPE_DUMMY = 'D'`, `DEV_TYPE_BARRIER = 'B'`, `DEV_TYPE_GROUP = 'G'`, `DEV_TYPE_UNDEFINED = 'U'`
- `MAX_DEVICE_LINES = 23`
- `MAX_OLD_GROUP_LINES = 4`

### `DTS.Serialization.TDM.ChannelHeader`

Writes the channel header section of the TDM CSV file.

| Member | Signature | Description |
|--------|-----------|-------------|
| `WriteChannelHeaderToString` | `void WriteChannelHeaderToString(Writer writer, System.IO.TextWriter tw, bool bFiltered, double start, double end)` | Writes 15 header lines per channel including DAS name, capacity, units, serial number, sensitivity, excitation, min/max values, Toyota calc fields, filter frequency, data flags, and channel codes |

**Constants (line indices):**
- `DAS_LINE = 0`, `CAPACITY_LINE = 1`, `EU_LINE = 2`, `SENSOR_SN_LINE = 3`
- `SENSITIVITY_LINE = 4`, `EXCITATION_LINE = 5`, `MIN_LINE = 6`, `MAX_LINE = 7`
- `TOYOTA_CALC1_LINE = 8`, `TOYOTA_CALC2_LINE = 9`, `TOYOTA_CALC3_LINE = 10`
- `KNEE_POINT_LINE = 11`, `STRANGE_DATA_FLAG_LINE = 12`
- `CHANNEL_CODE_LINE = 13`, `CHANNEL_JCODE_LINE = 14`

---

## 3. Invariants

1. **Time ordering**: `Start` must be less than `Stop` (validated in `TDMParameterDlg.btnOK_Click`)

2. **Time bounds**: User-selected start/stop must fall within the test's actual data range (`_min` to `_max`)

3. **Pre-trigger samples**: Must be between `0` and `numSamples` (clamped in `WriteTestHeader`)

4. **Time precision**: `Start` and `Stop` are rounded to 3 decimal places (milliseconds) in `Writer.Write` to handle floating-point precision issues

5. **Channel exclusion**: Squib voltage channels (detected via `IsSquibVoltage()`) are excluded from the channel count in the test header

6. **Modules without channels**: Modules with zero channels are skipped during test header processing (e.g., Slice6DB modules for temperature storage)

---

## 4. Dependencies

### This module depends on:
- `System.Windows.Forms` - For `TDMParameterDlg` UI components
- `DTS.Common.DAS.Concepts` - For `Test`, `Test.Module.Channel`, `Test.Module.AnalogInputChannel`, `DataScaler`
- `DTS.Common.Utilities.Logging` - For `APILogger.Log`
- `DTS.Common.Enums.Sensors` - For `ChannelFilter` enum and `SensorConstants`
- `DTS.Common.Utilities` - For `DescriptionAttributeCoder<T>`
- `DTS.Serialization` (inferred) - For base class `Serialization.File`, `Serialization.File.Writer<File>`, interfaces `IWriter<Test>`, event handlers (`BeginEventHandler`, `EndEventHandler`, `TickEventHandler`, `CancelEventHandler`, `ErrorEventHandler`, `CancelRequested`)
- `Properties.Settings1` - For user settings (TDMFolder, DefaultStart, DefaultStop)

### What depends on this module:
- Unclear from source alone; the module exposes `IWriter<Test>` suggesting consumers use the interface to trigger exports

---

## 5. Gotchas

1. **Unsupported Write overload**: The 7-parameter `Write` method throws `NotSupportedException` with message "TDM::Writer Write(pathname, id, test, bFiltering) not supported". Callers must use the 16-parameter overload.

2. **Floating-point precision workaround**: `Start` and `Stop` are rounded to 3 decimal places in `Writer.Write`. The source comments indicate this is a "hack" to reconcile differences between TDAS and SLICE download models regarding trigger sample handling.

3. **Unit conversion in dialog**: `TDMParameterDlg` displays and accepts times in milliseconds (multiplies by 1000 on display, divides by 1000 on retrieval), but the `File` and `Writer` classes work in seconds.

4. **Progress tick limitations**: The progress reporting logic in `Writer.Write` notes that the dataform expects a uint and can only handle single tick progress updates. `IncrementLevel` is calculated to work around this for large sample counts.

5. **Incomplete device section implementation**: `TestHeader.WriteDeviceSection` has a comment noting that barriers and groups are written with blank lines, and the implementation is "not completely implemented equivalent to TDM" for these device types.

6. **Hardcoded values**:
   - Squib channel capacity is hardcoded to `10`
   - Squib excitation voltage is hardcoded to `5D`
   - Digital excitation is hardcoded to `1D`
   - Toyota Calc 1 (cable multiplier) is hardcoded to `1`
   - Toyota Calc 2 and 3 are hardcoded to `0`

7. **Empty Initialize method**: `Writer.Initialize` is implemented but does nothing, which may indicate incomplete refactoring or an unused interface requirement.