Export an Atomic Model with Colors in GLTF or OBJ formats

Tom Goddard
May 21, 2021, updated June 23, 2021

Here is how to export an atomic model from ChimeraX as a GLTF or an OBJ file with colors in a texture. Also we look at how to reduce the level of detail and file size. The goal is to create an atomic model that can be rendered in 3D in a web browser or used in other 3D apps (Unity, cell phones) that don't know about molecules.

Atomic model

For an example we will look at a coronavirus spike protein structure saved in ChimeraX session file spike.cxs, details of where this model came from are below.

      open spike.cxs

Save in GLTF format

We can export the scene in GLTF format

      save spike.glb

Large file size

The spike.glb file is 100 Mbytes. For many uses this is too large. The number of triangles shown in the scene is reported by the graphics triangles command.

      graphics triangles
      
      -> 3767472 total triangles

Reduce level of detail

ChimeraX tries to give best appearance while still rendering fast and does not reduce the level of detail until it exceeds 10 million triangles. For showing the model on a web page or cell phone, 100,000 triangles would be a better size, giving faster download. The graphics quality command reports the level of detail and can change it.

      graphics quality

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

Using instead 50 triangles per atom, and 2 cartoon segments per residue, and 4 segments for the ribbon cross-section

      graphics quality atomTriangles 50 ribbonDivisions 2 ribbonSides 4

reduces the triangle count by a factor of about 30 down to 110,000.

      graphics triangles

      -> 110632 total triangles

And saving the GLTF file (save spike2.glb) now gives a size of 4 Mbytes.

GLTF model with vertex colors.

Show model in web browser

We can test the 3D model in the Firefox web browser using Babylon.js sandbox. Drag the spike2.glb file onto the browser window.

Vertex colors

ChimeraX colors the model using vertex colors. Each of the 3 vertices of a triangle have a color and the color varies smoothly across each triangle. Babylon.js can read vertex colors. But it is hard or impossible to use vertex colors in some 3D modelling packages (Blender, Maya, Cinema4D), that instead use texture colors. The GLTF file saved above will contain vertex colors because that is what ChimeraX uses internally. To write texture colors (spike3.glb) use an additional option available in ChimeraX versions newer than June 24, 2021.

      save spike3.glb textureColors true

Not all parts of a scene can be converted to texture colors. Parts that have continuous color variation, such as electrostatic potential or hydrophobicity coloring of a surface will still be output as vertex colors. We may remedy this in the future (see request #4808).

For OBJ format, the texture colors must be written to a separate image file which can be done as described below.

Saving in OBJ file format

Wavefront OBJ is another file format read by almost all 3D modeling software. To write our model in OBJ format use ChimeraX command

      save spike.obj

OBJ format does not support vertex colors, so the spike.obj file has no color information.

OBJ model with texture colors.

Setting texture
in Babylon.js sandbox.

Saving OBJ file with texture colors

Colors in OBJ format can only be shown using a texture. ChimeraX can write out a texture in addition to the OBJ file using the color image command

      close
      open spike2.glb
      color image #1 coords vertexcolors writeColors spike_texture.png
      save spike2.obj

To load the model in Babylon.js drag and drop the spike2.obj file on the Babylon sandbox web browser page. Then use Babylon settings, click on the default material, scroll down and add a diffuse texture choosing the spike_texture.png image file.

Here is what the texture image spike_texture.png looks like (scaled up since it is only one pixel high).

Texture image

Limitations converting vertex colors to texture colors

Surfaces only. Vertex colors can only be turned into texture colors using the "color image" command for a surface model, not an atomic model. That is why we opened the GLTF file above when using the "color image" command since GLTF is a surface format.
Discrete colors only. The "color image" command will produce artifacts for continuously varying colors. This is because the UV coodinates just define a 1-dimensional color palette. Triangles that have vertices with different colors will interpolate across the entire palette creating rainbow artifacts.

Details of Coronavirus Spike Model

Our example atomic model is a coronavirus spike protein structure. Here is a ChimeraX session file spike.cxs that was created using ChimeraX commands spike.cxc.

It shows UK B.1.1.7 variant of sars-cov-2 (PDB 7LWT) with mutated residues red, and also the mutated residues for the Brazilian B.1.1.28 variant (PDB 7LWW) blue, and the mutated residues for South African B1.351 variant (PDB 7LYN) cyan, with glycosylation decorating the spike colored yellow. The mutations shown are relative to sequence UNIPROT P0DTC2. These structures are described in article Effect of natural mutations of SARS-CoV-2 on spike structure, conformation and antigenicity.