2.2.0

- update "forceDraw" logic
- Ensure the scene is re-rendered when viewport size changes
- Support noDraw mode in PluginAnimationLoop

.gitignore

@@ -9,3 +9,5 @@ tsconfig.commonjs.tsbuildinfo
 
 *.sublime-workspace
 .idea
+
+.DS_Store

CHANGELOG.md

@@ -6,13 +6,24 @@ Note that since we don't clearly distinguish between a public and private interf
 
 ## [Unreleased]
 
+
+## [v2.2.0] - 2021-07-31
+
 - Add `tubularHelices` parameter to Cartoon representation
 - Add `SdfFormat` and update SDF parser to be able to parse data headers according to spec (hopefully :)) #230
 - Fix mononucleotides detected as polymer components (#229)
 - Set default outline scale back to 1
-- Improved DCD reader cell angle handling (intepret near 0 angles as 90 deg)
+- Improved DCD reader cell angle handling (interpret near 0 angles as 90 deg)
 - Handle more residue/atom names commonly used in force-fields
 - Add USDZ support to ``geo-export`` extension.
+- Fix `includeParent` support for multi-instance bond visuals.
+- Add `operator` Loci granularity, selecting everything with the same operator name.
+- Prefer ``_label_seq_id`` fields in secondary structure assignment.
+- Support new EMDB API (https://www.ebi.ac.uk/emdb/api/entry/map/[EMBD-ID]) for EM volume contour levels.
+- ``Canvas3D`` tweaks:
+    - Update ``forceDraw`` logic.
+    - Ensure the scene is re-rendered when viewport size changes.
+    - Support ``noDraw`` mode in ``PluginAnimationLoop``.
 
 ## [v2.1.0] - 2021-07-05
 

package-lock.json

@@ -1,11 +1,11 @@
 {
   "name": "molstar",
-  "version": "2.2.0-dev.1",
+  "version": "2.2.0",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
-      "version": "2.0.7",
+      "version": "2.2.0",
       "license": "MIT",
       "dependencies": {
         "@types/argparse": "^1.0.38",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "molstar",
-  "version": "2.2.0-dev.1",
+  "version": "2.2.0",
   "description": "A comprehensive macromolecular library.",
   "homepage": "https://github.com/molstar/molstar#readme",
   "repository": {

src/extensions/dnatco/confal-pyramids/representation.ts

@@ -20,10 +20,10 @@ import { Structure, StructureProperties, Unit } from '../../../mol-model/structu
 import { CustomProperty } from '../../../mol-model-props/common/custom-property';
 import { Representation, RepresentationContext, RepresentationParamsGetter } from '../../../mol-repr/representation';
 import { StructureRepresentation, StructureRepresentationProvider, StructureRepresentationStateBuilder, UnitsRepresentation } from '../../../mol-repr/structure/representation';
-import { StructureGroup, UnitsMeshParams, UnitsMeshVisual, UnitsVisual } from '../../../mol-repr/structure/units-visual';
+import { UnitsMeshParams, UnitsMeshVisual, UnitsVisual } from '../../../mol-repr/structure/units-visual';
 import { VisualUpdateState } from '../../../mol-repr/util';
 import { VisualContext } from '../../../mol-repr/visual';
-import { getAltResidueLociFromId } from '../../../mol-repr/structure/visual/util/common';
+import { getAltResidueLociFromId, StructureGroup } from '../../../mol-repr/structure/visual/util/common';
 import { ParamDefinition as PD } from '../../../mol-util/param-definition';
 import { Theme, ThemeRegistryContext } from '../../../mol-theme/theme';
 import { NullLocation } from '../../../mol-model/location';

src/extensions/rcsb/validation-report/representation.ts

@@ -16,7 +16,7 @@ import { RepresentationContext, RepresentationParamsGetter, Representation } fro
 import { UnitsRepresentation, StructureRepresentation, StructureRepresentationStateBuilder, StructureRepresentationProvider, ComplexRepresentation } from '../../../mol-repr/structure/representation';
 import { VisualContext } from '../../../mol-repr/visual';
 import { createLinkCylinderMesh, LinkCylinderParams, LinkStyle } from '../../../mol-repr/structure/visual/util/link';
-import { UnitsMeshParams, UnitsVisual, UnitsMeshVisual, StructureGroup } from '../../../mol-repr/structure/units-visual';
+import { UnitsMeshParams, UnitsVisual, UnitsMeshVisual } from '../../../mol-repr/structure/units-visual';
 import { VisualUpdateState } from '../../../mol-repr/util';
 import { LocationIterator } from '../../../mol-geo/util/location-iterator';
 import { ClashesProvider, IntraUnitClashes, InterUnitClashes, ValidationReport } from './prop';
@@ -28,6 +28,7 @@ import { CentroidHelper } from '../../../mol-math/geometry/centroid-helper';
 import { Sphere3D } from '../../../mol-math/geometry';
 import { bondLabel } from '../../../mol-theme/label';
 import { getUnitKindsParam } from '../../../mol-repr/structure/params';
+import { StructureGroup } from '../../../mol-repr/structure/visual/util/common';
 
 //
 

src/mol-canvas3d/canvas3d.ts

@@ -222,9 +222,11 @@ interface Canvas3D {
     animate(): void
     /**
      * Pause animation loop and optionally any rendering
-     * @param noDraw pause any rendering
+     * @param noDraw pause any rendering (drawPaused = true)
      */
     pause(noDraw?: boolean): void
+    /** Sets drawPaused = false without starting the built in animation loop */
+    resume(): void
     identify(x: number, y: number): PickData | undefined
     mark(loci: Representation.Loci, action: MarkerAction): void
     getLoci(pickingId: PickingId | undefined): Representation.Loci
@@ -305,7 +307,6 @@ namespace Canvas3D {
         const interactionHelper = new Canvas3dInteractionHelper(identify, getLoci, input, camera);
         const multiSampleHelper = new MultiSampleHelper(passes.multiSample);
 
-        let drawPending = false;
         let cameraResetRequested = false;
         let nextCameraResetDuration: number | undefined = void 0;
         let nextCameraResetSnapshot: Camera.SnapshotProvider | undefined = void 0;
@@ -373,9 +374,13 @@ namespace Canvas3D {
             let didRender = false;
             controls.update(currentTime);
             const cameraChanged = camera.update();
-            const multiSampleChanged = multiSampleHelper.update(force || cameraChanged, p.multiSample);
 
-            if (resized || force || cameraChanged || multiSampleChanged) {
+            const shouldRender = force || cameraChanged || resized || forceNextRender;
+            forceNextRender = false;
+
+            const multiSampleChanged = multiSampleHelper.update(shouldRender, p.multiSample);
+
+            if (shouldRender || multiSampleChanged) {
                 let cam: Camera | StereoCamera = camera;
                 if (p.camera.stereo.name === 'on') {
                     stereoCamera.update();
@@ -394,24 +399,20 @@ namespace Canvas3D {
             return didRender;
         }
 
-        let forceNextDraw = false;
+        let forceNextRender = false;
         let forceDrawAfterAllCommited = false;
         let currentTime = 0;
         let drawPaused = false;
 
         function draw(force?: boolean) {
             if (drawPaused) return;
-            if (render(!!force || forceNextDraw) && notifyDidDraw) {
+            if (render(!!force) && notifyDidDraw) {
                 didDraw.next(now() - startTime as now.Timestamp);
             }
-            forceNextDraw = false;
-            drawPending = false;
         }
 
         function requestDraw(force?: boolean) {
-            if (drawPending) return;
-            drawPending = true;
-            forceNextDraw = !!force;
+            forceNextRender = forceNextRender || !!force;
         }
 
         let animationFrameHandle = 0;
@@ -703,6 +704,7 @@ namespace Canvas3D {
             animate,
             resetTime,
             pause,
+            resume: () => { drawPaused = false; },
             identify,
             mark,
             getLoci,
@@ -816,6 +818,8 @@ namespace Canvas3D {
         };
 
         function updateViewport() {
+            const oldX = x, oldY = y, oldWidth = width, oldHeight = height;
+
             if (p.viewport.name === 'canvas') {
                 x = 0;
                 y = 0;
@@ -836,6 +840,9 @@ namespace Canvas3D {
                 // console.log({ x, y, width, height });
             }
 
+            if (oldX !== x || oldY !== y || oldWidth !== width || oldHeight !== height) {
+                forceNextRender = true;
+            }
         }
 
         function syncViewport() {

src/mol-geo/geometry/mesh/mesh.ts

@@ -387,9 +387,6 @@ export namespace Mesh {
 
     function createValues(mesh: Mesh, transform: TransformData, locationIt: LocationIterator, theme: Theme, props: PD.Values<Params>): MeshValues {
         const { instanceCount, groupCount } = locationIt;
-        if (instanceCount !== transform.instanceCount.ref.value) {
-            throw new Error('instanceCount values in TransformData and LocationIterator differ');
-        }
         const positionIt = createPositionIterator(mesh, transform);
 
         const color = createColors(locationIt, positionIt, theme.color);

src/mol-geo/geometry/spheres/spheres.ts

@@ -163,9 +163,6 @@ export namespace Spheres {
 
     function createValues(spheres: Spheres, transform: TransformData, locationIt: LocationIterator, theme: Theme, props: PD.Values<Params>): SpheresValues {
         const { instanceCount, groupCount } = locationIt;
-        if (instanceCount !== transform.instanceCount.ref.value) {
-            throw new Error('instanceCount values in TransformData and LocationIterator differ');
-        }
         const positionIt = createPositionIterator(spheres, transform);
 
         const color = createColors(locationIt, positionIt, theme.color);

src/mol-geo/geometry/text/text.ts

@@ -206,9 +206,6 @@ export namespace Text {
 
     function createValues(text: Text, transform: TransformData, locationIt: LocationIterator, theme: Theme, props: PD.Values<Params>): TextValues {
         const { instanceCount, groupCount } = locationIt;
-        if (instanceCount !== transform.instanceCount.ref.value) {
-            throw new Error('instanceCount values in TransformData and LocationIterator differ');
-        }
         const positionIt = createPositionIterator(text, transform);
 
         const color = createColors(locationIt, positionIt, theme.color);

src/mol-model-formats/structure/property/secondary-structure.ts

@@ -19,6 +19,7 @@ export { ModelSecondaryStructure };
 
 type StructConf = Table<mmCIF_Schema['struct_conf']>
 type StructSheetRange = Table<mmCIF_Schema['struct_sheet_range']>
+type CoordinateType = 'label' | 'auth';
 
 namespace ModelSecondaryStructure {
     export const Descriptor: CustomPropertyDescriptor = {
@@ -30,9 +31,12 @@ namespace ModelSecondaryStructure {
     export function fromStruct(conf: StructConf, sheetRange: StructSheetRange, hierarchy: AtomicHierarchy): SecondaryStructure {
         const map: SecondaryStructureMap = new Map();
         const elements: SecondaryStructure.Element[] = [{ kind: 'none' }];
-        addHelices(conf, map, elements);
+
+        const coordinates = getCoordinateType(conf, sheetRange);
+
+        addHelices(conf, coordinates, map, elements);
         // must add Helices 1st because of 'key' value assignment.
-        addSheets(sheetRange, map, conf._rowCount, elements);
+        addSheets(sheetRange, coordinates, map, conf._rowCount, elements);
 
         const n = hierarchy.residues._rowCount;
         const getIndex = (rI: ResidueIndex) => rI;
@@ -43,15 +47,24 @@ namespace ModelSecondaryStructure {
             elements
         };
 
-        if (map.size > 0) assignSecondaryStructureRanges(hierarchy, map, secStruct);
+        if (map.size > 0) assignSecondaryStructureRanges(hierarchy, coordinates, map, secStruct);
         return SecondaryStructure(secStruct.type, secStruct.key, secStruct.elements, getIndex);
     }
 }
 
+function getCoordinateType(conf: StructConf, sheetRange: StructSheetRange): CoordinateType {
+    if (conf._rowCount > 0) {
+        if (conf.beg_label_seq_id.valueKind(0) !== Column.ValueKind.Present || conf.end_label_seq_id.valueKind(0) !== Column.ValueKind.Present) return 'auth';
+    } else if (sheetRange) {
+        if (sheetRange.beg_label_seq_id.valueKind(0) !== Column.ValueKind.Present || sheetRange.end_label_seq_id.valueKind(0) !== Column.ValueKind.Present) return 'auth';
+    }
+    return 'label';
+}
+
 type SecondaryStructureEntry = {
-    startSeqNumber: number,
+    startSeqId: number,
     startInsCode: string | null,
-    endSeqNumber: number,
+    endSeqId: number,
     endInsCode: string | null,
     type: SecondaryStructureType,
     key: number
@@ -59,13 +72,16 @@ type SecondaryStructureEntry = {
 type SecondaryStructureMap = Map<string, Map<number, SecondaryStructureEntry[]>>
 type SecondaryStructureData = { type: SecondaryStructureType[], key: number[], elements: SecondaryStructure.Element[] }
 
-function addHelices(cat: StructConf, map: SecondaryStructureMap, elements: SecondaryStructure.Element[]) {
+function addHelices(cat: StructConf, coordinates: CoordinateType, map: SecondaryStructureMap, elements: SecondaryStructure.Element[]) {
     if (!cat._rowCount) return;
 
-    const { beg_label_asym_id, beg_auth_seq_id, pdbx_beg_PDB_ins_code } = cat;
-    const { end_auth_seq_id, pdbx_end_PDB_ins_code } = cat;
+    const { beg_label_asym_id, beg_label_seq_id, beg_auth_seq_id, pdbx_beg_PDB_ins_code } = cat;
+    const { end_label_seq_id, end_auth_seq_id, pdbx_end_PDB_ins_code } = cat;
     const { pdbx_PDB_helix_class, conf_type_id, details } = cat;
 
+    const beg_seq_id = coordinates === 'label' ? beg_label_seq_id : beg_auth_seq_id;
+    const end_seq_id = coordinates === 'label' ? end_label_seq_id : end_auth_seq_id;
+
     for (let i = 0, _i = cat._rowCount; i < _i; i++) {
         const type = SecondaryStructureType.create(pdbx_PDB_helix_class.valueKind(i) === Column.ValueKind.Present
             ? SecondaryStructureType.SecondaryStructurePdb[pdbx_PDB_helix_class.value(i)]
@@ -81,9 +97,9 @@ function addHelices(cat: StructConf, map: SecondaryStructureMap, elements: Secon
             details: details.valueKind(i) === Column.ValueKind.Present ? details.value(i) : void 0
         };
         const entry: SecondaryStructureEntry = {
-            startSeqNumber: beg_auth_seq_id.value(i),
+            startSeqId: beg_seq_id.value(i),
             startInsCode: pdbx_beg_PDB_ins_code.value(i),
-            endSeqNumber: end_auth_seq_id.value(i),
+            endSeqId: end_seq_id.value(i),
             endInsCode: pdbx_end_PDB_ins_code.value(i),
             type,
             key: elements.length
@@ -94,24 +110,27 @@ function addHelices(cat: StructConf, map: SecondaryStructureMap, elements: Secon
         const asymId = beg_label_asym_id.value(i)!;
         if (map.has(asymId)) {
             const entries = map.get(asymId)!;
-            if (entries.has(entry.startSeqNumber)) {
-                entries.get(entry.startSeqNumber)!.push(entry);
+            if (entries.has(entry.startSeqId)) {
+                entries.get(entry.startSeqId)!.push(entry);
             } else {
-                entries.set(entry.startSeqNumber, [entry]);
+                entries.set(entry.startSeqId, [entry]);
             }
         } else {
-            map.set(asymId, new Map([[entry.startSeqNumber, [entry]]]));
+            map.set(asymId, new Map([[entry.startSeqId, [entry]]]));
         }
     }
 }
 
-function addSheets(cat: StructSheetRange, map: SecondaryStructureMap, sheetCount: number, elements: SecondaryStructure.Element[]) {
+function addSheets(cat: StructSheetRange, coordinates: CoordinateType, map: SecondaryStructureMap, sheetCount: number, elements: SecondaryStructure.Element[]) {
     if (!cat._rowCount) return;
 
-    const { beg_label_asym_id, beg_auth_seq_id, pdbx_beg_PDB_ins_code } = cat;
-    const { end_auth_seq_id, pdbx_end_PDB_ins_code } = cat;
+    const { beg_label_asym_id, beg_label_seq_id, beg_auth_seq_id, pdbx_beg_PDB_ins_code } = cat;
+    const { end_label_seq_id, end_auth_seq_id, pdbx_end_PDB_ins_code } = cat;
     const { sheet_id } = cat;
 
+    const beg_seq_id = coordinates === 'label' ? beg_label_seq_id : beg_auth_seq_id;
+    const end_seq_id = coordinates === 'label' ? end_label_seq_id : end_auth_seq_id;
+
     const sheet_id_key = new Map<string, number>();
     let currentKey = sheetCount + 1;
 
@@ -132,9 +151,9 @@ function addSheets(cat: StructSheetRange, map: SecondaryStructureMap, sheetCount
             symmetry: void 0
         };
         const entry: SecondaryStructureEntry = {
-            startSeqNumber: beg_auth_seq_id.value(i),
+            startSeqId: beg_seq_id.value(i),
             startInsCode: pdbx_beg_PDB_ins_code.value(i),
-            endSeqNumber: end_auth_seq_id.value(i),
+            endSeqId: end_seq_id.value(i),
             endInsCode: pdbx_end_PDB_ins_code.value(i),
             type,
             key: elements.length
@@ -145,31 +164,33 @@ function addSheets(cat: StructSheetRange, map: SecondaryStructureMap, sheetCount
         const asymId = beg_label_asym_id.value(i)!;
         if (map.has(asymId)) {
             const entries = map.get(asymId)!;
-            if (entries.has(entry.startSeqNumber)) {
-                entries.get(entry.startSeqNumber)!.push(entry);
+            if (entries.has(entry.startSeqId)) {
+                entries.get(entry.startSeqId)!.push(entry);
             } else {
-                entries.set(entry.startSeqNumber, [entry]);
+                entries.set(entry.startSeqId, [entry]);
             }
         } else {
-            map.set(asymId, new Map([[entry.startSeqNumber, [entry]]]));
+            map.set(asymId, new Map([[entry.startSeqId, [entry]]]));
         }
     }
 
     return;
 }
 
-function assignSecondaryStructureEntry(hierarchy: AtomicHierarchy, entry: SecondaryStructureEntry, resStart: ResidueIndex, resEnd: ResidueIndex, data: SecondaryStructureData) {
-    const { auth_seq_id, pdbx_PDB_ins_code } = hierarchy.residues;
-    const { endSeqNumber, endInsCode, key, type } = entry;
+function assignSecondaryStructureEntry(hierarchy: AtomicHierarchy, coordinates: CoordinateType, entry: SecondaryStructureEntry, resStart: ResidueIndex, resEnd: ResidueIndex, data: SecondaryStructureData) {
+    const { auth_seq_id, label_seq_id, pdbx_PDB_ins_code } = hierarchy.residues;
+    const { endSeqId, endInsCode, key, type } = entry;
+
+    const seq_id = coordinates === 'label' ? label_seq_id : auth_seq_id;
 
     let rI = resStart;
     while (rI < resEnd) {
-        const seqNumber = auth_seq_id.value(rI);
+        const seqNumber = seq_id.value(rI);
         data.type[rI] = type;
         data.key[rI] = key;
 
-        if ((seqNumber > endSeqNumber) ||
-            (seqNumber === endSeqNumber && pdbx_PDB_ins_code.value(rI) === endInsCode)) {
+        if ((seqNumber > endSeqId) ||
+            (seqNumber === endSeqId && pdbx_PDB_ins_code.value(rI) === endInsCode)) {
             break;
         }
 
@@ -177,10 +198,11 @@ function assignSecondaryStructureEntry(hierarchy: AtomicHierarchy, entry: Second
     }
 }
 
-function assignSecondaryStructureRanges(hierarchy: AtomicHierarchy, map: SecondaryStructureMap, data: SecondaryStructureData) {
+function assignSecondaryStructureRanges(hierarchy: AtomicHierarchy, coordinates: CoordinateType, map: SecondaryStructureMap, data: SecondaryStructureData) {
     const { count: chainCount } = hierarchy.chainAtomSegments;
     const { label_asym_id } = hierarchy.chains;
-    const { auth_seq_id, pdbx_PDB_ins_code } = hierarchy.residues;
+    const { auth_seq_id, label_seq_id, pdbx_PDB_ins_code } = hierarchy.residues;
+    const seq_id = coordinates === 'label' ? label_seq_id : auth_seq_id;
 
     for (let cI = 0 as ChainIndex; cI < chainCount; cI++) {
         const resStart = AtomicHierarchy.chainStartResidueIndex(hierarchy, cI), resEnd = AtomicHierarchy.chainEndResidueIndexExcl(hierarchy, cI);
@@ -189,13 +211,13 @@ function assignSecondaryStructureRanges(hierarchy: AtomicHierarchy, map: Seconda
             const entries = map.get(asymId)!;
 
             for (let rI = resStart; rI < resEnd; rI++) {
-                const seqNumber = auth_seq_id.value(rI);
-                if (entries.has(seqNumber)) {
-                    const entryList = entries.get(seqNumber)!;
+                const seqId = seq_id.value(rI);
+                if (entries.has(seqId)) {
+                    const entryList = entries.get(seqId)!;
                     for (const entry of entryList) {
                         const insCode = pdbx_PDB_ins_code.value(rI);
                         if (entry.startInsCode !== insCode) continue;
-                        assignSecondaryStructureEntry(hierarchy, entry, rI, resEnd, data);
+                        assignSecondaryStructureEntry(hierarchy, coordinates, entry, rI, resEnd, data);
                     }
                 }
             }

src/mol-model-props/computed/representations/interactions-intra-unit-cylinder.ts

@@ -15,12 +15,13 @@ import { VisualContext } from '../../../mol-repr/visual';
 import { Theme } from '../../../mol-theme/theme';
 import { InteractionsProvider } from '../interactions';
 import { createLinkCylinderMesh, LinkCylinderParams, LinkStyle } from '../../../mol-repr/structure/visual/util/link';
-import { UnitsMeshParams, UnitsVisual, UnitsMeshVisual, StructureGroup } from '../../../mol-repr/structure/units-visual';
+import { UnitsMeshParams, UnitsVisual, UnitsMeshVisual } from '../../../mol-repr/structure/units-visual';
 import { VisualUpdateState } from '../../../mol-repr/util';
 import { LocationIterator } from '../../../mol-geo/util/location-iterator';
 import { Interactions } from '../interactions/interactions';
 import { InteractionFlag } from '../interactions/common';
 import { Sphere3D } from '../../../mol-math/geometry';
+import { StructureGroup } from '../../../mol-repr/structure/visual/util/common';
 
 async function createIntraUnitInteractionsCylinderMesh(ctx: VisualContext, unit: Unit, structure: Structure, theme: Theme, props: PD.Values<InteractionsIntraUnitParams>, mesh?: Mesh) {
     if (!Unit.isAtomic(unit)) return Mesh.createEmpty(mesh);

src/mol-model/loci.ts

@@ -231,6 +231,11 @@ namespace Loci {
                 ? StructureElement.Loci.extendToWholeModels(loci)
                 : loci;
         },
+        'operator': (loci: Loci) => {
+            return StructureElement.Loci.is(loci)
+                ? StructureElement.Loci.extendToWholeOperators(loci)
+                : loci;
+        },
         'structure': (loci: Loci) => {
             return StructureElement.Loci.is(loci)
                 ? Structure.toStructureElementLoci(loci.structure)

src/mol-model/structure/structure/element/loci.ts

@@ -488,6 +488,27 @@ export namespace Loci {
         return Loci(loci.structure, elements);
     }
 
+    export function extendToWholeOperators(loci: Loci): Loci {
+        const elements: Loci['elements'][0][] = [];
+        const operators = new Set<string>();
+        const { units } = loci.structure;
+
+        for (let i = 0, len = loci.elements.length; i < len; i++) {
+            const e = loci.elements[i];
+            operators.add(e.unit.conformation.operator.name);
+        }
+
+        for (let i = 0, il = units.length; i < il; ++i) {
+            const unit = units[i];
+            if (operators.has(unit.conformation.operator.name)) {
+                const indices = OrderedSet.ofBounds(0, unit.elements.length) as OrderedSet<UnitIndex>;
+                elements[elements.length] = { unit, indices };
+            }
+        }
+
+        return Loci(loci.structure, elements);
+    }
+
     //
 
     const boundaryHelper = new BoundaryHelper('98');

src/mol-plugin/animation-loop.ts

@@ -31,18 +31,24 @@ export class PluginAnimationLoop {
         this.plugin.canvas3d?.resetTime(t);
     }
 
-    start() {
+    start(options?: { immediate?: boolean }) {
+        this.plugin.canvas3d?.resume();
         this._isAnimating = true;
         this.resetTime();
-        this.currentFrame = requestAnimationFrame(this.frame);
+        // TODO: should immediate be the default mode?
+        if (options?.immediate) this.frame();
+        else this.currentFrame = requestAnimationFrame(this.frame);
     }
 
-    stop() {
+    stop(options?: { noDraw?: boolean }) {
         this._isAnimating = false;
         if (this.currentFrame !== void 0) {
             cancelAnimationFrame(this.currentFrame);
             this.currentFrame = void 0;
         }
+        if (options?.noDraw) {
+            this.plugin.canvas3d?.pause(options?.noDraw);
+        }
     }
 
     constructor(private plugin: PluginContext) {

src/mol-plugin/behavior/dynamic/volume-streaming/util.ts

@@ -76,8 +76,22 @@ export async function getContourLevelEmdb(plugin: PluginContext, taskCtx: Runtim
 }
 
 export async function getContourLevelPdbe(plugin: PluginContext, taskCtx: RuntimeContext, emdbId: string) {
+    // TODO: parametrize URL in plugin settings?
+    emdbId = emdbId.toUpperCase();
+    const header = await plugin.fetch({ url: `https://www.ebi.ac.uk/emdb/api/entry/map/${emdbId}`, type: 'json' }).runInContext(taskCtx);
+    const contours = header?.map?.contour_list?.contour;
+
+    if (!contours || contours.length === 0) {
+        // try fallback to the old API
+        return getContourLevelPdbeLegacy(plugin, taskCtx, emdbId);
+    }
+
+    return contours.find((c: any) => c.primary)?.level ?? contours[0].level;
+}
+
+async function getContourLevelPdbeLegacy(plugin: PluginContext, taskCtx: RuntimeContext, emdbId: string) {
+    // TODO: parametrize URL in plugin settings?
     emdbId = emdbId.toUpperCase();
-    // TODO: parametrize to a differnt URL? in plugin settings perhaps
     const header = await plugin.fetch({ url: `https://www.ebi.ac.uk/pdbe/api/emdb/entry/map/${emdbId}`, type: 'json' }).runInContext(taskCtx);
     const emdbEntry = header?.[emdbId];
     let contourLevel: number | undefined = void 0;

src/mol-repr/structure/params.ts

@@ -22,6 +22,7 @@ export function getUnitKindsParam(defaultValue: UnitKind[]) {
 
 export const StructureParams = {
     unitKinds: getUnitKindsParam(['atomic', 'spheres']),
+    includeParent: PD.Boolean(false, { isHidden: true }),
 };
 export type StructureParams = typeof StructureParams
 

src/mol-repr/structure/representation/ball-and-stick.ts

@@ -27,6 +27,7 @@ export const BallAndStickParams = {
     traceOnly: PD.Boolean(false, { isHidden: true }), // not useful here
     ...IntraUnitBondCylinderParams,
     ...InterUnitBondCylinderParams,
+    includeParent: PD.Boolean(false),
     unitKinds: getUnitKindsParam(['atomic']),
     sizeFactor: PD.Numeric(0.15, { min: 0.01, max: 10, step: 0.01 }),
     sizeAspectRatio: PD.Numeric(2 / 3, { min: 0.01, max: 3, step: 0.01 }),

src/mol-repr/structure/representation/ellipsoid.ts

@@ -25,6 +25,7 @@ export const EllipsoidParams = {
     ...EllipsoidMeshParams,
     ...IntraUnitBondCylinderParams,
     ...InterUnitBondCylinderParams,
+    includeParent: PD.Boolean(false),
     adjustCylinderLength: PD.Boolean(false, { isHidden: true }), // not useful here
     unitKinds: getUnitKindsParam(['atomic']),
     sizeFactor: PD.Numeric(1, { min: 0.01, max: 10, step: 0.01 }),

src/mol-repr/structure/representation/line.ts

@@ -23,6 +23,7 @@ const LineVisuals = {
 export const LineParams = {
     ...IntraUnitBondLineParams,
     ...InterUnitBondLineParams,
+    includeParent: PD.Boolean(false),
     sizeFactor: PD.Numeric(1.5, { min: 0.01, max: 10, step: 0.01 }),
     unitKinds: getUnitKindsParam(['atomic']),
     visuals: PD.MultiSelect(['intra-bond', 'inter-bond'], PD.objectToOptions(LineVisuals))

src/mol-repr/structure/units-representation.ts

@@ -8,7 +8,6 @@
 import { ParamDefinition as PD } from '../../mol-util/param-definition';
 import { StructureRepresentation, StructureRepresentationStateBuilder, StructureRepresentationState } from './representation';
 import { Visual } from '../visual';
-import { StructureGroup } from './units-visual';
 import { RepresentationContext, RepresentationParamsGetter } from '../representation';
 import { Structure, Unit, StructureElement, Bond } from '../../mol-model/structure';
 import { Subject } from 'rxjs';
@@ -25,6 +24,7 @@ import { Interval } from '../../mol-data/int';
 import { StructureParams } from './params';
 import { Clipping } from '../../mol-theme/clipping';
 import { WebGLContext } from '../../mol-gl/webgl/context';
+import { StructureGroup } from './visual/util/common';
 
 export interface UnitsVisual<P extends StructureParams> extends Visual<StructureGroup, P> { }
 

src/mol-repr/structure/units-visual.ts

@@ -11,7 +11,7 @@ import { Visual, VisualContext } from '../visual';
 import { Geometry, GeometryUtils } from '../../mol-geo/geometry/geometry';
 import { LocationIterator } from '../../mol-geo/util/location-iterator';
 import { Theme } from '../../mol-theme/theme';
-import { createUnitsTransform, includesUnitKind } from './visual/util/common';
+import { createUnitsTransform, includesUnitKind, StructureGroup } from './visual/util/common';
 import { createRenderObject, GraphicsRenderObject, RenderObjectValues } from '../../mol-gl/render-object';
 import { PickingId } from '../../mol-geo/geometry/picking';
 import { Loci, isEveryLoci, EmptyLoci } from '../../mol-model/loci';
@@ -41,13 +41,11 @@ import { Clipping } from '../../mol-theme/clipping';
 import { WebGLContext } from '../../mol-gl/webgl/context';
 import { isPromiseLike } from '../../mol-util/type-helpers';
 
-export type StructureGroup = { structure: Structure, group: Unit.SymmetryGroup }
-
 export interface UnitsVisual<P extends RepresentationProps = {}> extends Visual<StructureGroup, P> { }
 
-function createUnitsRenderObject<G extends Geometry>(group: Unit.SymmetryGroup, geometry: G, locationIt: LocationIterator, theme: Theme, props: PD.Values<Geometry.Params<G>>, materialId: number) {
+function createUnitsRenderObject<G extends Geometry>(structureGroup: StructureGroup, geometry: G, locationIt: LocationIterator, theme: Theme, props: PD.Values<StructureParams & Geometry.Params<G>>, materialId: number) {
     const { createValues, createRenderableState } = Geometry.getUtils(geometry);
-    const transform = createUnitsTransform(group);
+    const transform = createUnitsTransform(structureGroup, props.includeParent);
     const values = createValues(geometry, transform, locationIt, theme, props);
     const state = createRenderableState(props);
     return createRenderObject(geometry.kind, values, state, materialId);
@@ -179,7 +177,7 @@ export function UnitsVisual<G extends Geometry, P extends StructureParams & Geom
         if (updateState.createNew) {
             locationIt = createLocationIterator(newStructureGroup);
             if (newGeometry) {
-                renderObject = createUnitsRenderObject(newStructureGroup.group, newGeometry, locationIt, newTheme, newProps, materialId);
+                renderObject = createUnitsRenderObject(newStructureGroup, newGeometry, locationIt, newTheme, newProps, materialId);
                 positionIt = createPositionIterator(newGeometry, renderObject.values);
             } else {
                 throw new Error('expected geometry to be given');
@@ -198,7 +196,7 @@ export function UnitsVisual<G extends Geometry, P extends StructureParams & Geom
 
             if (updateState.updateMatrix) {
                 // console.log('update matrix');
-                createUnitsTransform(newStructureGroup.group, renderObject.values);
+                createUnitsTransform(newStructureGroup, newProps.includeParent, renderObject.values);
             }
 
             if (updateState.createGeometry) {

src/mol-repr/structure/visual/bond-intra-unit-cylinder.ts

@@ -13,7 +13,7 @@ import { Mesh } from '../../../mol-geo/geometry/mesh/mesh';
 import { Vec3 } from '../../../mol-math/linear-algebra';
 import { arrayEqual } from '../../../mol-util';
 import { createLinkCylinderImpostors, createLinkCylinderMesh, LinkBuilderProps, LinkStyle } from './util/link';
-import { UnitsMeshParams, UnitsVisual, UnitsMeshVisual, StructureGroup, UnitsCylindersParams, UnitsCylindersVisual } from '../units-visual';
+import { UnitsMeshParams, UnitsVisual, UnitsMeshVisual, UnitsCylindersParams, UnitsCylindersVisual } from '../units-visual';
 import { VisualUpdateState } from '../../util';
 import { BondType } from '../../../mol-model/structure/model/types';
 import { BondCylinderParams, BondIterator, eachIntraBond, getIntraBondLoci, makeIntraBondIgnoreTest } from './util/bond';
@@ -23,6 +23,7 @@ import { WebGLContext } from '../../../mol-gl/webgl/context';
 import { Cylinders } from '../../../mol-geo/geometry/cylinders/cylinders';
 import { SortedArray } from '../../../mol-data/int';
 import { arrayIntersectionSize } from '../../../mol-util/array';
+import { StructureGroup } from './util/common';
 
 // avoiding namespace lookup improved performance in Chrome (Aug 2020)
 const isBondType = BondType.is;

src/mol-repr/structure/visual/bond-intra-unit-line.ts

@@ -11,7 +11,7 @@ import { Theme } from '../../../mol-theme/theme';
 import { Vec3 } from '../../../mol-math/linear-algebra';
 import { arrayEqual } from '../../../mol-util';
 import { LinkStyle, createLinkLines, LinkBuilderProps } from './util/link';
-import { UnitsVisual, UnitsLinesParams, UnitsLinesVisual, StructureGroup } from '../units-visual';
+import { UnitsVisual, UnitsLinesParams, UnitsLinesVisual } from '../units-visual';
 import { VisualUpdateState } from '../../util';
 import { BondType } from '../../../mol-model/structure/model/types';
 import { BondIterator, BondLineParams, getIntraBondLoci, eachIntraBond, makeIntraBondIgnoreTest } from './util/bond';
@@ -19,6 +19,7 @@ import { Sphere3D } from '../../../mol-math/geometry';
 import { Lines } from '../../../mol-geo/geometry/lines/lines';
 import { IntAdjacencyGraph } from '../../../mol-math/graph';
 import { arrayIntersectionSize } from '../../../mol-util/array';
+import { StructureGroup } from './util/common';
 
 // avoiding namespace lookup improved performance in Chrome (Aug 2020)
 const isBondType = BondType.is;

src/mol-repr/structure/visual/element-sphere.ts

@@ -6,12 +6,13 @@
  */
 
 import { ParamDefinition as PD } from '../../../mol-util/param-definition';
-import { UnitsMeshParams, UnitsSpheresParams, UnitsVisual, UnitsSpheresVisual, UnitsMeshVisual, StructureGroup } from '../units-visual';
+import { UnitsMeshParams, UnitsSpheresParams, UnitsVisual, UnitsSpheresVisual, UnitsMeshVisual } from '../units-visual';
 import { WebGLContext } from '../../../mol-gl/webgl/context';
 import { createElementSphereImpostor, ElementIterator, getElementLoci, eachElement, createElementSphereMesh } from './util/element';
 import { VisualUpdateState } from '../../util';
 import { BaseGeometry } from '../../../mol-geo/geometry/base';
 import { Structure } from '../../../mol-model/structure';
+import { StructureGroup } from './util/common';
 
 export const ElementSphereParams = {
     ...UnitsMeshParams,

src/mol-repr/structure/visual/gaussian-surface-mesh.ts

@@ -5,7 +5,7 @@
  */
 
 import { ParamDefinition as PD } from '../../../mol-util/param-definition';
-import { UnitsMeshParams, UnitsTextureMeshParams, UnitsVisual, UnitsMeshVisual, UnitsTextureMeshVisual, StructureGroup } from '../units-visual';
+import { UnitsMeshParams, UnitsTextureMeshParams, UnitsVisual, UnitsMeshVisual, UnitsTextureMeshVisual } from '../units-visual';
 import { GaussianDensityParams, computeUnitGaussianDensity, computeUnitGaussianDensityTexture2d, GaussianDensityProps, computeStructureGaussianDensity, computeStructureGaussianDensityTexture2d } from './util/gaussian';
 import { VisualContext } from '../../visual';
 import { Unit, Structure } from '../../../mol-model/structure';
@@ -18,7 +18,7 @@ import { TextureMesh } from '../../../mol-geo/geometry/texture-mesh/texture-mesh
 import { extractIsosurface } from '../../../mol-gl/compute/marching-cubes/isosurface';
 import { Sphere3D } from '../../../mol-math/geometry';
 import { ComplexVisual, ComplexMeshParams, ComplexMeshVisual, ComplexTextureMeshVisual, ComplexTextureMeshParams } from '../complex-visual';
-import { getUnitExtraRadius, getStructureExtraRadius, getVolumeSliceInfo } from './util/common';
+import { getUnitExtraRadius, getStructureExtraRadius, getVolumeSliceInfo, StructureGroup } from './util/common';
 import { WebGLContext } from '../../../mol-gl/webgl/context';
 import { MeshValues } from '../../../mol-gl/renderable/mesh';
 import { TextureMeshValues } from '../../../mol-gl/renderable/texture-mesh';

src/mol-repr/structure/visual/orientation-ellipsoid-mesh.ts

@@ -5,7 +5,7 @@
  */
 
 import { ParamDefinition as PD } from '../../../mol-util/param-definition';
-import { UnitsMeshParams, UnitsVisual, UnitsMeshVisual, StructureGroup } from '../../../mol-repr/structure/units-visual';
+import { UnitsMeshParams, UnitsVisual, UnitsMeshVisual } from '../../../mol-repr/structure/units-visual';
 import { VisualUpdateState } from '../../../mol-repr/util';
 import { VisualContext } from '../../../mol-repr/visual';
 import { Unit, Structure, StructureElement } from '../../../mol-model/structure';
@@ -22,6 +22,7 @@ import { UnitIndex } from '../../../mol-model/structure/structure/element/elemen
 import { LocationIterator } from '../../../mol-geo/util/location-iterator';
 import { MoleculeType } from '../../../mol-model/structure/model/types';
 import { BaseGeometry } from '../../../mol-geo/geometry/base';
+import { StructureGroup } from './util/common';
 
 export const OrientationEllipsoidMeshParams = {
     ...UnitsMeshParams,

src/mol-repr/structure/visual/polymer-backbone-cylinder.ts

@@ -14,7 +14,7 @@ import { Vec3 } from '../../../mol-math/linear-algebra';
 import { CylinderProps } from '../../../mol-geo/primitive/cylinder';
 import { eachPolymerElement, getPolymerElementLoci, NucleicShift, PolymerLocationIterator, StandardShift } from './util/polymer';
 import { addCylinder } from '../../../mol-geo/geometry/mesh/builder/cylinder';
-import { UnitsMeshParams, UnitsVisual, UnitsMeshVisual, UnitsCylindersVisual, UnitsCylindersParams, StructureGroup } from '../units-visual';
+import { UnitsMeshParams, UnitsVisual, UnitsMeshVisual, UnitsCylindersVisual, UnitsCylindersParams } from '../units-visual';
 import { VisualUpdateState } from '../../util';
 import { BaseGeometry } from '../../../mol-geo/geometry/base';
 import { Sphere3D } from '../../../mol-math/geometry';
@@ -23,6 +23,7 @@ import { WebGLContext } from '../../../mol-gl/webgl/context';
 import { Cylinders } from '../../../mol-geo/geometry/cylinders/cylinders';
 import { CylindersBuilder } from '../../../mol-geo/geometry/cylinders/cylinders-builder';
 import { eachPolymerBackboneLink } from './util/polymer/backbone';
+import { StructureGroup } from './util/common';
 
 // avoiding namespace lookup improved performance in Chrome (Aug 2020)
 const v3scale = Vec3.scale;

src/mol-repr/structure/visual/polymer-backbone-sphere.ts

@@ -12,7 +12,7 @@ import { Mesh } from '../../../mol-geo/geometry/mesh/mesh';
 import { MeshBuilder } from '../../../mol-geo/geometry/mesh/mesh-builder';
 import { Vec3 } from '../../../mol-math/linear-algebra';
 import { eachPolymerElement, getPolymerElementLoci, PolymerLocationIterator } from './util/polymer';
-import { UnitsMeshParams, UnitsVisual, UnitsMeshVisual, UnitsSpheresVisual, UnitsSpheresParams, StructureGroup } from '../units-visual';
+import { UnitsMeshParams, UnitsVisual, UnitsMeshVisual, UnitsSpheresVisual, UnitsSpheresParams } from '../units-visual';
 import { VisualUpdateState } from '../../util';
 import { BaseGeometry } from '../../../mol-geo/geometry/base';
 import { Sphere3D } from '../../../mol-math/geometry';
@@ -22,6 +22,7 @@ import { WebGLContext } from '../../../mol-gl/webgl/context';
 import { Spheres } from '../../../mol-geo/geometry/spheres/spheres';
 import { SpheresBuilder } from '../../../mol-geo/geometry/spheres/spheres-builder';
 import { eachPolymerBackboneElement } from './util/polymer/backbone';
+import { StructureGroup } from './util/common';
 
 export const PolymerBackboneSphereParams = {
     ...UnitsMeshParams,

src/mol-repr/structure/visual/polymer-trace-mesh.ts

@@ -14,7 +14,7 @@ import { createCurveSegmentState, PolymerTraceIterator, interpolateCurveSegment,
 import { isNucleic, SecondaryStructureType } from '../../../mol-model/structure/model/types';
 import { addSheet } from '../../../mol-geo/geometry/mesh/builder/sheet';
 import { addTube } from '../../../mol-geo/geometry/mesh/builder/tube';
-import { UnitsMeshParams, UnitsVisual, UnitsMeshVisual, StructureGroup } from '../units-visual';
+import { UnitsMeshParams, UnitsVisual, UnitsMeshVisual } from '../units-visual';
 import { VisualUpdateState } from '../../util';
 import { SecondaryStructureProvider } from '../../../mol-model-props/computed/secondary-structure';
 import { addRibbon } from '../../../mol-geo/geometry/mesh/builder/ribbon';
@@ -22,6 +22,7 @@ import { addSphere } from '../../../mol-geo/geometry/mesh/builder/sphere';
 import { Vec3 } from '../../../mol-math/linear-algebra';
 import { BaseGeometry } from '../../../mol-geo/geometry/base';
 import { Sphere3D } from '../../../mol-math/geometry';
+import { StructureGroup } from './util/common';
 
 export const PolymerTraceMeshParams = {
     sizeFactor: PD.Numeric(0.2, { min: 0, max: 10, step: 0.01 }),

src/mol-repr/structure/visual/util/bond.ts

@@ -8,13 +8,12 @@ import { BondType } from '../../../../mol-model/structure/model/types';
 import { Unit, StructureElement, Structure, Bond } from '../../../../mol-model/structure';
 import { ParamDefinition as PD } from '../../../../mol-util/param-definition';
 import { LocationIterator } from '../../../../mol-geo/util/location-iterator';
-import { StructureGroup } from '../../units-visual';
 import { LinkCylinderParams, LinkLineParams } from './link';
 import { ObjectKeys } from '../../../../mol-util/type-helpers';
 import { PickingId } from '../../../../mol-geo/geometry/picking';
 import { EmptyLoci, Loci } from '../../../../mol-model/loci';
 import { Interval, OrderedSet, SortedArray } from '../../../../mol-data/int';
-import { isH, isHydrogen } from './common';
+import { isH, isHydrogen, StructureGroup } from './common';
 
 export const BondParams = {
     includeTypes: PD.MultiSelect(ObjectKeys(BondType.Names), PD.objectToOptions(BondType.Names)),

src/mol-repr/structure/visual/util/common.ts

@@ -71,7 +71,13 @@ export function getAltResidueLociFromId(structure: Structure, unit: Unit.Atomic,
 
 //
 
-export function createUnitsTransform({ units }: Unit.SymmetryGroup, transformData?: TransformData) {
+export type StructureGroup = { structure: Structure, group: Unit.SymmetryGroup }
+
+export function createUnitsTransform(structureGroup: StructureGroup, includeParent: boolean, transformData?: TransformData) {
+    const { child } = structureGroup.structure;
+    const units: ReadonlyArray<Unit> = includeParent && child
+        ? structureGroup.group.units.filter(u => child.unitMap.has(u.id))
+        : structureGroup.group.units;
     const unitCount = units.length;
     const n = unitCount * 16;
     const array = transformData && transformData.aTransform.ref.value.length >= n ? transformData.aTransform.ref.value : new Float32Array(n);

src/mol-repr/structure/visual/util/element.ts

@@ -17,10 +17,9 @@ import { PickingId } from '../../../../mol-geo/geometry/picking';
 import { LocationIterator } from '../../../../mol-geo/util/location-iterator';
 import { VisualContext } from '../../../../mol-repr/visual';
 import { Theme } from '../../../../mol-theme/theme';
-import { StructureGroup } from '../../../../mol-repr/structure/units-visual';
 import { Spheres } from '../../../../mol-geo/geometry/spheres/spheres';
 import { SpheresBuilder } from '../../../../mol-geo/geometry/spheres/spheres-builder';
-import { isTrace, isH } from './common';
+import { isTrace, isH, StructureGroup } from './common';
 import { Sphere3D } from '../../../../mol-math/geometry';
 
 // avoiding namespace lookup improved performance in Chrome (Aug 2020)

src/mol-repr/structure/visual/util/nucleotide.ts

@@ -9,8 +9,7 @@ import { Loci, EmptyLoci } from '../../../../mol-model/loci';
 import { Interval } from '../../../../mol-data/int';
 import { LocationIterator } from '../../../../mol-geo/util/location-iterator';
 import { PickingId } from '../../../../mol-geo/geometry/picking';
-import { StructureGroup } from '../../../../mol-repr/structure/units-visual';
-import { getResidueLoci } from './common';
+import { getResidueLoci, StructureGroup } from './common';
 import { eachAtomicUnitTracedElement } from './polymer';
 
 export namespace NucleotideLocationIterator {

src/mol-repr/structure/visual/util/polymer.ts

@@ -11,8 +11,7 @@ import { OrderedSet, Interval, SortedArray } from '../../../../mol-data/int';
 import { EmptyLoci, Loci } from '../../../../mol-model/loci';
 import { LocationIterator } from '../../../../mol-geo/util/location-iterator';
 import { PickingId } from '../../../../mol-geo/geometry/picking';
-import { StructureGroup } from '../../../structure/units-visual';
-import { getResidueLoci } from './common';
+import { getResidueLoci, StructureGroup } from './common';
 
 export * from './polymer/backbone';
 export * from './polymer/gap-iterator';