Mol3D — Interactive 3D Molecular Visualization for PowerPoint

Mol3D is an open-source PowerPoint add-in for embedding interactive 3D protein and ligand structures directly in your presentation slides. Built with 3Dmol.js, it works on both macOS and Windows — no ActiveX, no VSTO, no platform lock-in.

Platform Status:

• macOS — Fully built, tested, and working (DMG installer available)
• Windows — Build scripts and Inno Setup config ready, not yet tested. Contributions welcome!

---

Installation (macOS)

Option A: Pre-built Installer (Recommended)

1. Download Mol3DInstaller.dmg from Releases
2. Open the DMG and double-click "Install Mol3D Viewer.command"
3. The installer will:
   • Copy Mol3D Viewer.app to ~/Applications/ (no admin password required)
   • Register both add-in manifests with PowerPoint
   • Trust the HTTPS certificate in your Keychain (may prompt for password once)
4. PowerPoint opens automatically with Mol3D ready in the ribbon

Option B: Build from Source

# 1. Clone the repo
git clone https://github.com/suneelbvs/mol3d-ppt.git
cd mol3d-ppt

# 2. Install Node.js dependencies
npm install

# 3. Install Python dependencies
pip install fastapi uvicorn[standard] pyinstaller

# 4. Build the frontend
npm run build

# 5. Build the macOS installer
cd packaging
bash build.sh

Output: release/Mol3DInstaller.dmg (~13 MB)

Option C: Development Mode (No Installer)

# Terminal 1: Build frontend
npm run build

# Terminal 2: Start the HTTPS server
python server/server_main.py

Then sideload the manifests manually:

# Register both add-ins with PowerPoint
cp manifest.xml ~/Library/Containers/com.microsoft.Powerpoint/Data/Documents/wef/Mol3D.xml
cp manifest-content.xml ~/Library/Containers/com.microsoft.Powerpoint/Data/Documents/wef/Mol3DContent.xml

Restart PowerPoint. The add-ins appear under Add-ins (Home tab).

---

Installation (Windows)

Status: Build scripts ready, not yet tested. Contributions and testing welcome!

See packaging/windows/WINDOWS_BUILD_INSTRUCTIONS.md for full details.

REM Prerequisites: Miniconda, Node.js, (optional) Inno Setup 6
REM 1. Create Python env
conda create -n mol3d python=3.11 -y
conda activate mol3d
pip install fastapi uvicorn[standard] pyinstaller

REM 2. Install Node dependencies
npm install

REM 3. Build
packaging\windows\build.bat

Output: release\windows\Mol3DSetup.exe (or .zip if Inno Setup not installed)

Manual sideload (for development):

copy manifest.xml "%LOCALAPPDATA%\Microsoft\Office\16.0\Wef\Mol3D.xml"
copy manifest-content.xml "%LOCALAPPDATA%\Microsoft\Office\16.0\Wef\Mol3DContent.xml"

---

Usage

First Time Setup

1. Launch Mol3D Viewer.app (from ~/Applications/ or Spotlight)
2. PowerPoint opens with "Open Mol3D" and "Insert Snapshot" buttons in the Home tab ribbon
3. Click "Open Mol3D" to open the control panel (TaskPane)
4. Go to Add-ins (Home tab) > insert "Mol3D Slide" to place the interactive 3D viewer on a slide

Loading a Structure

1. Select PDB ID, UniProt, or File tab
2. Enter an ID (e.g., 2FGI, 1CBS) or choose a local file
3. Click Load

Quick Presets (One-Click)

Five presets are available right below the load section. One click configures all controls:

Preset	What it does
Binding Site	Active site residues (5A around ligand) in stick + labeled, ligand in cyan ball-and-stick, H-bonds shown, spectrum cartoon backbone
Surface + Ligand	White semi-transparent SAS surface over protein, ligand in green ball-and-stick, light gray background
Publication	Clean spectrum cartoon, ligand in ball-and-stick, white background, no labels — paper-ready
Interactions	Full binding view: site residues + labels + H-bonds + pocket surface, water & ions visible, secondary structure coloring, dark blue background
Chain View	Each chain in a distinct color, chain ID labels at center of mass, ligand as spheres, dark background

After applying a preset, you can fine-tune any individual setting.

Pushing to the In-Slide Viewer

1. Customize the visualization to your liking
2. Click "Push to Slide Viewer"
3. The Mol3D Slide Content add-in on the slide updates within ~1 second
4. Rotate, zoom, and pan the molecule directly on the slide with your mouse
5. Resize/reposition the viewer frame as needed

Static Image Insertion

• "Insert Static Image" — captures a high-res PNG snapshot and inserts it directly into the slide
• "Insert 6 Views" — generates a labeled 3x2 composite of Front/Back/Left/Right/Top/Bottom views

---

Features

Interactive 3D in Slides

• Content Add-in embeds a live 3Dmol.js viewer directly inside the slide — rotate, zoom, and pan with mouse
• Changes sync from the TaskPane to the in-slide viewer via localStorage
• Static image insertion available as fallback for slideshow compatibility

Data Sources

• RCSB PDB — load by PDB ID (e.g., 1CBS, 2FGI)
• AlphaFold DB — load predicted structures by UniProt ID (e.g., P00520)
• Local files — upload .pdb, .sdf, .mol2, .cif, .xyz files

Protein Visualization

• Styles: Cartoon, Ribbon, Stick, Sphere, Ball & Stick, Line, Cross
• Color schemes: Spectrum (Rainbow), Element (CPK), Chain, Secondary Structure, Hydrophobicity, B-Factor, Residue Type, Charge, Custom Color

Ligand Visualization

• Styles: Ball & Stick, Stick, Sphere, Line
• Color schemes: Element, Green/Cyan/Yellow/White/Orange Carbon, Spectrum, Chain, Custom Color

Binding Site Analysis

• Show residues near ligand within configurable distance (2–10 Angstroms)
• Independent style & color for binding site residues
• Auto-label binding site residue names
• H-bond visualization — dashed lines between ligand and nearby donor/acceptor atoms (N, O, S within 2.0–3.5 A)
• Binding site surface — semi-transparent surface around binding pocket

Surface Rendering

• Types: Van der Waals, Solvent Accessible (SAS), Solvent Excluded (SES), Molecular (MS)
• Opacity slider (0–100%)
• Color: Same as protein, Element, Chain, Spectrum, Hydrophobicity, Electrostatic, White, Custom

Viewer Controls

• Zoom in/out, reset view, auto-spin toggle
• View presets: Front, Back, Left, Right, Top, Bottom
• Atom selection with info panel (name, element, residue, chain, coordinates, B-factor)
• Focus on residue, highlight chain
• Distance measurement between two atoms (Angstroms)
• Clear all annotations

Labels & Background

• Labels: None, All Residues, Ligand Atoms, Chain IDs
• Backgrounds: White, Black, Light Gray, Silver, Dark Blue, Dark Gray, Warm White, Transparent

Export

• Download .glb — 3D model file for PowerPoint's native Insert > 3D Models
• Insert Static Image — high-res PNG directly into the slide
• Insert 6 Views — multi-angle composite image

---

Architecture

Mol3D consists of two Office Add-ins that work together:

Component	Type	Purpose
Mol3D	TaskPane Add-in	Control panel in the side panel — load structures, change styles, push to slide
Mol3D Slide	Content Add-in	Interactive 3Dmol.js viewer embedded directly inside the slide

They communicate via localStorage (same-origin: https://localhost:3000). The TaskPane writes PDB data + visualization config; the Content add-in polls every 500ms and renders when it detects changes.

A lightweight Python server (FastAPI + uvicorn) serves the static web files over HTTPS with a self-signed certificate.

Project Structure

mol3d-ppt/
├── src/
│   ├── taskpane/             # Control panel (side panel)
│   │   ├── taskpane.html     # UI: data source, presets, visualization controls, insert buttons
│   │   ├── taskpane.js       # Office.js + 3Dmol.js orchestration, presets, settings sync
│   │   └── taskpane.css      # Styling (forced light mode for Mac compatibility)
│   ├── content/              # In-slide 3D viewer
│   │   ├── content.html      # Minimal HTML: 3Dmol.js viewer
│   │   ├── content.js        # Reads localStorage, renders 3Dmol.js, polls for changes
│   │   └── content.css       # Full-viewport viewer
│   ├── commands/              # Ribbon button handlers
│   │   ├── commands.html
│   │   └── commands.js
│   ├── viewer/                # Shared modules
│   │   ├── molviewer.js       # 3Dmol.js wrapper (init, style, binding site, snapshot, etc.)
│   │   ├── datasources.js     # RCSB PDB, AlphaFold, local file fetchers
│   │   ├── mol3dexport.js     # Three.js GLB exporter
│   │   └── pptxbuilder.js     # OOXML PPTX builder (experimental)
│   └── config.js              # Configuration constants
├── server/
│   ├── server.py              # FastAPI static file server with self-signed HTTPS
│   ├── server_main.py         # PyInstaller entry point
│   └── requirements.txt
├── packaging/
│   ├── build.sh               # macOS build pipeline (webpack + PyInstaller + .app + DMG)
│   ├── launcher.sh            # macOS .app launcher (server + manifest registration + open PPT)
│   ├── install.sh             # macOS end-user installer (no admin required)
│   ├── Info.plist             # macOS app bundle metadata
│   ├── mol3d.spec             # PyInstaller spec (macOS)
│   ├── hooks/                 # PyInstaller hooks (fastapi, uvicorn, starlette, h11)
│   └── windows/
│       ├── build.bat          # Windows build pipeline
│       ├── install.bat        # Windows end-user installer
│       ├── mol3d_setup.iss    # Inno Setup 6 config (.exe installer)
│       ├── mol3d_windows.spec # PyInstaller spec (Windows)
│       └── WINDOWS_BUILD_INSTRUCTIONS.md
├── manifest.xml               # TaskPane add-in manifest
├── manifest-content.xml       # Content add-in manifest (in-slide viewer)
├── webpack.config.js          # 3 entry points: taskpane, content, commands
├── package.json
├── assets/                    # Icons (16x16, 32x32, 80x80)
├── LICENSE                    # MIT License
└── README.md

---

Technology Stack

Component	Technology
3D Rendering	3Dmol.js v2.x (WebGL)
Office Integration	Office.js (Web Add-in API)
Frontend Build	Webpack 5 + Babel
Server	Python FastAPI + uvicorn
HTTPS	Self-signed certificate via openssl CLI (auto-trusted in macOS Keychain)
GLB Export	Three.js r128 + GLTFExporter
macOS Packaging	PyInstaller + hdiutil (DMG)
Windows Packaging	PyInstaller + Inno Setup 6

---

How It Works

Content Add-in (In-Slide Viewer)

The manifest-content.xml declares xsi:type="ContentApp", which tells PowerPoint to embed the web view inside the slide canvas rather than in a side panel. This is the cross-platform equivalent of ActiveX controls — it works on both Mac and Windows without platform-specific dependencies.

Communication via localStorage

Both add-ins (TaskPane and Content) load from https://localhost:3000, sharing the same browser origin and localStorage. The TaskPane writes structure data + visualization config; the Content add-in polls every 500ms and renders when it detects changes.

Self-Signed HTTPS

Office Add-ins require HTTPS for all resources. The server generates a self-signed certificate using the openssl CLI on first launch, stores it persistently in ~/.mol3d/certs/, and adds it to the macOS Keychain as trusted. Subsequent launches reuse the same certificate.

---

Known Limitations

• Slideshow mode: Content add-ins may not render during PowerPoint Slide Show mode (office-js #4410). Use "Insert Static Image" for presentations.
• Large structures: Very large PDB files (>10 MB) may be slow to transfer via localStorage.
• Self-signed certificate: On first launch, macOS may prompt for your password to trust the certificate in Keychain.
• Windows: Build scripts are ready but not yet tested. The architecture is cross-platform; Windows testing contributions are welcome.

---

Contributing

Contributions are welcome! Please open an issue or pull request.

Areas Where Help Is Needed

• Windows testing — build, install, and test on Windows
• Slideshow mode — workarounds for Content add-in visibility during presentations
• Additional presets — more visualization presets for common use cases
• Performance — optimization for very large structures

Development Workflow

1. Fork and clone the repo
2. npm install
3. Make changes in src/
4. npm run build to compile
5. python server/server_main.py to start the server
6. Sideload manifests and test in PowerPoint
7. Submit a PR

---

License

MIT License. See LICENSE for details.

Credits

• 3Dmol.js — WebGL molecular viewer (University of Pittsburgh)
• Office.js — Microsoft Office JavaScript API
• Three.js — 3D graphics library (GLB export)
• FastAPI — Python web framework
• JSZip — ZIP file generation in browser