Core Module API

Foundation library with core abstractions, units, and data structures.

Units and Measurements

Type-safe physical quantity representations to prevent unit confusion.

Angle

Copy

// Create angles with explicit units
var degrees = Angle.FromDegrees(90);
var radians = Angle.FromRadians(Math.PI / 2);

// Access in desired units
double rad = degrees.Radians;      // π/2
double deg = radians.Degrees;      // 90

// Normalize to [-π, π]
var normalized = degrees.Normalize();

Distance and Vector Types

Copy

var distance = Distance.FromInches(24);
var metersEquiv = distance.Meters;

var position = new Vector2(12.5, 34.2);
var magnitude = position.Magnitude;
var normalized = position.Normalized;

Advanced Unit System Features

Automatic Unit Conversion & Verification

Compile-time safe unit types prevent calculation errors from unit mismatches.

Copy

// Type-safe dimensional analysis
var wheelDiameter = Distance.FromInches(3.25);
var circumference = wheelDiameter.Circumference;  // Returns Distance
var encoderRes = 360.0;  // ticks per revolution

// Velocity calculation (Distance / Time)
var wheelRotationsPerSecond = 5.0;
var velocity = wheelDiameter.Circumference * wheelRotationsPerSecond;

// Calculate gear ratio conversions
var motorRPM = 600.0;
var gearRatio = 3.36;
var outputRPM = motorRPM / gearRatio;

// Angular velocity
var angularVel = Angle.FromDegrees(outputRPM * 6.0);  // deg/s

3D Vector Operations

Advanced vector math for pose estimation and coordinate transformations.

Copy

// 3D position and orientation
var position = new Vector3(10, 20, 5);  // x, y, z meters
var heading = Angle.FromDegrees(45);

// Pose (position + heading)
var robotPose = new Pose3D(position, heading);

// Transformations
var homogenousMatrix = robotPose.ToMatrix4x4();
var transformedPoint = homogenousMatrix * new Vector3(1, 0, 0);

// Distance calculations
var target = new Vector3(50, 30, 10);
var distance = Vector3.Distance(position, target);
var direction = (target - position).Normalized;

// Interpolation (for smooth motion between poses)
var interpPose = Pose3D.Lerp(robotPose, targetPose, t: 0.5);

Thread-safe data structures optimized for real-time systems.

RingBuffer

Copy

// Thread-safe circular buffer for time-series data
var buffer = new RingBuffer(capacity: 1000);

// Add elements (auto-overwrites oldest when full)
for (int i = 0; i < 1000; i++)
    buffer.Add(sensor.ReadValue());

// Access as array
double[] data = buffer.ToArray();
Console.WriteLine($"Buffer contains {buffer.Count} elements");

Advanced Collections

RingBuffer for Real-Time Data Processing

Thread-safe circular buffer optimized for sensor data with statistical analysis.

Copy

// Real-time sensor data buffering with statistics
var sensorBuffer = new RingBuffer(capacity: 1000)
{
    ComputeStatistics = true,
    StatisticsUpdateFrequency = 100  // every 100 samples
};

// Background data collection
var dataTask = Task.Run(async () =>
{
    while (isRunning)
    {
        double reading = sensor.ReadValue();
        sensorBuffer.Add(reading);
        
        // Get statistics on-demand
        var stats = sensorBuffer.GetStatistics();
        if (stats.StandardDeviation > threshold)
        {
            logger.LogWarning($"High sensor noise: σ={stats.StandardDeviation:F3}");
        }
        
        await Task.Delay(10);  // 100 Hz sampling
    }
});

// Main thread can access buffered data
double[] recentData = sensorBuffer.GetLast(500);
double mean = sensorBuffer.Mean;
double median = sensorBuffer.Median;
double max = sensorBuffer.Max;

Specialized Collections

Optimized data structures for robotics-specific use cases.

Copy

// Priority queue for path planning
var openSet = new PriorityQueue<Node, double>();

// Deque for bidirectional algorithms
var deque = new Deque<Waypoint>();

// Spatial hash for fast neighbor queries (for collision detection)
var spatialHash = new SpatialHashGrid<Robot>(gridSize: 10.0);
foreach (var robot in robots)
{
    spatialHash.Insert(robot, robot.Position);
}

// Find all robots within radius
var neighbors = spatialHash.Query(position, radius: 5.0);

Structured logging for debugging and diagnostics.

Copy

var logger = LoggerFactory.Create("MyModule");
logger.Info("Starting robot initialization");
logger.Debug("Parameter: {0}", parameterValue);
logger.Warn("Battery voltage low: {0}V", voltage);
logger.Error("Connection failed: {0}", errorMessage);