crystal-viewer
Generate an interactive 3D HTML crystal structure viewer from a CIF file (URL or local path). Uses 3Dmol.js — no Python dependencies needed. Features rotate/zoom/pan controls, Jmol color scheme, ball-
SKILL.mdskills/crystal-viewer/SKILL.md
GitHubCrystal Viewer
Converts a CIF file (local path or URL) into a single HTML file with a fully interactive 3D crystal structure viewer powered by 3Dmol.js.
No Python dependencies required — the script uses only the standard library.
When to Use
- User provides a CIF link (URL) or path and wants to visualize it
- User asks to "show", "visualize", "render", or "view" a crystal structure
- User wants a rotatable 3D browser view of a material
Quick Start
# No pip install needed!
# From a URL
python scripts/cif_to_html.py https://example.com/structure.cif
# From a local file
python scripts/cif_to_html.py structure.cif
# Custom output name
python scripts/cif_to_html.py structure.cif -o viewer.html
Then open the generated HTML in any modern browser (internet required for the 3Dmol.js CDN).
Features
| Feature | Details |
|---|---|
| 3D controls | Drag rotate · Scroll zoom · Shift+drag pan |
| Rendering | 3Dmol.js with Jmol element colors |
| Style toggle | Ball & Stick · Space Filling · Stick · Wire |
| Unit cell | Toggleable wireframe overlay |
| Background | Dark / light toggle |
| Info panel | Formula, space group, a/b/c/α/β/γ |
| No deps | Pure Python stdlib — no pymatgen, numpy, etc. |
CLI Options
| Flag | Default | Description |
|---|---|---|
input |
required | CIF URL or local file path |
-o OUTPUT |
<stem>_crystal.html |
Output HTML path |
Implementation Notes
- CIF content is embedded as a JSON string directly in the HTML
- 3Dmol.js (
https://3Dmol.org/build/3Dmol-min.js) handles all parsing, symmetry expansion, and rendering - CIF header is parsed with regex to extract formula, space group, and cell parameters for the info panel
- The generated HTML requires an internet connection to load 3Dmol.js from CDN
Example Workflow
When a user says "可视化这个 CIF 文件 https://…/structure.cif":
python scripts/cif_to_html.py https://…/structure.cif
# → structure_crystal.html
Return a link that opens the generated viewer in a new tab, for example:
<a href="/viewer/structure_crystal.html" target="_blank" rel="noopener noreferrer">打开结构</a>
Replace structure_crystal.html with the actual generated HTML filename or viewer path.