ProteinStructureView add feature to download PDB and coloring files for Mol*, PyMol, and ChimeraX by davereinhart · Pull Request #701 · VariantEffect/mavedb-ui

davereinhart · 2026-07-10T15:26:49Z

This pull request adds advanced structure export features to the ProteinStructureView component, allowing users to download the currently viewed AlphaFold structure in multiple formats (PDB, PyMOL, ChimeraX, and MolViewSpec JSON) with coloring that matches the in-app visualization. It introduces a new download split button, script generation for color mapping, and refactors model fetching and state management for improved extensibility.

New Download Features:

Added a SplitButton to the UI for downloading the current structure in various formats (PDB, PyMOL .pml, ChimeraX .cxc, MolViewSpec .mvsj), with menu items and handlers for each format. [1] [2] [3] [4]

Script and File Generation:

Implemented methods to generate PyMOL, ChimeraX, and MolViewSpec scripts/files that reproduce the coloring currently shown in the viewer, including helper methods for residue selection and color normalization.

Model Fetching and State Management:

Refactored AlphaFold model fetching to store the selected model object (including URLs and IDs) in selectedModel, improving subsequent download and script generation logic. [1] [2] [3]

UI and Usability Improvements:

The download button is disabled unless a model is loaded, and filenames for downloads reflect the selected coloring and model. [1] [2]

Internal Refactoring:

Added utility methods for color normalization, RGB conversion, and residue selection compression to support script generation and maintain code clarity.

Add a "Download PDB" button to ProteinStructureView that downloads the PDB coordinate file for the currently displayed AlphaFold model. The PDB URL (pdbUrl) is read from the same AlphaFold prediction metadata already fetched to obtain the CIF URL loaded by the viewer.

Turn the structure viewer's download control into a SplitButton offering both the PDB structure and a PyMOL coloring script (.pml). The generated script reproduces the exact residue colors currently shown in the viewer for the selected "Color by" mode: it defines each displayed color with set_color and applies it to the matching residues via `color ..., resi`, reusing the same (residue number, color) pairs the viewer feeds to molstar so the coloring matches after loading the companion PDB.

Add a "ChimeraX coloring script (.cxc)" option to the structure viewer's download menu. The generated command script reproduces the same per-residue coloring as the PyMOL script, using `color /A:<ranges> #<hex> target acs` per unique color plus a whole-chain base color; ChimeraX accepts hex colors directly and writes residue lists as "5-8,12". Extract the residue grouping and run-compression (groupResiduesByColor, residueRuns) shared by the PyMOL and ChimeraX builders.

Add a "Mol* coloring script (.mvsj)" option to the structure viewer's download menu. The generated MolViewSpec document reproduces the current per-residue coloring for loading in the Mol* viewer (drag-and-drop, or the ?mvs-url= parameter). It fetches the AlphaFold structure by URL, so it is self-contained (no companion file needed), and selects residues by author numbering (auth_seq_id = UniProt position) to match MaveDB's numbering.

…type names

coveralls · 2026-07-10T15:28:37Z

coverage: 2.596%. remained the same — davereinhart/protein-viz-download-pdb into release-2026.2.5

bencap

Thanks Dave, opened these all in their respective apps and looks good. My one question is with the download button UI/UX. I'm wondering if the tradeoffs are worth it to have a Download PDB and a Export coloring as menu. The current drop down blurs the PDB with the coloring scripts a little bit.

I don't want to clutter the toolbar too much with a third control though, and I know the select button is already wide (as an aside, I wonder if swapping that to a drop-down might also be worthwhile to keep things un-cluttered as we add more controls).

I mainly just want to make sure users know that these coloring exports exist.

davereinhart · 2026-07-20T16:40:42Z

That makes sense, but there is some inherent overlap. In the case of the MolViewSpec JSON format, it includes both the model and the coloring in one file. The PyMol and ChimeraX formats are for applying colors to a model that is already loaded. That could probably be clearer by using a different icon for for the MolViewSpec download and/or adding option group headers to the dropdown (model, coloring, model + coloring). I'll try both.

Organize the SplitButton download menu into Model / Coloring / Model + Coloring sections. Since SplitButton uses TieredMenu (whose nested items render as flyouts rather than inline headers), the flat model uses disabled rows as group headers plus separators between groups, styled to read like section headers. Switch the menu icons to FontAwesome, rendered via the #menuitemicon slot so the MolViewSpec item can show two glyphs: cube for structure (matching Mol*'s structure-export icon), palette for coloring, and cube + palette for the combined export.

bencap

Looks good!

Resolve the ProteinStructureView.vue conflict by re-applying the download menu on top of the release's new multi-structure model. The release replaced the single-AlphaFold model (selectedAlphaFold + jQuery-parsed uniprotData) with allStructureModels/selectedModelId and a computed selectedModel of shape {id, url, format, provider, start, end, ...}, plus a segment selector and canonical-residue mapping. Adaptations of the download feature to the new model: - Read selectedModel.url / .format / .id instead of the old .pdbUrl / .cifUrl / .entryId, which no longer exist. - "PDB structure" download becomes "Structure file": it downloads selectedModel.url in its native format (cif/pdb/bcif) as a blob, since the model no longer carries a separate PDB URL. - The .mvsj export downloads selectedModel.url and derives the Mol* parse format from selectedModel.format. - Coloring-script filenames and the model id in script headers come from selectedModel.id. - Dropped the now-obsolete fetchAlphaFoldModel helper and my earlier render/destroyViewer edits in favor of the release's rewritten versions. The coloring exports (.pml/.cxc/.mvsj) write canonical UniProt residue numbers, which are correct for AlphaFold and SWISS-MODEL but would mis-color PDBe author-numbered structures. They are therefore omitted from the download menu when a PDBe structure is selected, leaving only the raw structure-file download.

List every structure-file format the source provides in the download menu's Model group instead of a single "Structure file" item. AlphaFold offers .pdb, .cif and .bcif; 3D-Beacons sources (PDBe, SWISS-MODEL) offer the one format they advertise. Each structure model now carries a `downloads` list ({format, label, url}) built by a `structureDownloads` helper, and the main split-button click downloads the first offered format.

3D-Beacons model URLs carry query strings (?range=...&template=...) and their model ids contain ":", so deriving download filenames from them produced invalid names like "Q86UP3.pdb_range=2190-2238&template=2da2.1.A&provider=swissmodel". Route every download filename (structure formats and the .pml/.cxc/.mvsj coloring exports) through a downloadBaseName that keeps AlphaFold's clean native filename (AF-<acc>-F1-model_v6) but builds a filesystem-safe "{uniprot}_{start}-{end}" name for PDBe and SWISS-MODEL structures.

davereinhart added 5 commits July 10, 2026 08:23

fix(protein-viewer): Update download button labels with correct file …

32998cd

…type names

davereinhart linked an issue Jul 10, 2026 that may be closed by this pull request

Add feature to download model file from protein structure viewer #646

Open

davereinhart changed the title ~~ProteinStructureView add feature todownload PDB and coloring files for Mol*, PyMol, and ChimeraX viewers~~ ProteinStructureView add feature to download PDB and coloring files for Mol*, PyMol, and ChimeraX Jul 10, 2026

bencap approved these changes Jul 20, 2026

View reviewed changes

davereinhart added 3 commits July 21, 2026 08:44

davereinhart merged commit bba0370 into release-2026.2.5 Jul 21, 2026
1 check passed

davereinhart deleted the davereinhart/protein-viz-download-pdb branch July 21, 2026 15:49

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

ProteinStructureView add feature to download PDB and coloring files for Mol*, PyMol, and ChimeraX#701

ProteinStructureView add feature to download PDB and coloring files for Mol*, PyMol, and ChimeraX#701
davereinhart merged 9 commits into
release-2026.2.5from
davereinhart/protein-viz-download-pdb

davereinhart commented Jul 10, 2026

Uh oh!

coveralls commented Jul 10, 2026 •

edited

Loading

Uh oh!

bencap left a comment

Uh oh!

davereinhart commented Jul 20, 2026

Uh oh!

bencap left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

davereinhart commented Jul 10, 2026

Uh oh!

coveralls commented Jul 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bencap left a comment

Choose a reason for hiding this comment

Uh oh!

davereinhart commented Jul 20, 2026

Uh oh!

bencap left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

coveralls commented Jul 10, 2026 •

edited

Loading