molview-spec

Molecular views and stories

Use the advertised ebi-pdbe-build_mvs tool for custom single scenes and ebi-pdbe-build_mvs_story for a guided story. Use their advertised legacy aliases only on servers that expose those names. Ordinary structure exploration uses ebi-pdbe-open_structure; aligned comparison uses ebi-pdbe-compare_structures. For any initial request to open, view, inspect, or show a structure or PDB entry—including a request that only supplies an entry ID—call ebi-pdbe-open_structure. Never call ebi-pdbe-load_structure_annotations for a user request: it is an App-only helper for loading optional annotations into a workspace that is already open and does not create a scene. A successful explorer result (status: "prepared") completes that viewing request. Stop calling visualization tools; do not repeatedly reopen the entry or switch to another viewer tool to wait for browser rendering.

The App displays supplied scientific data. Preserve PDBe/SIFTS residue correspondence and supplied alignment transforms. Do not calculate RMSD, per-residue displacement, distance-cutoff ligand neighbourhoods or inferred binding sites. Highlight binding-site residues only from explicit source annotations with provenance; if absent, report the annotation as unavailable. Coordinate loading and camera navigation do not establish new scientific results.

Ground biological claims, residue mappings, ligand instances and scene choices in PDBe evidence. Read scene guidance when building or modifying a scene, and story guidance for a tour or story. The tool schemas are authoritative; full schema resources are available at scene schema and story schema when exact field details are needed. Read the builder API reference for transforms, instances, additional structures, primitives, annotation tables and serialized MolQL. The same operations work inside each story scene.

On servers advertising ebi-pdbe-update_workspace, recover the latest complete workspace for the exact target viewer from App context or structured tool output. For follow-up changes, call that tool with the workspace, its revision as expected_revision, and a suitable operation batch. Preserve unrelated layers, structures, source annotations and transforms. Upserts replace complete named definitions. Use only component/annotation layers with explicit data selections; calculated binding_site layers and cutoff fields are unsupported. Use the source PDBe/SIFTS residue correspondence table and export without adding geometric measurements. A shared resource URI alone does not route results to an existing viewer: the host must match the target workspace ID.

On older servers without workspace updates, recover the complete builder and use the established full-replacement builder workflow. Do not pass host routing fields such as pdbe_visualization_request.mode to PDBe tools. If the requested viewer state is unavailable, recover it before constructing the edit.