Python Quickstart#

Overview#

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.

Prerequisites#

Windows#

As of release 11.0.4.0b, the Python SDK for Windows has been updated to target Python 3.10. Users with Python SDK versions prior to 11.0.4.0b 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
11.0.4.0b or newer	Windows 10 and newer	x64	Python 3.10
11.0.4.0 or older	Windows 10 and newer	x86	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: https://www.python.org/downloads/

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)]

Warning

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.

Linux#

As of release 11.0.5.0 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
11.0.5.0 or newer	Ubuntu 20.04 LTS	x86_64	Python 3.8
11.0.4.0 or older	Ubuntu 18.04 LTS	x86_64	Python 3.6

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

python3 MTIDevice-Demo.py

Dependencies#

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

These will also be downloaded upon running the InstallDependencies.py

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

Windows

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

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

python InstallDependencies.py

Linux

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.

MTIDevice-Demo.py

Python translation of the C++ MTIDevice-Demo, showcases multiple drive methodologies

TrackingExamples.py

For owners of the tracking bundle add-on or DEMO-01, demonstrates mutliple approaches tracking using MEMS mirrors.
Not runnable directly, run via MTIDevice-Demo.py

RGBExamples.py

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

GenerateTextData-Demo.py

A unique Python demo that demonstrates the versatility of the Mirrorcle API when paired with the Python language

Demo-Template.py

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:

python MTIDevice-Demo.py

For Linux users:

python3 MTIDevice-Demo.py

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 source.py).

For Windows users that want to install the mtidevice module to their Python site-packages, the SDK folder contains a setup.py 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.

Warning

Running the setup.py 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 setup.py 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.