Documentation

Everything in PDV

Protein Design Viz is a single-file, offline molecular visualization studio that runs entirely in your browser. This guide walks through every feature, from loading structures to publication-ready renders.

1Overview

PDV opens straight in a browser tab, nothing to install, no account, no upload. Your structures never leave your machine.

PDV is built as an extensive modification of 3Dmol.js, the open-source WebGL molecular rendering library, which powers the underlying 3D view. If you use PDV in published work, please also cite 3Dmol.js: Nicholas Rego & David Koes, “3Dmol.js: molecular visualization with WebGL,” Bioinformatics 31(8):1322–1324 (2015). 3Dmol.js is distributed under the BSD-3-Clause license.

Single file, offline

The whole studio is one self-contained HTML file. Double-click it; it works on a plane.

Private by design

Everything runs locally in WebGL. Files you load are never sent to a server.

Refined visuals

Full-bleed canvas, frosted-glass panels, cinematic backdrops, and crisp outline rendering.

Quantitative

Distance measurement, plus engines validated against the reference tools: SASA vs FreeSASA (r ≈ 0.997), antibody numbering vs RIOT, non-covalent contacts vs PLIP and Arpeggio, and liabilities from LAP.

2Quick start

Three ways to get a structure on screen.

  • Fetch a PDB ID: type a 4-character code (e.g. 1AHW) into the top bar and hit Fetch. PDV downloads it from the RCSB.
  • Open a file: click Open and pick one or more local files. Supported: .pdb, .cif, .ent, .mol2, .sdf, .xyz.
  • Drag & drop: drop structure files straight onto the canvas.
Selecting several files at once loads them all as separate objects, no need to add them one by one.

Once a structure is on screen, the whole studio comes down to six regions. Step through them below, the highlight follows along.

The PDV workspace, a quick tour
The PDV workspace with all panels visible
1/6

3Loading & objects

Every structure you load becomes an object in the right-hand Objects & Selections panel. PDV is fully multi-object.

  • Additive loading: opening another file or fetching another ID adds a new object; it never replaces what's already there.
  • Automatic copy naming: load the same structure twice and the second becomes name_1, the third name_2, and so on.
  • Per-object controls: each row has an eye (show/hide), a color swatch, an editable name, a chain/atom count, zoom-to, and remove (✕).
  • Active object: click an object row to target it; the left panel then edits that object.

Here's the whole loading flow, start to finish:

Loading a structure, step by step
Loading 1EVE into the PDV workspace
1/5

4Selections

Classic named selections. The left panel (representation, coloring, style) acts on the active selection if there is one, otherwise on the active object.

  • Pick residues: click residues in the 3D view or the sequence track. ⇧-drag for a range, ⌘/Ctrl-click to toggle individual residues.
  • Named selections: each selection has its own color, representation, and style, layered on top of the object. Rename, recolor, hide, zoom, or delete from the panel.
  • Quick selections: every chain of every object is listed (grouped under its object) as a one-click "add chain as a new selection" button.
  • Editing scope: while a selection is active a small name × badge appears on the Representation/Coloring/Style headers; click the × to switch back to the whole object.
Selections overlay on the base structure, e.g. keep the whole protein as cartoon and show a binding loop as ball-and-stick on top.

The right-hand panel stacks three sections, and Focus brings a pick to the foreground:

Objects, selections & focus
The Objects & Selections panel
1/4

5Representations

Seven representations, set per object or per selection from the Representation grid.

CartoonStickSphere Ball & StickLineSurfaceHide
  • Overlays preserve the base: applying a representation to a selection draws it on top of the object's representation rather than replacing it.
  • Hide: removes the selected residues from view (so you can carve regions out of a surface or cartoon).
  • Surface respects every coloring scheme, including per-residue ones.

Step through the seven, each on the same structure:

Representation styles, same structure, seven looks
Structure rendered in each representation style
1/7

6Coloring

A full palette of coloring schemes, each applied to the active object or selection and mirrored onto the sequence track.

SchemeWhat it shows
SpectrumRainbow along the residue chain (N→C), works in every representation.
ChainOne color per chain.
Secondary structureHelix / sheet / loop.
Element (CPK)By atom element.
B-factorBlue→white→red over the temperature factor.
HydrophobicityKyte–Doolittle scale per residue.
ChargePositive (blue) / negative (red) / neutral.
By residue…Residue-type categories, or MSA palettes (Clustal, Zappo, Taylor), or a custom per-residue editor.
Solid color…A single chosen color via the picker.
SASA accessibilitySolvent exposure (see Surface accessibility).

Clicking Solid color…, By residue…, or an object/selection color swatch opens a floating color picker with a curated palette plus a custom color input. Hydrophobicity can use any of several published scales, selectable from Advanced tools → Hydrophobicity scales.

Four published scales, spanning the main experimental strategies. Kyte–Doolittle hydropathy, the Eisenberg normalized consensus (ExPASy ProtScale normalization), Fauchère–Pliska octanol–water partition (the basis of the molecular lipophilicity potential), and Wimley–White whole-residue octanol. All are oriented so that higher = more hydrophobic, and PDV's profiles use relative values (rankings and windowed moments), which are insensitive to the sign and offset conventions that differ between sources.
Kyte–Doolittle: Kyte J, Doolittle RF. J. Mol. Biol. 157(1):105–132 (1982). doi.org/10.1016/0022-2836(82)90515-0Eisenberg consensus: Eisenberg D, Schwarz E, Komaromy M, Wall R. J. Mol. Biol. 179(1):125–142 (1984). doi.org/10.1016/0022-2836(84)90309-7 · normalization via ExPASy ProtScale: Gasteiger E, et al. (2005), web.expasy.org/protscaleFauchère–Pliska: Fauchère J-L, Pliska V. Eur. J. Med. Chem. 18(4):369–375 (1983).Wimley–White: Wimley WC, Creamer TP, White SH. Biochemistry 35(16):5109–5124 (1996). doi.org/10.1021/bi9600153 · White SH, Wimley WC. Annu. Rev. Biophys. Biomol. Struct. 28:319–365 (1999). doi.org/10.1146/annurev.biophys.28.1.319
Coloring schemes, same structure, every palette
Structure shown under each coloring scheme
1/10

7Style controls

Fine-tune geometry and display. Like representation and coloring, these target the active selection if one is active, otherwise the active object.

  • Sliders: cartoon thickness, stick radius, sphere size, surface opacity, and label size.
  • Hydrogens: show or hide hydrogen atoms (rendered visibly even over cartoon).
  • Residue labels: clean, frosted labels that scale with the label-size slider and high-resolution export.
  • Spin and Depth fog: scene-wide display toggles.

8Sequence viewer

A continuous sequence track docked at the bottom, fully linked to the 3D scene.

  • One continuous ribbon: all objects and chains laid out left-to-right, each prefixed by its object name and chain badge.
  • Mirrors the coloring: every cell carries the same color scheme as the structure, including SASA.
  • Minimap: a full-width overview with selection bands and a draggable viewport indicator.
  • Navigation: chain chips (tagged by object when several are loaded) jump the track to that chain or structure.
  • Two-way linking: hover a residue to highlight it in 3D and vice-versa; click to select; chain badges add a whole chain to the active selection.
Bottom sequence track with chain badges and minimap
Add screenshot · docs_assets/sequence.jpg
The bottom sequence dock with object/chain badges and the minimap
Figure 3. The sequence track stays in lock-step with the 3D scene, colors, selections, and hover.

9Backdrops & view

  • Backdrops: six cinematic presets (Aurora, Daylight, Mint mist, Blush, Twilight, Carbon) plus a custom-color chip. The backdrop is baked into exports.
  • Full screen: the expand button (top-right) toggles full-screen mode.
  • Panel toggles: collapse the left controls or right inspector to maximize the canvas; show/hide the sequence track.
Aurora Daylight Mint mist Blush Twilight Carbon

10Measuring distance

The Distance button (top bar) opens the measurement wizard.

  • Between residues: pick two residues; measure either Cα–Cα or the closest heavy-atom pair (PDV finds it for you). Residues can be picked in 3D or the sequence.
  • Between atoms: pick two individual atoms in 3D; pick targets tighten so you hit exactly the atom under the cursor.

Each measurement draws an orange dashed connector with endpoint halos and an Ångström label, and is listed in the panel where you can remove them individually or clear all.

Residue–residue distance

Between residues, pick two, read off the distance
Measuring a residue-to-residue distance
1/4

Atom–atom distance

Between atoms, pick two atoms in ball-and-stick
Measuring an atom-to-atom distance
1/4

11Contacts & non-covalent interactions

The Distance menu offers two distinct tools for mapping how two parts of a structure touch. They are easy to confuse, so the difference matters: Contacts is a pure distance search, while Non-covalent contacts classifies each contact by physical interaction type. Both run between any two groups of chains or selections.

Contacts, by distance

The simpler tool: a purely geometric proximity search, with no chemistry or interaction typing. Pick two groups, a distance basis and a cut-off, and PDV lists every residue pair within that distance, labelled with its actual separation. Use it when you just want "what is near what."

  • Assign groups: define Group A and Group B (chains or selections).
  • Distance basis & threshold: the closest heavy-atom pair or Cα–Cα, within a chosen cut-off (default 5 Å).
  • Contact map: a Sankey linking the interacting residues across the two groups, labelled with each pair's distance; the residues are saved as Contacts A / Contacts B selections and exported to CSV.
Detect contacts, group A vs group B, mapped and saved
Detecting contacts between two groups
1/4

Non-covalent contacts, by interaction type

The richer tool. Rather than a single distance cut-off, each contact is classified into a physical interaction type using PLIP-style geometric rules, and the contact map is colored by type rather than distance. Use it when you care how two residues interact, not just that they are close.

  • Interaction types (van der Waals, hydrogen bonds, salt bridges, hydrophobic contacts, weak C–H···O hydrogen bonds, halogen bonds, metal coordination, water bridges, and disulfides) each from its own geometric rule (Salentin et al., 2015).
  • Typed contact map: the same group-A / group-B Sankey, but grouping residue pairs by interaction category instead of distance.
Buyer beware, the interaction types are annotations, not ground truth. Unlike the distance Contacts above (which are exact), the typed interactions are inferred geometrically in pure JavaScript with no cheminformatics back-end (no RDKit or OpenBabel): donor/acceptor and charge assignment come from element identity, residue templates, and approximate hydrogen placement, and the π/aromatic family is out of scope. Treat the typing as a fast guide, not a definitive assignment, especially for small-molecule ligands, where even the established tools diverge sharply.
Benchmarked against PLIP and Arpeggio. Across ~2,500 protein, antibody, nanobody, ligand and nucleic-acid complexes, PDV reproduces PLIP at macro-F1 0.82 (hydrophobic 0.93, hydrogen bonds 0.81, salt bridges 0.89) and tracks Arpeggio about as closely as PLIP itself does. The key context: PLIP and Arpeggio (both mature, OpenBabel-backed tools) agree with each other only at F1 0.61–0.69 overall, and as low as 0.12–0.27 on small-molecule ligands. That inter-tool spread is the realistic ceiling, and PDV sits inside it for protein and protein–protein interfaces.
PLIP: Salentin S, Schreiber S, Haupt VJ, Adasme MF, Schroeder M. PLIP: fully automated protein–ligand interaction profiler. Nucleic Acids Research 43(W1):W443–W447 (2015). doi.org/10.1093/nar/gkv315Arpeggio: Jubb HC, Higueruelo AP, Ochoa-Montaño B, Pitt WR, Ascher DB, Blundell TL. Arpeggio: a web server for calculating and visualising interatomic interactions in protein structures. Journal of Molecular Biology 429(3):365–371 (2017). doi.org/10.1016/j.jmb.2016.12.004
Non-covalent contacts Sankey colored by interaction type
Add screenshot · docs_assets/contacts.jpg
The non-covalent contact map, colored by interaction type
Figure 5. Non-covalent contacts, the Sankey colored by interaction type (hydrogen bonds, salt bridges, hydrophobic, …), not by distance.

12Structural alignment

The Structural alignment button superposes one loaded object onto another so you can compare conformations or models.

  • Align using: a structural superposition (Kabsch quaternion least-squares) or a sequence alignment to define the correspondence.
  • RMSD: the root-mean-square deviation of the fit is reported.
Structural alignment, superpose one structure onto another
Structural alignment workflow
1/3

13Surface accessibility (SASA)

A built-in Shrake–Rupley solvent-accessible surface area engine, running in a Web Worker so the UI stays smooth.

  • Pick "SASA accessibility" in the Coloring palette to open the SASA panel.
  • Controls: probe radius and sampling density (points), plus a holo / apo context toggle.
  • Holo computes accessibility within the whole structure; apo computes the active selection in isolation, the difference reveals the binding interface.
  • Readouts: total/hydrophobic area, buried/partial/exposed counts, a per-residue bar chart, and a one-click CSV export. The structure and sequence color blue→white→red by relative exposure.
Validated against FreeSASA. The exact in-browser Shrake–Rupley worker was run under Node.js across 1,507 structures and more than 0.6 million residues (antibody, nanobody, hetero-complex and monomer sets). Per-residue absolute SASA correlates with FreeSASA at Pearson r ≈ 0.997–0.998 in both holo and apo states, with only a small constant offset attributable to the van der Waals radius set (Bondi vs ProtOr); three-state buried / partial / exposed labels agree for ~89–91% of residues; and the apo–holo interface annotation (ignoring partner chains) is reproduced at F1 ≳ 0.96, MCC ≳ 0.95. We treat PDV's SASA values as interchangeable with FreeSASA.
FreeSASA: Mitternacht S. FreeSASA: an open source C library for solvent accessible surface area calculations. F1000Research 5:189 (2016). doi.org/10.12688/f1000research.7931.1Shrake–Rupley algorithm: Shrake A, Rupley JA. Environment and exposure to solvent of protein atoms. Lysozyme and insulin. J. Mol. Biol. 79(2):351–371 (1973). doi.org/10.1016/0022-2836(73)90011-9Relative-SASA normalization: Tien MZ, Meyer AG, Sydykova DK, Spielman SJ, Wilke CO. Maximum allowed solvent accessibilities of residues in proteins. PLOS ONE 8(11):e80635 (2013). doi.org/10.1371/journal.pone.0080635
SASA panel with stats, per-residue chart and blue-white-red surface
Add screenshot · docs_assets/sasa.jpg
The SASA panel (probe, holo/apo, stats, chart) with the colored surface
Figure 6. Surface accessibility, exposure colored blue→white→red, with the analysis panel.

14Antibody numbering

From Advanced tools → Numbering, PDV runs NaturalAntibody's RIOT engine to recognise antibody chains, apply a numbering scheme, delineate the CDRs, and assign germline genes, entirely in the browser.

  • Schemes: IMGT, Kabat, Chothia, Martin (enhanced Chothia / AbM), and aHo.
  • CDR delineation: CDR-H1/H2/H3 and CDR-L1/L2/L3 are detected per scheme; non-antibody chains are flagged as not an antibody.
  • Germline assignment: the closest germline V (and J) genes are chosen by best local alignment.
  • Two sequence views: numbered (scheme residue numbers, with insertion codes) and annotated (coloured by region: CDR, germline-identical, buried, outside-CDR).
  • Report: a modal summarises the scheme, CDRs, and germline calls per chain.
Numbering powers the rest of the antibody analytics, CDR/germline context feeds the liability scoring below.
Benchmarked against RIOT. PDV's numbering draws on the RIOT algorithm, and we validated our independent implementation against the published RIOT reference across 16,996 sequences and all four schemes (more than 1.3 million residue positions). PDV makes the identical antibody / non-antibody call on 100% of sequences, agrees on chain locus and class for 100% and on germline V/J gene for >97% of antibody chains, and its residue numbering agrees with RIOT for ~98–99% of chains and >99.88% of all positions, including insertion codes and CDR boundaries. The residual differences trace to germline tie-breaks on heavily mutated sequences, not to the numbering itself.
RIOT: Dudzic P, Janusz B, Satława T, et al. RIOT, Rapid Immunoglobulin Overview Tool. Briefings in Bioinformatics 26(1):bbae632 (2024). doi.org/10.1093/bib/bbae632 · github.com/NaturalAntibody/riot_na
Antibody numbering, detect, mark, and read off the CDRs
Antibody numbering workflow
1/4

15Developability liabilities

Advanced tools → Liabilities scans for common antibody developability motifs and ranks them by how genuinely risky they are in this structure.

  • Motifs detected: Asn deamidation, Asp isomerization, N-glycosylation sequons, Met and Trp oxidation, metal-catalysed His oxidation, fragmentation / cleavage sites, and unpaired / missing cysteines.
  • Context-weighted: each hit is scored by structural context: solvent exposure, proximity to the CDRs, and whether it is germline-encoded. An exposed, CDR-proximal, non-germline motif is flagged as genuinely risky; a buried or germline one is down-weighted.
  • Linked highlighting: liabilities are marked on both the structure and the sequence track.
Built on LAP. PDV's liability motif catalogue and its context flags (germline, therapeutic-prevalence, and surface exposure) follow NaturalAntibody's Liability Antibody Profiler (LAP), which curated ~70 severity-graded motifs and showed these flags mark roughly 60% of raw motif hits as low-risk, benchmarked against experimental deamidation, isomerization, and oxidation datasets. Treat raw motif counts as over-predictive; the flags are what make them actionable.
LAP: Satława T, Tarkowski M, Wróbel S, et al. LAP: Liability Antibody Profiler by sequence & structural mapping of natural and therapeutic antibodies. PLOS Computational Biology 20(3):e1011881 (2024). doi.org/10.1371/journal.pcbi.1011881 · lap.naturalantibody.com
Developability liabilities, scan, rank, and map the risky sites
Developability liabilities workflow
1/4

16Rendering & export

The Render/Export button produces publication-quality PNGs with several render modes.

ModeLook
No outlinePlain shaded render.
Outline · defaultClean dark contour around the molecule.
CartoonBold thick ink outline.
Line artOutline-only line drawing on a white background.
Cel shadeQuantized colors + outline (mode 3).
  • Outline color: sets the contour color; pick black, ink, magenta, blue, teal, or a custom color.
  • Output quality: 1×, 2×, or 4× supersampling (auto-capped to your GPU's limit); labels scale so they stay readable.

The same view (1DGX), exported in each mode:

Render & export, one view, five looks
Exported render of 1DGX in each mode
1/5

17Sessions

The Save session button writes the entire scene to a portable .mvsession file.

  • What's saved: every loaded object, its representation, coloring and style, all named selections, and the camera view.
  • Portable: reopen the session later to restore the scene exactly, or hand the file to a colleague alongside the single-file app.

18Keyboard shortcuts

Available when the cursor isn't in a text field.

KeyAction
CCartoon representation
SStick representation
BSphere representation
LLine representation
FSurface representation
RReset / recenter the view
MOpen the Distance (measure) wizard
EscStop measuring · close popovers

Mouse: drag to rotate, scroll to zoom, right-drag (or two-finger) to pan, double-click a residue to zoom to it, right-click an atom for the context menu.

19Privacy & offline

PDV is a single HTML file. Apart from optionally fetching a structure from the RCSB when you type a PDB ID, nothing leaves your computer, files you open are parsed and rendered locally in WebGL. Save the file anywhere and it keeps working with no internet connection.

Ready to visualize?

Open the studio in a new tab and load your first structure.

Open PDV Back to home