ChimeraX docs icon

Command: meeting

The meeting command shares a scene between two or more ChimeraX instances running on different computers. Options for starting and joining a meeting are also implemented in a Meeting graphical interface that is simpler to use than the command. Meeting allows conducting a multi-person virtual reality (VR) session in ChimeraX. It can also be used without VR, but in that case, a desktop screen-sharing program may be a more reliable alternative. Each participant is represented by a head-position image and hand-controller pointer cones so that participants can see each other pointing at objects in the scene. For non-VR participants, the camera view is synchronized, and the cone indicating the mouse pointer position of a non-VR user is displayed to others when the user pauses the mouse over a model, as for picking.

Examples:

meeting start nanobody
   – start a meeting named nanobody
meeting join nanobody
   – join a meeting named nanobody
meeting close
   – leave the current meeting

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 have a synchronized common viewing direction that is not related to the viewing direction of VR participants.

The meeting command is under development and has several limitations. See also: vr

Compatibility: The message protocol used by the meeting command changed in a non-backward compatible way in ChimeraX versions released after December 8, 2020. All participants of a meeting must use a ChimeraX version newer than that date, or all must use a version older than that date. The incompatible change enabled reducing the network bandwidth (4-10x reduction) and increasing security that prevents joining a meeting without knowing its name.

Starting a Meeting

Usage: meeting  start  [ meeting-name ] [ name  participant-name ] [ color  pointer-color ] [ faceImage  image-file ] [ server  server-name ] [ nameServer  hostname ] [ nameServerPort  N ] [ copyScene  true | false ]

A meeting is initiated with meeting start meeting-name, where the meeting name is a text identifier that participants will use to join the meeting. Meeting names are not case-sensitive. The initiator (and each person who joins) can specify a name for identification within the shared environment, a pointer-cone color, and a faceImage file. These three settings are remembered whenever they are specified, and the remembered settings can be reported or changed with the meeting settings command. Full list of options:

name  participant-name
Name to show for a participant's pointer and image models in the Model Panel. The participant name is remembered as a preference.
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 image pathname is remembered as a preference.
server  server-name
The server determines how participants connect to a meeting and is used to get around firewalls that block access. The initial default method chimeraxmeeting.net has participants connect to a public server that forwards connections to the computer that started the meeting. The method direct has partipants directly connect to the computer that started the meeting but will fail if that computer cannot be reached. Additional methods can be defined using the meeting server command. Using this option with meeting start or meeting settings sets the method as the user default in the preferences.
nameServer  hostname
Specify the hostname or IP address to use as the meeting-name server. The name server is remembered as a preference. The initial default is chimeraxmeeting.net, provided by the UCSF RBVI, but a private name server can be used instead.
nameServerPort  N
Port number for the meeting-name server. The name server port is remembered as a preference (initial default 51472).
copyScene  true | false
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.

Joining a Meeting

Usage: meeting joinmeeting-name | host ) [ name  participant-name ] [ color  pointer-color ] [ faceImage  image-file ]  additional-options

Participants join the meeting by specifying its name. If a meeting is started without a meeting-name, participants join it by specifying the host name or IP address (e.g., descartes.cgl.ucsf.edu or 169.230.21.39) reported in the Log by the meeting start command. A participant's name, pointer-cone color, and faceImage settings are remembered whenever they are specified, and the remembered settings can be reported or changed with the meeting settings command. Full list of options:

name  participant-name
Name to show for a participant's pointer and image models in the Model Panel. The participant name is remembered as a preference.
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 image pathname is remembered as a preference.
host  host-name
The first argument of the meeting command normally specifies either a meeting name or a host name. Names containing “.” or “:” are interpreted as a host name. To avoid ambiguity, that first argument can be omitted, and the host option used instead to ensure interpreting the value as a host name (e.g., descartes.cgl.ucsf.edu or 169.230.21.39).
port  N
If participants join a meeting using a host name or IP address instead of a meeting name, they will need to specify the port on the destination computer, unless it is the default port, 52194. If a meeting name is used to join a meeting, this option is not used, as the port will be looked up using the meeting name.
id  meeting-name
The first argument of the meeting command normally specifies either a meeting name or a host name. Names containing “.” or “:” are interpreted as a host name. To avoid ambiguity, that first argument can be omitted, and the id option used instead to ensure interpreting the value as a meeting name.
ssh  true | false
Whether to use ssh to connect to the meeting server. This can sometimes avoid being blocked by firewalls, for instance, when the joining computer is behind a firewall that does not allow outgoing connections to unknown ports using unknown protocols. To use this option the meeting must either use server chimeraxmeeting.net, or if a different server is used the joiner must have the ssh key for that server specified with the meeting server command.
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.
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).
nameServer  hostname
Specify the hostname or IP address to use as the meeting-name server. The name server is remembered as a preference. The initial default is chimeraxmeeting.net, provided by the UCSF RBVI, but a private name server can be used instead.
nameServerPort  N
Port number for the meeting-name server. The name server port is remembered as a preference (initial default 51472).
timeout  seconds
Maximum time to wait when connecting to a meeting (default 5 seconds). If this time is exceeded, an error message is given and the meeting will not be joined.

Changing or Reporting Saved Settings

Usage: meeting settingsname  participant-name ] [ color  pointer-color ] [ faceImage  image-file ] [ server  server-name ] [ nameServer  hostname ] [ nameServerPort  N ]

The meeting settings command sets or reports the values of options that are saved as preferences. These options can also be specified with meeting start or meeting join and have the same meanings as described above for those commands. If no options are specified, the currently saved settings are reported.

Naming New Meeting Servers

Usage: meeting serverserver-name ] [ address  host ] [ port  port-number ] [ account  username ] [ key  ssh-identity-file ] [ portRange  port-min,port-max ] [ timeout  seconds ] [ delete ]

Example command that defines a name for a new server with given IP address, user account and password file:

meeting server "NIAID meeting server" address 52.0.161.5 account chimerax key /Users/goddard/ucsf/aws/niaid-chimerax-user.pem

The meeting server command defines a name for a new server that is shorthand for a computer address, a port number or port range, an authentication key, and a timeout value. When starting a meeting the server to use can be specified with the meeting start command server option. Server names with their settings are remembered as preferences. Given without arguments, meeting server reports the existing server names in the Log. To configure a computer to be a server, see the instructions below.

address  host-address
Host name or IP address of a publicly visible server computer to forward connections made by partipants to the computer that started the meeting.
port  N
The port number on the server computer that participants connect to (initial default 52194). One port is used for receiving connections from all participants. If a tunnel is created because the account option has been specified, then this port is not used and instead an available port in portRange is used. A tunnel is not needed for port forwarding from a network-address-translation router to a computer on the local network served by the router.
account  username
A user name of an account on the server computer for creating an ssh tunnel. Specifying this option implies that an ssh tunnel will be created between the computer that starts the meeting and the server computer.
key  ssh-identity-file
The ssh identity file (e.g., meeting-key-private.pem) for the account on the server computer used to make an ssh tunnel. Substituting the word browse for the pathname brings up a file browser window for choosing the file interactively. This identity file is the private key used to connect to the server 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.
portRange  port-min,port-max
The range of port numbers to use on the server computer. A randomly chosen port in this range is chosen to create a tunnel. All participants connect to that port. The initial default range of 52194,52203 allows up 10 simultaneous meetings to be handled by the server.
timeout  seconds
The time to wait for creating the tunnel to the server. If a connection is not made within this time the meeting will not be started. The initial default is 5 seconds.

Leaving a Meeting

Usage: meeting  close

The host can end the meeting with meeting close, or others can use it to exit the meeting individually.

Sharing a Scene

Usage: meeting  send

If unshared changes have been made, a participant can share his current scene with the others by using meeting send. This replaces the entire scene for the other participants and may take significant time to transmit to the participants if the scene contains large data models.

Reporting Meeting Status

Usage: meeting  info

The meeting info command reports information about the currently active meeting.

Removing an Unused Meeting Name

Usage: meeting  unname  meeting-name

If the computer that started a meeting loses its network connection before the meeting is closed, the meeting name will not be removed from the name server, and future attempts to use the same meeting name will fail, saying the meeting name is already being used. To remove the meeting name from the name server, use meeting unname meeting-name.

Limitations

Firewalls block connections. Most organizations have firewalls that block incoming network connections, and require administrative requests to open up network ports. The server option allows participants to connect to a publicly visible server computer. See getting around firewalls.

No passwords. There is no support for passwords to limit access to meetings. Any person who knows the meeting name can join the meeting. The meeting name server provides no way to list meeting names, so only participants who are told the meeting name will be able to join. In this sense the meeting name serves as the password, and using a less common name will prevent others guessing or accidentally joining the wrong meeting. To join a meeting the participant's Chimera transmits the meeting name to the host. The connection will be rejected if the name is incorrect preventing uninvited users from connecting and preventing port scans from generating spurious connections.

Synchronizing changes. After the initial scene is shared 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.

Small number of participants. The meeting command has been used for two to four participants. The number of participants is not limited. Larger numbers of participants increase the network bandwidth needed expecially for the computer hosting the meeting and may result in slow or jittery updating. All data to synchronize the scene is transmitted through the computer that starts the meeting, so it is a bottleneck. Each VR participant sends about 40 Kbits/second to update hand and head position. Desktop participants do not send continuous messages, only sending when they move the models or execute commands.

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 VR 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 that is not using a server, ChimeraX attempts to connect to port 52194 on the computer that started the meeting, and shows a status message “Waiting for scene data from meeting host.” If the connection is blocked, after 5 seconds (default) 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.

Use a server

By default the meeting start command uses a publicly visible server computer chimeraxmeeting.net which forwards connections through the firewall to the host computer. This is controlled by the server option, for example meeting start alzheimers server chimeraxmeeting.net. The chimeraxmeeting.net server is provided by the ChimeraX development team and can handle up to 10 simultaneous meetings.

Several problems may arise. The server may be at capacity, may be out of service, may introduce delays of seconds if participants are in distant parts of the world from the default server in California, USA.

Setting up one's own server

These problems can be mitigated by setting up and using one's own server, for example, using Amazon Web Services (AWS). The AWS machine simply accepts connections and forwards them to the host computer behind the institution firewall using an ssh tunnel.

Here is how to set up a server using an AWS virtual machine for ChimeraX meetings. 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 tier type t2.micro using an Ubuntu 18.04 LTS Amazon Machine Image. The machine will need minimal compute as it is just forwarding data. The network bandwidth needed depends on the number of participants, which each VR participant sending about 40 Kbits/second of hand and head position information. 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 ports 52194 - 52203. 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 remote tunnels allows only the remote computer to use the tunnel, so this setting change is necessary.
  4. Create an server name for the server using the meeting server command
    meeting server myserver address 54.215.157.17 account ubuntu key meeting-key-private.pem
    The key option specifies the public key encryption file meeting-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 default administer account name on the AWS virtual machine. To use this to start a meeting
    meeting start antibody309 server myserver
    The meeting start command will create the tunnel using ssh by executing a command like
          ssh -N -i meeting-key-private.pem -R 52201:localhost:52194 ubuntu@54.215.157.17
    
    The server option used to start the meeting will be remembered as a preference so those need only be used one time. Subsequent meetings can specify only the meeting name. Connections through the tunnel appear to come from the host machine.
  5. When participants join the meeting using command meet antibody309 it will connect to the AWS virtual machine public IP address. 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 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.
  6. In the above configuration the AWS administration account “ubuntu” was used. For better security it is worth making a separate account on the virtual machine to create the tunnels. This is especially important if the private key will be shared to allow different people to initiate meetings using this server. The account can have no login shell to prevent using ssh to execute commands, only allowing tunnels to be created. On Ubuntu, an account named “tunnel” can be made with the following commands starting from the ubuntu admin account.
      sudo adduser tunnel --disabled-password
      sudo su - tunnel
      ssh-keygen -t rsa -b 2048 -m PEM -C "ChimeraX meeting server" -f tunnel-key.pem
      mkdir .ssh
      chmod go-rwx .ssh
      mv tunnel-key.pem.pub .ssh/authorized_keys
      # Move tunnel-key.pem (private key) to machine that will start meetings.
      exit
      sudo usermod -s /usr/sbin/nologin tunnel
    
    To define a new server name using this safer tunnel account:
    meeting server myserver address 54.215.157.17 account tunnel key meeting-key-private.pem
    The server option used previously will be remembered so this server will be used when starting a meeting
    meeting start antibody442

Open a firewall port

A less complex solution than a server 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:

Setting up a Private Name Server

By default, the meeting command uses the name server chimeraxmeeting.net to record the computer address and port number for each active meeting name. This conveniently allows participants to join a meeting with a simple command, meeting meeting-name. The name server does not log the meetings, and there is no capability to list the meeting names or computers addresses and ports, providing privacy and security. In order to identify a meeting, a request would need to guess the meeting name.

For greater security, an organization may wish to use its own meeting-name server. This can be done by running shell command nohup python3 namerserver.py start & on a machine accessible to the participants. The nohup allows exiting the shell while leaving the name server running. The nameserver.py file is included in the ChimeraX distribution under Chimerax/lib/python3.8/site-packages/chimerax/meeting/nameserver.py (on Linux). To use the name server, all participants specify the name server address using the nameServer option when joining the meeting or before joining with the meeting settings command. This option value is remembered, so only needs to be used once to enable use of the private name server for future meetings.

Future Developments

Large meetings. We have not tried meetings with more than four participants. In principle, meetings can have any number of participants, but this needs testing and likely some improvements to make larger meetings feasible. Probably would need the ability for the host to prevent participants from moving or changing the models.

Reuse large data files. It would be useful if large data files could be transferred just one time and then used for multiple meetings. Currently all data is transferred at the start of each meeting, which can be time-consuming.


UCSF Resource for Biocomputing, Visualization, and Informatics / April 2021