Example Embedding a ChimeraX 3D Scene in a Web Page

Tom Goddard
May 23, 2023

Save a ChimeraX scene to a GLTF file with command "save scene.glb". Then reference that file in the html for a web page as shown below. You can rotate and zoom the model using mouse, trackpad or touchscreen.

HTML to Embed a 3D Scene

This html file contains just a couple lines of code to embed the 3D molecule shown above. The first line loads Google's JavaScript Model Viewer. The second line places the scene in the web page using the "model-viewer" tag.

    <script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.1.1/model-viewer.min.js"></script>

    <model-viewer alt="3D View of ChimeraX scene.glb file" src="scene.glb" style="width: 600px; height: 400px" shadow-intensity="1" camera-controls touch-action="pan-y"></model-viewer>

Reducing Scene Complexity for Fast Page Load

The GLTF scene files exported from ChimeraX can be very large if the underlying data is large. To make a web page load quickly the scene file should be made as small as practical. A 10 MByte file will take about a second on a typical home internet connection of 80 Mbits/second or 3 seconds on a typical 2023 cellular phone network speed of 27 Mbits/sec. Mostly web servers will compress the file for transmission. The example small molecule scene above is 1 Mbyte and compresses to 1/3 of that size.

Poster Images

If the scene file is large, one way to improve the user experience is to have the web page show an image of the scene initially until the data download completes. This can be done by specifying an image file in the "model-viewer" line. The image can be saved from ChimeraX (command "save scene.jpg").

    <model-viewer poster="scene.jpg" ...></model-viewer>

Reducing Scene File Size

ChimeraX renders scenes with a very large number of triangles to produce the best appearance for rendering on desktop and laptop computer graphics. It will use up to 10 million triangles. Triangles take about 24 bytes each, so a GLTF scene file size of 10 Mbytes would be only 400,000 triangles. Microscopy image data show as a semi-transparent volume uses few triangles but saves large images (called textures) in the scene file. Often it is necessary to adjust ChimeraX settings to reduce the quality to make the saved GLTF scene file small enough for quick download on a web page.

Reducing Scene Detail for Molecules

For molecular structures shown with atoms, bonds and ribbons, the ChimeraX "graphics quality" command reports or sets the level of detail, and "graphics triangles" command can report total number of triangles. For example, for the small molecule shown above

    graphics quality
    > Quality 1, atom triangles 2000, bond triangles 160, ribbon divisions 20

    graphics triangles
    > 36560 total triangles in 1 models and 4 drawings

Here is an example command to reduce the number of triangles for this molecular scene from 36560 to 1892 but the appearance is much worse as shown below

    graphics quality atomTriangles 100 bondTriangles 12 ribbonSides 4 ribbonDivisions 2

Normal ChimeraX quality

Reduced quality

Send to Quest Panel to Reduce Molecule Scene Size

ChimeraX daily builds newer than March 2023 have a panel Send to Quest (menu Tools / General / Send to Quest) that reports the number of triangles used and has buttons to reduce the quality of atoms, bonds and ribbons. The Send to Quest button on that panel will save a GLTF file to the Desktop. This panel is intended to send GLTF files to a Quest virtual reality headset, but it can instead be used just to get a desired reduced GLTF file size.

Reducing Scene File Size for Microscopy Images

It is often necessary to reduce the GLTF scene file size for 3D electron or light microscopy data. If the image data is 1000 by 1000 pixels with 100 z-planes shown at full resolution in ChimeraX it will use 2 bytes per pixel, so 200 Mbytes. For RGB color data it will be 4 bytes per pixel, or 400 Mbytes. Using step size 2 in the ChimeraX Volume Viewer pane will use every other data point along x, y, and z axes, so 8 times less data, or 25-50 Mbytes. Microscopy images usually do not compress well. To reduce the data further you could take step 4 along the z axis for another factor of 2 reduction (command "volume #1 step 2,2,4"). A better option is probably to crop the bounds of the image, say to the middle half along each axis (command "volume #1 region 250,250,25,750,750,75", the values listed are xmin,ymin,zmin,xmax,ymax,zmax voxel positions).

Reducing Scene File Size for Image Isosurfaces

3D images can also be displayed as iso-surfaces and then the number of triangles will determine the file size and can be reported with the "graphics triangles" command as shown above. Using a higher threshold level, step 2, or cropping the bounds of the image data can reduce the number of triangles.

Tom Goddard / goddard@sonic.net / May 2023