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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-17T15:27:55.460417+00:00	zai-org/GLM-5-FP8	1	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:

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:

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:

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.