This is a tutorial about how to use Qualisys Motion Capture System. This repo includes the usage and the example codes for Qualisys Python and C++ SDK, and MATLAB.
-
The configuration settings are all in a JSON file mocap_config.json. The changes in mocap_config.json affect all the codes here, so you don't have to change them manually in every single file or compile it every time after you change the settings.
-
The following are the meanings of each element.
- "IP_SERVER" is the IP address for the desktop that connects to the motion capture system. It shouldn't change.
- "NAME_SINGLE_BODY" is the rigid body name you define in QTM. You can have multiple names in this file. But you need to change your codes accordingly to get data for different rigid bodies.
- "NAME_FILE_LOADED_QTM" is the file path to load recorded motion capture data, and stream in real-time. (I need to test this recorded data playback functionality. - Sept 09, 2020)
- "FLAG_REALTIME" is the flag to stream real-time data ("1") or recorded data ("0").
- "HOST_UDP" is the IP address of the UDP socket.
- "PORT_UDP" is the port number of the UDP socket.
- "DATA_BYTES_LENGTH_UDP" is the number of bytes you want to send your data via the UDP socket. For example, if I want to send a position in R^3 and a rotation matrix in R^(3*3), there are 12 numbers. If the numbers are all double (float64), each number is 8 bytes and in total is 12*8=96 bytes.
- Download this repo to your local machine. <MAIN_DIRECTORY> is your local main directory of this repo.
$ git clone https://github.com/zehuilu/How-to-Use-Qualisys-Motion-Capture-System-in-AIMS-Lab.git
$ cd <MAIN_DIRECTORY>
- Follow the instructions of qualisys_python_sdk to install the Python SDK. The minimum version of Python is 3.5.3 per Qualisys SDK for Python's documentation. This section also needs numpy to process the data. If you want to use Python with ROS1 or ROS2, please navigate to https://github.com/qualisys/ros-resources. The following commands represent an example of installing numpy and qualisys_python_sdk. It assumes that you already have Python 3 and the latest Python package installer pip. You may need to be the administrator to install it.
$ pip3 install numpy
$ pip3 install qtm
- To get 6-DOF data from Qualisys server and publish it via UDP socket, run the following commands. Note that you can only run this script if processing 6-DOF data in this script is available.
$ cd <MAIN_DIRECTORY>
$ python3 python/streaming_6dof_data.py
- To subscribe the streaming data, run the following commands. The publisher and the subscriber should share the same network with the motion capture server. To subscribe to 6-DOF data via UDP socket:
$ cd <MAIN_DIRECTORY>
$ python3 python/subscriber_6dof_udp.py
- To make multiple devices access to the 6-DOF data, you can use either TCP/IP or UDP socket for communications. More information is available in Tutorial-About-TCP-IP-and-UDP-Communications.
In some robotics applications, there is a faster node publishing sensor data, such as Motion Capture System, and a slower node subscribes to these data and then does some computation. The streaming data gets accumulated in the communication channel and works as First-In-First-Out (FIFO) due to the frequency difference. But the slower node only needs the latest data. So, I customized the UDP Protocol with asyncio so that the subscriber can work as Last-In-First-Out (LIFO).
- Initialize the publisher
$ cd <MAIN_DIRECTORY>
$ python3 python/streaming_6dof_data_asyncio.py
- Initialize the subscriber
$ cd <MAIN_DIRECTORY>
$ python3 python/subscriber_6dof_asyncio.py
-
QTM Connect for MATLAB can stream real-time motion capture data to MATLAB. In addition, we can stream real-time data to MATLAB via UDP socket.
-
Add the whole repo to your MATLAB path.
-
Run a publisher to stream data. For example,
$ cd <MAIN_DIRECTORY>
$ python3 python/streaming_6dof_data.py
-
Run subscriber_6dof_udp_matlab.m. This can be done from multiple platforms and on different machines, as long as they share the same network with the motion capture server.
-
To make multiple devices access to the 6-DOF data, you can use either TCP/IP or UDP socket for communications. More information is available in Tutorial-About-TCP-IP-and-UDP-Communications.
-
I prefer to use CMake to build C++ projects in Linux and Windows.
-
Follow the instructions of qualisys_cpp_sdk to download the SDK.
$ cd <MAIN_DIRECTORY>
$ git clone https://github.com/qualisys/qualisys_cpp_sdk.git
- Follow the instructions below to build the package.
For Linux:
cd qualisys_cpp_sdk
mkdir build
cd build
cmake .. -DBUILD_EXAMPLES=ON
cmake --build .
For Windows, Open Developer Command Prompt for VS:
cd /d <YOUR_QUALISYS_CPP_SDK>
mkdir build
cd build
cmake .. -DBUILD_EXAMPLES=ON
MSBuild qualisys_cpp_sdk.sln
.\Debug\RigidBodyStreaming.exe