OpenIGTLink Rust
A high-performance, type-safe Rust implementation of the OpenIGTLink protocol for real-time communication in image-guided therapy and surgical navigation systems.
OpenIGTLink is the industry-standard open network protocol used in medical applications like 3D Slicer, PLUS Toolkit, and numerous surgical navigation systems worldwide.
Why OpenIGTLink Rust?
- 🦀 Memory Safety - Rust's ownership system eliminates memory leaks and buffer overflows common in medical software
- 🚀 High Performance - Zero-copy parsing and efficient serialization for real-time surgical applications
- ✅ 100% Compatible - Binary-compatible with the official C++ library - works with all existing OpenIGTLink software
- 🎯 Dynamic Dispatch - Receive any message type at runtime, just like C++ MessageFactory (v0.3.0+)
- 🔒 Production Ready - 102+ comprehensive tests, extensive documentation, and real-world examples
- 🏗️ Type-Safe Builder - Compile-time guarantees prevent invalid client configurations
Quick Start
The most common use case is receiving messages dynamically without knowing the type in advance:
use ClientBuilder;
use AnyMessage;
// Connect to an OpenIGTLink server
let mut client = new
.tcp
.async_mode
.build
.await?;
// Receive any message type dynamically
let msg = client.receive_any.await?;
// Pattern match to handle different message types
match msg
Try it now - Run your first example in 30 seconds:
# Terminal 1: Start a server that sends various message types
# Terminal 2: Receive and handle messages dynamically
For sending specific message types, use the type-safe API:
use IgtlMessage;
use TransformMessage;
let transform = identity;
let msg = new?;
client.send.await?;
Key Features
🎯 Dynamic Message Handling (v0.3.0+)
Receive any message type without compile-time knowledge - perfect for monitoring tools, protocol analyzers, and multi-device applications:
use AnyMessage;
// Receive messages dynamically at runtime
let msg = client.receive_any.await?;
// Access common header information
println!;
// Pattern match for specific handling
match msg
Use cases:
- Generic receivers for multiple devices (surgical tools, scanners, sensors)
- Message logging and monitoring dashboards
- Protocol debugging and testing tools
- Applications receiving unknown or custom message types
See dynamic_receiver.rs and async_dynamic_receiver.rs for complete examples.
🏗️ Flexible Client Builder
Create clients with exactly the features you need using the type-state builder pattern:
use ;
use Arc;
use rustls;
// Simple TCP client
let client = new
.tcp
.async_mode
.build
.await?;
// TLS-encrypted client
let tls_config = new;
let client = new
.tcp
.async_mode
.with_tls
.build
.await?;
// Auto-reconnecting client
let reconnect_config = with_max_attempts;
let client = new
.tcp
.async_mode
.with_reconnect
.build
.await?;
// TLS + Auto-reconnect (previously impossible!)
let client = new
.tcp
.async_mode
.with_tls
.with_reconnect
.build
.await?;
// UDP for low-latency tracking (bind any available local port)
let client = new
.udp
.build?;
Compile-time safety: Unsupported combinations (like UDP + TLS) are prevented at compile time!
🏥 Medical Imaging & Tracking
- 20/20 Message Types - Complete implementation of all OpenIGTLink messages
- Medical images (CT/MRI/Ultrasound) with compression
- Real-time video streaming (H.264, VP9, MJPEG)
- Surgical tool tracking (60-120 Hz)
- Sensor data (force sensors, IMU)
- 3D visualization (meshes, point clouds)
🌐 Networking & I/O
- Flexible Builder API - Type-safe client construction with compile-time validation
- Async/Sync I/O - Choose between blocking or Tokio async for your use case
- UDP Support - Low-latency tracking data transmission (120+ Hz)
- TLS/SSL Encryption - Secure medical data transfer with certificate validation
- Auto-reconnection - Robust network error handling with exponential backoff
- Multi-client Server - Built-in session management for concurrent connections
⚡ Performance & Reliability
- Zero-copy Parsing - Minimal overhead for real-time applications
- Image Compression - 98-99% reduction for medical images (Deflate/Gzip)
- Message Queuing - Backpressure control for high-throughput scenarios
- CRC-64 Validation - Optional integrity checking
- Structured Logging - Production-ready tracing integration
Installation
Add to your Cargo.toml
:
[]
= "0.3" # Latest: Dynamic message dispatch support
Or install from source:
Architecture
Builder Pattern Design
The library uses a type-state builder pattern to ensure compile-time safety:
.tcp // Or .udp(addr)
.async_mode // Or .sync() for blocking I/O
.with_tls // Optional: Add TLS encryption
.with_reconnect // Optional: Enable auto-reconnection
.verify_crc // Optional: CRC verification
.build // Returns Result<Client>
new
Key Design Decisions:
-
No Variant Explosion: Instead of creating separate types for every feature combination (TcpAsync, TcpAsyncTls, TcpAsyncReconnect, TcpAsyncTlsReconnect...), we use a single
UnifiedAsyncClient
with optional features. -
Type-Safe States: The builder uses Rust's type system to prevent invalid configurations at compile time. For example, you cannot call
.with_tls()
on a UDP client. -
Zero Runtime Cost: The
PhantomData
markers used for type states have zero size and are optimized away at compile time.
UnifiedAsyncClient Architecture
This design:
- ✅ Scales to any number of features without combinatorial explosion
- ✅ Maintains type safety and compile-time guarantees
- ✅ Enables previously impossible combinations (TLS + Reconnect)
- ✅ Easy to extend with new features (compression, authentication, etc.)
Client Types
Builder | Result Type | Best For | Key Features |
---|---|---|---|
.tcp().sync() |
SyncIgtlClient |
Simple applications | Blocking I/O, easy to use |
.tcp().async_mode() |
UnifiedAsyncClient |
High concurrency | Tokio async, 100+ clients |
.tcp().async_mode().with_tls() |
UnifiedAsyncClient |
Secure networks | Certificate-based encryption |
.tcp().async_mode().with_reconnect() |
UnifiedAsyncClient |
Unreliable networks | Auto-reconnect with backoff |
.udp() |
UdpClient |
Real-time tracking | Low latency (120+ Hz) |
Use Cases
🔬 Surgical Navigation
// Track surgical tools in real-time with UDP
let mut client = new
.udp
.build?;
loop
🏥 Medical Imaging Pipeline
use ImageMessage;
// Stream CT/MRI scans with compression
let image = new?;
let msg = new?;
client.send.await?;
🔐 Secure Hospital Network
use insecure_tls_config;
use Arc;
// TLS-encrypted communication with auto-reconnection
let tls_config = new;
let reconnect_config = with_max_attempts;
let mut client = new
.tcp
.async_mode
.with_tls
.with_reconnect
.build
.await?;
client.send.await?;
🔄 Robust Production System
// Production-ready client with all features
let client = new
.tcp
.async_mode
.with_tls
.with_reconnect
.verify_crc
.build
.await?;
Supported Message Types
✅ 20/20 message types fully implemented - Complete OpenIGTLink protocol coverage
- TRANSFORM - 4x4 transformation matrices
- POSITION - Position + quaternion orientation
- QTDATA - Quaternion tracking for surgical tools
- TDATA - Transform tracking data (3x4 matrices)
- TRAJECTORY - 3D surgical trajectories
- POINT - Fiducial points for navigation
- IMAGE - 2D/3D medical images (CT/MRI/Ultrasound)
- VIDEO - Video streaming (H.264/VP9/MJPEG/Raw)
- IMGMETA - Image metadata (patient info, modality)
- VIDEOMETA - Video metadata (codec, resolution, bitrate)
- SENSOR - Sensor arrays (force, IMU, etc.)
- NDARRAY - N-dimensional numerical arrays
- POLYDATA - 3D meshes and polygons
- LBMETA - Segmentation labels
- COLORTABLE - Color lookup tables
- STRING - Text messages
- COMMAND - XML commands
- STATUS - Device status
- CAPABILITY - Protocol negotiation
- BIND - Message grouping
Plus 22 query/control messages: GET_, STT_, STP_, RTS_
Examples
📝 Ready-to-run examples covering all features - Browse all examples
🚀 Getting Started
New to OpenIGTLink? Start here:
# 1. Dynamic message receiver (recommended - works with any message type)
# 2. Basic client/server (specific message types)
Key examples:
- async_dynamic_receiver.rs - Start here! Receive any message type dynamically (v0.3.0+)
- dynamic_receiver.rs - Sync version of dynamic receiver
- client.rs - Basic client with specific message types
- server.rs - Basic server example
🏥 Medical Applications
# CT/MRI/Ultrasound streaming
# Real-time video
# Tool tracking at 60-120 Hz
# Fiducial registration
# Force/torque sensors
# IMU data
🔧 Advanced Features
# TLS encryption
# Auto-reconnection
# Multi-client server
# Image compression (98-99% ratio)
# UDP low-latency
# Message queuing
# Query & streaming control
# Connect to remote Slicer
📊 Testing & Benchmarks
RUST_LOG=debug
Performance
Real-world benchmarks on Apple M1:
Operation | Performance | Details |
---|---|---|
Message Throughput | 10,000+ msg/sec | TRANSFORM, STATUS messages |
Image Encoding | ~50ms | 512×512×100 CT scan (16-bit) |
Compression | 98-99% | Medical images (Deflate) |
UDP Latency | <1ms RTT | TRANSFORM messages |
Concurrency | 100+ clients | Single async thread |
Run benchmarks:
Compatibility
🔗 Interoperability
- ✅ OpenIGTLink C++ 3.0+ - 100% binary compatible
- ✅ 3D Slicer - Medical imaging platform
- ✅ PLUS Toolkit - Image-guided intervention
🦀 Rust Support
- MSRV: Rust 1.70+
- Platforms: Linux, macOS, Windows
Documentation & Resources
- 📚 API Docs - Complete API reference
- 📖 Examples - 27 practical examples
- 🔍 Query Guide - Streaming control protocol
- 📊 Benchmarks - Performance analysis
- 🌐 OpenIGTLink Protocol - Official specification
Contributing
Contributions welcome! Feel free to:
- 🐛 Report bugs via issues
- 💡 Suggest features or improvements
- 🔧 Submit pull requests
Project Status
✅ Production-ready - Used in real surgical navigation systems
Metric | Status |
---|---|
Message Types | 20/20 ✅ |
Query/Control | 22/22 ✅ |
Tests | 102 passing ✅ |
C++ Compatibility | 100% ✅ |
Documentation | Complete ✅ |
License
MIT License - See LICENSE for details
⭐ Star on GitHub • 📦 View on crates.io • 📚 Read the Docs
Built with ❤️ for the medical robotics community