NG.Velox

Zero-allocation, high-performance G-code processing pipeline for CNC kinematics, trajectory planning, and real-time interpolation.

NG.Velox is a systems-level .NET library designed to parse, interpret, plan, and interpolate G-code with native C/C++ performance. It is built for mission-critical environments where Garbage Collection (GC) pauses are unacceptable, such as real-time CNC controllers, edge computing, and high-throughput CAM simulations.

🚀 Key Features

• Absolute Zero-Allocation (GC-Free): Hot paths utilize ArrayPool<T>, Span<T>, stackalloc, and MemoryMarshal. Processing 100,000 lines of G-code generates 0 bytes of managed heap allocations.
• Industrial Kinematics: Implements Look-Ahead planning, Junction Deviation, and S-Curve (jerk-limited) acceleration profiles.
• High-Throughput Pipeline: Processes ~400,000 lines of G-code per second on mid-tier hardware.
• Dual Output Targets:
  • Hardware: Packs trajectory into dense binary structures for direct UART/Ethernet transmission to microcontrollers.
  • Simulation: Generates self-contained DTOs for JSON export, web visualization, or Python analysis.
• UVW Plane Normalization: Unified mathematical path for G17/G18/G19 planes, eliminating redundant code branches.
• Accurate Diagnostics: IndexMap tracks preprocessed characters back to original source lines for precise error reporting.

🏗 Architecture & Pipeline

The library processes data through a strictly sequential, allocation-free pipeline:

1. Preprocessor: Strips comments, N-codes, and whitespace. Builds an IndexMap for error tracking.
2. Lexer: O(1) character classification via bitmask lookup tables (CharRegistry).
3. Parser: Generates a dense 16-byte AST Node using explicit struct unions (LayoutKind.Explicit).
4. Interpreter: Emulates the CNC VM (modal groups, planes, absolute/relative modes).
5. Planner: Look-Ahead algorithm calculating S-curve entry/exit/cruise velocities.
6. Interpolator: Generates adaptive-step trajectory points (linear and arc interpolation).
7. Postprocessor: Serializes to binary (Hardware) or materializes DTOs (Simulation).

📊 Benchmarks

Tested on Intel Core i5-10400F, .NET 10.0, X64 RyuJIT AVX2.

Pipeline Stage	10,000 Lines	100,000 Lines	Allocated
0. Preprocessor	0.25 ms	2.68 ms	0 B
1. Lexer	0.47 ms	4.83 ms	0 B
2. Parser	1.44 ms	14.61 ms	0 B
3. Interpreter	0.24 ms	2.77 ms	0 B
4. Planner	1.51 ms	16.12 ms	0 B
5. Interpolator	9.20 ms	93.35 ms	0 B
6. Postprocessor	9.33 ms	93.21 ms	0 B
TOTAL	~12.4 ms	~227.5 ms	0 B

Note: 100,000 lines of G-code represents a massive, highly detailed 3D toolpath. The entire pipeline processes it in under a quarter of a second with zero GC pressure.

💻 Usage Example

Hardware Pipeline (Binary Output for Microcontrollers)

using NG.Velox.Factories;
using NG.Velox.Pipeline.Data;
using NG.Velox.Diagnostic.Core;

var pipeline = VeloxPipelineFactory.CreateHardware();
var result = new PipelineResult<byte>();
var diag = new DiagnosticBag();

try
{
    ReadOnlyMemory<char> gcode = File.ReadAllText("toolpath.gcode").AsMemory();
    pipeline.Process(gcode, ref result, ref diag);

    if (diag.HasErrors)
    {
        Console.WriteLine($"Error {diag.Diagnostics[0].Code} at index {diag.Diagnostics[0].Start}");
        return;
    }

    // result.Values is a ReadOnlySpan<byte> ready for SerialPort.Write() or Ethernet
    SendToMachine(result.Values); 
}
finally
{
    result.Dispose();
    diag.Dispose();
}

Simulation Pipeline (DTOs for Visualization/JSON)

using NG.Velox.Factories;
using NG.Velox.Pipeline.Data;
using NG.Velox.Diagnostic.Core;
using System.Text.Json;

var pipeline = VeloxPipelineFactory.CreateSimulation();
var result = new PipelineResult<SimulationFrame>();
var diag = new DiagnosticBag();

try
{
    pipeline.Process(gcodeText.AsMemory(), ref result, ref diag);
    
    // SimulationFrame contains independent arrays, safe for JSON serialization
    string json = JsonSerializer.Serialize(result.Values.ToArray());
    File.WriteAllText("trajectory.json", json);
}
finally
{
    result.Dispose();
    diag.Dispose();
}

📸 Visual Validation

The mathematical correctness of the kinematics, S-curves, and arc interpolation is validated against industry-standard software.

1. Source G-Code Snippet:

(Complex arc and linear moves)
G00 X0.000 Y0.000 Z0.000 F100.000
G00 Z200.000
G00 X100.000 Y100.000 Z200.000
G00 X100.000 Y100.000 Z100.000
F100.000
G17
G03 X120.000 Y80.000 R20.000
G03 X100.000 Y60.000 R20.000
G03 X80.000 Y80.000 R20.000
G03 X100.000 Y100.000 R20.000
G03 X120.000 Y80.000 R20.000
G02 X80.000 Y80.000 R20
G02 X120.000 Y80.000 R20
G18
G03 X100.000 Z120.000 R20.000
G03 X80.000 Z100.000 R20.000
G03 X100.000 Z80.000 R20.000
G03 X120.000 Z100.000 R20.000
G02 X80.000 Z100.000 R20.000
G02 X120.000 Z100.000 R20.000
G17
G03 X100 Y100 R20
G19
G02 Y80 Z120 R20
G02 Y60 Z100 R20
G02 Y80 Z80 R20
G02 Y100 Z100 R20
G03 Y60 Z100 R20
G03 Y100 Z100 R20
G00 X100.000 Y100.000 Z200.0

2. NG.Velox Interpolation Output (NumPy/Matplotlib):

3. Ethalon Validation (CIMCO Edit):

⚙️ Technical Highlights for Systems Devs

• Struct Unions: Node uses [StructLayout(LayoutKind.Explicit, Size = 16)] to overlap enums, reducing AST memory footprint by ~40% and maximizing L1/L2 cache locality.
• Branchless Lexing: CharRegistry uses bitwise masks for O(1) character classification without if/switch branching.
• Safe Unsafe Code: Extensive use of fixed, pointers, and MemoryMarshal.AsBytes for zero-copy binary serialization.
• No Reflection / No Virtual Calls in Hot Paths: Interfaces are used for architecture, but concrete sealed classes are invoked directly in the pipeline to allow JIT inlining.

📦 Installation

dotnet add package MachineGate.NG.Velox --version 1.0.0

🤝 Contributing

This is a systems-level project. Contributions regarding mathematical edge-cases, SIMD vectorization for the interpolator, or NativeAOT compatibility tests are highly welcome. Please open an issue first to discuss the architectural impact.

⚖️ License

Distributed under the MIT License. See LICENSE for more information.