BioViewer

A powerful Visual Studio Code extension for visualizing biological structures and electron microscopy maps. Built on Mol*, BioViewer brings advanced molecular visualization directly into your development environment.

✨ Key Features

• 🗺️ Electron Microscopy Maps: Full support for MRC, MAP, and CCP4 volume files with proper visualization
• 🌐 Remote SSH Ready: Optimized for remote development with efficient file transfer
• 📦 Compression Support: Automatic .gz file handling saves bandwidth - especially valuable for remote connections
• 🧬 Multiple Formats: PDB, mmCIF, and all standard structural biology file formats
• 📍 Marker Overlays: Chimera .cmm marker models render prompt points and marker links on top of loaded maps or structures
• 🔗 Database Integration: Direct access to PDB, AlphaFold, and EMDB databases

🚀 Installation

1. Open Visual Studio Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "BioViewer"
4. Click Install

📖 Usage

Commands (Command Palette: Ctrl+Shift+P / Cmd+Shift+P)

Supported Formats

CMM Marker Models

BioViewer supports Chimera marker model files (.cmm and .cmm.gz) as marker overlays. A CMM file must contain one <marker_set> with one or more direct <marker> children:

<marker_set name="example_prompt">
  <marker id="1" x="59.4500" y="95.1850" z="24.3564" r="1.0" g="0.0" b="0.0" radius="1.0" />
</marker_set>

Required marker attributes are id, x, y, and z. Optional radius, r, g, and b attributes control sphere size and color. Direct <link id1="..." id2="..."> children are supported when both marker ids exist; links render as tubes. CMM coordinates are rendered as stored so prompt points can be overlaid on matching MRC/MAP/CCP4 density maps without replacing the map.

Quick Start

Right-click any supported file in VS Code Explorer → "BioViewer: Open Files"

🌐 Remote Development

BioViewer is optimized for remote SSH scenarios:

• Bandwidth Efficient: .gz files stay compressed during transfer
• Smart Decompression: Files decompress in browser, not on server
• Large File Handling: Memory-efficient processing of big datasets

⚙️ Requirements

• Visual Studio Code ^1.105.1 (for compatibility with Cursor)
• Modern web browser (for WebGL support)

🙏 Acknowledgments

This extension was inspired by molstar/VSCoding-Sequence and builds upon the powerful Mol* molecular visualization library.

Key Dependencies:

• Mol* (v5.7.0) - The core molecular visualization engine
• PDBe & RCSB PDB - Structural databases
• AlphaFold - AI protein structure predictions
• EMDB - Electron Microscopy Data Bank

🛠️ Development

git clone https://github.com/shuuul/bioviewer.git
cd bioviewer
npm install
prek install      # Install git pre-commit hooks
npm run watch    # Development mode
npm run compile  # Production build

BioViewer uses prek to run pre-commit checks (linting, type checks, and file hygiene hooks) before commits.

🐞 Debugging in VS Code

1. Open this repository in VS Code and run npm install.
2. Start debugging with F5 (or Run and Debug) using the Run Extension launch configuration.
3. VS Code opens an Extension Development Host window; run BioViewer commands there to reproduce issues.
4. Set breakpoints in src/**/*.{ts,tsx} (source maps map to dist/**/*.js).
5. Check extension logs in Output panel -> BioViewer.
6. For webview issues, run Developer: Toggle Developer Tools in the Extension Development Host and inspect console errors.
7. To debug tests, run npm run compile-tests and launch Extension Tests.

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• Documentation
• Issues
• Releases

Made with ❤️ for the structural biology community