ChimeraX docs icon

Command: device, vr

device  device-typestatus ]  device-options

The device command sets modes for certain external devices, where the device-type can be:

The status of a mode can be on (synonyms true, True, 1) or off (synonyms false, False, 0). Device-specific options are described below.

device snavstatus ] [ fly  true | false ] [ speed  factor ]

The command device snav enables manipulation with a SpaceNavigator® 3D mouse from 3Dconnexion. The fly option indicates whether the force applied to the device should be interpreted as acting on the camera (true), where pushing forward zooms in because it moves the camera viewpoint toward the scene, or as acting on the models in the scene (false, default), where pushing forward zooms out because it pushes the models away. In either case, however, it is the camera that actually moves. The speed option sets a sensitivity factor for motion relative to the device (default 1.0). Decreasing the value (for example, to 0.1) reduces sensitivity to give slower motion, whereas increasing the value has the opposite effect. See also: mousemode

vrstatus ] [ mirror  true | false ] [ showControllers  true | false ] [ clickRange  r ] [ gui  tool1[,tool2 ... ]] [ simplifyGraphics  true | false ] [ multishadowAllowed  true | false ] [ roomPosition  matrix | report ]

The vr command (same as device vr) enables a virtual reality mode for systems supported by SteamVR, including HTC Vive, Oculus Rift, and Samsung Odyssey. SteamVR must be installed separately by the user and started before the mode is enabled. In addition, Oculus Rift users should start the Oculus runtime before starting SteamVR. For details and related issues, see ChimeraX virtual reality. See also: vr button, vr roomCamera, meeting, camera, view, making movies

The mirror option indicates whether to show the ChimeraX scene in the desktop graphics window. If true (default), the VR headset right-eye view is shown, with graphics waitForVsync automatically set to false so that VR rendering will not slow down to the desktop rendering rate. If false, no graphics are shown in the desktop display, allowing all graphics computing resources to be dedicated to VR headset rendering. Updating the graphics window can cause flicker in the VR headset because refreshing the computer display (nominally 60 times per second) slows rendering to headset. ChimeraX turns off syncing to vertical refresh if possible. Another way to mirror is to use SteamVR's menu entry to display mirror window.

The showControllers option (default true) shows representations of the hand controllers in the scene. Not showing the representations may be useful to avoid time-consuming calculations of the shadows they cast.

The clickRange option sets the depth range for picking objects with the hand-controller cones, where r (default 5.0) is the maximum distance from the tip of the cone to the object in scene distance units, typically Å. Limiting the range prevents accidentally picking far-away objects.

The gui option specifies which ChimeraX tool panels to show in VR when the hand-controller button assigned to that function (by default, Vive menu or Oculus B/Y) is pressed. Any combination of tools can be specified as a comma-separated list of one or more tool names, as listed in the Tools menu and shown for most tools in their title bars. Tools may also be custom panels created with the buttonpanel command. If the gui option is not given, the same tools as currently shown in the desktop display (including the Toolbar, and on Windows only, the ChimeraX main menu) will be shown.

The simplifyGraphics option (default true) reduces the maximum level of detail in VR by limiting the total atom and bond triangles to one million each. This helps to maintain full rendering speed. The previous total-triangle limits are restored when the VR mode is turned off. Normally, the maximum atom and bond triangles are set to five million each. See also: graphics

Ambient shadowing or “ambient occlusion” requires calculating shadows from multiple directions, which may make rendering too slow for VR and cause stuttering in the headset. By default (multishadowAllowed  false), if the multiShadow lighting parameter is > 0, enabling VR switches to the simple lighting mode. With multishadowAllowed  true, the lighting mode is left unchanged.

When the mode is enabled, the roomPosition option can be used to specify the transformation between room coordinates (in meters, with origin at room center) and scene coordinates (typically in Å) or to simply report the current transformation in the Log. The transformation matrix is given as 12 numbers separated by commas only, corresponding to a 3x3 matrix for rotation and scaling, with a translation vector in the fourth column. Ordering is row-by-row, such that the translation vector is given as the fourth, eighth, and twelfth numbers. Example:

vr  room  20,0,0,0,0,20,0,0,0,0,20,0

The frequency of label reoriention is automatically decreased when VR is enabled and restored when VR is turned off.

vr button  button-name  functionhand  left | right ]
Vive hand controllers
Vive hand controllers

The vr button command assigns modes (functions) to the hand-controller buttons in virtual reality. The available function names are the same as for mousemode (command usage mousemode lists them in the Log) and should be enclosed in quotation marks if they contain spaces. The hand option can be given to assign a function to the specified button of only one hand controller; otherwise, those on both controllers will be assigned. The button-name can be:

Initial defaults are to translate and rotate with triggers, zoom with Vive touchpad or Oculus A/X button, and show/hide ChimeraX tool panels with the Vive menu or Oculus B/Y button (more...).

The only function settings that work by tilting the Oculus thumbstick are rotate , zoom , contour level , and play map series .

vr roomCamerastatus ] [ fieldOfView  angle ] [ width  w ] [ backgroundColor  color-spec ]
The vr roomCamera command sets up a separate camera view fixed in the VR room coordinates, useful for making video tutorials. The camera view is shown in the desktop graphics window and as “picture in picture” in the VR headset. The vr roomCamera command can only be used in virtual reality (after using vr on). In VR, the room camera is shown as a rectangle at the camera position (initially 1.5 meters above the floor and 2 meters from the center) that shows what that camera sees. The width of the rectangle is given in meters (default 1.0), and the height is chosen to match the aspect ratio of the desktop graphics window. The default fieldOfView for the room camera is 90°. The background color of the room camera can be set separately from the VR background; default is a dark gray (10,10,10) so that the rectangle is visible against a black scene background. See also: camera, making movies

UCSF Resource for Biocomputing, Visualization, and Informatics / October 2019