The meeting command shares a scene between two or more ChimeraX instances running on different computers. Its main purpose is to allow multi-person virtual reality (VR) sessions in ChimeraX, although it can also be used without VR. Each participant is represented by an image and hand-controller pointers (or if not using VR, the mouse pointer) so that participants can see each other pointing at objects in the scene.
The computer that started the meeting must be reachable over the network by the other participants. Firewalls can block the connection; see getting around firewalls below. See also: vr
The meeting is initiated with meeting start, which reports the hostname and IP address in the Log. Subsequently, others join using meeting host, where host is the hostname or IP address of the starting instance (e.g., descartes.cgl.ucsf.edu or 22.214.171.124).
Each participant can specify a name to serve as an identifier within the shared environment, a faceImage file, and a pointer-cone color.
Aside from synchronizing pointers, the meeting command will copy a session from the ChimeraX instance that initiates the meeting to each person who joins the meeting. This copying is done only when a person joins the meeting. Commands executed by one participant will automatically execute for the others (by default), and if a participant using VR moves the scene, others using VR will see the motion. Participants not using VR maintain their own viewing directions. If unshared changes have been made, a participant can still share his current scene with the others by using meeting send. The host can end the meeting with meeting close, or others can use it to exit the meeting individually.
The meeting command is under development and has several limitations.
Name to show for a participant's pointer and image models in the Model Panel. The meeting participant name is remembered as a preference (initial default Remote).
Color for the cones representing a VR participant's hand-controller pointers (or non-VR participant's mouse pointer). The pointer color is remembered as a preference (initial default lime
Image to represent a VR participant's headset position, where image-file is the pathname of a JPG or PNG file. The pathname can be absolute or relative to the current working directory as reported by pwd, Substituting the word browse for the pathname brings up a file browser window for choosing the file interactively. The meeting image pathname is remembered as a preference.
User and host name for a proxy server, for example, email@example.com. An ssh tunnel is made to the proxy server so that participants can connect to the proxy when the meeting host is not directly reachable due to a firewall (details...). The private key for connecting with ssh is provided with the keyForProxy option. If the connection to the proxy server fails because the proxy is not reachable, it takes typically 75 seconds before the ssh connection attempt times out and an error message is logged. This option can only be used by the meeting host.
The ssh identity file (e.g., vr-key-private.pem) used to make an ssh tunnel to the proxy server given with the proxy option. This identity file is the private key used to connect to the proxy using the ssh -i option when creating the tunnel. The file must not have read permissions by others or ssh will consider it insecure and not accept it.
copyScene true | false
Specified with meeting start, whether to copy the session from the starting instance to each person who joins the meeting (default true). This copying is done only when a person joins the meeting.
relayCommands true | false
Whether to share commands with other participants, and in turn, execute other participants' commands automatically (default true). Note that toolbar icon buttons and many mouseclick/pointer operations act via commands.
Number of the network port used to connect to the meeting host (default 52194). Unless the default is used, all who join the meeting must specify the same number as specified with meeting start.
How often to send a participant's VR headset and hand-controller positions to the other participants (every Mth frame, default 1, every frame). For non-VR users, the mouse pointer is not tracked continuously; the position is only displayed to others when it hovers over an atom.
Firewalls block connections. Most academic institutions have firewalls that block incoming network connections, and require administrative requests to open up network ports. See below for how to get around firewalls.
Synchronizing changes. After the initial scene is shared not all changes made by one participant will be propagated to other participants. Changes that are propagated include moving and scaling the displayed structures and (by default) executing commands. If a participant makes any unshared changes or introduces data for which the input file is not directly accessible to others (i.e., the same open command will not work for everyone), meeting send is needed to share the updated session. This may be slow for large amounts of data.
More than two participants. The meeting command has had very limited testing with more than two participants. Multiple participants may cause errors or slow display updating.
No audio chat support. An audio connection is not provided, so it is necessary to set up a separate audio link for remote participants. Zoom using the headset speakers and microphone works well.
Aligning two VR headsets in one room. Two Vive or Vive Pro VR headsets can be used in the same room, each connected to its own computer. Each headset uses the same pair of base stations. A problem sometimes arises that the two headsets do not see the ChimeraX structures displayed at the same location in the room. Specifically, one headset may see the structure positions as if the room is rotated 180° relative to the other headset. This happens because the SteamVR room setup is run separately on each computer and produces a different coordinate system. For structures to have the same room position in both headsets, the room boundaries traced using SteamVR room setup should be the same for both computers. The first step of SteamVR room setup in which users are asked to point the hand controller at the screen and click is the key to avoiding 180° misorientation. At that step, it is important to point along the short axis of the rectangle defining the room bounds (that will be traced in a later step). SteamVR chooses between two coordinate system orientations rotated 180° from each other based on the direction of pointing. If pointing is along the long axis of the rectangle bounds, a slight tilt toward the left or right of the long axis produces opposite coordinate system orientations. Pointing along the short axis instead is a reliable way to make both computers use the same orientation. (The computer screen position is irrelevant.)
Most universities, colleges, institutions, companies and government labs have firewalls that prevent incoming network connections. When joining a meeting, ChimeraX attempts to connect to port 52194 on the computer that started the meeting, as indicated by the message “Waiting for scene data from meeting host.” If the connection is blocked, usually after 60 seconds an error message will appear:
Socket error Connection timed out
Two ways to resolve the problem are to:
Details on each approach are given below.
Open a firewall port
By far the easiest solution is to change the firewall settings protecting the computer that starts the meeting to allow incoming connections on port 52194. Here are two examples of how that can be done:
Forward connections from a proxy virtual machine
If a firewall exception cannot be made, a more difficult solution is to set up a virtual machine that is publicly visible on the internet, for example, using Amazon Web Services (AWS). The AWS machine can simply accept connections and forward them to the host computer behind the institution firewall using an ssh tunnel.
I have used the following procedure to set up an AWS virtual machine for ChimeraX meeting access. This could be done with any cloud virtual machine service since only ssh is required.
meeting start proxy firstname.lastname@example.org key vr-key-private.pemThe key option specifies the public key encryption file vr-key-private.pem that was made when I created the AWS virtual machine. It allows ssh access to the virtual machine without typing a password. The “ubuntu” is the user account name on the AWS virtual machine. The meeting command creates the tunnel using ssh by executing a command like
ssh -N -i vr-key-private.pem -R 52194:localhost:52194 email@example.comConnections through the tunnel appear to come from the host machine.
Several future developments are intended to simplify ChimeraX meetings and handling of firewalls.
meeting start name sars-antibody...and participants could join with: