Qualisys PySide6 SDK

PySide6-based SDK for the Qualisys Real-Time (RT) protocol. Stream motion capture data from QTM using Qt's native networking and signals/slots.

Installation

Requires Python 3.10+ and PySide6 6.0+.

We recommend using a virtual environment to avoid conflicts with other packages:

# Create and activate a virtual environment
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

Then install the package:

pip install qtm-rt-pyside6

Quick Start

import sys
from PySide6.QtCore import QCoreApplication
from qtm_rt_pyside6 import QTMConnection, QRTPacket

def on_packet(packet: QRTPacket):
    print(f"Frame {packet.framenumber}")
    result = packet.get_3d_markers()
    if result:
        header, markers = result
        for marker in markers:
            print(f"  {marker.x}, {marker.y}, {marker.z}")

app = QCoreApplication(sys.argv)

connection = QTMConnection()
connection.connected.connect(lambda: connection.streamFrames(["3d"]))
connection.packetReceived.connect(on_packet)
connection.error.connect(lambda msg: print(f"Error: {msg}"))
connection.connectToHost("127.0.0.1")

sys.exit(app.exec())

API

QTMConnection Signals

QTMConnection Methods

Core methods to get started:

• connectToHost(host, port=22223, version="1.25", timeout_ms=5000) — Connect to QTM
• disconnectFromHost() — Close the connection
• streamFrames(components, frames="allframes", udp_port=None, udp_address=None) — Start streaming; pass udp_port to receive frames over UDP instead of TCP
• streamFramesStop() — Stop streaming
• getParameters(parameters) — Request current configuration as XML

See the class docstring or run help(QTMConnection) for the full method list — control, load/save, trigger, LED, quit, XML settings, etc.

Components

Valid streaming components: 2d, 2dlin, 3d, 3dres, 3dnolabels, 3dnolabelsres, analog, analogsingle, force, forcesingle, 6d, 6dres, 6deuler, 6deulerres, gazevector, eyetracker, image, timecode, skeleton, skeleton:global

Examples

Ready-to-run scripts live in examples/ — see examples/README.md for what each one demonstrates and how to run it. basic_example.py is the shortest path to verify your setup; the GUI examples (gui_example.py and gui_3d_example/) show how to wire the SDK into a desktop application.

Known Limitations

• No automatic reconnection. If the connection drops, you must call connectToHost() again. Listen to the disconnected signal to detect this.
• Single-threaded. QTMConnection and QTMDiscovery are QObject subclasses and must be used from the thread that created them (typically the main thread). Use Qt signals for cross-thread communication.
• Password sent in plain text. takeControl(password) transmits the password unencrypted over TCP. This is a QTM protocol limitation — use on trusted networks only.

Development

To work on the SDK itself:

git clone https://github.com/qualisys/qualisys_pyside6_sdk.git
cd qualisys_pyside6_sdk

# Create and activate a virtual environment
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

# Install dev dependencies (pytest, pytest-qt, ruff, build) and the package
pip install -r requirements-dev.txt
pip install -e .

Run tests and linting:

pytest -v
ruff check .
ruff format --check .

License

MIT — see LICENSE and THIRD_PARTY_LICENSES.