DP44/docs/ai/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-17T15:41:18.940422+00:00	zai-org/GLM-5-FP8	1	db7767b693a54948

Documentation: Test.Module (TiltAxes & RecordingMode)

1. Purpose

This module provides utilities for managing tilt sensor configuration and recording mode conversions within the DTS DAS (Data Acquisition System) Concepts framework. It handles the translation of raw ADC tilt sensor data into engineering units (degrees), manages axis orientation configurations (including axis inversion and ordering), and provides string-to-enum conversion for recording modes. The module is part of a larger Test partial class hierarchy and serves as a bridge between hardware-level sensor readings and application-level tilt calculations.

---

2. Public Interface

RecordingMode.cs

Test.Module.GetRecordingModeFromString

public static DFConstantsAndEnums.RecordingMode GetRecordingModeFromString(string recordingMode)

Converts a string representation of a recording mode enumeration into its corresponding DFConstantsAndEnums.RecordingMode enum value. Throws an Exception with a descriptive message if parsing fails (including handling for null input).

---

TiltAxes.cs

Nested Classes

TiltAxis

A data container class with the following properties:

Property	Type	Default
AxisNumber	int	-
CurrentTilt	double	-
Label	string	-
Inversion	int	1
IsIgnored	bool	false
MountedOffset	double	0.0
TargetOffset	double	0.0

TiltAxesHelper

A helper class for managing tilt axis configurations.

Constructors:

public TiltAxesHelper()  // Default constructor, initializes 3 axes
public TiltAxesHelper(string TiltAxes, double MountOffsetAxisOne, double MountOffsetAxisTwo,
    double TargetAxisOne, double TargetAxisTwo, double LevelTolerance,
    int AxisIgnored, bool UseForTiltCalculation)

Properties:

• Dictionary<int, TiltAxis> AxisConfigurations - Dictionary of axis configurations
• TiltAxis AxisOne / TiltAxis AxisTwo - References to the two active axes
• double LevelTolerance - Default: 0.5

Methods:

public string AxesToString()  // Returns string representation of axes with polarity

---

Enumerations

TiltAxesSimple

public enum TiltAxesSimple { XYZ = 0, XZY = 1, YXZ = 2, YZX = 3, ZXY = 4, ZYX = 5 }

TiltAxesPolarity

public enum TiltAxesPolarity { PPP = 0, PPN = 1, PNP = 2, PNN = 3, NPP = 4, NPN = 5, NNP = 6, NNN = 7 }

TiltSensorCalAttributes

Enumeration with 18 calibration attributes for tilt sensors (indices 0-17), including gains, zeros, and dominant axis calibration values.

AxisLabel

public enum AxisLabel { X = 0, Y = 1, Z = 2 }

---

Static Methods

SimplifyTiltAxes

public static TiltAxesSimple SimplifyTiltAxes(TiltAxes axes)

Removes 'I' (inversion) markers from a TiltAxes enum value and returns the simplified TiltAxesSimple equivalent.

GetTiltAxesFromString

public static TiltAxes GetTiltAxesFromString(string tiltAxes)

Converts a string representation to a TiltAxes enum value. Throws an Exception on parse failure.

GetPolaritiesFromTiltAxes

public static int[] GetPolaritiesFromTiltAxes(TiltAxes ta)

Returns an int[3] where each element is -1 (inverted) or 1 (not inverted) based on the 'I' markers in the enum name.

GetBoolPolaritiesFromTiltAxes

public static bool[] GetBoolPolaritiesFromTiltAxes(TiltAxes tiltAxes)

Returns a bool[3] where true indicates an inverted axis.

GetTiltDegreesEU

public static double[] GetTiltDegreesEU(short[] tiltSensorADC, double[] tiltSensorCals)
public static double[] GetTiltDegreesEU(short[] tiltSensorADC, double[] tiltSensorCals, 
    TiltAxes axes, int ignoredAxis, float[] mountOffsetAxis)

Converts raw ADC values to tilt degrees in engineering units. Returns double[3] with X, Y, Z tilt values. Ignored axis values are set to double.NaN. Uses 3 decimal places of precision (SIGNIFICANT_DIGITS = 1000).

GetTiltZeroData

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

Retrieves zero calibration data based on the dominant axis and its polarity.

GetDominantTiltAxis

public static int GetDominantTiltAxis(short[] tiltSensorADC)

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

GetTiltGains

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

Returns gain values for all three axes. Defaults to 1.0 if gain is 0.

GetAxisLabelFromTiltAxes

public static AxisLabel[] GetAxisLabelFromTiltAxes(TiltAxes tiltAxes)
public static AxisLabel[] GetAxisLabelFromTiltAxes(string tiltAxes)

Extracts axis labels from a TiltAxes configuration.

ConvertBoolToInvertString

public static string ConvertBoolToInvertString(bool isInverted)

Returns "I" if inverted, empty string otherwise.

GetOrientationLabelFromAxisInfo

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

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

GetTiltAxesFromAxisInfo

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

Constructs a TiltAxes enum from axis labels and inversion flags.

GetMountOffsetsOrTargetsFromAxisInfo

public static float[] GetMountOffsetsOrTargetsFromAxisInfo(float[] perAxisValue, int axisToIgnore)

Extracts mount offsets or targets for the two non-ignored axes. Returns float[2].

---

3. Invariants

• Array Sizes: tiltSensorADC must contain exactly 3 elements. tiltSensorCals must contain at least 18 elements (indexed by TiltSensorCalAttributes).
• Ignored Axis Values: Valid values are 1, 2, or 3. A value of 0 is treated as 3.
• Precision: Tilt degree calculations are rounded to 3 decimal places using SIGNIFICANT_DIGITS = 1000.
• Gain Default: If a gain calibration value is 0, it defaults to 1.0 to prevent division by zero.
• Dictionary Keys: TiltAxesHelper.AxisConfigurations uses keys 1, 2, and 3 (1-indexed), not 0, 1, 2.

---

4. Dependencies

This module depends on:

• DTS.Common.Enums.DASFactory - For DFConstantsAndEnums.RecordingMode and TiltAxes enum
• DTS.Common.Utilities - For DegreesFromADC.GetDegrees() method
• System, System.Collections.Generic, System.Linq, System.Text

Consumers:

• Unknown from source alone. The partial class structure (Test.Module) suggests this is consumed by other components within the DTS.Common.DAS.Concepts namespace.

---

5. Gotchas

Critical Bugs in TiltAxesHelper Constructor

1. Bug: AxisTwo never assigned in default case

   else
   {
       AxisOne = AxisConfigurations[1];
       AxisOne = AxisConfigurations[2];  // BUG: Should be AxisTwo
   }
   

   When AxisIgnored is not 1 or 2, AxisTwo remains null and AxisOne is assigned twice.

2. Bug: TargetAxisTwo assigned to wrong property

   AxisOne.TargetOffset = TargetAxisOne;
   AxisOne.TargetOffset = TargetAxisTwo;  // BUG: Should be AxisTwo.TargetOffset
   

   AxisTwo.TargetOffset is never set; `Axis