/molecular-visualization-3dmol

name: "molecular-visualization-3dmol"
description: "3Dmol.js WebGL molecular visualization emitted as self-contained HTML. Render structures (PDB/SDF/XYZ/MOL2/cube) with stick, sphere, cartoon, line, and surface styles; animate trajectories with a frame-delay (interval, ms) control; and animate vibrational normal modes via vibrate() from per-atom dx/dy/dz displacements or from precomputed frames. Output standalone HTML that loads 3Dmol from a CDN, with optional play/pause and speed controls. Use for transition-state imaginary-mode animations, MD or reaction-path playback, docking poses, and orbital/density isosurfaces. For static 2D chemical structure drawings use rdkit-chemdraw-cdxml; for 2D statistical plots use matplotlib or plotly."
license: "BSD-3-Clause"

3Dmol.js molecular visualization

Overview

3Dmol.js is a WebGL molecular viewer that runs entirely in the browser. This skill emits **self-contained HTML** files that load 3Dmol from a CDN and render a structure, a trajectory, or a vibrational mode — no server, no build step, no Python runtime to view. The bundled `scripts/mol_viewer.py` generates that HTML from any `.xyz/.trj/.pdb/.sdf/.mol2/.cube` file; the Core API below shows the underlying 3Dmol.js calls so you can hand-write or customize a viewer.

When to Use

• Animate a transition-state imaginary vibrational mode (from a mode trajectory or dx/dy/dz vectors)
• Play back a reaction path (IRC/NEB) or an MD trajectory with a speed control
• Show a protein–ligand docking pose with cartoon + ligand sticks + a binding-site surface
• Display an orbital or electron-density isosurface from a Gaussian `.cube` file
• Hand a colleague one HTML file that opens in any browser, no install
• Use **py3Dmol** instead for inline viewers inside a Jupyter notebook (same engine, Python API)
• Use **PyMOL/ChimeraX** instead for publication ray-traced stills or heavy structural editing
• Use **rdkit-chemdraw-cdxml** for 2D chemical structures, **plotly/matplotlib** for 2D plots

Prerequisites

• **Viewing**: any modern browser with network access (the HTML pulls 3Dmol.js from a CDN)
• **Generator script**: `scripts/mol_viewer.py` — Python 3 standard library only, no install
• **Optional**: `pip install py3Dmol` for notebook use (wraps the same library)

No package is needed to produce or open the HTML. The generator lives in this skill's `scripts/` folder (next to this SKILL.md). It can't be run in place from the skill directory, so use your file tools to read `scripts/mol_viewer.py` and save it into your working directory before running.

Quick Start

# animate a mode/trajectory file with play/pause + speed slider, in one call
python3 mol_viewer.py ts_imaginary_mode_000.trj --mode trajectory \
    --title "TS mode" --subtitle "-621.8 cm-1" --out ts_mode.html
# static structure:  python3 mol_viewer.py mol.xyz --out mol.html

Core API

All snippets assume `<script src="https://3Dmol.org/build/3Dmol-min.js"></script>` is loaded and a `<div id="v"></div>` exists.

Create a viewer and load a structure

`createViewer` binds to a div; `addModel(data, format)` loads coordinates. Always `zoomTo()` then `render()`. Supported `format`: `xyz`, `pdb`, `sdf`, `mol2`, `cube`, `cif`.

const viewer = $3Dmol.createViewer("v", {backgroundColor: "white"});
viewer.addModel(xyzString, "xyz");         // coordinates as a string, not a URL
viewer.setStyle({}, {stick: {radius: 0.15}, sphere: {scale: 0.28}});
viewer.zoomTo();
viewer.render();

Styles and coloring

`setStyle(selection, styleSpec)` — empty selection `{}` targets all atoms. Styles: `stick`, `sphere`, `line`, `cross`, `cartoon`. Color by element (default), a scheme, or a fixed color.

viewer.setStyle({}, {stick: {}, sphere: {scale: 0.25}});          // ball-and-stick
viewer.setStyle({elem: "C"}, {stick: {color: "gray"}});           // per-element override
viewer.setStyle({chain: "A"}, {cartoon: {color: "spectrum"}});    // protein ribbon
viewer.render();

Animate a trajectory

Load every frame with `addModelsAsFrames`, then `animate`. **`interval` is the delay between frames in milliseconds (larger = slower)** — do not use `step`, which skips frames and looks jumpy. `loop: "backAndForth"` makes a one-way path oscillate; `reps: 0` loops forever.

viewer.addModelsAsFrames(trjString, "xyz");   // multi-frame .trj or multi-model .xyz/.pdb
viewer.setStyle({}, {stick: {radius: 0.14}, sphere: {scale: 0.28}});
viewer.zoomTo();
viewer.render();
viewer.animate({loop: "backAndForth", interval: 120, reps: 0});

Animate a vibrational normal mode

If a model's atoms carry displacement vectors (`dx, dy, dz` — extra columns on each XYZ line: `elem x y z dx dy dz`), `model.vibrate(numFrames, amplitude, bothWays, arrowSpec)` builds the oscillation frames. `bothWays: true` swings symmetrically about equilibrium; `arrowSpec` draws motion arrows.

const m = viewer.addModel(modeXyz, "xyz");        // each atom line: elem x y z dx dy dz
m.vibrate(10, 1.0, true, {radius: 0.08, color: "black"});   // 10 frames, full amplitude, arrows
viewer.setStyle({}, {stick: {radius: 0.14}, sphere: {scale: 0.28}});
viewer.zoomTo();
viewer.render();
viewer.animate({loop: "backAndForth", interval: 120, reps: 0});

If you only have a precomputed frame trajectory (e.g. pysisyphus `ts_imaginary_mode_000.trj`), use the trajectory path above instead — no `dx/dy/dz` needed.

Surfaces and volumetric isosurfaces

`addSurface(type, style, atomsel)` builds a molecular surface (`VDW`, `SAS`, `SES`, `MS`). For an orbital/density isosurface, load the `.cube` and call `addVolumetricData`.

viewer.addSurface($3Dmol.SurfaceType.VDW, {opacity: 0.75, color: "lightblue"}, {chain: "A"});
// isosurface from a Gaussian cube (positive and negative lobes):
viewer.addVolumetricData(cubeString, "cube", {isoval:  0.02, color: "blue", opacity: 0.85});
viewer.addVolumetricData(cubeStri