init
This commit is contained in:
240
docs/ai/Common/DTS.Common.Serialization/SliceRaw.md
Normal file
240
docs/ai/Common/DTS.Common.Serialization/SliceRaw.md
Normal file
@@ -0,0 +1,240 @@
|
||||
---
|
||||
source_files:
|
||||
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.IDasTimestampHeader.cs
|
||||
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.Reader.BadCrcException.cs
|
||||
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.Reader.MissingFileException.cs
|
||||
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.Reader.TooManyFilesException.cs
|
||||
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.PersistentChannel.NotInitializedException.cs
|
||||
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.PersistentChannel.IsInitializingException.cs
|
||||
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.PersistentChannel.DataTooBigForArrayException.cs
|
||||
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.PersistentChannel.AlreadyInitializedException.cs
|
||||
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.PersistentChannel.DependencyNotInitializedException.cs
|
||||
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.BinaryDasTimestampHeader.cs
|
||||
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.PersistentEuChannel.cs
|
||||
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.IChannelHeader.cs
|
||||
- Common/DTS.Common.Serialization/SliceRaw/ModifyChannel.cs
|
||||
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.BinaryChannelHeader.cs
|
||||
generated_at: "2026-04-17T15:27:55.460417+00:00"
|
||||
model: "zai-org/GLM-5-FP8"
|
||||
schema_version: 1
|
||||
sha256: "433e54278b633cd4"
|
||||
---
|
||||
|
||||
# DTS.Serialization.SliceRaw Module Documentation
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This module provides serialization support for the SliceRaw binary file format used by Diversified Technical Systems' data acquisition systems. It defines header structures, exception types, and data access patterns for reading and writing binary channel data files (`.chn` files). The module handles timestamp headers, channel headers with calibration metadata, and provides a persistent channel abstraction for accessing large sample datasets without loading them entirely into memory.
|
||||
|
||||
---
|
||||
|
||||
## 2. Public Interface
|
||||
|
||||
### Interfaces
|
||||
|
||||
#### `IDasTimestampHeader`
|
||||
Defines the contract for timestamp header data in binary files.
|
||||
|
||||
| Property | Type | Access | Description |
|
||||
|----------|------|--------|-------------|
|
||||
| `MagicKey` | `uint` | get/set | Relatively-unique identifier for the binary file type |
|
||||
| `HeaderVersionNumber` | `uint` | get/set | Version number of the header format |
|
||||
| `OffsetOfSampleDataStart` | `ulong` | get/set | Byte offset where sample data begins |
|
||||
| `NumberOfSamples` | `ulong` | get/set | Total count of samples in the file |
|
||||
| `NumberOfBitsPerSample` | `uint` | get/set | Bit depth per sample |
|
||||
| `Crc32` | `uint` | get | CRC value for current header state |
|
||||
|
||||
#### `IChannelHeader`
|
||||
Defines the contract for channel header data with extensive calibration and diagnostic metadata.
|
||||
|
||||
| Property | Type | Access | Description |
|
||||
|----------|------|--------|-------------|
|
||||
| `MagicKey` | `uint` | get/set | File type identifier |
|
||||
| `HeaderVersionNumber` | `uint` | get/set | Header format version |
|
||||
| `OffsetOfSampleDataStart` | `ulong` | get/set | Byte offset to sample data |
|
||||
| `NumberOfSamples` | `ulong` | get/set | Sample count |
|
||||
| `NumberOfBitsPerSample` | `uint` | get/set | Bits per sample |
|
||||
| `AreSamplesSigned` | `uint` | get/set | Signed sample indicator |
|
||||
| `SampleRate` | `double` | get/set | Sample rate in Hz |
|
||||
| `NumberOfTriggers` | `ushort` | get/set | Trigger count |
|
||||
| `TriggerSampleNumbers` | `ulong[]` | get/set | Array of trigger sample indices |
|
||||
| `PreTestZeroLevelCounts` | `int` | get/set | Pre-test zero level ADC counts |
|
||||
| `RemovedADC` | `int` | get/set | ADC offset removed during hardware zeroing |
|
||||
| `Excitation` | `double` | get/set | Excitation voltage |
|
||||
| `ZeroMvInADC` | `int` | get/set | ADC value for 0mV injected signal |
|
||||
| `WindowAverageADC` | `int` | get/set | Average ADC over zero window |
|
||||
| `OriginalOffsetADC` | `int` | get/set | Initial offset in ADC |
|
||||
| `TriggerAdjustmentSamples` | `int` | get/set | Samples for trigger qualification |
|
||||
| `PreTestDiagnosticsLevelCounts` | `int` | get/set | Pre-test diagnostic level |
|
||||
| `PreTestNoisePercentageOfFullScale` | `double` | get/set | Pre-test noise percentage |
|
||||
| `PostTestZeroLevelCounts` | `int` | get/set | Post-test zero level counts |
|
||||
| `PostTestDiagnosticsLevelCounts` | `int` | get/set | Post-test diagnostic level |
|
||||
| `DataZeroLevelCounts` | `int` | get/set | Data zero level counts |
|
||||
| `ScaleFactorMv` | `double` | get/set | Millivolt scale factor |
|
||||
| `MvPerEu` | `double` | get/set | Sensitivity in mV/EU |
|
||||
| `EuFieldLengthWithTerminator` | `ushort` | get/set | EU field length including terminator |
|
||||
| `EngineeringUnit` | `char[]` | get/set | Engineering unit string |
|
||||
| `IsoCode` | `char[]` | get/set | ISO code string |
|
||||
| `Crc32` | `uint` | get | CRC for current header state |
|
||||
|
||||
---
|
||||
|
||||
### Classes
|
||||
|
||||
#### `File.BinaryDasTimestampHeader`
|
||||
Implementation of `IDasTimestampHeader`.
|
||||
|
||||
**Static Properties:**
|
||||
- `RequiredMagicKey` → `0xF15363C2`
|
||||
- `CurrentVersionNumber` → `0x01`
|
||||
- `KnownHeaderVersionNumbers` → `List<uint>` containing `{ 0x01 }`
|
||||
|
||||
**CRC Calculation:** Uses CRC16 algorithm via `Utils.Math_DoCRC16Step()`.
|
||||
|
||||
---
|
||||
|
||||
#### `File.BinaryChannelHeader`
|
||||
Implementation of `IChannelHeader`.
|
||||
|
||||
**Static Properties:**
|
||||
- `RequiredMagicKey` → `0x2C36351F`
|
||||
- `CurrentVersionNumber` → `0x04`
|
||||
- `KnownHeaderVersionNumbers` → `List<uint>` containing `{ 0x01, 0x02, 0x03, 0x04 }`
|
||||
|
||||
**CRC Properties:**
|
||||
- `Crc32` - Standard CRC with EU padding preserved
|
||||
- `UnpaddedEuCrc32` - CRC with EU string padding stripped
|
||||
- `UnpaddedEuStringPaddedEuLengthCrc32` - CRC with unpadded EU string but padded EU length
|
||||
|
||||
**Version-Conditional Fields:**
|
||||
- `RemovedADC` included for `HeaderVersionNumber >= 2`
|
||||
- `Excitation`, `TriggerAdjustmentSamples`, `ZeroMvInADC`, `OriginalOffsetADC` included for `HeaderVersionNumber >= 3`
|
||||
- `WindowAverageADC` included for `HeaderVersionNumber >= 4`
|
||||
|
||||
---
|
||||
|
||||
#### `File.PersistentEuChannel`
|
||||
Wrapper class that converts ADC values to Engineering Units on-demand. Inherits from `ExceptionalList<double>`.
|
||||
|
||||
**Constructor:**
|
||||
```csharp
|
||||
public PersistentEuChannel(PersistentChannel persistentChannel, DataScaler scaler)
|
||||
```
|
||||
|
||||
**Properties:**
|
||||
| Property | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `BasePersistentChannel` | `PersistentChannel` | The wrapped channel providing raw ADC data |
|
||||
| `EuDataScaler` | `DataScaler` | Conversion scaler from ADC to EU |
|
||||
| `Length` | `long` | Length of the channel data |
|
||||
|
||||
**Indexer:**
|
||||
```csharp
|
||||
public double this[ulong i] { get; } // Read-only, applies EU conversion
|
||||
```
|
||||
|
||||
**Methods:**
|
||||
- `void Dispose()` - Disposes the base persistent channel
|
||||
|
||||
---
|
||||
|
||||
#### `ModifyChannel`
|
||||
Windows Forms dialog for editing channel header metadata.
|
||||
|
||||
**Properties:**
|
||||
```csharp
|
||||
public File.PersistentChannel ChannelToModify { set; }
|
||||
```
|
||||
|
||||
**Key UI Event Handlers:**
|
||||
- `btnBrowse_Click` - Opens file dialog to select `.chn` file
|
||||
- `btnWrite_Click` - Applies edits and calls `StampCrc()` on the channel
|
||||
- `c1Button2_Click` - Cancels and closes dialog
|
||||
|
||||
---
|
||||
|
||||
### Exception Classes
|
||||
|
||||
All exception classes follow standard .NET exception patterns with three constructors:
|
||||
1. Default constructor
|
||||
2. Message constructor
|
||||
3. Message + inner exception constructor
|
||||
|
||||
#### `File.Reader.BadCrcException`
|
||||
Thrown when CRC validation fails during file reading. Inherits from `Exception`.
|
||||
|
||||
#### `File.Reader.MissingFileException`
|
||||
Thrown when a required file is not found. Inherits from `Exception`.
|
||||
|
||||
#### `File.Reader.TooManyFilesException`
|
||||
Thrown when file count exceeds expected limits. Inherits from `Exception`.
|
||||
|
||||
#### `File.PersistentChannel.NotInitializedException`
|
||||
Thrown when accessing a property before initialization. Inherits from `ApplicationException`.
|
||||
|
||||
#### `File.PersistentChannel.IsInitializingException`
|
||||
Thrown when accessing a property while the channel is still being initialized. Inherits from `ApplicationException`.
|
||||
|
||||
#### `File.PersistentChannel.DataTooBigForArrayException`
|
||||
Thrown when attempting to convert a dataset too large for a .NET array. Inherits from `ApplicationException`.
|
||||
|
||||
#### `File.PersistentChannel.AlreadyInitializedException`
|
||||
Thrown when attempting to set a property that has set-once behavior after initialization. Inherits from `ApplicationException`.
|
||||
|
||||
#### `File.PersistentChannel.DependencyNotInitializedException`
|
||||
Thrown when accessing a property whose dependency has not been initialized. Inherits from `ApplicationException`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Invariants
|
||||
|
||||
1. **Magic Key Validation:** `BinaryDasTimestampHeader` requires `MagicKey == 0xF15363C2`. `BinaryChannelHeader` requires `MagicKey == 0x2C36351F`.
|
||||
|
||||
2. **Version Compatibility:** `BinaryChannelHeader` only supports header versions 1-4. Unknown versions may cause undefined behavior during CRC calculation.
|
||||
|
||||
3. **CRC Algorithm:** All CRC calculations use CRC16 (not CRC32 as property names suggest), initialized with `0xFFFF` and processed 16 bits at a time.
|
||||
|
||||
4. **Word Alignment:** CRC data is padded to even byte count for DIAdem `.dat` file compatibility.
|
||||
|
||||
5. **Set-Once Behavior:** `PersistentChannel` properties exhibit set-once behavior; re-initialization throws `AlreadyInitializedException`.
|
||||
|
||||
6. **Read-Only EU Indexer:** `PersistentEuChannel[ulong i]` setter throws `NotSupportedException`.
|
||||
|
||||
7. **EU String Padding:** Engineering Unit strings are padded to even length for CRC calculation when `stripEuPadding` is false.
|
||||
|
||||
---
|
||||
|
||||
## 4. Dependencies
|
||||
|
||||
### External Dependencies (from imports):
|
||||
- `System` - Core .NET types
|
||||
- `System.Collections.Generic` - `List<T>` for data collection
|
||||
- `System.Text` - `Encoding.UTF8` for EU string encoding
|
||||
- `System.Windows.Forms` - UI components for `ModifyChannel`
|
||||
- `DTS.Common.Utilities` - `Exceptional` base class, utility functions
|
||||
- `DTS.Common.Utilities.Logging` - `APILogger` for logging
|
||||
- `DTS.Common.Utils` - `Utils.Math_DoCRC16Step()` for CRC calculation
|
||||
- `DTS.Common.DAS.Concepts` - `DataScaler` for EU conversion
|
||||
- `DTS.Common.Utilities.DotNetProgrammingConstructs` - `Property<T>` wrapper class
|
||||
|
||||
### Internal Dependencies:
|
||||
- `File.PersistentChannel` is referenced by `PersistentEuChannel` and `ModifyChannel` but its full implementation is not provided in the source files.
|
||||
- `File.Reader` is referenced by exception classes but its implementation is not provided.
|
||||
|
||||
---
|
||||
|
||||
## 5. Gotchas
|
||||
|
||||
1. **Misleading CRC Property Name:** Properties named `Crc32` actually compute a **CRC16** value (initialized to `0xFFFF`, processed 16 bits at a time). The method name and comments reference "CRC 32" but the implementation is CRC16.
|
||||
|
||||
2. **EU Field Length Bug Handling:** `BinaryChannelHeader.CalculateCrc32()` contains special handling for a historical bug where `EuFieldLengthWithTerminator` was set to `length + 1` incorrectly. The `plusOneFieldLengthBugErrorPresent` flag accommodates this.
|
||||
|
||||
3. **Duplicate Data in CRC Calculation:** In `BinaryChannelHeader.CalculateCrc32()`, `NumberOfSamples` is added to the CRC data twice (lines appear to be duplicated).
|
||||
|
||||
4. **Partial Class Structure:** Many classes are defined across multiple files using `partial class`. The complete implementation requires files not provided here (e.g., `SliceRaw.File.cs`, `SliceRaw.File.PersistentChannel.cs`, `SliceRaw.File.Reader.cs`).
|
||||
|
||||
5. **Version-Dependent Header Fields:** When reading older format files, fields like `RemovedADC`, `Excitation`, `TriggerAdjustmentSamples`, `ZeroMvInADC`, `OriginalOffsetADC`, and `WindowAverageADC` may not be present depending on `HeaderVersionNumber`.
|
||||
|
||||
6. **ModifyChannel Creates Backup:** The `btnBrowse_Click` method automatically creates a `.BAK` file when opening a channel, but silently deletes any existing backup without warning.
|
||||
|
||||
7. **Hardcoded Data Directory:** `ModifyChannel` defaults to a `DATA` subdirectory relative to `Environment.CurrentDirectory`.
|
||||
Reference in New Issue
Block a user