3Dmol.js molecular viewer

#Architecture

SMILES
  |
  v
POST /api/model
  |
  +-- RDKit conformer coordinates
  +-- SDF/MolBlock
  +-- local orbital coefficient vectors
  +-- lone-pair / sigma / pi classifications
  |
  v
3Dmol.js
  |
  +-- atoms + bonds
  +-- custom orbital meshes

The new route is:

/molviewer

The existing /molecule page remains available as the legacy custom-canvas viewer.

A second tab draws the same molecule and surfaces with Mol*, and three buttons write them as cube, PLY and MolBlock files in the same frame: see Mol* and files.

#π fields (16.1)

The viewer can overlay the π layer of the molecule on the same conformer:

• π electron density at a chosen e/bohr³ (violet);
• interference: where bonding moves charge, red where it gathers between atoms and blue where it was taken from; it integrates to zero;
• π molecular orbitals, any MO of any π system, amber ψ > 0 and teal ψ < 0;
• electric potential of the π-layer net charges, as colour on the π density surface (red negative, where a proton is attracted; blue positive).

/api/model sends the π layer as pi_field (the payload of the π density field engine); the browser evaluates it on a 3D grid with pi-field-engine.js, the same code that draws the 2D pKa maps, and extracts the surfaces with the viewer's marching tetrahedra. The server does no grid work.

#Why the MolBlock is part of /api/model

3Dmol.js accepts SDF/MolBlock data directly. Including the MolBlock in the same response guarantees that the molecule and the local orbital layer use exactly the same RDKit conformer coordinates and avoids a second conformer request. Since 16.1 the MolBlock is written in the same centred frame as atoms[].position (before, the atoms were centred and the MolBlock was not, so surfaces could sit a few hundredths of an ångström off their atoms).

#Orbital meshes

Version 13 converts local orbital directions to low-poly 3D meshes:

• sigma hybrid: large forward positive-phase lobe + smaller back lobe
• pi basis: symmetric opposite-phase p-lobes
• lone pair: localized direction lobe (white since 16.1)

These are genuine 3D WebGL scene meshes, not a 2D overlay.

They are still local-valence glyph meshes rather than exact wavefunction isosurfaces. A future mesh generator can replace the ellipsoid parameterization with

without changing the viewer architecture.

#Pinned dependency

3Dmol.js is pinned to version 2.5.5.

Install the local copy with:

./install_3dmoljs.sh

The page first tries:

/vendor/3dmol/3Dmol-min.js?v=2.5.5

and falls back to the same pinned version on unpkg.

#Diagnostics

curl https://app.lcserve.com/api/viewer-health

#API relationship

• POST /api/model — unprotected model endpoint used by browser pages
• POST /api/render-svg — bearer-protected page-independent SVG render
• GET /api/viewer-health — deployment diagnostics

3Dmol.js is BSD-3-Clause licensed. Follow the project's citation guidance when used in scientific work.