dsh-file-explorer-preview-molstar
中文 | English
A DSH Web plugin that adds a Mol* 3D structure viewer to dsh-file-explorer, overriding its plain previews for protein-structure and small-molecule files.
Select a .cif / .pdb (or any supported format below) in the file explorer and the preview panel renders an interactive 3D model instead of raw text.
Screenshots
Features
- 3D structure viewer built on
molstar (PluginContext + a minimal canvas — no full Mol* UI).
- Representation presets: Auto / Cartoon / Ball & Stick / Molecular surface.
- Coloring by default / chain / entity, reset camera, spin toggle, and a dark/light background that follows DSH's
data-ds-dark-theme.
- Status bar with the format badge and atom/residue/chain counts.
- Localized toolbar/status copy (中文 / English).
- Large & binary files: for files over the core's 2 MiB text cap (returned as the
text-large kind since dsh-file-explorer v0.3.0), and for .bcif, the plugin fetches raw bytes through the core's fileExplorer.readRawFile (standard in dsh-file-explorer v0.1.0+).
Supported formats
| Extension | Format |
|---|
cif mmcif mcif | mmCIF |
bcif | BinaryCIF |
pdb ent | PDB |
pdbqt | PDBQT |
pqr | PQR |
sdf sd | SDF |
mol | MOL |
mol2 | MOL2 |
xyz | XYZ |
gro | GRO |
Install
From the Git repository
dsh plugin --profile web add github:wolfsonliu/dsh-file-explorer-preview-molstar
dsh web
From source
git clone https://github.com/wolfsonliu/dsh-file-explorer-preview-molstar
cd dsh-file-explorer-preview-molstar
npm install
npm run build
dsh plugin --profile web add .
dsh web
Dependencies
This plugin requires @dsh-external/dsh-file-explorer v0.1.0 or later — it injects the fileExplorer cordis service (registerViewer / registerPreview / writeFile / readRawFile). Install and enable dsh-file-explorer before this plugin:
# install the core from git
dsh plugin --profile web add github:wolfsonliu/dsh-file-explorer
# or, from source
git clone https://github.com/wolfsonliu/dsh-file-explorer
cd dsh-file-explorer
npm install && npm run build
dsh plugin --profile web add .
For local development, this repo's devDependencies resolves @dsh-external/dsh-file-explorer's ./client type definitions. Point it at your checkout or your registry's published package before npm install.
For files ≤ 2 MiB the plugin parses the text preview content directly. For larger text files (text-large since v0.3.0) and .bcif, the plugin uses readRawFile to fetch raw bytes — a standard part of the FileExplorerService contract since dsh-file-explorer v0.1.0. Since dsh-file-explorer v0.7.0 the plugin passes an AbortSignal so the in-flight read is aborted when you switch files or close the preview.
On dsh-file-explorer v0.9.0+ the plugin registers one named viewer via registerViewer — id: 'molstar', label Mol* Structure — across every supported extension, so the Open with… menu and the preview-panel viewer switcher show a proper name instead of the generic "Extension viewer". On older cores (pre-v0.9.0) it falls back to one registerPreview per extension.
Limitations
- Requires a WebGL-capable browser.
- Read-only preview (no editing).
- Trajectories and density maps (
.dcd, .nc, .map) are out of scope.
Development
npm run check # tsc type check
npm test # vitest unit tests
npm run build # tsc + tsdown (single-file lib/client.js bundling molstar)
The real WebGL mount cannot run under jsdom; verify it with dsh web and a structure file in examples/.
After npm run build, hard-refresh the browser (Ctrl/Cmd+Shift+R): dsh web may keep serving a cached plugin bundle, so a soft reload can leave your latest build unused.
Acknowledgments
This plugin is built on Mol* (/ˈmol-star/), a next-generation technology stack for (not only) macromolecular structure data, jointly initiated by PDBe and RCSB PDB.
When using Mol*, please cite:
David Sehnal, Sebastian Bittrich, Mandar Deshpande, Radka Svobodová, Karel Berka, Václav Bazgier, Sameer Velankar, Stephen K Burley, Jaroslav Koča, Alexander S Rose: Mol* Viewer: modern web app for 3D visualization and analysis of large biomolecular structures, Nucleic Acids Research, 2021; https://doi.org/10.1093/nar/gkab314.
License
MIT
