Python Quickstart#


Mirrorcle’s Python API is wrapped from C++ to Python using the Simplified Wrapper and Interface Generator (SWIG).

This means that all classes, structs, and methods that are available in Mirrorcle’s C++ library are also available in Python! The key difference is that the Python API uses NumPy for handling arrays instead of C-style arrays and pointers.



As of release, the Python SDK for Windows has been updated to target Python 3.10. Users with Python SDK versions prior to should use 32-bit builds of Python 3.7, unless a 64-bit build was specifically requested & provided.

Python SDK Version

Operating System

Default Target Arch.

Required Python Version or newer

Windows 10 and newer


Python 3.10 or older

Windows 10 and newer


Python 3.7

Mirrorcle’s Python SDK for Windows requires a 64-bit build of Python 3.10. Ensure that you have installed 64-bit Python 3.10 to your system and have added Python to your Environment Variables -> Path

For the latest version of Python 3.10, please see Python releases:

This can be checked by running the below line in your Command Prompt

python -VV

Which should return a Python version greater than 3.x.x, and a 64-bit target build system. For example:

Python 3.10.9 (tags/v3.10.9:1dd9be6, Dec  6 2022, 20:01:21) [MSC v.1934 64 bit (AMD64)]


Debug versions of Python require that the mtidevice/_MTIDevice.pyd file be copied and renamed to _MTIDevice_d.pyd, otherwise Python will not be able to find and load the _MTIDevice.pyd library.


As of release the Python SDK for Linux targets Ubuntu 20.04 LTS on x86_64 architecture machines. A legacy version built for Ubuntu 18.04 LTS is also maintained and available upon request.

Python SDK Version

Operating System

Target Arch.

Required Python Version or newer

Ubuntu 20.04 LTS


Python 3.8 or older

Ubuntu 18.04 LTS


Python 3.6

Often Ubuntu systems will have both Python 2 and Python 3 installed. To differentiate use python3 to specify Python 3



To run the examples, numpy, OpenCV-Python, and freetype-py are required.

These will also be downloaded upon running the

Additionally, these packages can be installed using pip (Python package installer):


python -m pip install numpy
python -m pip install opencv-python
python -m pip install freetype-py

The script is provided to quickly install these three Python modules via pip, and can be run from the command prompt/terminal:



The Linux version of the SDK has an additional dependence on pynput for handling keystrokes in the demos.

pip3 install numpy
pip3 install opencv-python
pip3 install freetype-py
pip3 install pynput

Running the Provided Demos#

Mirrorcle’s Python SDK comes as a folder labeled “Python SDK X.X.X.X”. Inside that directory is the SDK-Python folder. It is recommended to copy the SDK-Python folder to your C:MirrorcleTechfolder which was created after installing the Mirrorcle Software Suite. If a different directory was chosen during the Mirrorcle Software Suite installation process, it is recommended to copy the SDK-Python folder to that directory, instead.

Inside the SDK-Python folder, there are five demo files.
  • Python translation of the C++ MTIDevice-Demo, showcases multiple drive methodologies
  • For owners of the tracking bundle add-on or DEMO-01, demonstrates mutliple approaches tracking using MEMS mirrors.

  • Not runnable directly, run via
  • Demonstrates interaction with RGB Playzers for multi-color vector display.

  • Not runnable directly, run via
  • A unique Python demo that demonstrates the versatility of the Mirrorcle API when paired with the Python language
  • A template for users to write their own demos. The template handles connection, loading parameters, and disconnecting.

In order to run the demos, navigate to the SDK-Python folder using your shell (command prompt on Windows, terminal on Linux) or IDE of choice.

For Windows users:


For Linux users:


Installing the mtidevice Module#

For both Windows and Linux users, the recommended method to integrating Mirrorcle’s mtidevice Python package into your project is to place the “mtidevice” folder in your project’s folder (i.e. in the same folder as your

For Windows users that want to install the mtidevice module to their Python site-packages, the SDK folder contains a file to allow for installation of the mtidevice module. Installing the mtidevice module to your site-packages allows the module to be accessible regardless of the current working directory of the Python, but it can lead to confusion when installed to the global Python installation. See the warning below.


Running the script to install to the Python site-packages is NOT recommended unless using a virtual environment or conda environment.

To install to your Python installation’s site-packages, run the following:

python install

Then see the “Importing the Module” section below.

Importing the Module#

Independent of the chosen installation method.

import mtidevice
from mtidevice import MTIError, MTIAxes, MTIParam, MTIDataMode, MTISync, MTIDataFormat

Using the Python SDK with RGB Playzer#

For users of RGB Playzer, some function calls have been modified for support in the Python SDK:

  • Where users want to write one value to the entire m_iRGBData` array, MTIDevice.SetRGBData() should be used.

  • Where users want to set set the m_iRGBData` array individually, MTIDevice.SetRGBData_array() should be used.