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
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.
Usage: meeting join ( meeting-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.
Usage: meeting settings [ name 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.
Usage: meeting server [ server-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.
Usage: meeting close
The host can end the meeting with meeting close, or others can use it to exit the meeting individually.
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.
Usage: meeting info
The meeting info command reports information about the currently active meeting.
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.
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.)
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.
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.
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.
meeting server myserver address 54.215.157.17 account ubuntu key meeting-key-private.pemThe 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 myserverThe 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.
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 tunnelTo define a new server name using this safer tunnel account:
meeting server myserver address 54.215.157.17 account tunnel key meeting-key-private.pemThe server option used previously will be remembered so this server will be used when starting a meeting
meeting start antibody442
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:
meeting server natrouter address 188.15.37.68 port 52194
meeting start rotavirus server natrouter
meeting start influenza server directSome institutions will not allow these exceptions due to institution security requirements.
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.
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.