UnityMol Reference Documentation

UnityMol is a molecular visualization software built on the Unity3D game engine, providing researchers, educators, and students with an interactive and immersive platform for exploring molecular structures and dynamics across multiple scales. It offers high-quality, real-time rendering, cross-platform compatibility, virtual reality (VR) and augmented reality (AR) visualization, scripting capabilities, and support for loading and displaying standard molecular file formats using a comprehensive set of representation styles. The software is designed for structural biologists, computational chemists, molecular biophysicists, educators, and students, and includes installation instructions, tutorials, reference guides, and examples for advanced usage scenarios. UnityMol is also compatible with VR environments and has been tested on Windows with HTC Vive & Vive Pro, Quest 2 & Quest 3 using the VIU toolkit with SteamVR as a backend.

The "Quickstart - a practical UnityMol tutorial" provides an introduction to using UnityMol, a molecular viewer that can be used in desktop and virtual reality contexts. The tutorial covers loading molecules, using the selection language, adding representations, adjusting camera settings, aligning proteins, working with bounding boxes and topology information, measuring distances, exploring docking modes, recording screenshots and videos, using keyboard shortcuts, scripting, and more advanced features such as virtual reality, multiplayer, interactive molecular dynamics (IMD), and potential maps. The tutorial includes step-by-step instructions for using the various menus, buttons, and input fields within UnityMol's interface.

The selection language used in UnityMol is based on the MDAnalysis library, allowing for various selections using keywords such as chain, atomid, and ss for secondary structures. Some MDAnalysis keywords are unsupported or limited in UnityMol, but many geometric criteria can still be utilized through keywords like within, insphere, and inrect. Examples of selections include selecting all atoms in helices, sheets, or coils, as well as atoms within a certain distance or inside a specific shape or volume.

The UnityMolX software allows for easy screenshot and video capture through the use of commands and settings, with options to adjust resolution, transparency, framerate, and pause/unpause functionality during recording. However, some parts of FFMPEG used in video recording are licensed under the GPL, which should be considered legally.

UnityMol, a molecular visualization software, provides keyboard and mouse shortcuts for efficient usage. The document outlines the Emacs-style notation used for keyboard shortcuts, general mouse actions such as rotating, zooming, and translating molecules, as well as general keyboard shortcuts for functions like resetting position, labeling atom information, setting measuring points, and toggling UI displays. In addition, it mentions the implementation of basic abbreviations in the Python console for editing convenience. These features enable users to interact with UnityMol efficiently and intuitively through various input devices.

The Python console is integrated into UnityMolX using IronPython, allowing for the use of C# and Unity classes/methods without needing to define all bindings. While not all Python modules are available, an API defines accessible UI actions through commands such as loading structures, selecting and hiding objects, changing their color and visibility, taking screenshots or recording videos, connecting to remote servers, and more. The console can be shown and hidden using a keyboard shortcut.

The Python Scripting Cookbook provided by UnityMol offers a collection of useful patterns for automating and simplifying common workflows using scripting with IronPython. It includes recipes from the UnityMolCommons library, such as q() to exit UnityMol, info() for general information about version and build, All() to use a selection with all atoms, setTrajFramerate() to set trajectory playback speed, and nameRes() to retrieve residue names in a selection. These functions can be used either without arguments or with specified structure references. The cookbook aims to facilitate work by collecting these patterns.

The docking mode in UnityMol, developed by João Rodriguez and Xavier Martinez at Stanford University, enables protein docking simulations in both desktop and virtual reality environments using the AMBER force field. It involves computing potential energy through a separate thread, which displays the last computed value. The code is implemented in C++ but a C# alternative exists for platforms without the OptimizedNBEnergyCalculation shared library. Ignoring specific structures or modifying colliders and scaling factors are possible, and saved docking conformations can be obtained using the UI menu or through a command-line function. Collisions between alpha carbons and red circles on contacting atoms facilitate interaction. Future improvements include better handling of energy variations during slight molecule movements and customizable collider creation based on residue or atom names.

This document introduces the virtual reality (VR) version of UnityMol, which is only compatible with Windows operating systems and has been tested with HTC Vive & Vive Pro as well as Quest 2 & Quest 3 headsets. The setup requires Steam and SteamVR, and while Quest headsets are supported, the Meta Quest link application is not. In the virtual room environment, elements such as floors, ceilings, and walls have been added to reduce motion sickness. Controllers for both HTC and Quest devices have been mapped in this version.

UnityMol's Multiplayer mode allows multiple users to simultaneously access and manipulate molecular structures within a shared scene using either Virtual Reality (VR) or desktop modes. Each participant is represented by a 3D head model, and communication can be enhanced with voice support through Photon Voice 2 library. Position synchronization and API calls are sent over the network, requiring shared access to molecular structure resources. The first user initiating the session has ownership rights, which may be transferred via a request feature. Non-VR users join the VR scene with a head model attached to their camera, allowing for movement using keyboard controls.