Site menu:

PyMOL mControl - Mobile Controller for Molecular Visualization  

PyMOL is a widely-used molecular structure visualization program for scientific research and education utilizing the conventional mouse and keyboard devices as input. With the PyMOL mControl program, users can perform viewing control of molecular objects using their mobile devices. Three sensor technologies equipped in the mobile device - accelerometer, gyroscope, and touch-screen - are utilized to accurately capture user's motions which will be translated and communicated to the PyMOL software for updating the spatial orientation of the molecular objects. Three viewing controls - translation, rotation, and zooming - as well as commonly used operations such as atom selection, changing display style, coloring, saving scenes, etc. are also supported.

Version 1.0 (6 Nov 2015)


(Freely available for academic use only, please read our Open Source License) 

Platform and Software Requirements

To work properly, the mControl plugin requires PyMOL and Python with Tkinter. The mControl mobile app client running on the user's mobile device requires a web browser supporting WebSocket (check out the compatibility table) and accessible to sensor events.

Based on our tests, the support of certain platform/browser of sensor events are as follows (Y for yes, N for no):
Viewing control         iOS                 Android      Chrome for Android
XY-Rotation  Y Y Y
Z-Rotation Y N N
Zooming Y N N
Translation Y Y Y

So, currently the only solution for running fully functional mobile control in Android-based platforms would be to implement it in native app. This would be considered as part of the future work.


The PyMOL mControl server plugin:
1. Open PyMOL
2. From the menu bar, select: Plugin -> Plugin Manager -> Install New Plugin
3. Select
4. If the installation is successful, the plugin will be available in the Plugin menu as Mobile Control (Some PyMOL versions may need to restart to begin using the new plugin)

The mobile app client:
1. Open the web browser in your mobile device
2. Visit
3. Go to the Output tab, select Add to Home Screen option
4. If the installation is successful, you will see the mControl mobile app logo in the home screen

Connection setup

The mControl plugin functions as a server to allow connection from mobile clients. A typical use would be having both the server and the client devices physically located in the same local area network.
To start the server:
1. Launch PyMOL
2. Load a molecule of your interest
3. Select Plugin -> mControl, click on the Open Server button to start the server. Note that the IP address of the server is displayed in the plugin windows.

To begin using mobile app client:
1. Launch the mobile app
2. Enter the server's IP address to begin connection
3. If connected, the main control page is displayed

Note that the orientation of the mobile device should be in the landscape mode to function properly.

Quick Usage Instructions

XY-Rotation Z-Rotation Zooming Translation


Wendy W. T. Lam and Shirley W. I. Siu, "PyMOL mControl: manipulating molecular visualization with mobile devices"

Contact Us

Developer: Wendy W. T. Lam lamwunteng_[at]_gmail_[dot]_com
Project P.I.: Shirley W. I. Siu shirley_siu_[at]_umac_[dot]_mo
(please remove all underscores)