IRL Molecular Builder Prototype (Legacy)

This version of the software exists for archival purposes. Please see the updated software at https://irl.itch.io/narupa-builder.

A VR Molecular Builder

IRL Molecular Builder is a companion application to NarupaXR, allowing you to build, design and edit molecules in VR. It is open source under GPL license: you can contribute to development over at the Narupa Builder Gitlab repository. 

Any bugs or issues should be reported to the issue board on the Gitlab repository. 

User Guide

We recommend that the controller with the menus is on the left hand for right-handed people, and vice-versa for left-handed people.

To interact with the menu, point the right controller to the left controller and select the tool with the laser pointer by clicking the trigger button.  (or vice-versa for left-handed people)

Right Menu

Create

• Creates a new atom in the scene. To do this, press the trigger button on the non-menu controller.

• If an existing atom is highlighted, replaces its element with the currently selected one.

Connect

• Connects 2 atoms by creating a bond between them. If the atoms are already connected, it updates the bond type to a double bond, and if the atoms are double bonded, it updates the bond to triple bond.
• Clicking on 2 placeholder atoms, or one placeholder atom and an atom, will connect the parent of the first placeholder with the parent of the second one.
• Cannot connect an atom with itself.

Change Bond

• Changes the bond type incrementally. 
• If the bond is triple, it will be changed to a single bond.

Rotate Bond

• Rotates an atom and all of its connections, using a bond as a pivot.
• A bond needs to first be selected as a pivot point of the rotation, followed by selecting one of the atoms at one side of the bond. All atoms connected to the selected atom will also be rotated in sync
• Cannot rotate if the selected bond and atom are part of a cycle.

Delete

• In single select mode, can choose between deleting atoms or bonds. To delete an object, hover over them and click the trigger button.
• In multi select mode, deletes all the selected atoms.

Move

• Can select between 2 modes: Move Selection and Move Fragment.

• Move Selection: in single select mode, move a single atom, together with its placeholders if it has any. In multi select mode, it moves all selected atoms.

• Move Fragment: moves a molecule/fragment of atoms. Atoms need to be connected to be considered a single fragment, otherwise they will be treated as separate structure.

Front Menu

Elements

• Opens a list of common elements.
• Clicking '...' will open the periodic table.

Minimize

• Calls Open Babel to minimize the atoms in the scene. 
• Open Babel needs to be installed for this to work.
• Large molecules can cause this to take a long  time to finish.
• Note: Minimize can NOT be undone and clears the undo history.

Single Select

• Only one atom can be manipulated at a time.

Multi Select

• Allows for selection of multiple atoms at the same time.
• To select atoms, hover over them with the controller and press the trigger button
• The selected atoms can be operated on, for example they can be deleted or moved.
• Some actions are not possible to perform in this mode, such as creation or connection. Clicking on these actions will re-activate single selection.

Clear Selection

• Deselects all selected atoms.

Left Menu

Undo/Redo

• Undo/redo the last action.
• Cannot undo import, export and minimization.

Clear All

• Deletes all objects in the scene.

Fill

• Replaces all placeholders with Hydrogen atoms.

File

• Can select between 3 options: Import, Export and Quit Application.
• Import: Imports a file from external sources. Currently accepts .pdb and .xyz formats.
• Export: Exports all atoms in the scene. Can export to either .pdb or .xyz file formats.
• Quit Application: Closes the builder application.

Debug Log

• Shows chemistry errors in the scene.
• Currently only shows if an atom has more connections than usual.
• Highlights the object where the error happens and displays a message on top of the non-menu controller.
• Press the debug log button again to close it.
• If the error is resolved, clicking on the button again will show a new error, if any are present.

Additional Controls

• By holding the grip button on any of the controllers, the scene can be translated and rotated. By holding both buttons at the same time, scaling is also possible.
• By pressing the menu button on the controller without the UI, the Move Selection tool can quickly be accessed. Pressing it a second time will reselect whatever tool the player was using before that.
• The menu button on the controller with the UI can be used to collapse the menu panels.
• On the controller with the UI, pressing the left and right arrows on the touchpad will rotate the menu panels.