MolViewSpec

Basic Example

Here’s a simple example that loads and displays a protein structure. We are using the molstar and mol-view-stories Javascript libraries dynamically build up mol-view-spec state tree which is rendered on a molstar canvas. Try it out!

Basic Protein Structure (1CBS)

Selections and Multiple Components

This example adds a few additional features. We use the builder to make muleiple different represetnations and selections. One for the polymer, one for the water, and one for the ligand. We also use focus to center the canvas on the ligand. Because we are building a state tree, anytime we with to branch we need to explicitly branch in our code - e.g. on ligand we use both focus and representation.

Protein with Ligand

Adding Controls

When controls="true" is set, you can: - Toggle auto-update on/off to control when the viewer re-renders - Click “Show execution log” to see execution details and any errors - Edit the code and see changes in real-time (when auto-update is on)

```{.molviewspec controls="true"}
// this block will be rendered with controls
```

Interactive Controls Demo

Hiding Code

You can split your code into two parts using --- as a separator: - Hidden code (above ---): Runs but doesn’t appear in the editor - useful for setup, imports, or shared variables - Scene code (below ---): Appears in the editor and is editable

Using Story and Scene Code

Writing Functions

You can write functions to save space and improve reusabilty.

Supported Attributes

You can customize molviewspec code blocks using the following attributes:

Container Attributes

  • title: Optional title displayed in the header. If empty, no header is shown.
  • controls: Enable interactive controls - “true” or “false” (default: “false”). When enabled, shows a bottom control panel with auto-update toggle and execution log toggle. This automatically enables showBottomControlPanel="true", showAutoUpdateToggle="true", and showLog="true".

MolViewSpec Builder API

The builder API provides a fluent interface for creating molecular visualizations. Key methods include:

  • download(): Download a structure from a URL
  • parse(): Parse the downloaded file (formats: bcif, cif, pdb, etc.)
  • modelStructure(): Create a model structure node
  • component(): Select parts of the structure (polymer, ligand, water, etc.)
  • representation(): Add a visual representation (cartoon, ball_and_stick, surface, spacefill, etc.)
  • color(): Apply colors (named colors like ‘red’, ‘blue’, or hex codes like ‘#cc3399’)
  • label(): Add text labels
  • focus(): Focus the camera on a component

For more information about MolViewSpec:

Technical Notes

This quarto extension wraps MolStar-Components which in turn uses the code from the Mol-View-Stories project.

  • Each block creates an independent interactive viewer
  • The extension automatically manages all JavaScript and CSS dependencies
  • The viewer is fully interactive and allows rotation, zooming, and selection
  • Use {.molviewspec} with a dot prefix for the code block class
  • The MolStar library is bundled with the extension for offline use
  • Write JavaScript code using the builder variable to construct your view