125 lines
6.3 KiB
Markdown
125 lines
6.3 KiB
Markdown
---
|
|
source_files:
|
|
- Common/DTS.Common.Calculations/ChannelData.cs
|
|
- Common/DTS.Common.Calculations/Integral.cs
|
|
- Common/DTS.Common.Calculations/Resultant.cs
|
|
- Common/DTS.Common.Calculations/HeadInjuryCriterion.cs
|
|
generated_at: "2026-04-16T11:35:26.354514+00:00"
|
|
model: "zai-org/GLM-5-FP8"
|
|
schema_version: 1
|
|
sha256: "2d2deac012cb62cf"
|
|
---
|
|
|
|
# DTS.Common.Calculations Module Documentation
|
|
|
|
## 1. Purpose
|
|
|
|
This module provides mathematical calculation utilities for signal processing, specifically focused on biomechanical injury analysis. It contains a data container class (`ChannelData`) for holding filtered time-series data with associated engineering units, and implements algorithms for numerical integration (`Integral`), vector resultant calculation (`Resultant`), and Head Injury Criterion computation (`HeadInjuryCriterion`). The module is designed to work with pre-filtered sensor data, particularly acceleration channels used in impact testing.
|
|
|
|
---
|
|
|
|
## 2. Public Interface
|
|
|
|
### `ChannelData` Class
|
|
|
|
A data container for holding filtered channel data with associated engineering units.
|
|
|
|
| Member | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| Constructor | `ChannelData(string units)` | Constructs a new `ChannelData` instance with the specified engineering units. |
|
|
| `Units` | `string Units { get; }` | Read-only property returning the engineering units of the data. |
|
|
| `FilteredEU` | `double[] FilteredEU { get; set; }` | Gets or sets the pre-filtered engineering unit data array. |
|
|
|
|
---
|
|
|
|
### `Integral` Static Class
|
|
|
|
Provides numerical integration methods.
|
|
|
|
| Method | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| `DefiniteIntegral` | `static double DefiniteIntegral(double[] input, int start, int end, double SPS)` | Computes the definite integral of `input` from index `start` to `end` (both inclusive) using trapezoidal summation. `SPS` is samples per second (sample rate). Returns the integrated value. |
|
|
|
|
---
|
|
|
|
### `Resultant` Static Class
|
|
|
|
Provides vector resultant calculation from multiple input channels.
|
|
|
|
| Method | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| `GenerateResultantChannel` | `static ChannelData GenerateResultantChannel(List<ChannelData> channels)` | Generates a resultant channel by computing the square root of the sum of squares across all input channels at each sample index. Returns a new `ChannelData` with the resultant values. |
|
|
|
|
---
|
|
|
|
### `HeadInjuryCriterion` Static Class
|
|
|
|
Provides Head Injury Criterion (HIC) calculation for biomechanical analysis.
|
|
|
|
| Method | Signature | Description |
|
|
|--------|-----------|-------------|
|
|
| `GetHeadInjuryCriterion` | `static HICResult GetHeadInjuryCriterion(ChannelData resultant, double SPS, int clipLengthMS)` | Calculates the maximum Head Injury Criterion over the input `resultant` acceleration channel for the specified `clipLengthMS` duration. `SPS` is the actual sample rate in samples per second. Returns an `HICResult` containing the maximum HIC value and its location. |
|
|
|
|
#### `HICResult` Nested Class
|
|
|
|
A result container for HIC calculations.
|
|
|
|
| Property | Type | Description |
|
|
|----------|------|-------------|
|
|
| `StartSample` | `int` | The starting sample index of the maximum HIC window. |
|
|
| `EndSample` | `int` | The ending sample index of the maximum HIC window. |
|
|
| `HicLengthMS` | `int` | The HIC clip length in milliseconds. |
|
|
| `HIC` | `double` | The calculated maximum HIC value. |
|
|
|
|
| Constructor | Signature |
|
|
|-------------|-----------|
|
|
| `HICResult` | `HICResult(double hic, int hicLength, int startSample, int endSample)` |
|
|
|
|
---
|
|
|
|
## 3. Invariants
|
|
|
|
- **`Integral.DefiniteIntegral`**: The input data must be tightly time-aligned (uniform sampling interval). The method assumes constant spacing between samples, allowing division by `SPS` rather than computing variable time deltas.
|
|
|
|
- **`Resultant.GenerateResultantChannel`**: All channels in the input list must have:
|
|
- Identical `FilteredEU` array lengths
|
|
- Identical `Units` values
|
|
|
|
These constraints are enforced via `Trace.Assert` calls.
|
|
|
|
- **`HeadInjuryCriterion.GetHeadInjuryCriterion`**:
|
|
- `SPS` must be greater than 0
|
|
- `clipLengthMS` must be greater than 0
|
|
- The `resultant.FilteredEU` array must contain at least `clipLengthMS` worth of data (specifically, at least `maxclip` samples where `maxclip = Ceiling(clipLengthMS * SPS / 1000)`)
|
|
|
|
---
|
|
|
|
## 4. Dependencies
|
|
|
|
### This module depends on:
|
|
- `System` (for `Math`, `Convert`, `DateTime`-related types)
|
|
- `System.Collections.Generic` (for `List<T>`)
|
|
- `System.Linq` (for `Distinct()`, `Max()`, `First()`, `Count()`, `Select()`)
|
|
- `System.Diagnostics` (for `Trace.Assert`)
|
|
|
|
### What depends on this module:
|
|
- **Unclear from source alone** — no consumers are shown in the provided files. This appears to be a foundational calculation library intended for use by higher-level analysis modules.
|
|
|
|
---
|
|
|
|
## 5. Gotchas
|
|
|
|
1. **Assertion behavior in production**: All validation is performed using `System.Diagnostics.Trace.Assert`. By default, `Trace.Assert` only triggers a dialog in debug builds and may be silently ignored in release configurations depending on trace listener configuration. Invalid inputs may produce incorrect results rather than explicit failures in production.
|
|
|
|
2. **Brute-force HIC algorithm**: The `GetHeadInjuryCriterion` method uses an exhaustive brute-force approach, recalculating integrals repeatedly. The source explicitly acknowledges this inefficiency with the comment: *"we are exhaustively recalculating sums, we can do this much better without a doubt."* Performance may be poor for large datasets.
|
|
|
|
3. **Documentation typo in `HICResult` constructor**: The XML documentation comments for the constructor parameters have the descriptions for `endSample` and `startSample` swapped:
|
|
```csharp
|
|
/// <param name="endSample">start sample of HIC</param>
|
|
/// <param name="startSample">end sample of HIC</param>
|
|
```
|
|
The actual parameter order is `(hic, hicLength, startSample, endSample)`.
|
|
|
|
4. **Future unit conversion not implemented**: The `ChannelData` class stores units but provides no unit conversion functionality. The comment indicates this is planned for future implementation.
|
|
|
|
5. **Potential parallelization opportunity**: The `Resultant.GenerateResultantChannel` method contains a comment indicating parallelization is planned for a future version, but the current implementation is single-threaded. |