molview

Name	molview JSON
Version	0.1.0 JSON
	download
home_page	None
Summary	A Molstar-based protein viewer for Jupyter notebooks with py3dmol-compatible API
upload_time	2025-11-02 22:32:51
maintainer	None
docs_url	None
author	Steven Yu
requires_python	>=3.7
license	None
keywords	protein visualization jupyter molstar molecular structure bioinformatics
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # MolView

A Molstar-based protein viewer for Jupyter notebooks with a py3dmol-compatible API.

## Features

- **py3dmol-compatible API** - Easy transition from py3dmol
- **Powered by Molstar** - Advanced molecular visualization engine
- **Rich color themes** - 7 color modes including rainbow gradients and pLDDT confidence
- **Surface rendering** - Customizable molecular surfaces
- **Illustrative style** - Artistic rendering with outlines
- **Direct PDB/AlphaFold fetching** - Download structures without leaving Python
- **Grid layout** - Compare multiple structures side-by-side
- **Jupyter integration** - Native display in notebooks

## Installation

```bash
pip install -e .
```

## Quick Start

```python
import molview as mv

# Create viewer
v = mv.view(width=800, height=600)

# Load structure
with open('protein.pdb') as f:
    v.addModel(f.read(), 'pdb')

# Display
v.show()
```

## Fetching Structures from Databases

MolView can directly fetch structures from RCSB PDB and AlphaFold DB:

### Fetch from RCSB PDB
```python
import molview as mv

# Fetch ubiquitin structure (1UBQ)
data = mv.fetch_pdb('1UBQ')

v = mv.view()
v.addModel(data, 'pdb')
v.show()
```

### Fetch mmCIF format
```python
# Fetch in mmCIF format
data = mv.fetch_pdb('7BV2', format='mmcif')
v = mv.view()
v.addModel(data, 'mmcif')
v.show()
```

### Fetch from AlphaFold DB
```python
# Fetch AlphaFold prediction for Human ABL1 kinase
data = mv.fetch_alphafold('P00519')

v = mv.view()
v.addModel(data, 'mmcif')
v.setColorMode('plddt')  # Color by confidence
v.show()
```

### Search PDB Database
```python
# Search for structures
pdb_ids = mv.search_pdb('hemoglobin', max_results=5)
print(pdb_ids)  # ['1A3N', '1GZX', '2HHB', ...]

# Visualize first result
if pdb_ids:
    data = mv.fetch_pdb(pdb_ids[0])
    v = mv.view()
    v.addModel(data, 'pdb')
    v.show()
```

## Color Modes

MolView supports all color modes from the nano protein viewer:

### 1. Element (by atom type)
```python
v.setColorMode('element')
```

### 2. Custom (single color)
```python
v.setColorMode('custom', color='#FF0000')  # Red
v.setColorMode('custom', color='#4ECDC4')  # Teal (default)
```

### 3. Residue (by amino acid)
```python
v.setColorMode('residue')
```

### 4. Chain (by chain ID)
```python
# Auto colors
v.setColorMode('chain')

# Custom chain colors
v.setColorMode('chain', custom_colors={
    'A': '#FF0000',  # Red
    'B': '#00FF00',  # Green
    'C': '#0000FF'   # Blue
})
```

### 5. Secondary Structure
```python
# Default colors (helix=blue, sheet=green, coil=gray)
v.setColorMode('secondary')

# Custom colors
v.setColorMode('secondary',
    helix_color='#FF0000',  # Red helices
    sheet_color='#00FF00',  # Green sheets
    coil_color='#0000FF'    # Blue coils
)
```

### 6. Rainbow (gradient by sequence)
```python
# Available palettes: 'rainbow', 'viridis', 'plasma', 'magma', 'blue-red', 'pastel'
v.setColorMode('rainbow', palette='viridis')
v.setColorMode('rainbow', palette='plasma')
v.setColorMode('rainbow', palette='magma')
```

### 7. pLDDT (confidence for predicted structures)
```python
v.setColorMode('plddt')
```

## Grid Viewer (Multiple Structures)

Compare multiple structures side-by-side in a grid layout:

```python
# Create a 2x2 grid
v = mv.view(viewergrid=(2, 2), width=900, height=900)

# Load structures into specific positions
v.addModel(pdb1, 'pdb', viewer=(0, 0))  # Top-left
v.addModel(pdb2, 'pdb', viewer=(0, 1))  # Top-right
v.addModel(pdb3, 'pdb', viewer=(1, 0))  # Bottom-left
v.addModel(pdb4, 'pdb', viewer=(1, 1))  # Bottom-right

# Settings apply to all viewers
v.setColorMode('rainbow', palette='viridis')
v.setSurface(True, opacity=40)
v.show()
```

**Note**: In grid mode, the `viewer=(row, col)` parameter is required for `addModel()`.

See [example/grid_examples.ipynb](example/grid_examples.ipynb) for more grid layout examples.

## Advanced Features

### Surface Rendering
```python
# Enable surface 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
```python
# Enable artistic rendering with outlines
v.setIllustrativeStyle(True)
```

### Camera Controls
```python
# Reset camera view
v.zoomTo()

# Enable continuous rotation
v.spin(True)
```

### Background Color
```python
v.setBackgroundColor('#000000')  # Black
v.setBackgroundColor('#FFFFFF')  # White
```

## Complete Example

```python
import molview as mv

# Create viewer
v = mv.view(width=800, height=600)

# Load structure
with open('protein.pdb') as f:
    pdb_data = f.read()
v.addModel(pdb_data, 'pdb')

# Set rainbow coloring with viridis palette
v.setColorMode('rainbow', palette='viridis')

# Add semi-transparent surface
v.setSurface(True, opacity=40)

# Enable illustrative style
v.setIllustrativeStyle(True)

# Set black background
v.setBackgroundColor('#000000')

# Display
v.show()
```

## Comparison with py3dmol

MolView is designed to be a drop-in replacement for py3dmol with additional features:

### py3dmol code:
```python
import py3dmol
v = py3dmol.view(width=800, height=600)
v.addModel(pdb_data, 'pdb')
v.setStyle({'cartoon': {'color': 'spectrum'}})
v.show()
```

### Equivalent MolView code:
```python
import molview as mv
v = mv.view(width=800, height=600)
v.addModel(pdb_data, 'pdb')
v.setColorMode('rainbow')
v.show()
```

## Supported Formats

- **PDB** - Protein Data Bank format
- **mmCIF** - Macromolecular Crystallographic Information File
- **SDF** - Structure Data File (coming soon)

## API Reference

### Viewer Creation
- `view(width, height, viewergrid)` - Create viewer instance
  - `viewergrid=(rows, cols)` - Optional grid layout for multiple structures

### Model Management
- `addModel(data, format, viewer)` - Load structure data
  - `viewer=(row, col)` - Required in grid mode to specify position
- `clear()` - Remove all models

### Fetching Structures
- `fetch_pdb(pdb_id, format='pdb')` - Fetch structure from RCSB PDB
- `query(pdb_id, format='pdb')` - Alias for fetch_pdb (py3dmol compatibility)
- `fetch_alphafold(uniprot_id, version=4)` - Fetch AlphaFold prediction
- `search_pdb(query_text, max_results=10)` - Search PDB database

### Styling
- `setColorMode(mode, **kwargs)` - Set color theme
- `setStyle(style)` - Set representation (cartoon default)
- `setSurface(enabled, opacity, inherit_color, color)` - Configure surface
- `setIllustrativeStyle(enabled)` - Toggle illustrative rendering
- `setBackgroundColor(color)` - Set background

### Camera
- `zoomTo()` - Reset camera view
- `spin(enabled)` - Toggle continuous rotation

### Display
- `show()` - Render in notebook

## Color Palettes

### Rainbow Palettes
Available palettes for `setColorMode('rainbow', palette='...')`:

- `'rainbow'` - Classic rainbow (ROYGBIV)
- `'viridis'` - Perceptually uniform (purple to yellow)
- `'plasma'` - Bright and vibrant (purple to yellow)
- `'magma'` - Dark and moody (black to white)
- `'blue-red'` - Simple blue to red gradient
- `'pastel'` - Soft pastel colors

### Custom Color Palette
Pre-defined colors for `setColorMode('custom', color='...')`:

- Teal: `#4ECDC4` (default)
- Red: `#FF6B6B`
- Blue: `#4DABF7`
- Green: `#69DB7C`
- Yellow: `#FFD93D`
- Orange: `#FF922B`
- Purple: `#DA77F2`
- Pink: `#FF8CC8`
- Cyan: `#15AABF`
- Gray: `#868E96`

## Requirements

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

## License

MIT License

## Contributing

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

**Repository**: [github.com/54yyyu/molview](https://github.com/54yyyu/molview)

This package uses modern Python packaging with `pyproject.toml` (PEP 517/518).

## Acknowledgments

- Built with [Molstar](https://molstar.org/) - Modern molecular visualization toolkit
- API inspired by [py3dmol](https://github.com/3dmol/3Dmol.js) - Python interface to 3Dmol.js
- Color palettes from scientific visualization best practices

## Roadmap

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

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "molview",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": null,
    "keywords": "protein, visualization, jupyter, molstar, molecular, structure, bioinformatics",
    "author": "Steven Yu",
    "author_email": null,
    "download_url": "https://files.pythonhosted.org/packages/17/a4/ea1fecaf6be2834f6dc48d66ca1294b2ce7c1227c989e0e6981834855381/molview-0.1.0.tar.gz",
    "platform": null,
    "description": "# MolView\n\nA Molstar-based protein viewer for Jupyter notebooks with a py3dmol-compatible API.\n\n## Features\n\n- **py3dmol-compatible API** - Easy transition from py3dmol\n- **Powered by Molstar** - Advanced molecular visualization engine\n- **Rich color themes** - 7 color modes including rainbow gradients and pLDDT confidence\n- **Surface rendering** - Customizable molecular surfaces\n- **Illustrative style** - Artistic rendering with outlines\n- **Direct PDB/AlphaFold fetching** - Download structures without leaving Python\n- **Grid layout** - Compare multiple structures side-by-side\n- **Jupyter integration** - Native display in notebooks\n\n## Installation\n\n```bash\npip install -e .\n```\n\n## Quick Start\n\n```python\nimport molview as mv\n\n# Create viewer\nv = mv.view(width=800, height=600)\n\n# Load structure\nwith open('protein.pdb') as f:\n    v.addModel(f.read(), 'pdb')\n\n# Display\nv.show()\n```\n\n## Fetching Structures from Databases\n\nMolView can directly fetch structures from RCSB PDB and AlphaFold DB:\n\n### Fetch from RCSB PDB\n```python\nimport molview as mv\n\n# Fetch ubiquitin structure (1UBQ)\ndata = mv.fetch_pdb('1UBQ')\n\nv = mv.view()\nv.addModel(data, 'pdb')\nv.show()\n```\n\n### Fetch mmCIF format\n```python\n# Fetch in mmCIF format\ndata = mv.fetch_pdb('7BV2', format='mmcif')\nv = mv.view()\nv.addModel(data, 'mmcif')\nv.show()\n```\n\n### Fetch from AlphaFold DB\n```python\n# Fetch AlphaFold prediction for Human ABL1 kinase\ndata = mv.fetch_alphafold('P00519')\n\nv = mv.view()\nv.addModel(data, 'mmcif')\nv.setColorMode('plddt')  # Color by confidence\nv.show()\n```\n\n### Search PDB Database\n```python\n# Search for structures\npdb_ids = mv.search_pdb('hemoglobin', max_results=5)\nprint(pdb_ids)  # ['1A3N', '1GZX', '2HHB', ...]\n\n# Visualize first result\nif pdb_ids:\n    data = mv.fetch_pdb(pdb_ids[0])\n    v = mv.view()\n    v.addModel(data, 'pdb')\n    v.show()\n```\n\n## Color Modes\n\nMolView supports all color modes from the nano protein viewer:\n\n### 1. Element (by atom type)\n```python\nv.setColorMode('element')\n```\n\n### 2. Custom (single color)\n```python\nv.setColorMode('custom', color='#FF0000')  # Red\nv.setColorMode('custom', color='#4ECDC4')  # Teal (default)\n```\n\n### 3. Residue (by amino acid)\n```python\nv.setColorMode('residue')\n```\n\n### 4. Chain (by chain ID)\n```python\n# Auto colors\nv.setColorMode('chain')\n\n# Custom chain colors\nv.setColorMode('chain', custom_colors={\n    'A': '#FF0000',  # Red\n    'B': '#00FF00',  # Green\n    'C': '#0000FF'   # Blue\n})\n```\n\n### 5. Secondary Structure\n```python\n# Default colors (helix=blue, sheet=green, coil=gray)\nv.setColorMode('secondary')\n\n# Custom colors\nv.setColorMode('secondary',\n    helix_color='#FF0000',  # Red helices\n    sheet_color='#00FF00',  # Green sheets\n    coil_color='#0000FF'    # Blue coils\n)\n```\n\n### 6. Rainbow (gradient by sequence)\n```python\n# Available palettes: 'rainbow', 'viridis', 'plasma', 'magma', 'blue-red', 'pastel'\nv.setColorMode('rainbow', palette='viridis')\nv.setColorMode('rainbow', palette='plasma')\nv.setColorMode('rainbow', palette='magma')\n```\n\n### 7. pLDDT (confidence for predicted structures)\n```python\nv.setColorMode('plddt')\n```\n\n## Grid Viewer (Multiple Structures)\n\nCompare multiple structures side-by-side in a grid layout:\n\n```python\n# Create a 2x2 grid\nv = mv.view(viewergrid=(2, 2), width=900, height=900)\n\n# Load structures into specific positions\nv.addModel(pdb1, 'pdb', viewer=(0, 0))  # Top-left\nv.addModel(pdb2, 'pdb', viewer=(0, 1))  # Top-right\nv.addModel(pdb3, 'pdb', viewer=(1, 0))  # Bottom-left\nv.addModel(pdb4, 'pdb', viewer=(1, 1))  # Bottom-right\n\n# Settings apply to all viewers\nv.setColorMode('rainbow', palette='viridis')\nv.setSurface(True, opacity=40)\nv.show()\n```\n\n**Note**: In grid mode, the `viewer=(row, col)` parameter is required for `addModel()`.\n\nSee [example/grid_examples.ipynb](example/grid_examples.ipynb) for more grid layout examples.\n\n## Advanced Features\n\n### Surface Rendering\n```python\n# Enable surface with default opacity (40%)\nv.setSurface(True)\n\n# Custom opacity (0-100)\nv.setSurface(True, opacity=60)\n\n# Custom surface color\nv.setSurface(True, opacity=40, inherit_color=False, color='#FF0000')\n```\n\n### Illustrative Style\n```python\n# Enable artistic rendering with outlines\nv.setIllustrativeStyle(True)\n```\n\n### Camera Controls\n```python\n# Reset camera view\nv.zoomTo()\n\n# Enable continuous rotation\nv.spin(True)\n```\n\n### Background Color\n```python\nv.setBackgroundColor('#000000')  # Black\nv.setBackgroundColor('#FFFFFF')  # White\n```\n\n## Complete Example\n\n```python\nimport molview as mv\n\n# Create viewer\nv = mv.view(width=800, height=600)\n\n# Load structure\nwith open('protein.pdb') as f:\n    pdb_data = f.read()\nv.addModel(pdb_data, 'pdb')\n\n# Set rainbow coloring with viridis palette\nv.setColorMode('rainbow', palette='viridis')\n\n# Add semi-transparent surface\nv.setSurface(True, opacity=40)\n\n# Enable illustrative style\nv.setIllustrativeStyle(True)\n\n# Set black background\nv.setBackgroundColor('#000000')\n\n# Display\nv.show()\n```\n\n## Comparison with py3dmol\n\nMolView is designed to be a drop-in replacement for py3dmol with additional features:\n\n### py3dmol code:\n```python\nimport py3dmol\nv = py3dmol.view(width=800, height=600)\nv.addModel(pdb_data, 'pdb')\nv.setStyle({'cartoon': {'color': 'spectrum'}})\nv.show()\n```\n\n### Equivalent MolView code:\n```python\nimport molview as mv\nv = mv.view(width=800, height=600)\nv.addModel(pdb_data, 'pdb')\nv.setColorMode('rainbow')\nv.show()\n```\n\n## Supported Formats\n\n- **PDB** - Protein Data Bank format\n- **mmCIF** - Macromolecular Crystallographic Information File\n- **SDF** - Structure Data File (coming soon)\n\n## API Reference\n\n### Viewer Creation\n- `view(width, height, viewergrid)` - Create viewer instance\n  - `viewergrid=(rows, cols)` - Optional grid layout for multiple structures\n\n### Model Management\n- `addModel(data, format, viewer)` - Load structure data\n  - `viewer=(row, col)` - Required in grid mode to specify position\n- `clear()` - Remove all models\n\n### Fetching Structures\n- `fetch_pdb(pdb_id, format='pdb')` - Fetch structure from RCSB PDB\n- `query(pdb_id, format='pdb')` - Alias for fetch_pdb (py3dmol compatibility)\n- `fetch_alphafold(uniprot_id, version=4)` - Fetch AlphaFold prediction\n- `search_pdb(query_text, max_results=10)` - Search PDB database\n\n### Styling\n- `setColorMode(mode, **kwargs)` - Set color theme\n- `setStyle(style)` - Set representation (cartoon default)\n- `setSurface(enabled, opacity, inherit_color, color)` - Configure surface\n- `setIllustrativeStyle(enabled)` - Toggle illustrative rendering\n- `setBackgroundColor(color)` - Set background\n\n### Camera\n- `zoomTo()` - Reset camera view\n- `spin(enabled)` - Toggle continuous rotation\n\n### Display\n- `show()` - Render in notebook\n\n## Color Palettes\n\n### Rainbow Palettes\nAvailable palettes for `setColorMode('rainbow', palette='...')`:\n\n- `'rainbow'` - Classic rainbow (ROYGBIV)\n- `'viridis'` - Perceptually uniform (purple to yellow)\n- `'plasma'` - Bright and vibrant (purple to yellow)\n- `'magma'` - Dark and moody (black to white)\n- `'blue-red'` - Simple blue to red gradient\n- `'pastel'` - Soft pastel colors\n\n### Custom Color Palette\nPre-defined colors for `setColorMode('custom', color='...')`:\n\n- Teal: `#4ECDC4` (default)\n- Red: `#FF6B6B`\n- Blue: `#4DABF7`\n- Green: `#69DB7C`\n- Yellow: `#FFD93D`\n- Orange: `#FF922B`\n- Purple: `#DA77F2`\n- Pink: `#FF8CC8`\n- Cyan: `#15AABF`\n- Gray: `#868E96`\n\n## Requirements\n\n- Python >=3.7\n- IPython >=7.0.0\n- Jupyter >=1.0.0\n\n## License\n\nMIT License\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n**Repository**: [github.com/54yyyu/molview](https://github.com/54yyyu/molview)\n\nThis package uses modern Python packaging with `pyproject.toml` (PEP 517/518).\n\n## Acknowledgments\n\n- Built with [Molstar](https://molstar.org/) - Modern molecular visualization toolkit\n- API inspired by [py3dmol](https://github.com/3dmol/3Dmol.js) - Python interface to 3Dmol.js\n- Color palettes from scientific visualization best practices\n\n## Roadmap\n\n- [x] Multiple viewer grid support\n- [ ] Selection and highlighting\n- [ ] Animation playback\n- [ ] Label/annotation support\n- [ ] Export to image/video\n- [ ] Additional representation styles (stick, sphere, line)\n- [ ] Measurement tools\n- [ ] Surface customization options\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "A Molstar-based protein viewer for Jupyter notebooks with py3dmol-compatible API",
    "version": "0.1.0",
    "project_urls": {
        "Documentation": "https://github.com/54yyyu/molview#readme",
        "Homepage": "https://github.com/54yyyu/molview",
        "Issues": "https://github.com/54yyyu/molview/issues",
        "Repository": "https://github.com/54yyyu/molview"
    },
    "split_keywords": [
        "protein",
        " visualization",
        " jupyter",
        " molstar",
        " molecular",
        " structure",
        " bioinformatics"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "3622b6dd7beb2dc78b26e3160d31fb01ad7bee153a62a7cf4793ac31b5f87a91",
                "md5": "cfdb506f1998e98eeb0eeb47de6d239d",
                "sha256": "a5217499697f5ac09c85c439f5d3019db63eab1785cd0e68f723561e45e3936b"
            },
            "downloads": -1,
            "filename": "molview-0.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "cfdb506f1998e98eeb0eeb47de6d239d",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 44335,
            "upload_time": "2025-11-02T22:32:50",
            "upload_time_iso_8601": "2025-11-02T22:32:50.581982Z",
            "url": "https://files.pythonhosted.org/packages/36/22/b6dd7beb2dc78b26e3160d31fb01ad7bee153a62a7cf4793ac31b5f87a91/molview-0.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "17a4ea1fecaf6be2834f6dc48d66ca1294b2ce7c1227c989e0e6981834855381",
                "md5": "02e59a2c1c54913fbd0e595981e1dc13",
                "sha256": "e44c8f51aed44e50cf7b9314bd807d15bdd29291aad4d82e7017a7e0e2ec82c0"
            },
            "downloads": -1,
            "filename": "molview-0.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "02e59a2c1c54913fbd0e595981e1dc13",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 45922,
            "upload_time": "2025-11-02T22:32:51",
            "upload_time_iso_8601": "2025-11-02T22:32:51.715286Z",
            "url": "https://files.pythonhosted.org/packages/17/a4/ea1fecaf6be2834f6dc48d66ca1294b2ce7c1227c989e0e6981834855381/molview-0.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-11-02 22:32:51",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "54yyyu",
    "github_project": "molview#readme",
    "github_not_found": true,
    "lcname": "molview"
}