Web Viewer Embedding

Orbitron provides two distribution options for embedding interactive 3D molecular visualizations in websites, presentations, and documentation:

  1. ZIP bundle (orbitron-viewer-web-v*.zip) – ~2-3 MB, optimized for websites and web applications
  2. Standalone HTML (orbitron-viewer-standalone-v*.html) – ~5 MB, self-contained file for PowerPoint and presentations

Both versions provide the same interactive viewer experience (rotation, zoom, selection, measurements) but differ in packaging and deployment workflow.

10.1 Download the Web Viewer

From GitHub Releases:

Visit the Orbitron releases page and download: - orbitron-viewer-web-v0.2.0.zip (for websites) - orbitron-viewer-standalone-v0.2.0.html (for presentations)

Build from source:

# ZIP bundle (requires trunk)
./scripts/build-wasm-viewer.sh

# Standalone HTML (requires trunk and base64)
./scripts/build-wasm-standalone.sh

# Output:
# dist/wasm-viewer/orbitron-viewer-web-v0.2.0.zip
# dist/wasm-viewer/orbitron-viewer-standalone-v0.2.0.html

See scripts/build-wasm-viewer.sh and scripts/build-wasm-standalone.sh for build requirements and options.

10.2 Embedding in Websites

Basic Setup

  1. Extract the ZIP bundle:

    unzip orbitron-viewer-web-v0.2.0.zip
cd orbitron-viewer-web

  2. Add your molecule:

    • Convert your structure to .bin format (see §10.5)
    • Place molecule.bin in the extracted directory

  3. Upload to your website:

    your-website/
├── orbitron/
│   ├── index.html
│   ├── orbitron-viewer-wasm_bg.wasm
│   ├── orbitron-viewer-wasm.js
│   └── molecule.bin

  4. Link to the viewer:

    <a href="/orbitron/index.html?scene=molecule.bin">View Benzene Structure</a>

Iframe Embedding

Embed the viewer directly in your page:

<iframe 
  src="/orbitron/index.html?scene=molecule.bin"
  width="800" 
  height="600" 
  style="border: 1px solid #ccc; border-radius: 4px;">
</iframe>

Responsive iframe:

<div style="position: relative; padding-bottom: 56.25%; height: 0;">
  <iframe 
    src="/orbitron/index.html?scene=molecule.bin"
    style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none;">
  </iframe>
</div>

Multiple Molecules

Host multiple structures by using different .bin files:

<h2>Benzene</h2>
<iframe src="/orbitron/index.html?scene=benzene.bin" width="400" height="300"></iframe>

<h2>Ethanol</h2>
<iframe src="/orbitron/index.html?scene=ethanol.bin" width="400" height="300"></iframe>

Advanced: Use JavaScript to switch scenes dynamically:

<select id="molecule-select">
  <option value="benzene.bin">Benzene</option>
  <option value="ethanol.bin">Ethanol</option>
  <option value="water.bin">Water</option>
</select>

<iframe id="viewer" src="/orbitron/index.html?scene=benzene.bin" width="800" height="600"></iframe>

<script>
document.getElementById('molecule-select').addEventListener('change', (e) => {
  const iframe = document.getElementById('viewer');
  iframe.src = `/orbitron/index.html?scene=${e.target.value}`;
});
</script>

Working example: See examples/web-embedding/simple-website/ for a complete multi-molecule demo.

10.3 PowerPoint Integration

Use the standalone HTML version for PowerPoint presentations. This single file (~5 MB) embeds the WASM binary as base64, so you can insert it without managing separate WASM/JS files.

PowerPoint 2016+ (Windows/Mac)

  1. Download orbitron-viewer-standalone-v0.2.0.html from releases
  2. Rename for clarity: benzene-viewer.html
  3. Place your .bin file in the same folder as the HTML file
  4. Insert into PowerPoint:
    • PowerPoint Windows: Insert → Object → HTML File → Select benzene-viewer.html
    • PowerPoint Mac: Insert → Web Page → Browse → Select benzene-viewer.html
  5. Resize and position the viewer frame on your slide

Note: The viewer looks for molecule.bin by default. Either: - Name your file molecule.bin, or - Edit the HTML and change the URL parameter (see §10.6)

URL parameter in HTML:

<!-- Find this line in the standalone HTML and edit scene= -->
<iframe src="about:blank" id="viewer" onload="loadViewer('?scene=your-molecule.bin')"></iframe>

Google Slides

Google Slides doesn’t support embedded HTML. Instead: 1. Upload the standalone HTML to a public web server or GitHub Pages 2. Insert iframe in Google Slides: Insert → Embed → Enter URL

Alternative: Export slides to PowerPoint (.pptx) and use PowerPoint’s HTML embedding.

LibreOffice Impress

  1. Insert → Object → OLE Object → Create from file
  2. Select the standalone HTML file
  3. Check “Link to file” for smaller presentation size

Working example: See examples/web-embedding/powerpoint-example/ for a demo .pptx with embedded viewer.

10.4 HTML Presentations (Reveal.js, Marp)

Reveal.js

Embed the viewer in any slide:

<section>
  <h2>Benzene Structure</h2>
  <iframe 
    src="/orbitron-viewer-standalone.html?scene=benzene.bin"
    width="800" 
    height="600" 
    data-preload>
  </iframe>
  <p>Interactive 3D visualization with WebGPU rendering</p>
</section>

Preload multiple viewers:

<!-- Slide 1 -->
<section data-background-iframe="/orbitron/index.html?scene=benzene.bin">
  <h1 style="background: rgba(0,0,0,0.7); padding: 20px;">Benzene</h1>
</section>

<!-- Slide 2 -->
<section data-background-iframe="/orbitron/index.html?scene=ethanol.bin">
  <h1 style="background: rgba(0,0,0,0.7); padding: 20px;">Ethanol</h1>
</section>

Working example: See examples/web-embedding/reveal-js-slides/ for a complete Reveal.js deck.

Marp

Marp supports HTML iframes in Markdown slides:

---
marp: true
theme: default
---

# Benzene Structure

<iframe src="/orbitron-viewer-standalone.html?scene=benzene.bin" width="100%" height="500px"></iframe>

Interactive 3D molecular viewer powered by Orbitron + WebGPU

---

# Ethanol Structure

<iframe src="/orbitron-viewer-standalone.html?scene=ethanol.bin" width="100%" height="500px"></iframe>

Note: Marp requires the html option enabled in marp.config.js:

module.exports = {
  html: true,
  // ... other options
};

10.5 Creating .bin Scene Files

The web viewer loads .bin files (serialized SceneGraph format) for optimal performance. Convert your molecular structures using the CLI or Python API:

Using CLI

# Convert single structure
orbitron convert molecule.xyz -o molecule.bin

# Convert specific frame from trajectory
orbitron convert trajectory.log -o molecule.bin --frame 10

# Convert Gaussian optimization final structure
orbitron convert gaussian.log -o final-structure.bin

Using Python

from orbitron import Orbitron

orb = Orbitron()
scene = orb.load("molecule.xyz")

# Serialize to bytes
scene_bytes = scene.to_bytes()

# Write to file
with open("molecule.bin", "wb") as f:
    f.write(scene_bytes)

Batch conversion:

from orbitron import Orbitron
from pathlib import Path

orb = Orbitron()
input_dir = Path("structures/")
output_dir = Path("website/orbitron/")

for xyz_file in input_dir.glob("*.xyz"):
    scene = orb.load(str(xyz_file))
    bin_file = output_dir / f"{xyz_file.stem}.bin"
    with open(bin_file, "wb") as f:
        f.write(scene.to_bytes())
    print(f"Converted {xyz_file.name} → {bin_file.name}")

Working example: See examples/converting-scenes/batch-convert.py for a production-ready batch conversion script.

Supported Input Formats

The viewer can display any format supported by Orbitron’s I/O pipeline: - XYZ, PDB, CIF (structures) - Gaussian LOG/FCHK, NWChem OUT, Molpro OUT (quantum chemistry) - VASP vasprun.xml (periodic systems) - SDF/MOL (connection tables)

Limitation: Only the final geometry is embedded in .bin files; trajectories, orbitals, and frequency data are not currently included.

10.6 Viewer URL Parameters

The viewer accepts query parameters to customize behavior:

Parameter Example Description
scene ?scene=molecule.bin Path to .bin file (required)
camera ?camera=front Initial camera preset (front, side, top)
rotate ?rotate=true Auto-rotate on load (default: false)
background ?background=white Background color (white, black, hex code)
style ?style=spacefill Render style (ball-stick, spacefill, stick)

Examples:

<!-- Load with top-down camera view -->
<iframe src="index.html?scene=benzene.bin&camera=top"></iframe>

<!-- Auto-rotating viewer with white background -->
<iframe src="index.html?scene=ethanol.bin&rotate=true&background=white"></iframe>

<!-- Space-filling representation -->
<iframe src="index.html?scene=protein.bin&style=spacefill"></iframe>

Multiple parameters:

<iframe src="index.html?scene=molecule.bin&camera=front&rotate=true&background=%23f0f0f0&style=ball-stick"></iframe>

Note: URL parameters are case-sensitive. Use scene=file.bin, not Scene=file.bin.

10.7 Browser Compatibility

The web viewer requires WebGPU support. Current compatibility:

Browser Version Status Notes
Chrome 113+ ✅ Supported Recommended for best performance
Edge 113+ ✅ Supported Chromium-based, full WebGPU support
Firefox 120+ ⚠️ Experimental Enable dom.webgpu.enabled in about:config
Safari 17+ (macOS 14+) ✅ Supported Requires macOS Sonoma or later
Mobile Chrome Android 12+ ⚠️ Limited WebGPU available on some devices
Mobile Safari iOS 17+ ⚠️ Limited WebGPU available on recent iPads/iPhones

Checking WebGPU support:

Open the browser console and run:

navigator.gpu ? "WebGPU supported" : "WebGPU not supported"

Browser support:

The viewer renders via WebGL2 (wgpu’s GL backend), which every current browser supports — it does not require WebGPU. If no compatible WebGL2 adapter is available, it shows an error message.

Recommended deployment strategy: 1. Primary: Serve the WebGPU viewer for modern browsers 2. Fallback: Provide a static image or video for unsupported browsers 3. Detection: Use JavaScript to detect navigator.gpu and show appropriate content

Example detection:

<div id="viewer-container">
  <iframe id="viewer" src="/orbitron/index.html?scene=molecule.bin" width="800" height="600"></iframe>
</div>

<div id="fallback" style="display: none;">
  <img src="molecule-preview.png" alt="Molecule structure">
  <p>Your browser doesn't support WebGPU. <a href="https://caniuse.com/webgpu">Learn more</a></p>
</div>

<script>
if (!navigator.gpu) {
  document.getElementById('viewer-container').style.display = 'none';
  document.getElementById('fallback').style.display = 'block';
}
</script>

Performance tips: - File size: Keep .bin files under 5 MB for fast loading (optimize by removing extra metadata) - Hosting: Use CDN or static hosting (GitHub Pages, Netlify, Vercel) for best delivery - Caching: Set appropriate Cache-Control headers for .wasm and .bin files - Compression: Enable gzip/brotli compression on your web server for .wasm files

Security notes: - The viewer runs in the browser sandbox (no file system access) - .bin files are loaded via fetch() and must respect CORS policies - For cross-origin scenes, ensure your server sends Access-Control-Allow-Origin headers

Working examples: See examples/web-embedding/ for complete integration demos covering all deployment scenarios.

Need help? File an issue on GitHub or consult the Developer Guide (§8 Viewer WASM) for architecture details and customization options.