-
Notifications
You must be signed in to change notification settings - Fork 33
3. Helper Methods
Helper functions are useful for programmatically controlling the visualization. The following examples demonstrate how the helper functions can be used:
The plugin implementation and web component implementation both provide helper functions for the categories below.
setBgColor(color?: string | { r: number, g: number, b: number }) => Promise<void>
Set canvas background color.
Example: set the background color to white
instance.canvas.setBgColor({ r: 255, g: 255, b: 255 });toggleControls(isVisible?: boolean) => void
Set controls panel visibility. Without isVisible parameter, toggle controls panel visibility.
Example: make the controls visible
instance.canvas.toggleControls(true);toggleExpanded(isExpanded?: boolean) => void
Set full-screen mode on or off. Without isExpanded parameter, toggle full-screen mode.
Example: switch to full-screen
instance.canvas.toggleExpanded(true);visibility(data: { polymer?: boolean, het?: boolean, water?: boolean, carbs?: boolean, nonStandard?: boolean, maps?: boolean }) => Promise<void>
Change the visibility of individual entity visuals.
Example: hide the ligand and water visuals
instance.visual.visibility({ het: false, water: false });structureVisibility(structureNumberOrId: string | number, visibility?: boolean) => Promise<void>
Change the visibility of a structure.
structureNumberOrId is either index (numbered from 1!) or the ID that was provided when loading the structure.
If visibility is undefined, toggle current visibility state.
Example: hide the ligand and water visuals
instance.visual.structureVisibility('main', false);toggleSpin(isSpinning?: boolean, resetCamera?: boolean) => Promise<void>
With isSpinning parameter, switch visual rotation on or off. Without isSpinning parameter, toggle rotation. If resetCamera, also reset the camera zoom.
Example: switch the rotation on
instance.visual.toggleSpin(true);focus(selection: QueryParam[], structureNumberOrId?: number | string) => Promise<void>
(QueryParam defined here)
Focus (zoom) on the part of the structure defined by selection.
If selection contains more items, focus on the union of those.
structureNumberOrId is either index (numbered from 1!) or the ID that was provided when loading the structure;
if not provided, will use the last added structure.
Example: focus on residue range 10–15 of chain A of entity 1
instance.visual.focus([{ entity_id: '1', struct_asym_id: 'A', start_residue_number: 10, end_residue_number: 15 }]);highlight(params: { data: QueryParam[], color?: AnyColor, focus?: boolean, structureId?: string, structureNumber?: number }) => Promise<void>
(QueryParam defined here)
Trigger highlight on the part of the structure defined by data
(this will look the same as when the user hovers over a part of the structure).
If focus, also zoom on the highlighted part.
If structureId or structureNumber is provided, use the specified structure (numbered from 1!); otherwise use the last added structure.
Example: highlight residue range 10–15 of chain A of entity 1
instance.visual.highlight({
data: [
{ entity_id: '1', struct_asym_id: 'A', start_residue_number: 10, end_residue_number: 15 },
],
});clearHighlight() => Promise<void>
Remove any current highlight and reset the highlight color to its default value.
Example: clear highlight
instance.visual.clearHighlight();select(params: { data: QueryParam[], nonSelectedColor?: AnyColor, structureId?: string, structureNumber?: number, keepColors?: boolean, keepRepresentations?: boolean }) => Promise<void>
(QueryParam defined here)
CoColor the parts of the structure defined by data. Color the rest of the structure in nonSelectedColor if provided.
If any items in data contain focus, zoom to the union of these items.
If any items in data contain sideChain or representation, add extra representations to them (colored in representationColor if provided).
If structureNumber is provided, apply to the specified structure (numbered from 1!); otherwise apply to all loaded structures.
Remove any previously added coloring and extra representations, unless keepColors and/or keepRepresentations is set.
* This method is not related to creating selections with Selection Mode (the mouse cursor icon).
Example: color residue range 10–15 of chain A of entity 1 in red and the rest of the structure in yellow color, zoom on the selected residues
instance.visual.select({
data: [
{ entity_id: '1', struct_asym_id: 'A', start_residue_number: 10, end_residue_number: 15, color: '#ff0000', focus: true },
],
nonSelectedColor: '#ffff00',
});clearSelection(structureNumberOrId?: number | string, options?: { keepColors?: boolean, keepRepresentations?: boolean }) => Promise<void>
Remove any coloring and extra representations previously added by the select method.
structureNumberOrId is either index (numbered from 1!) or the ID that was provided when loading the structure;
if not provided, will apply to all loaded structures.
If keepColors, current residue coloring is preserved. If keepRepresentations, current added representations are preserved.
Example: clear all active selections
instance.visual.clearSelection();tooltips: (params: { data: QueryParam[], structureId?: string, structureNumber?: number }) => Promise<void>
(QueryParam defined here)
Add interactive tooltips to parts of the structure. The added tooltips will be shown on a separate line in the tooltip box.
Repeated call to this function removes any previously added tooltips.
structureNumber counts from 1; if not provided, tooltips will be applied to all loaded structures.
Example:
instance.visual.tooltips({
data: [
{ struct_asym_id: 'A', tooltip: 'Chain A' },
{ struct_asym_id: 'B', tooltip: 'Chain B' },
],
});clearTooltips: (structureNumberOrId?: number | string) => Promise<void>
Remove any custom tooltips added by the tooltips method.
Example: remove all custom tooltips
instance.visual.clearTooltips();setColor(params: { highlight?: AnyColor, select?: AnyColor }) => Promise<void>
Set highlight and/or selection color. Highlight color is used when the user hovers over a part of the structure or when applying the highlight method. Selection color is used when creating selections with Selection Mode (the mouse cursor icon) and is not related to the color used by the select method.
Example: set highlight color to yellow
instance.visual.setColor({ highlight: '#ffff00' });reset(params: { camera?: boolean, theme?: boolean, highlightColor?: boolean, selectColor?: boolean }) => Promise<void>
Reset various settings to defaults: camera resets camera position (i.e. zooms on the whole scene). theme resets color theme for visual representations. highlightColor and selectColor reset colors previously set by the setColor method.
Example: reset camera position and color theme
instance.visual.reset({ camera: true, theme: true });update(options: Partial<InitParams>, fullLoad?: boolean) => Promise<boolean>
(plugin parameters (InitParams) defined here)
Change parameters of the plugin instance.
Can be used to load a different structure. If fullLoad, remove currently loaded structure before loading the new one; otherwise add the new structure to existing structures.
Example: add the structure of PDB entry 1cbs
instance.visual.update({ moleculeId: '1cbs' }, false);Event listeners can be used to bind the PDBe Molstar custom events
| Event | Description |
|---|---|
PDB.molstar.click |
Binds to click event. Event data (available in key = 'eventData') contains information structure residue clicked Example: document.addEventListener('PDB.molstar.click', (e) => { /* do something on event */ });
|
PDB.molstar.mouseover |
Binds to mouseover event. Example: document.addEventListener('PDB.molstar.mouseover', (e) => { /* do something on event */ });
|
PDB.molstar.mouseout |
Binds to mouseout event. Example: document.addEventListener('PDB.molstar.mouseout', () => { /* do something on event */ });
|
loadComplete |
This is a reactive event available on the viewer instance. It is fired on load/render completion. Example: instance.events.loadComplete.subscribe(() => { /* do something after 3D view is fully loaded */ });
|
-
Previous versions