QTM Motion Tracking System

A comprehensive motion tracking system using Qualisys Track Manager (QTM) for real-time 6DOF tracking with monitoring and logging capabilities.

📁 Project Structure

motion-tracking/
├── config/                          # Configuration files
│   └── qtm_config.py               # Main configuration settings
├── data/                           # Output data directory
│   ├── new.csv                     # Main tracking data output
│   ├── qtm_config.json            # Saved configuration (auto-generated)
│   ├── qtm_system_info.json       # QTM system information (auto-generated)
│   ├── qtm_parameters.xml         # QTM parameters (auto-generated)
│   ├── monitoring_logs.json       # Monitoring data (auto-generated)
│   └── monitoring_summary.txt     # Human-readable monitoring summary (auto-generated)
├── src/                           # Source code
│   ├── qtm_data_export.py         # Main data collection script
│   ├── test_qtm_connection.py     # QTM connection test script
│   ├── test_file_saving.py        # File saving functionality test
│   └── test_monitoring_events.py  # Monitoring events test
├── utils/                         # Utility modules
│   ├── qtm_handlers.py            # QTM data handling functions
│   ├── qtm_settings.py            # QTM system information utilities
│   └── savers.py                  # File saving utilities
├── requirements.txt               # Python dependencies
└── README.md                     # This file

🚀 Quick Start

Prerequisites

1. Python 3.8+ installed
2. QTM Server running and accessible
3. Network access to QTM server

Installation

1. Clone or download:

   git clone https://github.com/sensint/motion-tracking.git

2. Install dependencies:

   pip install -r requirements.txt

3. Configure QTM connection in config/qtm_config.py:

   QTM_HOST = '139.19.40.134'  # Your QTM server IP

   or for local host:

   QTM_HOST = '127.0.0.1'

Basic Usage

1. Test QTM connection:

   python src/test_qtm_connection.py

2. Run data collection:

   python src/qtm_data_export.py

UDP Streaming

The system supports real-time UDP streaming of QTM tracking data. This allows you to broadcast or multicast tracking data to other applications or devices on your network in real time.

How It Works

• Data is streamed as CSV-formatted rows, matching the CSV output.
• UDP streaming is controlled by the STREAM and LOG flags in config/qtm_config.py.
• By default, data is sent to the multicast address 224.1.1.1:5005, but you can set any IP/port.
• Both src/qtm_data_export.py and src/qtm_data_export_stream.py support UDP streaming.

Configuration

In config/qtm_config.py:

STREAM = True         # Enable UDP streaming
LOG = False           # Disable file logging (set True to log to CSV as well)
UDP_IP = '224.1.1.1'  # Multicast address (or use a specific IP or broadcast address)
UDP_PORT = 5005       # UDP port

Running the Streamer

To stream QTM data over UDP:

python src/qtm_data_export.py
# or
python src/qtm_data_export_stream.py

Receiving the Stream

A reference UDP receiver is provided:

python src/udp_receiver.py

This will print all received tracking data to the console. You can adapt this script to process or save the data as needed.

Configuration

Main Configuration (config/qtm_config.py)

Connection Settings

QTM_HOST = '139.19.40.134'              # QTM server IP address
QTM_CONNECTION_TIMEOUT = 10              # Connection timeout (seconds)
WARMUP_TIME = 2                          # Warmup period (seconds)
MONITORING_WARMUP_EXTRA = 0.5            # Extra monitoring warmup (seconds)

Capture Settings

TRACKING_COMPONENT = ['6d']              # Tracking type: '3d', '6d', or both
DURATION_SECONDS = 10                    # Recording duration (seconds)
TARGET_BODY_NAME = 'pen_27_06'           # Specific body to track (None = all)
rotation_type = 'matrix'                 # Rotation format: 'matrix' or 'quaternion'

Sampling Settings

SAMPLE = True                            # Enable/disable sampling
SAMPLE_FREQ = 100                        # Sampling frequency (Hz)
RATE_CHECK_INTERVAL = 1.0                # Rate monitoring interval (seconds)
NAN_CHECK_INTERVAL = 5.0                 # NaN monitoring interval (seconds)
RATE_DROP_SOFT_THRESHOLD = 90            # Soft rate drop warning (%)
RATE_DROP_HARD_THRESHOLD = 50            # Hard rate drop error (%)
NAN_THRESHOLD = 10                       # NaN rate warning threshold (%)

Output Settings

OUTPUT_FOLDER = '../data/'               # Output directory
FILE_NAME = 'new.csv'                    # Main data file name
CSV_HEADER = ['time_python(ms)', 'qtm_x', 'qtm_y', 'qtm_z', 'qtm_rot']  # CSV headers
STREAM = True                            # Enable UDP streaming
LOG = False                              # Enable/disable file logging
UDP_IP = '224.1.1.1'                     # UDP target IP (multicast/broadcast/unicast)
UDP_PORT = 5005                          # UDP target port

📊 Data Collection

Main Script: src/qtm_data_export.py

This is the primary data collection script that:

1. Connects to QTM and retrieves system information
2. Saves configuration and system parameters to files
3. Streams tracking data in real-time (to file and/or UDP, depending on config)
4. Monitors performance and logs events
5. Saves comprehensive logs including:
   • Real-time monitoring events
   • Performance statistics
   • System configuration
   • QTM parameters

Output Files

After running data collection, the following files are created in the data/ directory:

new.csv - Main Tracking Data

time_python(ms),qtm_x,qtm_y,qtm_z,qtm_rot
0.0,123.456,789.012,345.678,"(1.0,0.0,0.0,0.0,1.0,0.0,0.0,0.0,1.0)"
10.0,123.457,789.013,345.679,"(1.0,0.0,0.0,0.0,1.0,0.0,0.0,0.0,1.0)"
...

qtm_config.json - Configuration Snapshot

{
  "connection_settings": {
    "qtm_host": "139.19.40.134",
    "connection_timeout": 10,
    "warmup_time": 2
  },
  "capture_settings": {
    "tracking_component": ["6d"],
    "duration_seconds": 10,
    "target_body_name": "pen_27_06"
  },
  "sampling_settings": {
    "sample": true,
    "sample_freq": 100
  },
  "timestamp": "2024-01-15T10:30:00.123456"
}

monitoring_summary.txt - Human-Readable Summary

=== QTM Data Collection Monitoring Summary ===

Collection Date: 2024-01-15 10:30:00
Duration: 10 seconds
Expected Sampling Frequency: 100 Hz
Total Samples Logged: 950
Total NaN Samples: 5 (0.5%)
Actual Logging Rate: 95.0 Hz (95.0% of expected 100 Hz)
QTM Capture Frequency: 1400 Hz

=== Real-Time Monitoring Logs ===
[2024-01-15 10:30:03.123] Rate Check: 95 samples in 1.0s = 95.0 Hz (95.0% of expected 100 Hz)
  WARNING: Logging rate is 95.0% of expected rate!
[2024-01-15 10:30:08.456] NaN Check: 2/475 samples are NaN (0.4%)

=== Final Performance Assessment ===
✓ Final logging rate is within acceptable range
✓ Final NaN rate is within acceptable range

🔧 Testing and Validation

Connection Test

python src/test_qtm_connection.py

Tests QTM connectivity and basic communication.

File Saving Test

python src/test_file_saving.py

Tests file saving functionality without QTM connection.

Monitoring Events Test

python src/test_monitoring_events.py

Tests monitoring event capture functionality.

📈 Monitoring and Performance

Real-Time Monitoring

The system continuously monitors:

1. Logging Rate: Compares actual vs expected sampling rate
2. Data Quality: Tracks NaN values and data integrity
3. System Performance: Monitors QTM capture frequency

Real-Time Frequency Retrieval

The system can retrieve the actual QTM capture frequency using multiple methods:

1. Direct API Method: await conn.get_capture_frequency()
2. XML Parameters: Parses QTM XML parameters for frequency
3. Packet Timing: Estimates frequency from packet arrival times
4. Real-Time Monitoring: Tracks actual logging rates vs expected rates

The system automatically detects frequency mismatches and provides warnings when:

• Configured sampling frequency > QTM capture frequency
• Configured sampling frequency < QTM capture frequency (downsampling)

Performance Thresholds

• Soft Warning: < 90% of expected rate
• Hard Error: < 50% of expected rate
• NaN Warning: > 10% NaN values

Monitoring Events

Each monitoring check creates an event with:

• Timestamp
• Event type (rate_check, nan_check)
• Performance metrics
• Warnings/errors

Note: Monitoring events are captured in real-time and stored in the monitoring_logs.json file. The system uses a global variable to ensure events are not lost when the monitoring task is cancelled.

🛠️ Troubleshooting

Common Issues

1. Connection Timeout

   • Check QTM server is running
   • Verify IP address in config
   • Check network connectivity
   • Ensure QTM allows remote connections

2. No Data Received

   • Verify cameras are in preview mode
   • Check tracking components are enabled
   • Ensure target body exists in QTM

3. Low Sampling Rate

   • Check QTM capture frequency vs configured rate
   • Verify network bandwidth
   • Check system resources

4. High NaN Rate

   • Check marker visibility
   • Verify camera calibration
   • Check tracking settings

5. Empty Monitoring Events

   • This issue has been fixed in recent updates
   • Monitoring events are now captured using a global variable
   • Events are preserved even when tasks are cancelled
   • Check monitoring_logs.json for captured events

Debug Information

The system provides extensive debug information:

• Connection status and QTM version
• System parameters and available components
• Real-time monitoring with timestamps
• Performance statistics and warnings
• Comprehensive logs saved to files

📋 Dependencies

Required Packages

qtm-rt                    # QTM real-time client
asyncio                   # Asynchronous I/O (Python standard library)
csv                       # CSV file handling (Python standard library)
json                      # JSON handling (Python standard library)
xml.etree.ElementTree     # XML parsing (Python standard library)

Installation

pip install qtm-rt

🔄 Workflow

1. Setup: Configure QTM server and tracking setup
2. Configure: Adjust settings in config/qtm_config.py
3. Test: Run connection and functionality tests
4. Collect: Run main data collection script
5. Analyze: Review monitoring logs and performance data
6. Process: Use collected data for analysis

📝 File Descriptions

Configuration Files

• config/qtm_config.py: Main configuration settings
• config/params.xml: QTM system parameters (auto-generated)

Source Files

• src/qtm_data_export.py: Main data collection script (supports UDP streaming)
• src/qtm_data_export_stream.py: Alternative data collection script (also supports UDP streaming)
• src/udp_receiver.py: Example UDP receiver for streamed data
• src/test_qtm_connection.py: Connection testing
• src/test_file_saving.py: File saving tests
• src/test_monitoring_events.py: Monitoring tests

Utility Files

• utils/qtm_handlers.py: Data processing functions
• utils/qtm_settings.py: System information utilities
• utils/savers.py: File saving utilities

Output Files

• data/new.csv: Main tracking data
• data/qtm_config.json: Configuration snapshot
• data/qtm_system_info.json: System information
• data/qtm_parameters.xml: QTM parameters
• data/monitoring_logs.json: Monitoring data
• data/monitoring_summary.txt: Human-readable summary

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

🆘 Support

For issues and questions:

1. Check QTM documentation
2. Their Python API repository
3. Create an issue with detailed information
4. Or contact me at: [email protected]

---