tweaks

add external-structure theme

.eslintignore

@@ -1,3 +1,4 @@
 node_modules/*
 build/*
+docs/site/*
 lib/*

.github/pull_request_template.md

@@ -7,4 +7,5 @@
 
 - [ ] Added description of changes to the `[Unreleased]` section of `CHANGELOG.md`
 - [ ] Updated headers of modified files
-- [ ] Added my name to `package.json`'s `contributors`
+- [ ] Added my name to `package.json`'s `contributors`
+- [ ] (Optional but encouraged) Improved documentation in `docs`

.github/workflows/docs.yml

@@ -0,0 +1,62 @@
+name: Build & Deploy Docs
+
+on:
+  push:
+    branches: master
+    paths:
+      - docs/**
+      - ".github/workflows/docs.yml"
+  pull_request:
+    branches: master
+    paths:
+      - docs/**
+      - ".github/workflows/docs.yml"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 👨🏼‍💻 checkout
+        uses: actions/checkout@v4
+
+      - name: 🐍 python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: ⛓️ dependencies
+        run: |
+          pip install mkdocs-material
+      - name: 🔧 build site
+        run: |
+          cd docs
+          mkdocs build
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.ref == 'refs/heads/master'
+    steps:
+      - name: 👨🏼‍💻 checkout
+        uses: actions/checkout@v4
+
+      - name: 🐍 python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: ⛓️ dependencies
+        run: |
+          pip install mkdocs-material
+      - name: 🔧 build site
+        run: |
+          cd docs
+          mkdocs build
+
+      - name: 🚢 deploy docs
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          deploy_key: ${{ secrets.DOCS_DEPLOY_KEY }}
+          external_repository: molstar/docs
+          publish_branch: gh-pages
+          publish_dir: ./docs/site

.github/workflows/node.yml

@@ -2,7 +2,9 @@ name: Build
 
 on:
   push:
+    branches: master
   pull_request:
+    branches: master
 
 jobs:
   build:

.gitignore

@@ -1,5 +1,6 @@
 build/
 lib/
+docs/site/
 
 node_modules/
 debug.log

CHANGELOG.md

@@ -3,10 +3,245 @@ All notable changes to this project will be documented in this file, following t
 
 Note that since we don't clearly distinguish between a public and private interfaces there will be changes in non-major versions that are potentially breaking. If we make breaking changes to less used interfaces we will highlight it in here.
 
-
 ## [Unreleased]
 
-## [v4.0.0-beta.0] - 2023-01-06
+- Volume UI improvements
+  - Render all volume entries instead of selecting them one-by-one
+  - Toggle visibility of all volumes
+  - More accessible iso value control
+- Support wheel event on sliders
+- MolViewSpec extension:
+  - Add validation for discriminated union params
+  - Primitives: remove triangle_colors, line_colors, have implicit grouping instead; rename many parameters
+- Add `external-structure` theme that colors any geometry by structure properties
+- Support float and half-float data type for direct-volume rendering and GPU isosurface extraction
+- Minor documentation updates
+- Fix plugin mouse interactions when CSS `scale` transform is applied
+
+## [v4.10.0] - 2024-12-15
+
+- Add `ModelWithCoordinates` decorator transform.
+- Fix outlines on transparent background using illumination mode (#1364)
+- Fix transparent depth texture artifacts using illumination mode
+- Fix marking of consecutive gap elements (#876)
+- Allow React 19 in dependencies
+- Fix missing deflate header if `CompressionStream` is available
+- Fix is_iOS check for NodeJS
+- Added PluginCommands.Camera.FocusObject
+- Plugin state snapshot can have instructions to focus objects (PluginState.Snapshot.camera.focus)
+- MolViewSpec extension: Support for multi-state files (animations)
+- Fix units transform data not fully updated when structure child changes
+- Fix `addIndexPairBonds` quadratic runtime case
+- Use adjoint matrix to transform normals in shaders
+- Fix resize handling in `tests/browser`
+
+## [v4.9.1] - 2024-12-05
+
+- Fix iOS check when running on Node
+
+## [v4.9.0] - 2024-12-01
+
+- Fix artifacts when using xray shading with high xrayEdgeFalloff values
+- Enable double rounded capping on tubular helices
+- Fix single residue tubular helices not showing up
+- Fix outlines on volume and surface reps that do not disappear (#1326)
+- Add example `glb-export`
+- Membrane orientation: Improve `isApplicable` check and error handling (#1316)
+- Fix set fenceSync to null after deleteSync.
+- Fix operator key-based `IndexPairBonds` assignment
+    - Don't add bonds twice
+    - Add `IndexPairs.bySameOperator` to avoid looping over all bonds for each unit
+- Add `Structure.intraUnitBondMapping`
+- Add more structure-based visuals to avoid too many (small) render-objects
+    - `structure-intra-bond`, `structure-ellipsoid-mesh`, `structure-element-point`, `structure-element-cross`
+- Upgrade to express v5 (#1311)
+- Fix occupancy check using wrong index for inter-unit bond computation (@rxht, #1321)
+- Fix transparent SSAO for image rendering, e.g., volumne slices (#1332)
+- Fix bonds not shown with `ignoreHydrogens` on (#1315)
+    - Better handle mmCIF files with no entities defined by using `label_asym_id`
+    - Show bonds in water chains when `ignoreHydorgensVariant` is `non-polar`
+- Add MembraneServer API, generating data to be consumed in the context of MolViewSpec
+- Fix `StructConn.isExhaustive` for partial models (e.g., returned by the model server)
+- Refactor value swapping in molstar-math to fix SWC (Next.js) build (#1345)
+- Fix transform data not updated when structure child changes
+- Fix `PluginStateSnapshotManager.syncCurrent` to work as expected on re-loaded states.
+- Fix do not compute implicit hydrogens when unit is explicitly protonated (#1257)
+- ModelServer and VolumeServer: support for input files from Google Cloud Storage (gs://)
+- Fix color of missing partial charges for SB partial charges extension
+
+## [v4.8.0] - 2024-10-27
+
+- Add SSAO support for transparent geometry
+- Fix SSAO color not updating
+- Improve blending of overlapping outlines from transparent & opaque geometries
+- Default to `blended` transparency on iOS due to `wboit` not being supported.
+- Fix direct-volume with fog off (and on with `dpoit`) and transparent background on (#1286)
+- Fix missing pre-multiplied alpha for `blended` & `wboit` with no fog (#1284)
+- Fix backfaces visible using blended transparency on impostors (#1285)
+- Fix StructureElement.Loci.isSubset() only considers common units (#1292)
+- Fix `Scene.opacityAverage` calculation never 1
+- Fix bloom in illumination mode
+- Fix `findPredecessorIndex` bug when repeating values
+- MolViewSpec: Support for transparency and custom properties
+- MolViewSpec: MVP Support for geometrical primitives (mesh, lines, line, label, distance measurement)
+- Mesoscale Explorer: Add support for 4-character PDB IDs (e.g., 8ZZC) in PDB-Dev loader
+- Fix Sequence View in Safari 18
+- Improve performance of `IndexPairBonds` assignment when operator keys are available
+- ModelArchive QualityAssessment extension:
+    - Add support for ma_qa_metric_local_pairwise mmCIF category
+    - Add PAE plot component
+- Add new AlphaFoldDB-PAE example app
+- Add support for LAMMPS data and dump formats
+- Remove extra anti-aliasing from text shader (fixes #1208 & #1306)
+
+## [v4.7.1] - 2024-09-30
+
+- Improve `resolutionMode` (#1279)
+    - Add `auto` that picks `scaled` for mobile devices and `native` elsewhere
+    - Add `resolution-mode` Viewer GET param
+    - Add `PluginConfig.General.ResolutionMode` config item
+
+## [v4.7.0] - 2024-09-29
+
+- Add illumination mode
+    - Path-traced SSGI
+    - Automatic thickness (estimate)
+        - Base thickness as max(backface depth) - min(frontface depth)
+        - Per object density factor to adjust thickness
+    - Progressively trace samples to keep viewport interactive
+    - Toggle on/off by pressing "G"
+    - `illumination` Viewer GET param
+- Enables dXrayShaded define when rendering depth
+- Fix handling of PDB files that have chains with same id separated by TER record (#1245)
+- Sequence Panel: Improve visuals of unmodeled sequence positions (#1248)
+- Fix no-compression xtc parser (#1258)
+- Mol2 Reader: Fix mol2 status_bit read error (#1251)
+- Fix shadows with multiple lights
+- Fix impostor sphere interior normal when using orthographic projection
+- Add `resolutionMode` parameter to `Canvas3DContext`
+    - `scaled`, divides by `devicePixelRatio`
+    - `native`, no changes
+- Add `CustomProperty.Context.errorContext` to support reporting errors during loading of custom properties (#1254)
+    - Use in MolViewSpec extension
+- Mesoscale Explorer: fix color & style issues
+- Remove use of deprecated SASS explicit color functions
+- Allow "Components" section to display nested components created by "Apply Action > Selection".
+
+## [v4.6.0] - 2024-08-28
+
+- Add round-caps option on tubular alpha helices
+- Fix missing Sequence UI update on state object removal (#1219)
+- Improved prmtop format support (CTITLE, %COMMENT)
+- Avoid calculating bonds for water units when `ignoreHydrogens` is on
+- Add `Water` trait to `Unit`
+- Improve entity-id coloring for structures with multiple models from the same source (#1221)
+- Wrap screenshot & image generation in a `Task`
+- AlphaFold DB: Add BinaryCIF support when fetching data
+- PDB-Dev: Add support for 4-character PDB IDs (e.g., 8ZZC)
+- Fix polymer-gap visual coloring with cartoon theme
+- Add formal-charge color theme (#328)
+- Add more coloring options to cartoon theme
+- Use `CompressionStream` Browser API when available
+- Add `pdbx_structure_determination_methodology` mmcif field and `Model` helpers
+- Fix cartoon representation not updated when secondary structure changes
+- Add Zhang-Skolnick secondary-structure assignment method which handles coarse-grained models (#49)
+- Calculate bonds for coarse-grained models
+- VolumeServer: Add `health-check` endpoint + `healthCheckPath` config prop to report service health
+- ModelServer: Add `health-check` endpoint + `healthCheckPath` config prop to report service health
+
+## [v4.5.0] - 2024-07-28
+
+- Separated postprocessing passes
+- Take into account explicit hydrogens when computing hydrogen bonds
+- Fix DoF with pixel ratios =! 1
+- Fix DoF missing transparent depth
+- Fix trackball pinch zoom and add pan
+- Fix aromatic link rendering when `adjustCylinderLength` is true
+- Change trackball animate spin speed unit to radians per second
+- Fix `mol-plugin-ui/skin/base/components/misc.scss` syntax to be in line with latest Sass syntax
+- Handle missing theme updates
+    - Fix trajectory-index color-theme not always updated (#896)
+    - Fix bond cylinders not updated on size-theme change with `adjustCylinderLength` enabled (#1215)
+- Use `OES_texture_float_linear` for SSAO when available
+
+## [v4.4.1] - 2024-06-30
+
+- Clean `solidInterior` transparent cylinders
+- Create a transformer to deflate compressed data
+- Adjust Quick Styles panel button labels
+- Improve camera interpolation code (interpolate camera rotation instead of just position)
+- Mesoscale Explorer
+    - Add `illustrative` coloring option
+    - Press 'C' to toggle between center and zoom & center on click
+    - Add entities selection description
+    - Clicking a leaf node in the right panel tree will center each instance in turn
+    - Add measurement controls to right panel
+    - Mouse left click on label with snapshot key will load snapshot
+    - Mouse hover over label with protein name highlight entities with the same name
+    - Custom ViewportSnapshotDescription with custom MarkdowAnchor
+        - \# other snapshots with a given key \[...](#key)
+        - i highlight a protein with a given NAME \[...](iNAME)
+        - g highlight a group with a given group type and group name \[...](ggrouptype.groupname)
+        - h URLs with a given link \[...](http...)
+    - Snapshot description panel window size and text can be resized and hidden with new icons
+    - Add styles controls to right panel
+    - Add viewport settings to left panel
+    - Add app info component to left panel with interactive tour and doc link
+- Fixes SSAO edge artifacts (#1122)
+    - Add `reuseOcclusion` parameter to multi-sample pass
+    - Add `blurDepthBias` parameter to occlusion pass
+    - Handle near clip in SSAO blur
+- Support reading score from B-factor in pLDDT color theme
+- Add Cel-shading support
+    - `celShaded` geometry parameter
+    - `celSteps` renderer parameter
+- Add the ability to customize the Snapshot Description component via `PluginUISpec.components.viewport.snapshotDescription`
+- Add `doNotDisposeCanvas3DContext` option to `PluginContext.dispose`
+- Remove support for density data from edmaps.rcsb.org
+
+## [v4.3.0] - 2024-05-26
+
+- Fix State Snapshots export animation (#1140)
+- Add depth of field (dof) postprocessing effect
+- Add `SbNcbrTunnels` extension for for visualizing tunnels in molecular structures from ChannelsDB (more info in [tunnels.md](./docs/docs/extensions/tunnels.md))
+- Fix edge case in minimizing RMSD transform computation
+
+## [v4.2.0] - 2024-05-04
+
+- Add emissive material support
+- Add bloom post-processing
+- MolViewSpec extension: `loadMVS` supports `keepCamera` parameter
+- Return StateTransform selectors from measurements API (addDistance, addAngle, etc.)
+- Refactor transparency rendering
+    - More uniform behavior for blended, wboit, dpoit
+    - Fix issues with text & image geometry
+- Fix render-spheres example (#1100)
+    - Wrong step size in sphere geometry boundingSphere & groupmapping
+    - Handle empty `instanceGrid` in renderer & renderable
+- Fix bond assignment from `IndexPairBonds`
+    - Can not always be cached in `ElementSetIntraBondCache`
+    - Wrong operator checks in `findPairBonds`
+- Fix SSAO artifacts (@corredD, #1082)
+- Fix bumpiness artifacts (#1107, #1084)
+
+## [v4.1.0] - 2024-03-31
+
+- Add `VolumeTransform` to translate/rotate a volume like in a structure superposition
+- Fix BinaryCIF encoder edge cases caused by re-encoding an existing BinaryCIF file
+- Fix edge-case where width/height in InputObserver are not correct
+- Fix transparency rendering fallback (#1058)
+- Fix SSAO broken when `OES_texture_float_linear` is unavailable
+- Add `normalOffset` to `external-volume` color theme
+    - This can give results similar to pymol's surface_ramp_above_mode=1
+- Add `rotation` parameter to skybox background
+
+## [v4.0.1] - 2024-02-19
+
+- Fix BinaryCIF decoder edge cases. Fixes mmCIF model export from data provided by ModelServer.
+- MolViewSpec extension: support for MVSX file format
+- Revert "require WEBGL_depth_texture extension" & "remove renderbuffer use"
+
+## [v4.0.0] - 2024-02-04
 
 - Add Mesoscale Explorer app for investigating large systems
 - [Breaking] Remove `cellpack` extension (superseded by Mesoscale Explorer app)
@@ -42,7 +277,21 @@ Note that since we don't clearly distinguish between a public and private interf
 - Add stochastic/dithered transparency to fade overlapping LODs in and out
 - Add "Automatic Detail" preset that shows surface/cartoon/ball & stick based on camera distance
 
-## [v3.44.0] - 2023-01-06
+## [v3.45.0] - 2024-02-03
+
+- Add color interpolation to impostor cylinders
+- MolViewSpec components are applicable only when the model has been loaded from MolViewSpec
+- Add `snapshotKey` and `tooltip` params to loci `LabelRepresentation`
+- Update `FocusLoci` behavior to support `snapshotKey` param
+  - Clicking a visual with `snapshotKey` will trigger that snapshot
+- Render multiline loci label tooltips as Markdown
+- `ParamDefinition.Text` updates:
+  - Support `multiline` inputs
+  - Support `placeholder` parameter
+  - Support `disableInteractiveUpdates` to only trigger updates once the control loses focus
+- Move dependencies related to the headless context from optional deps to optional peer deps
+
+## [v3.44.0] - 2024-01-06
 
 - Add new `cartoon` visuals to support atomic nucleotide base with sugar
 - Add `thicknessFactor` to `cartoon` representation for scaling nucleotide block/ring/atomic-fill visuals

data/cif-field-names/mmcif-field-names.csv

@@ -107,6 +107,7 @@ entity.id
 entity.type
 entity.src_method
 entity.pdbx_description
+entity.pdbx_parent_entity_id
 entity.formula_weight
 entity.pdbx_number_of_molecules
 entity.details
@@ -262,6 +263,7 @@ software.version
 struct.entry_id
 struct.title
 struct.pdbx_descriptor
+struct.pdbx_structure_determination_methodology
 
 struct_asym.id
 struct_asym.pdbx_blank_PDB_chainid_flag
@@ -366,18 +368,43 @@ struct_site.details
 
 struct_site_gen.id
 struct_site_gen.site_id
-struct_site_gen.pdbx_num_res
-struct_site_gen.label_comp_id
+struct_site_gen.auth_asym_id
+struct_site_gen.auth_atom_id
+struct_site_gen.auth_comp_id
+struct_site_gen.auth_seq_id
+struct_site_gen.details
+struct_site_gen.label_alt_id
 struct_site_gen.label_asym_id
+struct_site_gen.label_atom_id
+struct_site_gen.label_comp_id
 struct_site_gen.label_seq_id
 struct_site_gen.pdbx_auth_ins_code
-struct_site_gen.auth_comp_id
-struct_site_gen.auth_asym_id
-struct_site_gen.auth_seq_id
-struct_site_gen.label_atom_id
-struct_site_gen.label_alt_id
+struct_site_gen.pdbx_num_res
 struct_site_gen.symmetry
-struct_site_gen.details
+
+struct_site_keywords.site_id
+struct_site_keywords.text
+
+struct_mon_prot_cis.pdbx_id
+struct_mon_prot_cis.auth_asym_id
+struct_mon_prot_cis.auth_comp_id
+struct_mon_prot_cis.auth_seq_id
+struct_mon_prot_cis.label_alt_id
+struct_mon_prot_cis.label_asym_id
+struct_mon_prot_cis.label_comp_id
+struct_mon_prot_cis.label_seq_id
+struct_mon_prot_cis.pdbx_PDB_ins_code
+struct_mon_prot_cis.pdbx_PDB_ins_code_2
+struct_mon_prot_cis.pdbx_PDB_model_num
+struct_mon_prot_cis.pdbx_auth_asym_id_2
+struct_mon_prot_cis.pdbx_auth_comp_id_2
+struct_mon_prot_cis.pdbx_auth_ins_code
+struct_mon_prot_cis.pdbx_auth_ins_code_2
+struct_mon_prot_cis.pdbx_auth_seq_id_2
+struct_mon_prot_cis.pdbx_label_asym_id_2
+struct_mon_prot_cis.pdbx_label_comp_id_2
+struct_mon_prot_cis.pdbx_label_seq_id_2
+struct_mon_prot_cis.pdbx_omega_angle
 
 symmetry.entry_id
 symmetry.cell_setting
@@ -849,6 +876,17 @@ ma_qa_metric_local.metric_value
 ma_qa_metric_local.model_id
 ma_qa_metric_local.ordinal_id
 
+ma_qa_metric_local_pairwise.ordinal_id
+ma_qa_metric_local_pairwise.model_id
+ma_qa_metric_local_pairwise.label_asym_id_1
+ma_qa_metric_local_pairwise.label_comp_id_1
+ma_qa_metric_local_pairwise.label_seq_id_1
+ma_qa_metric_local_pairwise.label_asym_id_2
+ma_qa_metric_local_pairwise.label_comp_id_2
+ma_qa_metric_local_pairwise.label_seq_id_2
+ma_qa_metric_local_pairwise.metric_id
+ma_qa_metric_local_pairwise.metric_value
+
 ma_software_group.group_id
 ma_software_group.ordinal_id
 ma_software_group.software_id

docs/README.md

@@ -0,0 +1,11 @@
+# Mol* Developer Documentation
+
+Contributions to the documentations are highly welcome! Please make a pull request with your changes.
+
+Requires Python 3.x to build. From this directory:
+
+```
+pip install mkdocs-material
+mkdocs serve
+```
+

docs/docs/data-access-tools/convert-to-bcif.md

@@ -0,0 +1,41 @@
+# Convert CIF to BinaryCIF
+BinaryCIF is an efficient, binary flavor of the CIF format. See [specification](https://github.com/molstar/BinaryCIF) and [publication](https://doi.org/10.1371/journal.pcbi.1008247) for further details.
+
+This script reads data in CIF format and converts it lossless to a BinaryCIF file that can be read by Mol* or other 
+applications.
+
+## Example
+```sh
+node lib/commonjs/cli/cif2bcif/index.js file.cif file.bcif
+```
+
+## Usage
+| Argument | Description |
+| --- | --- |
+| `src` | Source CIF to convert (can be gzipped) |
+| `out` | Generated BinaryCIF output path |
+| `-c` | Path to optional config file |
+| `-f` | Path to optional filter file |
+
+```sh
+index.js [-h] [-c CONFIG] [-f FILTER] src out
+```
+
+### Config file
+Controls how certain columns will be encoded. This is a JSON array of instructions:
+```ts
+interface EncodingStrategyHint {
+    categoryName: string,
+    columnName: string,
+    encoding: 'pack' | 'rle' | 'delta' | 'delta-rle',
+    precision?: number
+}
+```
+Identify a particular CIF columns by its name and override the encoding by Integer Packing, Run-Length Encoding, Delta 
+Encoding, or Delta & Run-Length Encoding. You can optionally control the precision if dealing with float values.
+
+### Filter file
+Specifies which categories and columns will be written. This is a plain text file, each line represents one entry. 
+You can specify explicitly which categories or columns to include by adding `category_name` or 
+`category_name.field_name`. You can also choose to ignore some categories or columns by adding `!category_name` or 
+`!category_name.field_name`.

docs/docs/data-access-tools/create-ccd-table.md

@@ -0,0 +1,25 @@
+# Create Table from CCD
+The [Chemical Component Dictionary (CCD)](https://www.wwpdb.org/data/ccd) is as an external reference file describing 
+all residue and small molecule components found in PDB entries. The 
+[Protonation Variants Companion Dictionary (PVCD)](https://www.wwpdb.org/data/ccd) enumerates protonation variants of
+canonical amino acids.
+
+This script bundles all `chem_comp_bond` information from the CCD and the PVCD into a single file for later use.
+Optionally, it can also generate a second output file that contains all `chem_comp_atom` information.
+
+## Example
+```sh
+node --max-old-space-size=4096 lib/commonjs/cli/chem-comp-dict/create-table.js build/data/ccb.bcif -b
+```
+
+## Usage
+| Argument | Description |
+| --- | --- |
+| `out` | Generated file output path |
+| `--forceDownload`, `-f` | Force download of CCD and PVCD |
+| `--binary`, `-b` | Output as BinaryCIF |
+| `--ccaOut`, `-a` | File output path of optionally generated chem_comp_atom |
+
+```sh
+create-table.js [-h] [--forceDownload] [--binary] [--ccaOut CCAOUT] out
+```

docs/docs/data-access-tools/extract-ccd-ions.md

@@ -0,0 +1,20 @@
+# Extract Ions from CCD
+The [Chemical Component Dictionary (CCD)](https://www.wwpdb.org/data/ccd) is as an external reference file describing 
+all residue and small molecule components found in PDB entries.
+
+This script extracts all ions from the CCD and provides their names as TypeScript set.
+
+## Example
+```sh
+node --max-old-space-size=4096 lib/commonjs/cli/chem-comp-dict/create-ions.js src/mol-model/structure/model/types/ions.ts
+```
+
+## Usage
+| Argument | Description |
+| --- | --- |
+| `out` | Generated file output path |
+| `--forceDownload`, `-f` | Force download of CCD |
+
+```sh
+create-ions.js [-h] [--forceDownload] out
+```

docs/docs/data-access-tools/model-server.md

@@ -0,0 +1,119 @@
+# Model Server
+
+Provides access to molecular 1D, 2D, and 3D (sub-)structure models of molecules. Substructures are described by the 
+mol-script (MolQL) language. It has the ability to include additional data to mmCIF “on the fly”, e.g. integrate 
+primary PDB archival data from [Chemical Component Dictionary (CCD)](https://www.wwpdb.org/data/ccd), 
+[Protonation Variants Companion Dictionary (PVCD)](https://www.wwpdb.org/data/ccd) and 
+[Biologically Interesting moleculeReference Dictionary (BIRD)](https://www.wwpdb.org/data/bird). 
+
+## Example
+```sh
+node lib/commonjs/servers/model/server --sourceMap pdb-bcif '/opt/data/bcif/${id}.bcif'
+```
+
+## Usage
+| Argument | Description |
+| --- | --- |
+| `--version`, `-v` | Show program's version number and exit. |
+| `--cfg` | JSON config file path. If a property is not specified, cmd line param/OS variable/default value are used. |
+| `--printCfg` | Print current config for validation and exit. |
+| `--cfgTemplate` | Prints default JSON config template to be modified and exit. |
+| `--apiPrefix` | Specify the prefix of the API, i.e. <host>/<apiPrefix>/<API queries> |
+| `--defaultPort` | Specify the port the server is running on |
+| `--cacheMaxSizeInBytes` | Read structures are cached, this specifies the cache size, 0 for off. |
+| `--cacheEntryTimeoutMs` | Specify in ms how long to keep entries in cache. |
+| `--requestTimeoutMs` | The maximum number of ms the server spends on a request. |
+| `--queryTimeoutMs` | The maximum time the server dedicates to executing a query in ms. Does not include the time it takes to read and export the data. |
+| `--shutdownTimeoutMinutes` | Server will shut down after this amount of minutes, 0 for off. |
+| `--shutdownTimeoutVarianceMinutes` | Modifies the shutdown timer by +/- `timeoutVarianceMinutes` (to avoid multiple instances shutting at the same time) |
+| `--maxQueryManyQueries` | Maximum number of queries allowed by the query-many at a time |
+| `--defaultSource` | modifies which 'sourceMap' source to use by default |
+| `--sourceMap` | Map `id`s for a `source` to a file path. Example: `pdb-bcif '../../data/bcif/${id}.bcif'` - JS expressions can be used inside `${}`, e.g. `${id.substr(1, 2)}/${id}.mdb` Can be specified multiple times. The `SOURCE` variable (e.g. `pdb-bcif`) is arbitrary and depends on how you plan to use the server. Supported formats: cif, bcif, cif.gz, bcif.gz |
+| `--sourceMapUrl` | Same as `--sourceMap` but for URL. `--sourceMapUrl src url format` Example: `pdb-cif 'https://www.ebi.ac.uk/pdbe/entry-files/download/${id}_updated.cif' cif` Supported formats: cif, bcif, cif.gz, bcif.gz. Supported protocols: http://, https://, gs:// |
+
+```sh
+node lib/commonjs/servers/model/server [-h] [-v]
+        [--cfg CFG]
+        [--printCfg]
+        [--cfgTemplate]
+        [--apiPrefix PREFIX]
+        [--defaultPort PORT]
+        [--cacheMaxSizeInBytes CACHE_SIZE]
+        [--cacheEntryTimeoutMs CACHE_TIMEOUT]
+        [--requestTimeoutMs REQUEST_TIMEOUT]
+        [--queryTimeoutMs QUERY_TIMEOUT]
+        [--shutdownTimeoutMinutes TIME]
+        [--shutdownTimeoutVarianceMinutes VARIANCE]
+        [--maxQueryManyQueries QUERY_MANY_LIMIT]
+        [--defaultSource DEFAULT_SOURCE]
+        [--sourceMap SOURCE PATH]
+        [--sourceMapUrl SOURCE PATH SOURCE_MAP_FORMAT]
+```
+
+### Production Use
+In production, it is required to use a service that will keep the server running, such as [forever.js](https://github.com/foreverjs/forever).
+
+### Memory Issues
+Sometimes nodejs might run into problems with memory. This is usually resolved by adding the ``--max-old-space-size=8192`` parameter.
+
+### Preprocessor Example
+The preprocessor application allows addiing custom data to CIF files and/or 
+[convert CIF to BinaryCIF](./convert-to-bcif.md).
+```sh
+node lib/commonjs/servers/model/preprocess
+```
+
+### Preprocessor Usage
+| Argument | Description |
+| --- | --- |
+| `--input`, `-i` | Input filename |
+| `--outCIF`, `-oc` | Output CIF filename |
+| `--outBCIF`, `-ob` | Output BinaryCIF filename |
+| `--cfg`, `-c` | Config file path |
+| `--folderIn`, `-fin` | Convert folder |
+| `--folderOutCIF`, `-foc` | Convert folder text output |
+| `--folderOutBCIF`, `-fob` | Convert folder binary output |
+| `--folderNumProcesses`, `-fp` | Convert folder number processes |
+
+Example cfg.json:
+```ts                       
+{ 
+    "numProcesses": 1, 
+    "customProperties": { 
+        "sources": [ "wwpdb" ], 
+        "params": { 
+            "wwPDB": { 
+                "chemCompBondTablePath": "./build/data/ccb.bcif"
+            }
+        }
+    }
+}
+```
+
+### Local Mode
+The server can be run in local/file based mode using
+```sh
+node lib/commonjs/servers/model/query
+```
+
+### Custom Properties
+This feature is still in development.
+
+It is possible to provide property descriptors that transform data to internal representation and define how it should 
+be exported into one or mode CIF categories. Examples of this are located in the ``mol-model-props`` module and are 
+linked to the server in the config and ``servers/model/properties``.
+
+## From NPM
+
+```
+npm install --production molstar
+cd ./model-server 
+```
+
+(or ``node node_modules\.bin\model-server`` in Windows).
+
+The NPM package contains all the tools mentioned in the previous sections as "binaries":
+
+- ``model-server``
+- ``model-server-query``
+- ``model-server-preprocess``

docs/docs/data-access-tools/plugin-state-server.md

@@ -0,0 +1,22 @@
+# Plugin State Server
+
+Provides a simple backend for online storing and sharing of Mol* sessions used by 
+[``mol-plugin``](https://github.com/molstar/molstar/tree/master/src/mol-plugin) and 
+[``mol-state``](https://github.com/molstar/molstar/tree/master/src/mol-state) modules.
+
+## Example
+```sh
+node lib/commonjs/servers/plugin-state --workding-folder ~
+```
+
+## Usage
+| Argument | Description |
+| --- | --- |
+| `--working-folder` | Working folder path |
+| `--port` | Server port. Alternatively, use ENV variable PORT. |
+| `--api-prefix` | Server API prefix |
+| `--max-states` | Maximum number of states to save |
+
+```sh
+node lib/commonjs/servers/plugin-state [-h] --working-folder WORKING_FOLDER [--port PORT] [--api-prefix API_PREFIX] [--max-states MAX_STATES]
+```

docs/docs/data-access-tools/volume-server/examples.md

@@ -1,9 +1,9 @@
-Zika Virus
-==========
+# VolumeServer Examples
+
+## Zika Virus
 
 ![Zika Virus](img/zika_downsampled.png)
 
-1TQN
-====
+## 1TQN
 
 ![1tqn](img/1tqn_downsampled.png)

docs/docs/data-access-tools/volume-server/how-it-works.md

@@ -1,5 +1,4 @@
-How it works
-============
+## VolumeServer: How it works
 
 This document provides a high level overview of how the DensityServer works.
 

docs/docs/data-access-tools/volume-server/index.md

@@ -0,0 +1,126 @@
+# VolumeServer
+
+## What is VolumeServer
+
+Provides near-instantaneous access to volumetric data including density maps (for instance, from X-ray crystallography 
+or cryo-electron microscopy experiments), spatial distribution data, output from electrostatic calculations. It works by
+utilizing adaptive downsampling (similar to how Google Earth works). 
+
+It uses the text based CIF and BinaryCIF formats to deliver the data to the client. 
+
+For quick info about the benefits of using the server, check out the [examples](examples.md).
+
+## Installing and Running
+
+Requires nodejs 8+.
+
+### From GitHub
+
+```
+git clone https://github.com/molstar/molstar
+npm install
+```
+
+Afterwards, build the project source:
+
+```
+npm run build-tsc
+```
+
+and run the server by 
+
+```
+node lib/commonjs/servers/volume/server
+```
+
+### From NPM
+
+```
+npm install --production molstar
+./volume-server 
+```
+
+(or ``node node_modules\.bin\volume-server`` in Windows).
+
+The NPM package contains all the tools mentioned here as "binaries":
+
+- ``volume-server``
+- ``volume-server-pack``
+- ``volume-server-query``
+
+
+#### Production use
+
+In production it is required to use a service that will keep the server running, such as [forever.js](https://github.com/foreverjs/forever).
+
+
+#### Memory issues
+
+Sometimes nodejs might run into problems with memory. This is usually resolved by adding the ``--max-old-space-size=8192`` parameter.
+
+
+### Preparing the Data
+
+For the server to work, CCP4/MAP (models 0, 1, 2 are supported) input data need to be converted into a custom block format. 
+To achieve this, use the ``pack`` application (``node lib/commonjs/servers/volume/pack`` or ``volume-server-pack`` binary from the NPM package).
+
+### Local Mode
+
+The program  ``lib/commonjs/servers/volume/query`` (``volume-server-query`` in NPM package) can be used to query the data without running a http server.
+
+### Navigating the Source Code
+
+The source code is split into 2 mains parts: ``pack`` and ``server``:
+
+- The ``pack`` part provides the means of converting CCP4 files into the internal block format.
+- The ``server`` includes
+  - ``query``: the main part of the server that handles a query. ``execute.ts`` is the "entry point".
+  - ``algebra``: linear, "coordinate", and "box" algebra provides the means for calculations necessary to concent a user query into a menaningful response.
+  - API wrapper that handles the requests.
+
+## Consuming the Data 
+
+
+The data can be consumed in any (modern) browser using the [ciftools library](https://github.com/molstar/ciftools) (or any other piece of code that can read text or binary CIF).
+
+The [Data Format](./response-data-format.md) document gives a detailed description of the server response format.
+
+As a reference/example of the server usage is available in Mol* ``mol-plugin`` module.
+
+## Hosting the server
+
+### Example
+
+```sh
+node lib/commonjs/servers/volume/server --idMap x-ray '/opt/data/xray/${id}.mdb'
+```
+
+### Usage
+| Argument= | Description |
+| --- | --- |
+| `--cfg` | JSON config file path. If a property is not specified, cmd line param/OS variable/default value are used. |
+| `--printCfg` | Print current config for validation and exit. |
+| `--cfgTemplate` | Prints default JSON config template to be modified and exit. |
+| `--apiPrefix` | Specify the prefix of the API, i.e. <host>/<apiPrefix>/<API queries> |
+| `--defaultPort` | Specify the port the server is running on |
+| `--shutdownTimeoutMinutes` | Server will shut down after this amount of minutes, 0 for off. |
+| `--shutdownTimeoutVarianceMinutes` | Modifies the shutdown timer by +/- `timeoutVarianceMinutes` (to avoid multiple instances shutting at the same time) |
+| `--idMap` | Map `id`s for a `type` to a file path. Example: `x-ray '../../data/mdb/xray/${id}-ccp4.mdb'` - JS expressions can be used inside `${}`, e.g. `${id.substr(1, 2)}/${id}.mdb` - Can be specified multiple times. - The `TYPE` variable (e.g. `x-ray`) is arbitrary and depends on how you plan to use the server. By default, Mol* Viewer uses `x-ray` and `em`, but any particular use case may vary. - If using URL, it can be http://, https://, gs:// or file:// protocol.|
+| `--maxRequestBlockCount` | Maximum number of blocks that could be read in 1 query. This is somewhat tied to the ``maxOutputSizeInVoxelCountByPrecisionLevel`` in that the `<maximum number of voxel> = maxRequestBlockCount * <block size>^3`. The default block size is 96 which corresponds to 28,311,552 voxels with 32 max blocks. |
+| `--maxFractionalBoxVolume` | The maximum fractional volume of the query box (to prevent queries that are too big). |
+| `--maxOutputSizeInVoxelCountByPrecisionLevel` | What is the (approximate) maximum desired size in voxel count by precision level - Rule of thumb: `<response gzipped size>` in `[<voxel count> / 8, <voxel count> / 4]`. The maximum number of voxels is tied to maxRequestBlockCount. |
+
+```sh
+node lib/commonjs/servers/volume/server [-h] [-v]
+        [--cfg CFG]
+        [--printCfg] 
+        [--cfgTemplate]
+        [--apiPrefix PREFIX]
+        [--defaultPort PORT]
+        [--shutdownTimeoutMinutes TIME]
+        [--shutdownTimeoutVarianceMinutes VARIANCE] 
+        [--idMap TYPE PATH]
+        [--maxRequestBlockCount COUNT] 
+        [--maxFractionalBoxVolume VOLUME]
+        [--maxOutputSizeInVoxelCountByPrecisionLevel LEVEL [LEVEL ...]]
+```

docs/docs/data-access-tools/volume-server/response-data-format.md

@@ -1,10 +1,8 @@
-Data Format
-===========
+# VolumeServer: Response Data Format
 
 This document describes the CIF categories and fields generated by the server.
 
-Query info
-----------
+## Query info
 
 The reponse always contains a data block called ``SERVER`` with this format:
 
@@ -28,8 +26,7 @@ _density_server_result.query_box_b[1]     35.737
 _density_server_result.query_box_b[2]     32.037001 
 ```
 
-Query data
-----------
+## Query data
 
 If the query completed successfully with a non-empty result the response will contain one or more data blocks that correpond to the
 "channels" present in the data (e.g. for x-ray data there will be ``2Fo-Fc`` and ``Fo-Fc``) channels.
@@ -41,6 +38,7 @@ data_2FO-FC
 #
 _volume_data_3d_info.name                         2Fo-Fc 
 ```
+
 ### Axis order
 
 Axis order determines the order of axes of ``origin``, ``dimensions`` and ``sample_count`` fields. It also specifies

docs/docs/extensions/mvs/index.md

@@ -0,0 +1,3 @@
+# MolViewSpec
+
+Please see the [standalone MolViewSpec documentation](https://molstar.org/mol-view-spec-docs/).

docs/docs/extensions/mvs/integration-examples.html

@@ -0,0 +1,112 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <!-- Replace "latest" by the specific version you want to use, e.g. "4.0.0" -->
+    <script src="https://cdn.jsdelivr.net/npm/molstar@latest/build/viewer/molstar.js"></script>
+    <!-- Replace "latest" by the specific version you want to use, e.g. "4.0.0" -->
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/molstar@latest/build/viewer/molstar.css" />
+</head>
+
+<body>
+    <h1>Integration of Mol* with MolViewSpec Extension</h1>
+    <p>
+        This page demonstrates several methods to integrate Mol* Viewer in a web page and use MolViewSpec functionality.
+        See the source HTML to see the actual code.
+    </p>
+
+
+    <h2>Method 1: Get MVS view from a server and pass to the viewer</h2>
+    <p>
+        The recommended method is to serve the MVS view files by your server (either as static files or generated by the
+        server on-demand) and call the <code>loadMvsFromUrl</code> method to retrieve and load them.
+        This example uses a MVS view file from the address specified in the <code>sourceUrl</code> variable.
+        If the MVS view file contains relative references, they will be resolved as relative to <code>sourceUrl</code>.
+    </p>
+
+    <div id="viewer1" style="position: relative; width: 500px; height: 500px;"></div>
+    <script>
+        const sourceUrl = 'https://raw.githubusercontent.com/molstar/molstar/master/examples/mvs/1h9t_domain_labels.mvsj';
+        molstar.Viewer.create('viewer1', { layoutIsExpanded: false, layoutShowControls: false })
+            .then(viewer => viewer.loadMvsFromUrl(sourceUrl, 'mvsj'));
+    </script>
+
+
+    <p>
+        A variation of this method uses <code>molstar.PluginExtensions.mvs.loadMVS</code> instead of
+        <code>loadMvsFromUrl</code> and allows replacing the MVS view after it has been loaded.
+    </p>
+
+    <div id="viewer1b" style="position: relative; width: 500px; height: 500px;"></div>
+    <button onclick="loadView1();">View 1</button>
+    <button onclick="loadView2();">View 2</button>
+    <script>
+        let theViewer;
+        function load(viewer, url, replace) {
+            fetch(url)
+                .then(response => response.text())
+                .then(text => molstar.PluginExtensions.mvs.MVSData.fromMVSJ(text))
+                .then(mvsData => molstar.PluginExtensions.mvs.loadMVS(viewer.plugin, mvsData, { sourceUrl: url, sanityChecks: true, replaceExisting: replace }));
+        }
+        function loadView1() {
+            load(theViewer, 'https://raw.githubusercontent.com/molstar/molstar/master/examples/mvs/1cbs.mvsj', true);
+        }
+        function loadView2() {
+            load(theViewer, 'https://raw.githubusercontent.com/molstar/molstar/master/examples/mvs/1cbs-focus.mvsj', true);
+        }
+        molstar.Viewer.create('viewer1b', { layoutIsExpanded: false, layoutShowControls: false })
+            .then(viewer => {
+                theViewer = viewer;
+                loadView1();
+            });
+    </script>
+
+
+    <h2>Method 2: Construct MVS view on frontend and pass to the viewer</h2>
+    <p>
+        Another option is to utilize the MVS builder provided by the extension to build the view on frontend and then
+        pass it to the viewer. This example builds the view in plain JavaScript, directly in a &lt;script&gt; tag in
+        HTML. However, for a better developer experience consider writing the code in TypeScript.
+        If the built MVS view contains relative references, they will be resolved as relative to the URL of this HTML
+        page.
+    </p>
+
+    <div id="viewer2" style="position: relative; width: 500px; height: 500px;"></div>
+    <script>
+        // Build an ad-hoc MVS view
+        const builder = molstar.PluginExtensions.mvs.MVSData.createBuilder();
+        const structure = builder
+            .download({ url: 'https://www.ebi.ac.uk/pdbe/entry-files/1cbs.bcif' })
+            .parse({ format: 'bcif' })
+            .modelStructure({});
+        structure
+            .component({ selector: 'polymer' })
+            .representation({ type: 'cartoon' })
+            .color({ color: 'green' });
+        structure
+            .component({ selector: 'ligand' })
+            .label({ text: 'Retinoic acid' })
+            .focus({})
+            .representation({ type: 'ball_and_stick' })
+            .color({ color: '#cc3399' });
+        const mvsData = builder.getState();
+
+        // Initialize viewer and load MVSJ
+        const mvsj = molstar.PluginExtensions.mvs.MVSData.toMVSJ(mvsData);
+        molstar.Viewer.create('viewer2', { layoutIsExpanded: false, layoutShowControls: false })
+            .then(viewer => viewer.loadMvsData(mvsj, 'mvsj'));
+
+        // // Alternative initialization and loading (avoids encoding and again decoding the data, allows changing the view by using `replaceExisting: true`):
+        // molstar.Viewer.create('viewer2', { layoutIsExpanded: false, layoutShowControls: false })
+        //     .then(viewer => molstar.PluginExtensions.mvs.loadMVS(viewer.plugin, mvsData, { sourceUrl: undefined, sanityChecks: true, replaceExisting: false }));
+    </script>
+
+
+    <p>
+        Again, there is variation with using <code>molstar.PluginExtensions.mvs.loadMVS</code> instead of
+        <code>loadMvsData</code>.
+    </p>
+
+</body>
+
+</html>

docs/docs/extensions/tunnels.md

@@ -0,0 +1,118 @@
+# Tunnel Visualization Extension
+This documentation outlines the usage of the Mol* extension for visualizing tunnels in molecular structures. The extension integrates with Mol* to render 3D representations of tunnels using specified data sources and properties.
+
+The extension is a key component in ChannelsDB (https://channelsdb2.biodata.ceitec.cz/), enabling users to visualize tunnels within molecules directly from the database. While it is used with ChannelsDB, users can also input their own data or connect to different databases, ensuring versatility across various research environments.
+
+## Data Types
+The primary data types involved in tunnel visualization are:
+
+### Tunnel
+A Tunnel object contains the actual tunnel data necessary for visualization. It consists of:
+
+- `data`: An array of `Profile` objects that describe the tunnel at various points.
+- `props`: Properties such as the tunnel's type, ID, and optional labels or descriptions.
+
+### Profile
+A `Profile` object in a `Tunnel` holds detailed geometric and physical properties of a tunnel at specific points along its length. These properties include:
+
+- `Charge`: The electric charge at a specific point in the tunnel.
+- `Radius`: The overall radius of the tunnel at this point.
+- `FreeRadius`: The radius of the tunnel not obstructed by any molecular elements.
+- `T`: Temperature factor or a similar property related to the point.
+- `Distance`: Distance along the tunnel's path from the start.
+- `X`, `Y`, `Z`: Coordinates of the point in 3D space.
+
+These profiles are crucial for understanding the physical and chemical environment inside the tunnel, allowing for detailed analysis and visualization.
+
+Example:
+```json
+"Profile": [
+    {
+        "Radius": 1.49,
+        "FreeRadius": 1.49,
+        "T": 0,
+        "Distance": 0,
+        "X": -19.152,
+        "Y": -22.654,
+        "Z": -13.034,
+        "Charge": 0
+    },
+    {
+        "Radius": 1.524,
+        "FreeRadius": 1.524,
+        "T": 0.00625,
+        "Distance": 0.087,
+        "X": -19.162,
+        "Y": -22.596,
+        "Z": -12.969,
+        "Charge": 0
+    },
+    {
+        "Radius": 1.56,
+        "FreeRadius": 1.56,
+        "T": 0.0125,
+        "Distance": 0.174,
+        "X": -19.171,
+        "Y": -22.539,
+        "Z": -12.905,
+        "Charge": 0
+    }
+]
+```
+## Transformers Usage
+The extension uses several transformations to process and visualize tunnel data:
+
+### Tunnels Data Transformer
+- `Purpose`: Converts a collection of Tunnel data into a state object.
+- `Usage`:
+    ```typescript
+    update.toRoot().apply(TunnelsFromRawData, { data: tunnels });
+    ```
+
+### Tunnel Data Provider
+- `Purpose`: Converts single Tunnel data into a state object for individual processing.
+- `Usage`:
+    ```typescript
+    update.toRoot().apply(TunnelFromRawData, {
+        data: {
+            data: tunnel.Profile,
+            props: { id: tunnel.Id, type: tunnel.Type }
+        }
+    });
+    ```
+
+### Tunnel Shape Provider
+- `Purpose`: Provides the shapes for rendering the tunnel based on WebGL context and shape parameters.
+- `Usage`:
+    ```typescript
+    update.apply(TunnelShapeProvider, {
+        webgl,
+    }).apply(StateTransforms.Representation.ShapeRepresentation3D);
+    ```
+
+## Visualization Examples
+To help users understand how to use these transformations in practice, include detailed examples:
+
+### Visualizing Multiple Tunnels
+This example ([runVisualizeTunnels](../../../src/extensions/sb-ncbr/tunnels/examples.ts#L19)) demonstrates how to visualize multiple tunnels from a fetched dataset.
+```typescript
+update.toRoot()
+        .apply(TunnelsFromRawData, { data: tunnels })
+        .apply(SelectTunnel)
+        .apply(TunnelShapeProvider, { webgl })
+        .apply(StateTransforms.Representation.ShapeRepresentation3D);
+```
+
+### Visualizing a Single Tunnel
+This example ([runVisualizeTunnel](../../../src/extensions/sb-ncbr/tunnels/examples.ts#L46)) shows how to visualize a single tunnel.
+```typescript
+update.toRoot()
+        .apply(TunnelFromRawData, {
+            data: {
+                data: tunnel.Profile,
+                props: { id: tunnel.Id, type: tunnel.Type }
+            }
+        })
+        .apply(TunnelShapeProvider, { webgl })
+        .apply(StateTransforms.Representation.ShapeRepresentation3D);
+```

docs/docs/index.md

@@ -0,0 +1,43 @@
+# Installation
+
+## NPM Package
+
+```
+yarn add molstar
+```
+
+or
+
+```
+npm install molstar
+```
+
+Mol* code can then be imported from the ``molstar/lib/...`` namespace, e.g.
+
+```ts
+import { PluginContext } from 'molstar/lib/mol-plugin/context';
+```
+
+## Clone from GitHub
+
+
+```
+git clone https://github.com/molstar/molstar.git
+cd molstar
+npm install
+npm build
+```
+
+--------------------
+
+For a watch task to automatically rebuild the source code on changes, run
+
+```
+npm run watch
+```
+
+or if working just with the Viewer app for better performance
+
+```
+npm run watch-viewer
+```

docs/docs/misc/exporting-components.md

@@ -0,0 +1,59 @@
+# Exporting components
+
+Export components data can be useful to reproduce the same view in a different visualization software.
+To do that, one would need to loop over all components, extract its selection (for example by using atom indices) and its representations (type, coloring and sizing).
+
+### Getting assets / molecular files
+
+```js
+for (const { asset, file } of plugin.managers.asset.assets) {
+  const isFile = asset.asset.kind === 'url'
+  console.log(asset.asset.id)
+  console.log(isFile)
+  const data = await file.arrayBuffer()
+}
+```
+
+### Getting components per structure
+
+```js
+import { PluginStateObject as PSO } from 'molstar/lib/mol-plugin-state/objects';
+//...
+
+const componentManager = plugin.managers.structure.component;
+for (const structure of componentManager.currentStructures) {
+  if (!structure.properties) {
+      continue;
+  }
+  const cell = plugin.state.data.select(structure.properties.cell.transform.ref)[0];
+  if (!cell || !cell.obj) {
+    continue;
+  }
+  const structureData = (cell.obj as PSO.Molecule.Structure).data;
+  for (const component of structure.components) {
+    if (!component.cell.obj) {
+      continue;
+    }
+    // For each component in each structure, display the content of the selection
+    Structure.eachAtomicHierarchyElement(component.cell.obj.data, {
+      atom: location => console.log(location.element)
+    });
+    for (const rep of component.representations) {
+      // For each representation of the component, display its type
+      console.log(rep.cell?.transform?.params?.type?.name)
+
+      // Also display the color for each atom
+      const colorThemeName = rep.cell.transform.params?.colorTheme.name;
+      const colorThemeParams = rep.cell.transform.params?.colorTheme.params;
+      const theme = plugin.representation.structure.themes.colorThemeRegistry.create(
+        colorThemeName || '',
+        { structure: structureData },
+        colorThemeParams
+      ) as ColorTheme<typeof colorThemeParams>;
+      Structure.eachAtomicHierarchyElement(component.cell.obj.data, {
+        atom: loc => console.log(theme.color(loc, false))
+      });
+    }
+  }
+}
+```

docs/docs/misc/interesting-pdb-entries.md

@@ -1,3 +1,5 @@
+# Interesting PDB Entries
+
 * Cyclic polymers (1sfi, 6dny, 1HVZ)
 * B-DNA (1bna)
 * Missing carbonyl oxygen (1gfl)
@@ -20,7 +22,7 @@
 * Discontinuous chains, i.e. gaps in the sequence (3sn6)
 * Lots of sheets (1cbs)
 * DNA (2np2, 1d66)
-* C-alpha only (2rcj)
+* C-alpha only (2RCJ, 6ZIG, 5AJ2)
 * Not cyclic, but termini are backbone-only and within distance but seqIds are not compatible (6SW3)
 * Close backbone atoms but not linked (e.g. 4HIV)
 * Non-standard residues
@@ -44,7 +46,6 @@
     * TA1 (e.g. 1JFF) - many fused rings (incl. a 8-member rings)
     * BPA (e.g. 1JDG) - many fused rings
     * CLR (e.g. 3GKI) - four fused rings
-
-Assembly symmetries
-* 5M30 (Assembly 1, C3 local and pseudo)
-* 1RB8 (Assembly 1, I global)
+* Assembly symmetries
+    * 5M30 (Assembly 1, C3 local and pseudo)
+    * 1RB8 (Assembly 1, I global)

docs/docs/plugin/custom-library.md

@@ -0,0 +1,193 @@
+# Building a Custom Library
+
+This page goes over creating a custom Mol\* based library usable inside a `<script>` tag in an HTML page.
+
+## Setup
+
+- Create a new npm/yarn package
+- Install `molstar` and `esbuild` packages
+
+```
+mkdir molstar-lib
+cd molstar-lib
+npm init
+npm install molstar
+npm install esbuild --save-dev
+```
+
+## Example Library Code
+
+Create new file `src/index.ts` (or `.js` if you don't want to use TypeScript):
+
+```ts
+import { DefaultPluginSpec, PluginSpec } from 'molstar/lib/mol-plugin/spec';
+import { PluginContext } from 'molstar/lib/mol-plugin/context';
+
+export async function initViewer(element: string | HTMLDivElement, options?: { spec?: PluginSpec }) {
+    const parent = typeof element === 'string' ? document.getElementById(element)! as HTMLDivElement : element;
+    const canvas = document.createElement('canvas') as HTMLCanvasElement;
+    parent.appendChild(canvas);
+
+    const spec = options?.spec ?? DefaultPluginSpec();
+
+    const plugin = new PluginContext(spec);
+    await plugin.init();
+
+    plugin.initViewer(canvas, parent);
+
+    return plugin;
+}
+
+export async function loadStructure(
+    plugin: PluginContext,
+    url: string,
+    options?: { format?: string, isBinary?: boolean }
+) {
+    const data = await plugin.builders.data.download(
+        { url, isBinary: options?.isBinary }
+    );
+    const trajectory = await plugin.builders.structure.parseTrajectory(
+        data,
+        options?.format ?? 'mmcif' as any
+    );
+    const preset = await plugin.builders.structure.hierarchy.applyPreset(trajectory, 'default');
+    return preset;
+}
+```
+
+## Building the Library
+
+Add new commands to the `scripts` section of the `package.json` file
+
+```json
+"scripts": {
+  "build": "esbuild src/index.ts --bundle --outfile=./build/js/index.js --global-name=molstarLib",
+  "watch": "esbuild src/index.ts --bundle --outfile=./build/js/index.js --global-name=molstarLib --watch"
+}
+```
+
+and run the command `npm run build` (or `watch` for interactive development experience). This will create `build/js/index.js` file which can be imported with a `<script>` tag and the exported functions called view the `molstarLib` prefix (you can customize this parameter).
+
+## Using the Library
+
+Create file `build/index.html`:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
+        <title>Mol* Library Example</title>
+    </head>
+    <style>
+        #viewer {
+            position: absolute;
+            width: 800px;
+            height: 600px;
+        }
+    </style>
+    <script type="text/javascript" src="./js/index.js"></script>
+    <body>
+        <div id="viewer"></div>
+        <script type="text/javascript">
+            async function init() {1
+                const plugin = await molstarLib.initViewer("viewer");
+                await molstarLib.loadStructure(
+                    plugin,
+                    "https://models.rcsb.org/4hhb.bcif",
+                    { isBinary: true }
+                );
+            }
+            init();
+        </script>
+    </body>
+</html>
+```
+
+After opening `index.html` in a browser, you should see 
+
+![lib-example](lib-example.png)
+
+## Using Mol* React UI
+
+The above example does not make use of the default Mol\* React UI and any UI components are therefore the author's responsibility. The below examples show how to (re)use the Mol\* React UI.
+
+- Create `src/ui.tsx`:
+```tsx
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+
+import { DefaultPluginUISpec, PluginUISpec } from 'molstar/lib/mol-plugin-ui/spec';
+import { PluginUIContext } from 'molstar/lib/mol-plugin-ui/context';
+import { Plugin } from 'molstar/lib/mol-plugin-ui/plugin';
+
+export async function initViewerUI(element: string | HTMLDivElement, options?: { spec?: PluginUISpec }) {
+    const parent = typeof element === 'string' ? document.getElementById(element)! as HTMLDivElement : element;
+    const spec = { ...DefaultPluginUISpec(), ...options?.spec };
+    const plugin = new PluginUIContext(spec);
+    await plugin.init();
+
+    createRoot(parent).render(<Plugin plugin={plugin} />)
+
+    return plugin;
+}
+
+export async function loadStructure(plugin: PluginUIContext, url: string, options?: { format?: string, isBinary?: boolean }) {
+    const data = await plugin.builders.data.download({ url, isBinary: options?.isBinary });
+    const trajectory = await plugin.builders.structure.parseTrajectory(data, options?.format ?? 'mmcif' as any);
+    await plugin.builders.structure.hierarchy.applyPreset(trajectory, 'default');
+}
+```
+- Create `src/style.scss`:
+```scss
+@import '../node_modules/molstar/lib/mol-plugin-ui/skin/light.scss';
+```
+- Create `build/ui.html`:
+```html
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
+        <title>Mol* UI Library Example</title>
+    </head>
+    <link rel="stylesheet" type="text/css" href="css/style.css" />
+    <style>
+        #viewer {
+            position: absolute;
+            inset: 0;
+        }
+    </style>
+    <script type="text/javascript" src="./js/ui.js"></script>
+    <body>
+        <div id="viewer"></div>
+        <script type="text/javascript">
+            async function init() {
+                const plugin = await molstarLib.initViewerUI("viewer", {
+                    spec: {
+                        layout: {
+                            initial: {
+                                isExpanded: true,
+                                showControls: true,
+                            },
+                        },
+                    }
+                });
+                await molstarLib.loadStructure(plugin, "https://models.rcsb.org/4hhb.bcif", { isBinary: true });
+            }
+            init();
+        </script>
+    </body>
+</html>
+```
+
+- Install `sass`: `npm install sass -save-dev` (or use [`esbuild` plugin](https://www.npmjs.com/package/esbuild-sass-plugin) and `import` the scss file in `ui.tsx`)
+- Add scripts to `package.json`:
+```json
+"build-ui": "esbuild src/ui.tsx --bundle --outfile=./build/js/ui.js --global-name=molstarLib",
+"css": "sass src/style.scss ./build/css/style.css"
+```
+- Run `npm run build-ui` and `npm run css` (skip if using `esbuild-sass-plugin`)
+- Opening `build/ui.html`:
+![ui-example](ui-example.png)

docs/docs/plugin/data-state.md

@@ -23,7 +23,7 @@ interface Snapshot {
 
 When defining the state object, all components are optional, i.e., it is possible to define just the ``data`` component.
 
-Example state is available [here](example-state.json). In the plugin, it is possible to create and load these objects using ``Download JSON`` 
+Example state is available [here](./example-state.json). In the plugin, it is possible to create and load these objects using ``Download JSON`` 
 and ``Open JSON`` buttons in the ``State Snapshots`` section.
 
 # State Tree
@@ -69,7 +69,7 @@ interface Transform.Props {
 }
 ```
 
-"Built-in" data state transforms and description of their parameters are defined in ``mol-plugin/state/transforms``. Behavior transforms are defined in ``mol-plugin/behavior``. Auto-generated documentation for the transforms is also [available](transforms.md).
+"Built-in" data state transforms and description of their parameters are defined in ``mol-plugin/state/transforms``. Behavior transforms are defined in ``mol-plugin/behavior``.
 
 # Animation State
 

docs/docs/plugin/examples.md

@@ -0,0 +1,3 @@
+# Plugin Examples
+
+Refer to Mol* [Apps](https://github.com/molstar/molstar/tree/master/src/apps) and [Examples](https://github.com/molstar/molstar/tree/master/src/examples).

docs/docs/plugin/instance.md

@@ -0,0 +1,274 @@
+# Creating Plugin Instance
+
+
+## Intro
+
+What is a plugin? A plugin is a collection of modules that provide functionality to the `Mol*` UI. The plugin is responsible for managing the state of the viewer, internal and user interactions. It has been a previous point of confusion for new users of `Mol*` to associate the __viewer__ part of the library with what is further referred to as the __plugin__. These two are closely connected in the `molstar-plugin-ui` module, which is the user-facing part of the library and ultimately provides the viewer, but they are ultimately distinct. 
+
+
+It is recommended that you inspect the general class structure of [`PluginInitWrapper`](https://github.com/molstar/molstar/blob/6edbae80db340134341631f669eec86543a0f1a8/src/mol-plugin-ui/plugin.tsx#L41), [`PluginUIContext`](https://github.com/molstar/molstar/blob/6edbae80db340134341631f669eec86543a0f1a8/src/mol-plugin-ui/context.ts#L12) and [`PluginUIComponent`](https://github.com/molstar/molstar/blob/6edbae80db340134341631f669eec86543a0f1a8/src/mol-plugin-ui/base.tsx#L16) to better understand the flow of data and events in the plugin. 
+A passing analogy is that a [ `PluginContext` ](https://github.com/molstar/molstar/blob/6edbae80db340134341631f669eec86543a0f1a8/src/mol-plugin/context.ts#L71) is the engine that powers computation, rendering, events and subscriptions inside the molstar UI. All UI components depend on `PluginContext`. 
+
+
+
+There are 4 basic ways of instantiating the Mol* plugin.
+
+## ``Viewer`` wrapper
+
+- The most basic usage is to use the ``Viewer`` wrapper. This is best suited for use cases that do not require much custom behavior and are mostly about just displaying a structure.
+- See ``Viewer`` class is defined in [src/apps/viewer/app.ts](https://github.com/molstar/molstar/blob/master/src/apps/viewer/app.ts) for available methods and options.
+
+Example usage without using WebPack:
+
+```HTML
+<style>
+    #app {
+        position: absolute;
+        left: 100px;
+        top: 100px;
+        width: 800px;
+        height: 600px;
+    }
+</style>
+<!-- 
+    molstar.js and .css are obtained from
+    - the folder build/viewer after cloning and building the molstar package 
+    - from the build/viewer folder in the Mol* NPM package
+-->
+<link rel="stylesheet" type="text/css" href="molstar.css" />
+<script type="text/javascript" src="./molstar.js"></script>
+
+<div id="app"></div>
+
+<script type="text/javascript">
+    molstar.Viewer.create('app', {
+        layoutIsExpanded: false,
+        layoutShowControls: false,
+        layoutShowRemoteState: false,
+        layoutShowSequence: true,
+        layoutShowLog: false,
+        layoutShowLeftPanel: true,
+
+        viewportShowExpand: true,
+        viewportShowSelectionMode: false,
+        viewportShowAnimation: false,
+
+        pdbProvider: 'rcsb',
+        emdbProvider: 'rcsb',
+    }).then(viewer => {
+        viewer.loadPdb('7bv2');
+        viewer.loadEmdb('EMD-30210', { detail: 6 });
+    });
+</script>
+```
+
+When using WebPack (or possibly other build tool) with the Mol* NPM package installed, the viewer class can be imported using 
+
+```ts
+import { Viewer } from 'molstar/build/viewer/molstar'
+
+function initViewer(target: string | HTMLElement) {
+    return new Viewer(target, { /* options */})
+}
+```
+
+## ``PluginContext`` with built-in React UI
+
+- For more customization options it is possible to use the [``PluginContext``](https://github.com/molstar/molstar/blob/master/src/mol-plugin/context.ts) directly.
+- When creating the plugin instance it is possible to customize the [``PluginSpec``](https://github.com/molstar/molstar/blob/master/src/mol-plugin/spec.ts).
+- The default [``PluginSpec``](https://github.com/molstar/molstar/blob/master/src/mol-plugin/spec.ts) is available [here](https://github.com/molstar/molstar/blob/master/src/mol-plugin/spec.ts).
+- [``PluginConfig``](https://github.com/molstar/molstar/blob/master/src/mol-plugin/config.ts) object provides additional customization options.
+- See the [Viewer State Management](viewer-state.md) section for more information on customizing things like background.
+- See the [Data State Management](data-state.md) section for more information on build the state.
+
+```ts
+import { DefaultPluginUISpec, PluginUISpec } from 'molstar/lib/mol-plugin-ui/spec';
+import { createPluginUI } from 'molstar/lib/mol-plugin-ui';
+import { renderReact18 } from 'molstar/lib/mol-plugin-ui/react18';
+import { PluginConfig } from 'molstar/lib/mol-plugin/config';
+
+const MySpec: PluginUISpec = {
+    ...DefaultPluginUISpec(),
+    config: [
+        [PluginConfig.VolumeStreaming.Enabled, false]
+    ]
+}
+
+async function createPlugin(parent: HTMLElement) {
+    const plugin = await createPluginUI({
+      target: parent,
+      spec: MySpec,
+      render: renderReact18
+    });
+
+    const data = await plugin.builders.data.download({ url: '...' }, { state: { isGhost: true } });
+    const trajectory = await plugin.builders.structure.parseTrajectory(data, format);
+    await this.plugin.builders.structure.hierarchy.applyPreset(trajectory, 'default');
+
+    return plugin;
+}
+
+createPlugin(document.getElementById('app')!); // app is a <div> element with position: relative
+```
+
+To use the plugin (with the React UI) inside another React app:
+
+A single-plugin setup is shown the example below. In order to initialize multiple
+plugins, each with its own context and viewport, some extra steps are required (docs section to be added).
+
+```ts
+import { useEffect, createRef } from "react";
+import { createPluginUI } from "molstar/lib/mol-plugin-ui";
+import { renderReact18 } from "molstar/lib/mol-plugin-ui/react18";
+import { PluginUIContext } from "molstar/lib/mol-plugin-ui/context";
+/*  Might require extra configuration,
+see https://webpack.js.org/loaders/sass-loader/ for example.
+create-react-app should support this natively. */
+import "molstar/lib/mol-plugin-ui/skin/light.scss";
+
+declare global {
+  interface Window {
+    molstar?: PluginUIContext;
+  }
+}
+
+
+export function MolStarWrapper() {
+  const parent = createRef<HTMLDivElement>();
+
+  // In debug mode of react's strict mode, this code will
+  // be called twice in a row, which might result in unexpected behavior.
+  useEffect(() => {
+    async function init() {
+        window.molstar = await createPluginUI({
+          target: parent.current as HTMLDivElement,
+          render: renderReact18
+        });
+
+        const data = await window.molstar.builders.data.download(
+          { url: "https://files.rcsb.org/download/3PTB.pdb" }, /* replace with your URL */
+          { state: { isGhost: true } }
+        );
+        const trajectory =
+          await window.molstar.builders.structure.parseTrajectory(data, "pdb");
+        await window.molstar.builders.structure.hierarchy.applyPreset(
+          trajectory,
+          "default"
+        );
+    }
+    init();
+    return () => {
+      window.molstar?.dispose();
+      window.molstar = undefined;
+    };
+  }, []);
+
+  return <div ref={parent} style={{ width: 640, height: 480 }}/>;
+}
+
+```
+
+
+Furthermore, if it is desirable in your project to use the `molstar`'s React UI components, but you wish to alter or rearrange the layout, you should take a look at the signatures of [ `PluginUIComponent` ](https://github.com/molstar/molstar/blob/6edbae80db340134341631f669eec86543a0f1a8/src/mol-plugin-ui/base.tsx#L16) which every "control" subclasses. 
+
+
+[ `SequenceView` ](https://github.com/molstar/molstar/blob/6edbae80db340134341631f669eec86543a0f1a8/src/mol-plugin-ui/sequence.tsx#L221C4-L221C4), for example, can be used separately from the `PluginUI`. Yet you would need to pass the `PluginUIContext` to it in order for it to observe the changes in the state of the plugin. This can be done via a `PluginContextContainer`:
+```typescript
+// your_app.plugin: PluginUIContext
+...
+<div className="your_custom_ui">
+  <PluginContextContainer plugin={your_app.plugin}>
+    <SequenceView />
+  </PluginContextContainer>
+</div>
+```
+
+## Directly using Mol* React UI
+
+```ts
+class MolStarWrapper {
+  private resolveInit: () => void;
+  initialized = new Promise<boolean>(res => { this.resolveInit = () => res(true); });
+
+  private initCalled = false;
+  plugin: PluginUIContext;
+  async init() {
+    if (this.initCalled) return;
+    this.initCalled = true;
+    this.plugin = ...;
+    await this.plugin.init();
+    this.resolveInit();
+  }
+}
+
+function MolStar({ model }: { model: MolStarWrapper }) {
+  const [initialized, setInitialized] = useState(false);
+  useEffect(() => {
+     async function init() {
+       await model.init();
+       setInitialized(true);
+     }
+     init();
+  }, [model]);
+
+  if (!initialized) return <>Loading</>;
+  return <div style={{ ..., position: 'relative' }}>
+    <Plugin plugin={model.plugin} />
+  </div>;
+}
+```
+
+## ``PluginContext`` without built-in React UI
+
+- The [``PluginContext``](https://github.com/molstar/molstar/blob/master/src/mol-plugin/context.ts) can be instantiated without using the default React UI.
+
+```HTML
+<div id='molstar-parent' style='position: absolute; top: 0; left: 0; right: 0; bottom: 0'>
+    <canvas id='molstar-canvas' style='position: absolute; top: 0; left: 0; right: 0; bottom: 0'></canvas>
+</div>
+```
+
+```ts
+import { DefaultPluginSpec, PluginSpec } from 'molstar/lib/mol-plugin/spec';
+import { PluginContext  } from 'molstar/lib/mol-plugin/context';
+import { PluginConfig } from 'molstar/lib/mol-plugin/config';
+
+const MySpec: PluginSpec = {
+    ...DefaultPluginSpec(),
+    config: [
+        [PluginConfig.VolumeStreaming.Enabled, false]
+    ]
+}
+
+async function init() {
+    const plugin = new PluginContext(MySpec);
+    await plugin.init();
+
+    const canvas = <HTMLCanvasElement> document.getElementById('molstar-canvas');
+    const parent = <HTMLDivElement> document.getElementById('molstar-parent');
+
+    if (!plugin.initViewer(canvas, parent)) {
+        console.error('Failed to init Mol*');
+        return;
+    }
+
+    // Example url:"https://files.rcsb.org/download/3j7z.pdb" 
+    // Example url:"https://files.rcsb.org/download/5AFI.cif" 
+    const data = await plugin.builders.data.download({ url: '...' }, { state: { isGhost: true } });
+    const trajectory = await plugin.builders.structure.parseTrajectory(data, format); //format is 'mmcif' or 'pdb' etc.
+    await plugin.builders.structure.hierarchy.applyPreset(trajectory, 'default');
+}
+
+```
+
+## ``Canvas3D`` without built-in state management
+
+- The ``PluginContext`` object from the above examples can be completely omitted.
+- See [Browser Tests](https://github.com/molstar/molstar/tree/master/src/tests/browser) for example usage.
+
+```ts
+const canvas = document.getElementById('canvas'); // parent <canvas> element
+const canvas3d = Canvas3D.create(Canvas3DContext.fromCanvas(canvas));
+canvas3d.animate();
+// use the canvas3d object here
+```

docs/docs/plugin/selections.md

@@ -0,0 +1,110 @@
+# Selections
+
+
+Assuming you have a model already loaded into the plugin (see [Creating Plugin Instance](./instance.md)), these are some of the following method you can select structural data.
+
+### Selecting directly from the `hierarchy` manager
+
+One can select a subcomponent's data directly from the plugin manager.
+
+```typescript 
+import { Structure } from '../mol-model/structure';
+
+const ligandData = plugin.managers.structure.hierarchy.selection.structures[0]?.components[0]?.cell.obj?.data;
+const ligandLoci = Structure.toStructureElementLoci(ligandData as any);
+
+plugin.managers.camera.focusLoci(ligandLoci);
+plugin.managers.interactivity.lociSelects.select({ loci: ligandLoci });
+```
+
+## Selection callbacks
+If you want to subscribe to selection events (e.g. to change external state in your application based on a user selection), you can use: `plugin.behaviors.interaction.click.subscribe`
+
+Here's an example of passing in a React "set" function to update selected residue positions.
+```typescript
+import {
+  Structure,
+  StructureProperties,
+} from "molstar/lib/mol-model/structure"
+// setSelected is assumed to be a "set" function returned by useState
+// (selected: any[]) => void
+plugin.behaviors.interaction.click.subscribe(
+  (event: InteractivityManager.ClickEvent) => {
+    const selections = Array.from(
+      plugin.managers.structure.selection.entries.values()
+    );
+    // This bit can be customized to record any piece information you want
+    const localSelected: any[] = [];
+    for (const { structure } of selections) {
+      if (!structure) continue;
+      Structure.eachAtomicHierarchyElement(structure, {
+        residue: (loc) => {
+          const position = StructureProperties.residue.label_seq_id(loc);
+          localSelected.push({ position });
+        },
+      });
+    }
+    setSelected(localSelected);
+  }
+)
+```
+
+### `Molscript` language
+
+Molscript is a language for addressing crystallographic structures and is a part of the Mol* library found at `https://github.com/molstar/molstar/tree/master/src/mol-script`. It can be used against the Molstar plugin as a query language and transpiled against multiple external molecular visualization libraries(see [here](https://github.com/molstar/molstar/tree/master/src/mol-script/transpilers)).
+
+### Querying a structure for a specific chain and residue range (select residues with 12<res_id<200 of chain with auth_asym_id==A) :
+
+```typescript
+import { compileIdListSelection } from 'molstar/lib/mol-script/util/id-list'
+
+const query = compileIdListSelection('A 12-200', 'auth');
+window.molstar?.managers.structure.selection.fromCompiledQuery('add',query);
+```
+
+## Selection Queries
+
+Another way to create a selection is via a `SelectionQuery` object. This is a more programmatic way to create a selection. The following example shows how to select a chain and a residue range using a `SelectionQuery` object.
+This relies on the concept of `Expression` which is basically a intermediate representation between a Molscript statement and a selection query. 
+ 
+### Select residues 10-15 of chains A and F in a structure using a `SelectionQuery` object:
+
+```typescript
+
+import { MolScriptBuilder as MS, MolScriptBuilder } from 'molstar/lib/mol-script/language/builder';
+import { Expression } from 'molstar/lib/mol-script/language/expression';
+import {  StructureSelectionQuery } from 'molstar/lib/mol-plugin-state/helpers/structure-selection-query'
+
+
+export function select_multiple() {
+
+ const args = [['A', 10, 15], ['F', 10, 15]]
+ const groups: Expression[] = [];
+ for (var chain of args) {
+   groups.push(MS.struct.generator.atomGroups({
+     "chain-test": MS.core.rel.eq([MolScriptBuilder.struct.atomProperty.macromolecular.auth_asym_id(), chain[0]]),
+     "residue-test": MS.core.rel.inRange([MolScriptBuilder.struct.atomProperty.macromolecular.label_seq_id(), chain[1], chain[2]])
+   }));
+ }
+ var sq = StructureSelectionQuery('residue_range_10_15_in_A_and_F', MS.struct.combinator.merge(groups))
+ mstar.managers.structure.selection.fromSelectionQuery('set', sq)
+}
+```
+
+Complex queries can be constructed by combining primitive queries at the level of [`chain-test`, `residue-test`, `entity-test`, etc] (https://github.com/molstar/molstar/blob/6edbae80db340134341631f669eec86543a0f1a8/src/mol-script/language/symbol-table/structure-query.ts#L88C4-L94C112) by combining them via logical connectives provided in the `MolscriptBuilder.core.rel` as above.
+
+Inspect these examples to get a better feeling for this syntax: `https://github.com/molstar/molstar/blob/6edbae80db340134341631f669eec86543a0f1a8/src/mol-plugin-state/helpers/structure-selection-query.ts#L88-L580`
+
+
+Furthermore, a query made this way can be converted to a `Loci` object which is important in many parts of the libary:
+```typescript
+
+// Select residue 124 of chain A and convert to Loci
+const Q = MolScriptBuilder;
+var sel = Script.getStructureSelection(Q => Q.struct.generator.atomGroups({
+                'chain-test'  : Q.core.rel.eq([Q.struct.atomProperty.macromolecular.auth_asym_id(), A]),
+                "residue-test": Q.core.rel.eq([Q.struct.atomProperty.macromolecular.label_seq_id(), 124]),
+              }), objdata)
+
+let loci = StructureSelection.toLociWithSourceUnits(sel);
+```

docs/docs/plugin/transforms/custom-conformation.md

@@ -0,0 +1,45 @@
+# Assign custom conformation to a Model
+
+This document shows how to update model conformation dynamically using the `ModelWithCoordinates` transforms. If this does not work well with your particular use case, it is suggested to write a custom version of `ModelWithCoordinates` with similar usage as outlined in this document.
+
+```ts
+async function animateFirstXCoordinateExample(plugin: PluginContext, url: string, format: BuiltInTrajectoryFormat) {
+    // Load data
+    const _data = await plugin.builders.data.download({ url });
+    const trajectory = await plugin.builders.structure.parseTrajectory(_data, format);
+    const hierarchy = await this.plugin.builders.structure.hierarchy.applyPreset(trajectory, 'default');
+    if (!hierarchy) return;
+
+    // Insert ModelWithCoordinates cell to be updated in the loop bellow
+    const coordinatesNode = await plugin.build().to(hierarchy!.model).insert(ModelWithCoordinates).commit();
+
+    const x0 = hierarchy!.model.data!.atomicConformation.x[0];
+    let xOffset = 0;
+    async function animateFirstXCoord() {
+        // Normally, the whole conformation would come from an API/library call, but here we fake it:
+        const { x, y, z } = hierarchy!.model.data!.atomicConformation;
+        const nextX = [...(x as number[])];
+        nextX[0] = x0 + xOffset;
+        xOffset += 0.05;
+        if (xOffset > 1) xOffset = 0;
+
+        // Construct new coodinate frame from the data and commit the update.
+        // Rest of the state tree will reconcile automatically.
+        await plugin.build().to(coordinatesNode).update({
+            atomicCoordinateFrame: {
+                elementCount: x.length,
+                time: { value: 0, unit: 'step' },
+                xyzOrdering: { isIdentity: true },
+                x: nextX,
+                y,
+                z,
+            }
+        }).commit();
+
+        requestAnimationFrame(animateFirstXCoord);
+    }
+    animateFirstXCoord();
+}
+
+// animateFirstXCoordinateExample('https://pubchem.ncbi.nlm.nih.gov/rest/pug/compound/CID/2244/record/SDF/?record_type=3d', 'sdf');
+```

docs/docs/plugin/transforms/custom-trajectory.md

@@ -0,0 +1,72 @@
+# Load Trajectory from a Custom Format
+
+This section shows a high level example for loading trajectory from custom data in specialized plugin instances. A more complete solution is available for example in form of the [G3D format extension](https://github.com/molstar/molstar/tree/master/src/extensions/g3d).
+
+## Defining and Using a Custom Transformer
+
+```ts
+import { StateTransformer } from 'molstar/lib/mol-state';
+
+const CreateTransformer = StateTransformer.builderFactory('custom-namespace');
+
+export interface CustomTrajectoryData {
+    // ...
+}
+
+export const TrajectoryFromCustomData = CreateTransformer({
+    name: 'trajectory-from-custom-data',
+    display: 'Trajectory',
+    from: PluginStateObject.Root,
+    to: PluginStateObject.Molecule.Trajectory,
+    params: {
+        data: PD.Value<CustomTrajectoryData>(void 0 as any, { isHidden: true }),
+    },
+})({
+    apply({ params }) {
+        return Task.create('Trajectory', async (ctx) => {
+            const models = await customParse(params.data, ctx);
+            return new PluginStateObject.Molecule.Trajectory(models, {
+                label: 'Trajectory',
+            });
+        });
+    },
+});
+```
+
+The ``customParse`` function can usually be implemented 
+by modifying/extending an [existing parser already available in Mol*](https://github.com/molstar/molstar/tree/master/src/mol-model-formats/structure).
+
+To use the transformer:
+
+```ts
+const data: CustomTrajectoryData = await (await fetch(url)).json();
+const trajectory = await plugin.build().toRoot().apply(TrajectoryFromCustomData, { data }).commit();
+// Create the representation
+await plugin.builders.structure.hierarchy.applyPreset(trajectory, 'default');
+```
+
+## Using Mol* to Download the Data
+
+```ts
+export const TrajectoryFromCustomData = CreateTransformer({
+    name: 'trajectory-from-custom-data',
+    display: 'Trajectory',
+    from: PluginStateObject.Data.String, // or PluginStateObject.Data.Binary
+    to: PluginStateObject.Molecule.Trajectory,
+})({
+    apply({ a }) {
+        return Task.create('Trajectory', async (ctx) => {
+            const models = await customParse(a.data, ctx);
+            return new PluginStateObject.Molecule.Trajectory(models, {
+                label: 'Trajectory',
+            });
+        });
+    },
+});
+
+//////////////
+
+const data = await plugin.builders.data.download({ url, isBinary });
+const trajectory = await plugin.build().to(data).apply(TrajectoryFromCustomData, { data }).commit();
+await plugin.builders.structure.hierarchy.applyPreset(trajectory, 'default');
+```

docs/docs/plugin/viewer-state.md

@@ -0,0 +1,132 @@
+# Viewer State Management
+
+## ``Canvas3D`` Properties
+Properties of the [``Canvas3D``](https://github.com/molstar/molstar/blob/master/src/mol-canvas3d/canvas3d.ts) can be 
+changed using [``PluginCommands``](https://github.com/molstar/molstar/blob/master/src/mol-plugin/commands.ts).  
+
+
+### Change background, highlight, or select color
+```ts
+import { ColorNames } from 'molstar/lib/mol-util/color/names';
+import { PluginCommands } from 'molstar/lib/mol-plugin/commands';
+
+const renderer = plugin.canvas3d!.props.renderer;
+PluginCommands.Canvas3D.SetSettings(plugin, { settings: { renderer: { ...renderer, backgroundColor: ColorNames.red /* or: 0xff0000 as Color */ } } });
+```
+Similarly, `highlightColor` and `selectColor` can be updated.
+
+
+## Interactivity
+
+Interactivity in Mol* is based on the concept of ``Loci``. A ``Loci`` usually references a collection of objects and can be created by a [``Selection``](selections.md). For example, the
+``Loci`` captures all atoms in the chain with label_asym_id B of a protein:
+```ts
+import { Script } from 'molstar/lib/mol-script/script';
+import { StructureSelection } from 'molstar/lib/mol-model/structure/query';
+
+const data = plugin.managers.structure.hierarchy.current.structures[0]?.cell.obj?.data;
+if (!data) return;
+
+const selection = Script.getStructureSelection(Q => Q.struct.generator.atomGroups({
+    'chain-test': Q.core.rel.eq(['B', Q.ammp('label_asym_id')])
+}), data);
+const loci = StructureSelection.toLociWithSourceUnits(selection);
+```
+A ``Loci`` can be used to trigger custom [``Behaviors``](#behaviors).
+
+
+### Log message to Mol* console
+The built-in console in the bottom center of the plugin shows log entries.
+```ts
+plugin.log.message('This message will appear in the Mol* console');
+```
+Other log levels are: `info`, `warn`, and `error`.
+
+
+### Show toast message
+Toast messages will appear in the bottom right of the plugin and will linger for a limited time before disappearing.
+```ts
+import { PluginCommands } from 'molstar/lib/mol-plugin/commands';
+
+PluginCommands.Toast.Show(plugin, {
+    title: 'Custom Message',
+    message: 'A custom toast message that will disappear after 2 seconds.',
+    key: 'toast-custom',
+    timeoutMs: 2000
+});
+```
+
+## Behaviors
+
+The state of the Mol* plugin is usually governed by dynamic behaviors which can be set up in initial plugin specification or updated during the plugin runtime. This allows for high modularity and customizability of individual plugin instances.
+
+
+### Highlight ``Loci``
+Highlighting adds a transient overpaint to a representation that will linger until the mouse enters hovers over another 
+object. Highlights can be applied to a previously defined ``Loci`` by:
+```ts
+plugin.managers.interactivity.lociHighlights.highlightOnly({ loci }); // loci: Loci
+```
+Reset all highlights by:
+```ts
+plugin.managers.interactivity.clearHighlights();
+```
+
+
+### Select ``Loci``
+
+Selected elements will appear with distinct visuals and, if applicable, the corresponding sequence positions will be 
+shown in the Sequence Viewer panel. Selections persist until removed, for example by clicking the background. A ``Loci``
+is selected by:
+```ts
+plugin.managers.interactivity.lociSelects.select({ loci }); // loci: Loci
+```
+
+Deselect a specific ``Loci`` by:
+```ts
+plugin.managers.interactivity.lociSelects.deselect({ loci }); // loci: Loci
+```
+To deselect everything:
+```ts
+plugin.managers.interactivity.lociSelects.deselectAll();
+```
+
+
+### Focus ``Loci``
+The focus representation shows a ``Loci`` in ball-and-stick representation and, additionally, visualizes non-covalent
+interactions between atoms of the ``Loci`` as well as interactions with surrounding residues (default: 5 Å).
+```ts
+plugin.managers.structure.focus.setFromLoci(loci);
+```
+Extend an existing focus representation by:
+```ts
+plugin.managers.structure.focus.addFromLoci(loci); // loci: Loci
+```
+Reset by:
+```ts
+plugin.managers.structure.focus.clear();
+```
+
+
+### Zoom ``Loci``
+A ``Loci`` can also be used to manipulate the camera. Zoom in by:
+```ts
+plugin.managers.camera.focusLoci(loci); // loci: Loci
+```
+
+Restore the default camera position by:
+```ts
+plugin.managers.camera.reset();
+```
+
+### Turn off view resetting on new representations
+A new representation via something like
+```ts
+.apply(StateTransforms.Representation.VolumeRepresentation3D, ...)
+```
+can reset the view to make the whole representation visible.
+When one wants to keep the view the same instead of having the rep reset the view,
+keep the view constant by:
+```ts
+plugin.canvas3d?.setProps({ camera: { manualReset: true } });
+```

docs/extensions/mvs/README.md

@@ -1,161 +0,0 @@
-# Mol* MolViewSpec extension
-
-**MolViewSpec (MVS)** is a tool for standardized description of reproducible molecular visualizations shareable across software applications.
-
-MolViewSpec provides a generic description of typical visual scenes that may occur as part of molecular visualizations. A tree format allows the composition of complex scene descriptors by combining reoccurring nodes that serve as building blocks.
-
-
-## More sources:
-
-- MolViewSpec home page: https://molstar.org/mol-view-spec/
-- Python library `molviewspec` for building MolViewSpec views: https://pypi.org/project/molviewspec/
-- Python library `molviewspec` in action: https://colab.research.google.com/drive/1O2TldXlS01s-YgkD9gy87vWsfCBTYuz9
-
-
-## MolViewSpec data structure
-
-MVS is based on a tree format, i.e. a molecular view is described as a tree where individual node types represent common data operations needed to create the view (e.g. download, parse, color). Each node can have parameters that provide additional details for the operation. 
-
-A simple example of a MVS tree showing PDB structure 1cbs:
-
-![Example MolViewSpec - 1cbs with labelled protein and ligand](./1cbs.png "Example MolViewSpec")
-
-```txt
-- root {}
-  - download {url: "https://www.ebi.ac.uk/pdbe/entry-files/1cbs.bcif"}
-    - parse {format: "bcif"}
-      - structure {type: "model"}
-        - component {selector: "polymer"}
-          - representation {type: "cartoon"}
-            - color {color: "green"}
-            - color {selector: {label_asym_id: "A", beg_label_seq_id: 1, end_label_seq_id: 50}, color: "#6688ff"}
-          - label {text: "Protein"}
-        - component {selector: "ligand"}
-          - representation {type: "ball_and_stick"}
-            - color {color: "#cc3399"}
-          - label {text: "Retinoic Acid"}
-  - canvas {background_color: "#ffffee"}
-  - camera {target: [17,21,27], position: [41,34,69], up: [-0.129,0.966,-0.224]}
-```
-
-(This is just a human-friendly representation of the tree, not the actual data format!)
-
-A complete list of supported node types and their parameters is described by the [MVS tree schema](./mvs-tree-schema.md).
-
-### Encoding
-
-A MolViewSpec tree can be encoded and stored in `.mvsj` format, which is basically a JSON representation of the tree with additional metadata:
-
-```json
-{
-  "metadata": {
-    "title": "Example MolViewSpec - 1cbs with labelled protein and ligand",
-    "version": "1",
-    "timestamp": "2023-11-24T10:38:17.483Z"
-  },
-  "root": {
-    "kind": "root",
-    "children": [
-      {
-        "kind": "download",
-        "params": {"url": "https://www.ebi.ac.uk/pdbe/entry-files/1cbs.bcif"},
-        "children": [
-          {
-            "kind": "parse",
-            "params": {"format": "bcif"},
-            "children": [
-    ...
-```
-Complete file: [1cbs.mvsj](../../../examples/mvs/1cbs.mvsj)
-
-
-## MolViewSpec extension functionality
-
-Mol* MolViewSpec extension provides functionality for building, validating, and visualizing MVS views.
-
-### Graphical user interface
-
-- **Drag&drop support:** The easiest way to load a MVS view into Mol* Viewer is to drag a `.mvsj` file and drop it in a browser window with Mol* Viewer.
-
-- **Load via menu:** Another way to load a MVS view is to use "Download File" or "Open Files" action, available in the "Home" tab in the left panel. For these actions, the "Format" parameter must be set to "MVSJ" (in the "Miscellaneous" category) or "Auto".
-
-- **URL parameters:** Mol* Viewer supports `mvs-url`, `mvs-data`, and `mvs-format` URL parameters to specify a MVS view to be loaded when the viewer is initialized.
-  - `mvs-url` specifies the address from which the MVS view should be retrieved.
-  - `mvs-data` specifies the MVS view data directly. Keep in mind that some characters must be escaped to be used in the URL. Also beware that URLs longer than 2000 character may not work in all browsers.
-  - `mvs-format` specifies the format of the MVS view data (from `mvs-url` or `mvs-data`). The only allowed (and default) value is `mvsj`, as this is currently the only supported format.
-  
-  Examples of URL parameter usage:
-
-  - https://molstar.org/viewer?mvs-format=mvsj&mvs-url=https://raw.githubusercontent.com/molstar/molstar/master/examples/mvs/1cbs.mvsj
-
-  - https://molstar.org/viewer?mvs-format=mvsj&mvs-data=%7B%22metadata%22%3A%7B%22title%22%3A%22Example%20MolViewSpec%20-%201cbs%20with%20labelled%20protein%20and%20ligand%22%2C%22version%22%3A%221%22%2C%22timestamp%22%3A%222023-11-24T10%3A38%3A17.483%22%7D%2C%22root%22%3A%7B%22kind%22%3A%22root%22%2C%22children%22%3A%5B%7B%22kind%22%3A%22download%22%2C%22params%22%3A%7B%22url%22%3A%22https%3A//www.ebi.ac.uk/pdbe/entry-files/1cbs.bcif%22%7D%2C%22children%22%3A%5B%7B%22kind%22%3A%22parse%22%2C%22params%22%3A%7B%22format%22%3A%22bcif%22%7D%2C%22children%22%3A%5B%7B%22kind%22%3A%22structure%22%2C%22params%22%3A%7B%22type%22%3A%22model%22%7D%2C%22children%22%3A%5B%7B%22kind%22%3A%22component%22%2C%22params%22%3A%7B%22selector%22%3A%22polymer%22%7D%2C%22children%22%3A%5B%7B%22kind%22%3A%22representation%22%2C%22params%22%3A%7B%22type%22%3A%22cartoon%22%7D%2C%22children%22%3A%5B%7B%22kind%22%3A%22color%22%2C%22params%22%3A%7B%22color%22%3A%22green%22%7D%7D%2C%7B%22kind%22%3A%22color%22%2C%22params%22%3A%7B%22selector%22%3A%7B%22label_asym_id%22%3A%22A%22%2C%22beg_label_seq_id%22%3A1%2C%22end_label_seq_id%22%3A50%7D%2C%22color%22%3A%22%236688ff%22%7D%7D%5D%7D%2C%7B%22kind%22%3A%22label%22%2C%22params%22%3A%7B%22text%22%3A%22Protein%22%7D%7D%5D%7D%2C%7B%22kind%22%3A%22component%22%2C%22params%22%3A%7B%22selector%22%3A%22ligand%22%7D%2C%22children%22%3A%5B%7B%22kind%22%3A%22representation%22%2C%22params%22%3A%7B%22type%22%3A%22ball_and_stick%22%7D%2C%22children%22%3A%5B%7B%22kind%22%3A%22color%22%2C%22params%22%3A%7B%22color%22%3A%22%23cc3399%22%7D%7D%5D%7D%2C%7B%22kind%22%3A%22label%22%2C%22params%22%3A%7B%22text%22%3A%22Retinoic%20Acid%22%7D%7D%5D%7D%5D%7D%5D%7D%5D%7D%2C%7B%22kind%22%3A%22canvas%22%2C%22params%22%3A%7B%22background_color%22%3A%22%23ffffee%22%7D%7D%2C%7B%22kind%22%3A%22camera%22%2C%22params%22%3A%7B%22target%22%3A%5B17%2C21%2C27%5D%2C%22position%22%3A%5B41%2C34%2C69%5D%2C%22up%22%3A%5B-0.129%2C0.966%2C-0.224%5D%7D%7D%5D%7D%7D
-
-
-### Programming interface
-
-Most functions for manipulation of MVS data (including parsing, encoding, validating, and building) are provided by the `MVSData` object (defined in [src/extensions/mvs/mvs-data.ts](/src/extensions/mvs/mvs-data.ts)). In TypeScript, `MVSData` is also the type for a MVS view.
-
-The `loadMVS` function (defined in [src/extensions/mvs/load.ts](/src/extensions/mvs/load.ts)) can be used to load MVS view data into Mol* Viewer.
-
-Example usage:
-
-```ts
-// Fetch a MVS, validate, and load
-const response = await fetch('https://raw.githubusercontent.com/molstar/molstar/master/examples/mvs/1cbs.mvsj');
-const rawData = await response.text();
-const mvsData: MVSData = MVSData.fromMVSJ(rawData);
-if (!MVSData.isValid(mvsData)) throw new Error(`Oh no: ${MVSData.validationIssues(mvsData)}`);
-await loadMVS(this.plugin, mvsData, { replaceExisting: true });
-console.log('Loaded this:', MVSData.toPrettyString(mvsData));
-console.log('Loaded this:', MVSData.toMVSJ(mvsData));
-
-// Build a MVS and load
-const builder = MVSData.createBuilder();
-const structure = builder
-    .download({ url: 'https://www.ebi.ac.uk/pdbe/entry-files/download/1og2_updated.cif' })
-    .parse({ format: 'mmcif' })
-    .modelStructure();
-structure
-    .component({ selector: 'polymer' })
-    .representation({ type: 'cartoon' });
-structure
-    .component({ selector: 'ligand' })
-    .representation({ type: 'ball_and_stick' })
-    .color({ color: '#aa55ff' });
-const mvsData2: MVSData = builder.getState();
-await loadMVS(this.plugin, mvsData2, { replaceExisting: false });
-```
-
-When using the pre-built Mol* plugin bundle, `MVSData` and `loadMVS` are exposed as `molstar.PluginExtensions.mvs.MVSData` and `molstar.PluginExtensions.mvs.loadMVS`. Furthermore, the `molstar.Viewer` class has `loadMvsFromUrl` and `loadMvsData` methods, providing the same functionality as `mvs-url` and `mvs-data` URL parameters.
-
-
-### Command-line utilities
-
-The MVS extension in Mol* provides a few command-line utilities, which can be executed via NodeJS:
-
-- `mvs-validate` provides validation of MolViewSpec files
-- `mvs-render` creates images based on MolViewSpec files
-- `mvs-print-schema` prints MolViewSpec tree schema (i.e. currently supported node types and their parameters)
-
-Example usage:
-
-```sh
-# Validate a MolViewSpec file `examples/mvs/1cbs.mvsj`
-node lib/commonjs/cli/mvs/mvs-validate examples/mvs/1cbs.mvsj
-
-# Render a MolViewSpec file `examples/mvs/1cbs.mvsj` to `../outputs/1cbs.png`
-npm install --no-save canvas gl jpeg-js pngjs  # Might be needed before the first execution
-node lib/commonjs/cli/mvs/mvs-render -i examples/mvs/1cbs.mvsj -o ../outputs/1cbs.png --size 800x600 --molj
-
-# Print MolViewSpec tree schema formatted as markdown
-node lib/commonjs/cli/mvs/mvs-print-schema --markdown
-```
-
-(If you installed Mol* package from the npm repository, use can just type `npx mvs-validate`...).
-
-
-## Topics
-
-- [Selectors](./selectors.md)
-- [Annotations](./annotations.md)
-- [Camera Settings](./camera-settings.md)

docs/extensions/mvs/annotations.md

@@ -1,185 +0,0 @@
-# MVS annotations
-
-Annotations are used to define substructures (components) and apply colors, labels, or tooltips to them. In contrast to [selectors](./selectors.md), annotations are defined in a separate file, which can then be referenced in the main MVS file.
-
-
-## MVS annotation files
-
-MVS annotations can be encoded in multiple different formats, but their logic is always the same and in fact very similar to that of selectors.
-
-### JSON format
-
-The simplest example of an annotation in JSON format is just a JSON-encoded [union component expression](./selectors.md) selector. Here is a simple annotation containing 4 **annotation rows**:
-
-```json
-[
-    { "label_asym_id": "A" },
-    { "label_asym_id": "B" },
-    { "label_asym_id": "B", "beg_label_seq_id": 100, "end_label_seq_id": 200 },
-    { "label_asym_id": "B", "beg_label_seq_id": 150, "end_label_seq_id": 160 },
-]
-```
-
-However, in a typical annotation, there is at least one extra field that provides the value of the dependent variable (such as color or label) mapped to each annotation row:
-
-```json
-[
-    { "label_asym_id": "A", "color": "#00ff00" },
-    { "label_asym_id": "B", "color": "blue" },
-    { "label_asym_id": "B", "beg_label_seq_id": 100, "end_label_seq_id": 200, "color": "skyblue" }
-    { "label_asym_id": "B", "beg_label_seq_id": 150, "end_label_seq_id": 160, "color": "lightblue" }
-]
-```
-
-This particular annotation (when applied via `color_from_uri` node) will apply green color (#00ff00) to the whole chain A and three shades of blue to the chain B. Later annotation rows override earlier rows, therefore residues 1–99 will be blue, 100–149 skyblue, 150–160 lightblue, 161–200 skyblue, and 201–end blue. (Tip: to color all the rest of the structure in one color, add an annotation row with no selector fields (e.g. `{ "color": "yellow" }`) to the beginning of the annotation.)
-
-Real-life annotation files can include huge numbers of annotation rows. To avoid repeating the same field keys in every row, we can convert the array-of-objects into object-of-arrays. This will result in an equivalent annotation but smaller file size:
-
-```json
-{
-    "label_asym_id": ["A", "B", "B", "B"],
-    "beg_label_seq_id": [null, null, 100, 150],
-    "end_label_seq_id": [null, null, 200, 160],
-    "color": ["#00ff00", "blue", "skyblue", "lightblue"]
-}
-```
-
-A more complex example of JSON annotation is provided in [/examples/mvs/1h9t_domains.json](/examples/mvs/1h9t_domains.json).
-
-### CIF format
-
-Annotations can also be encoded using CIF format, a table-based format which is commonly used in structure biology to store structures or any kind of tabular data.
-
-The example from above, encoded as CIF, would look like this:
-
-```cif
-data_annotation
-loop_
-_coloring.label_asym_id
-_coloring.beg_label_seq_id
-_coloring.end_label_seq_id
-_coloring.color
-A   .   . '#00ff00'
-B   .   . 'blue'
-B 100 200 'skyblue'
-B 150 160 'lightblue'
-```
-
-An advantage of the CIF format is that it can include multiple annotation tables in the same file, organized into blocks and categories. Then the MVS file can reference individual tables using `block_header` (or `block_index`) and `category_name` parameters. The column containing the dependent variable can be specified using `field_name` parameter. In this case, we could use `"block_header": "annotation", "category_name": "coloring", "field_name": "color"`.
-
-### BCIF format
-
-This has exactly the same structure as the CIF format, but encoded using [BinaryCIF](https://github.com/molstar/BinaryCIF).
-
-
-## Referencing MVS annotations in MVS tree
-
-### From URI
-
-MVS annotations can be referenced in `color_from_uri`, `label_from_uri`, `tooltip_from_uri`, and `component_from_uri` nodes in MVS tree.
-
-For example this part of a MVS tree:
-
-```txt
-- representation {type: "cartoon"}
-  - color {selector: {label_asym_id: "A"}, color: "#00ff00"}
-  - color {selector: {label_asym_id: "B"}, color: "blue"}
-  - color {selector: {label_asym_id: "B", beg_label_seq_id: 100, end_label_seq_id: 200}, color: "skyblue"}
-  - color {selector: {label_asym_id: "B", beg_label_seq_id: 150, end_label_seq_id: 160}, color: "lightblue"}
-```
-
-can be replaced by:
-
-```txt
-- representation {type: "cartoon"}
-  - color_from_uri {uri: "https://example.org/annotations.json", format: "json", schema: "residue_range"}
-```
-
-assuming that the JSON annotation file shown in the previous section is available at `https://example.org/annotations.json`. 
-
-#### Relative URIs
-
-The `uri` parameter can also hold a URI reference (relative URI). In such cases, this URI reference is relative to the URI of the MVS file itself (e.g. if the MVS file is available from `https://example.org/spanish/inquisition/expectations.mvsj`, then the relative URI `./annotations.json` is equivalent to `https://example.org/spanish/inquisition/annotations.json`). This is however not applicable in all cases (e.g. the MVS tree can be constructed ad-hoc within a web application, therefore it has no URI; or the MVS file is loaded from a local disk using drag&drop, therefore the relative location is not accessible by the browser).
-
-### From source
-
-The MVS annotations can in fact be stored within the same mmCIF file from which the structure coordinates are loaded. To reference these annotations, we can use `color_from_source`, `label_from_source`, `tooltip_from_source`, and `component_from_source` nodes. Example:
-
-```txt
-- representation {type: "cartoon"}
-  - color_from_source {schema: "residue_range", block_header: "annotation", category_name: "coloring"}
-```
-
-
-## Annotation schemas
-
-The `schema` parameter of all `*_from_uri` and `*_from_source` nodes specifies the MVS annotation schema, i.e. a set of fields used to select a substructure. In the example above we are using `residue_range` schema, which uses columns `label_entity_id`, `label_asym_id`, `beg_label_seq_id`, and `end_label_seq_id`. (We didn't provide values for `label_entity_id`, so it is not taken into account even though the schema supports it).
-
-
-Table of selector field names supported by individual MVS annotation schemas:
-
-|Field \ Schema|whole_structure|entity|chain|residue|residue_range|atom|auth_chain|auth_residue|auth_residue_range|auth_atom|all_atomic|
-|:------------------|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
-| label_entity_id   |   | X | X | X | X | X |   |   |   |   | X |
-| label_asym_id     |   |   | X | X | X | X |   |   |   |   | X |
-| label_seq_id      |   |   |   | X |   | X |   |   |   |   | X |
-| beg_label_seq_id  |   |   |   |   | X |   |   |   |   |   | X |
-| end_label_seq_id  |   |   |   |   | X |   |   |   |   |   | X |
-| label_atom_id     |   |   |   |   |   | X |   |   |   |   | X |
-| auth_asym_id      |   |   |   |   |   |   | X | X | X | X | X |
-| auth_seq_id       |   |   |   |   |   |   |   | X |   | X | X |
-| pdbx_PDB_ins_code |   |   |   |   |   |   |   | X |   | X | X |
-| beg_auth_seq_id   |   |   |   |   |   |   |   |   | X |   | X |
-| end_auth_seq_id   |   |   |   |   |   |   |   |   | X |   | X |
-| auth_atom_id      |   |   |   |   |   |   |   |   |   | X | X |
-| type_symbol       |   |   |   |   |   | X |   |   |   | X | X |
-| atom_id           |   |   |   |   |   | X |   |   |   | X | X |
-| atom_index        |   |   |   |   |   | X |   |   |   | X | X |
-
-To include all selector field names that are present in the annotation, one can use `"schema": "all_atomic"` (we could use it in the example above and the result would be the same). In future versions of MVS, non-atomic schemas might be added, to select parts of structures that are not composed of atoms, e.g. coarse models or geometric primitives.
-
-
-## `group_id` field
-
-The `group_id` field is a special field supported by all MVS annotation schemas. It does not change the sets of atoms selected by individual rows but instead groups annotation rows together to create more complex selections. This is useful when adding labels to our visualization.
-
-The following example (when applied via `label_from_uri` node) will create 7 separate labels, each bound to a single residue:
-
-```cif
-data_annotation
-loop_
-_labels.label_asym_id
-_labels.label_seq_id
-_labels.color
-_labels.label
-A 100 pink 'Substrate binding site'
-A 150 pink 'Substrate binding site'
-A 170 pink 'Substrate binding site'
-A 200 blue 'Inhibitor binding site'
-A 220 blue 'Inhibitor binding site'
-A 300 lime 'Glycosylation site'
-A 330 lime 'Glycosylation site'
-```
-
-On the other hand, the next example will only create 4 labels ("Substrate binding site" label bound to residues 100, 150, and 170; "Inhibitor binding site" label bound to residues 200 and 220; "Glycosylation site" label bound to residue 300; and "Glycosylation site" label bound to residue 330):
-
-```cif
-data_annotation
-loop_
-_labels.group_id
-_labels.label_asym_id
-_labels.label_seq_id
-_labels.color
-_labels.label
-1 A 100 pink 'Substrate binding site'
-1 A 150 pink 'Substrate binding site'
-1 A 170 pink 'Substrate binding site'
-2 A 200 blue 'Inhibitor binding site'
-2 A 220 blue 'Inhibitor binding site'
-. A 300 lime 'Glycosylation site'
-. A 330 lime 'Glycosylation site'
-```
-
-Note: Annotation rows with empty `group_id` field (`.` in CIF, ommitted field or `null` in JSON) are always treated as separate groups.
-
-Note 2: `group_id` field has no effect on colors, tooltips, components. It only makes any difference for labels.

docs/extensions/mvs/camera-settings.md

@@ -1,71 +0,0 @@
-# MVS camera settings
-
-Camera position and orientation in MVS views can be adjusted in two ways: using a `camera` node or a `focus` node. Global attributes of the MVS view unrelated to camera positioning can be adjusted via a `canvas` node.
-
-## `camera` node
-
-This node instructs to directly set the camera position and orientation. This is done by passing `target`, `position`, and optional `up` vector. The `camera` node is placed as a child of the `root` node (see [MVS tree schema](./mvs-tree-schema.md#camera)).
-
-However, if the `target` and `position` vectors were interpreted directly, the resulting view would wildly depend on the camera field of view (FOV). For example, assume we have a sphere with center in the point [0,0,0] and radius 10 Angstroms, and we set `target=[0,0,0]` and `position=[0,0,20]`. With a camera with vertical FOV=90°, the sphere will fit into the camera's view nicely, with some margin above and under the sphere. But with a camera with vertical FOV=30°, the top and bottom of sphere will be cropped. To avoid these differences, MVS always uses position of a "reference camera" instead of the real camera position.
-
-We define the "reference camera" as a camera with such FOV that a sphere with radius *R* viewed from distance 2*R* (from the center of the sphere) will just fit into view (i.e. there will be no margin but the sphere will not be cropped). This happens to be FOV = 2 arcsin(1/2) = 60° for perspective projection, and FOV = 2 arctan(1/2) ≈ 53° for orthographic projection.
-
-
-When using **perspective** projection, the real camera distance from target and the real camera position can be calculated using these formulas:
-
-$d _\mathrm{adj} = d _\mathrm{ref} \cdot \frac{1}{2 \sin(\alpha/2)}$
-
-$\mathbf{p} _\mathrm{adj} = \mathbf{t} + (\mathbf{p} _\mathrm{ref} - \mathbf{t}) \cdot \frac{1}{2 \sin(\alpha/2)}$
-
-Where $\alpha$ is the vertical FOV of the real camera, $d _\mathrm{ref}$ is the reference camera distance from target, $d _\mathrm{adj}$ is the real (adjusted) camera distance from target, $\mathbf{t}$ is the target position, $\mathbf{p} _\mathrm{ref}$ is the reference camera position (the actual value in the MVS file), and $\mathbf{p} _\mathrm{adj}$ is the real (adjusted) camera position.
-
-When using **orthographic** projection, the formulas are slightly different:
-
-$d _\mathrm{adj} = d _\mathrm{ref} \cdot \frac{1}{2 \tan(\alpha/2)}$
-
-$\mathbf{p} _\mathrm{adj} = \mathbf{t} + (\mathbf{p} _\mathrm{ref} - \mathbf{t}) \cdot \frac{1}{2 \tan(\alpha/2)}$
-
-
-Using the example above (`target=[0,0,0]` and `position=[0,0,20]`), we can calculate that the real camera position will have to be set to:
-
-- [0, 0, 14.14] for FOV=90° (perspective projection)
-- [0, 0, 20] for FOV=60° (perspective projection)
-- [0, 0, 38.68] for FOV=30° (perspective projection)
-
-Note that for orthographic projection this adjustment achieves that the resulting view does not depend on the FOV value. For perspective projection, this is not possible and there will always be some "fisheye effect", but still it greatly reduces the dependence on FOV and avoids the too-much-zoomed-in and too-much-zoomed-out views when FOV changes.
-
-
-The `up` vector describes how the camera should be rotated around the position-target axis, i.e. it is the vector in 3D space that will be point up when projected on the screen. For this, the `up` vector must be perpendicular to the position-target axis. However, the MVS specification does not require that the provided `up` vector be perpendicular. This can be solved by a simple adjustment:
-
-$\mathbf{u} _\mathrm{adj} = \mathrm{normalize} ( ((\mathbf{t}-\mathbf{p}) \times \mathbf{u}) \times (\mathbf{t}-\mathbf{p}) )$
-
-Where $\mathbf{u}$ is the unadjusted up vector (the actual value in the MVS file), $\mathbf{u} _\mathrm{adj}$ is the adjusted up vector, $\mathbf{t}$ is the target position, and $\mathbf{p}$ is the camera position (can be either reference or adjusted camera position, the result will be the same).
-
-If the up vector parameter is not provided, the default value ([0, 1, 0]) will be used (after adjustment).
-
-
-## `focus` node
-
-The other way to adjust camera is to use a `focus` node. This node is placed as a child of a `component` node and instructs to set focus to the parent component (zoom in). This means that the camera target should be set to the center of the bounding sphere of the component, and the camera position should be set so that the bounding sphere just fits into view (vertically and horizontally).
-
-By default, the camera will be oriented so that the X axis points right, the Y axis points up, and the Z axis points towards the observer. This orientation can be changed using the optional vector parameters `direction` and `up` (see [MVS tree schema](./mvs-tree-schema.md#focus)). The `direction` vector describes the direction from the camera position towards the target position (default [0, 0, -1]). The meaning of the `up` vector is the same as for the `camera` node and the same adjustment applies to it (default [0, 1, 0]).
-
-
-
-The reference camera position for a `focus` node can be calculated as follows:
-
-$\mathbf{p} _\mathrm{ref} = \mathbf{t} - \mathrm{normalize}(\mathbf{d}) \cdot 2 r \cdot \max(1, \frac{h}{w})$
-
-Where $\mathbf{t}$ is the target position (center of the bounding sphere of the component), $r$ is the radius of the bounding sphere of the component, $\mathbf{d}$ is the direction vector, $h$ is the height of the viewport, $w$ is the width of the viewport, and $\mathbf{p} _\mathrm{ref}$ is the reference camera position (see explanation above).
-
-Applying the FOV-adjustment formulas from the previous section, we can easily calculate the real position that we have to set to the camera ($\mathbf{p} _\mathrm{adj}$):
-
-For perspective projection: $\mathbf{p} _\mathrm{adj} = \mathbf{t} - \mathrm{normalize}(\mathbf{d}) \cdot \frac{r}{\sin(\alpha/2)} \cdot \max(1, \frac{h}{w})$
-
-For orthographic projection: $\mathbf{p} _\mathrm{adj} = \mathbf{t} - \mathrm{normalize}(\mathbf{d}) \cdot \frac{r}{\tan(\alpha/2)} \cdot \max(1, \frac{h}{w})$
-
-## `canvas` node
-
-Attributes that apply to the MVS view as a whole, but are not related to camera positioning, can be set using a `canvas` node. This node is placed as a child of the `root` node (see [MVS tree schema](./mvs-tree-schema.md#canvas)).
-
-Currently, this only includes one parameter: `background_color`. Its value can be set to either a [X11 color](http://www.w3.org/TR/css3-color/#svg-color) (e.g. `"red"`), or a hexadecimal color code (e.g. `"#FF0011"`). If there is no `canvas` node, the background will be white.

docs/extensions/mvs/mvs-tree-schema.md

@@ -1,565 +0,0 @@
-# MolViewSpec tree schema
-
-(This documentation was auto-generated by `node lib/commonjs/cli/mvs/mvs-print-schema --markdown`)
-
-## `root`
-
-[Root of the tree must be of this kind]
-
-Auxiliary node kind that only appears as the tree root.
-
-Parent: none
-
-Params: none
-
-## `download`
-
-This node instructs to retrieve a data resource.
-
-Parent: `root`
-
-Params:
-
-- **`url: `**`string`
-
-  URL of the data resource.
-
-## `parse`
-
-This node instructs to parse a data resource.
-
-Parent: `download`
-
-Params:
-
-- **`format: `**`"mmcif" | "bcif" | "pdb"`
-
-  Format of the input data resource.
-
-## `structure`
-
-This node instructs to create a structure from a parsed data resource. "Structure" refers to an internal representation of molecular coordinates without any visual representation.
-
-Parent: `parse`
-
-Params:
-
-- **`type: `**`"model" | "assembly" | "symmetry" | "symmetry_mates"`
-
-  Type of structure to be created (`"model"` for original model coordinates, `"assembly"` for assembly structure, `"symmetry"` for a set of crystal unit cells based on Miller indices, `"symmetry_mates"` for a set of asymmetric units within a radius from the original model).
-
-- **`block_header?: `**`string | null`
-
-  Header of the CIF block to read coordinates from (only applies when the input data are from CIF or BinaryCIF). If `null`, block is selected based on `block_index`.
-
-  Default: `null`
-
-- **`block_index?: `**`Integer`
-
-  0-based index of the CIF block to read coordinates from (only applies when the input data are from CIF or BinaryCIF and `block_header` is `null`).
-
-  Default: `0`
-
-- **`model_index?: `**`Integer`
-
-  0-based index of model in case the input data contain multiple models.
-
-  Default: `0`
-
-- **`assembly_id?: `**`string | null`
-
-  Assembly identifier (only applies when `kind` is `"assembly"`). If `null`, the first assembly is selected.
-
-  Default: `null`
-
-- **`radius?: `**`number`
-
-  Distance (in Angstroms) from the original model in which asymmetric units should be included (only applies when `kind` is `"symmetry_mates"`).
-
-  Default: `5`
-
-- **`ijk_min?: `**`[Integer, Integer, Integer]`
-
-  Miller indices of the bottom-left unit cell to be included (only applies when `kind` is `"symmetry"`).
-
-  Default: `[-1, -1, -1]`
-
-- **`ijk_max?: `**`[Integer, Integer, Integer]`
-
-  Miller indices of the top-right unit cell to be included (only applies when `kind` is `"symmetry"`).
-
-  Default: `[1, 1, 1]`
-
-## `transform`
-
-This node instructs to rotate and/or translate structure coordinates.
-
-Parent: `structure`
-
-Params:
-
-- **`rotation?: `**`Array<number>`
-
-  Rotation matrix (3x3 matrix flattened in column major format (j*3+i indexing), this is equivalent to Fortran-order in numpy). This matrix will multiply the structure coordinates from the left. The default value is the identity matrix (corresponds to no rotation).
-
-  Default: `[1, 0, 0, 0, 1, 0, 0, 0, 1]`
-
-- **`translation?: `**`[number, number, number]`
-
-  Translation vector, applied to the structure coordinates after rotation. The default value is the zero vector (corresponds to no translation).
-
-  Default: `[0, 0, 0]`
-
-## `component`
-
-This node instructs to create a component (i.e. a subset of the parent structure).
-
-Parent: `structure`
-
-Params:
-
-- **`selector: `**`("all" | "polymer" | "protein" | "nucleic" | "branched" | "ligand" | "ion" | "water") | Partial<{ label_entity_id: string, label_asym_id: string, auth_asym_id: string, label_seq_id: Integer, auth_seq_id: Integer, pdbx_PDB_ins_code: string, beg_label_seq_id: Integer, end_label_seq_id: Integer, beg_auth_seq_id: Integer, end_auth_seq_id: Integer, label_atom_id: string, auth_atom_id: string, type_symbol: string, atom_id: Integer, atom_index: Integer }> | Array<Partial<{ label_entity_id: string, label_asym_id: string, auth_asym_id: string, label_seq_id: Integer, auth_seq_id: Integer, pdbx_PDB_ins_code: string, beg_label_seq_id: Integer, end_label_seq_id: Integer, beg_auth_seq_id: Integer, end_auth_seq_id: Integer, label_atom_id: string, auth_atom_id: string, type_symbol: string, atom_id: Integer, atom_index: Integer }>>`
-
-  Defines what part of the parent structure should be included in this component.
-
-  Default: `"all"`
-
-## `component_from_uri`
-
-This node instructs to create a component defined by an external annotation resource.
-
-Parent: `structure`
-
-Params:
-
-- **`uri: `**`string`
-
-  URL of the annotation resource.
-
-- **`format: `**`"cif" | "bcif" | "json"`
-
-  Format of the annotation resource.
-
-- **`schema: `**`"whole_structure" | "entity" | "chain" | "auth_chain" | "residue" | "auth_residue" | "residue_range" | "auth_residue_range" | "atom" | "auth_atom" | "all_atomic"`
-
-  Annotation schema defines what fields in the annotation will be taken into account.
-
-- **`block_header?: `**`string | null`
-
-  Header of the CIF block to read annotation from (only applies when `format` is `"cif"` or `"bcif"`). If `null`, block is selected based on `block_index`.
-
-  Default: `null`
-
-- **`block_index?: `**`Integer`
-
-  0-based index of the CIF block to read annotation from (only applies when `format` is `"cif"` or `"bcif"` and `block_header` is `null`).
-
-  Default: `0`
-
-- **`category_name?: `**`string | null`
-
-  Name of the CIF category to read annotation from (only applies when `format` is `"cif"` or `"bcif"`). If `null`, the first category in the block is used.
-
-  Default: `null`
-
-- **`field_name?: `**`string`
-
-  Name of the column in CIF or field name (key) in JSON that contains the dependent variable (color/label/tooltip/component_id...).
-
-  Default: `"component"`
-
-- **`field_values?: `**`Array<string> | null`
-
-  List of component identifiers (i.e. values in the field given by `field_name`) which should be included in this component. If `null`, component identifiers are ignored (all annotation rows are included), and `field_name` field can be dropped from the annotation.
-
-  Default: `null`
-
-## `component_from_source`
-
-This node instructs to create a component defined by an annotation resource included in the same file this structure was loaded from. Only applicable if the structure was loaded from an mmCIF or BinaryCIF file.
-
-Parent: `structure`
-
-Params:
-
-- **`schema: `**`"whole_structure" | "entity" | "chain" | "auth_chain" | "residue" | "auth_residue" | "residue_range" | "auth_residue_range" | "atom" | "auth_atom" | "all_atomic"`
-
-  Annotation schema defines what fields in the annotation will be taken into account.
-
-- **`block_header?: `**`string | null`
-
-  Header of the CIF block to read annotation from. If `null`, block is selected based on `block_index`.
-
-  Default: `null`
-
-- **`block_index?: `**`Integer`
-
-  0-based index of the CIF block to read annotation from (only applies when `block_header` is `null`).
-
-  Default: `0`
-
-- **`category_name?: `**`string | null`
-
-  Name of the CIF category to read annotation from. If `null`, the first category in the block is used.
-
-  Default: `null`
-
-- **`field_name?: `**`string`
-
-  Name of the column in CIF or field name (key) in JSON that contains the dependent variable (color/label/tooltip/component_id...).
-
-  Default: `"component"`
-
-- **`field_values?: `**`Array<string> | null`
-
-  List of component identifiers (i.e. values in the field given by `field_name`) which should be included in this component. If `null`, component identifiers are ignored (all annotation rows are included), and `field_name` field can be dropped from the annotation.
-
-  Default: `null`
-
-## `representation`
-
-This node instructs to create a visual representation of a component.
-
-Parent: `component` or `component_from_uri` or `component_from_source`
-
-Params:
-
-- **`type: `**`"ball_and_stick" | "cartoon" | "surface"`
-
-  Method of visual representation of the component.
-
-## `color`
-
-This node instructs to apply color to a visual representation.
-
-Parent: `representation`
-
-Params:
-
-- **`color: `**`HexColor | ("aliceblue" | "antiquewhite" | "aqua" | "aquamarine" | "azure" | "beige" | "bisque" | "black" | "blanchedalmond" | "blue" | "blueviolet" | "brown" | "burlywood" | "cadetblue" | "chartreuse" | "chocolate" | "coral" | "cornflower" | "cornflowerblue" | "cornsilk" | "crimson" | "cyan" | "darkblue" | "darkcyan" | "darkgoldenrod" | "darkgray" | "darkgreen" | "darkgrey" | "darkkhaki" | "darkmagenta" | "darkolivegreen" | "darkorange" | "darkorchid" | "darkred" | "darksalmon" | "darkseagreen" | "darkslateblue" | "darkslategray" | "darkslategrey" | "darkturquoise" | "darkviolet" | "deeppink" | "deepskyblue" | "dimgray" | "dimgrey" | "dodgerblue" | "firebrick" | "floralwhite" | "forestgreen" | "fuchsia" | "gainsboro" | "ghostwhite" | "gold" | "goldenrod" | "gray" | "green" | "greenyellow" | "grey" | "honeydew" | "hotpink" | "indianred" | "indigo" | "ivory" | "khaki" | "laserlemon" | "lavender" | "lavenderblush" | "lawngreen" | "lemonchiffon" | "lightblue" | "lightcoral" | "lightcyan" | "lightgoldenrod" | "lightgoldenrodyellow" | "lightgray" | "lightgreen" | "lightgrey" | "lightpink" | "lightsalmon" | "lightseagreen" | "lightskyblue" | "lightslategray" | "lightslategrey" | "lightsteelblue" | "lightyellow" | "lime" | "limegreen" | "linen" | "magenta" | "maroon" | "maroon2" | "maroon3" | "mediumaquamarine" | "mediumblue" | "mediumorchid" | "mediumpurple" | "mediumseagreen" | "mediumslateblue" | "mediumspringgreen" | "mediumturquoise" | "mediumvioletred" | "midnightblue" | "mintcream" | "mistyrose" | "moccasin" | "navajowhite" | "navy" | "oldlace" | "olive" | "olivedrab" | "orange" | "orangered" | "orchid" | "palegoldenrod" | "palegreen" | "paleturquoise" | "palevioletred" | "papayawhip" | "peachpuff" | "peru" | "pink" | "plum" | "powderblue" | "purple" | "purple2" | "purple3" | "rebeccapurple" | "red" | "rosybrown" | "royalblue" | "saddlebrown" | "salmon" | "sandybrown" | "seagreen" | "seashell" | "sienna" | "silver" | "skyblue" | "slateblue" | "slategray" | "slategrey" | "snow" | "springgreen" | "steelblue" | "tan" | "teal" | "thistle" | "tomato" | "turquoise" | "violet" | "wheat" | "white" | "whitesmoke" | "yellow" | "yellowgreen")`
-
-  Color to apply to the representation. Can be either an X11 color name (e.g. `"red"`) or a hexadecimal code (e.g. `"#FF0011"`).
-
-- **`selector?: `**`("all" | "polymer" | "protein" | "nucleic" | "branched" | "ligand" | "ion" | "water") | Partial<{ label_entity_id: string, label_asym_id: string, auth_asym_id: string, label_seq_id: Integer, auth_seq_id: Integer, pdbx_PDB_ins_code: string, beg_label_seq_id: Integer, end_label_seq_id: Integer, beg_auth_seq_id: Integer, end_auth_seq_id: Integer, label_atom_id: string, auth_atom_id: string, type_symbol: string, atom_id: Integer, atom_index: Integer }> | Array<Partial<{ label_entity_id: string, label_asym_id: string, auth_asym_id: string, label_seq_id: Integer, auth_seq_id: Integer, pdbx_PDB_ins_code: string, beg_label_seq_id: Integer, end_label_seq_id: Integer, beg_auth_seq_id: Integer, end_auth_seq_id: Integer, label_atom_id: string, auth_atom_id: string, type_symbol: string, atom_id: Integer, atom_index: Integer }>>`
-
-  Defines to what part of the representation this color should be applied.
-
-  Default: `"all"`
-
-## `color_from_uri`
-
-This node instructs to apply colors to a visual representation. The colors are defined by an external annotation resource.
-
-Parent: `representation`
-
-Params:
-
-- **`uri: `**`string`
-
-  URL of the annotation resource.
-
-- **`format: `**`"cif" | "bcif" | "json"`
-
-  Format of the annotation resource.
-
-- **`schema: `**`"whole_structure" | "entity" | "chain" | "auth_chain" | "residue" | "auth_residue" | "residue_range" | "auth_residue_range" | "atom" | "auth_atom" | "all_atomic"`
-
-  Annotation schema defines what fields in the annotation will be taken into account.
-
-- **`block_header?: `**`string | null`
-
-  Header of the CIF block to read annotation from (only applies when `format` is `"cif"` or `"bcif"`). If `null`, block is selected based on `block_index`.
-
-  Default: `null`
-
-- **`block_index?: `**`Integer`
-
-  0-based index of the CIF block to read annotation from (only applies when `format` is `"cif"` or `"bcif"` and `block_header` is `null`).
-
-  Default: `0`
-
-- **`category_name?: `**`string | null`
-
-  Name of the CIF category to read annotation from (only applies when `format` is `"cif"` or `"bcif"`). If `null`, the first category in the block is used.
-
-  Default: `null`
-
-- **`field_name?: `**`string`
-
-  Name of the column in CIF or field name (key) in JSON that contains the dependent variable (color/label/tooltip/component_id...).
-
-  Default: `"color"`
-
-## `color_from_source`
-
-This node instructs to apply colors to a visual representation. The colors are defined by an annotation resource included in the same file this structure was loaded from. Only applicable if the structure was loaded from an mmCIF or BinaryCIF file.
-
-Parent: `representation`
-
-Params:
-
-- **`schema: `**`"whole_structure" | "entity" | "chain" | "auth_chain" | "residue" | "auth_residue" | "residue_range" | "auth_residue_range" | "atom" | "auth_atom" | "all_atomic"`
-
-  Annotation schema defines what fields in the annotation will be taken into account.
-
-- **`block_header?: `**`string | null`
-
-  Header of the CIF block to read annotation from. If `null`, block is selected based on `block_index`.
-
-  Default: `null`
-
-- **`block_index?: `**`Integer`
-
-  0-based index of the CIF block to read annotation from (only applies when `block_header` is `null`).
-
-  Default: `0`
-
-- **`category_name?: `**`string | null`
-
-  Name of the CIF category to read annotation from. If `null`, the first category in the block is used.
-
-  Default: `null`
-
-- **`field_name?: `**`string`
-
-  Name of the column in CIF or field name (key) in JSON that contains the dependent variable (color/label/tooltip/component_id...).
-
-  Default: `"color"`
-
-## `label`
-
-This node instructs to add a label (textual visual representation) to a component.
-
-Parent: `component` or `component_from_uri` or `component_from_source`
-
-Params:
-
-- **`text: `**`string`
-
-  Content of the shown label.
-
-## `label_from_uri`
-
-This node instructs to add labels (textual visual representations) to parts of a structure. The labels are defined by an external annotation resource.
-
-Parent: `structure`
-
-Params:
-
-- **`uri: `**`string`
-
-  URL of the annotation resource.
-
-- **`format: `**`"cif" | "bcif" | "json"`
-
-  Format of the annotation resource.
-
-- **`schema: `**`"whole_structure" | "entity" | "chain" | "auth_chain" | "residue" | "auth_residue" | "residue_range" | "auth_residue_range" | "atom" | "auth_atom" | "all_atomic"`
-
-  Annotation schema defines what fields in the annotation will be taken into account.
-
-- **`block_header?: `**`string | null`
-
-  Header of the CIF block to read annotation from (only applies when `format` is `"cif"` or `"bcif"`). If `null`, block is selected based on `block_index`.
-
-  Default: `null`
-
-- **`block_index?: `**`Integer`
-
-  0-based index of the CIF block to read annotation from (only applies when `format` is `"cif"` or `"bcif"` and `block_header` is `null`).
-
-  Default: `0`
-
-- **`category_name?: `**`string | null`
-
-  Name of the CIF category to read annotation from (only applies when `format` is `"cif"` or `"bcif"`). If `null`, the first category in the block is used.
-
-  Default: `null`
-
-- **`field_name?: `**`string`
-
-  Name of the column in CIF or field name (key) in JSON that contains the dependent variable (color/label/tooltip/component_id...).
-
-  Default: `"label"`
-
-## `label_from_source`
-
-This node instructs to add labels (textual visual representations) to parts of a structure. The labels are defined by an annotation resource included in the same file this structure was loaded from. Only applicable if the structure was loaded from an mmCIF or BinaryCIF file.
-
-Parent: `structure`
-
-Params:
-
-- **`schema: `**`"whole_structure" | "entity" | "chain" | "auth_chain" | "residue" | "auth_residue" | "residue_range" | "auth_residue_range" | "atom" | "auth_atom" | "all_atomic"`
-
-  Annotation schema defines what fields in the annotation will be taken into account.
-
-- **`block_header?: `**`string | null`
-
-  Header of the CIF block to read annotation from. If `null`, block is selected based on `block_index`.
-
-  Default: `null`
-
-- **`block_index?: `**`Integer`
-
-  0-based index of the CIF block to read annotation from (only applies when `block_header` is `null`).
-
-  Default: `0`
-
-- **`category_name?: `**`string | null`
-
-  Name of the CIF category to read annotation from. If `null`, the first category in the block is used.
-
-  Default: `null`
-
-- **`field_name?: `**`string`
-
-  Name of the column in CIF or field name (key) in JSON that contains the dependent variable (color/label/tooltip/component_id...).
-
-  Default: `"label"`
-
-## `tooltip`
-
-This node instructs to add a tooltip to a component. "Tooltip" is a text which is not a part of the visualization but should be presented to the users when they interact with the component (typically, the tooltip will be shown somewhere on the screen when the user hovers over a visual representation of the component).
-
-Parent: `component` or `component_from_uri` or `component_from_source`
-
-Params:
-
-- **`text: `**`string`
-
-  Content of the shown tooltip.
-
-## `tooltip_from_uri`
-
-This node instructs to add tooltips to parts of a structure. The tooltips are defined by an external annotation resource.
-
-Parent: `structure`
-
-Params:
-
-- **`uri: `**`string`
-
-  URL of the annotation resource.
-
-- **`format: `**`"cif" | "bcif" | "json"`
-
-  Format of the annotation resource.
-
-- **`schema: `**`"whole_structure" | "entity" | "chain" | "auth_chain" | "residue" | "auth_residue" | "residue_range" | "auth_residue_range" | "atom" | "auth_atom" | "all_atomic"`
-
-  Annotation schema defines what fields in the annotation will be taken into account.
-
-- **`block_header?: `**`string | null`
-
-  Header of the CIF block to read annotation from (only applies when `format` is `"cif"` or `"bcif"`). If `null`, block is selected based on `block_index`.
-
-  Default: `null`
-
-- **`block_index?: `**`Integer`
-
-  0-based index of the CIF block to read annotation from (only applies when `format` is `"cif"` or `"bcif"` and `block_header` is `null`).
-
-  Default: `0`
-
-- **`category_name?: `**`string | null`
-
-  Name of the CIF category to read annotation from (only applies when `format` is `"cif"` or `"bcif"`). If `null`, the first category in the block is used.
-
-  Default: `null`
-
-- **`field_name?: `**`string`
-
-  Name of the column in CIF or field name (key) in JSON that contains the dependent variable (color/label/tooltip/component_id...).
-
-  Default: `"tooltip"`
-
-## `tooltip_from_source`
-
-This node instructs to add tooltips to parts of a structure. The tooltips are defined by an annotation resource included in the same file this structure was loaded from. Only applicable if the structure was loaded from an mmCIF or BinaryCIF file.
-
-Parent: `structure`
-
-Params:
-
-- **`schema: `**`"whole_structure" | "entity" | "chain" | "auth_chain" | "residue" | "auth_residue" | "residue_range" | "auth_residue_range" | "atom" | "auth_atom" | "all_atomic"`
-
-  Annotation schema defines what fields in the annotation will be taken into account.
-
-- **`block_header?: `**`string | null`
-
-  Header of the CIF block to read annotation from. If `null`, block is selected based on `block_index`.
-
-  Default: `null`
-
-- **`block_index?: `**`Integer`
-
-  0-based index of the CIF block to read annotation from (only applies when `block_header` is `null`).
-
-  Default: `0`
-
-- **`category_name?: `**`string | null`
-
-  Name of the CIF category to read annotation from. If `null`, the first category in the block is used.
-
-  Default: `null`
-
-- **`field_name?: `**`string`
-
-  Name of the column in CIF or field name (key) in JSON that contains the dependent variable (color/label/tooltip/component_id...).
-
-  Default: `"tooltip"`
-
-## `focus`
-
-This node instructs to set the camera focus to a component (zoom in).
-
-Parent: `component` or `component_from_uri` or `component_from_source`
-
-Params:
-
-- **`direction?: `**`[number, number, number]`
-
-  Vector describing the direction of the view (camera position -> focused target).
-
-  Default: `[0, 0, -1]`
-
-- **`up?: `**`[number, number, number]`
-
-  Vector which will be aligned with the screen Y axis.
-
-  Default: `[0, 1, 0]`
-
-## `camera`
-
-This node instructs to set the camera position and orientation.
-
-Parent: `root`
-
-Params:
-
-- **`target: `**`[number, number, number]`
-
-  Coordinates of the point in space at which the camera is pointing.
-
-- **`position: `**`[number, number, number]`
-
-  Coordinates of the camera.
-
-- **`up?: `**`[number, number, number]`
-
-  Vector which will be aligned with the screen Y axis.
-
-  Default: `[0, 1, 0]`
-
-## `canvas`
-
-This node sets canvas properties.
-
-Parent: `root`
-
-Params:
-
-- **`background_color: `**`HexColor | ("aliceblue" | "antiquewhite" | "aqua" | "aquamarine" | "azure" | "beige" | "bisque" | "black" | "blanchedalmond" | "blue" | "blueviolet" | "brown" | "burlywood" | "cadetblue" | "chartreuse" | "chocolate" | "coral" | "cornflower" | "cornflowerblue" | "cornsilk" | "crimson" | "cyan" | "darkblue" | "darkcyan" | "darkgoldenrod" | "darkgray" | "darkgreen" | "darkgrey" | "darkkhaki" | "darkmagenta" | "darkolivegreen" | "darkorange" | "darkorchid" | "darkred" | "darksalmon" | "darkseagreen" | "darkslateblue" | "darkslategray" | "darkslategrey" | "darkturquoise" | "darkviolet" | "deeppink" | "deepskyblue" | "dimgray" | "dimgrey" | "dodgerblue" | "firebrick" | "floralwhite" | "forestgreen" | "fuchsia" | "gainsboro" | "ghostwhite" | "gold" | "goldenrod" | "gray" | "green" | "greenyellow" | "grey" | "honeydew" | "hotpink" | "indianred" | "indigo" | "ivory" | "khaki" | "laserlemon" | "lavender" | "lavenderblush" | "lawngreen" | "lemonchiffon" | "lightblue" | "lightcoral" | "lightcyan" | "lightgoldenrod" | "lightgoldenrodyellow" | "lightgray" | "lightgreen" | "lightgrey" | "lightpink" | "lightsalmon" | "lightseagreen" | "lightskyblue" | "lightslategray" | "lightslategrey" | "lightsteelblue" | "lightyellow" | "lime" | "limegreen" | "linen" | "magenta" | "maroon" | "maroon2" | "maroon3" | "mediumaquamarine" | "mediumblue" | "mediumorchid" | "mediumpurple" | "mediumseagreen" | "mediumslateblue" | "mediumspringgreen" | "mediumturquoise" | "mediumvioletred" | "midnightblue" | "mintcream" | "mistyrose" | "moccasin" | "navajowhite" | "navy" | "oldlace" | "olive" | "olivedrab" | "orange" | "orangered" | "orchid" | "palegoldenrod" | "palegreen" | "paleturquoise" | "palevioletred" | "papayawhip" | "peachpuff" | "peru" | "pink" | "plum" | "powderblue" | "purple" | "purple2" | "purple3" | "rebeccapurple" | "red" | "rosybrown" | "royalblue" | "saddlebrown" | "salmon" | "sandybrown" | "seagreen" | "seashell" | "sienna" | "silver" | "skyblue" | "slateblue" | "slategray" | "slategrey" | "snow" | "springgreen" | "steelblue" | "tan" | "teal" | "thistle" | "tomato" | "turquoise" | "violet" | "wheat" | "white" | "whitesmoke" | "yellow" | "yellowgreen")`
-
-  Color of the canvas background. Can be either an X11 color name (e.g. `"red"`) or a hexadecimal code (e.g. `"#FF0011"`).

docs/extensions/mvs/selectors.md

@@ -1,56 +0,0 @@
-# MVS selectors
-
-Selectors are used in MVS to define substructures (components) and apply colors, labels, or tooltips to them. MVS nodes that take a `selector` parameter are `component` (creates a component from the parent `structure` node) and `color` (applies coloring to a part of the parent `representation` node).
-
-There are three kinds of selectors:
-
-- **Static selector** is a string that selects a part of the structure based on entity type. The supported static selectors are these:
-
-  `"all", "polymer", "protein", "nucleic", "branched", "ligand", "ion", "water"`
-
-- **Component expression** is an object that selects a set of atoms based on their properties like chain identifier, residue number, or type symbol. The type of a component expression object is:
-
-  ```ts
-  {
-      label_entity_id?: str,    // Entity identifier
-      label_asym_id?: str,      // Chain identifier in label_* numbering
-      auth_asym_id?: str,       // Chain identifier in auth_* numbering
-      label_seq_id?: int,       // Residue number in label_* numbering
-      auth_seq_id?: int,        // Residue number in auth_* numbering
-      pdbx_PDB_ins_code?: str,  // PDB insertion code
-      beg_label_seq_id?: int,   // Minimum label_seq_id (inclusive), leave blank to start from the beginning of the chain
-      end_label_seq_id?: int,   // Maximum label_seq_id (inclusive), leave blank to go to the end of the chain
-      beg_auth_seq_id?: int,    // Minimum auth_seq_id (inclusive), leave blank to start from the beginning of the chain
-      end_auth_seq_id?: int,    // Maximum auth_seq_id (inclusive), leave blank to go to the end of the chain
-      label_atom_id?: str,      // Atom name like 'CA', 'N', 'O', in label_* numbering
-      auth_atom_id?: str,       // Atom name like 'CA', 'N', 'O', in auth_* numbering
-      type_symbol?: str,        // Element symbol like 'H', 'HE', 'LI', 'BE'
-      atom_id?: int,            // Unique atom identifier (_atom_site.id)
-      atom_index?: int,         // 0-based index of the atom in the source data
-  }
-  ```
-
-  A component expression can include any combination of the fields. An expression with multiple fields selects atoms that fulfill all fields at the same time. Examples:
-
-  ```ts
-  // Select whole chain A
-  selector: { label_asym_id: 'A' }
-
-  // Select residues 100 to 200 (inclusive) in chain B
-  selector: { label_asym_id: 'B', beg_label_seq_id: 100, end_label_seq_id: 200 }
-
-  // Select C-alpha atoms in residue 100 (using auth_* numbering) of any chain
-  selector: { auth_seq_id: 100, type_symbol: 'C', auth_atom_id: 'CA' }
-  ```
-
-- **Union component expression** is an array of simple component expressions. A union component expression is interpreted as set union, i.e. it selects all atoms that fulfill at least one of the expressions in the array. Example:
-
-  ```ts
-  // Select chains A, B, and C
-  selector: [{ label_asym_id: 'A' }, { label_asym_id: 'B' }, { label_asym_id: 'C' }]
-
-  // Select residues up to 100 (inclusive) in chain A plus all magnesium atoms
-  selector: [{ label_asym_id: 'A', end_label_seq_id: 100 }, { type_symbol: 'MG' }]
-  ```
-
-An alternative to using selectors is using [MVS annotations](./annotations.md). This means defining the selections in a separate file and referencing them from the MVS file.

docs/mkdocs.yml

@@ -0,0 +1,62 @@
+site_name: Mol* Developer Documentation
+theme:
+  name: material
+
+  # 404 page
+  static_templates:
+    - 404.html
+
+  # Necessary for search to work properly
+  include_search_page: false
+  search_index_only: true
+
+  # Default values, taken from mkdocs_theme.yml
+  language: en
+  font:
+    text: Roboto
+    code: Roboto Mono
+  favicon: assets/favicon.png
+  icon:
+    logo: logo
+markdown_extensions:
+  - pymdownx.highlight
+  - pymdownx.superfences
+  - pymdownx.arithmatex:
+      generic: true
+# Scripts for rendering Latex equations (in addition to pymdownx.arithmatex):
+extra_javascript:
+  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+nav:
+  - 'index.md'
+  - Plugin:
+    - Creating Instance: 'plugin/instance.md'
+    - Examples: plugin/examples.md
+    - Custom Library: 'plugin/custom-library.md'
+    - Selections: 'plugin/selections.md'
+    - Viewer State: 'plugin/viewer-state.md'
+    - Data State: 'plugin/data-state.md'
+    - File Formats: 'plugin/file-formats.md'
+    - CIF Schemas: 'plugin/cif-schemas.md'
+    - State Transforms:
+      - Custom Trajectory: 'plugin/transforms/custom-trajectory.md'
+      - Custom Conformation: 'plugin/transforms/custom-conformation.md'
+  - Data Access Tools:
+    - 'data-access-tools/model-server.md'
+    - Volume Server:
+      - Overview: 'data-access-tools/volume-server/index.md'
+      - Examples: 'data-access-tools/volume-server/examples.md'
+      - How it Works: 'data-access-tools/volume-server/how-it-works.md'
+      - Data Format: 'data-access-tools/volume-server/response-data-format.md'
+    - 'data-access-tools/plugin-state-server.md'
+    - 'data-access-tools/convert-to-bcif.md'
+    - 'data-access-tools/create-ccd-table.md'
+    - 'data-access-tools/extract-ccd-ions.md'
+  - Extensions:
+    - MolViewSpec: 'extensions/mvs/index.md'
+    - wwPDB StructConn: 'extensions/struct-conn.md'
+    - Tunnels: 'extensions/tunnels.md'
+  - Misc:
+    - Interesting PDB entries: misc/interesting-pdb-entries.md
+    - Exporting component data: exporting-components.md
+repo_url: https://github.com/molstar/docs

docs/model-server/readme.md

@@ -1,69 +0,0 @@
-Model Server
-============
-
-Model Server is a tool for preprocessing and querying macromolecular structure data.
-
-Installing and Running
-=====================
-
-Requires nodejs 8+.
-
-## From GitHub
-
-```
-git clone https://github.com/molstar/molstar
-npm install
-```
-
-Afterwards, build the project source:
-
-```
-npm run build-tsc
-```
-
-and run the server by 
-
-```
-node lib/commonjs/servers/model/server/server
-```
-
-## From NPM
-
-```
-npm install --production molstar
-./model-server 
-```
-
-(or ``node node_modules\.bin\model-server`` in Windows).
-
-The NPM package contains all the tools mentioned here as "binaries":
-
-- ``model-server``
-- ``model-server-query``
-- ``model-server-preprocess``
-
-
-### Production use
-
-In production it is required to use a service that will keep the server running, such as [forever.js](https://github.com/foreverjs/forever).
-
-
-### Memory issues
-
-Sometimes nodejs might run into problems with memory. This is usually resolved by adding the ``--max-old-space-size=8192`` parameter.
-
-## Preprocessor
-
-The preprocessor application allows to add custom data to CIF files and/or convert CIF to BinaryCIF. ``node lib/commonjs/servers/model/preprocess`` or ``model-server-preprocess`` binary from the NPM package.
-
-
-## Local Mode
-
-The server can be run in local/file based mode using ``node lib/commonjs/servers/model/query`` (``model-server-query`` binary from the NPM package).
-
-Custom Properties
-=================
-
-This feature is still in development.
-
-It is possible to provide property descriptors that transform data to internal representation and define how it should be exported into one or mode CIF categories. Examples of this are located in the ``mol-model-props`` module and are linked to the server in the config and ``servers/model/properties``.

docs/state/transforms.md

@@ -1,738 +0,0 @@
-# Mol* Plugin State Transformer Reference
-
-* [build-in.root](#build-in-root)
-* [ms-plugin.download](#ms-plugin-download)
-* [ms-plugin.read-file](#ms-plugin-read-file)
-* [ms-plugin.parse-cif](#ms-plugin-parse-cif)
-* [ms-plugin.parse-ccp4](#ms-plugin-parse-ccp4)
-* [ms-plugin.parse-dsn6](#ms-plugin-parse-dsn6)
-* [ms-plugin.trajectory-from-mmcif](#ms-plugin-trajectory-from-mmcif)
-* [ms-plugin.trajectory-from-pdb](#ms-plugin-trajectory-from-pdb)
-* [ms-plugin.model-from-trajectory](#ms-plugin-model-from-trajectory)
-* [ms-plugin.structure-from-model](#ms-plugin-structure-from-model)
-* [ms-plugin.structure-assembly-from-model](#ms-plugin-structure-assembly-from-model)
-* [ms-plugin.structure-symmetry-from-model](#ms-plugin-structure-symmetry-from-model)
-* [ms-plugin.structure-selection](#ms-plugin-structure-selection)
-* [ms-plugin.structure-complex-element](#ms-plugin-structure-complex-element)
-* [ms-plugin.custom-model-properties](#ms-plugin-custom-model-properties)
-* [ms-plugin.volume-from-ccp4](#ms-plugin-volume-from-ccp4)
-* [ms-plugin.volume-from-dsn6](#ms-plugin-volume-from-dsn6)
-* [ms-plugin.representation-highlight-loci](#ms-plugin-representation-highlight-loci)
-* [ms-plugin.representation-select-loci](#ms-plugin-representation-select-loci)
-* [ms-plugin.default-loci-label-provider](#ms-plugin-default-loci-label-provider)
-* [ms-plugin.structure-representation-3d](#ms-plugin-structure-representation-3d)
-* [ms-plugin.explode-structure-representation-3d](#ms-plugin-explode-structure-representation-3d)
-* [ms-plugin.volume-representation-3d](#ms-plugin-volume-representation-3d)
-* [ms-plugin.focus-loci-on-select](#ms-plugin-focus-loci-on-select)
-* [ms-plugin.pdbe-structure-quality-report-prop](#ms-plugin-pdbe-structure-quality-report-prop)
-* [ms-plugin.rcsb-assembly-symmetry-prop](#ms-plugin-rcsb-assembly-symmetry-prop)
-* [ms-plugin.structure-animation](#ms-plugin-structure-animation)
-* [ms-plugin.scene-labels](#ms-plugin-scene-labels)
-
-----------------------------
-## <a name="build-in-root"></a>build-in.root :: () -> ()
-*For internal use.*
-
-----------------------------
-## <a name="ms-plugin-download"></a>ms-plugin.download :: Root -> String | Binary
-*Download string or binary data from the specified URL*
-
-### Parameters
-- **url**: String *(Resource URL. Must be the same domain or support CORS.)*
-- **label**?: String
-- **isBinary**?: true/false *(If true, download data as binary (string otherwise))*
-
-### Default Parameters
-```js
-{
-  "url": "https://www.ebi.ac.uk/pdbe/static/entry/1cbs_updated.cif"
-}
-```
-----------------------------
-## <a name="ms-plugin-read-file"></a>ms-plugin.read-file :: Root -> String | Binary
-*Read string or binary data from the specified file*
-
-### Parameters
-- **file**: JavaScript File Handle
-- **label**?: String
-- **isBinary**?: true/false *(If true, open file as as binary (string otherwise))*
-
-### Default Parameters
-```js
-{}
-```
-----------------------------
-## <a name="ms-plugin-parse-cif"></a>ms-plugin.parse-cif :: String | Binary -> Cif
-*Parse CIF from String or Binary data*
-
-----------------------------
-## <a name="ms-plugin-parse-ccp4"></a>ms-plugin.parse-ccp4 :: Binary -> Ccp4
-*Parse CCP4/MRC/MAP from Binary data*
-
-----------------------------
-## <a name="ms-plugin-parse-dsn6"></a>ms-plugin.parse-dsn6 :: Binary -> Dsn6
-*Parse CCP4/BRIX from Binary data*
-
-----------------------------
-## <a name="ms-plugin-trajectory-from-mmcif"></a>ms-plugin.trajectory-from-mmcif :: Cif -> Trajectory
-*Identify and create all separate models in the specified CIF data block*
-
-### Parameters
-- **blockHeader**?: String *(Header of the block to parse. If none is specifed, the 1st data block in the file is used.)*
-
-### Default Parameters
-```js
-{}
-```
-----------------------------
-## <a name="ms-plugin-trajectory-from-pdb"></a>ms-plugin.trajectory-from-pdb :: String -> Trajectory
-
-----------------------------
-## <a name="ms-plugin-model-from-trajectory"></a>ms-plugin.model-from-trajectory :: Trajectory -> Model
-*Create a molecular structure from the specified model.*
-
-### Parameters
-- **modelIndex**: Numeric value *(Zero-based index of the model)*
-
-### Default Parameters
-```js
-{
-  "modelIndex": 0
-}
-```
-----------------------------
-## <a name="ms-plugin-structure-from-model"></a>ms-plugin.structure-from-model :: Model -> Structure
-*Create a molecular structure from the specified model.*
-
-----------------------------
-## <a name="ms-plugin-structure-assembly-from-model"></a>ms-plugin.structure-assembly-from-model :: Model -> Structure
-*Create a molecular structure assembly.*
-
-### Parameters
-- **id**?: String *(Assembly Id. Value 'deposited' can be used to specify deposited asymmetric unit.)*
-
-### Default Parameters
-```js
-{}
-```
-----------------------------
-## <a name="ms-plugin-structure-symmetry-from-model"></a>ms-plugin.structure-symmetry-from-model :: Model -> Structure
-*Create a molecular structure symmetry.*
-
-### Parameters
-- **ijkMin**: 3D vector [x, y, z]
-- **ijkMax**: 3D vector [x, y, z]
-
-### Default Parameters
-```js
-{
-  "ijkMin": [
-    -1,
-    -1,
-    -1
-  ],
-  "ijkMax": [
-    1,
-    1,
-    1
-  ]
-}
-```
-----------------------------
-## <a name="ms-plugin-structure-selection"></a>ms-plugin.structure-selection :: Structure -> Structure
-*Create a molecular structure from the specified query expression.*
-
-### Parameters
-- **query**: Value
-- **label**?: String
-
-### Default Parameters
-```js
-{}
-```
-----------------------------
-## <a name="ms-plugin-structure-complex-element"></a>ms-plugin.structure-complex-element :: Structure -> Structure
-*Create a molecular structure from the specified model.*
-
-### Parameters
-- **type**: One of 'atomic-sequence', 'water', 'atomic-het', 'spheres'
-
-### Default Parameters
-```js
-{
-  "type": "atomic-sequence"
-}
-```
-----------------------------
-## <a name="ms-plugin-custom-model-properties"></a>ms-plugin.custom-model-properties :: Model -> Model
-
-### Parameters
-- **properties**: Array of  *(A list of property descriptor ids.)*
-
-### Default Parameters
-```js
-{
-  "properties": []
-}
-```
-----------------------------
-## <a name="ms-plugin-volume-from-ccp4"></a>ms-plugin.volume-from-ccp4 :: Ccp4 -> Data
-*Create Volume from CCP4/MRC/MAP data*
-
-### Parameters
-- **voxelSize**: 3D vector [x, y, z]
-
-### Default Parameters
-```js
-{
-  "voxelSize": [
-    1,
-    1,
-    1
-  ]
-}
-```
-----------------------------
-## <a name="ms-plugin-volume-from-dsn6"></a>ms-plugin.volume-from-dsn6 :: Dsn6 -> Data
-*Create Volume from DSN6/BRIX data*
-
-### Parameters
-- **voxelSize**: 3D vector [x, y, z]
-
-### Default Parameters
-```js
-{
-  "voxelSize": [
-    1,
-    1,
-    1
-  ]
-}
-```
-----------------------------
-## <a name="ms-plugin-representation-highlight-loci"></a>ms-plugin.representation-highlight-loci :: Root -> Behavior
-
-----------------------------
-## <a name="ms-plugin-representation-select-loci"></a>ms-plugin.representation-select-loci :: Root -> Behavior
-
-----------------------------
-## <a name="ms-plugin-default-loci-label-provider"></a>ms-plugin.default-loci-label-provider :: Root -> Behavior
-
-----------------------------
-## <a name="ms-plugin-structure-representation-3d"></a>ms-plugin.structure-representation-3d :: Structure -> Representation3D
-
-### Parameters
-- **type**: Object { name: string, params: object } where name+params are:
-  - **cartoon**:
-Object with:
-      - **alpha**: Numeric value
-      - **useFog**: true/false
-      - **highlightColor**: Color as 0xrrggbb
-      - **selectColor**: Color as 0xrrggbb
-      - **quality**: One of 'custom', 'auto', 'highest', 'higher', 'high', 'medium', 'low', 'lower', 'lowest'
-      - **doubleSided**: true/false
-      - **flipSided**: true/false
-      - **flatShaded**: true/false
-      - **unitKinds**: Array of 'atomic', 'spheres', 'gaussians'
-      - **sizeFactor**: Numeric value
-      - **linearSegments**: Numeric value
-      - **radialSegments**: Numeric value
-      - **aspectRatio**: Numeric value
-      - **arrowFactor**: Numeric value
-      - **visuals**: Array of 'polymer-trace', 'polymer-gap', 'nucleotide-block', 'direction-wedge'
-
-  - **ball-and-stick**:
-Object with:
-      - **alpha**: Numeric value
-      - **useFog**: true/false
-      - **highlightColor**: Color as 0xrrggbb
-      - **selectColor**: Color as 0xrrggbb
-      - **quality**: One of 'custom', 'auto', 'highest', 'higher', 'high', 'medium', 'low', 'lower', 'lowest'
-      - **doubleSided**: true/false
-      - **flipSided**: true/false
-      - **flatShaded**: true/false
-      - **unitKinds**: Array of 'atomic', 'spheres', 'gaussians'
-      - **sizeFactor**: Numeric value
-      - **detail**: Numeric value
-      - **linkScale**: Numeric value
-      - **linkSpacing**: Numeric value
-      - **radialSegments**: Numeric value
-      - **sizeAspectRatio**: Numeric value
-      - **visuals**: Array of 'element-sphere', 'intra-link', 'inter-link'
-
-  - **carbohydrate**:
-Object with:
-      - **alpha**: Numeric value
-      - **useFog**: true/false
-      - **highlightColor**: Color as 0xrrggbb
-      - **selectColor**: Color as 0xrrggbb
-      - **quality**: One of 'custom', 'auto', 'highest', 'higher', 'high', 'medium', 'low', 'lower', 'lowest'
-      - **doubleSided**: true/false
-      - **flipSided**: true/false
-      - **flatShaded**: true/false
-      - **unitKinds**: Array of 'atomic', 'spheres', 'gaussians'
-      - **detail**: Numeric value
-      - **sizeFactor**: Numeric value
-      - **linkScale**: Numeric value
-      - **linkSpacing**: Numeric value
-      - **radialSegments**: Numeric value
-      - **linkSizeFactor**: Numeric value
-      - **visuals**: Array of 'carbohydrate-symbol', 'carbohydrate-link', 'carbohydrate-terminal-link'
-
-  - **distance-restraint**:
-Object with:
-      - **alpha**: Numeric value
-      - **useFog**: true/false
-      - **highlightColor**: Color as 0xrrggbb
-      - **selectColor**: Color as 0xrrggbb
-      - **quality**: One of 'custom', 'auto', 'highest', 'higher', 'high', 'medium', 'low', 'lower', 'lowest'
-      - **doubleSided**: true/false
-      - **flipSided**: true/false
-      - **flatShaded**: true/false
-      - **unitKinds**: Array of 'atomic', 'spheres', 'gaussians'
-      - **linkScale**: Numeric value
-      - **linkSpacing**: Numeric value
-      - **radialSegments**: Numeric value
-      - **sizeFactor**: Numeric value
-
-  - **molecular-surface**:
-Object with:
-      - **alpha**: Numeric value
-      - **useFog**: true/false
-      - **highlightColor**: Color as 0xrrggbb
-      - **selectColor**: Color as 0xrrggbb
-      - **quality**: One of 'custom', 'auto', 'highest', 'higher', 'high', 'medium', 'low', 'lower', 'lowest'
-      - **doubleSided**: true/false
-      - **flipSided**: true/false
-      - **flatShaded**: true/false
-      - **unitKinds**: Array of 'atomic', 'spheres', 'gaussians'
-      - **resolution**: Numeric value
-      - **radiusOffset**: Numeric value
-      - **smoothness**: Numeric value
-      - **useGpu**: true/false
-      - **ignoreCache**: true/false
-      - **sizeFactor**: Numeric value
-      - **lineSizeAttenuation**: true/false
-      - **visuals**: Array of 'gaussian-surface', 'gaussian-wireframe'
-
-  - **molecular-volume**:
-Object with:
-      - **alpha**: Numeric value
-      - **useFog**: true/false
-      - **highlightColor**: Color as 0xrrggbb
-      - **selectColor**: Color as 0xrrggbb
-      - **quality**: One of 'custom', 'auto', 'highest', 'higher', 'high', 'medium', 'low', 'lower', 'lowest'
-      - **isoValueNorm**: Numeric value *(Normalized Isolevel Value)*
-      - **renderMode**: One of 'isosurface', 'volume'
-      - **controlPoints**: A list of 2d vectors [xi, yi][]
-      - **list**: One of 'OrangeRed', 'PurpleBlue', 'BluePurple', 'Oranges', 'BlueGreen', 'YellowOrangeBrown', 'YellowGreen', 'Reds', 'RedPurple', 'Greens', 'YellowGreenBlue', 'Purples', 'GreenBlue', 'Greys', 'YellowOrangeRed', 'PurpleRed', 'Blues', 'PurpleBlueGreen', 'Spectral', 'RedYellowGreen', 'RedBlue', 'PinkYellowGreen', 'PurpleGreen', 'RedYellowBlue', 'BrownWhiteGreen', 'RedGrey', 'PurpleOrange', 'Set2', 'Accent', 'Set1', 'Set3', 'Dark2', 'Paired', 'Pastel2', 'Pastel1', 'Magma', 'Inferno', 'Plasma', 'Viridis', 'Cividis', 'Twilight', 'Rainbow', 'RedWhiteBlue'
-      - **unitKinds**: Array of 'atomic', 'spheres', 'gaussians'
-      - **resolution**: Numeric value
-      - **radiusOffset**: Numeric value
-      - **smoothness**: Numeric value
-
-  - **point**:
-Object with:
-      - **alpha**: Numeric value
-      - **useFog**: true/false
-      - **highlightColor**: Color as 0xrrggbb
-      - **selectColor**: Color as 0xrrggbb
-      - **quality**: One of 'custom', 'auto', 'highest', 'higher', 'high', 'medium', 'low', 'lower', 'lowest'
-      - **sizeFactor**: Numeric value
-      - **pointSizeAttenuation**: true/false
-      - **pointFilledCircle**: true/false
-      - **pointEdgeBleach**: Numeric value
-      - **unitKinds**: Array of 'atomic', 'spheres', 'gaussians'
-
-  - **spacefill**:
-Object with:
-      - **alpha**: Numeric value
-      - **useFog**: true/false
-      - **highlightColor**: Color as 0xrrggbb
-      - **selectColor**: Color as 0xrrggbb
-      - **quality**: One of 'custom', 'auto', 'highest', 'higher', 'high', 'medium', 'low', 'lower', 'lowest'
-      - **doubleSided**: true/false
-      - **flipSided**: true/false
-      - **flatShaded**: true/false
-      - **unitKinds**: Array of 'atomic', 'spheres', 'gaussians'
-      - **sizeFactor**: Numeric value
-      - **detail**: Numeric value
-
-
-- **colorTheme**: Object { name: string, params: object } where name+params are:
-  - **carbohydrate-symbol**:
-Object with:
-
-  - **chain-id**:
-Object with:
-      - **list**: One of 'OrangeRed', 'PurpleBlue', 'BluePurple', 'Oranges', 'BlueGreen', 'YellowOrangeBrown', 'YellowGreen', 'Reds', 'RedPurple', 'Greens', 'YellowGreenBlue', 'Purples', 'GreenBlue', 'Greys', 'YellowOrangeRed', 'PurpleRed', 'Blues', 'PurpleBlueGreen', 'Spectral', 'RedYellowGreen', 'RedBlue', 'PinkYellowGreen', 'PurpleGreen', 'RedYellowBlue', 'BrownWhiteGreen', 'RedGrey', 'PurpleOrange', 'Set2', 'Accent', 'Set1', 'Set3', 'Dark2', 'Paired', 'Pastel2', 'Pastel1', 'Magma', 'Inferno', 'Plasma', 'Viridis', 'Cividis', 'Twilight', 'Rainbow', 'RedWhiteBlue'
-
-  - **cross-link**:
-Object with:
-      - **domain**: Interval [min, max]
-      - **list**: One of 'OrangeRed', 'PurpleBlue', 'BluePurple', 'Oranges', 'BlueGreen', 'YellowOrangeBrown', 'YellowGreen', 'Reds', 'RedPurple', 'Greens', 'YellowGreenBlue', 'Purples', 'GreenBlue', 'Greys', 'YellowOrangeRed', 'PurpleRed', 'Blues', 'PurpleBlueGreen', 'Spectral', 'RedYellowGreen', 'RedBlue', 'PinkYellowGreen', 'PurpleGreen', 'RedYellowBlue', 'BrownWhiteGreen', 'RedGrey', 'PurpleOrange', 'Set2', 'Accent', 'Set1', 'Set3', 'Dark2', 'Paired', 'Pastel2', 'Pastel1', 'Magma', 'Inferno', 'Plasma', 'Viridis', 'Cividis', 'Twilight', 'Rainbow', 'RedWhiteBlue'
-
-  - **element-index**:
-Object with:
-      - **list**: One of 'OrangeRed', 'PurpleBlue', 'BluePurple', 'Oranges', 'BlueGreen', 'YellowOrangeBrown', 'YellowGreen', 'Reds', 'RedPurple', 'Greens', 'YellowGreenBlue', 'Purples', 'GreenBlue', 'Greys', 'YellowOrangeRed', 'PurpleRed', 'Blues', 'PurpleBlueGreen', 'Spectral', 'RedYellowGreen', 'RedBlue', 'PinkYellowGreen', 'PurpleGreen', 'RedYellowBlue', 'BrownWhiteGreen', 'RedGrey', 'PurpleOrange', 'Set2', 'Accent', 'Set1', 'Set3', 'Dark2', 'Paired', 'Pastel2', 'Pastel1', 'Magma', 'Inferno', 'Plasma', 'Viridis', 'Cividis', 'Twilight', 'Rainbow', 'RedWhiteBlue'
-
-  - **element-symbol**:
-Object with:
-
-  - **molecule-type**:
-Object with:
-
-  - **polymer-id**:
-Object with:
-      - **list**: One of 'OrangeRed', 'PurpleBlue', 'BluePurple', 'Oranges', 'BlueGreen', 'YellowOrangeBrown', 'YellowGreen', 'Reds', 'RedPurple', 'Greens', 'YellowGreenBlue', 'Purples', 'GreenBlue', 'Greys', 'YellowOrangeRed', 'PurpleRed', 'Blues', 'PurpleBlueGreen', 'Spectral', 'RedYellowGreen', 'RedBlue', 'PinkYellowGreen', 'PurpleGreen', 'RedYellowBlue', 'BrownWhiteGreen', 'RedGrey', 'PurpleOrange', 'Set2', 'Accent', 'Set1', 'Set3', 'Dark2', 'Paired', 'Pastel2', 'Pastel1', 'Magma', 'Inferno', 'Plasma', 'Viridis', 'Cividis', 'Twilight', 'Rainbow', 'RedWhiteBlue'
-
-  - **polymer-index**:
-Object with:
-      - **list**: One of 'OrangeRed', 'PurpleBlue', 'BluePurple', 'Oranges', 'BlueGreen', 'YellowOrangeBrown', 'YellowGreen', 'Reds', 'RedPurple', 'Greens', 'YellowGreenBlue', 'Purples', 'GreenBlue', 'Greys', 'YellowOrangeRed', 'PurpleRed', 'Blues', 'PurpleBlueGreen', 'Spectral', 'RedYellowGreen', 'RedBlue', 'PinkYellowGreen', 'PurpleGreen', 'RedYellowBlue', 'BrownWhiteGreen', 'RedGrey', 'PurpleOrange', 'Set2', 'Accent', 'Set1', 'Set3', 'Dark2', 'Paired', 'Pastel2', 'Pastel1', 'Magma', 'Inferno', 'Plasma', 'Viridis', 'Cividis', 'Twilight', 'Rainbow', 'RedWhiteBlue'
-
-  - **residue-name**:
-Object with:
-
-  - **secondary-structure**:
-Object with:
-
-  - **sequence-id**:
-Object with:
-      - **list**: One of 'OrangeRed', 'PurpleBlue', 'BluePurple', 'Oranges', 'BlueGreen', 'YellowOrangeBrown', 'YellowGreen', 'Reds', 'RedPurple', 'Greens', 'YellowGreenBlue', 'Purples', 'GreenBlue', 'Greys', 'YellowOrangeRed', 'PurpleRed', 'Blues', 'PurpleBlueGreen', 'Spectral', 'RedYellowGreen', 'RedBlue', 'PinkYellowGreen', 'PurpleGreen', 'RedYellowBlue', 'BrownWhiteGreen', 'RedGrey', 'PurpleOrange', 'Set2', 'Accent', 'Set1', 'Set3', 'Dark2', 'Paired', 'Pastel2', 'Pastel1', 'Magma', 'Inferno', 'Plasma', 'Viridis', 'Cividis', 'Twilight', 'Rainbow', 'RedWhiteBlue'
-
-  - **shape-group**:
-Object with:
-
-  - **unit-index**:
-Object with:
-      - **list**: One of 'OrangeRed', 'PurpleBlue', 'BluePurple', 'Oranges', 'BlueGreen', 'YellowOrangeBrown', 'YellowGreen', 'Reds', 'RedPurple', 'Greens', 'YellowGreenBlue', 'Purples', 'GreenBlue', 'Greys', 'YellowOrangeRed', 'PurpleRed', 'Blues', 'PurpleBlueGreen', 'Spectral', 'RedYellowGreen', 'RedBlue', 'PinkYellowGreen', 'PurpleGreen', 'RedYellowBlue', 'BrownWhiteGreen', 'RedGrey', 'PurpleOrange', 'Set2', 'Accent', 'Set1', 'Set3', 'Dark2', 'Paired', 'Pastel2', 'Pastel1', 'Magma', 'Inferno', 'Plasma', 'Viridis', 'Cividis', 'Twilight', 'Rainbow', 'RedWhiteBlue'
-
-  - **uniform**:
-Object with:
-      - **value**: Color as 0xrrggbb
-
-
-- **sizeTheme**: Object { name: string, params: object } where name+params are:
-  - **physical**:
-Object with:
-
-  - **shape-group**:
-Object with:
-
-  - **uniform**:
-Object with:
-      - **value**: Numeric value
-
-
-
-### Default Parameters
-```js
-{
-  "type": {
-    "name": "cartoon",
-    "params": {
-      "alpha": 1,
-      "useFog": true,
-      "highlightColor": 16737945,
-      "selectColor": 3407641,
-      "quality": "auto",
-      "doubleSided": false,
-      "flipSided": false,
-      "flatShaded": false,
-      "unitKinds": [
-        "atomic",
-        "spheres"
-      ],
-      "sizeFactor": 0.2,
-      "linearSegments": 8,
-      "radialSegments": 16,
-      "aspectRatio": 5,
-      "arrowFactor": 1.5,
-      "visuals": [
-        "polymer-trace"
-      ]
-    }
-  },
-  "colorTheme": {
-    "name": "polymer-id",
-    "params": {
-      "list": "RedYellowBlue"
-    }
-  },
-  "sizeTheme": {
-    "name": "uniform",
-    "params": {
-      "value": 1
-    }
-  }
-}
-```
-----------------------------
-## <a name="ms-plugin-explode-structure-representation-3d"></a>ms-plugin.explode-structure-representation-3d :: Representation3D -> Obj
-
-### Parameters
-- **t**: Numeric value
-
-### Default Parameters
-```js
-{
-  "t": 0
-}
-```
-----------------------------
-## <a name="ms-plugin-volume-representation-3d"></a>ms-plugin.volume-representation-3d :: Data -> Representation3D
-
-### Parameters
-- **type**: Object { name: string, params: object } where name+params are:
-  - **isosurface**:
-Object with:
-      - **alpha**: Numeric value
-      - **useFog**: true/false
-      - **highlightColor**: Color as 0xrrggbb
-      - **selectColor**: Color as 0xrrggbb
-      - **quality**: One of 'custom', 'auto', 'highest', 'higher', 'high', 'medium', 'low', 'lower', 'lowest'
-      - **doubleSided**: true/false
-      - **flipSided**: true/false
-      - **flatShaded**: true/false
-      - **isoValue**:       - **absolute**: Numeric value
-      - **relative**: Numeric value
-
-      - **sizeFactor**: Numeric value
-      - **lineSizeAttenuation**: true/false
-      - **visuals**: Array of 'solid', 'wireframe'
-
-  - **direct-volume**:
-Object with:
-      - **alpha**: Numeric value
-      - **useFog**: true/false
-      - **highlightColor**: Color as 0xrrggbb
-      - **selectColor**: Color as 0xrrggbb
-      - **quality**: One of 'custom', 'auto', 'highest', 'higher', 'high', 'medium', 'low', 'lower', 'lowest'
-      - **isoValueNorm**: Numeric value *(Normalized Isolevel Value)*
-      - **renderMode**: One of 'isosurface', 'volume'
-      - **controlPoints**: A list of 2d vectors [xi, yi][]
-      - **list**: One of 'OrangeRed', 'PurpleBlue', 'BluePurple', 'Oranges', 'BlueGreen', 'YellowOrangeBrown', 'YellowGreen', 'Reds', 'RedPurple', 'Greens', 'YellowGreenBlue', 'Purples', 'GreenBlue', 'Greys', 'YellowOrangeRed', 'PurpleRed', 'Blues', 'PurpleBlueGreen', 'Spectral', 'RedYellowGreen', 'RedBlue', 'PinkYellowGreen', 'PurpleGreen', 'RedYellowBlue', 'BrownWhiteGreen', 'RedGrey', 'PurpleOrange', 'Set2', 'Accent', 'Set1', 'Set3', 'Dark2', 'Paired', 'Pastel2', 'Pastel1', 'Magma', 'Inferno', 'Plasma', 'Viridis', 'Cividis', 'Twilight', 'Rainbow', 'RedWhiteBlue'
-
-
-- **colorTheme**: Object { name: string, params: object } where name+params are:
-  - **carbohydrate-symbol**:
-Object with:
-
-  - **chain-id**:
-Object with:
-      - **list**: One of 'OrangeRed', 'PurpleBlue', 'BluePurple', 'Oranges', 'BlueGreen', 'YellowOrangeBrown', 'YellowGreen', 'Reds', 'RedPurple', 'Greens', 'YellowGreenBlue', 'Purples', 'GreenBlue', 'Greys', 'YellowOrangeRed', 'PurpleRed', 'Blues', 'PurpleBlueGreen', 'Spectral', 'RedYellowGreen', 'RedBlue', 'PinkYellowGreen', 'PurpleGreen', 'RedYellowBlue', 'BrownWhiteGreen', 'RedGrey', 'PurpleOrange', 'Set2', 'Accent', 'Set1', 'Set3', 'Dark2', 'Paired', 'Pastel2', 'Pastel1', 'Magma', 'Inferno', 'Plasma', 'Viridis', 'Cividis', 'Twilight', 'Rainbow', 'RedWhiteBlue'
-
-  - **cross-link**:
-Object with:
-      - **domain**: Interval [min, max]
-      - **list**: One of 'OrangeRed', 'PurpleBlue', 'BluePurple', 'Oranges', 'BlueGreen', 'YellowOrangeBrown', 'YellowGreen', 'Reds', 'RedPurple', 'Greens', 'YellowGreenBlue', 'Purples', 'GreenBlue', 'Greys', 'YellowOrangeRed', 'PurpleRed', 'Blues', 'PurpleBlueGreen', 'Spectral', 'RedYellowGreen', 'RedBlue', 'PinkYellowGreen', 'PurpleGreen', 'RedYellowBlue', 'BrownWhiteGreen', 'RedGrey', 'PurpleOrange', 'Set2', 'Accent', 'Set1', 'Set3', 'Dark2', 'Paired', 'Pastel2', 'Pastel1', 'Magma', 'Inferno', 'Plasma', 'Viridis', 'Cividis', 'Twilight', 'Rainbow', 'RedWhiteBlue'
-
-  - **element-index**:
-Object with:
-      - **list**: One of 'OrangeRed', 'PurpleBlue', 'BluePurple', 'Oranges', 'BlueGreen', 'YellowOrangeBrown', 'YellowGreen', 'Reds', 'RedPurple', 'Greens', 'YellowGreenBlue', 'Purples', 'GreenBlue', 'Greys', 'YellowOrangeRed', 'PurpleRed', 'Blues', 'PurpleBlueGreen', 'Spectral', 'RedYellowGreen', 'RedBlue', 'PinkYellowGreen', 'PurpleGreen', 'RedYellowBlue', 'BrownWhiteGreen', 'RedGrey', 'PurpleOrange', 'Set2', 'Accent', 'Set1', 'Set3', 'Dark2', 'Paired', 'Pastel2', 'Pastel1', 'Magma', 'Inferno', 'Plasma', 'Viridis', 'Cividis', 'Twilight', 'Rainbow', 'RedWhiteBlue'
-
-  - **element-symbol**:
-Object with:
-
-  - **molecule-type**:
-Object with:
-
-  - **polymer-id**:
-Object with:
-      - **list**: One of 'OrangeRed', 'PurpleBlue', 'BluePurple', 'Oranges', 'BlueGreen', 'YellowOrangeBrown', 'YellowGreen', 'Reds', 'RedPurple', 'Greens', 'YellowGreenBlue', 'Purples', 'GreenBlue', 'Greys', 'YellowOrangeRed', 'PurpleRed', 'Blues', 'PurpleBlueGreen', 'Spectral', 'RedYellowGreen', 'RedBlue', 'PinkYellowGreen', 'PurpleGreen', 'RedYellowBlue', 'BrownWhiteGreen', 'RedGrey', 'PurpleOrange', 'Set2', 'Accent', 'Set1', 'Set3', 'Dark2', 'Paired', 'Pastel2', 'Pastel1', 'Magma', 'Inferno', 'Plasma', 'Viridis', 'Cividis', 'Twilight', 'Rainbow', 'RedWhiteBlue'
-
-  - **polymer-index**:
-Object with:
-      - **list**: One of 'OrangeRed', 'PurpleBlue', 'BluePurple', 'Oranges', 'BlueGreen', 'YellowOrangeBrown', 'YellowGreen', 'Reds', 'RedPurple', 'Greens', 'YellowGreenBlue', 'Purples', 'GreenBlue', 'Greys', 'YellowOrangeRed', 'PurpleRed', 'Blues', 'PurpleBlueGreen', 'Spectral', 'RedYellowGreen', 'RedBlue', 'PinkYellowGreen', 'PurpleGreen', 'RedYellowBlue', 'BrownWhiteGreen', 'RedGrey', 'PurpleOrange', 'Set2', 'Accent', 'Set1', 'Set3', 'Dark2', 'Paired', 'Pastel2', 'Pastel1', 'Magma', 'Inferno', 'Plasma', 'Viridis', 'Cividis', 'Twilight', 'Rainbow', 'RedWhiteBlue'
-
-  - **residue-name**:
-Object with:
-
-  - **secondary-structure**:
-Object with:
-
-  - **sequence-id**:
-Object with:
-      - **list**: One of 'OrangeRed', 'PurpleBlue', 'BluePurple', 'Oranges', 'BlueGreen', 'YellowOrangeBrown', 'YellowGreen', 'Reds', 'RedPurple', 'Greens', 'YellowGreenBlue', 'Purples', 'GreenBlue', 'Greys', 'YellowOrangeRed', 'PurpleRed', 'Blues', 'PurpleBlueGreen', 'Spectral', 'RedYellowGreen', 'RedBlue', 'PinkYellowGreen', 'PurpleGreen', 'RedYellowBlue', 'BrownWhiteGreen', 'RedGrey', 'PurpleOrange', 'Set2', 'Accent', 'Set1', 'Set3', 'Dark2', 'Paired', 'Pastel2', 'Pastel1', 'Magma', 'Inferno', 'Plasma', 'Viridis', 'Cividis', 'Twilight', 'Rainbow', 'RedWhiteBlue'
-
-  - **shape-group**:
-Object with:
-
-  - **unit-index**:
-Object with:
-      - **list**: One of 'OrangeRed', 'PurpleBlue', 'BluePurple', 'Oranges', 'BlueGreen', 'YellowOrangeBrown', 'YellowGreen', 'Reds', 'RedPurple', 'Greens', 'YellowGreenBlue', 'Purples', 'GreenBlue', 'Greys', 'YellowOrangeRed', 'PurpleRed', 'Blues', 'PurpleBlueGreen', 'Spectral', 'RedYellowGreen', 'RedBlue', 'PinkYellowGreen', 'PurpleGreen', 'RedYellowBlue', 'BrownWhiteGreen', 'RedGrey', 'PurpleOrange', 'Set2', 'Accent', 'Set1', 'Set3', 'Dark2', 'Paired', 'Pastel2', 'Pastel1', 'Magma', 'Inferno', 'Plasma', 'Viridis', 'Cividis', 'Twilight', 'Rainbow', 'RedWhiteBlue'
-
-  - **uniform**:
-Object with:
-      - **value**: Color as 0xrrggbb
-
-
-- **sizeTheme**: Object { name: string, params: object } where name+params are:
-  - **physical**:
-Object with:
-
-  - **shape-group**:
-Object with:
-
-  - **uniform**:
-Object with:
-      - **value**: Numeric value
-
-
-
-### Default Parameters
-```js
-{
-  "type": {
-    "name": "isosurface",
-    "params": {
-      "alpha": 1,
-      "useFog": true,
-      "highlightColor": 16737945,
-      "selectColor": 3407641,
-      "quality": "auto",
-      "doubleSided": false,
-      "flipSided": false,
-      "flatShaded": false,
-      "isoValue": {
-        "kind": "relative",
-        "stats": {
-          "min": 0,
-          "max": 0,
-          "mean": 0,
-          "sigma": 0
-        },
-        "relativeValue": 2
-      },
-      "sizeFactor": 1,
-      "lineSizeAttenuation": false,
-      "visuals": [
-        "solid"
-      ]
-    }
-  },
-  "colorTheme": {
-    "name": "uniform",
-    "params": {
-      "value": 13421772
-    }
-  },
-  "sizeTheme": {
-    "name": "uniform",
-    "params": {
-      "value": 1
-    }
-  }
-}
-```
-----------------------------
-## <a name="ms-plugin-focus-loci-on-select"></a>ms-plugin.focus-loci-on-select :: Root -> Behavior
-
-### Parameters
-- **minRadius**: Numeric value
-- **extraRadius**: Numeric value *(Value added to the boundning sphere radius of the Loci.)*
-
-### Default Parameters
-```js
-{
-  "minRadius": 10,
-  "extraRadius": 4
-}
-```
-----------------------------
-## <a name="ms-plugin-pdbe-structure-quality-report-prop"></a>ms-plugin.pdbe-structure-quality-report-prop :: Root -> Behavior
-
-### Parameters
-- **autoAttach**: true/false
-
-### Default Parameters
-```js
-{
-  "autoAttach": false
-}
-```
-----------------------------
-## <a name="ms-plugin-rcsb-assembly-symmetry-prop"></a>ms-plugin.rcsb-assembly-symmetry-prop :: Root -> Behavior
-
-### Parameters
-- **autoAttach**: true/false
-
-### Default Parameters
-```js
-{
-  "autoAttach": false
-}
-```
-----------------------------
-## <a name="ms-plugin-structure-animation"></a>ms-plugin.structure-animation :: Root -> Behavior
-
-### Parameters
-- **rotate**: true/false
-- **rotateValue**: Numeric value
-- **explode**: true/false
-- **explodeValue**: Numeric value
-
-### Default Parameters
-```js
-{
-  "rotate": false,
-  "rotateValue": 0,
-  "explode": false,
-  "explodeValue": 0
-}
-```
-----------------------------
-## <a name="ms-plugin-scene-labels"></a>ms-plugin.scene-labels :: Root -> Behavior
-
-### Parameters
-- **alpha**: Numeric value
-- **useFog**: true/false
-- **highlightColor**: Color as 0xrrggbb
-- **selectColor**: Color as 0xrrggbb
-- **quality**: One of 'custom', 'auto', 'highest', 'higher', 'high', 'medium', 'low', 'lower', 'lowest'
-- **fontFamily**: One of 'sans-serif', 'monospace', 'serif', 'cursive'
-- **fontQuality**: One of '0', '1', '2', '3', '4'
-- **fontStyle**: One of 'normal', 'italic', 'oblique'
-- **fontVariant**: One of 'normal', 'small-caps'
-- **fontWeight**: One of 'normal', 'bold'
-- **sizeFactor**: Numeric value
-- **borderWidth**: Numeric value
-- **borderColor**: Color as 0xrrggbb
-- **offsetX**: Numeric value
-- **offsetY**: Numeric value
-- **offsetZ**: Numeric value
-- **background**: true/false
-- **backgroundMargin**: Numeric value
-- **backgroundColor**: Color as 0xrrggbb
-- **backgroundOpacity**: Numeric value
-- **attachment**: One of 'bottom-left', 'bottom-center', 'bottom-right', 'middle-left', 'middle-center', 'middle-right', 'top-left', 'top-center', 'top-right'
-- **levels**: Array of 'structure', 'polymer', 'ligand'
-
-### Default Parameters
-```js
-{
-  "alpha": 1,
-  "useFog": true,
-  "highlightColor": 16737945,
-  "selectColor": 3407641,
-  "quality": "auto",
-  "fontFamily": "sans-serif",
-  "fontQuality": 3,
-  "fontStyle": "normal",
-  "fontVariant": "normal",
-  "fontWeight": "normal",
-  "sizeFactor": 1,
-  "borderWidth": 0,
-  "borderColor": 8421504,
-  "offsetX": 0,
-  "offsetY": 0,
-  "offsetZ": 0,
-  "background": true,
-  "backgroundMargin": 0.2,
-  "backgroundColor": 16775930,
-  "backgroundOpacity": 0.9,
-  "attachment": "middle-center",
-  "levels": []
-}
-```
-----------------------------

docs/volume-server/README.md

@@ -1,86 +0,0 @@
-What is VolumeServer
-=====================
-
-VolumeServer is a service for accessing subsets of volumetric density data. It automatically downsamples the data depending on the volume of the requested region to reduce the bandwidth requirements and provide near-instant access to even the largest data sets.
-
-It uses the text based CIF and BinaryCIF formats to deliver the data to the client. 
-
-For quick info about the benefits of using the server, check out the [examples](examples.md).
-
-Installing and Running
-=====================
-
-Requires nodejs 8+.
-
-## From GitHub
-
-```
-git clone https://github.com/molstar/molstar
-npm install
-```
-
-Afterwards, build the project source:
-
-```
-npm run build-tsc
-```
-
-and run the server by 
-
-```
-node lib/commonjs/servers/volume/server
-```
-
-## From NPM
-
-```
-npm install --production molstar
-./volume-server 
-```
-
-(or ``node node_modules\.bin\volume-server`` in Windows).
-
-The NPM package contains all the tools mentioned here as "binaries":
-
-- ``volume-server``
-- ``volume-server-pack``
-- ``volume-server-query``
-
-
-### Production use
-
-In production it is required to use a service that will keep the server running, such as [forever.js](https://github.com/foreverjs/forever).
-
-
-### Memory issues
-
-Sometimes nodejs might run into problems with memory. This is usually resolved by adding the ``--max-old-space-size=8192`` parameter.
-
-
-## Preparing the Data
-
-For the server to work, CCP4/MAP (models 0, 1, 2 are supported) input data need to be converted into a custom block format. 
-To achieve this, use the ``pack`` application (``node lib/commonjs/servers/volume/pack`` or ``volume-server-pack`` binary from the NPM package).
-
-## Local Mode
-
-The program  ``lib/commonjs/servers/volume/pack`` (``volume-server-query`` in NPM package) can be used to query the data without running a http server.
-
-## Navigating the Source Code
-
-The source code is split into 2 mains parts: ``pack`` and ``server``:
-
-- The ``pack`` part provides the means of converting CCP4 files into the internal block format.
-- The ``server`` includes
-  - ``query``: the main part of the server that handles a query. ``execute.ts`` is the "entry point".
-  - ``algebra``: linear, "coordinate", and "box" algebra provides the means for calculations necessary to concent a user query into a menaningful response.
-  - API wrapper that handles the requests.
-
-Consuming the Data 
-==================
-
-The data can be consumed in any (modern) browser using the [ciftools library](https://github.com/molstar/ciftools) (or any other piece of code that can read text or binary CIF).
-
-The [Data Format](DataFormat.md) document gives a detailed description of the server response format.
-
-As a reference/example of the server usage is available in Mol* ``mol-plugin`` module.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "molstar",
-  "version": "4.0.0-beta.0",
+  "version": "4.10.0",
   "description": "A comprehensive macromolecular library.",
   "homepage": "https://github.com/molstar/molstar#readme",
   "repository": {
@@ -104,78 +104,103 @@
     "Dominik Tichy <tichydominik451@gmail.com>",
     "Yana Rose <yana.v.rose@gmail.com>",
     "Yakov Pechersky <ffxen158@gmail.com>",
-    "Christian Dominguez <christian.99dominguez@gmail.com>"
+    "Christian Dominguez <christian.99dominguez@gmail.com>",
+    "Cai Huiyu <szmun.caihy@gmail.com>",
+    "Ryan DiRisio <rjdiris@gmail.com>",
+    "Dušan Veľký <dvelky@mail.muni.cz>",
+    "Neli Fonseca <neli@ebi.ac.uk>",
+    "Paul Pillot <paul.pillot@tandemai.com>",
+    "Herman Bergwerf <post@hbergwerf.nl>",
+    "Eric E <etongfu@outlook.com>",
+    "Xavier Martinez <xavier.martinez.xm@gmail.com>",
+    "Alex Chan <smalldirkalex@gmail.com>",
+    "Simeon Borko <simeon.borko@gmail.com>"
   ],
   "license": "MIT",
   "devDependencies": {
     "@types/cors": "^2.8.17",
     "@types/gl": "^6.0.5",
-    "@types/jpeg-js": "^0.3.7",
-    "@types/pngjs": "^6.0.4",
-    "@types/jest": "^29.5.11",
-    "@types/react": "^18.2.47",
-    "@types/react-dom": "^18.2.18",
-    "@typescript-eslint/eslint-plugin": "^6.18.0",
-    "@typescript-eslint/parser": "^6.18.0",
+    "@types/jest": "^29.5.14",
+    "@types/pngjs": "^6.0.5",
+    "@types/react": "^18.3.16",
+    "@types/react-dom": "^18.3.5",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
     "benchmark": "^2.1.4",
-    "concurrently": "^8.2.2",
-    "cpx2": "^7.0.1",
-    "crypto-browserify": "^3.12.0",
-    "css-loader": "^6.8.1",
-    "eslint": "^8.56.0",
+    "concurrently": "^9.1.0",
+    "cpx2": "^8.0.0",
+    "crypto-browserify": "^3.12.1",
+    "css-loader": "^7.1.2",
+    "eslint": "^8.57.1",
     "extra-watch-webpack-plugin": "^1.0.3",
     "file-loader": "^6.2.0",
     "fs-extra": "^11.2.0",
     "http-server": "^14.1.1",
     "jest": "^29.7.0",
-    "mini-css-extract-plugin": "^2.7.6",
+    "jpeg-js": "^0.4.4",
+    "mini-css-extract-plugin": "^2.9.2",
     "path-browserify": "^1.0.1",
     "raw-loader": "^4.0.2",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
-    "sass": "^1.69.7",
-    "sass-loader": "^13.3.3",
-    "simple-git": "^3.22.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "sass": "^1.83.0",
+    "sass-loader": "^16.0.4",
+    "simple-git": "^3.27.0",
     "stream-browserify": "^3.0.0",
-    "style-loader": "^3.3.3",
-    "ts-jest": "^29.1.1",
-    "typescript": "^5.3.3",
-    "webpack": "^5.89.0",
+    "style-loader": "^4.0.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.7.2",
+    "webpack": "^5.97.1",
     "webpack-cli": "^5.1.4"
   },
   "dependencies": {
-    "@types/argparse": "^2.0.14",
+    "@types/argparse": "^2.0.17",
     "@types/benchmark": "^2.1.5",
     "@types/compression": "1.7.5",
-    "@types/express": "^4.17.21",
-    "@types/node": "^18.19.4",
-    "@types/node-fetch": "^2.6.10",
-    "@types/swagger-ui-dist": "3.30.4",
+    "@types/express": "^5.0.0",
+    "@types/node": "^18.19.68",
+    "@types/node-fetch": "^2.6.12",
+    "@types/swagger-ui-dist": "3.30.5",
     "argparse": "^2.0.1",
-    "body-parser": "^1.20.2",
-    "compression": "^1.7.4",
+    "compression": "^1.7.5",
     "cors": "^2.8.5",
-    "express": "^4.18.2",
+    "express": "^5.0.1",
     "h264-mp4-encoder": "^1.0.12",
-    "immer": "^10.0.3",
-    "immutable": "^4.3.4",
-    "io-ts": "^2.2.21",
+    "immer": "^10.1.1",
+    "immutable": "^5.0.3",
+    "io-ts": "^2.2.22",
     "node-fetch": "^2.7.0",
     "react-markdown": "^9.0.1",
     "rxjs": "^7.8.1",
-    "swagger-ui-dist": "^5.10.5",
-    "tslib": "^2.6.2",
+    "swagger-ui-dist": "^5.18.2",
+    "tslib": "^2.8.1",
     "util.promisify": "^1.1.2",
     "xhr2": "^0.2.1"
   },
   "peerDependencies": {
-    "react": "^18.1.0 || ^17.0.2 || ^16.14.0",
-    "react-dom": "^18.1.0 || ^17.0.2 || ^16.14.0"
-  },
-  "optionalDependencies": {
+    "@google-cloud/storage": "^7.14.0",
     "canvas": "^2.11.2",
     "gl": "^6.0.2",
     "jpeg-js": "^0.4.4",
-    "pngjs": "^6.0.0"
+    "pngjs": "^6.0.0",
+    "react": ">=16.14.0",
+    "react-dom": ">=16.14.0"
+  },
+  "peerDependenciesMeta": {
+    "@google-cloud/storage": {
+      "optional": true
+    },
+    "canvas": {
+      "optional": true
+    },
+    "gl": {
+      "optional": true
+    },
+    "jpeg-js": {
+      "optional": true
+    },
+    "pngjs": {
+      "optional": true
+    }
   }
 }

scripts/deploy.js

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2019-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2019-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -39,6 +39,14 @@ function copyViewer() {
     addAnalytics(path.resolve(viewerDeployPath, 'index.html'));
 }
 
+function copyMe() {
+    console.log('\n###', 'copy me files');
+    const meBuildPath = path.resolve(buildDir, '../build/mesoscale-explorer/');
+    const meDeployPath = path.resolve(localPath, 'me/viewer/');
+    fse.copySync(meBuildPath, meDeployPath, { overwrite: true });
+    addAnalytics(path.resolve(meDeployPath, 'index.html'));
+}
+
 function copyDemos() {
     console.log('\n###', 'copy demos files');
     const lightingBuildPath = path.resolve(buildDir, '../build/examples/lighting/');
@@ -53,8 +61,13 @@ function copyDemos() {
 }
 
 function copyFiles() {
-    copyViewer();
-    copyDemos();
+    try {
+        copyViewer();
+        copyMe();
+        copyDemos();
+    } catch (e) {
+        console.error(e);
+    }
 }
 
 if (!fs.existsSync(localPath)) {

src/apps/docking-viewer/viewport.tsx

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2020-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2020-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -44,15 +44,6 @@ function occlusionStyle(plugin: PluginContext) {
         },
         postprocessing: {
             ...plugin.canvas3d!.props.postprocessing,
-            occlusion: { name: 'on', params: {
-                blurKernelSize: 15,
-                multiScale: { name: 'off', params: {} },
-                radius: 5,
-                bias: 0.8,
-                samples: 32,
-                resolutionScale: 1,
-                color: Color(0x000000),
-            } },
             outline: { name: 'on', params: {
                 scale: 1.0,
                 threshold: 0.33,

src/apps/mesoscale-explorer/app.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2022-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2022-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -30,6 +30,7 @@ import { Asset } from '../../mol-util/assets';
 import { AnimateCameraSpin } from '../../mol-plugin-state/animation/built-in/camera-spin';
 import { AnimateCameraRock } from '../../mol-plugin-state/animation/built-in/camera-rock';
 import { AnimateStateSnapshots } from '../../mol-plugin-state/animation/built-in/state-snapshots';
+import { MesoViewportSnapshotDescription } from './ui/entities';
 
 export { PLUGIN_VERSION as version } from '../../mol-plugin/version';
 export { setDebugMode, setProductionMode, setTimingMode, consoleStats } from '../../mol-util/debug';
@@ -46,7 +47,9 @@ export type ExampleEntry = {
 export type MesoscaleExplorerState = {
     examples?: ExampleEntry[],
     graphicsMode: GraphicsMode,
+    illumination: boolean,
     stateRef?: string,
+    driver?: any,
     stateCache: { [k: string]: any },
 }
 
@@ -76,6 +79,8 @@ const DefaultMesoscaleExplorerOptions = {
     preferWebgl1: PluginConfig.General.PreferWebGl1.defaultValue,
     allowMajorPerformanceCaveat: PluginConfig.General.AllowMajorPerformanceCaveat.defaultValue,
     powerPreference: PluginConfig.General.PowerPreference.defaultValue,
+    resolutionMode: PluginConfig.General.ResolutionMode.defaultValue,
+    illumination: false,
 
     viewportShowExpand: PluginConfig.Viewport.ShowExpand.defaultValue,
     viewportShowControls: PluginConfig.Viewport.ShowControls.defaultValue,
@@ -90,7 +95,8 @@ const DefaultMesoscaleExplorerOptions = {
     emdbProvider: PluginConfig.Download.DefaultEmdbProvider.defaultValue,
     saccharideCompIdMapType: 'default' as SaccharideCompIdMapType,
 
-    graphicsMode: 'quality' as GraphicsMode
+    graphicsMode: 'quality' as GraphicsMode,
+    driver: undefined
 };
 type MesoscaleExplorerOptions = typeof DefaultMesoscaleExplorerOptions;
 
@@ -170,6 +176,9 @@ export class MesoscaleExplorer {
                     right: RightPanel,
                 },
                 remoteState: 'none',
+                viewport: {
+                    snapshotDescription: MesoViewportSnapshotDescription,
+                }
             },
             config: [
                 [PluginConfig.General.DisableAntialiasing, o.disableAntialiasing],
@@ -179,6 +188,7 @@ export class MesoscaleExplorer {
                 [PluginConfig.General.PreferWebGl1, o.preferWebgl1],
                 [PluginConfig.General.AllowMajorPerformanceCaveat, o.allowMajorPerformanceCaveat],
                 [PluginConfig.General.PowerPreference, o.powerPreference],
+                [PluginConfig.General.ResolutionMode, o.resolutionMode],
                 [PluginConfig.Viewport.ShowExpand, o.viewportShowExpand],
                 [PluginConfig.Viewport.ShowControls, o.viewportShowControls],
                 [PluginConfig.Viewport.ShowSettings, o.viewportShowSettings],
@@ -207,7 +217,12 @@ export class MesoscaleExplorer {
             onBeforeUIRender: async plugin => {
                 let examples: MesoscaleExplorerState['examples'] = undefined;
                 try {
-                    examples = await plugin.fetch({ url: './examples/list.json', type: 'json' }).run();
+                    examples = await plugin.fetch({ url: '../examples/list.json', type: 'json' }).run();
+                    // extend the array with file tour.json if it exists
+                    const tour = await plugin.fetch({ url: '../examples/tour.json', type: 'json' }).run();
+                    if (tour) {
+                        examples = examples?.concat(tour);
+                    }
                 } catch (e) {
                     console.log(e);
                 }
@@ -215,6 +230,8 @@ export class MesoscaleExplorer {
                 (plugin.customState as MesoscaleExplorerState) = {
                     examples,
                     graphicsMode: o.graphicsMode,
+                    illumination: o.illumination,
+                    driver: o.driver,
                     stateCache: {},
                 };
 

src/apps/mesoscale-explorer/behavior/camera.ts

@@ -11,10 +11,12 @@ import { ButtonsType, ModifiersKeys } from '../../../mol-util/input/input-observ
 import { Binding } from '../../../mol-util/binding';
 import { PluginCommands } from '../../../mol-plugin/commands';
 import { Sphere3D } from '../../../mol-math/geometry';
+import { StructureElement } from '../../../mol-model/structure';
 
 const B = ButtonsType;
 const M = ModifiersKeys;
 const Trigger = Binding.Trigger;
+const Key = Binding.TriggerKey;
 
 const DefaultMesoFocusLociBindings = {
     clickCenter: Binding([
@@ -23,13 +25,14 @@ const DefaultMesoFocusLociBindings = {
     clickCenterFocus: Binding([
         Trigger(B.Flag.Secondary, M.create()),
     ], 'Camera center and focus', 'Click element using ${triggers}'),
+    keyCenterOnly: Binding([Key('C')], 'Center Only Toggle', 'Press ${triggers}'),
 };
-const MesoFocusLociParams = {
+
+export const MesoFocusLociParams = {
     minRadius: PD.Numeric(8, { min: 1, max: 50, step: 1 }),
     extraRadius: PD.Numeric(4, { min: 1, max: 50, step: 1 }, { description: 'Value added to the bounding-sphere radius of the Loci' }),
     durationMs: PD.Numeric(250, { min: 0, max: 1000, step: 1 }, { description: 'Camera transition duration' }),
     centerOnly: PD.Boolean(true, { description: 'Keep current camera distance' }),
-
     bindings: PD.Value(DefaultMesoFocusLociBindings, { isHidden: true }),
 };
 type MesoFocusLociProps = PD.Values<typeof MesoFocusLociParams>
@@ -47,25 +50,45 @@ export const MesoFocusLoci = PluginBehavior.create<MesoFocusLociProps>({
                 const sphere = Loci.getBoundingSphere(loci) || Sphere3D();
 
                 const { clickCenter, clickCenterFocus } = this.params.bindings;
-                const { durationMs, extraRadius, minRadius } = this.params;
+                const { durationMs, extraRadius, minRadius, centerOnly } = this.params;
                 const radius = Math.max(sphere.radius + extraRadius, minRadius);
 
                 if (Binding.match(clickCenter, button, modifiers)) {
+                    // left mouse button
                     if (Loci.isEmpty(current.loci)) {
                         PluginCommands.Camera.Reset(this.ctx, { });
                         return;
                     }
-
-                    const snapshot = canvas3d.camera.getCenter(sphere.center);
-                    canvas3d.requestCameraReset({ durationMs, snapshot });
+                    if (StructureElement.Loci.is(current.loci)) {
+                        if (centerOnly) {
+                            const snapshot = canvas3d.camera.getCenter(sphere.center);
+                            canvas3d.requestCameraReset({ durationMs, snapshot });
+                        } else {
+                            this.ctx.managers.camera.focusSphere(sphere, this.params);
+                        }
+                    }
                 } else if (Binding.match(clickCenterFocus, button, modifiers)) {
+                    // right mouse button
                     if (Loci.isEmpty(current.loci)) {
                         PluginCommands.Camera.Reset(this.ctx, { });
                         return;
                     }
+                    if (centerOnly) {
+                        const snapshot = canvas3d.camera.getCenter(sphere.center, radius);
+                        canvas3d.requestCameraReset({ durationMs, snapshot });
+                    } else {
+                        this.ctx.managers.camera.focusSphere(sphere, this.params);
+                    }
+                }
+            });
 
-                    const snapshot = canvas3d.camera.getCenter(sphere.center, radius);
-                    canvas3d.requestCameraReset({ durationMs, snapshot });
+            this.subscribeObservable(this.ctx.behaviors.interaction.key, ({ code, key, modifiers }) => {
+                if (!this.ctx.canvas3d) return;
+                const b = { ...DefaultMesoFocusLociBindings, ...this.params.bindings };
+                const { centerOnly } = this.params;
+
+                if (Binding.matchKey(b.keyCenterOnly, code, modifiers, key)) {
+                    this.params.centerOnly = !centerOnly;
                 }
             });
         }

src/apps/mesoscale-explorer/behavior/select.ts

@@ -16,12 +16,16 @@ import { StateTreeSpine } from '../../../mol-state/tree/spine';
 import { Representation } from '../../../mol-repr/representation';
 import { MarkerAction } from '../../../mol-util/marker-action';
 import { PluginContext } from '../../../mol-plugin/context';
+import { MesoscaleState, expandAllGroups, getCellDescription, getEveryEntity } from '../data/state';
 
 const B = ButtonsType;
 const M = ModifiersKeys;
 const Trigger = Binding.Trigger;
 
 const DefaultMesoSelectLociBindings = {
+    click: Binding([
+        Trigger(B.Flag.Primary, M.create())
+    ], 'Click', 'Click element using ${triggers}'),
     clickToggleSelect: Binding([
         Trigger(B.Flag.Primary, M.create({ shift: true })),
         Trigger(B.Flag.Primary, M.create({ control: true })),
@@ -63,15 +67,36 @@ export const MesoSelectLoci = PluginBehavior.create<MesoSelectLociProps>({
             this.subscribeObservable(this.ctx.behaviors.interaction.click, ({ current, button, modifiers }) => {
                 if (!this.ctx.canvas3d || this.ctx.isBusy) return;
 
-                const { clickToggleSelect } = this.params.bindings;
+                const { click, clickToggleSelect } = this.params.bindings;
                 if (Binding.match(clickToggleSelect, button, modifiers)) {
                     if (Loci.isEmpty(current.loci)) {
                         this.ctx.managers.interactivity.lociSelects.deselectAll();
                         return;
                     }
-
                     const loci = Loci.normalize(current.loci, modifiers.control ? 'entity' : 'chain');
                     this.ctx.managers.interactivity.lociSelects.toggle({ loci }, false);
+                    if (StructureElement.Loci.is(current.loci)) {
+                        const cell = this.ctx.helpers.substructureParent.get(current.loci.structure);
+                        const d = getCellDescription(cell!);
+                        MesoscaleState.set(this.ctx, { focusInfo: `${d}` });
+                    }
+                }
+                if (Binding.match(click, button, modifiers)) {
+                    if (Loci.isEmpty(current.loci)) {
+                        MesoscaleState.set(this.ctx, { focusInfo: '', filter: '' });
+                        return;
+                    }
+                    const snapshotKey = current.repr?.props?.snapshotKey?.trim() ?? '';
+                    if (snapshotKey) {
+                        this.ctx.managers.snapshot.applyKey(snapshotKey);
+                    } else {
+                        if (StructureElement.Loci.is(current.loci)) {
+                            const cell = this.ctx.helpers.substructureParent.get(current.loci.structure);
+                            const d = getCellDescription(cell!);
+                            MesoscaleState.set(this.ctx, { focusInfo: `${d}`, filter: `${cell?.obj?.label}` });
+                            expandAllGroups(this.ctx);
+                        }
+                    }
                 }
             });
             this.ctx.managers.interactivity.lociSelects.addProvider(this.lociMarkProvider);
@@ -87,22 +112,41 @@ export const MesoSelectLoci = PluginBehavior.create<MesoSelectLociProps>({
                         this.ctx.managers.interactivity.lociHighlights.clearHighlights();
                         return;
                     }
-
-                    if (modifiers.control) {
-                        this.ctx.managers.interactivity.lociHighlights.highlightOnly({ repr: current.repr, loci: EveryLoci }, false);
-                    } else {
-                        const loci = Loci.normalize(current.loci, 'chain');
-                        this.ctx.managers.interactivity.lociHighlights.highlightOnly({ repr: current.repr, loci }, false);
+                    if (StructureElement.Loci.is(current.loci)) {
+                        if (modifiers.control) {
+                            this.ctx.managers.interactivity.lociHighlights.highlightOnly({ repr: current.repr, loci: EveryLoci }, false);
+                        } else {
+                            const loci = Loci.normalize(current.loci, 'chain');
+                            this.ctx.managers.interactivity.lociHighlights.highlightOnly({ repr: current.repr, loci }, false);
+                        }
                     }
                 }
 
                 if (Loci.isEmpty(current.loci)) {
                     this.ctx.behaviors.labels.highlight.next({ labels: [] });
+                    this.ctx.canvas3d?.mark({ loci: EveryLoci }, MarkerAction.RemoveHighlight);
                 } else {
                     const labels: string[] = [];
                     if (StructureElement.Loci.is(current.loci)) {
                         const cell = this.ctx.helpers.substructureParent.get(current.loci.structure);
-                        labels.push(cell?.obj?.label || 'Unknown');
+                        const d = getCellDescription(cell!);
+                        labels.push(d);
+                    } else {
+                        const loci = Loci.normalize(current.loci, this.ctx.managers.interactivity.props.granularity);
+                        if (loci.kind === 'group-loci') {
+                            if ('shape' in current.loci && current.loci.shape.geometry.kind === 'text') {
+                                const qname = current.repr?.props.customText;
+                                // highlight protein with same name
+                                const entities = getEveryEntity(this.ctx, qname);
+                                for (const r of entities) {
+                                    const repr = r.obj?.data.repr;
+                                    if (repr) {
+                                        this.ctx.canvas3d?.mark({ repr, loci: EveryLoci }, MarkerAction.Highlight);
+                                    }
+                                }
+                            }
+                            labels.push(loci.shape.getLabel(0, 0));
+                        }
                     }
                     this.ctx.behaviors.labels.highlight.next({ labels });
                 }

src/apps/mesoscale-explorer/data/cellpack/model.ts

@@ -161,15 +161,12 @@ const CellpackStructure = PluginStateTransform.BuiltIn({
 
             const unitsByEntity = getUnitsByEntity(parent);
             const units = unitsByEntity.get(idx) || [];
-            // if (!unitsByEntity.get(idx)) {
-            //     console.log(entities.data.pdbx_description.value(idx));
-            // }
+
             const structure = Structure.create(units);
-
-            const description = entities.data.pdbx_description.value(idx)[0] || 'model';
-            const label = description.split('.').at(-1) || a.label;
-
-            return new PSO.Molecule.Structure(structure, { label, description: `${a.description}` });
+            const description_label = entities.data.pdbx_description.value(idx)[0] || 'model';
+            const label = description_label.split('.').at(-1) || a.label;
+            const description = entities.data.pdbx_parent_entity_id.value(idx) || label;
+            return new PSO.Molecule.Structure(structure, { label, description: description }); // `${a.description}`
         });
     },
     dispose({ b }) {

src/apps/mesoscale-explorer/data/cellpack/preset.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2019-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2019-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  * @author Ludovic Autin <ludovic.autin@gmail.com>
@@ -96,12 +96,12 @@ export async function createCellpackHierarchy(plugin: PluginContext, trajectory:
 
     const compRoot = await state.build()
         .toRoot()
-        .applyOrUpdateTagged('group:comp:', MesoscaleGroup, { ...groupParams, root: true, index: -1, tag: `comp:`, label: 'compartment', color: { type: 'custom', value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1 } }, { tags: 'group:comp:', state: { isCollapsed: false, isHidden: groupParams.hidden } })
+        .apply(MesoscaleGroup, { ...groupParams, root: true, index: -1, tag: 'comp:', label: 'compartment', color: { type: 'custom', illustrative: false, value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: 'group:comp:', state: { isCollapsed: false, isHidden: groupParams.hidden } })
         .commit();
 
     const funcRoot = await state.build()
         .toRoot()
-        .applyOrUpdateTagged('group:func:', MesoscaleGroup, { ...groupParams, root: true, index: -1, tag: `func:`, label: 'function', color: { type: 'custom', value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1 } }, { tags: 'group:func:', state: { isCollapsed: false, isHidden: groupParams.hidden } })
+        .apply(MesoscaleGroup, { ...groupParams, root: true, index: -1, tag: 'func:', label: 'function', color: { type: 'custom', illustrative: false, value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: 'group:func:', state: { isCollapsed: false, isHidden: groupParams.hidden } })
         .commit();
 
     if (entities._rowCount > 1) {
@@ -159,7 +159,7 @@ export async function createCellpackHierarchy(plugin: PluginContext, trajectory:
                     parent.cell!.state.isCollapsed = false;
                     const group = await state.build()
                         .to(parent)
-                        .applyOrUpdateTagged(`group:comp:${n}`, MesoscaleGroup, { ...groupParams, root: parent === compRoot, index: colorIdx, tag: `comp:${n}`, label, color: { type: 'generate', value: color, variability: 20, shift: 0, lightness: 0, alpha: 1 } }, { tags: `comp:${p}`, state: { isCollapsed: true, isHidden: groupParams.hidden } })
+                        .apply(MesoscaleGroup, { ...groupParams, root: parent === compRoot, index: colorIdx, tag: `comp:${n}`, label, color: { type: 'generate', illustrative: false, value: color, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: [`group:comp:${n}`, `comp:${p}`], state: { isCollapsed: true, isHidden: groupParams.hidden } })
                         .commit({ revertOnError: true });
                     compGroups.set(n, group);
                 }
@@ -171,7 +171,7 @@ export async function createCellpackHierarchy(plugin: PluginContext, trajectory:
                 const color = colorIdx !== undefined ? baseFuncColors[colorIdx] : ColorNames.white;
                 const group = await state.build()
                     .to(funcRoot)
-                    .applyOrUpdateTagged(`group:func:${f}`, MesoscaleGroup, { ...groupParams, index: colorIdx, tag: `func:${f}`, label: f, color: { type: 'custom', value: color, variability: 20, shift: 0, lightness: 0, alpha: 1 } }, { tags: 'func:', state: { isCollapsed: true, isHidden: groupParams.hidden } })
+                    .apply(MesoscaleGroup, { ...groupParams, index: colorIdx, tag: `func:${f}`, label: f, color: { type: 'custom', illustrative: false, value: color, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: [`group:func:${f}`, 'func:'], state: { isCollapsed: true, isHidden: groupParams.hidden } })
                     .commit({ revertOnError: true });
                 funcGroups.set(f, group);
             }

src/apps/mesoscale-explorer/data/generic/model.ts

@@ -76,6 +76,7 @@ const StructureFromGeneric = PluginStateTransform.BuiltIn({
     params: {
         instances: PD.Value<GenericInstances<Asset>>(EmptyInstances),
         label: PD.Optional(PD.Text('')),
+        description: PD.Optional(PD.Text('')),
         cellSize: PD.Numeric(500, { min: 0, max: 10000, step: 100 }),
     }
 })({
@@ -111,7 +112,7 @@ const StructureFromGeneric = PluginStateTransform.BuiltIn({
                 structure = assembler.getStructure();
             }
 
-            const props = { label, description: Structure.elementDescription(structure) };
+            const props = { label, description: params.description || Structure.elementDescription(structure) };
             return new SO.Molecule.Structure(structure, props);
         });
     },

src/apps/mesoscale-explorer/data/generic/preset.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2023-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -11,7 +11,7 @@ import { SpacefillRepresentationProvider } from '../../../../mol-repr/structure/
 import { Color } from '../../../../mol-util/color';
 import { utf8Read } from '../../../../mol-io/common/utf8';
 import { Mat3, Quat, Vec3 } from '../../../../mol-math/linear-algebra';
-import { GraphicsMode, MesoscaleGroup, MesoscaleState, getGraphicsModeProps, getMesoscaleGroupParams, updateColors } from '../state';
+import { GraphicsMode, MesoscaleGroup, MesoscaleState, getGraphicsModeProps, getMesoscaleGroupParams } from '../state';
 import { ColorNames } from '../../../../mol-util/color/names';
 import { ShapeRepresentation3D, StructureRepresentation3D } from '../../../../mol-plugin-state/transforms/representation';
 import { ParseCif, ParsePly, ReadFile } from '../../../../mol-plugin-state/transforms/data';
@@ -124,7 +124,7 @@ export async function createGenericHierarchy(plugin: PluginContext, file: Asset.
     async function addGroup(g: GenericGroup, cell: StateObjectSelector, parent: string) {
         const group = await state.build()
             .to(cell)
-            .apply(MesoscaleGroup, { ...groupParams, index: undefined, tag: `${g.root}:${g.id}`, label: g.label || g.id, color: { type: 'custom', value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1 } }, { tags: [`group:${g.root}:${g.id}`, g.root === parent ? `${g.root}:` : `${g.root}:${parent}`], state: { isCollapsed: true, isHidden: groupParams.hidden } })
+            .apply(MesoscaleGroup, { ...groupParams, index: undefined, tag: `${g.root}:${g.id}`, label: g.label || g.id, description: g.description, color: { type: 'custom', illustrative: false, value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: [`group:${g.root}:${g.id}`, g.root === parent ? `${g.root}:` : `${g.root}:${parent}`], state: { isCollapsed: true, isHidden: groupParams.hidden } })
             .commit();
 
         if (g.children) {
@@ -137,7 +137,7 @@ export async function createGenericHierarchy(plugin: PluginContext, file: Asset.
     for (const r of manifest.roots) {
         const root = await state.build()
             .toRoot()
-            .apply(MesoscaleGroup, { ...groupParams, root: true, index: -1, tag: `${r.id}:`, label: r.label || r.id, color: { type: 'custom', value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1 } }, { tags: `group:${r.id}:`, state: { isCollapsed: false, isHidden: groupParams.hidden } })
+            .apply(MesoscaleGroup, { ...groupParams, root: true, index: -1, tag: `${r.id}:`, label: r.label || r.id, description: r.description, color: { type: 'custom', illustrative: false, value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: `group:${r.id}:`, state: { isCollapsed: false, isHidden: groupParams.hidden } })
             .commit();
 
         if (r.children) {
@@ -193,11 +193,12 @@ export async function createGenericHierarchy(plugin: PluginContext, file: Asset.
                 const file = Asset.File(new File([t], ent.file));
 
                 const color = ColorNames.skyblue;
-                const label = ent.label || ent.file.split('.')[0];
+
                 const sizeFactor = ent.sizeFactor || 1;
                 const tags = ent.groups.map(({ id, root }) => `${root}:${id}`);
                 const instances = ent.instances && getAssetInstances(ent.instances);
-
+                const description = ent.description;
+                const label = ent.label || ent.file.split('.')[0];
                 build = build
                     .toRoot()
                     .apply(ReadFile, { file, label, isBinary });
@@ -233,7 +234,7 @@ export async function createGenericHierarchy(plugin: PluginContext, file: Asset.
 
                     build = build
                         .apply(ModelFromTrajectory, { modelIndex: 0 })
-                        .apply(StructureFromGeneric, { instances, label })
+                        .apply(StructureFromGeneric, { instances, label, description })
                         .apply(StructureRepresentation3D, getSpacefillParams(color, sizeFactor, graphicsMode, clipVariant), { tags });
                 } else if (['ply'].includes(info.ext)) {
                     if (['ply'].includes(info.ext)) {
@@ -249,10 +250,6 @@ export async function createGenericHierarchy(plugin: PluginContext, file: Asset.
                 }
             }
             await build.commit();
-
-            const rootId = `${manifest.roots[0].id}:`;
-            const values = { type: 'group-generate', value: ColorNames.white, lightness: 0, alpha: 1 };
-            await updateColors(plugin, values, rootId, '');
         } catch (e) {
             console.error(e);
             plugin.log.error(e);

src/apps/mesoscale-explorer/data/mmcif/model.ts

@@ -186,9 +186,10 @@ const MmcifStructure = PluginStateTransform.BuiltIn({
             } else {
                 structure = Structure.create(units);
             }
-
+            // could also use _struct_ref.pdbx_db_accession to point to uniprot with _struct_ref.db_name == UNP
             const label = entities.data.pdbx_description.value(idx).join(', ') || 'model';
-            return new PSO.Molecule.Structure(structure, { label, description: `${a.description}` });
+            const description = `*Entity id* ${entities.data.id.value(idx)} *src_method* ${entities.data.src_method.value(idx)} *type* ${entities.data.type.value(idx)}`;
+            return new PSO.Molecule.Structure(structure, { label, description: description });
         });
     },
     update({ newParams, oldParams }) {

src/apps/mesoscale-explorer/data/mmcif/preset.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2023-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -114,7 +114,7 @@ export async function createMmcifHierarchy(plugin: PluginContext, trajectory: St
 
     const entRoot = await state.build()
         .toRoot()
-        .applyOrUpdateTagged('group:ent:', MesoscaleGroup, { ...groupParams, root: true, index: -1, tag: `ent:`, label: 'entity', color: { type: 'custom', value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1 } }, { tags: 'group:ent:', state: { isCollapsed: false, isHidden: groupParams.hidden } })
+        .apply(MesoscaleGroup, { ...groupParams, root: true, index: -1, tag: 'ent:', label: 'entity', color: { type: 'custom', illustrative: false, value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: 'group:ent:', state: { isCollapsed: false, isHidden: groupParams.hidden } })
         .commit();
 
     const getEntityType = (i: number) => {
@@ -148,7 +148,7 @@ export async function createMmcifHierarchy(plugin: PluginContext, trajectory: St
             const color = colorIdx !== undefined ? baseEntColors[colorIdx] : ColorNames.white;
             const group = await state.build()
                 .to(entRoot)
-                .applyOrUpdateTagged(`group:ent:${t}`, MesoscaleGroup, { ...groupParams, index: colorIdx, tag: `ent:${t}`, label: t, color: { type: 'generate', value: color, variability: 20, shift: 0, lightness: 0, alpha: 1 } }, { tags: `ent:`, state: { isCollapsed: true, isHidden: groupParams.hidden } })
+                .applyOrUpdateTagged(`group:ent:${t}`, MesoscaleGroup, { ...groupParams, index: colorIdx, tag: `ent:${t}`, label: t, color: { type: 'generate', illustrative: false, value: color, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: `ent:`, state: { isCollapsed: true, isHidden: groupParams.hidden } })
                 .commit({ revertOnError: true });
             entGroups.set(t, group);
         }

src/apps/mesoscale-explorer/data/petworld/model.ts

@@ -39,8 +39,10 @@ const StructureFromPetworld = PluginStateTransform.BuiltIn({
 
             const { frame } = s.model.sourceData.data;
             const pdbx_model = frame.categories.pdbx_model.getField('name')!;
+            const pdbx_description = frame.categories.pdbx_model.getField('description')!;
+            const description = pdbx_description ? pdbx_description.str(params.modelIndex) : Structure.elementDescription(s);
             const label = pdbx_model.str(params.modelIndex);
-            const props = { label, description: Structure.elementDescription(s) };
+            const props = { label, description: description };
             return new SO.Molecule.Structure(s, props);
         });
     },

src/apps/mesoscale-explorer/data/petworld/preset.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2022-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2022-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -97,12 +97,12 @@ export async function createPetworldHierarchy(plugin: PluginContext, trajectory:
 
     const group = await state.build()
         .toRoot()
-        .applyOrUpdateTagged('group:ent:', MesoscaleGroup, { ...groupParams, root: true, index: -1, tag: `ent:`, label: 'entity', color: { type: 'generate', value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1 } }, { tags: 'group:ent:', state: { isCollapsed: false, isHidden: groupParams.hidden } })
+        .apply(MesoscaleGroup, { ...groupParams, root: true, index: -1, tag: `ent:`, label: 'entity', color: { type: 'generate', illustrative: false, value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: ['group:ent:'], state: { isCollapsed: false, isHidden: groupParams.hidden } })
         .commit({ revertOnError: true });
 
     await state.build()
         .to(group)
-        .applyOrUpdateTagged(`group:ent:mem`, MesoscaleGroup, { ...groupParams, index: undefined, tag: `ent:mem`, label: 'Membrane', color: { type: 'uniform', value: ColorNames.lightgrey, variability: 20, shift: 0, lightness: 0, alpha: 1 } }, { tags: `ent:`, state: { isCollapsed: true, isHidden: groupParams.hidden } })
+        .apply(MesoscaleGroup, { ...groupParams, index: undefined, tag: `ent:mem`, label: 'Membrane', color: { type: 'uniform', illustrative: false, value: ColorNames.lightgrey, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: ['group:ent:mem', 'ent:', '__no_group_color__'], state: { isCollapsed: true, isHidden: groupParams.hidden } })
         .commit();
 
     const colors = getDistinctBaseColors(other.length, 0);
@@ -115,13 +115,13 @@ export async function createPetworldHierarchy(plugin: PluginContext, trajectory:
                 build = build
                     .to(cell)
                     .apply(StructureFromPetworld, membrane[i])
-                    .apply(StructureRepresentation3D, getSpacefillParams(ColorNames.lightgrey, graphicsMode), { tags: [`ent:mem`] });
+                    .apply(StructureRepresentation3D, getSpacefillParams(ColorNames.lightgrey, graphicsMode), { tags: ['ent:mem', '__no_group_color__'] });
             }
             for (let i = 0, il = other.length; i < il; ++i) {
                 build = build
                     .to(cell)
                     .apply(StructureFromPetworld, other[i])
-                    .apply(StructureRepresentation3D, getSpacefillParams(colors[i], graphicsMode), { tags: [`ent:`] });
+                    .apply(StructureRepresentation3D, getSpacefillParams(colors[i], graphicsMode), { tags: ['ent:'] });
             }
             await build.commit();
         } catch (e) {

src/apps/mesoscale-explorer/data/state.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2023-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -24,6 +24,7 @@ import { SpacefillRepresentationProvider } from '../../../mol-repr/structure/rep
 import { assertUnreachable } from '../../../mol-util/type-helpers';
 import { MesoscaleExplorerState } from '../app';
 import { saturate } from '../../../mol-math/interpolate';
+import { Material } from '../../../mol-util/material';
 
 function getHueRange(hue: number, variability: number) {
     let min = hue - variability;
@@ -106,11 +107,13 @@ export function getDistinctBaseColors(count: number, shift: number, props?: Part
 
 export const ColorParams = {
     type: PD.Select('generate', PD.arrayToOptions(['generate', 'uniform', 'custom'])),
+    illustrative: PD.Boolean(false, { description: 'Illustrative style', hideIf: p => p.type === 'custom' }),
     value: PD.Color(Color(0xFFFFFF), { hideIf: p => p.type === 'custom' }),
     variability: PD.Numeric(20, { min: 1, max: 180, step: 1 }, { hideIf: p => p.type !== 'generate' }),
     shift: PD.Numeric(0, { min: 0, max: 100, step: 1 }, { hideIf: p => !p.type.includes('generate') }),
     lightness: PD.Numeric(0, { min: -6, max: 6, step: 0.1 }, { hideIf: p => p.type === 'custom' }),
     alpha: PD.Numeric(1, { min: 0, max: 1, step: 0.01 }, { hideIf: p => p.type === 'custom' }),
+    emissive: PD.Numeric(0, { min: 0, max: 1, step: 0.01 }, { hideIf: p => p.type === 'custom' }),
 };
 export type ColorProps = PD.Values<typeof ColorParams>
 
@@ -118,11 +121,13 @@ export const ColorValueParam = PD.Color(Color(0xFFFFFF));
 
 export const RootParams = {
     type: PD.Select('custom', PD.arrayToOptions(['group-generate', 'group-uniform', 'generate', 'uniform', 'custom'])),
+    illustrative: PD.Boolean(false, { description: 'Illustrative style', hideIf: p => p.type === 'custom' }),
     value: PD.Color(Color(0xFFFFFF), { hideIf: p => p.type !== 'uniform' }),
     variability: PD.Numeric(20, { min: 1, max: 180, step: 1 }, { hideIf: p => p.type !== 'group-generate' }),
     shift: PD.Numeric(0, { min: 0, max: 100, step: 1 }, { hideIf: p => !p.type.includes('generate') }),
     lightness: PD.Numeric(0, { min: -6, max: 6, step: 0.1 }, { hideIf: p => p.type === 'custom' }),
     alpha: PD.Numeric(1, { min: 0, max: 1, step: 0.01 }, { hideIf: p => p.type === 'custom' }),
+    emissive: PD.Numeric(0, { min: 0, max: 1, step: 0.01 }, { hideIf: p => p.type === 'custom' }),
 };
 
 export const LightnessParams = {
@@ -130,15 +135,36 @@ export const LightnessParams = {
 };
 export const DimLightness = 6;
 
+export const IllustrativeParams = {
+    illustrative: PD.Boolean(false, { description: 'Illustrative style' }),
+};
+
 export const OpacityParams = {
     alpha: PD.Numeric(1, { min: 0, max: 1, step: 0.01 }),
 };
 
+export const EmissiveParams = {
+    emissive: PD.Numeric(0, { min: 0, max: 1, step: 0.01 }),
+};
+
+export const celShaded = {
+    celShaded: PD.Boolean(false, { description: 'Cel Shading light for stylized rendering of representations' })
+};
+
+export type celShadedProps = PD.Values<typeof celShaded>;
+
+
 export const PatternParams = {
     frequency: PD.Numeric(1, { min: 0, max: 1, step: 0.01 }),
     amplitude: PD.Numeric(1, { min: 0, max: 1, step: 0.01 }),
 };
 
+export const StyleParams = {
+    ignoreLight: PD.Boolean(false, { description: 'Ignore light for stylized rendering of representations' }),
+    materialStyle: Material.getParam(),
+    celShaded: PD.Boolean(false, { description: 'Cel Shading light for stylized rendering of representations' }),
+};
+
 export const LodParams = {
     lodLevels: Spheres.Params.lodLevels,
     cellSize: Spheres.Params.cellSize,
@@ -244,10 +270,12 @@ export const MesoscaleGroupParams = {
     index: PD.Value<number>(-1, { isHidden: true }),
     tag: PD.Value<string>('', { isHidden: true }),
     label: PD.Value<string>('', { isHidden: true }),
+    description: PD.Value<string>('', { isHidden: true }),
     hidden: PD.Boolean(false),
     color: PD.Group(RootParams),
     lightness: PD.Numeric(0, { min: -6, max: 6, step: 0.1 }),
     alpha: PD.Numeric(1, { min: 0, max: 1, step: 0.01 }),
+    emissive: PD.Numeric(0, { min: 0, max: 1, step: 0.01 }),
     lod: PD.Group(LodParams),
     clip: PD.Group(SimpleClipParams),
 };
@@ -264,7 +292,7 @@ export const MesoscaleGroup = PluginStateTransform.BuiltIn({
 })({
     apply({ a, params }, plugin: PluginContext) {
         return Task.create('Apply Mesoscale Group', async () => {
-            return new MesoscaleGroupObject({}, { label: params.label });
+            return new MesoscaleGroupObject({}, { label: params.label, description: params.description });
         });
     },
 });
@@ -311,10 +339,10 @@ export function getLodLevels(graphicsMode: Exclude<GraphicsMode, 'custom'>): Lod
             ];
         case 'ultra':
             return [
-                { minDistance: 1, maxDistance: 2000, overlap: 0, stride: 1, scaleBias: 1 },
-                { minDistance: 2000, maxDistance: 8000, overlap: 0, stride: 10, scaleBias: 3 },
-                { minDistance: 8000, maxDistance: 20000, overlap: 0, stride: 50, scaleBias: 2.5 },
-                { minDistance: 20000, maxDistance: 10000000, overlap: 0, stride: 200, scaleBias: 2 },
+                { minDistance: 1, maxDistance: 5000, overlap: 0, stride: 1, scaleBias: 1 },
+                { minDistance: 5000, maxDistance: 10000, overlap: 0, stride: 10, scaleBias: 3 },
+                { minDistance: 10000, maxDistance: 30000, overlap: 0, stride: 50, scaleBias: 2.5 },
+                { minDistance: 30000, maxDistance: 10000000, overlap: 0, stride: 200, scaleBias: 2 },
             ];
         default:
             assertUnreachable(graphicsMode);
@@ -353,7 +381,10 @@ export const MesoscaleStateParams = {
     filter: PD.Value<string>('', { isHidden: true }),
     graphics: PD.Select('quality', PD.arrayToOptions(['ultra', 'quality', 'balanced', 'performance', 'custom'] as GraphicsMode[])),
     description: PD.Value<string>('', { isHidden: true }),
+    focusInfo: PD.Value<string>('', { isHidden: true }),
     link: PD.Value<string>('', { isHidden: true }),
+    textSizeDescription: PD.Numeric(14, { min: 1, max: 100, step: 1 }, { isHidden: true }),
+    index: PD.Value<number>(-1, { isHidden: true })
 };
 
 export class MesoscaleStateObject extends PSO.Create<MesoscaleState>({ name: 'Mesoscale State', typeClass: 'Object' }) { }
@@ -400,7 +431,8 @@ const MesoscaleState = {
         return ref;
     },
     has(ctx: PluginContext): boolean {
-        return !!(ctx.customState as MesoscaleExplorerState).stateRef;
+        const ref = (ctx.customState as MesoscaleExplorerState).stateRef || '';
+        return ctx.state.data.cells.has(ref) ? true : false;
     },
 };
 
@@ -474,6 +506,7 @@ function getFilterMatcher(filter: string) {
 }
 
 export function getFilteredEntities(plugin: PluginContext, tag: string, filter: string) {
+    if (!filter) return getEntities(plugin, tag);
     const matcher = getFilterMatcher(filter);
     return getEntities(plugin, tag).filter(c => getEntityLabel(plugin, c).match(matcher) !== null);
 }
@@ -491,22 +524,72 @@ export function getAllEntities(plugin: PluginContext, tag?: string) {
 }
 
 export function getAllFilteredEntities(plugin: PluginContext, tag: string, filter: string) {
+    if (!filter) return getAllEntities(plugin, tag);
     const matcher = getFilterMatcher(filter);
     return getAllEntities(plugin, tag).filter(c => getEntityLabel(plugin, c).match(matcher) !== null);
 }
 
+export function getEveryEntity(plugin: PluginContext, filter?: string, tag?: string) {
+    if (filter) {
+        const matcher = getFilterMatcher(filter);
+        return getAllEntities(plugin, tag).filter(c => getEntityLabel(plugin, c).match(matcher) !== null);
+    } else {
+        return getAllEntities(plugin, tag);
+    }
+}
+
 export function getEntityLabel(plugin: PluginContext, cell: StateObjectCell) {
     return StateObjectRef.resolve(plugin.state.data, cell.transform.parent)?.obj?.label || 'Entity';
 }
 
-//
+export function getCellDescription(cell: StateObjectCell) {
+    // markdown style for description
+    return '**' + cell?.obj?.label + '**\n\n' + cell?.obj?.description;
+}
+
+export function getEntityDescription(plugin: PluginContext, cell: StateObjectCell) {
+    const s = StateObjectRef.resolve(plugin.state.data, cell.transform.parent);
+    const d = getCellDescription(s!);
+    return d;
+}
+
+export async function updateStyle(plugin: PluginContext, options: { ignoreLight: boolean, material: Material, celShaded: boolean, illustrative: boolean }) {
+    const update = plugin.state.data.build();
+    const { ignoreLight, material, celShaded, illustrative } = options;
+
+    const entities = getAllEntities(plugin);
+
+    for (let j = 0; j < entities.length; ++j) {
+        update.to(entities[j]).update(old => {
+            if (old.type) {
+                const value = old.colorTheme.name === 'illustrative'
+                    ? old.colorTheme.params.style.params.value
+                    : old.colorTheme.params.value;
+                const lightness = old.colorTheme.name === 'illustrative'
+                    ? old.colorTheme.params.style.params.lightness
+                    : old.colorTheme.params.lightness;
+                if (illustrative) {
+                    old.colorTheme = { name: 'illustrative', params: { style: { name: 'uniform', params: { value, lightness } } } };
+                } else {
+                    old.colorTheme = { name: 'uniform', params: { value, lightness } };
+                }
+                old.type.params.ignoreLight = ignoreLight;
+                old.type.params.material = material;
+                old.type.params.celShaded = celShaded;
+            }
+        });
+    }
+
+    await update.commit();
+};
 
 export async function updateColors(plugin: PluginContext, values: PD.Values, tag: string, filter: string) {
     const update = plugin.state.data.build();
-    const { type, value, shift, lightness, alpha } = values;
-
+    const { type, illustrative, value, shift, lightness, alpha, emissive } = values;
     if (type === 'group-generate' || type === 'group-uniform') {
-        const groups = getAllLeafGroups(plugin, tag);
+        const leafGroups = getAllLeafGroups(plugin, tag);
+        const rootLeafGroups = getRoots(plugin).filter(g => g.params?.values.tag === tag && getEntities(plugin, g.params?.values.tag).length > 0);
+        const groups = [...leafGroups, ...rootLeafGroups];
         const baseColors = getDistinctBaseColors(groups.length, shift);
 
         for (let i = 0; i < groups.length; ++i) {
@@ -523,24 +606,31 @@ export async function updateColors(plugin: PluginContext, values: PD.Values, tag
                 const c = type === 'group-generate' ? groupColors[j] : baseColors[i];
                 update.to(entities[j]).update(old => {
                     if (old.type) {
-                        old.colorTheme.params.value = c;
-                        old.colorTheme.params.lightness = lightness;
+                        if (illustrative) {
+                            old.colorTheme = { name: 'illustrative', params: { style: { name: 'uniform', params: { value: c, lightness: lightness } } } };
+                        } else {
+                            old.colorTheme = { name: 'uniform', params: { value: c, lightness: lightness } };
+                        }
                         old.type.params.alpha = alpha;
                         old.type.params.xrayShaded = alpha < 1 ? 'inverted' : false;
+                        old.type.params.emissive = emissive;
                     } else if (old.coloring) {
                         old.coloring.params.color = c;
                         old.coloring.params.lightness = lightness;
                         old.alpha = alpha;
                         old.xrayShaded = alpha < 1 ? true : false;
+                        old.emissive = emissive;
                     }
                 });
             }
 
             update.to(g.transform.ref).update(old => {
                 old.color.type = type === 'group-generate' ? 'generate' : 'uniform';
+                old.color.illustrative = illustrative;
                 old.color.value = baseColors[i];
                 old.color.lightness = lightness;
                 old.color.alpha = alpha;
+                old.color.emissive = emissive;
             });
         }
     } else if (type === 'generate' || type === 'uniform') {
@@ -555,15 +645,20 @@ export async function updateColors(plugin: PluginContext, values: PD.Values, tag
             const c = type === 'generate' ? groupColors[j] : value;
             update.to(entities[j]).update(old => {
                 if (old.type) {
-                    old.colorTheme.params.value = c;
-                    old.colorTheme.params.lightness = lightness;
+                    if (illustrative) {
+                        old.colorTheme = { name: 'illustrative', params: { style: { name: 'uniform', params: { value: c, lightness: lightness } } } };
+                    } else {
+                        old.colorTheme = { name: 'uniform', params: { value: c, lightness: lightness } };
+                    }
                     old.type.params.alpha = alpha;
                     old.type.params.xrayShaded = alpha < 1 ? 'inverted' : false;
+                    old.type.params.emissive = emissive;
                 } else if (old.coloring) {
                     old.coloring.params.color = c;
                     old.coloring.params.lightness = lightness;
                     old.alpha = alpha;
                     old.xrayShaded = alpha < 1 ? true : false;
+                    old.emissive = emissive;
                 }
             });
         }
@@ -572,9 +667,11 @@ export async function updateColors(plugin: PluginContext, values: PD.Values, tag
         for (const o of others) {
             update.to(o).update(old => {
                 old.color.type = type === 'generate' ? 'custom' : 'uniform';
+                old.color.illustrative = illustrative;
                 old.color.value = value;
                 old.color.lightness = lightness;
                 old.color.alpha = alpha;
+                old.color.emissive = emissive;
             });
         }
     }
@@ -589,3 +686,4 @@ export function expandAllGroups(plugin: PluginContext) {
         }
     }
 };
+

src/apps/mesoscale-explorer/embedded.html

@@ -0,0 +1,79 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
+    <style>
+        * {
+            margin: 0;
+            padding: 0;
+            box-sizing: border-box;
+        }
+        html, body {
+            width: 100%;
+            height: 100%;
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            justify-content: flex-start;
+            overflow: hidden;
+        }
+        #controls {
+            display: flex;
+            justify-content: center;
+            width: 800px;
+            margin-bottom: 10px;
+            z-index: 1;
+        }
+        button {
+            margin: 5px;
+            padding: 10px 20px;
+            font-size: 14px;
+            cursor: pointer;
+        }
+        #viewer-container {
+            width: 100%;
+            height: 600px;
+            border: 1px solid #ccc;
+            position: relative;
+        }
+    </style>
+    <link rel="stylesheet" type="text/css" href="./molstar.css" />
+</head>
+<body>
+    <div id="controls">
+        <button onclick="loadExample('cellpack-hiv1')">Load HIV-1 Example</button>
+        <button onclick="loadExample('machineryoflife-tour')">Load Machinery of Life Tour</button>
+        <button onclick="loadExample('petworld-synvesicle')">Load Synaptic Vesicle Example</button>
+    </div>
+    <div id="viewer-container">
+        <div id="meso-viewer" style="position: relative; width: 100%; height: 400px;"></div>
+    </div>
+
+    <script src="./molstar.js"></script>
+    <script type="text/javascript">
+        let mesoExplorer;
+
+        function loadExample(example) {
+            if (mesoExplorer) {
+                mesoExplorer.loadExample(example);
+            }
+        }
+
+        molstar.MesoscaleExplorer.create('meso-viewer', {
+            layoutShowControls: false,
+            viewportShowExpand: false,
+	        layoutIsExpanded: false,
+            powerPreference: 'high-performance',
+            graphicsMode: 'quality'
+        }).then(me => {
+            mesoExplorer = me;
+            me.loadExample('cellpack-hiv1');  // Load the default example on page load
+
+            window.addEventListener('unload', () => {
+                me.dispose();
+            });
+        });
+    </script>
+</body>
+</html>

src/apps/mesoscale-explorer/index.html

@@ -4,6 +4,7 @@
         <meta charset="utf-8" />
         <meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
         <link rel="icon" href="./favicon.ico" type="image/x-icon">
+        <link rel="stylesheet" href="../extras/driver.css"/>
         <title>Mol* Mesoscale Explorer</title>
         <style>
             * {
@@ -38,8 +39,11 @@
     </head>
     <body>
         <div id="app"></div>
+        <script src="../extras/driver.js.iife.js"></script>
         <script type="text/javascript" src="./molstar.js"></script>
         <script type="text/javascript">
+            const driver = window.driver ? window.driver.js.driver() : undefined;
+
             function getParam(name, regex) {
                 var r = new RegExp(name + '=' + '(' + regex + ')[&]?', 'i');
                 return decodeURIComponent(((window.location.search || '').match(r) || [])[1] || '');
@@ -56,6 +60,8 @@
             var allowMajorPerformanceCaveat = getParam('allow-major-performance-caveat', '[^&]+').trim() === '1';
             var powerPreference = getParam('power-preference', '[^&]+').trim().toLowerCase();
             var graphicsMode = getParam('graphics-mode', '[^&]+').trim().toLowerCase();
+            var illumination = getParam('illumination', '[^&]+').trim() === '1';
+            var resolutionMode = getParam('resolution-mode', '[^&]+').trim().toLowerCase();
 
             molstar.MesoscaleExplorer.create('app', {
                 layoutShowControls: !hideControls,
@@ -64,6 +70,9 @@
                 allowMajorPerformanceCaveat: allowMajorPerformanceCaveat,
                 powerPreference: powerPreference || 'high-performance',
                 graphicsMode: graphicsMode || 'quality',
+                illumination: illumination,
+                resolutionMode: resolutionMode || 'auto',
+                driver: driver
             }).then(me => {
                 var example = getParam('example', '[^&]+').trim();
                 if (example) {
@@ -89,7 +98,6 @@
                     me.loadPdbDev(pdbdev);
                     return;
                 }
-
                 window.addEventListener('unload', () => {
                     // to aid GC
                     me.dispose();
@@ -98,4 +106,4 @@
         </script>
         <!-- __MOLSTAR_ANALYTICS__ -->
     </body>
-</html>
+</html>

src/apps/mesoscale-explorer/style.scss

@@ -1,3 +1,5 @@
+@use "sass:color";
+
 $default-background:         #2D3E50;
 $font-color:                 #EDF1F2;
 $hover-font-color:           #3B9AD9;
@@ -16,14 +18,15 @@ $log-error:            #FD354B;
 $logo-background: rgba(0,0,0,0.75);
 
 @function color-lower-contrast($color, $amount) {
-    @return darken($color, $amount);
+    @return color.adjust($color, $lightness: -$amount, $space: hsl);
 }
 
 @function color-increase-contrast($color, $amount) {
-    @return lighten($color, $amount);
+    @return color.adjust($color, $lightness: $amount, $space: hsl);
 }
 
 @import 'mol-plugin-ui/skin/base/base';
+@import 'mol-plugin-ui/skin/base/variables';
 
 a {
     color: $font-color;
@@ -31,3 +34,35 @@ a {
         color: $hover-font-color;
     }
 }
+
+
+.msp-snapshot-description-me {
+    background: color.change($default-background, $alpha: 0.5, $space: rgb);
+
+    position: absolute;
+    height: 50vh; // 50% of the viewport height
+    left: 0;
+    top: $control-spacing + $row-height;
+    padding: (0.66 * $control-spacing) $control-spacing;
+
+    resize: both; /* Allows resizing in both directions */
+    overflow: auto; /* Adjust as needed */
+
+    a {
+        text-decoration: underline;
+        cursor: pointer;
+        color: $font-color;
+    }
+
+    ul, ol {
+        padding-left: $control-spacing + 4px;
+    }
+
+    &.hidden {
+        display: none;
+    }
+
+    &.shown {
+        display: block; // or 'flex', 'grid', etc. depending on your layout
+    }
+}

src/apps/mesoscale-explorer/ui/entities.tsx

@@ -1,12 +1,12 @@
 /**
- * Copyright (c) 2022-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2022-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
 
-import { PluginUIComponent } from '../../../mol-plugin-ui/base';
+import { PluginReactContext, PluginUIComponent } from '../../../mol-plugin-ui/base';
 import { Button, ControlGroup, IconButton } from '../../../mol-plugin-ui/controls/common';
-import { ArrowDropDownSvg, ArrowRightSvg, CloseSvg, VisibilityOffOutlinedSvg, VisibilityOutlinedSvg, ContentCutSvg, BrushSvg, SearchSvg } from '../../../mol-plugin-ui/controls/icons';
+import { ArrowDropDownSvg, ArrowRightSvg, CloseSvg, VisibilityOffOutlinedSvg, VisibilityOutlinedSvg, ContentCutSvg, BrushSvg, SearchSvg, TooltipTextSvg, TooltipTextOutlineSvg, PlusBoxSvg, MinusBoxSvg } from '../../../mol-plugin-ui/controls/icons';
 import { PluginCommands } from '../../../mol-plugin/commands';
 import { State, StateObjectCell, StateSelection, StateTransformer } from '../../../mol-state';
 import { ParameterControls, ParameterMappingControl, ParamOnChange, SelectControl } from '../../../mol-plugin-ui/controls/parameters';
@@ -18,14 +18,17 @@ import { CombinedColorControl } from '../../../mol-plugin-ui/controls/color';
 import { MarkerAction } from '../../../mol-util/marker-action';
 import { EveryLoci, Loci } from '../../../mol-model/loci';
 import { deepEqual } from '../../../mol-util';
-import { ColorValueParam, ColorParams, ColorProps, DimLightness, LightnessParams, LodParams, MesoscaleGroup, MesoscaleGroupProps, OpacityParams, SimpleClipParams, SimpleClipProps, createClipMapping, getClipObjects, getDistinctGroupColors, RootParams, MesoscaleState, getRoots, getAllGroups, getAllLeafGroups, getFilteredEntities, getAllFilteredEntities, getGroups, getEntities, getAllEntities, getEntityLabel, updateColors, getGraphicsModeProps, GraphicsMode, MesoscaleStateParams, setGraphicsCanvas3DProps, PatternParams, expandAllGroups } from '../data/state';
-import React from 'react';
+import { ColorValueParam, ColorParams, ColorProps, DimLightness, LightnessParams, LodParams, MesoscaleGroup, MesoscaleGroupProps, OpacityParams, SimpleClipParams, SimpleClipProps, createClipMapping, getClipObjects, getDistinctGroupColors, RootParams, MesoscaleState, getRoots, getAllGroups, getAllLeafGroups, getFilteredEntities, getAllFilteredEntities, getGroups, getEntities, getAllEntities, getEntityLabel, updateColors, getGraphicsModeProps, GraphicsMode, MesoscaleStateParams, setGraphicsCanvas3DProps, PatternParams, expandAllGroups, EmissiveParams, IllustrativeParams, getCellDescription, getEntityDescription, getEveryEntity } from '../data/state';
+import React, { useState } from 'react';
 import { MesoscaleExplorerState } from '../app';
 import { StructureElement } from '../../../mol-model/structure/structure/element';
 import { PluginStateObject as PSO } from '../../../mol-plugin-state/objects';
 import { Structure } from '../../../mol-model/structure';
 import { PluginContext } from '../../../mol-plugin/context';
 import { Sphere3D } from '../../../mol-math/geometry';
+import { MesoFocusLoci } from '../behavior/camera';
+import Markdown from 'react-markdown';
+import { combineLatest } from 'rxjs';
 
 function centerLoci(plugin: PluginContext, loci: Loci, durationMs = 250) {
     const { canvas3d } = plugin;
@@ -60,6 +63,7 @@ export class ModelInfo extends PluginUIComponent<{}, { isDisabled: boolean }> {
         if (!state.description && !state.link) return;
 
         return {
+            selectionDescription: state.focusInfo,
             description: state.description,
             link: state.link,
         };
@@ -68,7 +72,7 @@ export class ModelInfo extends PluginUIComponent<{}, { isDisabled: boolean }> {
     render() {
         const info = this.info;
         return info && <>
-            <div className='msp-help-text'>
+            <div id='modelinfo' className='msp-help-text'>
                 <div>{info.description}</div>
                 <div><a href={info.link} target='_blank'>Source</a></div>
             </div>
@@ -101,17 +105,20 @@ export class SelectionInfo extends PluginUIComponent<{}, { isDisabled: boolean }
     }
 
     get info() {
-        const info: { label: string, key: string }[] = [];
+        const infos: { label: string, key: string, description?: string }[] = [];
         this.plugin.managers.structure.selection.entries.forEach((e, k) => {
             if (StructureElement.Loci.is(e.selection) && !StructureElement.Loci.isEmpty(e.selection)) {
                 const cell = this.plugin.helpers.substructureParent.get(e.selection.structure);
-                info.push({
+                const { entities } = e.selection.structure.model;
+                const description = entities.data.pdbx_description.value(0)[0] || 'model';
+                infos.push({
+                    description: description,
                     label: cell?.obj?.label || 'Unknown',
                     key: k,
                 });
             }
         });
-        return info;
+        return infos;
     }
 
     find(label: string) {
@@ -133,31 +140,40 @@ export class SelectionInfo extends PluginUIComponent<{}, { isDisabled: boolean }
 
         const loci = Structure.toStructureElementLoci(e.selection.structure);
         centerLoci(this.plugin, loci);
+        const cell = this.plugin.helpers.substructureParent.get(loci.structure);
+        const d = getCellDescription(cell!); // '### ' + cell?.obj?.label + '\n\n' + cell?.obj?.description;
+        MesoscaleState.set(this.plugin, { focusInfo: `${d}` });
     }
 
     get selection() {
         const info = this.info;
+        const help_selection = <><div>Use <i>ctrl+left</i> to select entities, either on the 3D canvas or in the tree below</div><div>Use <i>shift+left</i> to select individual chain on the 3D canvas</div></>;
         if (!info.length) return <>
-            <div className='msp-help-text'>
-                <div>Use <i>ctrl+left click</i> to select entities, either on the 3D canvas or in the tree below</div>
+            <div id='seleinfo' className='msp-help-text'>
+                {help_selection}
             </div>
         </>;
-
         return <>
-            {info.map((entry, index) => {
-                const label = <Button className={`msp-btn-tree-label`} noOverflow disabled={this.state.isDisabled}
-                    onClick={() => this.center(entry.key)}
-                >
-                    <span title={entry.label}>{entry.label}</span>
-                </Button>;
-                const find = <IconButton svg={SearchSvg} toggleState={false} disabled={this.state.isDisabled} small onClick={() => this.find(entry.label)} />;
-                const remove = <IconButton svg={CloseSvg} toggleState={false} disabled={this.state.isDisabled} onClick={() => this.remove(entry.key)} />;
-                return <div key={index} className={`msp-flex-row`} style={{ margin: `1px 5px 1px ${1 * 10 + 5}px` }}>
-                    {label}
-                    {find}
-                    {remove}
-                </div>;
-            })}
+            <div id='seleinfo'>
+                {info.map((entry, index) => {
+                    const label = <Button className={`msp-btn-tree-label`} noOverflow disabled={this.state.isDisabled}
+                        onClick={() => this.center(entry.key)}
+                    >
+                        <span title={entry.label}>
+                            {entry.label}
+                        </span>
+                    </Button>;
+                    const find = <IconButton svg={SearchSvg} toggleState={false} disabled={this.state.isDisabled} small onClick={() => this.find(entry.label)} />;
+                    const remove = <IconButton svg={CloseSvg} toggleState={false} disabled={this.state.isDisabled} onClick={() => this.remove(entry.key)} />;
+                    return <>
+                        <div key={index} className={`msp-flex-row`} style={{ margin: `1px 5px 1px ${1 * 10 + 5}px` }}>
+                            {label}
+                            {find}
+                            {remove}
+                        </div>
+                    </>;
+                })};
+            </div>
         </>;
     }
 
@@ -216,7 +232,7 @@ export class SelectionInfo extends PluginUIComponent<{}, { isDisabled: boolean }
 
     renderStyle() {
         const style = this.style || '';
-        return <div style={{ margin: '5px', marginBottom: '10px' }}>
+        return <div id='selestyle' style={{ margin: '5px', marginBottom: '10px' }}>
             <SelectControl name={'Style'} param={SelectionStyleParam} value={style} onChange={(e) => { this.setStyle(e.value); }} />
         </div>;
     }
@@ -229,6 +245,195 @@ export class SelectionInfo extends PluginUIComponent<{}, { isDisabled: boolean }
     }
 }
 
+export function MesoMarkdownAnchor({ href, children, element }: { href?: string, children?: any, element?: any }) {
+    const plugin = React.useContext(PluginReactContext);
+    if (!href) return element;
+    // Decode the href to handle encoded spaces and other characters
+    const decodedHref = href ? decodeURIComponent(href) : '';
+    const handleHover = (e: React.MouseEvent<HTMLAnchorElement, MouseEvent>) => {
+        e.preventDefault();
+        if (decodedHref.startsWith('i')) {
+            plugin.canvas3d?.mark({ loci: EveryLoci }, MarkerAction.RemoveHighlight);
+            const query_names = decodedHref.substring(1).split(',');
+            for (const query_name of query_names) {
+                const entities = getEveryEntity(plugin, query_name);
+                for (const r of entities) {
+                    const repr = r.obj?.data.repr;
+                    if (repr) {
+                        plugin.canvas3d?.mark({ repr, loci: EveryLoci }, MarkerAction.Highlight);
+                    }
+                }
+            }
+        } else if (decodedHref.startsWith('g')) {
+            plugin.canvas3d?.mark({ loci: EveryLoci }, MarkerAction.RemoveHighlight);
+            const qindex = decodedHref.indexOf('.');
+            const query = decodedHref.substring(1, qindex) + ':';
+            const query_names = decodedHref.substring(qindex + 1).split(',');
+            for (const query_name of query_names) {
+                const e = getAllEntities(plugin, query + query_name);
+                for (const r of e) {
+                    const repr = r.obj?.data.repr;
+                    if (repr) {
+                        plugin.canvas3d?.mark({ repr, loci: EveryLoci }, MarkerAction.Highlight);
+                    }
+                }
+            }
+        }
+    };
+    const handleLeave = (e: React.MouseEvent<HTMLAnchorElement, MouseEvent>) => {
+        // Implement your hover off logic here
+        // Example: Perform an action if the href starts with 'h'
+        if (decodedHref.startsWith('i') || decodedHref.startsWith('g')) {
+            // Example hover off action
+            e.preventDefault();
+            plugin.canvas3d?.mark({ loci: EveryLoci }, MarkerAction.RemoveHighlight);
+        }
+    };
+    const handleClick = (e: React.MouseEvent<HTMLAnchorElement, MouseEvent>) => {
+        e.preventDefault();
+        if (href.startsWith('#')) {
+            plugin.managers.snapshot.applyKey(decodedHref.substring(1));
+        } else if (decodedHref.startsWith('i')) {
+            plugin.managers.interactivity.lociSelects.deselectAll();
+            plugin.canvas3d?.mark({ loci: EveryLoci }, MarkerAction.RemoveHighlight);
+            const query_names = decodedHref.substring(1).split(',');
+            for (const query_name of query_names) {
+                const entities = getFilteredEntities(plugin, '', query_name);
+                for (const r of entities) {
+                    const repr = r.obj?.data.repr;
+                    if (repr) {
+                        plugin.canvas3d?.mark({ repr, loci: EveryLoci }, MarkerAction.Highlight);
+                    }
+                    const cell = r as StateObjectCell<PSO.Molecule.Structure.Representation3D | PSO.Shape.Representation3D> | undefined;
+                    if (!(cell?.obj?.data.sourceData instanceof Structure)) {
+                        return;
+                    }
+                    const loci = Structure.toStructureElementLoci(cell.obj.data.sourceData);
+                    plugin.managers.interactivity.lociSelects.toggle({ loci }, false);
+                }
+            }
+        } else if (decodedHref.startsWith('g')) {
+            plugin.managers.interactivity.lociSelects.deselectAll();
+            plugin.canvas3d?.mark({ loci: EveryLoci }, MarkerAction.RemoveHighlight);
+            const qindex = decodedHref.indexOf('.');
+            const query = decodedHref.substring(1, qindex) + ':';
+            const query_names = decodedHref.substring(qindex + 1).split(',');
+            for (const query_name of query_names) {
+                const entities = getAllEntities(plugin, query + query_name);
+                for (const r of entities) {
+                    const repr = r.obj?.data.repr;
+                    if (repr) {
+                        plugin.canvas3d?.mark({ repr, loci: EveryLoci }, MarkerAction.Highlight);
+                    }
+                    const cell = r as StateObjectCell<PSO.Molecule.Structure.Representation3D | PSO.Shape.Representation3D> | undefined;
+                    if (!(cell?.obj?.data.sourceData instanceof Structure)) return;
+                    const loci = Structure.toStructureElementLoci(cell.obj.data.sourceData);
+                    plugin.managers.interactivity.lociSelects.toggle({ loci }, false);
+                }
+            }
+        } else {
+            // open the link in a new tab
+            window.open(decodedHref, '_blank');
+        }
+    };
+
+    if (decodedHref[0] === '#') {
+        return <a href={decodedHref[0]} onMouseOver={handleHover} onClick={handleClick}>{children}</a>;
+    }
+    if (decodedHref[0] === 'i' || decodedHref[0] === 'g') {
+        return <a href={decodedHref[0]} onMouseLeave={handleLeave} onMouseOver={handleHover} onClick={handleClick}>{children}</a>;
+    }
+    if (decodedHref[0] === 'h') {
+        return <a href={decodedHref[0]} onClick={handleClick} rel='noopener noreferrer'>{children}</a>;
+    }
+    return element;
+}
+
+export function MesoViewportSnapshotDescription() {
+    let tSize = 14;
+    const plugin = React.useContext(PluginReactContext);
+    if (MesoscaleState.has(plugin)) {
+        const state = MesoscaleState.get(plugin);
+        tSize = state.textSizeDescription;
+    }
+    const [_, setV] = React.useState(0);
+    const [isShown, setIsShown] = useState(true);
+    const [textSize, setTextSize] = useState(tSize);
+    const toggleVisibility = () => {
+        setIsShown(!isShown);
+    };
+
+    const increaseTextSize = () => {
+        setTextSize(prevSize => Math.min(prevSize + 2, 50)); // Increase the text size by 2px, but not above 50px
+    };
+
+    const decreaseTextSize = () => {
+        setTextSize(prevSize => Math.max(prevSize - 2, 2)); // Decrease the text size by 2px, but not below 2px
+    };
+
+
+    React.useEffect(() => {
+        const sub = plugin.managers.snapshot.events.changed.subscribe(() => setV(v => v + 1));
+        return () => sub.unsubscribe();
+    }, [plugin]);
+
+    const current = plugin.managers.snapshot.state.current;
+    if (!current) return null;
+
+    const e = plugin.managers.snapshot.getEntry(current)!;
+    if (!e?.description?.trim()) return null;
+    if (MesoscaleState.has(plugin)) {
+        MesoscaleState.set(plugin, { textSizeDescription: textSize });
+    }
+    const showInfo = <IconButton svg={isShown ? TooltipTextSvg : TooltipTextOutlineSvg} flex='20px' onClick={toggleVisibility} title={isShown ? 'Hide Description' : 'Show Description'}/>;
+    const increasePoliceSize = <IconButton svg={PlusBoxSvg} flex='20px' onClick={increaseTextSize} title='Bigger Text' />;
+    const decreasePoliceSize = <IconButton svg={MinusBoxSvg} flex='20px' onClick={decreaseTextSize} title='Smaller Text' />;
+    return (
+        <>
+            <div id='snapinfoctrl' className="msp-state-snapshot-viewport-controls" style={{ marginRight: '30px' }}>
+                {showInfo}{increasePoliceSize}{decreasePoliceSize}
+            </div>
+            <div id='snapinfo' className={`msp-snapshot-description-me ${isShown ? 'shown' : 'hidden'}`} style={{ fontSize: `${textSize}px` }}>
+                {e.descriptionFormat === 'plaintext'
+                    && e.description
+                    || <Markdown skipHtml={false} components={{ a: MesoMarkdownAnchor }}>{e.description}</Markdown>
+                }
+            </div>
+        </>
+    );
+}
+
+export class FocusInfo extends PluginUIComponent<{}, { isDisabled: boolean }> {
+    componentDidMount() {
+        this.subscribe(combineLatest([
+            this.plugin.state.data.behaviors.isUpdating,
+            this.plugin.managers.structure.selection.events.changed
+        ]), ([isUpdating]) => {
+            if (!isUpdating) this.forceUpdate();
+        });
+    }
+
+    get info() {
+        let focusInfo = '';
+        if (MesoscaleState.has(this.plugin)) {
+            const state = MesoscaleState.get(this.plugin);
+            if (state.focusInfo) focusInfo = state.focusInfo;
+        }
+        return focusInfo;
+    }
+
+    render() {
+        const focusInfo = this.info;
+        const description = (focusInfo !== '') ? <Markdown skipHtml components={{ a: MesoMarkdownAnchor }}>{focusInfo}</Markdown> : '';
+        return <>
+            <div id='focusinfo' className='msp-help-text'>
+                {description}
+            </div>
+        </>;
+    }
+}
+
+
 export class EntityControls extends PluginUIComponent<{}, { isDisabled: boolean }> {
     filterRef = React.createRef<HTMLInputElement>();
     prevFilter = '';
@@ -336,7 +541,7 @@ export class EntityControls extends PluginUIComponent<{}, { isDisabled: boolean
 
     renderGraphics() {
         const graphics = this.graphics;
-        return <div style={{ margin: '5px', marginBottom: '10px' }}>
+        return <div id='graphicsquality' style={{ margin: '5px', marginBottom: '10px' }}>
             <SelectControl name={'Graphics'} param={MesoscaleStateParams.graphics} value={`${graphics}`} onChange={(e) => { this.setGraphics(e.value); }} />
         </div>;
     }
@@ -363,7 +568,7 @@ export class EntityControls extends PluginUIComponent<{}, { isDisabled: boolean
 
         return <>
             {this.renderGraphics()}
-            <div className={`msp-flex-row msp-control-row`} style={{ margin: '5px', marginBottom: '10px' }}>
+            <div id='searchtree' className={`msp-flex-row msp-control-row`} style={{ margin: '5px', marginBottom: '10px' }}>
                 <input type='text' ref={this.filterRef}
                     value={filter}
                     placeholder='Search'
@@ -373,10 +578,12 @@ export class EntityControls extends PluginUIComponent<{}, { isDisabled: boolean
                 />
                 <IconButton svg={CloseSvg} toggleState={false} disabled={disabled} onClick={() => this.setFilter('')} />
             </div>
-            {options.length > 1 && <div style={{ margin: '5px', marginBottom: '10px' }}>
+            {options.length > 1 && <div id='grouptree' style={{ margin: '5px', marginBottom: '10px' }}>
                 <SelectControl name={'Group By'} param={groupParam} value={`${groupBy}`} onChange={(e) => { this.setGroupBy(parseInt(e.value)); }} />
             </div>}
-            <GroupNode filter={filter} cell={root} depth={0} />
+            <div id='tree' style={{ position: 'relative', overflowY: 'auto', borderBottom: '1px  solid #000', maxHeight: '600px' }}>
+                <GroupNode filter={filter} cell={root} depth={0} />
+            </div>
         </>;
     }
 }
@@ -435,6 +642,12 @@ export class GroupNode extends Node<{ filter: string }, { isCollapsed: boolean,
         this.setState({ action: this.state.action === 'root' ? undefined : 'root' });
     };
 
+    showInfo = (e: React.MouseEvent<HTMLElement>) => {
+        e.preventDefault();
+        const d = getCellDescription(this.cell); // '### ' + this.cell?.obj?.label + '\n\n' + this.cell?.obj?.description;
+        MesoscaleState.set(this.plugin, { focusInfo: `${d}` });
+    };
+
     highlight = (e: React.MouseEvent<HTMLElement>) => {
         e.preventDefault();
         this.plugin.canvas3d?.mark({ loci: EveryLoci }, MarkerAction.RemoveHighlight);
@@ -493,7 +706,7 @@ export class GroupNode extends Node<{ filter: string }, { isCollapsed: boolean,
 
     updateColor = (values: ColorProps) => {
         const update = this.plugin.state.data.build();
-        const { value, type, lightness, alpha } = values;
+        const { value, illustrative, type, lightness, alpha, emissive } = values;
 
         const entities = this.filteredEntities;
 
@@ -507,15 +720,20 @@ export class GroupNode extends Node<{ filter: string }, { isCollapsed: boolean,
             const c = type === 'generate' ? groupColors[i] : value;
             update.to(entities[i]).update(old => {
                 if (old.type) {
-                    old.colorTheme.params.value = c;
-                    old.colorTheme.params.lightness = lightness;
+                    if (illustrative) {
+                        old.colorTheme = { name: 'illustrative', params: { style: { name: 'uniform', params: { value: c, lightness } } } };
+                    } else {
+                        old.colorTheme = { name: 'uniform', params: { value: c, lightness } };
+                    }
                     old.type.params.alpha = alpha;
                     old.type.params.xrayShaded = alpha < 1 ? 'inverted' : false;
+                    old.type.params.emissive = emissive;
                 } else {
                     old.coloring.params.color = c;
                     old.coloring.params.lightness = lightness;
                     old.alpha = alpha;
                     old.xrayShaded = alpha < 1 ? true : false;
+                    old.emissive = emissive;
                 }
             });
         }
@@ -653,6 +871,7 @@ export class GroupNode extends Node<{ filter: string }, { isCollapsed: boolean,
         const label = <Button className={`msp-btn-tree-label`} noOverflow disabled={disabled}
             onMouseEnter={this.highlight}
             onMouseLeave={this.clearHighlight}
+            onClick={this.showInfo}
         >
             <span title={groupLabel}>{groupLabel}</span>
         </Button>;
@@ -772,18 +991,63 @@ export class EntityNode extends Node<{}, { action?: 'color' | 'clip', isDisabled
         if (e.ctrlKey) {
             this.toggleSelect(e);
         } else {
-            this.center(e);
+            const d = getEntityDescription(this.plugin, this.cell);
+            if (this.cell?.obj?.data.sourceData.state.models.length !== 0) {
+                const repr = this.cell?.obj?.data.repr;
+                if (repr) {
+                    // for fiber need to think how to handle.
+                    const aloci = repr.getAllLoci()[0];
+                    const locis = Loci.normalize(aloci, 'chainInstances') as StructureElement.Loci;
+                    const nChain = aloci.structure.state.unitSymmetryGroups.length;
+                    let index = MesoscaleState.get(this.plugin).index + 1;
+                    if (index * nChain >= locis.elements.length) index = 0;
+                    const elems = locis.elements.slice(index * nChain, ((index + 1) * nChain)); // end index is not included
+                    const loci = StructureElement.Loci(aloci.structure, elems);
+                    const sphere = Loci.getBoundingSphere(loci) || Sphere3D();
+                    const state = this.plugin.state.behaviors;
+                    const selections = state.select(StateSelection.Generators.ofTransformer(MesoFocusLoci));
+                    const params = selections.length === 1 ? selections[0].obj?.data.params : undefined;
+                    if (!params.centerOnly) {
+                        this.plugin.managers.camera.focusSphere(sphere, params);
+                    } else {
+                        const snapshot = this.plugin.canvas3d?.camera.getCenter(sphere.center);
+                        this.plugin.canvas3d?.requestCameraReset({ durationMs: params.durationMs, snapshot });
+                    }
+                    MesoscaleState.set(this.plugin, { index: index, focusInfo: `${d}` });
+                }
+            } else {
+                this.center(e);
+                MesoscaleState.set(this.plugin, { focusInfo: `${d}` });
+            }
         }
     };
 
     get colorValue(): Color | undefined {
-        return this.cell.transform.params?.colorTheme?.params.value ?? this.cell.transform.params?.coloring?.params.color;
+        if (this.cell.transform.params?.colorTheme?.params.value) {
+            return this.cell.transform.params?.colorTheme?.params.value;
+        } else if (this.cell.transform.params?.colorTheme?.name === 'illustrative') {
+            return this.cell.transform.params?.colorTheme?.params.style.params.value;
+        } else {
+            return this.cell.transform.params?.colorTheme?.params.value ?? this.cell.transform.params?.coloring?.params.color;
+        }
+    }
+
+    get illustrativeValue(): { illustrative: boolean } | undefined {
+        return {
+            illustrative: (this.cell.transform.params?.colorTheme?.name === 'illustrative')
+        };
     }
 
     get lightnessValue(): { lightness: number } | undefined {
-        return {
-            lightness: this.cell.transform.params?.colorTheme?.params.lightness ?? this.cell.transform.params?.coloring?.params.lightness ?? 0
-        };
+        if (this.cell.transform.params?.colorTheme?.name === 'illustrative') {
+            return {
+                lightness: this.cell.transform.params?.colorTheme?.params.style.params.lightness ?? 0
+            };
+        } else {
+            return {
+                lightness: this.cell.transform.params?.colorTheme?.params.lightness ?? this.cell.transform.params?.coloring?.params.lightness ?? 0
+            };
+        }
     }
 
     get opacityValue(): { alpha: number } | undefined {
@@ -792,6 +1056,12 @@ export class EntityNode extends Node<{}, { action?: 'color' | 'clip', isDisabled
         };
     }
 
+    get emissiveValue(): { emissive: number } | undefined {
+        return {
+            emissive: this.cell.transform.params?.type?.params.emissive ?? this.cell.transform.params?.emissive ?? 0
+        };
+    }
+
     get clipValue(): Clip.Props | undefined {
         return this.cell.transform.params.type?.params.clip ?? this.cell.transform.params.clip;
     }
@@ -830,7 +1100,11 @@ export class EntityNode extends Node<{}, { action?: 'color' | 'clip', isDisabled
         }
         update.to(this.ref).update(old => {
             if (old.colorTheme) {
-                old.colorTheme.params.value = value;
+                if (old.colorTheme.name === 'illustrative') {
+                    old.colorTheme.params.style.params.value = value;
+                } else {
+                    old.colorTheme.params.value = value;
+                }
             } else if (old.coloring) {
                 old.coloring.params.color = value;
             }
@@ -838,10 +1112,26 @@ export class EntityNode extends Node<{}, { action?: 'color' | 'clip', isDisabled
         update.commit();
     };
 
+    updateIllustrative = (values: PD.Values) => {
+        return this.plugin.build().to(this.ref).update(old => {
+            if (old.colorTheme) {
+                if (old.colorTheme.name !== 'illustrative' && values.illustrative) {
+                    old.colorTheme = { name: 'illustrative', params: { style: { name: 'uniform', params: { value: old.colorTheme.params.value, lightness: old.colorTheme.params.lightness } } } };
+                } else if (old.colorTheme.name === 'illustrative' && !values.illustrative) {
+                    old.colorTheme = { name: 'uniform', params: { value: old.colorTheme.params.style.params.value, lightness: old.colorTheme.params.style.params.lightness } };
+                }
+            }
+        }).commit();
+    };
+
     updateLightness = (values: PD.Values) => {
         return this.plugin.build().to(this.ref).update(old => {
             if (old.colorTheme) {
-                old.colorTheme.params.lightness = values.lightness;
+                if (old.colorTheme.name === 'illustrative') {
+                    old.colorTheme.params.style.params.lightness = values.lightness;
+                } else {
+                    old.colorTheme.params.lightness = values.lightness;
+                }
             } else if (old.coloring) {
                 old.coloring.params.lightness = values.lightness;
             }
@@ -860,6 +1150,16 @@ export class EntityNode extends Node<{}, { action?: 'color' | 'clip', isDisabled
         }).commit();
     };
 
+    updateEmissive = (values: PD.Values) => {
+        return this.plugin.build().to(this.ref).update(old => {
+            if (old.type) {
+                old.type.params.emissive = values.emissive;
+            } else {
+                old.emissive = values.emissive;
+            }
+        }).commit();
+    };
+
     updateClip = (props: Clip.Props) => {
         const params = this.cell.transform.params;
         const clip = params.type ? params.type.params.clip : params.clip;
@@ -906,7 +1206,9 @@ export class EntityNode extends Node<{}, { action?: 'color' | 'clip', isDisabled
         const depth = this.props.depth;
         const colorValue = this.colorValue;
         const lightnessValue = this.lightnessValue;
+        const illustrativeValue = this.illustrativeValue;
         const opacityValue = this.opacityValue;
+        const emissiveValue = this.emissiveValue;
         const lodValue = this.lodValue;
         const patternValue = this.patternValue;
 
@@ -934,8 +1236,10 @@ export class EntityNode extends Node<{}, { action?: 'color' | 'clip', isDisabled
                 <ControlGroup header='Color' initialExpanded={true} hideExpander={true} hideOffset={true} onHeaderClick={this.toggleColor}
                     topRightIcon={CloseSvg} noTopMargin childrenClassName='msp-viewport-controls-panel-controls'>
                     <CombinedColorControl param={ColorValueParam} value={colorValue ?? Color(0xFFFFFF)} onChange={this.updateColor} name='color' hideNameRow />
+                    <ParameterControls params={IllustrativeParams} values={illustrativeValue} onChangeValues={this.updateIllustrative} />
                     <ParameterControls params={LightnessParams} values={lightnessValue} onChangeValues={this.updateLightness} />
                     <ParameterControls params={OpacityParams} values={opacityValue} onChangeValues={this.updateOpacity} />
+                    <ParameterControls params={EmissiveParams} values={emissiveValue} onChangeValues={this.updateEmissive} />
                     {patternValue && <ParameterControls params={PatternParams} values={patternValue} onChangeValues={this.updatePattern} />}
                 </ControlGroup>
             </div>}

src/apps/mesoscale-explorer/ui/panels.tsx

@@ -5,20 +5,63 @@
  */
 
 import { Mp4EncoderUI } from '../../../extensions/mp4-export/ui';
-import { PluginUIComponent } from '../../../mol-plugin-ui/base';
+import { CollapsableControls, CollapsableState, PluginUIComponent } from '../../../mol-plugin-ui/base';
 import { SectionHeader } from '../../../mol-plugin-ui/controls/common';
+import { ParameterControls } from '../../../mol-plugin-ui/controls/parameters';
+import { PluginCommands } from '../../../mol-plugin/commands';
+import { StructureMeasurementsControls } from '../../../mol-plugin-ui/structure/measurements';
 import { MesoscaleExplorerState } from '../app';
 import { MesoscaleState } from '../data/state';
-import { EntityControls, ModelInfo, SelectionInfo } from './entities';
-import { LoaderControls, ExampleControls, SessionControls, SnapshotControls, DatabaseControls } from './states';
+import { EntityControls, FocusInfo, ModelInfo, SelectionInfo } from './entities';
+import { LoaderControls, ExampleControls, SessionControls, SnapshotControls, DatabaseControls, MesoQuickStylesControls, ExplorerInfo } from './states';
+import { ParamDefinition as PD } from '../../../mol-util/param-definition';
+import { TuneSvg } from '../../../mol-plugin-ui/controls/icons';
+import { RendererParams } from '../../../mol-gl/renderer';
+import { TrackballControlsParams } from '../../../mol-canvas3d/controls/trackball';
 
 const Spacer = () => <div style={{ height: '2em' }} />;
 
+const ViewportParams = {
+    renderer: PD.Group(RendererParams),
+    trackball: PD.Group(TrackballControlsParams),
+};
+
+class ViewportSettingsUI extends CollapsableControls<{}, {}> {
+    protected defaultState(): CollapsableState {
+        return {
+            header: 'Viewport Settings',
+            isCollapsed: true,
+            brand: { accent: 'cyan', svg: TuneSvg }
+        };
+    }
+
+    protected renderControls(): JSX.Element | null {
+        return <>
+            {this.plugin.canvas3d && this.plugin.canvas3dContext && <>
+                <ParameterControls params={ViewportParams} values={this.plugin.canvas3d.props} onChange={this.setSettings} />
+            </>}
+        </>;
+    }
+
+    private setSettings = (p: { param: PD.Base<any>, name: string, value: any }) => {
+        PluginCommands.Canvas3D.SetSettings(this.plugin, { settings: { [p.name]: p.value } });
+    };
+
+    componentDidMount() {
+        this.subscribe(this.plugin.events.canvas3d.settingsUpdated, () => this.forceUpdate());
+        this.subscribe(this.plugin.layout.events.updated, () => this.forceUpdate());
+    }
+}
+
 export class LeftPanel extends PluginUIComponent {
     render() {
         const customState = this.plugin.customState as MesoscaleExplorerState;
 
         return <div className='msp-scrollable-container'>
+            {customState.driver && <>
+                <ExplorerInfo />
+                <Spacer />
+            </>}
             <SectionHeader title='Database' />
             <DatabaseControls />
             <Spacer />
@@ -42,6 +85,7 @@ export class LeftPanel extends PluginUIComponent {
             <Spacer />
 
             <Mp4EncoderUI />
+            <ViewportSettingsUI />
         </div>;
     }
 }
@@ -59,6 +103,13 @@ export class RightPanel extends PluginUIComponent<{}, { isDisabled: boolean }> {
         );
     }
 
+    get hasFocusInfo() {
+        return (
+            MesoscaleState.has(this.plugin) &&
+            !!(MesoscaleState.get(this.plugin).focusInfo !== '')
+        );
+    }
+
     componentDidMount() {
         this.subscribe(this.plugin.state.data.behaviors.isUpdating, v => {
             this.setState({ isDisabled: v });
@@ -89,10 +140,18 @@ export class RightPanel extends PluginUIComponent<{}, { isDisabled: boolean }> {
                 <SectionHeader title='Selection' />
                 <SelectionInfo />
                 <Spacer />
+                <StructureMeasurementsControls initiallyCollapsed={true}/>
             </>
-
+            <MesoQuickStylesControls />
+            <Spacer />
             <SectionHeader title='Entities' />
             <EntityControls />
+            <Spacer />
+            {this.hasFocusInfo && <>
+                <SectionHeader title='Focus Info' />
+                <FocusInfo />
+                <Spacer />
+            </>}
         </div>;
     }
-}
+}

src/apps/mesoscale-explorer/ui/states.tsx

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2022-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2022-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -7,9 +7,9 @@
 import { MmcifFormat } from '../../../mol-model-formats/structure/mmcif';
 import { MmcifProvider } from '../../../mol-plugin-state/formats/trajectory';
 import { PluginStateObject } from '../../../mol-plugin-state/objects';
-import { PluginUIComponent } from '../../../mol-plugin-ui/base';
-import { Button, ExpandGroup } from '../../../mol-plugin-ui/controls/common';
-import { GetAppSvg, Icon, OpenInBrowserSvg } from '../../../mol-plugin-ui/controls/icons';
+import { Button, ExpandGroup, IconButton } from '../../../mol-plugin-ui/controls/common';
+import { GetAppSvg, HelpOutlineSvg, MagicWandSvg, TourSvg, Icon, OpenInBrowserSvg } from '../../../mol-plugin-ui/controls/icons';
+import { CollapsableControls, PluginUIComponent } from '../../../mol-plugin-ui/base';
 import { ApplyActionControl } from '../../../mol-plugin-ui/state/apply-action';
 import { LocalStateSnapshotList, LocalStateSnapshotParams, LocalStateSnapshots } from '../../../mol-plugin-ui/state/snapshots';
 import { PluginCommands } from '../../../mol-plugin/commands';
@@ -24,9 +24,13 @@ import { createCellpackHierarchy } from '../data/cellpack/preset';
 import { createGenericHierarchy } from '../data/generic/preset';
 import { createMmcifHierarchy } from '../data/mmcif/preset';
 import { createPetworldHierarchy } from '../data/petworld/preset';
-import { MesoscaleState, MesoscaleStateObject, setGraphicsCanvas3DProps } from '../data/state';
+import { MesoscaleState, MesoscaleStateObject, setGraphicsCanvas3DProps, updateStyle } from '../data/state';
+import { isTimingMode } from '../../../mol-util/debug';
+import { now } from '../../../mol-util/now';
 
 function adjustPluginProps(ctx: PluginContext) {
+    const customState = ctx.customState as MesoscaleExplorerState;
+
     ctx.managers.interactivity.setProps({ granularity: 'chain' });
     ctx.canvas3d?.setProps({
         multiSample: { mode: 'off' },
@@ -77,14 +81,15 @@ function adjustPluginProps(ctx: PluginContext) {
                     radius: 5,
                     bias: 1,
                     blurKernelSize: 11,
+                    blurDepthBias: 0.5,
                     resolutionScale: 1,
                     color: Color(0x000000),
+                    transparentThreshold: 0.4,
                 }
             },
             shadow: {
                 name: 'on',
                 params: {
-                    bias: 0.6,
                     maxDistance: 80,
                     steps: 3,
                     tolerance: 1.0,
@@ -98,8 +103,13 @@ function adjustPluginProps(ctx: PluginContext) {
                     color: Color(0x000000),
                     includeTransparent: false,
                 }
-            }
-        }
+            },
+        },
+        illumination: {
+            enabled: customState.illumination,
+            firstStepSize: 0.1,
+            rayDistance: 1024,
+        },
     });
 
     const { graphics } = MesoscaleState.get(ctx);
@@ -162,14 +172,36 @@ export async function loadExampleEntry(ctx: PluginContext, entry: ExampleEntry)
 }
 
 export async function loadUrl(ctx: PluginContext, url: string, type: 'molx' | 'molj' | 'cif' | 'bcif') {
+    let startTime = 0;
+    if (isTimingMode) {
+        startTime = now();
+    }
     if (type === 'molx' || type === 'molj') {
+        const customState = ctx.customState as MesoscaleExplorerState;
+        delete customState.stateRef;
+        customState.stateCache = {};
+        ctx.managers.asset.clear();
+
+        await PluginCommands.State.Snapshots.Clear(ctx);
         await PluginCommands.State.Snapshots.OpenUrl(ctx, { url, type });
+
+        const cell = ctx.state.data.selectQ(q => q.ofType(MesoscaleStateObject))[0];
+        if (!cell) throw new Error('Missing MesoscaleState');
+
+        customState.stateRef = cell.transform.ref;
+        customState.graphicsMode = cell.obj?.data.graphics || customState.graphicsMode;
     } else {
         await reset(ctx);
         const isBinary = type === 'bcif';
         const data = await ctx.builders.data.download({ url, isBinary });
         await createHierarchy(ctx, data.ref);
     }
+    if (isTimingMode) {
+        const endTime = now();
+        // Calculate the elapsed time
+        const timeTaken = endTime - startTime;
+        console.log(`Model loaded in ${timeTaken} milliseconds`);
+    }
 }
 
 export async function loadPdb(ctx: PluginContext, id: string) {
@@ -181,8 +213,14 @@ export async function loadPdb(ctx: PluginContext, id: string) {
 
 export async function loadPdbDev(ctx: PluginContext, id: string) {
     await reset(ctx);
-    const nId = id.toUpperCase().startsWith('PDBDEV_') ? id : `PDBDEV_${id.padStart(8, '0')}`;
-    const url = `https://pdb-dev.wwpdb.org/bcif/${nId.toUpperCase()}.bcif`;
+    let url: string;
+    // 4 character PDB id, TODO: support extended PDB ID
+    if (id.match(/^[1-9][A-Z0-9]{3}$/i) !== null) {
+        url = `https://pdb-dev.wwpdb.org/bcif/${id.toLowerCase()}.bcif`;
+    } else {
+        const nId = id.toUpperCase().startsWith('PDBDEV_') ? id : `PDBDEV_${id.padStart(8, '0')}`;
+        url = `https://pdb-dev.wwpdb.org/bcif/${nId.toUpperCase()}.bcif`;
+    }
     const data = await ctx.builders.data.download({ url, isBinary: true });
     await createHierarchy(ctx, data.ref);
 }
@@ -269,7 +307,7 @@ export class DatabaseControls extends PluginUIComponent {
     }
 
     render() {
-        return <div style={{ margin: '5px' }}>
+        return <div id='database' style={{ margin: '5px' }}>
             <ApplyActionControl state={this.plugin.state.data} action={LoadDatabase} nodeRef={this.plugin.state.data.tree.root.ref} applyLabel={'Load'} hideHeader />
         </div>;
     }
@@ -281,7 +319,7 @@ export class LoaderControls extends PluginUIComponent {
     }
 
     render() {
-        return <div style={{ margin: '5px' }}>
+        return <div id='loader' style={{ margin: '5px' }}>
             <ApplyActionControl state={this.plugin.state.data} action={LoadModel} nodeRef={this.plugin.state.data.tree.root.ref} applyLabel={'Load'} hideHeader />
         </div>;
     }
@@ -293,7 +331,7 @@ export class ExampleControls extends PluginUIComponent {
     }
 
     render() {
-        return <div style={{ margin: '5px' }}>
+        return <div id='example' style={{ margin: '5px' }}>
             <ApplyActionControl state={this.plugin.state.data} action={LoadExample} nodeRef={this.plugin.state.data.tree.root.ref} applyLabel={'Load'} hideHeader />
         </div>;
     }
@@ -330,7 +368,7 @@ export class SessionControls extends PluginUIComponent {
     };
 
     render() {
-        return <div style={{ margin: '5px' }}>
+        return <div id='session' style={{ margin: '5px' }}>
             <div className='msp-flex-row'>
                 <Button icon={GetAppSvg} onClick={this.downloadToFileZip} title='Download the state.'>
                     Download
@@ -346,14 +384,14 @@ export class SessionControls extends PluginUIComponent {
 export class SnapshotControls extends PluginUIComponent<{}> {
     render() {
         return <div style={{ margin: '5px' }}>
-            <div style={{ marginBottom: '10px' }}>
+            <div id='snaplist' style={{ marginBottom: '10px' }}>
                 <LocalStateSnapshotList />
             </div>
-            <div style={{ marginBottom: '10px' }}>
+            <div id='snap' style={{ marginBottom: '10px' }}>
                 <LocalStateSnapshots />
             </div>
 
-            <div style={{ marginBottom: '10px' }}>
+            <div id='snapoption' style={{ marginBottom: '10px' }}>
                 <ExpandGroup header='Snapshot Options' initiallyExpanded={false}>
                     <LocalStateSnapshotParams />
                 </ExpandGroup>
@@ -361,3 +399,336 @@ export class SnapshotControls extends PluginUIComponent<{}> {
         </div>;
     }
 }
+
+export class ExplorerInfo extends PluginUIComponent<{}, { isDisabled: boolean, showHelp: boolean }> {
+    state = {
+        isDisabled: false,
+        showHelp: false
+    };
+
+    componentDidMount() {
+        this.subscribe(this.plugin.state.data.behaviors.isUpdating, v => {
+            this.setState({ isDisabled: v });
+        });
+
+        this.subscribe(this.plugin.state.events.cell.stateUpdated, e => {
+            if (!this.state.isDisabled && MesoscaleState.has(this.plugin) && MesoscaleState.ref(this.plugin) === e.ref) {
+                this.forceUpdate();
+            }
+        });
+    }
+
+    setupDriver = () => {
+        // setup the tour of the interface
+        const driver = (this.plugin.customState as MesoscaleExplorerState).driver;
+        if (!driver) return;
+
+        driver.setSteps([
+            // Left panel
+            { element: '#explorerinfo', popover: { title: 'Explorer Header Info', description: 'This section displays the explorer header with version information, documentation access, and tour navigation. Use the right and left arrow keys to navigate the tour.', side: 'left', align: 'start' } },
+            { element: '#database', popover: { title: 'Import from PDB', description: 'Load structures directly from PDB and PDB-DEV databases.', side: 'bottom', align: 'start' } },
+            { element: '#loader', popover: { title: 'Import from File', description: 'Load local files (.molx, .molj, .zip, .cif, .bcif) using this option.', side: 'bottom', align: 'start' } },
+            { element: '#example', popover: { title: 'Example Models and Tours', description: 'Select from a range of example models and tours provided.', side: 'left', align: 'start' } },
+            { element: '#session', popover: { title: 'Session Management', description: 'Download the current session in .molx format.', side: 'top', align: 'start' } },
+            { element: '#snaplist', popover: { title: 'Snapshot List', description: 'View and manage the list of snapshots. You can reorder them and edit their titles, keys, and descriptions. Snapshot states cannot be edited.', side: 'right', align: 'start' } },
+            { element: '#snap', popover: { title: 'Add Snapshot', description: 'Save the current state (e.g., camera position, color, visibility, etc.) in a snapshot with an optional title, key, and description.', side: 'right', align: 'start' } },
+            { element: '#snapoption', popover: { title: 'Snapshot Options', description: 'These options are saved in the snapshot. Set them before adding a snapshot to see their effect during animation playback.', side: 'right', align: 'start' } },
+            { element: '#exportanimation', popover: { title: 'Export Animation', description: 'Create movies or scenes with rocking, rotating, or snapshots animations.', side: 'right', align: 'start' } },
+            { element: '#viewportsettings', popover: { title: 'Viewport Settings', description: 'Advanced settings for the renderer and trackball.', side: 'right', align: 'start' } },
+            // Viewport
+            { element: '#snapinfo', popover: { title: 'Snapshot Description', description: 'Save the current state (e.g., camera position, color, visibility, etc.) in a snapshot with an optional title, key, and description.', side: 'right', align: 'start' } },
+            { element: '#snapinfoctrl', popover: { title: 'Snapshot Description Control', description: 'Control the visibility and text size of the snapshot description widget.', side: 'right', align: 'start' } },
+            // Right panel
+            { element: '#modelinfo', popover: { title: 'Model Information', description: 'Summary information about the model, if available.', side: 'right', align: 'start' } },
+            { element: '#selestyle', popover: { title: 'Selection Style', description: 'Choose the rendering style for entity selection accessed via Shift/Ctrl mouse. Options include: Color & Outline, Color, Outline.', side: 'right', align: 'start' } },
+            { element: '#seleinfo', popover: { title: 'Selection List', description: 'View the current list of selected entities.', side: 'right', align: 'start' } },
+            { element: '#measurements', popover: { title: 'Measurements', description: 'Use this widget to create labels, measure distances, angles, dihedral orientations, and planes for the selected entities.', side: 'right', align: 'start' } },
+            { element: '#quickstyles', popover: { title: 'Quick Styles', description: 'Change between a selection of style presets.', side: 'right', align: 'start' } },
+            { element: '#graphicsquality', popover: { title: 'Graphics Quality', description: 'Adjust the overall graphics quality. Lower quality improves performance. Options are: Ultra, Quality (Default), Balanced, Performance, Custom. Custom settings use the Culling & LOD values set in the Tree.', side: 'right', align: 'start' } },
+            { element: '#searchtree', popover: { title: 'Search', description: 'Filter the entity tree based on your queries.', side: 'right', align: 'start' } },
+            { element: '#grouptree', popover: { title: 'Group By', description: 'Change the grouping of the hierarchy tree, e.g., group by instance or by compartment.', side: 'right', align: 'start' } },
+            { element: '#tree', popover: { title: 'Tree Hierarchy', description: 'View the hierarchical tree of entity types in the model.', side: 'right', align: 'start' } },
+            { element: '#focusinfo', popover: { title: 'Selection Description', description: 'Detailed information about the current selection, if present in the loaded file.', side: 'right', align: 'start' } },
+            { popover: { title: 'Happy Exploring!', description: 'That’s all! Go ahead and start exploring or creating mesoscale tours.' } }
+        ]);
+        driver.refresh();
+    };
+
+    openHelp = () => {
+        // open a new page with the documentation
+        window.open('https://molstar.org/me-docs/', '_blank');
+    };
+
+    toggleHelp = () => {
+        const driver = (this.plugin.customState as MesoscaleExplorerState).driver;
+        if (!driver || !driver.hasNextStep()) {
+            this.setupDriver();
+        }
+        this.setState({ showHelp: !this.state.showHelp }, () => {
+            if (this.state.showHelp && driver) {
+                driver.drive(); // start at 0
+            }
+        });
+    };
+
+    render() {
+        const driver = (this.plugin.customState as MesoscaleExplorerState).driver;
+        if (!driver) return;
+
+        const help = <IconButton svg={HelpOutlineSvg} toggleState={false} small onClick={this.openHelp} title='Open the Documentation' />;
+        const tour = <IconButton svg={TourSvg} toggleState={false} small onClick={this.toggleHelp} title='Start the interactive tour' />;
+        return <>
+            <div id='explorerinfo' style={{ display: 'flex', alignItems: 'center', padding: '4px 0 4px 8px' }} className='msp-help-text'>
+                <h2 style={{ flexGrow: 1 }}>Mol* Mesoscale Explorer</h2>
+                {tour}{help}
+            </div>
+        </>;
+    }
+}
+
+
+export class MesoQuickStylesControls extends CollapsableControls {
+    defaultState() {
+        return {
+            isCollapsed: true,
+            header: 'Quick Styles',
+            brand: { accent: 'gray' as const, svg: MagicWandSvg }
+        };
+    }
+
+    renderControls() {
+        return <>
+            <MesoQuickStyles />
+        </>;
+    }
+}
+
+export class MesoQuickStyles extends PluginUIComponent {
+    async default() {
+        if (!this.plugin.canvas3d) return;
+        const p = this.plugin.canvas3d.props;
+        this.plugin.canvas3d.setProps({
+            renderer: {
+                exposure: 1.1,
+            },
+            postprocessing: {
+                ...p.postprocessing,
+                shadow: {
+                    name: 'on',
+                    params: {
+                        maxDistance: 80,
+                        steps: 3,
+                        tolerance: 1.0,
+                    }
+                },
+                outline: {
+                    name: 'on',
+                    params: {
+                        scale: 1,
+                        threshold: 0.15,
+                        color: Color(0x000000),
+                        includeTransparent: false,
+                    }
+                },
+                dof: { name: 'off', params: {} },
+            }
+        });
+        await updateStyle(this.plugin, {
+            ignoreLight: true,
+            material: { metalness: 0, roughness: 1.0, bumpiness: 0 },
+            celShaded: false,
+            illustrative: false,
+        });
+    }
+
+    async celshading() {
+        if (!this.plugin.canvas3d) return;
+        const p = this.plugin.canvas3d.props;
+        this.plugin.canvas3d.setProps({
+            renderer: {
+                exposure: 1.5,
+            },
+            postprocessing: {
+                ...p.postprocessing,
+                shadow: {
+                    name: 'on',
+                    params: {
+                        maxDistance: 256,
+                        steps: 64,
+                        tolerance: 1.0,
+                    }
+                },
+                outline: { name: 'off', params: {} },
+                dof: { name: 'off', params: {} },
+            }
+        });
+        await updateStyle(this.plugin, {
+            ignoreLight: false,
+            material: { metalness: 0, roughness: 1.0, bumpiness: 0 },
+            celShaded: true,
+            illustrative: false,
+        });
+    }
+
+    async shinyDof() {
+        if (!this.plugin.canvas3d) return;
+        const p = this.plugin.canvas3d.props;
+        this.plugin.canvas3d.setProps({
+            renderer: {
+                exposure: 1.1,
+            },
+            postprocessing: {
+                ...p.postprocessing,
+                shadow: {
+                    name: 'on',
+                    params: {
+                        maxDistance: 256,
+                        steps: 64,
+                        tolerance: 1.0,
+                    }
+                },
+                outline: { name: 'off', params: {} },
+                dof: {
+                    name: 'on',
+                    params: {
+                        blurSize: 9,
+                        blurSpread: 1.0,
+                        inFocus: 0.0,
+                        PPM: 200.0,
+                        center: 'camera-target',
+                        mode: 'sphere',
+                    }
+                }
+            }
+        });
+        await updateStyle(this.plugin, {
+            ignoreLight: false,
+            material: { metalness: 0, roughness: 0.2, bumpiness: 0 },
+            celShaded: false,
+            illustrative: false,
+        });
+    }
+
+    async illustrative() {
+        if (!this.plugin.canvas3d) return;
+        const p = this.plugin.canvas3d.props;
+        this.plugin.canvas3d.setProps({
+            renderer: {
+                exposure: 1.5,
+            },
+            postprocessing: {
+                ...p.postprocessing,
+                shadow: {
+                    name: 'on',
+                    params: {
+                        maxDistance: 256,
+                        steps: 64,
+                        tolerance: 1.0,
+                    }
+                },
+                outline: {
+                    name: 'on',
+                    params: {
+                        scale: 1,
+                        threshold: 0.15,
+                        color: Color(0x000000),
+                        includeTransparent: false,
+                    }
+                },
+                dof: { name: 'off', params: {} },
+            }
+        });
+        await updateStyle(this.plugin, {
+            ignoreLight: true,
+            material: { metalness: 0, roughness: 1.0, bumpiness: 0 },
+            celShaded: false,
+            illustrative: true,
+        });
+    }
+
+    async shiny() {
+        if (!this.plugin.canvas3d) return;
+        const p = this.plugin.canvas3d.props;
+        this.plugin.canvas3d.setProps({
+            renderer: {
+                exposure: 1.5,
+            },
+            postprocessing: {
+                ...p.postprocessing,
+                shadow: { name: 'off', params: {} },
+                outline: { name: 'off', params: {} },
+                dof: { name: 'off', params: {} },
+            }
+        });
+        await updateStyle(this.plugin, {
+            ignoreLight: false,
+            material: { metalness: 0, roughness: 0.2, bumpiness: 0 },
+            celShaded: false,
+            illustrative: false,
+        });
+    }
+
+    async stylized() {
+        if (!this.plugin.canvas3d) return;
+        const p = this.plugin.canvas3d.props;
+        this.plugin.canvas3d.setProps({
+            renderer: {
+                exposure: 1.1,
+            },
+            postprocessing: {
+                ...p.postprocessing,
+                shadow: {
+                    name: 'on',
+                    params: {
+                        maxDistance: 256,
+                        steps: 64,
+                        tolerance: 1.0,
+                    }
+                },
+                outline: {
+                    name: 'on',
+                    params: {
+                        scale: 1,
+                        threshold: 0.15,
+                        color: Color(0x000000),
+                        includeTransparent: false,
+                    }
+                },
+                dof: { name: 'off', params: {} },
+            }
+        });
+        await updateStyle(this.plugin, {
+            ignoreLight: false,
+            material: { metalness: 0, roughness: 0.2, bumpiness: 0 },
+            celShaded: false,
+            illustrative: true,
+        });
+    }
+
+    render() {
+        return <>
+            <div className='msp-flex-row'>
+                <Button noOverflow title='Applies default representation preset and sets outline and occlusion effects to default' onClick={() => this.default()} style={{ width: 'auto' }}>
+                    Default
+                </Button>
+                <Button noOverflow title='Applies celShading' onClick={() => this.celshading()} style={{ width: 'auto' }}>
+                    Cel-shaded
+                </Button>
+                <Button noOverflow title='Applies illustrative colors preset' onClick={() => this.illustrative()} style={{ width: 'auto' }}>
+                    Illustrative
+                </Button>
+            </div>
+            <div className='msp-flex-row'>
+                <Button noOverflow title='Apply shiny material to default' onClick={() => this.shiny()} style={{ width: 'auto' }}>
+                    Shiny
+                </Button>
+                <Button noOverflow title='Enable shiny material, outline, and illustrative colors' onClick={() => this.stylized()} style={{ width: 'auto' }}>
+                    Shiny-Illustrative
+                </Button>
+                <Button noOverflow title='Enable DOF and shiny material' onClick={() => this.shinyDof()} style={{ width: 'auto' }}>
+                    Shiny-DOF
+                </Button>
+            </div>
+        </>;
+    }
+}

src/apps/viewer/app.ts

@@ -1,8 +1,10 @@
 /**
- * Copyright (c) 2018-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2018-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author David Sehnal <david.sehnal@gmail.com>
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ * @author Neli Fonseca <neli@ebi.ac.uk>
+ * @author Adam Midlik <midlik@gmail.com>
  */
 
 import { ANVILMembraneOrientation } from '../../extensions/anvil/behavior';
@@ -10,17 +12,18 @@ import { Backgrounds } from '../../extensions/backgrounds';
 import { DnatcoNtCs } from '../../extensions/dnatco';
 import { G3DFormat, G3dProvider } from '../../extensions/g3d/format';
 import { GeometryExport } from '../../extensions/geo-export';
-import { MAQualityAssessment, QualityAssessmentPLDDTPreset, QualityAssessmentQmeanPreset } from '../../extensions/model-archive/quality-assessment/behavior';
+import { MAQualityAssessment, MAQualityAssessmentConfig, QualityAssessmentPLDDTPreset, QualityAssessmentQmeanPreset } from '../../extensions/model-archive/quality-assessment/behavior';
 import { QualityAssessment } from '../../extensions/model-archive/quality-assessment/prop';
 import { ModelExport } from '../../extensions/model-export';
 import { Mp4Export } from '../../extensions/mp4-export';
 import { MolViewSpec } from '../../extensions/mvs/behavior';
-import { loadMVS } from '../../extensions/mvs/load';
+import { loadMVSX } from '../../extensions/mvs/components/formats';
+import { loadMVS, MolstarLoadingExtension } from '../../extensions/mvs/load';
 import { MVSData } from '../../extensions/mvs/mvs-data';
 import { PDBeStructureQualityReport } from '../../extensions/pdbe';
 import { RCSBValidationReport } from '../../extensions/rcsb';
 import { AssemblySymmetry, AssemblySymmetryConfig } from '../../extensions/assembly-symmetry';
-import { SbNcbrPartialCharges, SbNcbrPartialChargesPreset, SbNcbrPartialChargesPropertyProvider } from '../../extensions/sb-ncbr';
+import { SbNcbrPartialCharges, SbNcbrPartialChargesPreset, SbNcbrPartialChargesPropertyProvider, SbNcbrTunnels } from '../../extensions/sb-ncbr';
 import { Volseg, VolsegVolumeServerConfig } from '../../extensions/volumes-and-segmentations';
 import { wwPDBChemicalComponentDictionary } from '../../extensions/wwpdb/ccd/behavior';
 import { wwPDBStructConnExtensionFunctions } from '../../extensions/wwpdb/struct-conn';
@@ -45,11 +48,12 @@ import { createPluginUI } from '../../mol-plugin-ui';
 import { renderReact18 } from '../../mol-plugin-ui/react18';
 import { DefaultPluginUISpec, PluginUISpec } from '../../mol-plugin-ui/spec';
 import { PluginCommands } from '../../mol-plugin/commands';
-import { PluginConfig } from '../../mol-plugin/config';
+import { PluginConfig, PluginConfigItem } from '../../mol-plugin/config';
 import { PluginLayoutControlsDisplay } from '../../mol-plugin/layout';
 import { PluginSpec } from '../../mol-plugin/spec';
 import { PluginState } from '../../mol-plugin/state';
 import { StateObjectRef, StateObjectSelector } from '../../mol-state';
+import { Task } from '../../mol-task';
 import { Asset } from '../../mol-util/assets';
 import { Color } from '../../mol-util/color';
 import '../../mol-util/polyfill';
@@ -67,7 +71,7 @@ export const ExtensionMap = {
     'backgrounds': PluginSpec.Behavior(Backgrounds),
     'dnatco-ntcs': PluginSpec.Behavior(DnatcoNtCs),
     'pdbe-structure-quality-report': PluginSpec.Behavior(PDBeStructureQualityReport),
-    'rcsb-assembly-symmetry': PluginSpec.Behavior(AssemblySymmetry),
+    'assembly-symmetry': PluginSpec.Behavior(AssemblySymmetry),
     'rcsb-validation-report': PluginSpec.Behavior(RCSBValidationReport),
     'anvil-membrane-orientation': PluginSpec.Behavior(ANVILMembraneOrientation),
     'g3d': PluginSpec.Behavior(G3DFormat),
@@ -79,6 +83,7 @@ export const ExtensionMap = {
     'sb-ncbr-partial-charges': PluginSpec.Behavior(SbNcbrPartialCharges),
     'wwpdb-chemical-component-dictionary': PluginSpec.Behavior(wwPDBChemicalComponentDictionary),
     'mvs': PluginSpec.Behavior(MolViewSpec),
+    'tunnels': PluginSpec.Behavior(SbNcbrTunnels),
 };
 
 const DefaultViewerOptions = {
@@ -101,6 +106,8 @@ const DefaultViewerOptions = {
     preferWebgl1: PluginConfig.General.PreferWebGl1.defaultValue,
     allowMajorPerformanceCaveat: PluginConfig.General.AllowMajorPerformanceCaveat.defaultValue,
     powerPreference: PluginConfig.General.PowerPreference.defaultValue,
+    resolutionMode: PluginConfig.General.ResolutionMode.defaultValue,
+    illumination: false,
 
     viewportShowExpand: PluginConfig.Viewport.ShowExpand.defaultValue,
     viewportShowControls: PluginConfig.Viewport.ShowControls.defaultValue,
@@ -118,6 +125,8 @@ const DefaultViewerOptions = {
     rcsbAssemblySymmetryDefaultServerType: AssemblySymmetryConfig.DefaultServerType.defaultValue,
     rcsbAssemblySymmetryDefaultServerUrl: AssemblySymmetryConfig.DefaultServerUrl.defaultValue,
     rcsbAssemblySymmetryApplyColors: AssemblySymmetryConfig.ApplyColors.defaultValue,
+
+    config: [] as [PluginConfigItem, any][],
 };
 type ViewerOptions = typeof DefaultViewerOptions;
 
@@ -178,6 +187,7 @@ export class Viewer {
                 [PluginConfig.General.PreferWebGl1, o.preferWebgl1],
                 [PluginConfig.General.AllowMajorPerformanceCaveat, o.allowMajorPerformanceCaveat],
                 [PluginConfig.General.PowerPreference, o.powerPreference],
+                [PluginConfig.General.ResolutionMode, o.resolutionMode],
                 [PluginConfig.Viewport.ShowExpand, o.viewportShowExpand],
                 [PluginConfig.Viewport.ShowControls, o.viewportShowControls],
                 [PluginConfig.Viewport.ShowSettings, o.viewportShowSettings],
@@ -196,6 +206,7 @@ export class Viewer {
                 [AssemblySymmetryConfig.DefaultServerType, o.rcsbAssemblySymmetryDefaultServerType],
                 [AssemblySymmetryConfig.DefaultServerUrl, o.rcsbAssemblySymmetryDefaultServerUrl],
                 [AssemblySymmetryConfig.ApplyColors, o.rcsbAssemblySymmetryApplyColors],
+                ...(o.config ?? []),
             ]
         };
 
@@ -213,6 +224,7 @@ export class Viewer {
                 plugin.builders.structure.representation.registerPreset(ViewerAutoPreset);
             }
         });
+        plugin.canvas3d?.setProps({ illumination: { enabled: o.illumination } });
         return new Viewer(plugin);
     }
 
@@ -314,7 +326,10 @@ export class Viewer {
             source: {
                 name: 'alphafolddb' as const,
                 params: {
-                    id: afdb,
+                    provider: {
+                        id: afdb,
+                        encoding: 'bcif'
+                    },
                     options: {
                         ...params.source.params.options,
                         representation: 'preset-structure-representation-ma-quality-assessment-plddt'
@@ -420,6 +435,34 @@ export class Viewer {
         });
     }
 
+    loadFullResolutionEMDBMap(emdbId: string, options: { isoValue: Volume.IsoValue, color?: Color }) {
+        const plugin = this.plugin;
+        const numericId = parseInt(emdbId.toUpperCase().replace('EMD-', ''));
+        const url = `https://ftp.ebi.ac.uk/pub/databases/emdb/structures/EMD-${numericId}/map/emd_${numericId}.map.gz`;
+
+        return plugin.dataTransaction(async () => {
+            const data = await plugin.build().toRoot()
+                .apply(StateTransforms.Data.Download, { url, isBinary: true, label: emdbId }, { state: { isGhost: true } })
+                .apply(StateTransforms.Data.DeflateData)
+                .commit();
+
+            const parsed = await plugin.dataFormats.get('ccp4')!.parse(plugin, data, { entryId: emdbId });
+            const firstVolume = (parsed.volume || parsed.volumes[0]) as StateObjectSelector<PluginStateObject.Volume.Data>;
+            if (!firstVolume?.isOk) throw new Error('Failed to parse any volume.');
+
+            const volume: StateObjectSelector<PluginStateObject.Volume.Data> = parsed.volumes?.[0] ?? parsed.volume;
+            await plugin.build()
+                .to(volume)
+                .apply(StateTransforms.Representation.VolumeRepresentation3D, createVolumeRepresentationParams(this.plugin, firstVolume.data!, {
+                    type: 'isosurface',
+                    typeParams: { alpha: 1, isoValue: options.isoValue },
+                    color: 'uniform',
+                    colorParams: { value: options.color ?? Color(0x33BB33) }
+                }))
+                .commit();
+        });
+    }
+
     /**
      * @example
      *  viewer.loadTrajectory({
@@ -468,25 +511,46 @@ export class Viewer {
         return { model, coords, preset };
     }
 
-    async loadMvsFromUrl(url: string, format: 'mvsj') {
+    async loadMvsFromUrl(url: string, format: 'mvsj' | 'mvsx', options?: { replaceExisting?: boolean, keepCamera?: boolean, extensions?: MolstarLoadingExtension<any>[] }) {
         if (format === 'mvsj') {
             const data = await this.plugin.runTask(this.plugin.fetch({ url, type: 'string' }));
             const mvsData = MVSData.fromMVSJ(data);
-            await loadMVS(this.plugin, mvsData, { sanityChecks: true, sourceUrl: url });
+            await loadMVS(this.plugin, mvsData, { sanityChecks: true, sourceUrl: url, ...options });
+        } else if (format === 'mvsx') {
+            const data = await this.plugin.runTask(this.plugin.fetch({ url, type: 'binary' }));
+            await this.plugin.runTask(Task.create('Load MVSX file', async ctx => {
+                const parsed = await loadMVSX(this.plugin, ctx, data);
+                await loadMVS(this.plugin, parsed.mvsData, { sanityChecks: true, sourceUrl: parsed.sourceUrl, ...options });
+            }));
         } else {
             throw new Error(`Unknown MolViewSpec format: ${format}`);
         }
-        // We might add more formats in the future
     }
 
-    async loadMvsData(data: string, format: 'mvsj') {
+    /** Load MolViewSpec from `data`.
+     * If `format` is 'mvsj', `data` must be a string or a Uint8Array containing a UTF8-encoded string.
+     * If `format` is 'mvsx', `data` must be a Uint8Array or a string containing base64-encoded binary data prefixed with 'base64,'. */
+    async loadMvsData(data: string | Uint8Array, format: 'mvsj' | 'mvsx', options?: { replaceExisting?: boolean, keepCamera?: boolean, extensions?: MolstarLoadingExtension<any>[] }) {
+        if (typeof data === 'string' && data.startsWith('base64')) {
+            data = Uint8Array.from(atob(data.substring(7)), c => c.charCodeAt(0)); // Decode base64 string to Uint8Array
+        }
         if (format === 'mvsj') {
+            if (typeof data !== 'string') {
+                data = new TextDecoder().decode(data); // Decode Uint8Array to string using UTF8
+            }
             const mvsData = MVSData.fromMVSJ(data);
-            await loadMVS(this.plugin, mvsData, { sanityChecks: true, sourceUrl: undefined });
+            await loadMVS(this.plugin, mvsData, { sanityChecks: true, sourceUrl: undefined, ...options });
+        } else if (format === 'mvsx') {
+            if (typeof data === 'string') {
+                throw new Error("loadMvsData: if `format` is 'mvsx', then `data` must be a Uint8Array or a base64-encoded string prefixed with 'base64,'.");
+            }
+            await this.plugin.runTask(Task.create('Load MVSX file', async ctx => {
+                const parsed = await loadMVSX(this.plugin, ctx, data as Uint8Array);
+                await loadMVS(this.plugin, parsed.mvsData, { sanityChecks: true, sourceUrl: parsed.sourceUrl, ...options });
+            }));
         } else {
             throw new Error(`Unknown MolViewSpec format: ${format}`);
         }
-        // We might add more formats in the future
     }
 
     handleResize() {
@@ -555,4 +619,9 @@ export const ViewerAutoPreset = StructureRepresentationPresetProvider({
 export const PluginExtensions = {
     wwPDBStructConn: wwPDBStructConnExtensionFunctions,
     mvs: { MVSData, loadMVS },
+    modelArchive: {
+        qualityAssessment: {
+            config: MAQualityAssessmentConfig
+        }
+    }
 };

src/apps/viewer/index.html

@@ -63,6 +63,8 @@
             var preferWebgl1 = getParam('prefer-webgl1', '[^&]+').trim() === '1' || void 0;
             var allowMajorPerformanceCaveat = getParam('allow-major-performance-caveat', '[^&]+').trim() === '1';
             var powerPreference = getParam('power-preference', '[^&]+').trim().toLowerCase();
+            var illumination = getParam('illumination', '[^&]+').trim() === '1';
+            var resolutionMode = getParam('resolution-mode', '[^&]+').trim().toLowerCase();
 
             // console.log('Available extensions: ', Object.keys(molstar.ExtensionMap));
 
@@ -83,6 +85,8 @@
                 preferWebgl1: preferWebgl1,
                 allowMajorPerformanceCaveat: allowMajorPerformanceCaveat,
                 powerPreference: powerPreference || 'high-performance',
+                illumination: illumination,
+                resolutionMode: resolutionMode || 'auto'
             }).then(viewer => {
                 var snapshotId = getParam('snapshot-id', '[^&]+').trim();
                 if (snapshotId) viewer.setRemoteSnapshot(snapshotId);

src/cli/cifschema/index.ts

@@ -158,8 +158,8 @@ async function ensureDicAvailable(dicPath: string, dicUrl: string) {
 const DIC_DIR = path.resolve(__dirname, '../../../../build/dics/');
 const MMCIF_DIC_PATH = `${DIC_DIR}/mmcif_pdbx_v50.dic`;
 const MMCIF_DIC_URL = 'http://mmcif.wwpdb.org/dictionaries/ascii/mmcif_pdbx_v50.dic';
-const IHM_DIC_PATH = `${DIC_DIR}/ihm-extension.dic`;
-const IHM_DIC_URL = 'https://raw.githubusercontent.com/ihmwg/IHM-dictionary/master/ihm-extension.dic';
+const IHM_DIC_PATH = `${DIC_DIR}/mmcif_ihm_ext.dic`;
+const IHM_DIC_URL = 'https://raw.githubusercontent.com/ihmwg/IHMCIF/master/dist/mmcif_ihm_ext.dic';
 const MA_DIC_PATH = `${DIC_DIR}/ma-extension.dic`;
 const MA_DIC_URL = 'https://raw.githubusercontent.com/ihmwg/ModelCIF/master/dist/mmcif_ma.dic';
 

src/cli/cifschema/util/cif-dic.ts

@@ -41,6 +41,7 @@ export function getFieldType(type: string, description: string, values?: string[
         case 'pdbx_related_db_id':
         case 'sequence_dep':
         case 'pdb_id':
+        case 'pdb_id_u': // should be case insensitve, but can't express that
         case 'emd_id':
         // todo, consider adding specialised fields
         case 'yyyy-mm-dd':
@@ -233,13 +234,19 @@ const FORCE_INT_FIELDS = [
     '_atom_site.id',
     '_atom_site.auth_seq_id',
     '_atom_site_anisotrop.id',
+    '_atom_site_anisotrop.pdbx_auth_seq_id',
     '_pdbx_struct_mod_residue.auth_seq_id',
+    '_pdbx_unobs_or_zero_occ_residues.auth_seq_id',
     '_struct_conf.beg_auth_seq_id',
     '_struct_conf.end_auth_seq_id',
     '_struct_conn.ptnr1_auth_seq_id',
     '_struct_conn.ptnr2_auth_seq_id',
     '_struct_sheet_range.beg_auth_seq_id',
     '_struct_sheet_range.end_auth_seq_id',
+    '_struct_site.pdbx_auth_seq_id',
+    '_struct_site_gen.auth_seq_id',
+    '_struct_mon_prot_cis.auth_seq_id',
+    '_struct_mon_prot_cis.pdbx_auth_seq_id_2',
 ];
 
 /**

src/cli/lipid-params/index.ts

@@ -13,8 +13,8 @@ import { UniqueArray } from '../../mol-data/generic';
 
 const LIPIDS_DIR = path.resolve(__dirname, '../../../../build/lipids/');
 
-const MARTINI_LIPIDS_PATH = path.resolve(LIPIDS_DIR, 'martini_lipids.itp');
-const MARTINI_LIPIDS_URL = 'http://www.cgmartini.nl/images/parameters/lipids/Collections/martini_v2.0_lipids_all_201506.itp';
+const MARTINI_LIPIDS_PATH = path.resolve(LIPIDS_DIR, 'martini_lipids_v3.itp');
+const MARTINI_LIPIDS_URL = 'https://cgmartini-library.s3.ca-central-1.amazonaws.com/1_Downloads/ff_parameters/martini3/martini_v3.0.0_phospholipids_v1.itp';
 
 async function ensureAvailable(path: string, url: string) {
     if (FORCE_DOWNLOAD || !fs.existsSync(path)) {
@@ -32,6 +32,7 @@ async function ensureAvailable(path: string, url: string) {
 async function ensureLipidsAvailable() { await ensureAvailable(MARTINI_LIPIDS_PATH, MARTINI_LIPIDS_URL); }
 
 const extraLipids = ['DMPC'];
+const v2lipids = ['DAPC', 'DBPC', 'DFPC', 'DGPC', 'DIPC', 'DLPC', 'DNPC', 'DOPC', 'DPPC', 'DRPC', 'DTPC', 'DVPC', 'DXPC', 'DYPC', 'LPPC', 'PAPC', 'PEPC', 'PGPC', 'PIPC', 'POPC', 'PRPC', 'PUPC', 'DAPE', 'DBPE', 'DFPE', 'DGPE', 'DIPE', 'DLPE', 'DNPE', 'DOPE', 'DPPE', 'DRPE', 'DTPE', 'DUPE', 'DVPE', 'DXPE', 'DYPE', 'LPPE', 'PAPE', 'PGPE', 'PIPE', 'POPE', 'PQPE', 'PRPE', 'PUPE', 'DAPS', 'DBPS', 'DFPS', 'DGPS', 'DIPS', 'DLPS', 'DNPS', 'DOPS', 'DPPS', 'DRPS', 'DTPS', 'DUPS', 'DVPS', 'DXPS', 'DYPS', 'LPPS', 'PAPS', 'PGPS', 'PIPS', 'POPS', 'PQPS', 'PRPS', 'PUPS', 'DAPG', 'DBPG', 'DFPG', 'DGPG', 'DIPG', 'DLPG', 'DNPG', 'DOPG', 'DPPG', 'DRPG', 'DTPG', 'DVPG', 'DXPG', 'DYPG', 'LPPG', 'PAPG', 'PGPG', 'PIPG', 'POPG', 'PRPG', 'DAPA', 'DBPA', 'DFPA', 'DGPA', 'DIPA', 'DLPA', 'DNPA', 'DOPA', 'DPPA', 'DRPA', 'DTPA', 'DVPA', 'DXPA', 'DYPA', 'LPPA', 'PAPA', 'PGPA', 'PIPA', 'POPA', 'PRPA', 'PUPA', 'DPP', 'DPPI', 'PAPI', 'PIPI', 'POP', 'POPI', 'PUPI', 'PVP', 'PVPI', 'PADG', 'PIDG', 'PODG', 'PUDG', 'PVDG', 'APC', 'CPC', 'IPC', 'LPC', 'OPC', 'PPC', 'TPC', 'UPC', 'VPC', 'BNSM', 'DBSM', 'DPSM', 'DXSM', 'PGSM', 'PNSM', 'POSM', 'PVSM', 'XNSM', 'DPCE', 'DXCE', 'PNCE', 'XNCE'];
 
 async function run(out: string) {
     await ensureLipidsAvailable();
@@ -50,11 +51,15 @@ async function run(out: string) {
         UniqueArray.add(lipids, v, v);
     }
 
+    for (const v of v2lipids) {
+        UniqueArray.add(lipids, v, v);
+    }
+
     const lipidNames = JSON.stringify(lipids.array);
 
     if (out) {
         const output = `/**
- * Copyright (c) 2020 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * Code-generated lipid params file. Names extracted from Martini FF lipids itp.
  *

src/cli/mvs/mvs-print-schema.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 /**
  * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
@@ -11,7 +12,6 @@
 
 import { ArgumentParser } from 'argparse';
 import { treeSchemaToMarkdown, treeSchemaToString } from '../../extensions/mvs/tree/generic/tree-schema';
-import { MVSDefaults } from '../../extensions/mvs/tree/mvs/mvs-defaults';
 import { MVSTreeSchema } from '../../extensions/mvs/tree/mvs/mvs-tree';
 
 
@@ -31,9 +31,9 @@ function parseArguments(): Args {
 /** Main workflow for printing MolViewSpec tree schema. */
 function main(args: Args) {
     if (args.markdown) {
-        console.log(treeSchemaToMarkdown(MVSTreeSchema, MVSDefaults));
+        console.log(treeSchemaToMarkdown(MVSTreeSchema));
     } else {
-        console.log(treeSchemaToString(MVSTreeSchema, MVSDefaults));
+        console.log(treeSchemaToString(MVSTreeSchema));
     }
 }
 

src/cli/mvs/mvs-render.ts

@@ -1,12 +1,18 @@
+#!/usr/bin/env node
 /**
- * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2023-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Adam Midlik <midlik@gmail.com>
  *
  * Command-line application for rendering images from MolViewSpec files
- * Build: npm install --no-save canvas gl jpeg-js pngjs  // these packages are not listed in Mol* dependencies for performance reasons
- *        npm run build
- * Run:   node lib/commonjs/cli/mvs/mvs-render -i examples/mvs/1cbs.mvsj -o ../outputs/1cbs.png --size 800x600 --molj
+ * From Molstar NPM package:
+ *     npm install molstar canvas gl jpeg-js pngjs
+ *     npx mvs-render -i examples/mvs/1cbs.mvsj -o ../outputs/1cbs.png --size 800x600 --molj
+ * From Molstar source code:
+ *     npm install
+ *     npm install --no-save canvas gl jpeg-js pngjs  // these packages are not listed in Mol* dependencies for performance reasons
+ *     npm run build
+ *     node lib/commonjs/cli/mvs/mvs-render -i examples/mvs/1cbs.mvsj -o ../outputs/1cbs.png --size 800x600 --molj
  */
 
 import { ArgumentParser } from 'argparse';
@@ -17,19 +23,22 @@ import path from 'path';
 import pngjs from 'pngjs';
 
 import { Canvas3DParams } from '../../mol-canvas3d/canvas3d';
+import { setCanvasModule } from '../../mol-geo/geometry/text/font-atlas';
 import { PluginContext } from '../../mol-plugin/context';
 import { HeadlessPluginContext } from '../../mol-plugin/headless-plugin-context';
 import { DefaultPluginSpec, PluginSpec } from '../../mol-plugin/spec';
 import { ExternalModules, defaultCanvas3DParams } from '../../mol-plugin/util/headless-screenshot';
+import { Task } from '../../mol-task';
 import { setFSModule } from '../../mol-util/data-source';
 import { onelinerJsonString } from '../../mol-util/json';
 import { ParamDefinition as PD } from '../../mol-util/param-definition';
 
 // MolViewSpec must be imported after HeadlessPluginContext
+import { Mp4Export } from '../../extensions/mp4-export';
 import { MolViewSpec } from '../../extensions/mvs/behavior';
+import { loadMVSX } from '../../extensions/mvs/components/formats';
 import { loadMVS } from '../../extensions/mvs/load';
 import { MVSData } from '../../extensions/mvs/mvs-data';
-import { setCanvasModule } from '../../mol-geo/geometry/text/font-atlas';
 
 
 setFSModule(fs);
@@ -43,15 +52,17 @@ interface Args {
     output: string[],
     size: { width: number, height: number },
     molj: boolean,
+    no_extensions: boolean,
 }
 
 /** Return parsed command line arguments for `main` */
 function parseArguments(): Args {
     const parser = new ArgumentParser({ description: 'Command-line application for rendering images from MolViewSpec files' });
-    parser.add_argument('-i', '--input', { required: true, nargs: '+', help: 'Input file(s) in .mvsj format' });
+    parser.add_argument('-i', '--input', { required: true, nargs: '+', help: 'Input file(s) in .mvsj or .mvsx format. File format is inferred from the file extension.' });
     parser.add_argument('-o', '--output', { required: true, nargs: '+', help: 'File path(s) for output files (one output path for each input file). Output format is inferred from the file extension (.png or .jpg)' });
     parser.add_argument('-s', '--size', { help: `Output image resolution, {width}x{height}. Default: ${DEFAULT_SIZE}.`, default: DEFAULT_SIZE });
     parser.add_argument('-m', '--molj', { action: 'store_true', help: `Save Mol* state (.molj) in addition to rendered images (use the same output file paths but with .molj extension)` });
+    parser.add_argument('-n', '--no-extensions', { action: 'store_true', help: `Do not apply builtin MVS-loading extensions (not a part of standard MVS specification)` });
     const args = parser.parse_args();
     try {
         const parts = args.size.split('x');
@@ -75,15 +86,31 @@ async function main(args: Args): Promise<void> {
         const output = args.output[i];
         console.log(`Processing ${input} -> ${output}`);
 
-        const data = fs.readFileSync(input, { encoding: 'utf8' });
-        const mvsData = MVSData.fromMVSJ(data);
+        let mvsData: MVSData;
+        let sourceUrl: string | undefined;
+        if (input.toLowerCase().endsWith('.mvsj')) {
+            const data = fs.readFileSync(input, { encoding: 'utf8' });
+            mvsData = MVSData.fromMVSJ(data);
+            sourceUrl = `file://${path.resolve(input)}`;
+        } else if (input.toLowerCase().endsWith('.mvsx')) {
+            const data = fs.readFileSync(input);
+            const mvsx = await plugin.runTask(Task.create('Load MVSX', async ctx => loadMVSX(plugin, ctx, data)));
+            mvsData = mvsx.mvsData;
+            sourceUrl = mvsx.sourceUrl;
+        } else {
+            throw new Error(`Input file name must end with .mvsj or .mvsx: ${input}`);
+        }
+        await loadMVS(plugin, mvsData, { sanityChecks: true, replaceExisting: true, sourceUrl: sourceUrl, extensions: args.no_extensions ? [] : undefined });
 
-        await loadMVS(plugin, mvsData, { sanityChecks: true, replaceExisting: true, sourceUrl: `file://${path.resolve(input)}` });
         fs.mkdirSync(path.dirname(output), { recursive: true });
         if (args.molj) {
             await plugin.saveStateSnapshot(withExtension(output, '.molj'));
         }
-        await plugin.saveImage(output);
+        if (output.toLowerCase().endsWith('.mp4')) {
+            await plugin.saveAnimation(output);
+        } else {
+            await plugin.saveImage(output);
+        }
         checkState(plugin);
     }
     await plugin.clear();
@@ -95,6 +122,7 @@ async function createHeadlessPlugin(args: Pick<Args, 'size'>): Promise<HeadlessP
     const externalModules: ExternalModules = { gl, pngjs, 'jpeg-js': jpegjs };
     const spec = DefaultPluginSpec();
     spec.behaviors.push(PluginSpec.Behavior(MolViewSpec));
+    spec.behaviors.push(PluginSpec.Behavior(Mp4Export));
     const headlessCanvasOptions = defaultCanvas3DParams();
     const canvasOptions = {
         ...PD.getDefaultValues(Canvas3DParams),

src/cli/mvs/mvs-validate.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 /**
  * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *

src/examples/alphafolddb-pae/index.html

@@ -0,0 +1,58 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
+        <title>Mol* AlphaFold DB Predicted Aligned Error Example</title>
+        <style>
+            * {
+                margin: 0;
+                padding: 0;
+                box-sizing: border-box;
+                font-family: sans-serif;
+            }
+            #app {
+                position: absolute;
+                top: 20px;
+                left: 20px;
+                width: 640px;
+                height: 480px;
+            }
+
+            #plot {
+                position: absolute;
+                left: 680px;
+                top: 20px;
+                width: 480px;
+                height: 480px;
+            }
+
+            #controls {
+                position: absolute;
+                left: 20px;
+                top: 520px;
+                font-family: sans-serif;
+                font-size: smaller;
+            }
+        </style>
+        <link rel="stylesheet" type="text/css" href="molstar.css" />
+        <script type="text/javascript" src="./index.js"></script>
+    </head>
+    <body>
+        <div id='controls'>
+            <input type='text' id='af-id' value='Q8W3K0' />
+            <button id='af-load'>Load</button>
+        </div>
+        <div id='app'></div>
+        <div id='plot'></div>
+        <script>
+            AlphaFoldPAEExample.init({ pluginContainerId: 'app', plotContainerId: 'plot' }).then(example => {
+                example.load('Q8W3K0')
+            });
+
+            function $(id) { return document.getElementById(id); }
+            $('af-load').onclick = () => AlphaFoldPAEExample.load($('af-id').value)
+        </script>
+        <!-- __MOLSTAR_ANALYTICS__ -->
+    </body>
+</html>

src/examples/alphafolddb-pae/index.tsx

@@ -0,0 +1,96 @@
+/**
+ * Copyright (c) 2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+
+import { createRoot } from 'react-dom/client';
+import { Viewer } from '../../apps/viewer/app';
+import { MAPairwiseScorePlot } from '../../extensions/model-archive/quality-assessment/pairwise/ui';
+import { QualityAssessment } from '../../extensions/model-archive/quality-assessment/prop';
+import { Model, ResidueIndex } from '../../mol-model/structure';
+import './index.html';
+require('mol-plugin-ui/skin/light.scss');
+
+export class AlphaFoldPAEExample {
+    viewer: Viewer;
+    plotContainerId: string;
+
+
+    async init(options: { pluginContainerId: string, plotContainerId: string }) {
+        this.plotContainerId = options.plotContainerId;
+        this.viewer = await Viewer.create(options.pluginContainerId, {
+            layoutIsExpanded: false,
+            layoutShowControls: false,
+            layoutShowLeftPanel: false,
+            layoutShowLog: false,
+        });
+
+        return this;
+    }
+
+    async load(afId: string) {
+        const id = afId.trim().toUpperCase();
+
+        const plotRoot = createRoot(document.getElementById(this.plotContainerId)!);
+        plotRoot.render(<div>Loading...</div>);
+
+        await this.viewer.plugin.clear();
+        await this.viewer.loadAlphaFoldDb(id);
+
+        try {
+            const req = await fetch(`https://alphafold.ebi.ac.uk/files/AF-${id}-F1-predicted_aligned_error_v4.json`);
+            const json = await req.json();
+
+            const model = this.viewer.plugin.managers.structure.hierarchy.current.models[0]?.cell.obj?.data!;
+            const metric = pairwiseMetricFromAlphaFoldDbJson(model, json)!;
+
+            createRoot(document.getElementById(this.plotContainerId)!).render(
+                <div className='msp-plugin' style={{ background: 'white' }}>
+                    <MAPairwiseScorePlot plugin={this.viewer.plugin} pairwiseMetric={metric} model={model} />
+                </div>
+            );
+        } catch (err) {
+            plotRoot.render(<div>Error: {String(err)}</div>);
+        }
+    }
+}
+
+function pairwiseMetricFromAlphaFoldDbJson(model: Model, data: any): QualityAssessment.Pairwise | undefined {
+    if (!Array.isArray(data) || !data[0]?.predicted_aligned_error) return undefined;
+
+    const { residues, residueAtomSegments, atomSourceIndex } = model.atomicHierarchy;
+    const sortedResidueIndices = new Array(residues._rowCount).fill(0).map((_, i) => i);
+    sortedResidueIndices.sort((a, b) => {
+        const idxA = atomSourceIndex.value(residueAtomSegments.offsets[a]);
+        const idxB = atomSourceIndex.value(residueAtomSegments.offsets[b]);
+        return idxA - idxB;
+    });
+
+    const metricData = data[0].predicted_aligned_error as number[][];
+
+    const metric: QualityAssessment.Pairwise = {
+        id: 0,
+        name: 'AlphaFold DB PAE',
+        residueRange: [0 as ResidueIndex, (residues._rowCount - 1) as ResidueIndex],
+        valueRange: [0, data[0].max_predicted_aligned_error],
+        values: {}
+    };
+
+    for (let i = 0; i < metricData.length; i++) {
+        const rA = sortedResidueIndices[i];
+        if (typeof rA !== 'number') continue;
+        const row = metricData[i];
+        const xs: any = (metric.values[rA as ResidueIndex] = {});
+        for (let j = 0; j < row.length; j++) {
+            const rB = sortedResidueIndices[j];
+            if (typeof rB !== 'number') continue;
+            xs[rB] = row[j];
+        }
+    }
+
+    return metric;
+}
+
+(window as any).AlphaFoldPAEExample = new AlphaFoldPAEExample();

src/examples/glb-export/index.ts

@@ -0,0 +1,97 @@
+/**
+ * Copyright (c) 2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alex Chan <smalldirkalex@gmail.com>
+ *
+ * Thanks to @author Adam Midlik <midlik@gmail.com> for the example code ../image-renderer and https://github.com/midlik/surface-calculator i can make reference to,
+ *
+ * Example command-line application generating and exporting PubChem SDF structures
+ * Build: npm install --no-save gl  // these packages are not listed in dependencies for performance reasons
+ *        npm run build
+ * Run:   node lib/commonjs/examples/glb-export 2519 ../outputs_2519/
+ */
+
+import { ArgumentParser } from 'argparse';
+import fs from 'fs';
+import path from 'path';
+import gl from 'gl';
+
+import { Task } from '../../mol-task';
+import { Download } from '../../mol-plugin-state/transforms/data';
+import { GraphicsRenderObject } from '../../mol-gl/render-object';
+import { GlbExporter } from '../../extensions/geo-export/glb-exporter';
+import { Box3D } from '../../mol-math/geometry';
+import { ModelFromTrajectory, StructureFromModel, TrajectoryFromSDF } from '../../mol-plugin-state/transforms/model';
+import { StructureRepresentation3D } from '../../mol-plugin-state/transforms/representation';
+import { HeadlessPluginContext } from '../../mol-plugin/headless-plugin-context';
+import { DefaultPluginSpec } from '../../mol-plugin/spec';
+import { ExternalModules } from '../../mol-plugin/util/headless-screenshot';
+import { setFSModule } from '../../mol-util/data-source';
+
+setFSModule(fs);
+
+// cid `2519` for Caffeine
+interface Args {
+    cid: string,
+    outDirectory: string
+}
+
+function parseArguments(): Args {
+    const parser = new ArgumentParser({ description: 'Example command-line application exporting .glb file of SDF structures from PubChem' });
+    parser.add_argument('cid', { help: 'PubChem identifier' });
+    parser.add_argument('outDirectory', { help: 'Directory for outputs' });
+    const args = parser.parse_args();
+    return { ...args };
+}
+
+async function main() {
+    const args = parseArguments();
+    const root = 'https://pubchem.ncbi.nlm.nih.gov/rest';
+    const url = `${root}/pug/compound/cid/${args.cid}/sdf?record_type=3d`;
+
+    console.log('PubChem CID:', args.cid);
+    console.log('Source URL:', url);
+    console.log('Outputs:', args.outDirectory);
+
+    // Create a headless plugin
+    const externalModules: ExternalModules = { gl };
+    const plugin = new HeadlessPluginContext(externalModules, DefaultPluginSpec());
+    await plugin.init();
+
+    // Download and visualize data in the plugin
+    const update = plugin.build();
+    const structure = await update.toRoot()
+        .apply(Download, { url, isBinary: false })
+        .apply(TrajectoryFromSDF)
+        .apply(ModelFromTrajectory)
+        .apply(StructureFromModel)
+        .apply(StructureRepresentation3D, {
+            type: { name: 'ball-and-stick', params: { size: 'physical' } },
+            colorTheme: { name: 'element-symbol', params: { carbonColor: { name: 'element-symbol', params: {} } } },
+            sizeTheme: { name: 'physical', params: {} },
+        })
+        .commit();
+
+    const meshes = structure.data!.repr.renderObjects.filter(obj => obj.type === 'mesh') as GraphicsRenderObject<'mesh'>[];
+
+    const boundingSphere = plugin.canvas3d?.boundingSphereVisible!;
+    const boundingBox = Box3D.fromSphere3D(Box3D(), boundingSphere);
+
+    const renderObjectExporter = new GlbExporter(boundingBox);
+
+    await plugin.runTask(Task.create('Export Geometry', async ctx => {
+        for (let i = 0, il = meshes.length; i < il; ++i) {
+            await renderObjectExporter.add(meshes[i], plugin.canvas3d?.webgl!, ctx);
+        }
+
+        const blob = await renderObjectExporter.getBlob(ctx);
+        const buffer = await blob.arrayBuffer();
+        await fs.promises.writeFile(path.join(args.outDirectory, `${args.cid}.glb`), Buffer.from(buffer));
+    }));
+
+    // Cleanup
+    await plugin.clear();
+    plugin.dispose();
+}
+
+main();

src/examples/lighting/index.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2019-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2019-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -33,8 +33,10 @@ const Canvas3DPresets = {
                         radius: 5,
                         bias: 0.8,
                         blurKernelSize: 15,
+                        blurDepthBias: 0.5,
                         resolutionScale: 1,
                         color: Color(0x000000),
+                        transparentThreshold: 0.4,
                     }
                 },
                 outline: {

src/extensions/alpha-orbitals/transforms.ts

@@ -182,7 +182,7 @@ export const CreateOrbitalRepresentation3D = PluginStateTransform.BuiltIn({
         return Task.create('Orbitals Representation 3D', async ctx => {
             const params = volumeParams(plugin, a, srcParams);
 
-            const propertyCtx = { runtime: ctx, assetManager: plugin.managers.asset };
+            const propertyCtx = { runtime: ctx, assetManager: plugin.managers.asset, errorContext: plugin.errorContext };
             const provider = plugin.representation.volume.registry.get(params.type.name);
             if (provider.ensureCustomProperties) await provider.ensureCustomProperties.attach(propertyCtx, a.data);
             const props = params.type.params || {};

src/extensions/anvil/behavior.ts

@@ -118,7 +118,7 @@ const MembraneOrientation3D = PluginStateTransform.BuiltIn({
     },
     apply({ a, params }, plugin: PluginContext) {
         return Task.create('Membrane Orientation', async ctx => {
-            await MembraneOrientationProvider.attach({ runtime: ctx, assetManager: plugin.managers.asset }, a.data);
+            await MembraneOrientationProvider.attach({ runtime: ctx, assetManager: plugin.managers.asset, errorContext: plugin.errorContext }, a.data);
             const repr = MembraneOrientationRepresentation({ webgl: plugin.canvas3d?.webgl, ...plugin.representation.structure.themes }, () => MembraneOrientationParams);
             await repr.createOrUpdate(params, a.data).runInContext(ctx);
             return new PluginStateObject.Shape.Representation3D({ repr, sourceData: a.data }, { label: 'Membrane Orientation' });
@@ -126,7 +126,7 @@ const MembraneOrientation3D = PluginStateTransform.BuiltIn({
     },
     update({ a, b, newParams }, plugin: PluginContext) {
         return Task.create('Membrane Orientation', async ctx => {
-            await MembraneOrientationProvider.attach({ runtime: ctx, assetManager: plugin.managers.asset }, a.data);
+            await MembraneOrientationProvider.attach({ runtime: ctx, assetManager: plugin.managers.asset, errorContext: plugin.errorContext }, a.data);
             const props = { ...b.data.repr.props, ...newParams };
             await b.data.repr.createOrUpdate(props, a.data).runInContext(ctx);
             b.data.sourceData = a.data;
@@ -155,7 +155,7 @@ export const MembraneOrientationPreset = StructureRepresentationPresetProvider({
 
         if (!MembraneOrientationProvider.get(structure).value) {
             await plugin.runTask(Task.create('Membrane Orientation', async runtime => {
-                await MembraneOrientationProvider.attach({ runtime, assetManager: plugin.managers.asset }, structure);
+                await MembraneOrientationProvider.attach({ runtime, assetManager: plugin.managers.asset, errorContext: plugin.errorContext }, structure);
             }));
         }
 

src/extensions/anvil/prop.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2020 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2020-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Sebastian Bittrich <sebastian.bittrich@rcsb.org>
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
@@ -67,13 +67,33 @@ export const MembraneOrientationProvider: CustomStructureProperty.Provider<Membr
     type: 'root',
     defaultParams: MembraneOrientationParams,
     getParams: (data: Structure) => MembraneOrientationParams,
-    isApplicable: (data: Structure) => true,
+    isApplicable,
     obtain: async (ctx: CustomProperty.Context, data: Structure, props: Partial<MembraneOrientationProps>) => {
         const p = { ...PD.getDefaultValues(MembraneOrientationParams), ...props };
-        return { value: await computeAnvil(ctx, data, p) };
+        try {
+            return { value: await computeAnvil(ctx, data, p) };
+        } catch (e) {
+            // the "Residues Embedded in Membrane" symbol may bypass isApplicable() checks
+            console.warn('Failed to predict membrane orientation. This happens for short peptides and entries without amino acids.');
+            return { value: undefined };
+        }
     }
 });
 
+function isApplicable(structure: Structure) {
+    if (!structure.isAtomic) return false;
+
+    for (const model of structure.models) {
+        const { byEntityKey } = model.sequence;
+        for (const key of Object.keys(byEntityKey)) {
+            const { kind, length } = byEntityKey[+key].sequence;
+            if (kind !== 'protein') continue; // can only process protein chains
+            if (length >= 15) return true; // short peptides might fail
+        }
+    }
+    return false;
+}
+
 async function computeAnvil(ctx: CustomProperty.Context, data: Structure, props: Partial<ANVILProps>): Promise<MembraneOrientation> {
     const p = { ...PD.getDefaultValues(ANVILParams), ...props };
     return await computeANVIL(data, p).runInContext(ctx.runtime);

src/extensions/anvil/representation.ts

@@ -81,7 +81,7 @@ export const MembraneOrientationRepresentationProvider = StructureRepresentation
     defaultValues: PD.getDefaultValues(MembraneOrientationParams),
     defaultColorTheme: { name: 'shape-group' },
     defaultSizeTheme: { name: 'shape-group' },
-    isApplicable: (structure: Structure) => structure.elementCount > 0,
+    isApplicable(structure: Structure) { return MembraneOrientationProvider.isApplicable(structure); },
     ensureCustomProperties: {
         attach: (ctx: CustomProperty.Context, structure: Structure) => MembraneOrientationProvider.attach(ctx, structure, void 0, true),
         detach: (data) => MembraneOrientationProvider.ref(data, false)

src/extensions/assembly-symmetry/behavior.ts

@@ -82,7 +82,7 @@ export const InitAssemblySymmetry3D = StateAction.build({
     params: (a, plugin: PluginContext) => getConfiguredDefaultParams(plugin)
 })(({ a, ref, state, params }, plugin: PluginContext) => Task.create('Init Assembly Symmetry', async ctx => {
     try {
-        const propCtx = { runtime: ctx, assetManager: plugin.managers.asset };
+        const propCtx = { runtime: ctx, assetManager: plugin.managers.asset, errorContext: plugin.errorContext };
         await AssemblySymmetryDataProvider.attach(propCtx, a.data, params);
         const assemblySymmetryData = AssemblySymmetryDataProvider.get(a.data).value;
         const symmetryIndex = assemblySymmetryData ? AssemblySymmetryData.firstNonC1(assemblySymmetryData) : -1;
@@ -118,7 +118,7 @@ const AssemblySymmetry3D = PluginStateTransform.BuiltIn({
     },
     apply({ a, params }, plugin: PluginContext) {
         return Task.create('Assembly Symmetry', async ctx => {
-            await AssemblySymmetryProvider.attach({ runtime: ctx, assetManager: plugin.managers.asset }, a.data);
+            await AssemblySymmetryProvider.attach({ runtime: ctx, assetManager: plugin.managers.asset, errorContext: plugin.errorContext }, a.data);
             const assemblySymmetry = AssemblySymmetryProvider.get(a.data).value;
             if (!assemblySymmetry || assemblySymmetry.symbol === 'C1') {
                 return StateObject.Null;
@@ -131,7 +131,7 @@ const AssemblySymmetry3D = PluginStateTransform.BuiltIn({
     },
     update({ a, b, newParams }, plugin: PluginContext) {
         return Task.create('Assembly Symmetry', async ctx => {
-            await AssemblySymmetryProvider.attach({ runtime: ctx, assetManager: plugin.managers.asset }, a.data);
+            await AssemblySymmetryProvider.attach({ runtime: ctx, assetManager: plugin.managers.asset, errorContext: plugin.errorContext }, a.data);
             const assemblySymmetry = AssemblySymmetryProvider.get(a.data).value;
             if (!assemblySymmetry || assemblySymmetry.symbol === 'C1') {
                 // this should NOT be StateTransformer.UpdateResult.Null
@@ -176,7 +176,7 @@ export const AssemblySymmetryPreset = StructureRepresentationPresetProvider({
 
         if (!AssemblySymmetryDataProvider.get(structure).value) {
             await plugin.runTask(Task.create('Assembly Symmetry', async runtime => {
-                const propCtx = { runtime, assetManager: plugin.managers.asset };
+                const propCtx = { runtime, assetManager: plugin.managers.asset, errorContext: plugin.errorContext };
                 const propProps = { serverType: params.serverType, serverUrl: params.serverUrl };
                 await AssemblySymmetryDataProvider.attach(propCtx, structure, propProps);
                 const assemblySymmetryData = AssemblySymmetryDataProvider.get(structure).value;

src/extensions/backgrounds/index.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2022-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2022-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -80,6 +80,7 @@ export const Backgrounds = PluginBehavior.create<{ }>({
                             saturation: 0,
                             opacity: 1,
                             blur: 0.3,
+                            rotation: { x: 0, y: 0, z: 0 },
                         }
                     }
                 }, 'Purple Nebula Skybox'],

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

@@ -30,7 +30,7 @@ export const ConfalPyramidsPreset = StructureRepresentationPresetProvider({
         if (!structureCell || !model) return {};
 
         await plugin.runTask(Task.create('Confal Pyramids', async runtime => {
-            await ConfalPyramidsProvider.attach({ runtime, assetManager: plugin.managers.asset }, model);
+            await ConfalPyramidsProvider.attach({ runtime, assetManager: plugin.managers.asset, errorContext: plugin.errorContext }, model);
         }));
 
         const { components, representations } = await PresetStructureRepresentations.auto.apply(ref, { ...params }, plugin);

src/extensions/dnatco/ntc-tube/behavior.ts

@@ -30,7 +30,7 @@ export const NtCTubePreset = StructureRepresentationPresetProvider({
         if (!structureCell || !model) return {};
 
         await plugin.runTask(Task.create('NtC tube', async runtime => {
-            await NtCTubeProvider.attach({ runtime, assetManager: plugin.managers.asset }, model);
+            await NtCTubeProvider.attach({ runtime, assetManager: plugin.managers.asset, errorContext: plugin.errorContext }, model);
         }));
 
         const { components, representations } = await PresetStructureRepresentations.auto.apply(ref, { ...params }, plugin);

src/extensions/geo-export/glb-exporter.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2021-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2021-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Sukolsak Sakshuwong <sukolsak@stanford.edu>
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
@@ -170,8 +170,8 @@ export class GlbExporter extends MeshExporter<GlbData> {
         return this.addBuffer(colorBuffer, UNSIGNED_BYTE, 'VEC4', vertexCount, ARRAY_BUFFER, undefined, undefined, true);
     }
 
-    private addMaterial(metalness: number, roughness: number, doubleSided: boolean, alpha: boolean) {
-        const hash = `${metalness}|${roughness}|${doubleSided}`;
+    private addMaterial(metalness: number, roughness: number, emissive: number, doubleSided: boolean, alpha: boolean) {
+        const hash = `${metalness}|${roughness}|${emissive}|${doubleSided}`;
         if (!this.materialMap.has(hash)) {
             this.materialMap.set(hash, this.materials.length);
             this.materials.push({
@@ -180,6 +180,7 @@ export class GlbExporter extends MeshExporter<GlbData> {
                     metallicFactor: metalness,
                     roughnessFactor: roughness
                 },
+                emissiveFactor: [emissive, emissive, emissive],
                 doubleSided,
                 alphaMode: alpha ? 'BLEND' : 'OPAQUE',
             });
@@ -200,10 +201,11 @@ export class GlbExporter extends MeshExporter<GlbData> {
         const instanceCount = values.uInstanceCount.ref.value;
         const metalness = values.uMetalness.ref.value;
         const roughness = values.uRoughness.ref.value;
+        const emissive = values.uEmissive.ref.value;
         const doubleSided = values.uDoubleSided?.ref.value || values.hasReflection.ref.value;
         const alpha = values.uAlpha.ref.value < 1;
 
-        const material = this.addMaterial(metalness, roughness, doubleSided, alpha);
+        const material = this.addMaterial(metalness, roughness, emissive, doubleSided, alpha);
 
         let interpolatedColors: Uint8Array | undefined;
         if (webgl && mesh && (colorType === 'volume' || colorType === 'volumeInstance')) {

src/extensions/meshes/mesh-extension.ts

@@ -164,7 +164,7 @@ const meshShapeProviderParams: Mesh.Params = {
     quality: PD.Select<VisualQuality>('custom', VisualQualityOptions, { isEssential: true, description: 'Visual/rendering quality of the representation.' }), // use 'custom' when wanting to apply doubleSided
     doubleSided: PD.Boolean(true, BaseGeometry.CustomQualityParamInfo),
     // set `flatShaded`: true to see the real mesh vertices and triangles
-    transparentBackfaces: PD.Select('on', PD.arrayToOptions(['off', 'on', 'opaque']), BaseGeometry.ShadingCategory), // 'on' means: show backfaces with correct opacity, even when opacity < 1 (requires doubleSided) ¯\_(ツ)_/¯
+    transparentBackfaces: PD.Select('on', PD.arrayToOptions(['off', 'on', 'opaque'] as const), BaseGeometry.ShadingCategory), // 'on' means: show backfaces with correct opacity, even when opacity < 1 (requires doubleSided) ¯\_(ツ)_/¯
 };
 
 

src/extensions/model-archive/quality-assessment/behavior.ts

@@ -1,7 +1,8 @@
 /**
- * Copyright (c) 2021 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2021-24 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ * @author David Sehnal <david.sehnal@gmail.com>
  */
 
 import { ParamDefinition as PD } from '../../../mol-util/param-definition';
@@ -17,6 +18,12 @@ import { cantorPairing } from '../../../mol-data/util';
 import { QmeanScoreColorThemeProvider } from './color/qmean';
 import { PresetStructureRepresentations, StructureRepresentationPresetProvider } from '../../../mol-plugin-state/builder/structure/representation-preset';
 import { StateObjectRef } from '../../../mol-state';
+import { MAPairwiseScorePlotPanel } from './pairwise/ui';
+import { PluginConfigItem } from '../../../mol-plugin/config';
+
+export const MAQualityAssessmentConfig = {
+    EnablePairwiseScorePlot: new PluginConfigItem('ma-quality-assessment-prop.enable-pairwise-score-plot', true),
+};
 
 export const MAQualityAssessment = PluginBehavior.create<{ autoAttach: boolean, showTooltip: boolean }>({
     name: 'ma-quality-assessment-prop',
@@ -52,6 +59,10 @@ export const MAQualityAssessment = PluginBehavior.create<{ autoAttach: boolean,
 
             this.ctx.builders.structure.representation.registerPreset(QualityAssessmentPLDDTPreset);
             this.ctx.builders.structure.representation.registerPreset(QualityAssessmentQmeanPreset);
+
+            if (this.ctx.config.get(MAQualityAssessmentConfig.EnablePairwiseScorePlot)) {
+                this.ctx.customStructureControls.set('ma-quality-assessment-pairwise-plot', MAPairwiseScorePlotPanel as any);
+            }
         }
 
         update(p: { autoAttach: boolean, showTooltip: boolean }) {
@@ -76,6 +87,8 @@ export const MAQualityAssessment = PluginBehavior.create<{ autoAttach: boolean,
 
             this.ctx.builders.structure.representation.unregisterPreset(QualityAssessmentPLDDTPreset);
             this.ctx.builders.structure.representation.unregisterPreset(QualityAssessmentQmeanPreset);
+
+            this.ctx.customStructureControls.delete('ma-quality-assessment-pairwise-plot');
         }
     },
     params: () => ({

src/extensions/model-archive/quality-assessment/color/plddt.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2021 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2021-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Mandar Deshpande <mandar@ebi.ac.uk>
  * @author Sebastian Bittrich <sebastian.bittrich@rcsb.org>
@@ -8,7 +8,7 @@
 
 import { QualityAssessment, QualityAssessmentProvider } from '../prop';
 import { Location } from '../../../../mol-model/location';
-import { Bond, StructureElement, Unit } from '../../../../mol-model/structure';
+import { Bond, Model, StructureElement, Unit } from '../../../../mol-model/structure';
 import { ColorTheme, LocationColor } from '../../../../mol-theme/color';
 import { ThemeDataContext } from '../../../../mol-theme/theme';
 import { Color } from '../../../../mol-util/color';
@@ -41,8 +41,13 @@ export function PLDDTConfidenceColorTheme(ctx: ThemeDataContext, props: PD.Value
         const getColor = (location: StructureElement.Location): Color => {
             const { unit, element } = location;
             if (!Unit.isAtomic(unit)) return DefaultColor;
+
             const qualityAssessment = QualityAssessmentProvider.get(unit.model).value;
-            const score = qualityAssessment?.pLDDT?.get(unit.model.atomicHierarchy.residueAtomSegments.index[element]) ?? -1;
+            let score = qualityAssessment?.pLDDT?.get(unit.model.atomicHierarchy.residueAtomSegments.index[element]);
+            if (typeof score !== 'number') {
+                score = unit.model.atomicConformation.B_iso_or_equiv.value(element);
+            }
+
             if (score < 0) {
                 return DefaultColor;
             } else if (score <= 50) {
@@ -74,7 +79,7 @@ export function PLDDTConfidenceColorTheme(ctx: ThemeDataContext, props: PD.Value
         preferSmoothing: true,
         color,
         props,
-        description: 'Assigns residue colors according to the pLDDT Confidence score.',
+        description: 'Assigns residue colors according to the pLDDT Confidence score. If no Model Archive quality assessment score is available, the B-factor value is used instead.',
         legend: ConfidenceColorLegend
     };
 }
@@ -86,7 +91,7 @@ export const PLDDTConfidenceColorThemeProvider: ColorTheme.Provider<PLDDTConfide
     factory: PLDDTConfidenceColorTheme,
     getParams: getPLDDTConfidenceColorThemeParams,
     defaultValues: PD.getDefaultValues(getPLDDTConfidenceColorThemeParams({})),
-    isApplicable: (ctx: ThemeDataContext) => !!ctx.structure?.models.some(m => QualityAssessment.isApplicable(m, 'pLDDT')),
+    isApplicable: (ctx: ThemeDataContext) => !!ctx.structure?.models.some(m => QualityAssessment.isApplicable(m, 'pLDDT') || (m.atomicConformation.B_iso_or_equiv.isDefined && !Model.isExperimental(m))),
     ensureCustomProperties: {
         attach: async (ctx: CustomProperty.Context, data: ThemeDataContext) => {
             if (data.structure) {

src/extensions/model-archive/quality-assessment/pairwise/plot.ts

@@ -0,0 +1,83 @@
+/**
+ * Copyright (c) 2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import { Model, ResidueIndex } from '../../../../mol-model/structure';
+import { AtomicHierarchy } from '../../../../mol-model/structure/model/properties/atomic';
+import { Color } from '../../../../mol-util/color';
+import { QualityAssessment } from '../prop';
+
+
+const DefaultMetricColorRange = [0x00441B, 0xF7FCF5] as [Color, Color];
+
+export type MAResidueRangeInfo = { startOffset: number, endOffset: number, label: string };
+
+function drawMetricPNG(model: Model, metric: QualityAssessment.Pairwise, colorRange: [Color, Color], noDataColor: Color) {
+    const [minResidueIndex, maxResidueIndex] = metric.residueRange;
+    const [minMetric, maxMetric] = metric.valueRange;
+    const [minColor, maxColor] = colorRange;
+    const range = maxResidueIndex - minResidueIndex + 1;
+    const valueRange = maxMetric - minMetric;
+    const values = metric.values;
+
+    const canvas = document.createElement('canvas');
+    canvas.width = range;
+    canvas.height = range;
+    const ctx = canvas.getContext('2d')!;
+    ctx.fillStyle = Color.toStyle(noDataColor);
+    ctx.fillRect(0, 0, canvas.width, canvas.height);
+
+    for (let rA = minResidueIndex; rA <= maxResidueIndex; rA++) {
+        const row = values[rA];
+        if (!row) continue;
+
+        for (let rB = minResidueIndex; rB <= maxResidueIndex; rB++) {
+            const value = row[rB];
+            if (typeof value !== 'number') continue;
+
+            const x = rA - minResidueIndex;
+            const y = rB - minResidueIndex;
+            const t = (value - minMetric) / valueRange;
+
+            const color = Color.interpolate(minColor, maxColor, t);
+            ctx.fillStyle = Color.toStyle(color);
+            ctx.fillRect(x, y, 1, 1);
+            ctx.fillRect(y, x, 1, 1);
+        }
+    }
+
+    const chains: MAResidueRangeInfo[] = [];
+    const hierarchy = model.atomicHierarchy;
+    const { label_asym_id } = hierarchy.chains;
+
+    let cI = AtomicHierarchy.residueChainIndex(hierarchy, minResidueIndex as ResidueIndex);
+    let currentChain: MAResidueRangeInfo = { startOffset: 0, endOffset: 1, label: label_asym_id.value(cI) };
+    chains.push(currentChain);
+
+    for (let i = 1; i < range; i++) {
+        cI = AtomicHierarchy.residueChainIndex(hierarchy, (minResidueIndex + i) as ResidueIndex);
+        const asym_id = label_asym_id.value(cI);
+        if (asym_id === currentChain.label) {
+            currentChain.endOffset = i + 1;
+        } else {
+            currentChain = { startOffset: i, endOffset: i + 1, label: asym_id };
+            chains.push(currentChain);
+        }
+    }
+
+    return {
+        model,
+        metric,
+        chains,
+        colorRange: [Color.toStyle(colorRange[0]), Color.toStyle(colorRange[1])] as const,
+        png: canvas.toDataURL('png')
+    };
+}
+
+export function maDrawPairwiseMetricPNG(model: Model, metric: QualityAssessment.Pairwise) {
+    return drawMetricPNG(model, metric, DefaultMetricColorRange, Color(0xE2E2E2));
+}
+
+export type MAPairwiseMetricDrawing = ReturnType<typeof drawMetricPNG>

src/extensions/model-archive/quality-assessment/pairwise/ui.tsx

@@ -0,0 +1,504 @@
+/**
+ * Copyright (c) 2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import { CSSProperties, Fragment, memo, ReactNode, useEffect, useRef } from 'react';
+import { BehaviorSubject, combineLatest, distinctUntilChanged, throttleTime } from 'rxjs';
+import { clamp } from '../../../../mol-math/interpolate';
+import { Model, ResidueIndex, StructureElement, StructureProperties, StructureQuery } from '../../../../mol-model/structure';
+import { AtomicHierarchy } from '../../../../mol-model/structure/model/properties/atomic';
+import { atoms } from '../../../../mol-model/structure/query/queries/generators';
+import { PluginStateObject } from '../../../../mol-plugin-state/objects';
+import { OverpaintStructureRepresentation3DFromBundle } from '../../../../mol-plugin-state/transforms/representation';
+import { CollapsableControls, CollapsableState } from '../../../../mol-plugin-ui/base';
+import { ScatterPlotSvg } from '../../../../mol-plugin-ui/controls/icons';
+import { ParameterControls } from '../../../../mol-plugin-ui/controls/parameters';
+import { useBehavior } from '../../../../mol-plugin-ui/hooks/use-behavior';
+import { PluginContext } from '../../../../mol-plugin/context';
+import { StateBuilder, StateTransform } from '../../../../mol-state';
+import { round } from '../../../../mol-util';
+import { Color } from '../../../../mol-util/color';
+import { ParamDefinition as PD } from '../../../../mol-util/param-definition';
+import { SingleAsyncQueue } from '../../../../mol-util/single-async-queue';
+import { QualityAssessment } from '../prop';
+import { maDrawPairwiseMetricPNG, MAPairwiseMetricDrawing } from './plot';
+
+type State = ReturnType<typeof getPropsAndValues>
+
+export class MAPairwiseScorePlotPanel extends CollapsableControls<{}, State> {
+    protected defaultState(): State & CollapsableState {
+        return {
+            header: 'Predicted Aligned Error',
+            isCollapsed: false,
+            isHidden: true,
+            brand: { accent: 'purple', svg: ScatterPlotSvg },
+            params: {} as any,
+            values: undefined as any,
+            dataSources: [],
+        };
+    }
+
+    toggleCollapsed() {
+        if (!this.state.isCollapsed) {
+            this.setState({ isCollapsed: true });
+        } else {
+            const state = getPropsAndValues(this.plugin, this.state.values);
+            this.setState({
+                ...state,
+                isCollapsed: false,
+                isHidden: state.params.data.options.length === 0 || state.params.model.options.length === 0
+            });
+        }
+    };
+
+    interactivity = new BehaviorSubject<PlotInteractivityState>({});
+    queue = new SingleAsyncQueue();
+
+    componentDidMount() {
+        this.subscribe(combineLatest([
+            this.plugin.state.data.events.changed,
+            this.plugin.behaviors.state.isAnimating
+        ]), ([_, anim]) => {
+            if (anim || this.state.isCollapsed) return;
+            const state = getPropsAndValues(this.plugin, this.state.values);
+            this.setState({
+                ...state,
+                isHidden: state.params.data.options.length === 0 || state.params.model.options.length === 0
+            });
+        });
+
+        this.subscribe(filterHighlightState(this.interactivity), state => {
+            highlightState(this.plugin, state);
+        });
+        this.subscribe(filterOverpaintState(this.interactivity), state => {
+            this.queue.enqueue(() => overpaintState(this.plugin, state));
+        });
+    }
+
+    protected renderControls(): JSX.Element | null {
+        const { params, values, dataSources } = this.state;
+        return <>
+            <ParameterControls params={params} values={values} onChangeValues={values => this.setState({ values })} />
+            <PlotWrapper plugin={this.plugin} values={values} dataSources={dataSources} interactivity={this.interactivity} />
+        </>;
+    }
+}
+
+export function MAPairwiseScorePlot({ plugin, model, pairwiseMetric }: { plugin: PluginContext, model: Model, pairwiseMetric: QualityAssessment.Pairwise }) {
+    const _interactivity = useRef<BehaviorSubject<PlotInteractivityState>>();
+    const interactivity = _interactivity.current ??= new BehaviorSubject<PlotInteractivityState>({});
+
+    useEffect(() => {
+        const queue = new SingleAsyncQueue();
+
+        const highlight = filterHighlightState(interactivity).subscribe(state => highlightState(plugin, state));
+        const paint = filterOverpaintState(interactivity).subscribe(state => queue.enqueue(() => overpaintState(plugin, state)));
+
+        return () => {
+            highlight.unsubscribe();
+            paint.unsubscribe();
+            queue.enqueue(() => overpaintState(plugin, interactivity.value));
+        };
+    }, [model, pairwiseMetric]);
+
+    return <MAPairwiseScorePlotBase model={model} pairwiseMetric={pairwiseMetric} interactivity={interactivity} />;
+}
+
+function filterHighlightState(state: BehaviorSubject<PlotInteractivityState>) {
+    return state.pipe(
+        throttleTime(16, undefined, { leading: true, trailing: true }),
+        distinctUntilChanged((a, b) => a.crosshairOffset === b.crosshairOffset)
+    );
+}
+
+function filterOverpaintState(state: BehaviorSubject<PlotInteractivityState>) {
+    return state.pipe(
+        throttleTime(66, undefined, { leading: true, trailing: true }),
+        distinctUntilChanged((a, b) => a.boxStart === b.boxStart && (a.mouseDown ? a.crosshairOffset : a.boxEnd) === (b.mouseDown ? b.crosshairOffset : b.boxEnd))
+    );
+}
+
+const PlotWrapper = memo(({ plugin, values, dataSources, interactivity }: { plugin: PluginContext, values: State['values'], dataSources: State['dataSources'], interactivity: BehaviorSubject<PlotInteractivityState> }) => {
+    const model: Model | undefined = plugin.managers.structure.hierarchy.current.models.find(m => m.cell.transform.ref === values.model)?.cell.obj?.data;
+    const src = dataSources.find(src => src.id === values.data);
+    const cif: PluginStateObject.Format.Cif | undefined = plugin.state.data.cells.get(src?.dataRef!)?.obj;
+    const block = cif?.data.blocks[src?.blockIndex!];
+
+    if (!model || !block || !src) return <div className='msp-description'>Data not available</div>;
+
+    const metric = QualityAssessment.pairwiseMetricFromModelArchiveCIF(model, block, src.metridId);
+    if (!metric) return <div className='msp-description'>Data not available</div>;
+
+    return <MAPairwiseScorePlotBase interactivity={interactivity} model={model} pairwiseMetric={metric} />;
+}, (prev, next) => prev.values.data === next.values.data && prev.values.model === next.values.model);
+
+function getPropsAndValues(plugin: PluginContext, current?: { model?: string, data?: string }) {
+    const models = plugin.managers.structure.hierarchy.current.models;
+    const cifs = plugin.state.data.selectQ(q => q.root.subtree().ofType(PluginStateObject.Format.Cif));
+
+    const dataSources: {
+        id: string,
+        label: string,
+        metridId: number,
+        dataRef: StateTransform.Ref,
+        blockIndex: number,
+    }[] = [];
+
+    for (const cif of cifs) {
+        if (!cif.obj?.data.blocks) continue;
+        let blockIndex = 0;
+        for (const block of cif.obj.data.blocks) {
+            for (const pae of QualityAssessment.findModelArchiveCIFPAEMetrics(block)) {
+                dataSources.push({
+                    id: `${cif.transform.ref}:${blockIndex}:${pae.id}`,
+                    metridId: pae.id,
+                    label: `${block.header}: ${pae.name}`,
+                    dataRef: cif.transform.ref,
+                    blockIndex,
+                });
+            }
+            blockIndex++;
+        }
+    }
+
+    const params = {
+        model: PD.Select(models[0]?.cell.transform.ref, models.map(m => [m.cell.transform.ref, m.cell.obj?.data.label!]), { isHidden: models.length <= 1 }),
+        data: PD.Select(dataSources[0]?.id, dataSources.map(o => [o.id, o.label]), { isHidden: dataSources.length <= 1 })
+    };
+
+    const values = {
+        model: params.model.options.find(o => o[0] === current?.model)?.[0] ?? params.model.options[0]?.[0],
+        data: params.data.options.find(o => o[0] === current?.data)?.[0] ?? params.data.options[0]?.[0],
+    };
+
+    return { params, values, dataSources };
+}
+
+const PlotSize = 1000;
+const PlotOffset = 120;
+
+const PlotColors = {
+    ScoredOverpaint: Color(0xFFA500),
+    ScoredLabel: Color(0xBC7100),
+    AlignedOverpaint: Color(0x1AFFBB),
+    AlignedLabel: Color(0x0F8E68),
+};
+
+interface PlotInteractivityState {
+    model?: Model;
+    drawing?: MAPairwiseMetricDrawing;
+    crosshairOffset?: [number, number];
+    inside?: boolean;
+    mouseDown?: boolean;
+    boxStart?: [number, number];
+    boxEnd?: [number, number];
+}
+
+export const MAPairwiseScorePlotBase = memo(({ model, pairwiseMetric, interactivity }: { model: Model, pairwiseMetric: QualityAssessment.Pairwise, interactivity: BehaviorSubject<PlotInteractivityState> }) => {
+    const interactivityRect = useRef<SVGRectElement>();
+    const drawing = maDrawPairwiseMetricPNG(model, pairwiseMetric);
+
+    useEffect(() => {
+        if (!drawing) {
+            interactivity.next({});
+            return;
+        }
+        interactivity.next({ model, drawing });
+        const moveEvent = (ev: MouseEvent) => {
+            const current = interactivity.value;
+            if (!current.inside && !current.mouseDown) return;
+
+            const offset = getPlotMouseOffsetBase(interactivityRect.current!, ev.clientX, ev.clientY);
+            interactivity.next({ ...current, crosshairOffset: offset });
+        };
+        const mouseUpEvent = (ev: MouseEvent) => {
+            if (!interactivity.value.mouseDown) return;
+            const offset = getPlotMouseOffsetBase(interactivityRect.current!, ev.clientX, ev.clientY);
+            interactivity.next({ ...interactivity.value, mouseDown: false, boxEnd: offset });
+        };
+        window.addEventListener('mousemove', moveEvent);
+        window.addEventListener('mouseup', mouseUpEvent);
+        return () => {
+            window.removeEventListener('mousemove', moveEvent);
+            window.removeEventListener('mouseup', mouseUpEvent);
+        };
+    }, [model, interactivity, drawing]);
+
+    if (!drawing) return <>Not available</>;
+
+
+    const { metric, colorRange, chains, png } = drawing;
+    const nResidues = metric.residueRange[1] - metric.residueRange[0];
+
+    const border = '#333';
+    const line = '#000';
+
+    const legendHeight = 80;
+    const legendOffsetY = PlotOffset + PlotSize + 50;
+
+    const viewBox = '0 0 1140 1270';
+
+    return <div style={{ margin: '8px 8px 0 8px', position: 'relative' }}>
+        <svg viewBox={viewBox} width='100%'>
+            <image x={PlotOffset + 1} y={PlotOffset + 1} width={PlotSize - 1} height={PlotSize - 1} href={png} />
+            <line x1={PlotOffset} x2={PlotOffset + PlotSize} y1={PlotOffset} y2={PlotOffset + PlotSize} style={{ stroke: line, strokeDasharray: '15,15' }} />
+            <linearGradient id='legend-gradient' x1={0} x2={1} y1={0} y2={0}>
+                <stop offset='0%' stopColor={colorRange[0]} />
+                <stop offset='100%' stopColor={colorRange[1]} />
+            </linearGradient>
+            <rect x={PlotOffset} y={legendOffsetY} width={PlotSize} height={legendHeight} style={{ fill: 'url(#legend-gradient)', strokeWidth: 1, stroke: border }} />
+            <text x={PlotOffset + 20} y={legendOffsetY + legendHeight - 22} style={{ fontSize: '45px', fill: 'white', fontWeight: 'bold' }}>{round(metric.valueRange[0], 2)} Å</text>
+            <text x={PlotOffset + PlotSize - 20} y={legendOffsetY + legendHeight - 22} style={{ fontSize: '45px', fill: 'black', fontWeight: 'bold' }} textAnchor='end'>{round(metric.valueRange[1], 2)} Å</text>
+            <text x={PlotOffset + PlotSize / 2} y={legendOffsetY + legendHeight - 22} style={{ fontSize: '45px', fill: 'black' }} textAnchor='middle'>Predicted Aligned Error</text>
+
+            <text x={PlotOffset + PlotSize / 2} y={50} style={{ fontSize: '45px', fontWeight: 'bold', fill: Color.toStyle(PlotColors.ScoredLabel) }} textAnchor='middle'>Scored Residue</text>
+            <text className='msp-svg-text' style={{ fontSize: '50px', fontWeight: 'bold', fill: Color.toStyle(PlotColors.AlignedLabel) }} transform={`translate(50, ${PlotOffset + PlotSize / 2}) rotate(270)`} textAnchor='middle'>Aligned Residue</text>
+
+            {chains.map(({ startOffset, endOffset, label }) => {
+                const textOffset = PlotOffset + PlotSize * (startOffset + (endOffset - startOffset) / 2) / nResidues;
+                const endLineOffset = PlotOffset + PlotSize * endOffset / nResidues;
+                const startLineOffset = PlotOffset + PlotSize * startOffset / nResidues;
+
+                const seq_id = model.atomicHierarchy.residues.label_seq_id;
+                const startIndex = seq_id.value(metric.residueRange[0] + startOffset);
+                const endIndex = seq_id.value(metric.residueRange[0] + endOffset - 1);
+
+                return <Fragment key={startOffset}>
+                    <text x={textOffset} y={PlotOffset - 15} className='msp-svg-text' style={{ fontSize: '40px' }} textAnchor='middle'>{label} {startIndex}-{endIndex}</text>
+                    <text className='msp-svg-text' style={{ fontSize: '40px' }} transform={`translate(${PlotOffset - 15}, ${textOffset}) rotate(270)`} textAnchor='middle'>{label} {startIndex}-{endIndex}</text>
+                    <line x1={startLineOffset} x2={startLineOffset} y1={PlotOffset - 20} y2={PlotOffset + PlotSize + 20} style={{ stroke: line, strokeDasharray: '15,15' }} />
+                    <line x1={endLineOffset} x2={endLineOffset} y1={PlotOffset - 20} y2={PlotOffset + PlotSize + 20} style={{ stroke: line, strokeDasharray: '15,15' }} />
+                    <line x1={PlotOffset - 20} x2={PlotOffset + PlotSize + 20} y1={startLineOffset} y2={startLineOffset} style={{ stroke: line, strokeDasharray: '15,15' }} />
+                    <line x1={PlotOffset - 20} x2={PlotOffset + PlotSize + 20} y1={endLineOffset} y2={endLineOffset} style={{ stroke: line, strokeDasharray: '15,15' }} />
+                </Fragment>;
+            })}
+        </svg>
+        <svg viewBox={viewBox} style={{ position: 'absolute', inset: 0 }}>
+            <rect x={PlotOffset} y={PlotOffset} width={PlotSize} height={PlotSize} style={{ fill: 'transparent', cursor: 'crosshair' }}
+                ref={interactivityRect as any}
+                onMouseMove={(ev) => {
+                    interactivity.next({ ...interactivity.value, inside: true });
+                    ev.currentTarget.style.stroke = 'black';
+                    ev.currentTarget.style.strokeWidth = '4px';
+                }}
+                onMouseDown={(ev) => {
+                    interactivity.next({ ...interactivity.value, mouseDown: true, boxStart: getPlotMouseOffset(ev) });
+                }}
+                onMouseLeave={(ev) => {
+                    interactivity.next({ ...interactivity.value, inside: false, crosshairOffset: undefined });
+                    ev.currentTarget.style.stroke = '#333';
+                    ev.currentTarget.style.strokeWidth = '1px';
+                }} />
+            <PlotInteractivity drawing={drawing} interactity={interactivity} />
+        </svg>
+    </div>;
+}, (prev, next) => prev.model === next.model && prev.pairwiseMetric === next.pairwiseMetric);
+
+function PlotInteractivity({ drawing, interactity }: { drawing: MAPairwiseMetricDrawing, interactity: BehaviorSubject<PlotInteractivityState> }) {
+    const state = useBehavior(interactity);
+    const { crosshairOffset, inside } = state;
+    const box = getBox(state);
+    const label = getCrosshairLabel(state);
+
+    let labelNode: ReactNode | undefined;
+    if (label) {
+        const labelStyle: CSSProperties | undefined = label ? { fontSize: '45px', fill: 'black', fontWeight: 'bold', pointerEvents: 'none', userSelect: 'none' } : undefined;
+        let x: number, y: number, anchor: string;
+        if (crosshairOffset![0] < PlotSize / 2) {
+            x = PlotOffset + crosshairOffset![0] + 20;
+            anchor = 'start';
+        } else {
+            x = PlotOffset + crosshairOffset![0] - 20;
+            anchor = 'end';
+        }
+
+        if (crosshairOffset![1] < PlotSize / 2) {
+            y = PlotOffset + crosshairOffset![1] + 65;
+        } else {
+            y = PlotOffset + crosshairOffset![1] - (label[2] ? 3 * 45 : 2 * 45) + 20;
+        }
+
+        labelNode = <text y={y} style={labelStyle} textAnchor={anchor}>
+            <tspan x={x}>S: {label[0]}</tspan>
+            <tspan x={x} dy={45}>A: {label[1]}</tspan>
+            {label[2] && <tspan x={x} dy={45}>{label[2]}</tspan>}
+        </text>;
+    }
+
+    return <>
+        {inside && crosshairOffset && <line x1={crosshairOffset[0] + PlotOffset} x2={crosshairOffset[0] + PlotOffset} y1={PlotOffset} y2={PlotOffset + PlotSize} style={{ pointerEvents: 'none', stroke: 'black', strokeDasharray: '5,5' }} />}
+        {inside && crosshairOffset && <line x1={PlotOffset} x2={PlotOffset + PlotSize} y1={crosshairOffset[1] + PlotOffset} y2={crosshairOffset[1] + PlotOffset} style={{ pointerEvents: 'none', stroke: 'black', strokeDasharray: '5,5' }} />}
+        {box && <rect x={PlotOffset + box[0]} y={PlotOffset + box[1]} width={box[2]} height={box[3]} style={{ stroke: '#eee', strokeWidth: 4, fill: 'rgba(0, 0, 0, 0.15)', pointerEvents: 'none' }} />}
+        {labelNode}
+    </>;
+}
+
+function getCrosshairLabel(state: PlotInteractivityState) {
+    if (!state.drawing || !state.crosshairOffset || !state.inside) return;
+
+    const { drawing } = state;
+    const rA = getResidueIndex(drawing, clamp(state.crosshairOffset[0], 0, PlotSize));
+    const rB = getResidueIndex(drawing, clamp(state.crosshairOffset[1], 0, PlotSize));
+
+    const value = drawing.metric.values[rA]?.[rB] ?? drawing.metric.values[rB]?.[rA];
+    const valueLabel = typeof value === 'number' ? `${round(value, 2)} Å` : '';
+
+    return [getResidueLabel(drawing, rA), getResidueLabel(drawing, rB), valueLabel];
+}
+
+function getResidueIndex(drawing: MAPairwiseMetricDrawing, offset: number) {
+    const rI = drawing.metric.residueRange[0] + Math.round(offset / PlotSize * (drawing.metric.residueRange[1] - drawing.metric.residueRange[0] + 1)) as ResidueIndex;
+    return clamp(rI, drawing.metric.residueRange[0], drawing.metric.residueRange[1]) as ResidueIndex;
+}
+
+function getResidueLabel(drawing: MAPairwiseMetricDrawing, rI: ResidueIndex) {
+    const hierarchy = drawing.model.atomicHierarchy;
+    const asym_id = hierarchy.chains.label_asym_id;
+    const seq_id = hierarchy.residues.label_seq_id;
+    const comp_id = hierarchy.atoms.label_comp_id;
+
+    return `${asym_id.value(AtomicHierarchy.residueChainIndex(hierarchy, rI))} ${seq_id.value(rI)} ${comp_id.value(AtomicHierarchy.residueFirstAtomIndex(hierarchy, rI))}`;
+}
+
+function getBox(state: PlotInteractivityState) {
+    const start = state.boxStart;
+    const end = state.mouseDown ? state.crosshairOffset : state.boxEnd;
+    if (!start || !end) return undefined;
+
+    const x = clamp(Math.min(start[0], end[0]), 0, PlotSize);
+    const width = clamp(Math.max(start[0], end[0]), 0, PlotSize) - x;
+    const y = clamp(Math.min(start[1], end[1]), 0, PlotSize);
+    const height = clamp(Math.max(start[1], end[1]), 0, PlotSize) - y;
+
+    if (width < 1 && height < 1) return undefined;
+
+    return [x, y, width, height];
+}
+
+function getPlotMouseOffset(ev: React.MouseEvent<SVGRectElement, MouseEvent>) {
+    return getPlotMouseOffsetBase(ev.currentTarget, ev.clientX, ev.clientY);
+}
+
+function getPlotMouseOffsetBase(target: HTMLElement | SVGRectElement, clientX: number, clientY: number) {
+    const rect = target.getBoundingClientRect();
+    const offsetX = PlotSize * (clientX - rect.left) / rect.width;
+    const offsetY = PlotSize * (clientY - rect.top) / rect.height;
+    return [offsetX, offsetY] as [number, number];
+}
+
+function findModelRef(plugin: PluginContext, model: Model | undefined) {
+    if (!model) return undefined;
+    for (const m of plugin.managers.structure.hierarchy.current.models) {
+        if (m.cell.obj?.data === model) return m;
+    }
+    return undefined;
+}
+
+function highlightState(plugin: PluginContext, state: PlotInteractivityState) {
+    const structure = findModelRef(plugin, state.model)?.structures[0]?.cell.obj?.data;
+    if (!state.drawing || !state.crosshairOffset || !state.inside || !structure) {
+        plugin.managers.interactivity.lociHighlights.clearHighlights();
+        return;
+    }
+
+    const { drawing } = state;
+    const rA = getResidueIndex(drawing, clamp(state.crosshairOffset[0], 0, PlotSize));
+    const rB = getResidueIndex(drawing, clamp(state.crosshairOffset[1], 0, PlotSize));
+
+    const resIdx = StructureProperties.residue.key;
+    const loci = StructureQuery.loci(atoms({
+        residueTest: ctx => {
+            const rI = resIdx(ctx.element);
+            return rI === rA || rI === rB;
+        },
+    }), structure);
+
+    plugin.managers.interactivity.lociHighlights.highlightOnly({ loci });
+}
+
+async function overpaintState(plugin: PluginContext, state: PlotInteractivityState) {
+    const tag = 'modelarchive-pae-overpaint';
+
+    const overpaints = plugin.state.data.selectQ(q => q.root.subtree().withTag(tag));
+    const update = plugin.build();
+    for (const overpaint of overpaints) update.delete(overpaint);
+
+    const model = findModelRef(plugin, state.model);
+    const structure = model?.structures[0]?.cell.obj?.data;
+    if (!state.drawing || !state.boxStart || !(state.boxEnd || state.crosshairOffset) || !structure) {
+        if (!overpaints) return;
+        return reApplyRepresentationStates(plugin, update);
+    }
+
+    const start = state.boxStart;
+    const end = state.mouseDown ? state.crosshairOffset! : state.boxEnd!;
+
+    const x0 = clamp(Math.min(start[0], end[0]), 0, PlotSize);
+    const x1 = clamp(Math.max(start[0], end[0]), 0, PlotSize);
+    const y0 = clamp(Math.min(start[1], end[1]), 0, PlotSize);
+    const y1 = clamp(Math.max(start[1], end[1]), 0, PlotSize);
+
+    if (x1 - x0 <= 1 || y1 - y0 <= 1) {
+        if (!overpaints) return;
+        return reApplyRepresentationStates(plugin, update);
+    }
+
+    const representations = plugin.state.data.selectQ(q =>
+        q.byRef(model.cell.transform.ref!)
+            .subtree()
+            .ofType(PluginStateObject.Molecule.Structure.Representation3D)
+    );
+
+    const resIdx = StructureProperties.residue.key;
+
+    const startScored = getResidueIndex(state.drawing, x0);
+    const endScored = getResidueIndex(state.drawing, x1);
+    const lociScored = StructureQuery.loci(atoms({
+        residueTest: ctx => {
+            const rI = resIdx(ctx.element);
+            return rI >= startScored && rI <= endScored;
+        },
+    }), structure);
+
+    const startAligned = getResidueIndex(state.drawing, y0);
+    const endAligned = getResidueIndex(state.drawing, y1);
+    const lociAligned = StructureQuery.loci(atoms({
+        residueTest: ctx => {
+            const rI = resIdx(ctx.element);
+            return rI >= startAligned && rI <= endAligned;
+        },
+    }), structure);
+
+    const layers = [{
+        bundle: StructureElement.Bundle.fromSubStructure(structure, structure),
+        color: Color(0x777777),
+        clear: false,
+    }, {
+        bundle: StructureElement.Bundle.fromLoci(lociScored),
+        color: PlotColors.ScoredOverpaint,
+        clear: false,
+    }, {
+        bundle: StructureElement.Bundle.fromLoci(lociAligned),
+        color: PlotColors.AlignedOverpaint,
+        clear: false,
+    }];
+
+    for (const repr of representations) {
+        update.to(repr).apply(OverpaintStructureRepresentation3DFromBundle, { layers }, { tags: [tag], state: { isGhost: true } });
+    }
+
+    return update.commit();
+}
+
+async function reApplyRepresentationStates(plugin: PluginContext, update: StateBuilder.Root) {
+    await update.commit();
+    const states = plugin.state.data.selectQ(q => q.root.subtree().ofType(PluginStateObject.Molecule.Structure.Representation3DState));
+    for (const state of states) {
+        const data = state.obj?.data;
+        if (!data) continue;
+        data.repr.setState(data.state);
+        plugin.canvas3d?.update(data.repr);
+    }
+}

src/extensions/model-archive/quality-assessment/prop.ts

@@ -1,21 +1,24 @@
 /**
- * Copyright (c) 2021 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2021-24 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  * @author David Sehnal <david.sehnal@gmail.com>
  */
 
-import { ParamDefinition as PD } from '../../../mol-util/param-definition';
-import { Unit } from '../../../mol-model/structure';
-import { CustomProperty } from '../../../mol-model-props/common/custom-property';
+import { CifFrame } from '../../../mol-io/reader/cif';
+import { toDatabase } from '../../../mol-io/reader/cif/schema';
+import { mmCIF_Schema } from '../../../mol-io/reader/cif/schema/mmcif';
+import { MmcifFormat } from '../../../mol-model-formats/structure/mmcif';
 import { CustomModelProperty } from '../../../mol-model-props/common/custom-model-property';
+import { CustomProperty } from '../../../mol-model-props/common/custom-property';
+import { CustomPropertyDescriptor } from '../../../mol-model/custom-property';
+import { Unit } from '../../../mol-model/structure';
 import { Model, ResidueIndex } from '../../../mol-model/structure/model';
-import { QuerySymbolRuntime } from '../../../mol-script/runtime/query/compiler';
+import { AtomicIndex } from '../../../mol-model/structure/model/properties/atomic';
 import { CustomPropSymbol } from '../../../mol-script/language/symbol';
 import { Type } from '../../../mol-script/language/type';
-import { CustomPropertyDescriptor } from '../../../mol-model/custom-property';
-import { MmcifFormat } from '../../../mol-model-formats/structure/mmcif';
-import { AtomicIndex } from '../../../mol-model/structure/model/properties/atomic';
+import { QuerySymbolRuntime } from '../../../mol-script/runtime/query/compiler';
+import { ParamDefinition as PD } from '../../../mol-util/param-definition';
 
 export { QualityAssessment };
 
@@ -26,10 +29,19 @@ interface QualityAssessment {
 }
 
 namespace QualityAssessment {
+    export interface Pairwise {
+        id: number
+        name: string
+
+        residueRange: [ResidueIndex, ResidueIndex]
+        valueRange: [number, number]
+        values: Record<ResidueIndex, Record<ResidueIndex, number | undefined> | undefined>
+    }
+
     const Empty = {
         value: {
-            localMetrics: new Map()
-        }
+            localMetrics: new Map(),
+        } satisfies QualityAssessment
     };
 
     export function isApplicable(model?: Model, localMetricName?: 'pLDDT' | 'qmean'): boolean {
@@ -106,6 +118,101 @@ namespace QualityAssessment {
         };
     }
 
+    const PairwiseSchema = {
+        ma_qa_metric: mmCIF_Schema.ma_qa_metric,
+        ma_qa_metric_local_pairwise: mmCIF_Schema.ma_qa_metric_local_pairwise
+    };
+
+    export function findModelArchiveCIFPAEMetrics(frame: CifFrame) {
+        const { ma_qa_metric, ma_qa_metric_local_pairwise } = toDatabase(PairwiseSchema, frame);
+        const result: { id: number, name: string }[] = [];
+        if (ma_qa_metric_local_pairwise._rowCount === 0) return result;
+
+        for (let i = 0, il = ma_qa_metric._rowCount; i < il; i++) {
+            if (ma_qa_metric.mode.value(i) !== 'local-pairwise') continue;
+            const id = ma_qa_metric.id.value(i);
+            const name = ma_qa_metric.name.value(i);
+            if (!name.toLowerCase().includes('pae')) continue;
+            result.push({ id, name });
+        }
+        return result;
+    }
+
+    export function pairwiseMetricFromModelArchiveCIF(model: Model, frame: CifFrame, metricId: number): Pairwise | undefined {
+        const db = toDatabase(PairwiseSchema, frame);
+        if (!db.ma_qa_metric_local_pairwise._rowCount) return undefined;
+
+        const { ma_qa_metric, ma_qa_metric_local_pairwise } = db;
+        const { model_id, label_asym_id_1, label_seq_id_1, label_asym_id_2, label_seq_id_2, metric_id, metric_value } = db.ma_qa_metric_local_pairwise;
+        const { index } = model.atomicHierarchy;
+
+        let metric: Pairwise | undefined;
+
+        for (let i = 0, il = ma_qa_metric._rowCount; i < il; i++) {
+            if (ma_qa_metric.mode.value(i) !== 'local-pairwise') continue;
+            const id = ma_qa_metric.id.value(i);
+            if (id !== metricId) continue;
+
+            const name = ma_qa_metric.name.value(i);
+            metric = {
+                id,
+                name,
+                residueRange: [Number.MAX_SAFE_INTEGER as ResidueIndex, Number.MIN_SAFE_INTEGER as ResidueIndex],
+                valueRange: [Number.MAX_VALUE, -Number.MAX_VALUE],
+                values: {}
+            };
+        }
+
+        if (!metric) return undefined;
+
+        const { values, residueRange, valueRange } = metric;
+        const residueKey: AtomicIndex.ResidueLabelKey = {
+            label_entity_id: '',
+            label_asym_id: '',
+            label_seq_id: 0,
+            pdbx_PDB_ins_code: undefined,
+        };
+
+        for (let i = 0, il = ma_qa_metric_local_pairwise._rowCount; i < il; i++) {
+            if (model_id.value(i) !== model.modelNum || metric_id.value(i) !== metricId) continue;
+
+            let labelAsymId = label_asym_id_1.value(i);
+            let entityIndex = index.findEntity(labelAsymId);
+            residueKey.label_entity_id = model.entities.data.id.value(entityIndex);
+            residueKey.label_asym_id = labelAsymId;
+            residueKey.label_seq_id = label_seq_id_1.value(i);
+
+            const rI_1 = index.findResidueLabel(residueKey);
+            if (rI_1 < 0) continue;
+
+            labelAsymId = label_asym_id_2.value(i);
+            entityIndex = index.findEntity(labelAsymId);
+            residueKey.label_entity_id = model.entities.data.id.value(entityIndex);
+            residueKey.label_asym_id = labelAsymId;
+            residueKey.label_seq_id = label_seq_id_2.value(i);
+
+            const rI_2 = index.findResidueLabel(residueKey);
+            if (rI_1 < 0) continue;
+
+            let r1 = values[rI_1];
+            if (!r1) {
+                r1 = {};
+                values[rI_1] = r1;
+            }
+            const value = metric_value.value(i);
+            r1[rI_2] = value;
+
+            if (rI_1 < residueRange[0]) residueRange[0] = rI_1;
+            if (rI_2 < residueRange[0]) residueRange[0] = rI_2;
+            if (rI_1 > residueRange[1]) residueRange[1] = rI_1;
+            if (rI_2 > residueRange[1]) residueRange[1] = rI_2;
+            if (value < valueRange[0]) valueRange[0] = value;
+            if (value > valueRange[1]) valueRange[1] = value;
+        }
+
+        return metric;
+    }
+
     export const symbols = {
         pLDDT: QuerySymbolRuntime.Dynamic(CustomPropSymbol('ma', 'quality-assessment.pLDDT', Type.Num),
             ctx => {

src/extensions/mp4-export/encoder.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2020 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2020-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author David Sehnal <david.sehnal@gmail.com>
  */
@@ -72,11 +72,11 @@ export async function encodeMp4Animation<A extends PluginStateAnimation>(plugin:
         await params.pass.updateBackground();
 
         await plugin.managers.animation.play(params.animation.definition, params.animation.params);
+
         stoppedAnimation = false;
         for (let i = 0; i <= N; i++) {
-            await loop.tick(i * dt, { isSynchronous: true, animation: { currentFrame: i, frameCount: N }, manualDraw: true });
-
-            const image = params.pass.getImageData(width, height, normalizedViewport);
+            await loop.tick(i * dt, { isSynchronous: true, animation: { currentFrame: i, frameCount: N }, manualDraw: true, updateControls: true });
+            const image = await params.pass.getImageData(ctx, width, height, normalizedViewport);
             encoder.addFrameRgba(image.data);
 
             if (ctx.shouldUpdate) {