init

enriched-qwen3-coder-next/Common/DTS.Common.Serialization/Iso.md

@@ -0,0 +1,201 @@
+---
+source_files:
+  - Common/DTS.Common.Serialization/Iso/Iso.File.Test.ExtraProperty.cs
+  - Common/DTS.Common.Serialization/Iso/Iso.File.cs
+  - Common/DTS.Common.Serialization/Iso/Iso.File.Test.Object.cs
+  - Common/DTS.Common.Serialization/Iso/Iso.File.Test.cs
+generated_at: "2026-04-16T03:35:46.255556+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "353d00996507afad"
+---
+
+# Documentation: `DTS.Serialization.Iso.File` Module
+
+## 1. Purpose
+
+This module implements the ISO 14967-compliant serialization format for test data, specifically for crash test and impact testing scenarios. It provides structured representations of test metadata, test objects (e.g., dummies, barriers), channels (sensor data), and custom properties, enabling export of test results in a standardized text-based format. The module resides within the `DTS.Serialization.Iso` namespace and extends a base `Serialization.File` class, integrating with a proprietary test plan abstraction (`Common.ISO.TestPlan`) to populate ISO fields and delegate writing to a dedicated `Writer` class.
+
+## 2. Public Interface
+
+### `DTS.Serialization.Iso.File`
+
+- **`File(Common.ISO.TestPlan testplan)`**  
+  Constructor. Initializes a new ISO file instance with the provided test plan. Calls `base("ISO")`.
+
+- **`bool ExportSummaryReport { get; set; } = false`**  
+  Controls whether a summary report is included in the export.
+
+- **`bool UseZeroForUnfiltered { get; set; } = false`**  
+  When `true`, unfiltered channel data is exported as `0` instead of omitting it.
+
+- **`bool UseIsoCodeFilterMapping { get; set; }`**  
+  When `true`, the ISO code for a filter is determined by the software filter mapping for the channel.
+
+- **`bool FilteredExport { get; set; } = false`**  
+  Indicates whether the export is filtered.
+
+- **`bool ExportISOChannelName { get; set; } = false`**  
+  Controls whether the ISO channel name is exported.
+
+- **`void AddChannel(string dasserial, int moduleNumber, int number, string description, FilteredData data)`**  
+  Delegates to the exporter (`Writer`) to add a channel with the specified metadata and data.
+
+- **`void ApplyTestPlan(Serialization.Test test)`**  
+  Populates the `TestInstance` properties by iterating over `Common.ISO.TestPlan.IsoFields` enum values and mapping each to corresponding fields on `TestInstance`. Special handling includes:
+  - Parsing `Date` with fallback to `test.InceptionDate`.
+  - Converting `ExtraProperties` dictionary to `List<ExtraProperty>`.
+  - Using `"NOVALUE"` for null/empty values via `GetFieldString`.
+  - Throws `NotSupportedException` for unsupported fields.
+
+- **`IWriter<Serialization.Test> Exporter { get; }`**  
+  Lazily initializes and returns a `Writer` instance configured with current settings (`UseZeroForUnfiltered`, `UseIsoCodeFilterMapping`, etc.). Throws a wrapped `Exception` on failure.
+
+- **`Test TestInstance { get; }`**  
+  Returns the `Test` instance associated with this file. Initialized with a default `Test()`.
+
+- **`static string TestFileExtension { get; }`**  
+  Returns `".mme"` (file extension for serialized test data).
+
+- **`static string ChannelFileExtension { get; }`**  
+  Returns `".chn"` (file extension for serialized channel data).
+
+- **`Common.ISO.TestPlan GetTestPlan()`**  
+  Returns the `_testPlan` field passed at construction.
+
+### `DTS.Serialization.Iso.File.Test`
+
+- **`string DataFormatEditionNumber { get; set; }`**  
+  Default: `"1.6"`. Represents the ISO data format edition.
+
+- **`string LaboratoryName`, `LaboratoryContactName`, `LaboratoryContactPhone`, etc.**  
+  Standard ISO metadata fields (e.g., lab name, contact info, test reference numbers). All are `string` properties with associated label constants (e.g., `LaboratoryNameLabel = "Laboratory name"`).
+
+- **`string CustomerName`, `CustomerTestReferenceNumber`, `CustomerProjectReferenceNumber`, etc.**  
+  Customer-related metadata fields.
+
+- **`string TestEngineerName`, `TestEngineerPhone`, `TestEngineerFax`, `TestEngineerEmail`**  
+  Test engineer contact fields.
+
+- **`string Title { get; set; }`**  
+  Title of the test. If `null` or `"NOVALUE"`, defaults to `test.Id` in `ApplyTestPlan`.
+
+- **`string NumberOfMedia { get; set; }`**  
+  Default: `"1/1"`.
+
+- **`string Timestamp { get; set; }`**  
+  Default: current time in `"yyyy-MM-dd HH:mm:ss"` format.
+
+- **`string TestComment { get; set; }`**  
+  Comment field for the test.
+
+- **`string Type { get; set; }`**  
+  Type of the test.
+
+- **`DateTime Date { get; set; }`**  
+  Date of the test. Initialized to `DateTime.Now`.
+
+- **`string Subtype { get; set; }`**  
+  Subtype of the test.
+
+- **`string Regulation { get; set; }`**  
+  Regulatory framework.
+
+- **`string ReferenceTemperature { get; set; }`**  
+  Reference temperature.
+
+- **`string RelativeAirHumidity { get; set; }`**  
+  Relative air humidity.
+
+- **`int NumberOfTestObjects { get; }`**  
+  Returns `Objects.Count`.
+
+- **`List<Object> Objects { get; set; }`**  
+  List of test objects (e.g., dummies, barriers). Initialized to empty list.
+
+- **`List<Channel> Channels { get; set; }`**  
+  List of channels (defined in other files, not included here).
+
+- **`List<ExtraProperty> ExtraProperties { get; set; }`**  
+  List of custom key-value properties. Initialized to empty list.
+
+- **`string ToString()`**  
+  Generates the ISO header section of the test file, including all metadata fields and extra properties, formatted as `label: value` lines. Uses `GetFieldString` to handle uninitialized values as `"NOVALUE"`.
+
+### `DTS.Serialization.Iso.File.Test.ExtraProperty`
+
+- **`ExtraProperty(string key, string value)`**  
+  Constructor. Initializes `_Key` and `_Value` with provided values.
+
+- **`string Key { get; set; }`**  
+  Gets or sets the property key. Returns `null` if not initialized.
+
+- **`string Value { get; set; }`**  
+  Gets or sets the property value. Returns `null` if not initialized.
+
+### `DTS.Serialization.Iso.File.Test.Object`
+
+- **`string[] Comments { get; set; }`**  
+  Array of comment strings.
+
+- **`string Name`, `Type`, `Number`, `Velocity`, `Mass`, `Position`, `TestObjectImpactSide`, `Class`, `Code`, `Offset`, `BarrierWidth`, `BarrierHeight`, `YawAngle`, `ReferenceSystem`, `OriginX`, `OriginY`, `OriginZ`, `NumberOfLoadcells`**  
+  All are `string` properties with associated label constants (e.g., `NameLabel = "Name of test object #"`). Default values: `"0.0"` for `Velocity`, `""` for `Mass`, `"?"` for `Position`.
+
+- **`int MmeNumber { get; set; }`**  
+  Internal MME number for the object. Default: `-1`.
+
+- **`string TestObject { get; set; }`**  
+  Placeholder field (label: `"Test Object #"`).
+
+- **`List<ExtraProperty> ExtraProperties { get; set; }`**  
+  List of custom properties for this object. Initialized to empty list.
+
+- **`string ToString()`**  
+  Generates the ISO representation of the test object, including comments, metadata, and conditional barrier-specific fields (if `Type == "B"`). Uses `GetFieldString` for value extraction. Special handling for `Position` and `TestObjectImpactSide`: if not `"NOVALUE"` or empty, extracts substring before `'-'` (e.g., `"L-1"` → `"L"`).
+
+## 3. Invariants
+
+- **`NoValue` constant**: The string `"NOVALUE"` is used to represent missing or uninitialized field values in the output.
+- **Label formatting**: All labels are right-padded to `SeparatorOffset` (28 characters) before appending `Separator` (`":"`).
+- **`GetFieldString` behavior**: Returns `"NOVALUE"` if the extractor returns `null`, `string.Empty`, or throws an exception.
+- **`Property<T>` initialization**: All properties use `Property<T>` wrappers with unique keys (namespace-qualified), default values, and immutability flags (`true` for statics like `TestFileExtension`, `false` for instance fields).
+- **`ExtraProperties` handling**: In `ApplyTestPlan`, `ExtraProperties` from `TestPlan` (a dictionary) is converted to a list of `ExtraProperty` instances.
+- **`Date` parsing**: If `DateTime.TryParse` fails for `Date` field, falls back to `test.InceptionDate`.
+- **`Type == "B"` condition**: Barrier-specific fields (`BarrierWidth`, `OriginX`, etc.) are only included in `Object.ToString()` if `Type == "B"`.
+- **`Position`/`TestObjectImpactSide` substring extraction**: Only performed if value is not `"NOVALUE"` and not empty; uses `IndexOf('-') - 1` as end index.
+
+## 4. Dependencies
+
+- **Imports/Usings**:
+  - `DTS.Common.Utilities` and `DTS.Common.Utilities.DotNetProgrammingConstructs` (for `Property<T>`, `Exceptional` base class).
+  - `DTS.Serialization.Iso.Report` (for `IWritable<Test>` and `IWriter<Test>`).
+  - `System`, `System.Collections.Generic`, `System.Linq`, `System.Text`, `System.Threading.Tasks`.
+
+- **Key Dependencies**:
+  - `Common.ISO.TestPlan`: Provides test metadata via `GetField(IsoFields)` and `ExtraProperties` dictionary.
+  - `Serialization.File`: Base class for file serialization.
+  - `IWritable<Test>`: Interface implemented by `File`.
+  - `IWriter<Test>`: Writer interface (implemented by `Writer` class, instantiated in `Exporter`).
+  - `FilteredData`: Type for channel data (used in `AddChannel`).
+
+- **Depended Upon**:
+  - `Writer` class (inferred from `Exporter` property and `AddChannel` method).
+  - Likely consumed by higher-level serialization logic (e.g., export UI or batch processor).
+
+## 5. Gotchas
+
+- **Substring index risk in `Object.ToString()`**: The `Position` and `TestObjectImpactSide` substring extraction (`Substring(0, IndexOf('-') - 1)`) will throw `ArgumentOutOfRangeException` if the value contains no `'-'` or if `'-'` is at index `0` or `1`. This is not guarded against in the source.
+  
+- **`Timestamp` default is non-deterministic**: `Timestamp` defaults to `DateTime.Now`, which may cause non-reproducible exports if not explicitly set.
+
+- **`ExtraProperties` key collision**: If `ExtraProperties` from `TestPlan` contains duplicate keys, the last one wins in the list (no explicit deduplication).
+
+- **`TestInstance` is lazily initialized but not thread-safe**: The `TestInstance` property returns a shared instance; concurrent modifications could cause race conditions.
+
+- **`NoValue` is hardcoded**: `"NOVALUE"` is used as a sentinel, but there is no validation to prevent user data from accidentally using this string.
+
+- **`ApplyTestPlan` throws `NotSupportedException`**: Any unhandled `IsoFields` enum value causes a hard failure. This may break if the enum is extended.
+
+- **`Property<T>` null handling**: Properties with `IsValueInitialized == false` return `null` for reference types (e.g., `string`, `List<T>`), but `GetFieldString` treats `null` as `"NOVALUE"`. This is consistent but requires care when checking for presence.
+
+- **No explicit validation**: No validation is performed on field values (e.g., `Velocity` is a string but expected to be numeric; `Position` codes like `"L-1"` are parsed but not validated).