py2Dmol, embedded

The div is yours, the canvas inside it is the library's. PDB or mmCIF, told apart by looking at the text, so you do not have to say which you have.

The frame around the canvas is on by default. box: false takes it off.

Getting the text. show takes a string, so it is yours to fetch, read from a file input, or write into the page. For the two public archives there is a helper that knows the URLs:

const text = await py2Dmol.fetch('1UBQ');    // four characters: the PDB
const text = await py2Dmol.fetch('P01308');  // anything else: AlphaFold
py2Dmol.show('mol', text);

It is separate from show and hands back text rather than a viewer, so a download that fails — offline, a wrong id, a slow server — is yours to catch, and show stays something that either works or throws immediately.

Biological assemblies are built by default. A crystal structure file holds the asymmetric unit, which for anything symmetric is a fraction of the real molecule — one protomer of a trimer, a sixtieth of a capsid — along with the operations that make the rest. Those are applied unless you say otherwise:

py2Dmol.show('mol', text, { biounit: false });   // the deposited coordinates

A file with no assembly records is drawn exactly as it is, which is most files, so the default costs a search that finds nothing.

Pass it to show as style, or change it later with setStyle. Both take the same four names.

3d comes up on a black page, since solid shaded geometry is meant to be seen on one. bg: 'white' overrides that.

auto · chain · rainbow · plddt · deepmind · ss. A name it does not know throws, rather than leaving the picture unchanged and letting you wonder.

plddt reads the B-factor column, which in a crystal structure is a real B-factor rather than a confidence.

This is the selector, and everything else on the page takes the same one. A bare string is a chain, {range} is half open, and {residues} is the numbering in the file.

Colours accumulate: a range and then a chain leaves both in place. To start again, set a mode.

select adds, unselect takes away, and unselect() with nothing to take away clears.

Clicking the canvas selects too: a click takes a residue, shift-click adds another, double-click takes the whole chain, and a click on the background clears. select: false turns that off for a viewer meant only to be looked at.

hide takes residues off, show puts them back, and resetVisibility() returns to everything. To draw one thing and nothing else, reset first and hide the rest: v.resetVisibility(); v.hide({not: sel});

What is hidden is hidden to everything else too: it cannot be clicked, and it does not pull the camera when you orient.

{type} is what a position is: 'L' ligand, 'P' protein, 'N' nucleic. You do not need to know what the ligand is called.

{near} is everything within 5 Å of another selector, measured atom to atom. That is a contact shell — a hydrogen bond is under 3.5 and a salt bridge under 4. {angstroms} changes it.

The ligand is part of site, since it is within 5 Å of itself. {not: {type: 'L'}} would leave it out.

hideSidechains takes them away again.

They arrive coloured by element — carbon in the residue's own colour, oxygen red, nitrogen blue — and so does a ligand. That is on by default, since those are the atoms with an element worth reading; v.hideElements(sel) turns it off for a flat colour, and v.showElements(sel) puts it back.

This needs a structure that carries side-chain atoms — a C-alpha trace has none, and asking for them throws rather than quietly doing nothing. The file here keeps every C-alpha, and all the atoms of the residues nearest the ligand.

With no selector it frames the selection, or everything visible if nothing is selected.

{animate: false} jumps instead of flying. On load it never animates, and orient: false keeps the file's own orientation for a structure that already sits the way you want it.

The slab is as thick as the selection is deep, and refits as you turn, so it stays over the site rather than at a fixed depth. Drag it and watch.

To cut deeper, clip to less: v.clip({type: 'L'}) keeps a thinner slice than v.clip(site). There is no separate thickness setting — the selector is it.

v.clip() with no selector turns it off.

A file with more than one model gets a player; a single structure stays a bare canvas. play: false refuses it, play: true insists.

The player is the library's: play, a slider, a counter and a speed control. You can also step frames from code with v.setFrame(i).

Bases are drawn as plates on the backbone. Nothing asks for that either — a structure holding protein and nucleic is drawn as both.

Within one structure an end is either a position or a chain and residue number: [5, 60, 1.0] or ['A', 12, 'B', 34, 1.0].

An empty list clears them. Contacts belong to the structure, so loading over it replaces them.

Names are yours to choose. They are deliberately not A and B here, which is what the chains inside a structure are called.

The camera widens to take in a structure it has not framed before. Hiding one and showing it again leaves the camera where it is.

A contact can join two different structures. Each end names its own, and the contact belongs to the viewer rather than to either one, so you pass no name.

The canvas is looked up inside its own container, so the containers are what must be distinct. Everything the library creates inside them is scoped and may repeat.

The two viewers are independent: a selection, a style or a camera in one does not touch the other.

Style, Capture and every slider, plus Orient and Rotate. Off by default: most embeds want a picture and nothing else.

Its styling is scoped to your container, so it cannot reach your page's own dropdowns or buttons.

It stays inside the box you give it. On a fixed height the panel scrolls; in a container too narrow for the panel beside the canvas, it wraps underneath.