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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.DAS.Concepts/Test/Module/RecordingMode.cs Common/DTS.Common.DAS.Concepts/Test/Module/TiltAxes.cs	2026-04-16T11:39:41.280506+00:00	zai-org/GLM-5-FP8	1	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

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

public static TiltAxes GetTiltAxesFromString(string tiltAxes)

Converts a string representation to a TiltAxes enum value. Throws Exception with descriptive message if parsing fails.

public static TiltAxesSimple SimplifyTiltAxes(TiltAxes axes)

Converts a TiltAxes enum to its simplified form by removing "I" (inversion) prefixes.

public static int[] GetPolaritiesFromTiltAxes(TiltAxes ta)

Returns an array of polarity values (-1 or 1) for each axis based on the TiltAxes enum.

public static bool[] GetBoolPolaritiesFromTiltAxes(TiltAxes tiltAxes)

Returns a boolean array indicating inversion state for each axis. true indicates inverted.

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

public static double[] GetTiltDegreesEU(short[] tiltSensorADC, double[] tiltSensorCals)

Overload that uses default parameters: TiltAxes.IXYZ, ignored axis 3, and zero mount offsets.

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.

public static double[] GetTiltZeroData(short[] tiltSensorADC, double[] tiltSensorCals, int dominantAxis)

Calculates zero offset data based on the dominant axis and its polarity.

public static int GetDominantTiltAxis(short[] tiltSensorADC)

Returns the index of the axis with the largest absolute ADC value.

public static double[] GetTiltGains(double[] tiltSensorCals)

Extracts gain values from calibration data. Returns 1.0 for any gain that is 0.0.

---

Utility Methods

public static string ConvertBoolToInvertString(bool isInverted)

Returns "I" if isInverted is true, otherwise empty string.

public static string GetOrientationLabelFromAxisInfo(string[] axisLabels, bool[] invertAxis)

Builds an orientation label string from axis labels and inversion flags.

public static TiltAxes GetTiltAxesFromAxisInfo(string[] axisLabels, bool[] invertAxis)

Constructs a TiltAxes enum from axis labels and inversion flags.

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:

   for (int i = 0; i < 3; i++)
   {
       AxisConfigurations[i].Label = TiltAxes[i * 2].ToString();
   }
   

   However, the conditional logic references keys 1, 2, 3:

   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):

   AxisOne = AxisConfigurations[1];
   AxisOne = AxisConfigurations[2];  // Overwrites previous line
   

   AxisOne is assigned twice and AxisTwo is never assigned (remains null).

3. TargetOffset Assignment Bug:

   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.