Miranda is a GUI tool for calibrating eye and head tracker input to match your screen gaze. It enables seamless integration with other applications, allowing you to use your calibrated tracker data in various ways.
For example, you can use Opentrack as an input source, calibrate your head rotation to your screen, and output the data as UDP messages. This enables you to control applications like OptiKey with your head movements.
Install Python >=3.12.6 and Pip. Then load the dependencies and run main.py:
pip install -r requirements.txt
python main.py
Alternatively, you may also use uv to run Miranda:
uv run --with-requirements requirements.txt main.py [miranda args]
pip install PyInstaller
PyInstaller .\Miranda.spec
In short, data comes from a data source, this data will be translated into mouse movements using a tracking approach, and these mouse movements will be published for further usage. Every data source and tracking approach combination needs a calibration first.
A data source is where eye and head tracking data comes from. The data could be the yaw and pitch rotation of your eyes in degrees. The data source is mostly a different application, that needs to run alongside Miranda. Since the data itself gives no indication of where the user is looking at or how the mouse cursor shall be moved, we need a tracking approach.
A tracking approach tells how the data from the data source shall be translated into a mouse movement. There are two approaches:
- Gaze on Screen: The user is directly looking at the screen. The cursor shall follow the gaze. This is the most straight-forward and probably mostly used approach.
- D-Pad: This approach is a good alternative if your input device is not accurate enough for the Gaze on Screen approach. Usually, a D-pad is a flat, typically thumb-operated, directional control. Likewise with this approach the cursor is looking at a d-pad to steer the cursor. E.g. by looking at the "up" arrow, the cursor moves up.
Before we can translate the data from the data source into mouse movements, we need to do a calibration first. Every data source and tracking approach combination needs its own calibration. Once such a calibration is done the result will be stored and is available on the next start of Miranda.
Publishers take the mouse movements created by the tracking approach and publish them for further usage of other applications. Currently there is just the UDP-Publisher, which publishes the mouse coordinates via UDP to 127.0.0.1 port 9999 in the following format:
# example
{"x": 173, "y": 432, "timestamp": "2024-11-14 00:56:42.308879"}
This application uses Open Source components. You can find the source code of their open source projects along with license information below. We acknowledge and are grateful to these developers for their contributions to open source.
- Copyright (c) 2005-2025 NumPy Developers
- BSD 3-Clause License
- Copyright (c) 2015 Marcin Kurczewski
- MIT License
- Copyright (c) 1997-2011 by Secret Labs AB
- Copyright (c) 1995-2011 by Fredrik Lundh and contributors
- Copyright (c) 2010 by Jeffrey A. Clark and contributors
- MIT-CMU License
- Copyright (c) 2014 Al Sweigart
- BSD 3-Clause License
- Copyright (C) 2008-2011 INADA Naoki songofacandy@gmail.com
- Apache License 2.0
- Copyright (c) 2009-2012, Brian Granger, Min Ragan-Kelley
- BSD 3-Clause License