MolView

An IPython/Jupyter widget for interactive molecular visualization, based on Molstar. This is the Jupyter widget version of nano-protein-viewer.

Features

img

Molstar-powered visualization - Advanced molecular graphics engine
Multiple color modes - Element, chain, secondary structure, rainbow gradients, pLDDT confidence, and custom colors
Interactive controls - Optional control panel with real-time adjustments
Surface rendering - Molecular surfaces with customizable opacity
Illustrative rendering - Outline-based artistic visualization
Grid layout - Side-by-side comparison of multiple structures
Structure fetching - Direct download from RCSB PDB and AlphaFold Database
File downloads - Export loaded structures
py3dmol-like API - Familiar interface for easy adoption

Installation

pip install molview

Or using uv:

uv pip install molview

Quick Start

import molview as mv
# Create viewer
v = mv.view(width=800, height=600)
# Load structure from file
with open('protein.pdb') as f:
 v.addModel(f.read())
# Or fetch from RCSB PDB
pdb_data = mv.fetch_pdb('1CRN')
v.addModel(pdb_data)
# Customize and display
v.setColorMode('rainbow', palette='viridis')
v.show()

Control Panel

Enable the interactive control panel for real-time adjustments:

v = mv.view(width=800, height=600, panel=True)
v.addModel(pdb_data)
v.show()

The panel provides controls for:

Color modes with customizable parameters
Surface rendering toggle and opacity
Solvent molecule removal
File downloads
Spin animation with speed control

Fetching Structures

From RCSB PDB

# Fetch PDB format
data = mv.fetch_pdb('1UBQ')
v = mv.view()
v.addModel(data)
v.show()
# Fetch mmCIF format
data = mv.fetch_pdb('7BV2', format='mmcif')
v.addModel(data)

From AlphaFold Database

# Fetch by UniProt ID
data = mv.fetch_alphafold('P00519')
v = mv.view()
v.addModel(data)
v.setColorMode('plddt') # Color by confidence
v.show()

Search PDB

# Search for structures
pdb_ids = mv.search_pdb('hemoglobin', max_results=5)
print(pdb_ids) # ['1A3N', '1GZX', '2HHB', ...]
# Visualize first result
data = mv.fetch_pdb(pdb_ids[0])
v = mv.view()
v.addModel(data)
v.show()

Color Modes

Element

Color by atom type (CPK coloring):

v.setColorMode('element')

Custom

Single uniform color:

v.setColorMode('custom', color='#FF6B6B')

Chain

Color by protein chain:

# Automatic colors
v.setColorMode('chain')
# Custom chain colors
v.setColorMode('chain', custom_colors={
 'A': '#FF0000',
 'B': '#00FF00'
})

Secondary Structure

Color by structural elements:

# Default colors
v.setColorMode('secondary')
# Custom colors
v.setColorMode('secondary',
 helix_color='#FF6B6B',
 sheet_color='#4ECDC4',
 coil_color='#FFE66D'
)

Rainbow Gradient

Color by sequence position with scientific color palettes:

v.setColorMode('rainbow', palette='viridis')
v.setColorMode('rainbow', palette='plasma')
v.setColorMode('rainbow', palette='magma')

Available palettes: rainbow, viridis, plasma, magma, blue-red, pastel

pLDDT Confidence

Color predicted structures by confidence scores:

v.setColorMode('plddt')

Colors: Dark blue (>90), light blue (70-90), yellow (50-70), orange (<50)

Grid Layout

Display multiple structures side-by-side:

# Create 2x2 grid
v = mv.view(viewergrid=(2, 2), width=900, height=900)
# Load structures into specific positions
v.addModel(pdb1, viewer=(0, 0)) # Top-left
v.addModel(pdb2, viewer=(0, 1)) # Top-right
v.addModel(pdb3, viewer=(1, 0)) # Bottom-left
v.addModel(pdb4, viewer=(1, 1)) # Bottom-right
# Apply settings to all viewers
v.setColorMode('rainbow', palette='viridis')
v.show()

The viewer=(row, col) parameter is required when using grid layout.

Advanced Features

Surface Rendering

# Enable with default opacity (40%)
v.setSurface(True)
# Custom opacity (0-100)
v.setSurface(True, opacity=60)
# Custom surface color
v.setSurface(True, opacity=40, inherit_color=False, color='#FF0000')

Illustrative Style

Artistic rendering with outlines:

v.setIllustrativeStyle(True)

Animation

# Enable spinning
v.spin(True)
# Custom speed
v.spin(True, speed=0.5)
# Stop spinning
v.spin(False)

Solvent Removal

Remove water molecules and ions:

v.removeSolvent(True)

Background Color

v.setBackgroundColor('#000000') # Black
v.setBackgroundColor('#FFFFFF') # White

Complete Example

import molview as mv
# Create viewer with control panel
v = mv.view(width=800, height=600, panel=True)
# Fetch and load structure
pdb_data = mv.fetch_pdb('1CRN')
v.addModel(pdb_data)
# Apply styling
v.setColorMode('rainbow', palette='viridis')
v.setSurface(True, opacity=40)
v.setIllustrativeStyle(True)
v.setBackgroundColor('#1a1a2e')
v.spin(True, speed=0.2)
# Display
v.show()

API Reference

Creating Viewers

view(width=800, height=600, viewergrid=None, panel=False)

width, height: Viewer dimensions in pixels
viewergrid: Tuple of (rows, cols) for grid layout
panel: Enable interactive control panel

Loading Structures

addModel(data, format=None, viewer=None)

data: Structure data string
format: Auto-detected if not specified (pdb, mmcif, sdf)
viewer: Grid position (row, col) for grid layout

Fetching Data

fetch_pdb(pdb_id, format='pdb') # Fetch from RCSB PDB
fetch_alphafold(uniprot_id, version=4) # Fetch from AlphaFold DB
search_pdb(query, max_results=10) # Search PDB database
query(pdb_id, format='pdb') # Alias for fetch_pdb

Styling Methods

setColorMode(mode, **kwargs) # Set color scheme
setBackgroundColor(color) # Set background
setSurface(enabled, opacity, ...) # Configure surface
setIllustrativeStyle(enabled) # Toggle outlines
spin(enabled, speed) # Toggle rotation
removeSolvent(enabled) # Toggle solvent visibility
zoomTo() # Reset camera
show() # Render viewer

Supported Formats

PDB - Protein Data Bank format
mmCIF - Macromolecular Crystallographic Information File
SDF - Structure Data File (small molecules)

Format is auto-detected from file content.

Requirements

Python >=3.7
IPython >=7.0.0
Jupyter >=1.0.0

Examples

See the example/ directory for Jupyter notebooks:

example.ipynb - Comprehensive feature demonstrations
grid_examples.ipynb - Grid layout examples

Online Notebooks (Google Colab)

Try MolView directly in your browser without installation:

MolView Examples - Comprehensive feature demonstrations
ColabFold Integration - Protein structure prediction with ColabFold
Boltz-2 Integration - Protein structure prediction with Boltz-2

py3dmol Compatibility

MolView provides a py3dmol-like API for easy adoption. Key differences:

Format auto-detection (second parameter optional)
Additional color modes (pLDDT, rainbow gradients)
Built-in control panel
Grid layout support
Structure fetching utilities

Related Projects

nano-protein-viewer - Standalone vscode/cursor plugin version
protein-viewer - Standalone web app version
Molstar - Underlying visualization engine

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

Built with Molstar - Modern molecular visualization toolkit
Project idea inspired by py2Dmol
API inspired by py3dmol - Python interface to 3Dmol.js
Color palettes from scientific visualization best practices

Roadmap

Multiple viewer grid support
Export to image/video
Surface customization options
Selection and highlighting
Animation playback
Label/annotation support
Additional representation styles (stick, sphere, line)

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
example		example
media		media
molview		molview
.gitignore		.gitignore
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
setup.py		setup.py

Latest commit

History

Folders and files

Repository files navigation