noisedestroyers/DP44
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bc3ac1d4c9bfb56c00ec892a5a321bb0e5dcc55d
DP44/enriched-qwen3-coder-next/Common/DTS.Common.Serialization/Control/Event/Module/Channel.md
noisedestroyers bc3ac1d4c9 init
2026-04-17 14:55:32 -04:00

14 KiB
Raw Blame History

source_files, generated_at, model, schema_version, sha256
source_files generated_at model schema_version sha256
Common/DTS.Common.Serialization/Control/Event/Module/Channel/DataValues.cs
Common/DTS.Common.Serialization/Control/Event/Module/Channel/ReviewableAttribute.NotApplicableException.cs
Common/DTS.Common.Serialization/Control/Event/Module/Channel/Filter.cs
Common/DTS.Common.Serialization/Control/Event/Module/Channel/ChannelDefaultSaeJ211Filter.cs
Common/DTS.Common.Serialization/Control/Event/Module/Channel/CalculatedChannel.cs
Common/DTS.Common.Serialization/Control/Event/Module/Channel/SaeJ211Filter.cs
2026-04-16T03:42:34.925173+00:00 Qwen/Qwen3-Coder-Next-FP8 1 2400faf1f9897d63

Documentation: DTS.Slice.Control.Event.Module.Channel Subsystem

1. Purpose

This module provides core data structures and abstractions for representing and manipulating channel data within event recordings in the DTS Slice Control system. It defines the foundational types for physical channels, calculated channels, filters (including SAE J211–compliant filters), and data storage mechanisms (in-memory vs. memory-mapped). The subsystem enables filtering, unit conversion, and serialization of channel data, supporting both raw sensor inputs (ADC) and derived quantities (EU, mV), as well as computed channels (e.g., integrals, derivatives, FFTs). It serves as the data model layer for event analysis and review workflows.

2. Public Interface

DataValues class

Defined in: Common/DTS.Common.Serialization/Control/Event/Module/Channel/DataValues.cs

  • DataValues()
    Initializes a DataValues instance using in-memory storage (i.e., UseMemoryMappedFile = false).

  • DataValues(bool useMemoryMappedFile)
    Initializes a DataValues instance. If useMemoryMappedFile is true, the instance is configured to use memory-mapped files for data storage (intended for large datasets exceeding process memory limits).

  • UseMemoryMappedFile: bool
    Property controlling whether the instance uses memory-mapped files (true) or in-memory storage (false). Implemented via a Property<bool> wrapper.

Filter abstract class

Defined in: Common/DTS.Common.Serialization/Control/Event/Module/Channel/Filter.cs

  • Name: string (abstract)
    Returns a descriptive name for the filter (e.g., "6G" for a 6g filter, or "123.45Hz" for ad hoc).

  • IsCfc: bool (abstract)
    Returns true if the filter corresponds to a defined CFC (Channel Filter Classification) value; false for Unfiltered or AdHoc.

  • Type: ChannelFilter (abstract)
    Returns the canonical ChannelFilter enum value representing the filter (e.g., ChannelFilter.SixG, ChannelFilter.AdHoc).

  • CutoffFrequencyHz: double (abstract)
    Returns the filter’s cutoff frequency in hertz.

  • Apply(Channel input, DataDisplayUnits displayUnits, bool bUseLegacyTDCSoftwareFilterAdjustment): double[] (abstract)
    Applies the filter to the unfiltered data of the specified input channel, returning filtered data in the requested displayUnits (ADC, EU, or mV). The bUseLegacyTDCSoftwareFilterAdjustment flag controls whether a one-sample phase shift is applied to match legacy TDC behavior (see issue #8747).

  • Apply(double[] data, double sampleRate, bool bUseLegacyTDCSoftwareFilterAdjustment): double[] (abstract)
    Applies the filter to a raw data array with known sampleRate, returning filtered data. Used when channel context is unavailable.

  • ToBaseString(): string (abstract)
    Returns the filter’s base name (e.g., "6G"), without any decorative prefix (e.g., "Default (6G)"). Distinct from ToString().

SaeJ211Filter class

Defined in: Common/DTS.Common.Serialization/Control/Event/Module/Channel/SaeJ211Filter.cs

  • SaeJ211Filter(ChannelFilter originalType)
    Initializes a filter for a CFC-compliant type (e.g., ChannelFilter.SixG). Throws Exception if originalType == ChannelFilter.AdHoc.

  • SaeJ211Filter(double cutoffFrequencyHz)
    Initializes an ad hoc filter with the specified cutoff frequency.

  • SaeJ211Filter(SaeJ211Filter originalFilter)
    Copy constructor.

  • OriginalType: ChannelFilter
    Stores the original filter type passed at construction (e.g., AdHoc for ad hoc filters). Not modifiable after construction.

  • Type: ChannelFilter (override)
    Returns the effective filter type: if OriginalType == AdHoc, resolves to the nearest matching CFC (or AdHoc if no match); otherwise returns OriginalType.

  • IsCfc: bool (override)
    Returns true if Type is neither Unfiltered nor AdHoc.

  • CutoffFrequencyHz: double (override)
    Returns the cutoff frequency in Hz (derived from OriginalType or explicitly set for ad hoc filters).

  • IsoDescription: char
    Returns the first character of the ISO description for OriginalType (e.g., 'G' for SixG).

  • Name: string (override)
    Returns a human-readable name:

    • For AdHoc: "123.45Hz"
    • For CFC types: description from DescriptionAttributeCoder<ChannelFilter> (e.g., "6G").

  • Apply(...) (override)
    Implements filtering using FilterUtility. Supports filtering from UnfilteredData, UnfilteredDataEu, or UnfilteredDataMv depending on displayUnits. Logs warnings for invalid data via APILogger.

  • Parse(string serialization): Filter (static)
    Parses a serialized filter string (e.g., "6G", "123.45Hz") into a Filter instance. Falls back to Unfiltered on parse failure.

  • Equals(object obj): bool (override)
    Case-insensitive comparison of filter names.

  • GetHashCode(): int (override)
    Hash code based on lowercase filter name.

  • ToString(): string (override)
    Returns Name.

  • ToBaseString(): string (override)
    Returns Name.

DefaultSaeJ211Filter class

Defined in: Common/DTS.Common.Serialization/Control/Event/Module/Channel/ChannelDefaultSaeJ211Filter.cs

  • DefaultSaeJ211Filter(SaeJ211Filter filter)
    Copy constructor.

  • DefaultSaeJ211Filter(ChannelFilter filterType)
    Initializes with a CFC filter type.

  • DefaultSaeJ211Filter(double adHocFrequency)
    Initializes with an ad hoc frequency.

  • Name: string (override)
    Returns "Default (" + base.Name + ")" (e.g., "Default (6G)").

  • ToBaseString(): string (override)
    Returns base.Name (e.g., "6G").

  • ToString(): string (override)
    Returns Name.

CalculatedChannel abstract class

Defined in: Common/DTS.Common.Serialization/Control/Event/Module/Channel/CalculatedChannel.cs

  • Operation enum
    Defines supported calculations: Integral, Derivative, HeadInjuryCriteria, FFT, ImportedCSV, Resultant, TSR, Scale, Offset, Sine, Cosine.

  • CalculationType: Operation
    Returns the operation performed by this channel.

  • X: double[], Y: double[]
    Read-only arrays of x-axis and y-axis data points.

  • XAxis: XUnits
    X-axis unit type (msec, sec, Hz, samples).

  • XUnitsString: string
    Human-readable unit string (e.g., "ms", "Hz").

  • EngineeringUnits: string
    Y-axis engineering units (e.g., "g", "m/s").

  • SupportsADC: bool (override)
    Always false for calculated channels.

  • SupportsEU: bool (override)
    Always true.

  • SupportsmV: bool (override)
    Always false.

  • ActualMaxRangeEu, ActualMinRangeEu, DataMaxEu, DataMinEu, DataRangeEu, DataHalfRangeValueEu (overrides)
    Computed from Y data (e.g., DataMaxEu = _y.Max()).

  • IsConfigured: bool (override)
    Always true; setting throws NotSupportedException.

  • GetUnfilteredDataEu(): List<double> (override)
    Returns a copy of Y.

  • Constructors

    • CalculatedChannel(string name, XUnits xAxis, string yAxis, double[] xValues, double[] yValues, Operation calcType, int number, Module parentModule)
      Initializes with data, axis labels, and calculation type. Sets CurrentFilter to DefaultSaeJ211Filter(ChannelFilter.Unfiltered).

  • ToString(): string (override)
    Returns ChannelDescriptionString or "N/A".

Derived CalculatedChannel classes

Defined in: Common/DTS.Common.Serialization/Control/Event/Module/Channel/CalculatedChannel.cs

  • FFTCalculatedChannel

    • PeakFrequency: double
      Returns the peak frequency from the FFT.

  • IntegralCalculatedChannel, DerivativeCalculatedChannel, ScaleCalculatedChannel, OffsetCalculatedChannel, ResultantCalculatedChannel, AdditiveVectorCalculatedChannel, SineCalculatedChannel, CosineCalculatedChannel
    All inherit from CalculatedChannel with no additional public members.

Note

: HICCalculatedChannel is commented out in source and not documented.

ReviewableAttribute.NotApplicableException class

Defined in: Common/DTS.Common.Serialization/Control/Event/Module/Channel/ReviewableAttribute.NotApplicableException.cs

  • NotApplicableException()
    Default constructor.

  • NotApplicableException(string msg)
    Constructor with message.

  • NotApplicableException(string msg, Exception innerEx)
    Constructor with message and inner exception.

Inherits from ApplicationException.

3. Invariants

  • DataValues.UseMemoryMappedFile
    Once set during construction, this flag determines the storage strategy for channel data. No runtime switching is exposed.

  • SaeJ211Filter.OriginalType
    Immutable after construction. Type may differ from OriginalType for ad hoc filters (resolved to nearest CFC or AdHoc).

  • Filter.Type
    For ad hoc filters (OriginalType == AdHoc), Type is computed dynamically based on CutoffFrequencyHz (via ConvertFrequencyToChannelFilter). If frequency matches a CFC enum value, Type becomes that CFC; otherwise remains AdHoc.

  • CalculatedChannel properties

    • SupportsADC and SupportsmV are always false; SupportsEU is always true.
    • Range properties (ActualMaxRangeEu, etc.) are derived from Y data and may change if Y is modified (though Y is read-only via public API).

  • Filter.Apply(...)
    Filtering always uses FilterUtility with Cfc = Type, AdHocFrequency = CutoffFrequencyHz, and SampleRate from channel or parameter. Invalid data triggers logging and exception.

  • Filter.Parse(...)
    Returns Unfiltered filter on parse failure (not null).

4. Dependencies

Internal Dependencies (from source)

  • DTS.Common.Utilities
    Used for Property<T>, logging (APILogger), and encoding utilities (CfcValueAttributeCoder, DescriptionAttributeCoder, IsoDescriptionAttributeCoder).

  • DTS.Slice.Control.DAS.Channel
    Referenced for ChannelFilter enum and DataDisplayUnits enum.

  • DTS.Common.DAS.Concepts.DAS.Channel.IEngineeringUnitAware
    Implemented by CalculatedChannel.

  • Serialization types
    Serialization.SliceRaw.File.PersistentChannel, Serialization.TDAS.File.PersistentChannel, ILargeDataAware, Serialization.Test.Module.Channel.

  • DTS.Calculations.HeadInjuryCriterion.HICResult
    Referenced in commented-out HICCalculatedChannel code.

  • DTS.Common.Utilities.SaeJ211
    Used for FilterUtility and related encoding.

External Dependencies (inferred)

  • System
    Standard .NET types (Exception, ApplicationException, CultureInfo, Enum, etc.).

  • Windows Forms (commented)
    System.Windows.Forms.MessageBox appears in commented-out code (not active).

5. Gotchas

  • DataValues has no data storage logic
    The class only configures storage mode (UseMemoryMappedFile). Actual data handling is delegated to Channel (not shown in these files). DataValues is a configuration helper, not a data container.

  • SaeJ211Filter.Type may differ from OriginalType
    For ad hoc filters, Type resolves to the nearest CFC match. This can cause IsCfc to return true even if OriginalType == AdHoc.

  • Filter.Parse(...) silently falls back to Unfiltered
    On parse failure, returns new SaeJ211Filter(ChannelFilter.Unfiltered) instead of throwing. Callers must validate if needed.

  • DefaultSaeJ211Filter.ToString() vs ToBaseString()
    ToString() returns "Default (X)", while ToBaseString() returns "X". Confusing if not documented.

  • CalculatedChannel range properties assume non-empty Y
    DataMaxEu, DataMinEu, etc., use _y.Max()/_y.Min() without checking for empty data. Will throw InvalidOperationException if Y is empty.

  • SupportsADC/SupportsmV are hard-coded false
    Calculated channels never support raw ADC or mV; only engineering units (EU). Attempting to access ActualMinRangeMv throws NotImplementedException.

  • CalculatedChannel serialization methods throw NotSupportedException
    FromDtsSerializationTestModuleChannel, ToDtsSerializationTestModuleChannel, SetPropertyValuesFrom(...) all throw. Calculated channels are not serializable via these paths.

  • Filter.Apply(...) logs invalid data but throws
    FilterUtility.InvalidDataDelegate logs via APILogger but then throws an exception. No silent failure.

  • ChannelFilter enum values are used as frequencies
    CFC filters (e.g., ChannelFilter.SixG) are implicitly cast to double for frequency. This relies on enum underlying values matching CFC frequencies.

  • IsoDescription uses OriginalType
    The ISO description character is derived from OriginalType, not Type. For ad hoc filters, this may be Unfiltered (not meaningful).

  • DataValues constructor catches and rethrows as Exception
    Any exception during construction is wrapped in a generic Exception with a message like "encountered problem constructing DTS.Slice.Control.Event.Module.Channel.DataValues". Original exception is preserved in InnerException.

Reference in New Issue View Git Blame Copy Permalink