majiayu000 Chemical Visualization Skill
Overview
Generate publication-quality 2D molecular structure images and interactive 3D conformer viewers from chemical names, SMILES, or InChI strings.
Needs network access to *.nih.gov servers to access PubChem for common names like caffeine, testosterone, estrogen, etc.
Much of the code was generated by Claude, with careful validation, error fixing, and OPSIN integration by Geoff Hutchison.
Quick Start
# 2D structure image
python scripts/chem_2d.py "caffeine" --output caffeine.png
# 3D interactive viewer
python scripts/chem_3d.py "caffeine" --output caffeine.html
# Both at once
python scripts/chem_vis.py "caffeine" --both --output-dir ./caffeine/
Dependencies
pip install rdkit pubchempy py2opsin --break-system-packages
Scripts
| Script | Purpose |
|---|---|
chem_2d.py |
Generate 2D structure images (PNG/SVG) |
chem_3d.py |
Generate 3D conformer viewers (HTML) |
chem_vis.py |
Unified CLI for both |
common.py |
Shared utilities (name resolution, etc.) |
2D Structure Images
Generate static images of molecular structures.
Usage
python scripts/chem_2d.py "aspirin" --output aspirin.png
python scripts/chem_2d.py "CCO" --input-type smiles --output ethanol.svg --format svg
python scripts/chem_2d.py "glucose" --width 400 --height 400 --output glucose.png
Options
| Option | Description | Default |
|---|---|---|
--input-type, -t |
Input: name, smiles, inchi |
name |
--output, -o |
Output file path | molecule.png |
--format, -f |
Output: png, svg |
png |
--width, -W |
Width in pixels | 300 |
--height, -H |
Height in pixels | 300 |
--kekulize, -k |
Show Kekulé structure | False |
--show-atom-numbers, -n |
Display atom indices | False |
--highlight-atoms |
Atom indices to highlight | None |
Python API
from scripts.chem_2d import chemical_to_image, batch_convert
# Single molecule
chemical_to_image("caffeine", "caffeine.png", width=400, height=400)
# Batch conversion
chemicals = ["aspirin", "ibuprofen", "acetaminophen"]
results = batch_convert(chemicals, output_dir="./structures/", format="svg")
3D Conformer Viewers
Generate interactive HTML viewers with 3Dmol.js.
Usage
python scripts/chem_3d.py "dopamine" --output dopamine.html
python scripts/chem_3d.py "CCO" --input-type smiles --style ballstick --output ethanol.html
python scripts/chem_3d.py "serotonin" --embed --output serotonin_widget.html
Options
| Option | Description | Default |
|---|---|---|
--input-type, -t |
Input: name, smiles |
name |
--output, -o |
Output file path | molecule_3d.html |
--width, -W |
Viewer width (px) | 500 |
--height, -H |
Viewer height (px) | 400 |
--style, -s |
Style: stick, sphere, line, ballstick |
stick |
--conformers, -c |
Conformers to sample | 10 |
--no-optimize |
Skip MMFF optimization | False |
--no-controls |
Hide interactive buttons | False |
--embed |
Output snippet without HTML wrapper | False |
Embed Mode
Use --embed to generate a snippet for inserting into existing web pages:
python scripts/chem_3d.py "aspirin" --embed --output aspirin_widget.html
The parent page must load 3Dmol.js:
<script src="https://3dmol.org/build/3Dmol-min.js"></script>
Each viewer gets a unique ID, so multiple molecules can coexist on one page.
Python API
from scripts.chem_3d import chemical_to_3d, generate_conformer, generate_html_viewer
# Full pipeline
chemical_to_3d("caffeine", "caffeine.html")
# Step by step
from scripts.common import get_smiles
smiles = get_smiles("caffeine", "name")
mol_block = generate_conformer(smiles, num_conformers=20)
html = generate_html_viewer(mol_block, title="Caffeine", width=600, height=500)
# Embeddable snippet
snippet = generate_html_viewer(mol_block, title="Caffeine", embed=True)
Unified CLI
Generate both 2D and 3D outputs with one command.
# 2D only
python scripts/chem_vis.py "caffeine" --2d --output caffeine.png
# 3D only
python scripts/chem_vis.py "caffeine" --3d --output caffeine.html
# Both
python scripts/chem_vis.py "caffeine" --both --output-dir ./caffeine/
Examples
Generate structures for a lecture
from scripts.chem_2d import batch_convert
neurotransmitters = ["dopamine", "serotonin", "acetylcholine", "GABA", "glutamate"]
batch_convert(neurotransmitters, output_dir="./lecture_slides/", width=400, height=400)
Comparison page with multiple 3D viewers
from scripts.chem_3d import generate_conformer, generate_html_viewer
from scripts.common import get_smiles
molecules = ["aspirin", "ibuprofen", "naproxen"]
page = '''<!DOCTYPE html>
<html>
<head>
<script src="https://3dmol.org/build/3Dmol-min.js"></script>
<style>
.container { display: flex; gap: 20px; flex-wrap: wrap; padding: 20px; }
</style>
</head>
<body>
<h1>NSAID Comparison</h1>
<div class="container">
'''
for mol_name in molecules:
smiles = get_smiles(mol_name, "name")
mol_block = generate_conformer(smiles)
page += generate_html_viewer(mol_block, title=mol_name.title(),
width=350, height=300, embed=True)
page += '</div></body></html>'
with open("nsaid_comparison.html", "w") as f:
f.write(page)
Troubleshooting
"Could not find chemical"
- Check if network access is enabled to
*.nih.govsites for PubChem use. - Check spelling
- Try alternative names (IUPAC vs common)
- Use SMILES directly:
--input-type smiles
"Could not generate 3D conformer"
- Try
--no-optimizeflag - Increase
--conformerscount - Some structures (metals, unusual bonding) may not embed well
Poor 2D layout
- RDKit's 2D coordinate generation works best for typical organic molecules
- Very large or unusual structures may need manual adjustment
3D viewer doesn't load
- Check internet connection (3Dmol.js loads from CDN)
- Check browser console for errors
- For embed mode, ensure parent page loads 3Dmol.js first