Chem Vis

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:

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 = '''

    
    
        .container { display: flex; gap: 20px; flex-wrap: wrap; padding: 20px; }
    

NSAID Comparison

'''

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 += ''

with open("nsaid_comparison.html", "w") as f:
    f.write(page)

---

Troubleshooting

"Could not find chemical"

• Check if network access is enabled to *.nih.gov sites for PubChem use.
• Check spelling
• Try alternative names (IUPAC vs common)
• Use SMILES directly: --input-type smiles

"Could not generate 3D conformer"

• Try --no-optimize flag
• Increase --conformers count
• 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ghutchis
• Source: ghutchis/chem-skill
• License: MIT

Install and usage instructions live in the source repository linked above.