DP44/enriched-partialglm/Common/DTS.Common.DAS.Concepts/Test/Module.md

---
source_files:
  - Common/DTS.Common.DAS.Concepts/Test/Module/RecordingMode.cs
  - Common/DTS.Common.DAS.Concepts/Test/Module/TiltAxes.cs
generated_at: "2026-04-16T11:39:41.280506+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "d40daed59089dfb4"
---

# Documentation: DTS.Common.DAS.Concepts.Test.Module

## 1. Purpose

This module provides utilities for handling tilt sensor data and recording mode configurations within the DTS data acquisition system. It contains classes and methods for converting raw ADC tilt sensor readings into engineering units (degrees), managing tilt axis configurations and polarities, and parsing string representations of enumeration values. The module serves as a bridge between hardware-level sensor data and application-level tilt calculations, supporting multiple axis orientations and calibration parameters.

---

## 2. Public Interface

### Classes

#### `Test.Module.TiltAxis`
A data container class representing a single tilt axis configuration.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `AxisNumber` | `int` | - | The axis identifier number |
| `CurrentTilt` | `double` | - | The current tilt value |
| `Label` | `string` | - | The axis label (e.g., "X", "Y", "Z") |
| `Inversion` | `int` | `1` | Polarity multiplier (-1 or 1) |
| `IsIgnored` | `bool` | `false` | Whether this axis is excluded from calculations |
| `MountedOffset` | `double` | `0.0` | Mount offset in degrees |
| `TargetOffset` | `double` | `0.0` | Target offset in degrees |

#### `Test.Module.TiltAxesHelper`
A helper class for managing tilt axis configurations parsed from firmware attributes.

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `AxisConfigurations` | `Dictionary<int, TiltAxis>` | Empty dict with keys 0,1,2 | Collection of axis configurations |
| `AxisOne` | `TiltAxis` | - | Reference to the first active axis |
| `AxisTwo` | `TiltAxis` | - | Reference to the second active axis |
| `LevelTolerance` | `double` | `0.5` | Tolerance for level detection |

**Constructors:**
- `TiltAxesHelper()` - Default constructor initializing 3 axis configurations
- `TiltAxesHelper(string TiltAxes, double MountOffsetAxisOne, double MountOffsetAxisTwo, double TargetAxisOne, double TargetAxisTwo, double LevelTolerance, int AxisIgnored, bool UseForTiltCalculation)` - Constructs from firmware attributes

**Methods:**
- `string AxesToString()` - Returns a string representation of axis labels with polarity indicators (e.g., "IXPYP")

---

### Enumerations

#### `Test.Module.TiltAxesSimple`
Simplified tilt axis orderings (6 permutations).

| Value | Name |
|-------|------|
| 0 | `XYZ` |
| 1 | `XZY` |
| 2 | `YXZ` |
| 3 | `YZX` |
| 4 | `ZXY` |
| 5 | `ZYX` |

#### `Test.Module.TiltAxesPolarity`
Polarity combinations for three axes (8 combinations).

| Value | Name |
|-------|------|
| 0 | `PPP` |
| 1 | `PPN` |
| 2 | `PNP` |
| 3 | `PNN` |
| 4 | `NPP` |
| 5 | `NPN` |
| 6 | `NNP` |
| 7 | `NNN` |

#### `Test.Module.TiltSensorCalAttributes`
18 calibration attribute indices for tilt sensor calibration data.

| Value | Name |
|-------|------|
| 0 | `TILTSENSOR_CAL_1_GainAxis1` |
| 1 | `TILTSENSOR_CAL_2_ZeroAxis1` |
| 2 | `TILTSENSOR_CAL_3_ZeroDomAxis2PosAxis1` |
| 3 | `TILTSENSOR_CAL_4_ZeroDomAxis2NegAxis1` |
| ... | (continues through index 17) |
| 17 | `TILTSENSOR_CAL_18_ZeroDomAxis2NegAxis3` |

#### `Test.Module.AxisLabel`
| Value | Name |
|-------|------|
| 0 | `X` |
| 1 | `Y` |
| 2 | `Z` |

---

### Static Methods

#### Recording Mode Methods

```csharp
public static DFConstantsAndEnums.RecordingMode GetRecordingModeFromString(string recordingMode)
```
Converts a string representation to a `DFConstantsAndEnums.RecordingMode` enum value. Throws `Exception` with descriptive message if parsing fails.

---

#### Tilt Axes Parsing Methods

```csharp
public static TiltAxes GetTiltAxesFromString(string tiltAxes)
```
Converts a string representation to a `TiltAxes` enum value. Throws `Exception` with descriptive message if parsing fails.

```csharp
public static TiltAxesSimple SimplifyTiltAxes(TiltAxes axes)
```
Converts a `TiltAxes` enum to its simplified form by removing "I" (inversion) prefixes.

```csharp
public static int[] GetPolaritiesFromTiltAxes(TiltAxes ta)
```
Returns an array of polarity values (-1 or 1) for each axis based on the `TiltAxes` enum.

```csharp
public static bool[] GetBoolPolaritiesFromTiltAxes(TiltAxes tiltAxes)
```
Returns a boolean array indicating inversion state for each axis. `true` indicates inverted.

```csharp
public static AxisLabel[] GetAxisLabelFromTiltAxes(TiltAxes tiltAxes)
public static AxisLabel[] GetAxisLabelFromTiltAxes(string tiltAxes)
```
Extracts axis labels from a `TiltAxes` enum or string representation.

---

#### Tilt Calculation Methods

```csharp
public static double[] GetTiltDegreesEU(short[] tiltSensorADC, double[] tiltSensorCals)
```
Overload that uses default parameters: `TiltAxes.IXYZ`, ignored axis 3, and zero mount offsets.

```csharp
public static double[] GetTiltDegreesEU(short[] tiltSensorADC, double[] tiltSensorCals, TiltAxes axes, int ignoredAxis, float[] mountOffsetAxis)
```
Converts raw ADC tilt sensor readings to engineering units (degrees). Returns a `double[3]` containing X, Y, Z tilt values in degrees. The ignored axis value is set to `double.NaN`.

```csharp
public static double[] GetTiltZeroData(short[] tiltSensorADC, double[] tiltSensorCals, int dominantAxis)
```
Calculates zero offset data based on the dominant axis and its polarity.

```csharp
public static int GetDominantTiltAxis(short[] tiltSensorADC)
```
Returns the index of the axis with the largest absolute ADC value.

```csharp
public static double[] GetTiltGains(double[] tiltSensorCals)
```
Extracts gain values from calibration data. Returns `1.0` for any gain that is `0.0`.

---

#### Utility Methods

```csharp
public static string ConvertBoolToInvertString(bool isInverted)
```
Returns `"I"` if `isInverted` is true, otherwise empty string.

```csharp
public static string GetOrientationLabelFromAxisInfo(string[] axisLabels, bool[] invertAxis)
```
Builds an orientation label string from axis labels and inversion flags.

```csharp
public static TiltAxes GetTiltAxesFromAxisInfo(string[] axisLabels, bool[] invertAxis)
```
Constructs a `TiltAxes` enum from axis labels and inversion flags.

```csharp
public static float[] GetMountOffsetsOrTargetsFromAxisInfo(float[] perAxisValue, int axisToIgnore)
```
Extracts a 2-element array of values for the non-ignored axes (1-indexed: 1, 2, or 3).

---

## 3. Invariants

1. **Array Size Requirements:**
   - `tiltSensorADC` must be a 3-element array (indices 0, 1, 2 correspond to axes)
   - `tiltSensorCals` must be an 18-element array (indexed by `TiltSensorCalAttributes`)
   - `mountOffsetAxis` must be a 2-element array
   - `perAxisValue` in `GetMountOffsetsOrTargetsFromAxisInfo` must be a 3-element array

2. **Ignored Axis Values:**
   - Valid values are 1, 2, or 3 (1-indexed)
   - A value of 0 is silently converted to 3 in `GetTiltDegreesEU`

3. **Gain Default Behavior:**
   - Any gain value of `0.0` is replaced with `1.0` in `GetTiltGains`

4. **Output Format:**
   - `GetTiltDegreesEU` returns degrees rounded to 3 decimal places (via `SIGNIFICANT_DIGITS = 1000`)
   - Ignored axis values are set to `double.NaN`

5. **TiltAxesHelper Dictionary Keys:**
   - The default constructor initializes `AxisConfigurations` with keys 0, 1, 2 (not 1, 2, 3)

---

## 4. Dependencies

### External Dependencies (Imports)
- `DTS.Common.Enums.DASFactory` - Provides `DFConstantsAndEnums.RecordingMode` and `TiltAxes` enumerations
- `DTS.Common.Utilities` - Provides `DegreesFromADC.GetDegrees()` method
- `System` - Core .NET types
- `System.Collections.Generic` - `Dictionary<TKey, TValue>`, `List<T>`
- `System.ComponentModel` - Component model infrastructure
- `System.Linq` - LINQ extension methods (`Max()`, `Min()`, `IndexOf()`)
- `System.Text` - `StringBuilder`

### Consumers
- Unknown from source alone. The partial class structure (`Test.cs`, `Test.Module`) suggests this is part of a larger test configuration system.

---

## 5. Gotchas

### Critical Bugs in `TiltAxesHelper` Constructor

1. **Dictionary Key Mismatch:** The constructor parses `TiltAxes` string using indices 0, 1, 2:
   ```csharp
   for (int i = 0; i < 3; i++)
   {
       AxisConfigurations[i].Label = TiltAxes[i * 2].ToString();
   }
   ```
   However, the conditional logic references keys 1, 2, 3:
   ```csharp
   AxisOne = AxisConfigurations[2];
   AxisTwo = AxisConfigurations[3];  // Key 3 does not exist!
   ```
   This will throw a `KeyNotFoundException` at runtime when `AxisIgnored == 1`.

2. **Duplicate Assignment Bug:** In the `else` branch (when `AxisIgnored` is not 1 or 2):
   ```csharp
   AxisOne = AxisConfigurations[1];
   AxisOne = AxisConfigurations[2];  // Overwrites previous line
   ```
   `AxisOne` is assigned twice and `AxisTwo` is never assigned (remains `null`).

3. **TargetOffset Assignment Bug:**
   ```csharp
   AxisOne.TargetOffset = TargetAxisOne;
   AxisOne.TargetOffset = TargetAxisTwo;  // Overwrites previous line
   ```
   `TargetAxisTwo` overwrites `TargetAxisOne`, and `AxisTwo.TargetOffset` is never set.

### Other Issues

4. **Misleading Comments:** Comments in `GetTiltDegreesEU` state "1 decimal place" but the code uses `SIGNIFICANT_DIGITS = 1000` which provides 3 decimal places.

5. **Inconsistent Mount Offset Usage:** In `GetTiltDegreesEU`, some switch cases use `mountOffsetAxisOne` twice for different axes (e.g., case 2 in XYZ uses `mountOffsetAxisOne` for both X and Z calculations). This may be intentional but appears inconsistent.

6. **Silent Normalization:** `ignoredAxis == 0` is silently converted to `3` without documentation or validation of other invalid values.

7. **Unused Property:** `UseForTiltCalculation` property in `TiltAxesHelper` is set in the constructor but never used elsewhere in the visible code.