ChimeraX docs icon

Command: meeting

Usage:
meeting  start  [ name  participant-name ] [ color  pointer-color ] [ faceImage  image-file ]  other-options

Usage:
meeting  host  [ name  participant-name ] [ color  pointer-color ] [ faceImage  image-file ]  other-options

Usage:
meeting  send

Usage:
meeting  close

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 169.230.21.39).

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.

Options

name  participant-name
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  pointer-color
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
).
faceImage  image-file
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.
proxy  proxy-host
User and host name for a proxy server, for example, chimerax@13.56.160.227. 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.
keyForProxy  ssh-identity-file
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.
port  N
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.
updateInterval  M
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.

Limitations and Potential Developments

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.)

Getting Around Firewalls

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.

  1. Create an AWS EC2 virtual machine; I used a free type t2.micro using an Ubuntu 18.04 LTS Amazon Machine Image. The machine will need minimal compute and network bandwidth as it is just forwarding data. The only large data being forwarded is the initial ChimeraX meeting session. I chose Ubuntu 18.04 only because I have experience with it. Any Linux distribution will work, since only ssh will be used.
  2. Set the virtual machine security group to allow any computer to connect on port 52194. By default, the virtual machine will not allow connections except on ssh port 22, so this is a necessary step.
  3. Change sshd configuration file on the virtual machine /etc/ssh/sshd_config enabling “GatewayPorts yes” and restart sshd (on Ubuntu 18, “sudo service ssh restart”). This will allow other computers to connect to ssh tunnels. The normal use of ssh tunnels just allows the local computer use the tunnel, so this setting change is necessary.
  4. Create the tunnel using the proxy option when starting the meeting, for example:
    meeting start proxy ubuntu@54.215.157.17 key vr-key-private.pem
    The 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 ubuntu@54.215.157.17
    
    Connections through the tunnel appear to come from the host machine.
  5. Tell participants to join the meeting using the AWS virtual machine public IP address (for example, command: meet 54.215.157.17). The participants do not need any authentication or account on the AWS virtual machine. If there are participants within the same firewall as the meeting host, they can probably connect directly to the host computer without using the AWS virtual machine (for example, command: meet 169.230.21.34). Connections through the tunnel and from within the firewall can both be made in the same meeting.

Future developments
Several future developments are intended to simplify ChimeraX meetings and handling of firewalls.

  1. Remember proxy settings. Would like an option to remember the meeting command proxy and keyForProxy settings so they don't need to be re-entered for each meeting.
  2. Free proxy service. We will look into providing a free, always-available proxy service that requires no setup. We would have to find funds to pay for this, and it would likely be just a single virtual machine based in California where ChimeraX is developed. This may have significant lag for users on other continents.
  3. Named meetings. A cloud virtual machine typically changes IP addresses when stopped and started. To avoid meeting participants having to know the latest proxy IP address to join a meeting, I hope to use a name service where the meeting host would give the meeting a name that would be used instead of the host computer address. For example, the meeting could be started with command:
    meeting start name sars-antibody
    ...and participants could join with:
    meeting sars-antibody
  4. User interface panel. It would be nice to have a user interface panel as an alternative to typed commands for starting and joining meetings. The panel could also show settings such as proxy, face image, and participant name.

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