4.1.0

- fix types
- fix webpack browserify issue

.eslintrc.json

@@ -18,7 +18,7 @@
         ],
         "brace-style": "off",
         "comma-spacing": "off",
-        "space-infix-ops": "error",
+        "space-infix-ops": "off",
         "comma-dangle": "off",
         "eqeqeq": [
             "error",
@@ -38,7 +38,25 @@
                 "selector": "ExportDefaultDeclaration",
                 "message": "Default exports are not allowed"
             }
-        ]
+        ],
+        "no-throw-literal": "error",
+        "key-spacing": "error",
+        "object-curly-spacing": ["error", "always"],
+        "array-bracket-spacing": "error",
+        "space-in-parens": "error",
+        "computed-property-spacing": "error",
+        "prefer-const": ["error", {
+            "destructuring": "all",
+            "ignoreReadBeforeAssign": false
+        }],
+        "space-before-function-paren": "off",
+        "func-call-spacing": "off",
+        "no-multi-spaces": "error",
+        "block-spacing": "error",
+        "keyword-spacing": "off",
+        "space-before-blocks": "error",
+        "semi-spacing": "error",
+        "no-constant-binary-expression": "error"
     },
     "overrides": [
         {
@@ -89,7 +107,15 @@
                     "error",
                     "1tbs", { "allowSingleLine": true }
                 ],
-                "@typescript-eslint/comma-spacing": "error"
+                "@typescript-eslint/comma-spacing": "error",
+                "@typescript-eslint/space-infix-ops": "error",
+                "@typescript-eslint/space-before-function-paren": ["error", {
+                    "anonymous": "always",
+                    "named": "never",
+                    "asyncArrow": "always"
+                }],
+                "@typescript-eslint/func-call-spacing": ["error"],
+                "@typescript-eslint/keyword-spacing": ["error"]
             }
         }
     ]

.github/pull_request_template.md

@@ -0,0 +1,10 @@
+<!-- Thank you for contributing to Mol* -->
+
+# Description
+
+
+## Actions
+
+- [ ] Added description of changes to the `[Unreleased]` section of `CHANGELOG.md`
+- [ ] Updated headers of modified files
+- [ ] Added my name to `package.json`'s `contributors`

.github/workflows/lint.yml

@@ -1,18 +0,0 @@
-on:
-  push:
-  pull_request:
-
-jobs:
-  eslint:
-    name: eslint
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v1
-    - name: install node v12
-      uses: actions/setup-node@v1
-      with:
-        node-version: 12
-    - name: yarn install
-      run: yarn install
-    - name: eslint
-      uses: icrawl/action-eslint@v1

.github/workflows/node.yml

@@ -0,0 +1,22 @@
+name: Build
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: actions/setup-node@v2
+      with:
+        node-version: 18
+    - run: npm ci
+    - run: sudo apt-get install xvfb
+    - name: Lint
+      run: npm run lint
+    - name: Test
+      run: npm install --no-save "gl@^6.0.2" && xvfb-run --auto-servernum npm run jest
+    - name: Build
+      run: npm run build

.gitignore

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

.npmignore

@@ -1 +1,5 @@
-tsconfig.commonjs.buildinfo
+tests
+perf-tests
+_spec
+*.tsbuildinfo
+*.js.map

.travis.yml

@@ -1,18 +0,0 @@
-language: node_js
-os: linux
-sudo: required
-dist: trusty
-before_install:
-  - sudo apt-get install -y mesa-utils
-  - sudo apt-get install -y xvfb
-  - sudo apt-get install -y libgl1-mesa-dri
-  - sudo apt-get install -y libglapi-mesa
-  - sudo apt-get install -y libosmesa6
-  - sudo apt-get install -y gcc-4.9
-  - sudo apt-get install -y libstdc++6
-  - sudo apt-get install -y libxi-dev
-node_js:
-  - "12"
-  - "10"
-before_script:
-  - export DISPLAY=:99.0; sh -e /etc/init.d/xvfb start

.vscode/extensions.json

@@ -6,7 +6,6 @@
 	"recommendations": [
 		"dbaeumer.vscode-eslint",
 		"firsttris.vscode-jest-runner",
-		"msjsdiag.debugger-for-chrome",
 		"slevesque.shader",
 		"stpn.vscode-graphql",
 		"wayou.vscode-todo-highlight"

.vscode/settings.json

@@ -7,6 +7,8 @@
         "*.gql.ts": "graphql"
     },
     "eslint.options": {
-        "ignorePattern": ["webpack.config.js", "scripts/*"],
+        "overrideConfig": {
+            "ignorePatterns": ["webpack.config.js", "scripts/*"],
+        },
     }
 }

CITATION.cff

@@ -0,0 +1,72 @@
+cff-version: 1.2.0
+title: >-
+  Mol* library
+message: >-
+  Please cite this software using the metadata from
+  'preferred-citation'.
+authors:
+  - given-names: Alexander S
+    family-names: Rose
+    orcid: 'https://orcid.org/0000-0002-0893-5551'
+  - given-names: David
+    family-names: Sehnal
+    orcid: 'https://orcid.org/0000-0002-0682-3089'
+  - given-names: Sebastian
+    family-names: Bittrich
+    orcid: 'https://orcid.org/0000-0003-3576-0387'
+  - given-names: Áron Samuel
+    family-names: Kovács
+  - given-names: Ludovic
+    family-names: Autin
+    orcid: 'https://orcid.org/0000-0002-2197-191X'
+  - given-names: Michal
+    family-names: Malý
+  - given-names: Jiří
+    family-names: Černý
+  - given-names: Panagiotis
+    family-names: Tourlas
+type: software
+doi: 10.5281/zenodo.3947306
+preferred-citation:
+  authors:
+    - given-names: David
+      family-names: Sehnal
+      orcid: 'https://orcid.org/0000-0002-0682-3089'
+    - given-names: Sebastian
+      family-names: Bittrich
+      orcid: 'https://orcid.org/0000-0003-3576-0387'
+    - given-names: Mandar
+      family-names: Deshpande
+      orcid: 'https://orcid.org/0000-0002-9043-7665'
+    - given-names: Radka
+      family-names: Svobodová
+      orcid: 'https://orcid.org/0000-0002-3840-8760'
+    - given-names: Karel
+      family-names: Berka
+      orcid: 'https://orcid.org/0000-0001-9472-2589'
+    - given-names: Václav
+      family-names: Bazgier
+      orcid: 'https://orcid.org/0000-0003-3393-3010'
+    - given-names: Sameer
+      family-names: Velankar
+      orcid: 'https://orcid.org/0000-0002-8439-5964'
+    - given-names: Stephen K
+      family-names: Burley
+      orcid: 'https://orcid.org/0000-0002-2487-9713'
+    - given-names: Jaroslav
+      family-names: Koča
+      orcid: 'https://orcid.org/0000-0002-2780-4901'
+    - given-names: Alexander S
+      family-names: Rose
+      orcid: 'https://orcid.org/0000-0002-0893-5551'
+  title: >-
+    Mol* Viewer: modern web app for 3D visualization
+    and analysis of large biomolecular structures
+  type: article
+  doi: 10.1093/nar/gkab314
+  journal: "Nucleic Acids Research"
+  issue: W1
+  volume: 49
+  year: 2021
+  month: 7
+  pages: "W431–W437"

README.md

@@ -1,19 +1,26 @@
 [![License](http://img.shields.io/badge/license-MIT-blue.svg?style=flat)](./LICENSE)
 [![npm version](https://badge.fury.io/js/molstar.svg)](https://www.npmjs.com/package/molstar)
-[![Build Status](https://travis-ci.org/molstar/molstar.svg?branch=master)](https://travis-ci.org/molstar/molstar)
+[![Build](https://github.com/molstar/molstar/actions/workflows/node.yml/badge.svg)](https://github.com/molstar/molstar/actions/workflows/node.yml)
 [![Gitter](https://badges.gitter.im/molstar/Lobby.svg)](https://gitter.im/molstar/Lobby)
 
 # Mol*
 
-The goal of **Mol\*** (*/'mol-star/*) is to provide a technology stack that will serve as a basis for the next-generation data delivery and analysis tools for macromolecular structure data. This is a collaboration between PDBe and RCSB PDB teams and the development will be open-source and available to anyone who wants to use it for developing visualization tools for macromolecular structure data available from [PDB](https://www.wwpdb.org/) and other institutions.
+The goal of **Mol\*** (*/'mol-star/*) is to provide a technology stack that serves as a basis for the next-generation data delivery and analysis tools for (not only) macromolecular structure data. Mol* development was jointly initiated by PDBe and RCSB PDB to combine and build on the strengths of [LiteMol](https://litemol.org) (developed by PDBe) and [NGL](https://nglviewer.org) (developed by RCSB PDB) viewers.
 
-This particular project is the implementation of this technology (still under development).
+When using Mol*, please cite:
 
-*If you are looking for the "MOLeculAR structure annoTator", that package is now available on NPM as [MolArt](https://www.npmjs.com/package/molart).*
+David Sehnal, Sebastian Bittrich, Mandar Deshpande, Radka Svobodová, Karel Berka, Václav Bazgier, Sameer Velankar, Stephen K Burley, Jaroslav Koča, Alexander S Rose: [Mol* Viewer: modern web app for 3D visualization and analysis of large biomolecular structures](https://doi.org/10.1093/nar/gkab314), *Nucleic Acids Research*, 2021; https://doi.org/10.1093/nar/gkab314.
 
-## Project Overview
+### Protein Data Bank Integrations
 
-The core of Mol* currently consists of these modules (see under `src/`):
+- The [pdbe-molstar](https://github.com/molstar/pdbe-molstar) library is the Mol* implementation used by EMBL-EBI data resources such as [PDBe](https://pdbe.org/), [PDBe-KB](https://pdbe-kb.org/) and [AlphaFold DB](https://alphafold.ebi.ac.uk/). This implementation can be used as a JS plugin and a Web component and supports property/attribute-based easy customisation. It provides helper methods to facilitate programmatic interactions between the web application and the 3D viewer. It also provides a superposition view for overlaying all the observed ligand molecules on representative protein conformations.
+
+- [rcsb-molstar](https://github.com/molstar/rcsb-molstar) is the Mol* plugin used by [RCSB PDB](https://www.rcsb.org). The project provides additional presets for the visualization of structure alignments and structure motifs such as ligand binding sites. Furthermore, [rcsb-molstar](https://github.com/molstar/rcsb-molstar) allows to interactively add or hide of (parts of) chains, as seen in the [3D Protein Feature View](https://www.rcsb.org/3d-sequence/4hhb).
+
+
+## Project Structure Overview
+
+The core of Mol* consists of these modules (see under `src/`):
 
 - `mol-task` Computation abstraction with progress tracking and cancellation support.
 - `mol-data` Collections (integer-based sets, interface to columns/tables, etc.)
@@ -29,7 +36,6 @@ The core of Mol* currently consists of these modules (see under `src/`):
 - `mol-gl` A wrapper around WebGL.
 - `mol-canvas3d` A low-level 3d view component. Uses `mol-geo` to generate geometries.
 - `mol-state` State representation tree with state saving and automatic updates.
-- `mol-app` Components for building UIs.
 - `mol-plugin` Allow to define modular Mol* plugin instances utilizing `mol-state` and `mol-canvas3d`.
 - `mol-plugin-state` State transformations, builders, and managers.
 - `mol-plugin-ui` React-based user interface for the Mol* plugin. Some components of the UI are usable outside the main plugin and can be integrated into 3rd party solutions.
@@ -41,7 +47,7 @@ Moreover, the project contains the implementation of `servers`, including
 - `servers/volume` A tool for accessing volumetric experimental data related to molecular structures.
 - `servers/plugin-state` A basic server to store Mol* Plugin states.
 
-The project also contains performance tests (`perf-tests`), `examples`, and basic proof of concept `cli` apps (CIF to BinaryCIF converter and JSON domain annotation to CIF converter).
+The project also contains performance tests (`perf-tests`), `examples`, and `cli` apps (CIF to BinaryCIF converter and JSON domain annotation to CIF converter).
 
 ## Previous Work
 This project builds on experience from previous solutions:
@@ -69,6 +75,17 @@ If working on just the viewer, ``npm run watch-viewer`` will provide shorter com
 
 Debug/production mode in browsers can be turned on/off during runtime by calling ``setMolStarDebugMode(true/false, true/false)`` from the dev console.
 
+### Cleaning and forcing a full rebuild
+    npm run clean
+
+Wipes the `build` and `lib` directories and `.tsbuildinfo` files.
+
+    npm run rebuild
+
+Runs the cleanup script prior to building the project, forcing a full rebuild of the project.
+
+Use these commands to resolve occassional build failures which may arise after some dependency updates. Once done, `npm run build` should work again. Note that full rebuilds take more time to complete.
+
 ### Build for production:
     NODE_ENV=production npm run build
 
@@ -103,10 +120,9 @@ and navigate to `build/viewer`
 
     node --max-old-space-size=4096 lib/commonjs/cli/chem-comp-dict/create-ions.js src/mol-model/structure/model/types/ions.ts
 
+**Saccharide names**
 
-**GraphQL schemas**
-
-    node node_modules//@graphql-codegen/cli/bin -c src/extensions/rcsb/graphql/codegen.yml
+    node --max-old-space-size=4096 lib/commonjs/cli/chem-comp-dict/create-saccharides.js src/mol-model/structure/model/types/saccharides.ts
 
 ### Other scripts
 **Create chem comp bond table**
@@ -121,16 +137,21 @@ and navigate to `build/viewer`
 
     export NODE_PATH="lib"; node build/state-docs
 
-**Convert any CIF to BinaryCIF**
+**Convert any CIF to BinaryCIF (or vice versa)**
 
-    node lib/servers/model/preprocess -i file.cif -ob file.bcif
+    node lib/commonjs/servers/model/preprocess -i file.cif -ob file.bcif
 
-To see all available commands, use ``node lib/servers/model/preprocess -h``.
+To see all available commands, use ``node lib/commonjs/servers/model/preprocess -h``.
 
 Or
 
     node lib/commonjs/cli/cif2bcif
 
+E.g.
+
+    node lib/commonjs/cli/cif2bcif src.cif out.bcif.gz
+    node lib/commonjs/cli/cif2bcif src.bcif.gz out.cif
+
 ## Development
 
 ### Installation
@@ -142,13 +163,12 @@ If node complains about a missing acorn peer dependency, run the following comma
 
 ### Editor
 
-To get syntax highlighting for shader and graphql files add the following to Visual Code's settings files and make sure relevant extensions are installed in the editor.
+To get syntax highlighting for shader files add the following to Visual Code's settings files and make sure relevant extensions are installed in the editor.
 
     "files.associations": {
         "*.glsl.ts": "glsl",
         "*.frag.ts": "glsl",
-        "*.vert.ts": "glsl",
-        "*.gql.ts": "graphql"
+        "*.vert.ts": "glsl"
     },
 
 ## Publish
@@ -169,12 +189,9 @@ To get syntax highlighting for shader and graphql files add the following to Vis
 ## Contributing
 Just open an issue or make a pull request. All contributions are welcome.
 
-## Roadmap
-Continually develop this prototype project. As individual modules become stable, make them into standalone libraries.
-
 ## Funding
 Funding sources include but are not limited to:
 * [RCSB PDB](https://www.rcsb.org) funding by a grant [DBI-1338415; PI: SK Burley] from the NSF, the NIH, and the US DoE
 * [PDBe, EMBL-EBI](https://pdbe.org)
 * [CEITEC](https://www.ceitec.eu/)
-* [EntosAI](https://www.entos.ai) (``alpha-orbitals`` extension)
+* [EntosAI](https://www.entos.ai)

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

@@ -2,11 +2,11 @@ audit.block_doi
 
 database_code.depnum_ccdc_archive
 database_code.depnum_ccdc_fiz
-database_code.ICSD
-database_code.MDF
-database_code.NBS
-database_code.CSD
-database_code.COD
+database_code.icsd
+database_code.mdf
+database_code.nbs
+database_code.csd
+database_code.cod
 
 chemical.name_systematic
 chemical.name_common
@@ -24,8 +24,8 @@ atom_type_scat.dispersion_imag
 atom_type_scat.source
 
 space_group.crystal_system
-space_group.name_H-M_full
-space_group.IT_number
+space_group.name_h-m_full
+space_group.it_number
 space_group_symop.operation_xyz
 
 cell.length_a
@@ -35,14 +35,14 @@ cell.angle_alpha
 cell.angle_beta
 cell.angle_gamma
 cell.volume
-cell.formula_units_Z
+cell.formula_units_z
 
 atom_site.label
 atom_site.type_symbol
 atom_site.fract_x
 atom_site.fract_y
 atom_site.fract_z
-atom_site.U_iso_or_equiv
+atom_site.u_iso_or_equiv
 atom_site.adp_type
 atom_site.occupancy
 atom_site.calc_flag
@@ -52,20 +52,13 @@ atom_site.disorder_group
 atom_site.site_symmetry_multiplicity
 
 atom_site_aniso.label
-atom_site_aniso.U
-atom_site_aniso.U_11
-atom_site_aniso.U_22
-atom_site_aniso.U_33
-atom_site_aniso.U_23
-atom_site_aniso.U_13
-atom_site_aniso.U_12
-atom_site_aniso.U_su
-atom_site_aniso.U_11_su
-atom_site_aniso.U_22_su
-atom_site_aniso.U_33_su
-atom_site_aniso.U_23_su
-atom_site_aniso.U_13_su
-atom_site_aniso.U_12_su
+atom_site_aniso.u
+atom_site_aniso.u_11
+atom_site_aniso.u_22
+atom_site_aniso.u_33
+atom_site_aniso.u_23
+atom_site_aniso.u_13
+atom_site_aniso.u_12
 
 geom_bond.atom_site_label_1
 geom_bond.atom_site_label_2

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

@@ -24,6 +24,11 @@ atom_site.auth_asym_id
 atom_site.auth_seq_id
 atom_site.pdbx_PDB_model_num
 atom_site.ihm_model_id
+atom_site.pdbx_label_index
+atom_site.pdbx_sifts_xref_db_name
+atom_site.pdbx_sifts_xref_db_acc
+atom_site.pdbx_sifts_xref_db_num
+atom_site.pdbx_sifts_xref_db_res
 
 atom_site_anisotrop.id
 atom_site_anisotrop.U
@@ -246,6 +251,14 @@ citation_author.ordinal
 exptl.entry_id
 exptl.method
 
+software.classification
+software.date
+software.description
+software.name
+software.pdbx_ordinal
+software.type
+software.version
+
 struct.entry_id
 struct.title
 struct.pdbx_descriptor
@@ -802,4 +815,58 @@ ihm_multi_state_modeling.population_fraction_sd
 ihm_multi_state_modeling.state_type
 ihm_multi_state_modeling.state_name
 ihm_multi_state_modeling.experiment_type
-ihm_multi_state_modeling.details
+ihm_multi_state_modeling.details
+
+ma_data.content_type
+ma_data.content_type_other_details
+ma_data.id
+ma_data.name
+
+ma_model_list.data_id
+ma_model_list.model_group_id
+ma_model_list.model_group_name
+ma_model_list.model_id
+ma_model_list.model_name
+ma_model_list.model_type
+ma_model_list.ordinal_id
+
+ma_qa_metric.id
+ma_qa_metric.mode
+ma_qa_metric.name
+ma_qa_metric.software_group_id
+ma_qa_metric.type
+
+ma_qa_metric_global.metric_id
+ma_qa_metric_global.metric_value
+ma_qa_metric_global.model_id
+ma_qa_metric_global.ordinal_id
+
+ma_qa_metric_local.label_asym_id
+ma_qa_metric_local.label_comp_id
+ma_qa_metric_local.label_seq_id
+ma_qa_metric_local.metric_id
+ma_qa_metric_local.metric_value
+ma_qa_metric_local.model_id
+ma_qa_metric_local.ordinal_id
+
+ma_software_group.group_id
+ma_software_group.ordinal_id
+ma_software_group.software_id
+
+ma_target_entity.data_id
+ma_target_entity.entity_id
+ma_target_entity.origin
+
+ma_target_entity_instance.asym_id
+ma_target_entity_instance.details
+ma_target_entity_instance.entity_id
+
+ma_target_ref_db_details.db_accession
+ma_target_ref_db_details.db_code
+ma_target_ref_db_details.db_name
+ma_target_ref_db_details.ncbi_taxonomy_id
+ma_target_ref_db_details.organism_scientific
+ma_target_ref_db_details.seq_db_align_begin
+ma_target_ref_db_details.seq_db_align_end
+ma_target_ref_db_details.seq_db_isoform
+ma_target_ref_db_details.target_entity_id

docs/extensions/mvs/README.md

@@ -0,0 +1,86 @@
+# MolViewSpec extension in Mol\*
+
+**MolViewSpec (MVS)** is a toolkit for standardized description of reproducible molecular visualizations shareable across software applications. MolViewSpec describes a 3D molecular scene by a MolViewSpec State, a viewer-independent representation that contains all information necessary to reproduce the scene. Thanks to its nested tree-based format, complex scenes can be composed from simple building blocks.
+
+MolViewSpec documentation is available from <https://molstar.org/docs/extensions/mvs/>.
+
+MolViewSpec extension in Mol\* provides functionality for building, validating, and visualizing MolViewSpec States.
+
+## Graphical user interface
+
+-   **Drag&drop support:** The easiest way to load a MVS view into Mol* Viewer is to drag a `.mvsj` or `.mvsx` 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" or "MVSX" (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. Because of these limitations, the preferred method it to host the data somewhere and use `mvs-url` instead.
+    -   `mvs-format` specifies the format of the MVS view data from `mvs-url` or `mvs-data`. Allowed values are `mvsj` and `mvsx` (default is `mvsj`).
+
+    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=mvsx&mvs-url=https://raw.githubusercontent.com/molstar/molstar/master/examples/mvs/1h9t.mvsx
+
+    -   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
+
+    -   https://molstar.org/viewer/?mvs-format=mvsx&mvs-data=base64,UEsDBBQAAAAIADSFPlhDx8RXYwEAAGwFAAAUABwAYW5ub3RhdGlvbnMtMWg5dC5jaWZVVAkAA8MmuWVuvbtldXgLAAEE9gEAAAQUAAAAlZJNj4IwEIbv/RVNPPSkacGPckT8TDabPe6emkq72ARbF9iD/34LFBV1FSbh7YTh4Z1hELzgjOyDgnGtTcELZXQOQGrMkQEWm8PRaKmLfJTynUwZz08HpkSrck5BCD8yU0ilwfycRXDxHoJFpUu4NqkAm/pYwWifmkwJCdaXdHtJmy6uOrtt47q0kwmry7n8uatKLZ5UY2M9Hzi1byWZ+T2WbAhtBPaiPoRoIMR0ijGyqZ1yuFNaKJ0geI5RBdAxhJ5PSgBjSmsgjE/pMDIhbFEj+wFbDnHcAP85zO8dKH3mEFWHEzQgBGPOnQP8vHp347BoA6KKBvh6ACzbwLeNeoZy/XfPW2DTF1i1AYyFqIHmH0I3wLovsO0LlJuezJygTDZ9ozeVcC2aLcBcFSVLKmA6c9IRIB5x8hrwamDipDMQOOkKzKiT14BfAh72S+nY0rzf0OMa6D60A7oPXQF9ZhiDP1BLAwQUAAAACACagEFYhgn8CJECAAAbFQAACgAcAGluZGV4Lm12c2pVVAkAAyTBu2UlwbtldXgLAAEE9gEAAAQUAAAA7VjBjtowEL3vV0S5tiSBFnXhttpKPbWq1KqXqoqMPWwsHDuynaVoxb/XNhAIiUOEtK26m5zIzLzJG8+8gfB0EwShFEKH8+DJfDZ3K8qJudtZ3+5sOKOMSODG/tNZgn10DUHEmjOByB7lfAWSKFdV9r21lMwCMq0LNY/j9XodwYJGCEflKi7IAmLgWm5GS8pAxYe88Tib6bQsCNJAIkyXYZVze/LIFrJ1wjXShqCCE8Z+1s6zFDJH9rTCPK8xOGPRxaTJpsZIaVliXcpzVt3MnFdvCnDcBAEWNiK2LQk7OLbzrHHFIi8EN81Kl1LkaSlpC+nLxF2EBZuUUYw4FxppKrga2Za7VrenrXWkMwyboXkQcpNylEONuurITYGRJsIPWDCBV2kGiIC0EDexJ/X4kQpnkCP3mAxRfonTI2IlKE/T9pFfpdBgUnkifrXaW2bEJbswJ/bydfZ0qUAhQZkjdMfhLbLPvLiow8BjJLUQ3lK9ZbkkPUqzVxeRmiSYkJfkUKF6lekir5NHBe8nkyq8IZc+Q3x82JluzIlcBl2tnSrDUUNmyCgpIZWIP4B/Kuy17fD6fe3i8SHaolsn8nWv22fYgR+/3L2G/bdAjBmtkFRpilfDGvTC/+oaHPZRhRj20S7yk2CkS/b3mZENJd4ZeUlLS5VyiXCHHIZtNWwrT/Q124qhBbD/b1P1en2s/+J2lT7vW2qPGWnr5jV9M292TNNi6Ny/7VzDdq7LesSp9+g5WHcWe+cmIsxBI4I0Ov4P+QhS2a8bwziJxod/IgkoLGmh9547HsBvlBcMgjXVWfD5x7egeRyhpjkobeIsZpJM3o+SySgZfx+P59Pb+btZNPtwO5lO3yTJPEnskWxvtn8AUEsBAh4DFAAAAAgANIU+WEPHxFdjAQAAbAUAABQAGAAAAAAAAQAAAKSBAAAAAGFubm90YXRpb25zLTFoOXQuY2lmVVQFAAPDJrlldXgLAAEE9gEAAAQUAAAAUEsBAh4DFAAAAAgAmoBBWIYJ/AiRAgAAGxUAAAoAGAAAAAAAAQAAAKSBsQEAAGluZGV4Lm12c2pVVAUAAyTBu2V1eAsAAQT2AQAABBQAAABQSwUGAAAAAAIAAgCqAAAAhgQAAAAA
+
+## 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. See the [integration examples](./integration-examples.html) page for a demonstration.
+
+## 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
+# Clone Mol* repo, install, and build
+git clone https://github.com/molstar/molstar.git
+cd molstar/
+npm install && npm run build
+
+# Validate a MolViewSpec file `examples/mvs/1cbs.mvsj`
+node lib/commonjs/cli/mvs/mvs-validate.js examples/mvs/1cbs.mvsj
+
+# Render a MolViewSpec file `examples/mvs/1cbs.mvsj` to `../outputs/1cbs.png`
+node lib/commonjs/cli/mvs/mvs-render.js -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.js --markdown
+```
+
+(An alternative to cloning the GitHub repository is to install Mol\* package from npm by `npm install molstar canvas gl jpeg-js pngjs`. Then you can type `npx mvs-validate ...` instead of `node lib/commonjs/cli/mvs/mvs-validate.js ...`)

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/extensions/struct-conn.md

@@ -0,0 +1,118 @@
+# wwPDB StructConn extension
+
+The STRUCT_CONN category in the mmCIF file format contains details about the connections between portions of the structure. These can be hydrogen bonds, salt bridges, disulfide bridges and so on (see more at <https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v40.dic/Categories/struct_conn.html>).
+
+**wwPDB StructConn extension** in Mol* provides functionality to retrieve and visualize these connections.
+
+The extension exposes three functions, located in `src/extensions/wwpdb/struct-conn/index.ts`. 
+
+- `getStructConns` - to retrieve struct_conn records from a loaded structure
+- `inspectStructConn` - to visualize a struct_conn
+- `clearStructConnInspections` - to remove visulizations created by `inspectStructConn`
+
+
+## Example 1
+
+The following example is a minimal HTML using this functionality:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8" />
+        <link rel="icon" href="./favicon.ico" type="image/x-icon">
+        <title>Mol* Viewer</title>
+        <link rel="stylesheet" type="text/css" href="molstar.css" />
+    </head>
+    <body style="margin: 0px;">
+        <div style="position: absolute; width: 100%; height: 10%; padding-block: 10px;">
+            <button onclick="molstar.PluginExtensions.wwPDBStructConn.inspectStructConn(molstarViewer.plugin, '5elb', 'disulf1');">disulf1</button>
+            <button onclick="molstar.PluginExtensions.wwPDBStructConn.inspectStructConn(molstarViewer.plugin, '5elb', 'disulf2');">disulf2</button>
+            <button onclick="molstar.PluginExtensions.wwPDBStructConn.inspectStructConn(molstarViewer.plugin, '5elb', 'covale1');">covale1</button>
+            <button onclick="molstar.PluginExtensions.wwPDBStructConn.inspectStructConn(molstarViewer.plugin, '5elb', 'covale2');">covale2</button>
+            <button onclick="molstar.PluginExtensions.wwPDBStructConn.inspectStructConn(molstarViewer.plugin, '5elb', 'covale3');">covale3</button>
+            <button onclick="molstar.PluginExtensions.wwPDBStructConn.inspectStructConn(molstarViewer.plugin, '5elb', 'covale4');">covale4</button>
+            <button onclick="molstar.PluginExtensions.wwPDBStructConn.inspectStructConn(molstarViewer.plugin, '5elb', 'metalc1');">metalc1</button>
+            <button onclick="molstar.PluginExtensions.wwPDBStructConn.inspectStructConn(molstarViewer.plugin, '5elb', 'metalc2');">metalc2</button>
+            <button onclick="molstar.PluginExtensions.wwPDBStructConn.inspectStructConn(molstarViewer.plugin, '5elb', 'metalc3');">metalc3</button>
+            <button onclick="molstar.PluginExtensions.wwPDBStructConn.inspectStructConn(molstarViewer.plugin, '5elb', 'metalc4');">metalc4</button>
+            <button onclick="molstar.PluginExtensions.wwPDBStructConn.clearStructConnInspections(molstarViewer.plugin, '5elb');">CLEAR</button>
+        </div>
+        <div id="app" style="position: absolute; top: 10%; width: 100%; height: 90%;"></div>
+        <script type="text/javascript" src="./molstar.js"></script>
+        <script type="text/javascript">
+            var molstarViewer;
+            molstar.Viewer.create('app', { layoutIsExpanded: false }).then(viewer => {
+                molstarViewer = viewer;
+                viewer.loadPdb('5elb');
+            });
+        </script>
+    </body>
+</html>
+```
+
+The PDB ID (`'5elb'`) can be replaced be `undefined`, in which case the functions will apply to the first loaded structure.
+
+
+## Example 2
+
+This is a more elaborated example, which automatically loads `5elb` (or any PDB entry given in the URL after `?pdb=`), retrieves the list of struct_conns, and creates a button for each struct_conn. 
+
+Be aware that some of the struct_conns may be present in the deposited model but not in the preferred assembly (default view). The presented example will raise a dialog window with error message in such cases, e.g. `disulf6` in entry `5elb`.
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8" />
+        <link rel="icon" href="./favicon.ico" type="image/x-icon">
+        <title>Mol* Viewer - StructConn Extension Demo</title>
+        <link rel="stylesheet" type="text/css" href="molstar.css" />
+    </head>
+    <style>
+        body { margin: 0px; }
+        #app { position: absolute; width: 85%; height: 100%; }
+        #controls { position: absolute; right: 0; width: 15%; height: 100%; display: flex; flex-direction: column; overflow-y: scroll; }
+        h1 { text-align: center; margin: 12px; font-weight: bold; font-size: 120%; }
+        button { margin: 4px; margin-top: 0px; }
+    </style>
+    <body>
+        <div id="app"></div>
+        <div id="controls">
+            <h1 id="pdb-id">Loading...</h1>
+            <button onclick="clearInspections();">CLEAR</button>
+        </div>
+        <script type="text/javascript" src="./molstar.js"></script>
+        <script type="text/javascript">
+            var pdbId = window.location.search.match(/[?&]pdb=(\w+)/i)?.[1]?.toLowerCase() ?? '5elb';
+            var molstarViewer;
+            function inspect(structConnId) {
+                if (molstarViewer?.plugin) {
+                    molstar.PluginExtensions.wwPDBStructConn.inspectStructConn(molstarViewer.plugin, pdbId, structConnId).then(nSelectedAtoms => {
+                        if (nSelectedAtoms < 2) alert('Some of the interacting atoms were not found :(\n(maybe not present in the viewed assembly)');
+                    });
+                }
+            }
+            function clearInspections() {
+                if (molstarViewer?.plugin) {
+                    molstar.PluginExtensions.wwPDBStructConn.clearStructConnInspections(molstarViewer.plugin, pdbId);
+                }
+            }
+            molstar.Viewer.create('app', { layoutIsExpanded: false }).then(viewer => {
+                molstarViewer = viewer;
+                return viewer.loadPdb(pdbId);
+            }).then(() => {
+                const structConns = molstar.PluginExtensions.wwPDBStructConn.getStructConns(molstarViewer.plugin, pdbId);
+                const controls = document.getElementById('controls');
+                for (const structConnId in structConns) {
+                    const button = document.createElement('button');
+                    button.innerText = structConnId;
+                    button.addEventListener('click', () => inspect(structConnId));
+                    controls.appendChild(button);
+                };
+                document.getElementById('pdb-id').innerHTML = pdbId;
+            });
+        </script>
+    </body>
+</html>
+```

docs/file-formats.md

@@ -0,0 +1,44 @@
+
+Support file formats and their extensions.
+
+## Structure
+
+- MMCIF and CIFCORE (mmCIF and coreCIF schemas): cif, bcif, mmcif, mcif
+- GRO: gro
+- MOL: mol
+- MOL2: mol2
+- PDB/PDBQT: pdb, ent, pdbqt
+- SDF: sdf, sd
+- XYZ: xyz
+
+
+## Topology
+
+Need to be loaded together with Coordinates.
+
+- PRMTOP: prmtop, parm7
+- PSF: psf
+- TOP: top
+
+## Coordinates
+
+Need to be loaded together with a Structure or Topology.
+
+- DCD: dcd
+- NCTRAJ: nc, nctraj
+- TRR: trr
+- XTC: xtc
+
+
+## Volume
+
+- CCP4/MRC/MAP: ccp4, mrc, map
+- CUBE (may include a Structure): cub, cube
+- DSN6/BRIX: dsn6, brix
+- DX and DXBIN: dx, dxbin
+- DSCIF (DensityServer CIF schema): cif, bcif
+
+
+## Shape
+
+- PLY

docs/interesting-pdb-entries.md

@@ -13,6 +13,7 @@
     * DZ has C1 instead of N1 (e.g. 6I4N)
     * DP has N5 instead of C5 and C7 instead of N7 (e.g. 6I4N)
 * Beta & Gamma peptides (e.g. 1GAC, 6PQF)
+* Helices of D-amino acids (e.g. 7QDI)
 * Mixed (heterogeneous) all-atom/trace-only RNA model (1JGQ)
 * Polymers with residues with missing trace atoms (e.g. 2QFJ)
 * Modified RNA bases (1y26, 5L4O)
@@ -25,4 +26,25 @@
 * Non-standard residues
     * Protein (1BRR, 5Z6Y)
     * DNA (5D3G)
+    * Collagen (6JEC)
 * Multiple models with different sets of ligands or missing ligands (1J6T, 1VRC, 2ICY, 1O2F)
+* Long linear sugar chain (4HG6)
+* Anisotropic B-factors/Ellipsoids (1EJG)
+* NOS bridges (LYS-CSO in 7B0L, 6ZWJ, 6ZWH)
+* Non-polymer components in polymer entities
+    * PN2 in 1F80
+    * ACE (many, e.g. 5AGU, 1E1X)
+    * ACY in 7ABY
+    * NH2 (many, e.g. 6Y13)
+* Ligands with many rings
+    * STU (e.g. 1U59) - many fused rings
+    * HT (e.g. 127D) - rings connected by a single bond
+    * J2C (e.g. 7EFJ) - rings connected by a single atom
+    * RBF (e.g. 7QF2) - three linearly fused rings
+    * 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)

examples/ace2-hit.mol2

@@ -0,0 +1,86 @@
+@<TRIPOS>MOLECULE
+ace2_r_r2.top2000.poses.plain/3_Z1137565832_1_T2.pdb
+ 37 41 0 0 0
+SMALL
+GASTEIGER
+
+@<TRIPOS>ATOM
+      1  C         64.7720   85.9180   38.1090 C.3     1  LIG1        0.0799
+      2  C         64.6440   84.6900   37.1570 C.3     1  LIG1        0.0306
+      3  C         65.2660   83.4260   37.8080 C.3     1  LIG1        0.0927
+      4  N         66.6560   83.6710   38.1790 N.pl3   1  LIG1       -0.2919
+      5  C         67.7080   82.9280   37.6260 C.ar    1  LIG1        0.1520
+      6  C         69.0970   83.1860   37.8250 C.ar    1  LIG1        0.0393
+      7  C         70.0830   82.4100   37.1810 C.ar    1  LIG1        0.0436
+      8  C         69.6450   81.3740   36.3510 C.ar    1  LIG1        0.1867
+      9  N         70.3370   80.5030   35.6050 N.ar    1  LIG1       -0.1270
+     10  N         69.4700   79.7480   35.0040 N.ar    1  LIG1       -0.1228
+     11  C         68.2200   80.1120   35.3570 C.ar    1  LIG1        0.2583
+     12  N         68.3350   81.1470   36.2040 N.ar    1  LIG1       -0.1866
+     13  N         67.4230   81.8700   36.8030 N.ar    1  LIG1       -0.1473
+     14  C         66.8190   84.7600   39.1350 C.3     1  LIG1        0.0927
+     15  C         66.2560   86.0870   38.5570 C.3     1  LIG1        0.0306
+     16  N         64.4520   87.4670   36.2150 N.am    1  LIG1       -0.2979
+     17  H         64.9740   86.7650   35.7110 H       1  LIG1        0.1498
+     18  C         64.2290   87.1720   37.5220 C.2     1  LIG1        0.2224
+     19  O         63.5690   87.9550   38.2480 O.2     1  LIG1       -0.2751
+     20  C         64.0160   88.6470   35.5420 C.3     1  LIG1        0.1559
+     21  C         65.9650   88.2170   32.5700 C.ar    1  LIG1        0.1629
+     22  N         65.8040   88.0390   33.8860 N.ar    1  LIG1       -0.3232
+     23  H         66.4190   87.5270   34.5040 H       1  LIG1        0.1686
+     24  C         64.6770   88.6690   34.2330 C.ar    1  LIG1        0.1601
+     25  N         64.1890   89.2810   33.1430 N.ar    1  LIG1       -0.1318
+     26  N         64.9640   89.0070   32.1450 N.ar    1  LIG1       -0.1293
+     27  F         69.9260   86.0280   29.3520 F       1  LIG1       -0.2042
+     28  C         68.9880   86.5420   30.0990 C.ar    1  LIG1        0.1401
+     29  C         67.6590   86.0900   29.9830 C.ar    1  LIG1        0.0297
+     30  C         66.6500   86.6450   30.7950 C.ar    1  LIG1        0.0053
+     31  C         66.9590   87.6470   31.7450 C.ar    1  LIG1        0.0359
+     32  C         68.2970   88.0990   31.8400 C.ar    1  LIG1        0.0053
+     33  C         69.3030   87.5560   31.0230 C.ar    1  LIG1        0.0297
+     34  C         66.9850   79.4910   34.8440 C.3     1  LIG1        0.4541
+     35  F         67.3150   78.4110   34.0640 F       1  LIG1       -0.1631
+     36  F         66.2460   80.3690   34.0910 F       1  LIG1       -0.1631
+     37  F         66.1920   79.0650   35.8800 F       1  LIG1       -0.1631
+@<TRIPOS>BOND
+     1     1     2    1
+     2     1    18    1
+     3     1    15    1
+     4     2     3    1
+     5     3     4    1
+     6     4     5    1
+     7     4    14    1
+     8     5    13   ar
+     9     5     6   ar
+    10     6     7   ar
+    11     7     8   ar
+    12     8     9   ar
+    13     8    12   ar
+    14     9    10   ar
+    15    10    11   ar
+    16    11    34    1
+    17    11    12   ar
+    18    12    13   ar
+    19    14    15    1
+    20    16    20    1
+    21    16    17    1
+    22    16    18   am
+    23    18    19    2
+    24    20    24    1
+    25    21    31    1
+    26    21    26   ar
+    27    21    22   ar
+    28    22    24   ar
+    29    22    23    1
+    30    24    25   ar
+    31    25    26   ar
+    32    27    28    1
+    33    28    29   ar
+    34    28    33   ar
+    35    29    30   ar
+    36    30    31   ar
+    37    31    32   ar
+    38    32    33   ar
+    39    34    35    1
+    40    34    36    1
+    41    34    37    1

examples/mvs/1cbs-focus.mvsj

@@ -0,0 +1,115 @@
+{
+ "metadata": {
+  "title": "Example MolViewSpec - 1cbs with labelled and zoomed ligand",
+  "version": "1",
+  "timestamp": "2023-11-24T10:45:49.873Z"
+ },
+ "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": [
+       {
+        "kind": "structure",
+        "params": {
+         "type": "model"
+        },
+        "children": [
+         {
+          "kind": "component",
+          "params": {
+           "selector": "polymer"
+          },
+          "children": [
+           {
+            "kind": "representation",
+            "params": {
+             "type": "cartoon"
+            },
+            "children": [
+             {
+              "kind": "color",
+              "params": {
+               "color": "green"
+              }
+             },
+             {
+              "kind": "color",
+              "params": {
+               "selector": {
+                "label_asym_id": "A",
+                "end_label_seq_id": 50
+               },
+               "color": "#6688ff"
+              }
+             }
+            ]
+           },
+           {
+            "kind": "label",
+            "params": {
+             "text": "Protein"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": "ligand"
+          },
+          "children": [
+           {
+            "kind": "focus",
+            "params": {
+             "direction": [0.5, 0, -1],
+             "up": [0.365, 0.913, 0.183]
+            }
+           },
+           {
+            "kind": "representation",
+            "params": {
+             "type": "ball_and_stick"
+            },
+            "children": [
+             {
+              "kind": "color",
+              "params": {
+               "color": "#cc3399"
+              }
+             }
+            ]
+           },
+           {
+            "kind": "label",
+            "params": {
+             "text": "Retinoic Acid"
+            }
+           }
+          ]
+         }
+        ]
+       }
+      ]
+     }
+    ]
+   },
+   {
+    "kind": "canvas",
+    "params": {
+     "background_color": "#ffffee"
+    }
+   }
+  ]
+ }
+}

examples/mvs/1cbs.mvsj

@@ -0,0 +1,117 @@
+{
+ "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": [
+       {
+        "kind": "structure",
+        "params": {
+         "type": "model"
+        },
+        "children": [
+         {
+          "kind": "component",
+          "params": {
+           "selector": "polymer"
+          },
+          "children": [
+           {
+            "kind": "representation",
+            "params": {
+             "type": "cartoon"
+            },
+            "children": [
+             {
+              "kind": "color",
+              "params": {
+               "color": "green"
+              }
+             },
+             {
+              "kind": "color",
+              "params": {
+               "selector": {
+                "label_asym_id": "A",
+                "beg_label_seq_id": 1,
+                "end_label_seq_id": 50
+               },
+               "color": "#6688ff"
+              }
+             }
+            ]
+           },
+           {
+            "kind": "label",
+            "params": {
+             "text": "Protein"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": "ligand"
+          },
+          "children": [
+           {
+            "kind": "representation",
+            "params": {
+             "type": "ball_and_stick"
+            },
+            "children": [
+             {
+              "kind": "color",
+              "params": {
+               "color": "#cc3399"
+              }
+             }
+            ]
+           },
+           {
+            "kind": "label",
+            "params": {
+             "text": "Retinoic Acid"
+            }
+           }
+          ]
+         }
+        ]
+       }
+      ]
+     }
+    ]
+   },
+   {
+    "kind": "canvas",
+    "params": {
+     "background_color": "#ffffee"
+    }
+   },
+   {
+    "kind": "camera",
+    "params": {
+     "target": [17, 21, 27],
+     "position": [41, 34, 69],
+     "up": [-0.129,0.966,-0.224]
+    }
+   }
+  ]
+ }
+}

examples/mvs/1h9t_domain_colors.mvsj

@@ -0,0 +1,67 @@
+{
+ "metadata": {
+  "title": "Example MolViewSpec - 1h9t colored by external annotation",
+  "version": "1",
+  "timestamp": "2023-11-24T10:47:33.182Z"
+ },
+ "root": {
+  "kind": "root",
+  "children": [
+   {
+    "kind": "download",
+    "params": {
+     "url": "https://www.ebi.ac.uk/pdbe/entry-files/1h9t.bcif"
+    },
+    "children": [
+     {
+      "kind": "parse",
+      "params": {
+       "format": "bcif"
+      },
+      "children": [
+       {
+        "kind": "structure",
+        "params": {
+         "type": "model"
+        },
+        "children": [
+         {
+          "kind": "component",
+          "params": {
+           "selector": "polymer"
+          },
+          "children": [
+           {
+            "kind": "representation",
+            "params": {
+             "type": "cartoon"
+            },
+            "children": [
+             {
+              "kind": "color",
+              "params": {
+               "selector": "all",
+               "color": "white"
+              }
+             },
+             {
+              "kind": "color_from_uri",
+              "params": {
+               "uri": "./1h9t_domains.json",
+               "format": "json",
+               "schema": "all_atomic"
+              }
+             }
+            ]
+           }
+          ]
+         }
+        ]
+       }
+      ]
+     }
+    ]
+   }
+  ]
+ }
+}

examples/mvs/1h9t_domain_labels.mvsj

@@ -0,0 +1,583 @@
+{
+ "metadata": {
+  "title": "Example MolViewSpec - 1h9t colored and labelled by external annotation",
+  "version": "1",
+  "timestamp": "2023-11-24T10:48:28.677Z"
+ },
+ "root": {
+  "kind": "root",
+  "children": [
+   {
+    "kind": "download",
+    "params": {
+     "url": "https://www.ebi.ac.uk/pdbe/entry-files/1h9t.bcif"
+    },
+    "children": [
+     {
+      "kind": "parse",
+      "params": {
+       "format": "bcif"
+      },
+      "children": [
+       {
+        "kind": "structure",
+        "params": {
+         "type": "model"
+        },
+        "children": [
+         {
+          "kind": "component",
+          "params": {
+           "selector": "protein"
+          },
+          "children": [
+           {
+            "kind": "representation",
+            "params": {
+             "type": "cartoon"
+            },
+            "children": [
+             {
+              "kind": "color",
+              "params": {
+               "selector": "all",
+               "color": "white"
+              }
+             },
+             {
+              "kind": "color_from_uri",
+              "params": {
+               "uri": "./1h9t_domains.json",
+               "format": "json",
+               "schema": "all_atomic"
+              }
+             }
+            ]
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": "nucleic"
+          },
+          "children": [
+           {
+            "kind": "representation",
+            "params": {
+             "type": "ball_and_stick"
+            },
+            "children": [
+             {
+              "kind": "color",
+              "params": {
+               "selector": "all",
+               "color": "white"
+              }
+             },
+             {
+              "kind": "color_from_uri",
+              "params": {
+               "uri": "./1h9t_domains.json",
+               "format": "json",
+               "schema": "all_atomic"
+              }
+             }
+            ]
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": "ion"
+          },
+          "children": [
+           {
+            "kind": "representation",
+            "params": {
+             "type": "surface"
+            },
+            "children": [
+             {
+              "kind": "color_from_uri",
+              "params": {
+               "uri": "./1h9t_domains.json",
+               "format": "json",
+               "schema": "all_atomic"
+              }
+             }
+            ]
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "A",
+            "beg_label_seq_id": 9,
+            "end_label_seq_id": 83
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "DNA-binding"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "B",
+            "beg_label_seq_id": 9,
+            "end_label_seq_id": 83
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "DNA-binding"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "A",
+            "beg_label_seq_id": 84,
+            "end_label_seq_id": 231
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Acyl-CoA\nbinding"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "B",
+            "beg_label_seq_id": 84,
+            "end_label_seq_id": 231
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Acyl-CoA binding"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "C"
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "DNA X"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "D"
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "DNA Y"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "D",
+            "atom_id": 4016
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "DNA Y O5'"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "D",
+            "atom_id": 4391
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "DNA Y O3'"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "E"
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Gold"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "H"
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Gold"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "F"
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Chloride"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "G"
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Chloride"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "I"
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Chloride"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "A",
+            "label_seq_id": 57
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Ligand binding"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "A",
+            "label_seq_id": 67
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Ligand binding"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "A",
+            "label_seq_id": 121
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Ligand binding"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "A",
+            "label_seq_id": 125
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Ligand binding"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "A",
+            "label_seq_id": 129
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Ligand binding"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "A",
+            "label_seq_id": 178
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Ligand binding"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "A",
+            "beg_label_seq_id": 203,
+            "end_label_seq_id": 205
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Ligand binding"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "B",
+            "label_seq_id": 67
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Ligand binding"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "B",
+            "label_seq_id": 121
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Ligand binding"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "B",
+            "label_seq_id": 125
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Ligand binding"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "B",
+            "label_seq_id": 129
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Ligand binding"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "B",
+            "label_seq_id": 178
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Ligand binding"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": {
+            "label_asym_id": "B",
+            "beg_label_seq_id": 203,
+            "end_label_seq_id": 205
+           }
+          },
+          "children": [
+           {
+            "kind": "label",
+            "params": {
+             "text": "Ligand binding"
+            }
+           }
+          ]
+         },
+         {
+          "kind": "component",
+          "params": {
+           "selector": "all"
+          },
+          "children": [
+           {
+            "kind": "focus",
+            "params": {
+             "direction": [-0.3, -0.1, -1]
+            }
+           }
+          ]
+         }
+        ]
+       }
+      ]
+     }
+    ]
+   },
+   {
+    "kind": "canvas",
+    "params": {
+     "background_color": "#eeffee"
+    }
+   }
+  ]
+ }
+}

examples/mvs/1h9t_domains.json

@@ -0,0 +1,155 @@
+[
+    {
+        "label_asym_id": "A",
+        "beg_label_seq_id": 9,
+        "end_label_seq_id": 83,
+        "color": "#dd6600",
+        "tooltip": "DNA-binding"
+    },
+    {
+        "label_asym_id": "A",
+        "beg_label_seq_id": 84,
+        "end_label_seq_id": 231,
+        "color": "#008800",
+        "tooltip": "Acyl-CoA binding"
+    },
+    {
+        "label_asym_id": "B",
+        "beg_label_seq_id": 9,
+        "end_label_seq_id": 83,
+        "color": "#cc8800",
+        "tooltip": "DNA-binding"
+    },
+    {
+        "label_asym_id": "B",
+        "beg_label_seq_id": 84,
+        "end_label_seq_id": 231,
+        "color": "#008888",
+        "tooltip": "Acyl-CoA binding"
+    },
+    {
+        "label_asym_id": "C",
+        "color": "#1100aa",
+        "tooltip": "DNA X"
+    },
+    {
+        "label_asym_id": "D",
+        "color": "#dddddd",
+        "tooltip": "DNA Y"
+    },
+    {
+        "label_asym_id": "D",
+        "atom_id": 4016,
+        "color": "#ff0044",
+        "tooltip": "DNA Y - O5'"
+    },
+    {
+        "label_asym_id": "D",
+        "atom_id": 4391,
+        "color": "#4400ff",
+        "tooltip": "DNA Y - O3'"
+    },
+    
+
+    {
+        "label_asym_id": "E",
+        "color": "#ffff00",
+        "tooltip": "Gold"
+    },
+    {
+        "label_asym_id": "H",
+        "color": "#ffff00",
+        "tooltip": "Gold"
+    },
+    {
+        "label_asym_id": "F",
+        "color": "#00dd00",
+        "tooltip": "Chloride"
+    },
+    {
+        "label_asym_id": "G",
+        "color": "#00dd00",
+        "tooltip": "Chloride"
+    },
+    {
+        "label_asym_id": "I",
+        "color": "#00dd00",
+        "tooltip": "Chloride"
+    },
+
+    {
+        "label_asym_id": "A",
+        "label_seq_id": 57,
+        "color": "#ff0000",
+        "tooltip": "Ligand binding site"
+    },
+    {
+        "label_asym_id": "A",
+        "label_seq_id": 67,
+        "color": "#ff0000",
+        "tooltip": "Ligand binding site"
+    },
+    {
+        "label_asym_id": "A",
+        "label_seq_id": 121,
+        "color": "#ff0000",
+        "tooltip": "Ligand binding site"
+    },
+    {
+        "label_asym_id": "A",
+        "label_seq_id": 125,
+        "color": "#ff0000",
+        "tooltip": "Ligand binding site"
+    },
+    {
+        "label_asym_id": "A",
+        "label_seq_id": 129,
+        "color": "#ff0000",
+        "tooltip": "Ligand binding site"
+    },
+    {
+        "label_asym_id": "A",
+        "label_seq_id": 178,
+        "color": "#ff0000",
+        "tooltip": "Ligand binding site"
+    },
+    {
+        "label_asym_id": "A",
+        "beg_label_seq_id": 203,
+        "end_label_seq_id": 205,
+        "color": "#ff0000",
+        "tooltip": "Ligand binding site"
+    },
+
+    {
+        "label_asym_id": "B",
+        "label_seq_id": 67,
+        "color": "#ff0000",
+        "tooltip": "Ligand binding site"
+    },
+    {
+        "label_asym_id": "B",
+        "label_seq_id": 121,
+        "color": "#ff0000",
+        "tooltip": "Ligand binding site"
+    },
+    {
+        "label_asym_id": "B",
+        "label_seq_id": 125,
+        "color": "#ff0000",
+        "tooltip": "Ligand binding site"
+    },
+    {
+        "label_asym_id": "B",
+        "label_seq_id": 129,
+        "color": "#ff0000",
+        "tooltip": "Ligand binding site"
+    },
+    {
+        "label_asym_id": "B",
+        "beg_label_seq_id": 203,
+        "end_label_seq_id": 205,
+        "color": "#ff0000",
+        "tooltip": "Ligand binding site"
+    }
+]

package.json

@@ -1,6 +1,6 @@
 {
   "name": "molstar",
-  "version": "2.0.0-dev.3",
+  "version": "4.1.0",
   "description": "A comprehensive macromolecular library.",
   "homepage": "https://github.com/molstar/molstar#readme",
   "repository": {
@@ -13,11 +13,14 @@
   "scripts": {
     "lint": "eslint .",
     "lint-fix": "eslint . --fix",
-    "test": "npm run lint && jest",
+    "test": "npm install --no-save \"gl@^6.0.2\" && npm run lint && jest",
+    "jest": "jest",
     "build": "npm run build-tsc && npm run build-extra && npm run build-webpack",
+    "clean": "node ./scripts/clean.js",
+    "rebuild": "npm run clean && npm run build",
     "build-viewer": "npm run build-tsc && npm run build-extra && npm run build-webpack-viewer",
     "build-tsc": "concurrently \"tsc --incremental\" \"tsc --build tsconfig.commonjs.json --incremental\"",
-    "build-extra": "cpx \"src/**/*.{scss,html,ico}\" lib/",
+    "build-extra": "cpx \"src/**/*.{scss,html,ico,jpg}\" lib/",
     "build-webpack": "webpack --mode production --config ./webpack.config.production.js",
     "build-webpack-viewer": "webpack --mode production --config ./webpack.config.viewer.js",
     "watch": "concurrently -c \"green,green,gray,gray\" --names \"tsc,srv,ext,wpc\" --kill-others \"npm:watch-tsc\" \"npm:watch-servers\" \"npm:watch-extra\" \"npm:watch-webpack\"",
@@ -25,17 +28,17 @@
     "watch-viewer-debug": "concurrently -c \"green,gray,gray\" --names \"tsc,ext,wpc\" --kill-others \"npm:watch-tsc\" \"npm:watch-extra\" \"npm:watch-webpack-viewer-debug\"",
     "watch-tsc": "tsc --watch --incremental",
     "watch-servers": "tsc --build tsconfig.commonjs.json --watch --incremental",
-    "watch-extra": "cpx \"src/**/*.{scss,html,ico}\" lib/ --watch",
-    "watch-webpack": "webpack -w --mode development --display minimal",
-    "watch-webpack-viewer": "webpack -w --mode development --display errors-only --info-verbosity verbose --config ./webpack.config.viewer.js",
-    "watch-webpack-viewer-debug": "webpack -w --mode development --display errors-only --info-verbosity verbose --config ./webpack.config.viewer.debug.js",
+    "watch-extra": "cpx \"src/**/*.{scss,html,ico,jpg}\" lib/ --watch",
+    "watch-webpack": "webpack -w --mode development --stats minimal",
+    "watch-webpack-viewer": "webpack -w --mode development --stats minimal --config ./webpack.config.viewer.js",
+    "watch-webpack-viewer-debug": "webpack -w --mode development --stats minimal --config ./webpack.config.viewer.debug.js",
     "serve": "http-server -p 1338 -g",
     "model-server": "node lib/commonjs/servers/model/server.js",
     "model-server-watch": "nodemon --watch lib lib/commonjs/servers/model/server.js",
     "volume-server-test": "node lib/commonjs/servers/volume/server.js --idMap em 'test/${id}.mdb' --defaultPort 1336",
     "plugin-state": "node lib/commonjs/servers/plugin-state/index.js --working-folder ./build/state --port 1339",
     "preversion": "npm run test",
-    "version": "npm run build",
+    "version": "npm run rebuild && cpx .npmignore lib/",
     "postversion": "git push && git push --tags"
   },
   "files": [
@@ -45,6 +48,9 @@
   "bin": {
     "cif2bcif": "lib/commonjs/cli/cif2bcif/index.js",
     "cifschema": "lib/commonjs/cli/cifschema/index.js",
+    "mvs-validate": "lib/commonjs/cli/mvs/mvs-validate.js",
+    "mvs-render": "lib/commonjs/cli/mvs/mvs-render.js",
+    "mvs-print-schema": "lib/commonjs/cli/mvs/mvs-print-schema.js",
     "model-server": "lib/commonjs/servers/model/server.js",
     "model-server-query": "lib/commonjs/servers/model/query.js",
     "model-server-preprocess": "lib/commonjs/servers/model/preprocess.js",
@@ -72,7 +78,9 @@
       "node_modules",
       "lib"
     ],
-    "testURL": "http://localhost/",
+    "testEnvironmentOptions": {
+      "url": "http://localhost/"
+    },
     "testRegex": "\\.spec\\.ts$"
   },
   "author": "Mol* Contributors",
@@ -83,69 +91,104 @@
     "Áron Samuel Kovács <aron.kovacs@mail.muni.cz>",
     "Ludovic Autin <autin@scripps.edu>",
     "Michal Malý <michal.maly@ibt.cas.cz>",
-    "Jiří Černý <jiri.cerny@ibt.cas.cz>"
+    "Jiří Černý <jiri.cerny@ibt.cas.cz>",
+    "Panagiotis Tourlas <panagiot_tourlov@hotmail.com>",
+    "Adam Midlik <midlik@gmail.com>",
+    "Koya Sakuma <koya.sakuma.work@gmail.com>",
+    "Gianluca Tomasello <giagitom@gmail.com>",
+    "Ke Ma <mark.ma@rcsb.org>",
+    "Jason Pattle <jpattle@exscientia.co.uk>",
+    "David Williams <dwilliams@nobiastx.com>",
+    "Zhenyu Zhang <jump2cn@gmail.com>",
+    "Russell Parker <russell@benchling.com>",
+    "Dominik Tichy <tichydominik451@gmail.com>",
+    "Yana Rose <yana.v.rose@gmail.com>",
+    "Yakov Pechersky <ffxen158@gmail.com>",
+    "Christian Dominguez <christian.99dominguez@gmail.com>",
+    "Cai Huiyu <szmun.caihy@gmail.com>"
   ],
   "license": "MIT",
   "devDependencies": {
-    "@graphql-codegen/add": "^2.0.2",
-    "@graphql-codegen/cli": "^1.19.4",
-    "@graphql-codegen/time": "^2.0.2",
-    "@graphql-codegen/typescript": "^1.19.0",
-    "@graphql-codegen/typescript-graphql-files-modules": "^1.18.1",
-    "@graphql-codegen/typescript-graphql-request": "^2.0.3",
-    "@graphql-codegen/typescript-operations": "^1.17.12",
-    "@types/cors": "^2.8.8",
-    "@typescript-eslint/eslint-plugin": "^4.9.1",
-    "@typescript-eslint/parser": "^4.9.1",
+    "@types/cors": "^2.8.17",
+    "@types/gl": "^6.0.5",
+    "@types/pngjs": "^6.0.4",
+    "@types/jest": "^29.5.12",
+    "@types/react": "^18.2.73",
+    "@types/react-dom": "^18.2.23",
+    "@typescript-eslint/eslint-plugin": "^7.4.0",
+    "@typescript-eslint/parser": "^7.4.0",
     "benchmark": "^2.1.4",
-    "concurrently": "^5.3.0",
-    "cpx2": "^3.0.0",
-    "css-loader": "^5.0.1",
-    "eslint": "^7.15.0",
+    "concurrently": "^8.2.2",
+    "cpx2": "^7.0.1",
+    "crypto-browserify": "^3.12.0",
+    "css-loader": "^6.10.0",
+    "eslint": "^8.57.0",
     "extra-watch-webpack-plugin": "^1.0.3",
     "file-loader": "^6.2.0",
-    "fs-extra": "^9.0.1",
-    "graphql": "^15.4.0",
-    "http-server": "^0.12.3",
-    "jest": "^26.6.3",
-    "mini-css-extract-plugin": "^1.3.2",
-    "node-sass": "^5.0.0",
+    "fs-extra": "^11.2.0",
+    "http-server": "^14.1.1",
+    "jest": "^29.7.0",
+    "jpeg-js": "^0.4.4",
+    "mini-css-extract-plugin": "^2.8.1",
+    "path-browserify": "^1.0.1",
     "raw-loader": "^4.0.2",
-    "sass-loader": "^10.1.0",
-    "simple-git": "^2.25.0",
-    "style-loader": "^2.0.0",
-    "ts-jest": "^26.4.4",
-    "typescript": "^4.1.2",
-    "webpack": "^4.44.1",
-    "webpack-cli": "^3.3.12",
-    "webpack-version-file-plugin": "^0.4.0"
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "sass": "^1.72.0",
+    "sass-loader": "^14.1.1",
+    "simple-git": "^3.24.0",
+    "stream-browserify": "^3.0.0",
+    "style-loader": "^3.3.4",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.4.3",
+    "webpack": "^5.91.0",
+    "webpack-cli": "^5.1.4"
   },
   "dependencies": {
-    "@types/argparse": "^1.0.38",
-    "@types/benchmark": "^2.1.0",
-    "@types/compression": "1.7.0",
-    "@types/express": "^4.17.9",
-    "@types/jest": "^26.0.18",
-    "@types/node": "^14.14.11",
-    "@types/node-fetch": "^2.5.7",
-    "@types/react": "^17.0.0",
-    "@types/react-dom": "^17.0.0",
-    "@types/swagger-ui-dist": "3.30.0",
-    "argparse": "^1.0.10",
-    "body-parser": "^1.19.0",
+    "@types/argparse": "^2.0.16",
+    "@types/benchmark": "^2.1.5",
+    "@types/compression": "1.7.5",
+    "@types/express": "^4.17.21",
+    "@types/node": "^18.19.28",
+    "@types/node-fetch": "^2.6.11",
+    "@types/swagger-ui-dist": "3.30.4",
+    "argparse": "^2.0.1",
+    "body-parser": "^1.20.2",
     "compression": "^1.7.4",
     "cors": "^2.8.5",
-    "express": "^4.17.1",
+    "express": "^4.19.2",
     "h264-mp4-encoder": "^1.0.12",
-    "immer": "^8.0.0",
-    "immutable": "^3.8.2",
-    "node-fetch": "^2.6.1",
-    "react": "^17.0.1",
-    "react-dom": "^17.0.1",
-    "rxjs": "^6.6.3",
-    "swagger-ui-dist": "^3.37.2",
-    "tslib": "^2.0.3",
-    "util.promisify": "^1.0.1",
-    "xhr2": "^0.2.0"
+    "immer": "^10.0.4",
+    "immutable": "^4.3.5",
+    "io-ts": "^2.2.21",
+    "node-fetch": "^2.7.0",
+    "react-markdown": "^9.0.1",
+    "rxjs": "^7.8.1",
+    "swagger-ui-dist": "^5.13.0",
+    "tslib": "^2.6.2",
+    "util.promisify": "^1.1.2",
+    "xhr2": "^0.2.1"
+  },
+  "peerDependencies": {
+    "canvas": "^2.11.2",
+    "gl": "^6.0.2",
+    "jpeg-js": "^0.4.4",
+    "pngjs": "^6.0.0",
+    "react": "^18.1.0 || ^17.0.2 || ^16.14.0",
+    "react-dom": "^18.1.0 || ^17.0.2 || ^16.14.0"
+  },
+  "peerDependenciesMeta": {
+    "canvas": {
+      "optional": true
+    },
+    "gl": {
+      "optional": true
+    },
+    "jpeg-js": {
+      "optional": true
+    },
+    "pngjs": {
+      "optional": true
+    }
   }
 }

scripts/clean.js

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2021 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Michal Malý <malym@ibt.cas.cz>
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function removeDir(dirPath) {
+    for (const ent of fs.readdirSync(dirPath)) {
+        const entryPath = path.join(dirPath, ent);
+        remove(entryPath);
+    }
+
+    fs.rmdirSync(dirPath);
+}
+
+function remove(entryPath) {
+    const st = fs.statSync(entryPath);
+    if (st.isDirectory())
+        removeDir(entryPath);
+    else
+        fs.unlinkSync(entryPath);
+}
+
+const toClean = [
+    path.resolve(__dirname, '../build'),
+    path.resolve(__dirname, '../lib'),
+    path.resolve(__dirname, '../tsconfig.tsbuildinfo'),
+];
+
+toClean.forEach(ph => {
+    if (fs.existsSync(ph)) {
+        try {
+            remove(ph);
+        } catch (err) {
+            console.warn(`Cleanup failed: ${err}`);
+        }
+    }
+});

scripts/deploy.js

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2019 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>
  */
@@ -14,6 +14,9 @@ const buildDir = path.resolve(__dirname, '../build/');
 const deployDir = path.resolve(buildDir, 'deploy/');
 const localPath = path.resolve(deployDir, 'molstar.github.io/');
 
+const analyticsTag = /<!-- __MOLSTAR_ANALYTICS__ -->/g;
+const analyticsCode = `<!-- Cloudflare Web Analytics --><script defer src='https://static.cloudflareinsights.com/beacon.min.js' data-cf-beacon='{"token": "c414cbae2d284ea995171a81e4a3e721"}'></script><!-- End Cloudflare Web Analytics --><iframe src="https://web3dsurvey.com/collector-iframe.html" style="width: 1px; height: 1px;"></iframe>`;
+
 function log(command, stdout, stderr) {
     if (command) {
         console.log('\n###', command);
@@ -22,11 +25,45 @@ function log(command, stdout, stderr) {
     }
 }
 
+function addAnalytics(path) {
+    const data = fs.readFileSync(path, 'utf8');
+    const result = data.replace(analyticsTag, analyticsCode);
+    fs.writeFileSync(path, result, 'utf8');
+}
+
 function copyViewer() {
     console.log('\n###', 'copy viewer files');
     const viewerBuildPath = path.resolve(buildDir, '../build/viewer/');
     const viewerDeployPath = path.resolve(localPath, 'viewer/');
     fse.copySync(viewerBuildPath, viewerDeployPath, { overwrite: true });
+    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/');
+    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/');
+    const lightingDeployPath = path.resolve(localPath, 'demos/lighting/');
+    fse.copySync(lightingBuildPath, lightingDeployPath, { overwrite: true });
+    addAnalytics(path.resolve(lightingDeployPath, 'index.html'));
+
+    const orbitalsBuildPath = path.resolve(buildDir, '../build/examples/alpha-orbitals/');
+    const orbitalsDeployPath = path.resolve(localPath, 'demos/alpha-orbitals/');
+    fse.copySync(orbitalsBuildPath, orbitalsDeployPath, { overwrite: true });
+    addAnalytics(path.resolve(orbitalsDeployPath, 'index.html'));
+}
+
+function copyFiles() {
+    copyViewer();
+    copyMe();
+    copyDemos();
 }
 
 if (!fs.existsSync(localPath)) {
@@ -42,9 +79,9 @@ if (!fs.existsSync(path.resolve(localPath, '.git/'))) {
         .outputHandler(log)
         .clone(remoteUrl, localPath)
         .fetch(['--all'])
-        .exec(copyViewer)
+        .exec(copyFiles)
         .add(['-A'])
-        .commit('updated viewer')
+        .commit('updated viewer & demos')
         .push();
 } else {
     console.log('\n###', 'update repository');
@@ -52,8 +89,8 @@ if (!fs.existsSync(path.resolve(localPath, '.git/'))) {
         .outputHandler(log)
         .fetch(['--all'])
         .reset(['--hard', 'origin/master'])
-        .exec(copyViewer)
+        .exec(copyFiles)
         .add(['-A'])
-        .commit('updated viewer')
+        .commit('updated viewer & demos')
         .push();
 }

src/apps/docking-viewer/index.html

@@ -19,19 +19,19 @@
         <div id="app"></div>
         <script type="text/javascript" src="./molstar.js"></script>
         <script type="text/javascript">
-            var viewer = new DockingViewer('app', [0x33DD22, 0x1133EE], true);
-
             function getParam(name, regex) {
                 var r = new RegExp(name + '=' + '(' + regex + ')[&]?', 'i');
                 return decodeURIComponent(((window.location.search || '').match(r) || [])[1] || '');
             }
-            var pdbqt = getParam('pdbqt', '[^&]+').trim();
-            var mol2 = getParam('mol2', '[^&]+').trim();
+            var pdbqt = getParam('pdbqt', '[^&]+').trim() || '../../examples/ace2.pdbqt';
+            var mol2 = getParam('mol2', '[^&]+').trim() || '../../examples/ace2-hit.mol2';
 
-            viewer.loadStructuresFromUrlsAndMerge([
-                { url: pdbqt, format: 'pdbqt' },
-                { url: mol2, format: 'mol2' }
-            ]);
+            DockingViewer.create('app', [0x33DD22, 0x1133EE], true).then(viewer => {
+                viewer.loadStructuresFromUrlsAndMerge([
+                    { url: pdbqt, format: 'pdbqt' },
+                    { url: mol2, format: 'mol2' }
+                ]);
+            });
         </script>
     </body>
 </html>

src/apps/docking-viewer/index.ts

@@ -5,31 +5,33 @@
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
 
-import '../../mol-util/polyfill';
-import { createPlugin } from '../../mol-plugin';
-import { DefaultPluginSpec } from '../../mol-plugin/spec';
-import './index.html';
-import { PluginContext } from '../../mol-plugin/context';
-import { PluginCommands } from '../../mol-plugin/commands';
-import { PluginSpec } from '../../mol-plugin/spec';
-import { PluginConfig } from '../../mol-plugin/config';
-import { ObjectKeys } from '../../mol-util/type-helpers';
-import { PluginLayoutControlsDisplay } from '../../mol-plugin/layout';
-import { BuiltInTrajectoryFormat } from '../../mol-plugin-state/formats/trajectory';
 import { Structure } from '../../mol-model/structure';
-import { PluginStateTransform, PluginStateObject as PSO } from '../../mol-plugin-state/objects';
-import { ParamDefinition as PD } from '../../mol-util/param-definition';
-import { Task } from '../../mol-task';
-import { StateObject } from '../../mol-state';
-import { ViewportComponent, StructurePreset, ShowButtons } from './viewport';
+import { BuiltInTrajectoryFormat } from '../../mol-plugin-state/formats/trajectory';
+import { PluginStateObject as PSO, PluginStateTransform } from '../../mol-plugin-state/objects';
+import { createPluginUI } from '../../mol-plugin-ui';
+import { renderReact18 } from '../../mol-plugin-ui/react18';
+import { PluginUIContext } from '../../mol-plugin-ui/context';
+import { PluginLayoutControlsDisplay } from '../../mol-plugin/layout';
+import { DefaultPluginUISpec, PluginUISpec } from '../../mol-plugin-ui/spec';
 import { PluginBehaviors } from '../../mol-plugin/behavior';
-import { ColorNames } from '../../mol-util/color/names';
+import { PluginCommands } from '../../mol-plugin/commands';
+import { PluginConfig } from '../../mol-plugin/config';
+import { PluginSpec } from '../../mol-plugin/spec';
+import { StateObject } from '../../mol-state';
+import { Task } from '../../mol-task';
 import { Color } from '../../mol-util/color';
+import { ColorNames } from '../../mol-util/color/names';
+import { ParamDefinition as PD } from '../../mol-util/param-definition';
+import '../../mol-util/polyfill';
+import { ObjectKeys } from '../../mol-util/type-helpers';
+import './index.html';
+import { ShowButtons, StructurePreset, ViewportComponent } from './viewport';
 
 require('mol-plugin-ui/skin/light.scss');
 
 export { PLUGIN_VERSION as version } from '../../mol-plugin/version';
-export { setProductionMode, setDebugMode } from '../../mol-util/debug';
+export { setDebugMode, setProductionMode } from '../../mol-util/debug';
+export { Viewer as DockingViewer };
 
 const DefaultViewerOptions = {
     extensions: ObjectKeys({}),
@@ -53,27 +55,30 @@ const DefaultViewerOptions = {
 };
 
 class Viewer {
-    plugin: PluginContext
+    constructor(public plugin: PluginUIContext) {
+    }
 
-    constructor(elementOrId: string | HTMLElement, colors = [Color(0x992211), Color(0xDDDDDD)], showButtons = true) {
-        const o = { ...DefaultViewerOptions, ...{
-            layoutIsExpanded: false,
-            layoutShowControls: false,
-            layoutShowRemoteState: false,
-            layoutShowSequence: true,
-            layoutShowLog: false,
-            layoutShowLeftPanel: true,
+    static async create(elementOrId: string | HTMLElement, colors = [Color(0x992211), Color(0xDDDDDD)], showButtons = true) {
+        const o = {
+            ...DefaultViewerOptions, ...{
+                layoutIsExpanded: false,
+                layoutShowControls: false,
+                layoutShowRemoteState: false,
+                layoutShowSequence: true,
+                layoutShowLog: false,
+                layoutShowLeftPanel: true,
 
-            viewportShowExpand: true,
-            viewportShowControls: false,
-            viewportShowSettings: false,
-            viewportShowSelectionMode: false,
-            viewportShowAnimation: false,
-        } };
-        const defaultSpec = DefaultPluginSpec();
+                viewportShowExpand: true,
+                viewportShowControls: false,
+                viewportShowSettings: false,
+                viewportShowSelectionMode: false,
+                viewportShowAnimation: false,
+            }
+        };
+        const defaultSpec = DefaultPluginUISpec();
 
-        const spec: PluginSpec = {
-            actions: [...defaultSpec.actions],
+        const spec: PluginUISpec = {
+            actions: defaultSpec.actions,
             behaviors: [
                 PluginSpec.Behavior(PluginBehaviors.Representation.HighlightLoci, { mark: false }),
                 PluginSpec.Behavior(PluginBehaviors.Representation.DefaultLociLabelProvider),
@@ -83,7 +88,7 @@ class Viewer {
                 PluginSpec.Behavior(PluginBehaviors.CustomProps.Interactions),
                 PluginSpec.Behavior(PluginBehaviors.CustomProps.SecondaryStructure),
             ],
-            animations: [...defaultSpec.animations || []],
+            animations: defaultSpec.animations,
             customParamEditors: defaultSpec.customParamEditors,
             layout: {
                 initial: {
@@ -91,15 +96,15 @@ class Viewer {
                     showControls: o.layoutShowControls,
                     controlsDisplay: o.layoutControlsDisplay,
                 },
-                controls: {
-                    ...defaultSpec.layout && defaultSpec.layout.controls,
-                    top: o.layoutShowSequence ? undefined : 'none',
-                    bottom: o.layoutShowLog ? undefined : 'none',
-                    left: o.layoutShowLeftPanel ? undefined : 'none',
-                }
             },
             components: {
                 ...defaultSpec.components,
+                controls: {
+                    ...defaultSpec.components?.controls,
+                    top: o.layoutShowSequence ? undefined : 'none',
+                    bottom: o.layoutShowLog ? undefined : 'none',
+                    left: o.layoutShowLeftPanel ? undefined : 'none',
+                },
                 remoteState: o.layoutShowRemoteState ? 'default' : 'none',
                 viewport: {
                     view: ViewportComponent
@@ -124,29 +129,29 @@ class Viewer {
             ? document.getElementById(elementOrId)
             : elementOrId;
         if (!element) throw new Error(`Could not get element with id '${elementOrId}'`);
-        this.plugin = createPlugin(element, spec);
+        const plugin = await createPluginUI({ target: element, spec, render: renderReact18 });
 
-        (this.plugin.customState as any) = {
+        (plugin.customState as any) = {
             colorPalette: {
                 name: 'colors',
                 params: { list: { colors } }
             }
         };
 
-        this.plugin.behaviors.canvas3d.initialized.subscribe(v => {
-            if (v) {
-                PluginCommands.Canvas3D.SetSettings(this.plugin, { settings: {
-                    renderer: {
-                        ...this.plugin.canvas3d!.props.renderer,
-                        backgroundColor: ColorNames.white,
-                    },
-                    camera: {
-                        ...this.plugin.canvas3d!.props.camera,
-                        helper: { axes: { name: 'off', params: {} } }
-                    }
-                } });
+        PluginCommands.Canvas3D.SetSettings(plugin, {
+            settings: {
+                renderer: {
+                    ...plugin.canvas3d!.props.renderer,
+                    backgroundColor: ColorNames.white,
+                },
+                camera: {
+                    ...plugin.canvas3d!.props.camera,
+                    helper: { axes: { name: 'off', params: {} } }
+                }
             }
         });
+
+        return new Viewer(plugin);
     }
 
     async loadStructuresFromUrlsAndMerge(sources: { url: string, format: BuiltInTrajectoryFormat, isBinary?: boolean }[]) {
@@ -162,7 +167,7 @@ class Viewer {
             structures.push({ ref: structureProperties?.ref || structure.ref });
         }
 
-        // remove current structuresfrom hierarchy as they will be merged
+        // remove current structures from hierarchy as they will be merged
         // TODO only works with using loadStructuresFromUrlsAndMerge once
         //      need some more API metho to work with the hierarchy
         this.plugin.managers.structure.hierarchy.updateCurrent(this.plugin.managers.structure.hierarchy.current.structures, 'remove');
@@ -210,4 +215,3 @@ const MergeStructures = PluginStateTransform.BuiltIn({
 });
 
 (window as any).DockingViewer = Viewer;
-export { Viewer as DockingViewer };

src/apps/docking-viewer/viewport.tsx

@@ -1,38 +1,38 @@
 /**
- * Copyright (c) 2020 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2020-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
 
-import * as React from 'react';
-import { PluginUIComponent } from '../../mol-plugin-ui/base';
-import { Viewport, ViewportControls } from '../../mol-plugin-ui/viewport';
-import { BackgroundTaskProgress } from '../../mol-plugin-ui/task';
-import { LociLabels } from '../../mol-plugin-ui/controls';
-import { Toasts } from '../../mol-plugin-ui/toast';
-import { Button } from '../../mol-plugin-ui/controls/common';
-import { StructureRepresentationPresetProvider, presetStaticComponent } from '../../mol-plugin-state/builder/structure/representation-preset';
-import { StateObjectRef } from '../../mol-state';
-import { StructureSelectionQueries, StructureSelectionQuery } from '../../mol-plugin-state/helpers/structure-selection-query';
-import { MolScriptBuilder as MS } from '../../mol-script/language/builder';
 import { InteractionsRepresentationProvider } from '../../mol-model-props/computed/representations/interactions';
 import { InteractionTypeColorThemeProvider } from '../../mol-model-props/computed/themes/interaction-type';
-import { PluginCommands } from '../../mol-plugin/commands';
-import { PluginContext } from '../../mol-plugin/context';
+import { presetStaticComponent, StructureRepresentationPresetProvider } from '../../mol-plugin-state/builder/structure/representation-preset';
+import { StructureSelectionQueries, StructureSelectionQuery } from '../../mol-plugin-state/helpers/structure-selection-query';
 import { StructureRef } from '../../mol-plugin-state/manager/structure/hierarchy-state';
-import { Color } from '../../mol-util/color';
+import { PluginUIComponent } from '../../mol-plugin-ui/base';
+import { LociLabels } from '../../mol-plugin-ui/controls';
+import { Button } from '../../mol-plugin-ui/controls/common';
+import { BackgroundTaskProgress } from '../../mol-plugin-ui/task';
+import { Toasts } from '../../mol-plugin-ui/toast';
+import { Viewport, ViewportControls } from '../../mol-plugin-ui/viewport';
+import { PluginCommands } from '../../mol-plugin/commands';
 import { PluginConfig } from '../../mol-plugin/config';
+import { PluginContext } from '../../mol-plugin/context';
+import { MolScriptBuilder as MS } from '../../mol-script/language/builder';
+import { StateObjectRef } from '../../mol-state';
+import { Color } from '../../mol-util/color';
+import { Material } from '../../mol-util/material';
 
 function shinyStyle(plugin: PluginContext) {
     return PluginCommands.Canvas3D.SetSettings(plugin, { settings: {
         renderer: {
             ...plugin.canvas3d!.props.renderer,
-            style: { name: 'plastic', params: {} },
         },
         postprocessing: {
             ...plugin.canvas3d!.props.postprocessing,
             occlusion: { name: 'off', params: {} },
-            outline: { name: 'off', params: {} }
+            shadow: { name: 'off', params: {} },
+            outline: { name: 'off', params: {} },
         }
     } });
 }
@@ -41,20 +41,25 @@ function occlusionStyle(plugin: PluginContext) {
     return PluginCommands.Canvas3D.SetSettings(plugin, { settings: {
         renderer: {
             ...plugin.canvas3d!.props.renderer,
-            style: { name: 'flat', params: {} }
         },
         postprocessing: {
             ...plugin.canvas3d!.props.postprocessing,
             occlusion: { name: 'on', params: {
-                samples: 64,
-                radius: 8,
-                bias: 1.0,
-                blurKernelSize: 13
+                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
-            } }
+                threshold: 0.33,
+                color: Color(0x0000),
+                includeTransparent: true,
+            } },
+            shadow: { name: 'off', params: {} },
         }
     } });
 }
@@ -78,7 +83,7 @@ const PresetParams = {
     ...StructureRepresentationPresetProvider.CommonParams,
 };
 
-
+const CustomMaterial = Material({ roughness: 0.2, metalness: 0 });
 
 export const StructurePreset = StructureRepresentationPresetProvider({
     id: 'preset-structure',
@@ -95,8 +100,8 @@ export const StructurePreset = StructureRepresentationPresetProvider({
 
         const { update, builder, typeParams } = StructureRepresentationPresetProvider.reprBuilder(plugin, params);
         const representations = {
-            ligand: builder.buildRepresentation(update, components.ligand, { type: 'ball-and-stick', typeParams: { ...typeParams, sizeFactor: 0.35 }, color: 'element-symbol', colorParams: { carbonColor: { name: 'element-symbol', params: {} } } }, { tag: 'ligand' }),
-            polymer: builder.buildRepresentation(update, components.polymer, { type: 'cartoon', typeParams: { ...typeParams }, color: 'chain-id', colorParams: { palette: (plugin.customState as any).colorPalette } }, { tag: 'polymer' }),
+            ligand: builder.buildRepresentation(update, components.ligand, { type: 'ball-and-stick', typeParams: { ...typeParams, material: CustomMaterial, sizeFactor: 0.35 }, color: 'element-symbol', colorParams: { carbonColor: { name: 'element-symbol', params: {} } } }, { tag: 'ligand' }),
+            polymer: builder.buildRepresentation(update, components.polymer, { type: 'cartoon', typeParams: { ...typeParams, material: CustomMaterial }, color: 'chain-id', colorParams: { palette: (plugin.customState as any).colorPalette } }, { tag: 'polymer' }),
         };
 
         await update.commit({ revertOnError: true });
@@ -122,8 +127,8 @@ export const IllustrativePreset = StructureRepresentationPresetProvider({
 
         const { update, builder, typeParams } = StructureRepresentationPresetProvider.reprBuilder(plugin, params);
         const representations = {
-            ligand: builder.buildRepresentation(update, components.ligand, { type: 'spacefill', typeParams: { ...typeParams }, color: 'element-symbol', colorParams: { carbonColor: { name: 'element-symbol', params: {} } } }, { tag: 'ligand' }),
-            polymer: builder.buildRepresentation(update, components.polymer, { type: 'spacefill', typeParams: { ...typeParams }, color: 'illustrative', colorParams: { palette: (plugin.customState as any).colorPalette } }, { tag: 'polymer' }),
+            ligand: builder.buildRepresentation(update, components.ligand, { type: 'spacefill', typeParams: { ...typeParams, ignoreLight: true }, color: 'element-symbol', colorParams: { carbonColor: { name: 'element-symbol', params: {} } } }, { tag: 'ligand' }),
+            polymer: builder.buildRepresentation(update, components.polymer, { type: 'spacefill', typeParams: { ...typeParams, ignoreLight: true }, color: 'illustrative', colorParams: { palette: (plugin.customState as any).colorPalette } }, { tag: 'polymer' }),
         };
 
         await update.commit({ revertOnError: true });
@@ -150,8 +155,8 @@ const SurfacePreset = StructureRepresentationPresetProvider({
 
         const { update, builder, typeParams } = StructureRepresentationPresetProvider.reprBuilder(plugin, params);
         const representations = {
-            ligand: builder.buildRepresentation(update, components.ligand, { type: 'ball-and-stick', typeParams: { ...typeParams, sizeFactor: 0.26 }, color: 'element-symbol', colorParams: { carbonColor: { name: 'element-symbol', params: {} } } }, { tag: 'ligand' }),
-            polymer: builder.buildRepresentation(update, components.polymer, { type: 'molecular-surface', typeParams: { ...typeParams, quality: 'custom', resolution: 0.5, doubleSided: true }, color: 'partial-charge' }, { tag: 'polymer' }),
+            ligand: builder.buildRepresentation(update, components.ligand, { type: 'ball-and-stick', typeParams: { ...typeParams, material: CustomMaterial, sizeFactor: 0.26 }, color: 'element-symbol', colorParams: { carbonColor: { name: 'element-symbol', params: {} } } }, { tag: 'ligand' }),
+            polymer: builder.buildRepresentation(update, components.polymer, { type: 'molecular-surface', typeParams: { ...typeParams, material: CustomMaterial, quality: 'custom', resolution: 0.5, doubleSided: true }, color: 'partial-charge' }, { tag: 'polymer' }),
         };
 
         await update.commit({ revertOnError: true });
@@ -178,8 +183,8 @@ const PocketPreset = StructureRepresentationPresetProvider({
 
         const { update, builder, typeParams } = StructureRepresentationPresetProvider.reprBuilder(plugin, params);
         const representations = {
-            ligand: builder.buildRepresentation(update, components.ligand, { type: 'ball-and-stick', typeParams: { ...typeParams, sizeFactor: 0.26 }, color: 'element-symbol', colorParams: { carbonColor: { name: 'element-symbol', params: {} } } }, { tag: 'ligand' }),
-            surroundings: builder.buildRepresentation(update, components.surroundings, { type: 'molecular-surface', typeParams: { ...typeParams, includeParent: true, quality: 'custom', resolution: 0.2, doubleSided: true }, color: 'partial-charge' }, { tag: 'surroundings' }),
+            ligand: builder.buildRepresentation(update, components.ligand, { type: 'ball-and-stick', typeParams: { ...typeParams, material: CustomMaterial, sizeFactor: 0.26 }, color: 'element-symbol', colorParams: { carbonColor: { name: 'element-symbol', params: {} } } }, { tag: 'ligand' }),
+            surroundings: builder.buildRepresentation(update, components.surroundings, { type: 'molecular-surface', typeParams: { ...typeParams, material: CustomMaterial, includeParent: true, quality: 'custom', resolution: 0.2, doubleSided: true }, color: 'partial-charge' }, { tag: 'surroundings' }),
         };
 
         await update.commit({ revertOnError: true });
@@ -202,15 +207,15 @@ const InteractionsPreset = StructureRepresentationPresetProvider({
         const components = {
             ligand: await presetStaticComponent(plugin, structureCell, 'ligand'),
             surroundings: await plugin.builders.structure.tryCreateComponentFromSelection(structureCell, ligandSurroundings, `surroundings`),
-            interactions: await plugin.builders.structure.tryCreateComponentFromSelection(structureCell, ligandPlusSurroundings, `interactions`)
+            interactions: await presetStaticComponent(plugin, structureCell, 'ligand'),
         };
 
         const { update, builder, typeParams } = StructureRepresentationPresetProvider.reprBuilder(plugin, params);
         const representations = {
-            ligand: builder.buildRepresentation(update, components.ligand, { type: 'ball-and-stick', typeParams: { ...typeParams, sizeFactor: 0.3 }, color: 'element-symbol', colorParams: { carbonColor: { name: 'element-symbol', params: {} } } }, { tag: 'ligand' }),
-            ballAndStick: builder.buildRepresentation(update, components.surroundings, { type: 'ball-and-stick', typeParams: { ...typeParams, sizeFactor: 0.1, sizeAspectRatio: 1 }, color: 'element-symbol', colorParams: { carbonColor: { name: 'element-symbol', params: {} } } }, { tag: 'ball-and-stick' }),
-            interactions: builder.buildRepresentation(update, components.interactions, { type: InteractionsRepresentationProvider, typeParams: { ...typeParams }, color: InteractionTypeColorThemeProvider }, { tag: 'interactions' }),
-            label: builder.buildRepresentation(update, components.surroundings, { type: 'label', typeParams: { ...typeParams, background: false, borderWidth: 0.1 }, color: 'uniform', colorParams: { value: Color(0x000000) } }, { tag: 'label' }),
+            ligand: builder.buildRepresentation(update, components.ligand, { type: 'ball-and-stick', typeParams: { ...typeParams, material: CustomMaterial, sizeFactor: 0.3 }, color: 'element-symbol', colorParams: { carbonColor: { name: 'element-symbol', params: {} } } }, { tag: 'ligand' }),
+            ballAndStick: builder.buildRepresentation(update, components.surroundings, { type: 'ball-and-stick', typeParams: { ...typeParams, material: CustomMaterial, sizeFactor: 0.1, sizeAspectRatio: 1 }, color: 'element-symbol', colorParams: { carbonColor: { name: 'element-symbol', params: {} } } }, { tag: 'ball-and-stick' }),
+            interactions: builder.buildRepresentation(update, components.interactions, { type: InteractionsRepresentationProvider, typeParams: { ...typeParams, material: CustomMaterial, includeParent: true, parentDisplay: 'between' }, color: InteractionTypeColorThemeProvider }, { tag: 'interactions' }),
+            label: builder.buildRepresentation(update, components.surroundings, { type: 'label', typeParams: { ...typeParams, material: CustomMaterial, background: false, borderWidth: 0.1 }, color: 'uniform', colorParams: { value: Color(0x000000) } }, { tag: 'label' }),
         };
 
         await update.commit({ revertOnError: true });
@@ -231,7 +236,7 @@ export class ViewportComponent extends PluginUIComponent {
 
     set = async (preset: StructureRepresentationPresetProvider) => {
         await this._set(this.plugin.managers.structure.hierarchy.selection.structures, preset);
-    }
+    };
 
     structurePreset = () => this.set(StructurePreset);
     illustrativePreset = () => this.set(IllustrativePreset);
@@ -239,7 +244,7 @@ export class ViewportComponent extends PluginUIComponent {
     pocketPreset = () => this.set(PocketPreset);
     interactionsPreset = () => this.set(InteractionsPreset);
 
-    get showButtons () {
+    get showButtons() {
         return this.plugin.config.get(ShowButtons);
     }
 

src/apps/mesoscale-explorer/app.ts

@@ -0,0 +1,280 @@
+/**
+ * Copyright (c) 2022-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ */
+
+import { Mp4Export } from '../../extensions/mp4-export';
+import { DataFormatProvider } from '../../mol-plugin-state/formats/provider';
+import { createPluginUI } from '../../mol-plugin-ui';
+import { renderReact18 } from '../../mol-plugin-ui/react18';
+import { PluginUIContext } from '../../mol-plugin-ui/context';
+import { DefaultPluginUISpec, PluginUISpec } from '../../mol-plugin-ui/spec';
+import { PluginConfig } from '../../mol-plugin/config';
+import { PluginLayoutControlsDisplay } from '../../mol-plugin/layout';
+import { PluginSpec } from '../../mol-plugin/spec';
+import '../../mol-util/polyfill';
+import { ObjectKeys } from '../../mol-util/type-helpers';
+import { SaccharideCompIdMapType } from '../../mol-model/structure/structure/carbohydrates/constants';
+import { Backgrounds } from '../../extensions/backgrounds';
+import { LeftPanel, RightPanel } from './ui/panels';
+import { Color } from '../../mol-util/color';
+import { SpacefillRepresentationProvider } from '../../mol-repr/structure/representation/spacefill';
+import { PluginBehaviors } from '../../mol-plugin/behavior';
+import { MesoFocusLoci } from './behavior/camera';
+import { GraphicsMode, MesoscaleState } from './data/state';
+import { MesoSelectLoci } from './behavior/select';
+import { Transparency } from '../../mol-gl/webgl/render-item';
+import { LoadModel, loadExampleEntry, loadPdb, loadPdbDev, loadUrl, openState } from './ui/states';
+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';
+
+export { PLUGIN_VERSION as version } from '../../mol-plugin/version';
+export { setDebugMode, setProductionMode, setTimingMode, consoleStats } from '../../mol-util/debug';
+
+export type ExampleEntry = {
+    id: string,
+    label: string,
+    url: string,
+    type: 'molx' | 'molj' | 'cif' | 'bcif',
+    description?: string,
+    link?: string,
+}
+
+export type MesoscaleExplorerState = {
+    examples?: ExampleEntry[],
+    graphicsMode: GraphicsMode,
+    stateRef?: string,
+    stateCache: { [k: string]: any },
+}
+
+//
+
+const Extensions = {
+    'backgrounds': PluginSpec.Behavior(Backgrounds),
+    'mp4-export': PluginSpec.Behavior(Mp4Export),
+};
+
+const DefaultMesoscaleExplorerOptions = {
+    customFormats: [] as [string, DataFormatProvider][],
+    extensions: ObjectKeys(Extensions),
+    layoutIsExpanded: true,
+    layoutShowControls: true,
+    layoutShowRemoteState: true,
+    layoutControlsDisplay: 'reactive' as PluginLayoutControlsDisplay,
+    layoutShowSequence: true,
+    layoutShowLog: true,
+    layoutShowLeftPanel: true,
+    collapseLeftPanel: false,
+    collapseRightPanel: false,
+    disableAntialiasing: PluginConfig.General.DisableAntialiasing.defaultValue,
+    pixelScale: PluginConfig.General.PixelScale.defaultValue,
+    pickScale: PluginConfig.General.PickScale.defaultValue,
+    transparency: 'blended' as Transparency,
+    preferWebgl1: PluginConfig.General.PreferWebGl1.defaultValue,
+    allowMajorPerformanceCaveat: PluginConfig.General.AllowMajorPerformanceCaveat.defaultValue,
+    powerPreference: PluginConfig.General.PowerPreference.defaultValue,
+
+    viewportShowExpand: PluginConfig.Viewport.ShowExpand.defaultValue,
+    viewportShowControls: PluginConfig.Viewport.ShowControls.defaultValue,
+    viewportShowSettings: PluginConfig.Viewport.ShowSettings.defaultValue,
+    viewportShowSelectionMode: false,
+    viewportShowAnimation: false,
+    viewportShowTrajectoryControls: false,
+    pluginStateServer: PluginConfig.State.DefaultServer.defaultValue,
+    volumeStreamingServer: PluginConfig.VolumeStreaming.DefaultServer.defaultValue,
+    volumeStreamingDisabled: !PluginConfig.VolumeStreaming.Enabled.defaultValue,
+    pdbProvider: PluginConfig.Download.DefaultPdbProvider.defaultValue,
+    emdbProvider: PluginConfig.Download.DefaultEmdbProvider.defaultValue,
+    saccharideCompIdMapType: 'default' as SaccharideCompIdMapType,
+
+    graphicsMode: 'quality' as GraphicsMode
+};
+type MesoscaleExplorerOptions = typeof DefaultMesoscaleExplorerOptions;
+
+export class MesoscaleExplorer {
+    constructor(public plugin: PluginUIContext) {
+    }
+
+    async loadExample(id: string) {
+        const entries = (this.plugin.customState as MesoscaleExplorerState).examples || [];
+        const entry = entries.find(e => e.id === id);
+        if (entry !== undefined) {
+            await loadExampleEntry(this.plugin, entry);
+        }
+    }
+
+    async loadUrl(url: string, type: 'molx' | 'molj' | 'cif' | 'bcif') {
+        await loadUrl(this.plugin, url, type);
+    }
+
+    async loadPdb(id: string) {
+        await loadPdb(this.plugin, id);
+    }
+
+    async loadPdbDev(id: string) {
+        await loadPdbDev(this.plugin, id);
+    }
+
+    static async create(elementOrId: string | HTMLElement, options: Partial<MesoscaleExplorerOptions> = {}) {
+        const definedOptions = {} as any;
+        // filter for defined properies only so the default values
+        // are property applied
+        for (const p of Object.keys(options) as (keyof MesoscaleExplorerOptions)[]) {
+            if (options[p] !== void 0) definedOptions[p] = options[p];
+        }
+
+        const o: MesoscaleExplorerOptions = { ...DefaultMesoscaleExplorerOptions, ...definedOptions };
+        const defaultSpec = DefaultPluginUISpec();
+
+        const spec: PluginUISpec = {
+            actions: defaultSpec.actions,
+            behaviors: [
+                PluginSpec.Behavior(PluginBehaviors.Camera.CameraAxisHelper),
+                PluginSpec.Behavior(PluginBehaviors.Camera.CameraControls),
+
+                PluginSpec.Behavior(MesoFocusLoci),
+                PluginSpec.Behavior(MesoSelectLoci),
+
+                ...o.extensions.map(e => Extensions[e]),
+            ],
+            animations: [
+                AnimateCameraSpin,
+                AnimateCameraRock,
+                AnimateStateSnapshots,
+            ],
+            customParamEditors: defaultSpec.customParamEditors,
+            customFormats: o?.customFormats,
+            layout: {
+                initial: {
+                    isExpanded: o.layoutIsExpanded,
+                    showControls: o.layoutShowControls,
+                    controlsDisplay: o.layoutControlsDisplay,
+                    regionState: {
+                        bottom: 'full',
+                        left: o.collapseLeftPanel ? 'collapsed' : 'full',
+                        right: o.collapseRightPanel ? 'hidden' : 'full',
+                        top: 'full',
+                    }
+                },
+            },
+            components: {
+                ...defaultSpec.components,
+                controls: {
+                    ...defaultSpec.components?.controls,
+                    top: 'none',
+                    bottom: 'none',
+                    left: LeftPanel,
+                    right: RightPanel,
+                },
+                remoteState: 'none',
+            },
+            config: [
+                [PluginConfig.General.DisableAntialiasing, o.disableAntialiasing],
+                [PluginConfig.General.PixelScale, o.pixelScale],
+                [PluginConfig.General.PickScale, o.pickScale],
+                [PluginConfig.General.Transparency, o.transparency],
+                [PluginConfig.General.PreferWebGl1, o.preferWebgl1],
+                [PluginConfig.General.AllowMajorPerformanceCaveat, o.allowMajorPerformanceCaveat],
+                [PluginConfig.General.PowerPreference, o.powerPreference],
+                [PluginConfig.Viewport.ShowExpand, o.viewportShowExpand],
+                [PluginConfig.Viewport.ShowControls, o.viewportShowControls],
+                [PluginConfig.Viewport.ShowSettings, o.viewportShowSettings],
+                [PluginConfig.Viewport.ShowSelectionMode, o.viewportShowSelectionMode],
+                [PluginConfig.Viewport.ShowAnimation, o.viewportShowAnimation],
+                [PluginConfig.Viewport.ShowTrajectoryControls, o.viewportShowTrajectoryControls],
+                [PluginConfig.State.DefaultServer, o.pluginStateServer],
+                [PluginConfig.State.CurrentServer, o.pluginStateServer],
+                [PluginConfig.VolumeStreaming.DefaultServer, o.volumeStreamingServer],
+                [PluginConfig.VolumeStreaming.Enabled, !o.volumeStreamingDisabled],
+                [PluginConfig.Download.DefaultPdbProvider, o.pdbProvider],
+                [PluginConfig.Download.DefaultEmdbProvider, o.emdbProvider],
+                [PluginConfig.Structure.SaccharideCompIdMapType, o.saccharideCompIdMapType],
+            ]
+        };
+
+        const element = typeof elementOrId === 'string'
+            ? document.getElementById(elementOrId)
+            : elementOrId;
+        if (!element) throw new Error(`Could not get element with id '${elementOrId}'`);
+
+        const plugin = await createPluginUI({
+            target: element,
+            spec,
+            render: renderReact18,
+            onBeforeUIRender: async plugin => {
+                let examples: MesoscaleExplorerState['examples'] = undefined;
+                try {
+                    examples = await plugin.fetch({ url: './examples/list.json', type: 'json' }).run();
+                } catch (e) {
+                    console.log(e);
+                }
+
+                (plugin.customState as MesoscaleExplorerState) = {
+                    examples,
+                    graphicsMode: o.graphicsMode,
+                    stateCache: {},
+                };
+
+                await MesoscaleState.init(plugin);
+            }
+        });
+
+        plugin.canvas3d?.setProps({
+            renderer: {
+                backgroundColor: Color(0x101010),
+            },
+            cameraFog: { name: 'off', params: {} },
+            hiZ: { enabled: true },
+        });
+
+        plugin.representation.structure.registry.clear();
+        plugin.representation.structure.registry.add(SpacefillRepresentationProvider);
+
+        plugin.state.setSnapshotParams({
+            image: true,
+            componentManager: false,
+            structureSelection: true,
+            behavior: true,
+        });
+
+        plugin.managers.lociLabels.clearProviders();
+
+        plugin.managers.dragAndDrop.addHandler('mesoscale-explorer', (files) => {
+            const sessions = files.filter(f => {
+                const fn = f.name.toLowerCase();
+                return fn.endsWith('.molx') || fn.endsWith('.molj');
+            });
+
+            if (sessions.length > 0) {
+                openState(plugin, sessions[0]);
+            } else {
+                plugin.runTask(plugin.state.data.applyAction(LoadModel, {
+                    files: files.map(f => Asset.File(f)),
+                }));
+            }
+
+            return true;
+        });
+
+        plugin.state.events.object.created.subscribe(e => {
+            (plugin.customState as MesoscaleExplorerState).stateCache = {};
+        });
+
+        plugin.state.events.object.removed.subscribe(e => {
+            (plugin.customState as MesoscaleExplorerState).stateCache = {};
+        });
+
+        return new MesoscaleExplorer(plugin);
+    }
+
+    handleResize() {
+        this.plugin.layout.events.updated.next(void 0);
+    }
+
+    dispose() {
+        this.plugin.dispose();
+    }
+}

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

@@ -0,0 +1,75 @@
+/**
+ * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ */
+
+import { Loci } from '../../../mol-model/loci';
+import { ParamDefinition as PD } from '../../../mol-util/param-definition';
+import { PluginBehavior } from '../../../mol-plugin/behavior';
+import { ButtonsType, ModifiersKeys } from '../../../mol-util/input/input-observer';
+import { Binding } from '../../../mol-util/binding';
+import { PluginCommands } from '../../../mol-plugin/commands';
+import { Sphere3D } from '../../../mol-math/geometry';
+
+const B = ButtonsType;
+const M = ModifiersKeys;
+const Trigger = Binding.Trigger;
+
+const DefaultMesoFocusLociBindings = {
+    clickCenter: Binding([
+        Trigger(B.Flag.Primary, M.create()),
+    ], 'Camera center', 'Click element using ${triggers}'),
+    clickCenterFocus: Binding([
+        Trigger(B.Flag.Secondary, M.create()),
+    ], 'Camera center and focus', 'Click element using ${triggers}'),
+};
+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>
+
+export const MesoFocusLoci = PluginBehavior.create<MesoFocusLociProps>({
+    name: 'camera-meso-focus-loci',
+    category: 'interaction',
+    ctor: class extends PluginBehavior.Handler<MesoFocusLociProps> {
+        register(): void {
+            this.subscribeObservable(this.ctx.behaviors.interaction.click, ({ current, button, modifiers }) => {
+                const { canvas3d } = this.ctx;
+                if (!canvas3d) return;
+
+                const loci = Loci.normalize(current.loci, this.ctx.managers.interactivity.props.granularity);
+                const sphere = Loci.getBoundingSphere(loci) || Sphere3D();
+
+                const { clickCenter, clickCenterFocus } = this.params.bindings;
+                const { durationMs, extraRadius, minRadius } = this.params;
+                const radius = Math.max(sphere.radius + extraRadius, minRadius);
+
+                if (Binding.match(clickCenter, button, modifiers)) {
+                    if (Loci.isEmpty(current.loci)) {
+                        PluginCommands.Camera.Reset(this.ctx, { });
+                        return;
+                    }
+
+                    const snapshot = canvas3d.camera.getCenter(sphere.center);
+                    canvas3d.requestCameraReset({ durationMs, snapshot });
+                } else if (Binding.match(clickCenterFocus, button, modifiers)) {
+                    if (Loci.isEmpty(current.loci)) {
+                        PluginCommands.Camera.Reset(this.ctx, { });
+                        return;
+                    }
+
+                    const snapshot = canvas3d.camera.getCenter(sphere.center, radius);
+                    canvas3d.requestCameraReset({ durationMs, snapshot });
+                }
+            });
+        }
+    },
+    params: () => MesoFocusLociParams,
+    display: { name: 'Camera Meso Focus Loci on Canvas' }
+});

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

@@ -0,0 +1,164 @@
+/**
+ * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ */
+
+import { EveryLoci, Loci } from '../../../mol-model/loci';
+import { ParamDefinition as PD } from '../../../mol-util/param-definition';
+import { PluginBehavior } from '../../../mol-plugin/behavior';
+import { ButtonsType, ModifiersKeys } from '../../../mol-util/input/input-observer';
+import { Binding } from '../../../mol-util/binding';
+import { PluginStateObject as SO } from '../../../mol-plugin-state/objects';
+import { Structure, StructureElement } from '../../../mol-model/structure';
+import { StateSelection } from '../../../mol-state';
+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';
+
+const B = ButtonsType;
+const M = ModifiersKeys;
+const Trigger = Binding.Trigger;
+
+const DefaultMesoSelectLociBindings = {
+    clickToggleSelect: Binding([
+        Trigger(B.Flag.Primary, M.create({ shift: true })),
+        Trigger(B.Flag.Primary, M.create({ control: true })),
+    ], 'Toggle select', 'Click element using ${triggers}'),
+    hoverHighlightOnly: Binding([
+        Trigger(B.Flag.None, M.create({ shift: true })),
+        Trigger(B.Flag.None, M.create({ control: true })),
+    ], 'Highlight', 'Hover element using ${triggers}'),
+};
+const MesoSelectLociParams = {
+    bindings: PD.Value(DefaultMesoSelectLociBindings, { isHidden: true }),
+};
+type MesoSelectLociProps = PD.Values<typeof MesoSelectLociParams>
+
+export const MesoSelectLoci = PluginBehavior.create<MesoSelectLociProps>({
+    name: 'camera-meso-select-loci',
+    category: 'interaction',
+    ctor: class extends PluginBehavior.Handler<MesoSelectLociProps> {
+        private spine: StateTreeSpine.Impl;
+        private lociMarkProvider = (interactionLoci: Representation.Loci, action: MarkerAction) => {
+            if (!this.ctx.canvas3d) return;
+            this.ctx.canvas3d.mark(interactionLoci, action);
+        };
+        private applySelectMark(ref: string, clear?: boolean) {
+            const cell = this.ctx.state.data.cells.get(ref);
+            if (cell && SO.isRepresentation3D(cell.obj)) {
+                this.spine.current = cell;
+                const so = this.spine.getRootOfType(SO.Molecule.Structure);
+                if (so) {
+                    if (clear) {
+                        this.lociMarkProvider({ loci: Structure.Loci(so.data) }, MarkerAction.Deselect);
+                    }
+                    const loci = this.ctx.managers.structure.selection.getLoci(so.data);
+                    this.lociMarkProvider({ loci }, MarkerAction.Select);
+                }
+            }
+        }
+        register(): void {
+            this.subscribeObservable(this.ctx.behaviors.interaction.click, ({ current, button, modifiers }) => {
+                if (!this.ctx.canvas3d || this.ctx.isBusy) return;
+
+                const { 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);
+                }
+            });
+            this.ctx.managers.interactivity.lociSelects.addProvider(this.lociMarkProvider);
+
+            this.subscribeObservable(this.ctx.behaviors.interaction.hover, ({ current, button, modifiers }) => {
+                if (!this.ctx.canvas3d || this.ctx.isBusy) return;
+
+                const pointerLock = !!this.ctx.canvas3dContext?.input.pointerLock;
+                const { hoverHighlightOnly } = this.params.bindings;
+
+                if (!pointerLock && Binding.match(hoverHighlightOnly, button, modifiers)) {
+                    if (Loci.isEmpty(current.loci)) {
+                        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 (Loci.isEmpty(current.loci)) {
+                    this.ctx.behaviors.labels.highlight.next({ labels: [] });
+                } 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');
+                    }
+                    this.ctx.behaviors.labels.highlight.next({ labels });
+                }
+            });
+            this.ctx.managers.interactivity.lociHighlights.addProvider(this.lociMarkProvider);
+
+            let dimDisabled = false;
+
+            this.subscribeObservable(this.ctx.behaviors.interaction.keyReleased, ({ code, modifiers }) => {
+                if (!this.ctx.canvas3d) return;
+
+                if ((code.startsWith('Shift') && !modifiers.control) || (code.startsWith('Control') && !modifiers.shift)) {
+                    if (dimDisabled) {
+                        dimDisabled = false;
+                        this.ctx.canvas3d?.setProps({ renderer: { dimStrength: 1 } }, true);
+                    }
+                    this.ctx.managers.interactivity.lociHighlights.clearHighlights();
+                }
+            });
+
+            this.subscribeObservable(this.ctx.behaviors.interaction.key, ({ modifiers }) => {
+                if (!this.ctx.canvas3d) return;
+
+                if (!dimDisabled && modifiers.control && modifiers.shift) {
+                    dimDisabled = true;
+                    this.ctx.canvas3d?.setProps({ renderer: { dimStrength: 0 } });
+                }
+            });
+
+            this.subscribeObservable(this.ctx.state.events.object.created, ({ ref }) => this.applySelectMark(ref));
+
+            // re-apply select-mark to all representation of an updated structure
+            this.subscribeObservable(this.ctx.state.events.object.updated, ({ ref, obj, oldObj, oldData, action }) => {
+                const cell = this.ctx.state.data.cells.get(ref);
+                if (cell && SO.Molecule.Structure.is(cell.obj)) {
+                    const structure: Structure = obj.data;
+                    const oldStructure: Structure | undefined = action === 'recreate' ? oldObj?.data :
+                        action === 'in-place' ? oldData : undefined;
+                    if (oldStructure &&
+                        Structure.areEquivalent(structure, oldStructure) &&
+                        Structure.areHierarchiesEqual(structure, oldStructure)) return;
+
+                    const reprs = this.ctx.state.data.select(StateSelection.children(ref).ofType(SO.Molecule.Structure.Representation3D));
+                    for (const repr of reprs) this.applySelectMark(repr.transform.ref, true);
+                }
+            });
+        }
+        unregister() {
+            this.ctx.managers.interactivity.lociSelects.removeProvider(this.lociMarkProvider);
+            this.ctx.managers.interactivity.lociHighlights.removeProvider(this.lociMarkProvider);
+        }
+        constructor(ctx: PluginContext, params: MesoSelectLociProps) {
+            super(ctx, params);
+            this.spine = new StateTreeSpine.Impl(ctx.state.data.cells);
+        }
+    },
+    params: () => MesoSelectLociParams,
+    display: { name: 'Camera Meso Select Loci on Canvas' }
+});

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

@@ -0,0 +1,178 @@
+/**
+ * Copyright (c) 2019-2023 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>
+ * @author David Sehnal <david.sehnal@gmail.com>
+ */
+
+import { SortedArray } from '../../../../mol-data/int';
+import { SymmetryOperator } from '../../../../mol-math/geometry';
+import { Mat4 } from '../../../../mol-math/linear-algebra';
+import { ModelSymmetry } from '../../../../mol-model-formats/structure/property/symmetry';
+import { CustomStructureProperty } from '../../../../mol-model-props/common/custom-structure-property';
+import { ElementIndex, EntityIndex, Model, Structure, Unit } from '../../../../mol-model/structure';
+import { Assembly, Symmetry } from '../../../../mol-model/structure/model/properties/symmetry';
+import { PluginStateObject as PSO, PluginStateTransform } from '../../../../mol-plugin-state/objects';
+import { PluginContext } from '../../../../mol-plugin/context';
+import { Task } from '../../../../mol-task';
+import { ParamDefinition as PD } from '../../../../mol-util/param-definition';
+
+function createModelChainMap(model: Model) {
+    const builder = new Structure.StructureBuilder();
+    const units = new Map<string, Unit>();
+
+    const { label_asym_id, _rowCount } = model.atomicHierarchy.chains;
+    const { offsets } = model.atomicHierarchy.chainAtomSegments;
+
+    for (let i = 0; i < _rowCount; i++) {
+        const elements = SortedArray.ofBounds(offsets[i] as ElementIndex, offsets[i + 1] as ElementIndex);
+        const unit = builder.addUnit(Unit.Kind.Atomic, model, SymmetryOperator.Default, elements, Unit.Trait.FastBoundary);
+        units.set(label_asym_id.value(i), unit);
+    }
+
+    return units;
+}
+
+function buildCellpackAssembly(model: Model, assembly: Assembly) {
+    const coordinateSystem = SymmetryOperator.create(assembly.id, Mat4.identity(), { assembly: { id: assembly.id, operId: 0, operList: [] } });
+    const assembler = Structure.Builder({
+        coordinateSystem,
+        label: model.label,
+    });
+
+    const units = createModelChainMap(model);
+
+    for (const g of assembly.operatorGroups) {
+        for (const oper of g.operators) {
+            for (const id of g.asymIds!) {
+                const u = units.get(id);
+                if (u) {
+                    assembler.addWithOperator(u, oper);
+                } else {
+                    console.log(`missing asymId '${id}'`);
+                }
+            }
+        }
+    }
+
+    return assembler.getStructure();
+}
+
+export { CellpackAssembly };
+type CellpackAssembly = typeof CellpackAssembly
+const CellpackAssembly = PluginStateTransform.BuiltIn({
+    name: 'cellpack-assembly',
+    display: { name: 'Cellpack Assembly' },
+    from: PSO.Molecule.Model,
+    to: PSO.Molecule.Structure,
+    params: {
+        id: PD.Text('', { label: 'Asm Id', description: 'Assembly Id (use empty for the 1st assembly)' }),
+    }
+})({
+    canAutoUpdate({ newParams }) {
+        return true;
+    },
+    apply({ a, params }, plugin: PluginContext) {
+        return Task.create('Build Structure', async ctx => {
+            const model = a.data;
+
+            let id = params.id;
+            let asm: Assembly | undefined = void 0;
+            const symmetry = ModelSymmetry.Provider.get(model);
+
+            // if no id is specified, use the 1st assembly.
+            if (!id && symmetry && symmetry.assemblies.length !== 0) {
+                id = symmetry.assemblies[0].id;
+            }
+
+            if (!symmetry || symmetry.assemblies.length === 0) {
+                plugin.log.warn(`Model '${model.entryId}' has no assembly, returning model structure.`);
+            } else {
+                asm = Symmetry.findAssembly(model, id || '');
+                if (!asm) {
+                    plugin.log.warn(`Model '${model.entryId}' has no assembly called '${id}', returning model structure.`);
+                }
+            }
+
+            const base = Structure.ofModel(model);
+            if (!asm) {
+                const label = { label: 'Model', description: Structure.elementDescription(base) };
+                return new PSO.Molecule.Structure(base, label);
+            }
+
+            const s = buildCellpackAssembly(model, asm);
+
+            const objProps = { label: `Assembly ${id}`, description: Structure.elementDescription(s) };
+            return new PSO.Molecule.Structure(s, objProps);
+        });
+    },
+    dispose({ b }) {
+        b?.data.customPropertyDescriptors.dispose();
+    }
+});
+
+type UnitsByEntity = Map<EntityIndex, Unit[]>;
+const UnitsByEntity = CustomStructureProperty.createSimple<UnitsByEntity>('units_by_entity', 'root');
+
+function getUnitsByEntity(structure: Structure): UnitsByEntity {
+    if (UnitsByEntity.get(structure).value) {
+        return UnitsByEntity.get(structure).value!;
+    }
+
+    const atomicIndex = structure.model.atomicHierarchy.index;
+    const map: UnitsByEntity = new Map();
+    for (const ug of structure.unitSymmetryGroups) {
+        const u = ug.units[0] as Unit.Atomic;
+        const e = atomicIndex.getEntityFromChain(u.chainIndex[u.elements[0]]);
+
+        if (!map.has(e)) map.set(e, []);
+        const entityUnits = map.get(e)!;
+
+        for (let i = 0, il = ug.units.length; i < il; ++i) {
+            entityUnits.push(ug.units[i]);
+        }
+    }
+
+    UnitsByEntity.set(structure, { value: map }, map);
+    return map;
+}
+
+export { CellpackStructure };
+type CellpackStructure = typeof CellpackStructure
+const CellpackStructure = PluginStateTransform.BuiltIn({
+    name: 'cellpack-structure',
+    display: { name: 'Cellpack Structure' },
+    from: PSO.Root,
+    to: PSO.Molecule.Structure,
+    params: {
+        structureRef: PD.Text(''),
+        entityId: PD.Text('')
+    }
+})({
+    canAutoUpdate({ newParams }) {
+        return true;
+    },
+    apply({ a, params, dependencies }) {
+        return Task.create('Build Structure', async ctx => {
+            const parent = dependencies![params.structureRef].data as Structure;
+            const { entities } = parent.model;
+            const idx = entities.getEntityIndex(params.entityId);
+
+            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}` });
+        });
+    },
+    dispose({ b }) {
+        b?.data.customPropertyDescriptors.dispose();
+    }
+});

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

@@ -0,0 +1,227 @@
+/**
+ * Copyright (c) 2019-2023 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>
+ */
+
+import { PluginStateObject } from '../../../../mol-plugin-state/objects';
+import { StructureRepresentation3D } from '../../../../mol-plugin-state/transforms/representation';
+import { PluginContext } from '../../../../mol-plugin/context';
+import { SpacefillRepresentationProvider } from '../../../../mol-repr/structure/representation/spacefill';
+import { StateObjectRef, StateObjectSelector, StateBuilder } from '../../../../mol-state';
+import { Color } from '../../../../mol-util/color';
+import { ColorNames } from '../../../../mol-util/color/names';
+import { GraphicsMode, MesoscaleGroup, MesoscaleState, getDistinctBaseColors, getDistinctGroupColors, getGraphicsModeProps, getMesoscaleGroupParams } from '../state';
+import { CellpackAssembly, CellpackStructure } from './model';
+
+function getSpacefillParams(color: Color, sizeFactor: number, graphics: GraphicsMode, merge?: boolean) {
+    const gmp = getGraphicsModeProps(graphics === 'custom' ? 'quality' : graphics);
+    return {
+        type: {
+            name: 'spacefill',
+            params: {
+                ...SpacefillRepresentationProvider.defaultValues,
+                ignoreHydrogens: false,
+                instanceGranularity: true,
+                ignoreLight: true,
+                lodLevels: gmp.lodLevels,
+                quality: 'lowest', // avoid 'auto', triggers boundary calc
+                sizeFactor,
+                clip: {
+                    variant: merge ? 'pixel' : 'instance',
+                    objects: [],
+                },
+                clipPrimitive: true,
+                approximate: gmp.approximate,
+                alphaThickness: gmp.alphaThickness,
+                visuals: [merge ? 'structure-element-sphere' : 'element-sphere'],
+            },
+        },
+        colorTheme: {
+            name: 'uniform',
+            params: {
+                value: color,
+                saturation: 0,
+                lightness: 0,
+            }
+        },
+        sizeTheme: {
+            name: 'physical',
+            params: {
+                value: 1,
+            }
+        },
+    };
+}
+
+function getSizeFactor(name: string): number {
+    switch (name) {
+        case 'dLDL':
+            return 2.5;
+        case 'iLDL':
+            return 5;
+        case 'NP_CA':
+        case 'POL_CA':
+        case 'FactorH1':
+        case 'iIgM_Antibody_5mer':
+        // case 'MG_271_272_273_274_192MER': // has a coarse and an atomic part
+            return 2;
+        default: return 1;
+    }
+}
+
+export async function createCellpackHierarchy(plugin: PluginContext, trajectory: StateObjectRef<PluginStateObject.Molecule.Trajectory>) {
+    const builder = plugin.builders.structure;
+    const state = plugin.state.data;
+
+    const model = await builder.createModel(trajectory, { modelIndex: 0 });
+    const entities = model.data!.entities.data;
+
+    const compGroups = new Map<string, StateObjectSelector>();
+    const compIds = new Map<string, { idx: number, members: Map<string, number> }>();
+    const compColors = new Map<string, Color[]>();
+
+    const funcGroups = new Map<string, StateObjectSelector>();
+    const funcIds = new Map<string, { idx: number, size: number }>();
+    const funcColors = new Map<string, Color[]>();
+
+    const graphicsMode = MesoscaleState.get(plugin).graphics;
+    const groupParams = getMesoscaleGroupParams(graphicsMode);
+
+    const base = await state.build()
+        .to(model)
+        .apply(CellpackAssembly, { id: '' })
+        .commit();
+
+    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 } })
+        .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 } })
+        .commit();
+
+    if (entities._rowCount > 1) {
+        for (let i = 0; i < entities._rowCount; i++) {
+            const description = entities.pdbx_description.value(i)[0] || 'unknown compartment';
+            const d = description.split('.');
+            const n = d.slice(0, -1).join('.');
+            const l = d.at(-1)!;
+            if (!compIds.has(n)) {
+                compIds.set(n, { idx: compIds.size, members: new Map() });
+            }
+            const cm = compIds.get(n)!;
+            cm.members.set(l, cm.members.size);
+
+            const f = entities.details.value(i) || 'unknown function';
+            if (!funcIds.has(f)) {
+                funcIds.set(f, { idx: funcIds.size, size: 0 });
+            }
+            funcIds.get(f)!.size += 1;
+        }
+
+        //
+
+        const baseCompColors = getDistinctBaseColors(compIds.size, 0);
+        const compIdEntries = Array.from(compIds.entries());
+        for (let i = 0; i < compIdEntries.length; ++i) {
+            const [n, m] = compIdEntries[i];
+            const groupColors = getDistinctGroupColors(m.members.size, baseCompColors[i], 20, 0);
+            compColors.set(n, groupColors);
+        }
+
+        //
+
+        const baseFuncColors = getDistinctBaseColors(funcIds.size, 0);
+        const funcIdEntries = Array.from(funcIds.entries());
+        for (let i = 0; i < funcIdEntries.length; ++i) {
+            const [n, m] = funcIdEntries[i];
+            const groupColors = getDistinctGroupColors(m.size, baseFuncColors[i], 20, 0);
+            funcColors.set(n, groupColors);
+        }
+
+        //
+
+        for (let i = 0; i < entities._rowCount; i++) {
+            const description = entities.pdbx_description.value(i)[0] || 'unknown compartment';
+            const nodes = description.split('.');
+            for (let j = 0, jl = nodes.length - 1; j < jl; ++j) {
+                const n = nodes.slice(0, j + 1).join('.');
+                const p = nodes.slice(0, j).join('.');
+                if (!compGroups.has(n)) {
+                    const colorIdx = compIds.get(n)?.idx;
+                    const color = colorIdx !== undefined ? baseCompColors[colorIdx] : ColorNames.white;
+                    const label = nodes[j];
+                    const parent = compGroups.get(p) ?? compRoot;
+                    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 } })
+                        .commit({ revertOnError: true });
+                    compGroups.set(n, group);
+                }
+            }
+
+            const f = entities.details.value(i) || 'unknown function';
+            if (!funcGroups.has(f)) {
+                const colorIdx = funcIds.get(f)?.idx;
+                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 } })
+                    .commit({ revertOnError: true });
+                funcGroups.set(f, group);
+            }
+        }
+
+        //
+
+        await state.transaction(async () => {
+            try {
+                const dependsOn = [base.ref];
+                plugin.animationLoop.stop({ noDraw: true });
+                let build: StateBuilder.Root | StateBuilder.To<any> = state.build();
+                for (let i = 0; i < entities._rowCount; i++) {
+                    const description = entities.pdbx_description.value(i)[0] || 'model';
+                    const d = description.split('.');
+                    const n = d.slice(0, -1).join('.');
+                    const l = d.at(-1)!;
+
+                    const f = entities.details.value(i) || 'unknown function';
+
+                    const color = compColors.get(n)![compIds.get(n)!.members.get(l)!];
+                    const sizeFactor = getSizeFactor(l);
+
+                    build = build
+                        .toRoot()
+                        .apply(CellpackStructure, { structureRef: base.ref, entityId: entities.id.value(i) }, { dependsOn })
+                        .apply(StructureRepresentation3D, getSpacefillParams(color, sizeFactor, graphicsMode), { tags: [`comp:${n}`, `func:${f}`] });
+                }
+                await build.commit();
+            } catch (e) {
+                console.error(e);
+                plugin.log.error(e);
+            } finally {
+                plugin.animationLoop.start();
+            }
+        }).run();
+    } else {
+        const dependsOn = [base.ref];
+
+        const merge = (
+            base.data &&
+            base.data.model.entities.data._rowCount === 1 &&
+            base.data.unitSymmetryGroups.length > 100 &&
+            base.data.unitSymmetryGroups.some(usg => usg.units.length > 1)
+        );
+
+        await state.build()
+            .toRoot()
+            .apply(CellpackStructure, { structureRef: base.ref, entityId: entities.id.value(0) }, { dependsOn })
+            .apply(StructureRepresentation3D, getSpacefillParams(ColorNames.lightgray, 1, graphicsMode, merge), { tags: [`comp:`, `func:`] })
+            .commit();
+    }
+}

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

@@ -0,0 +1,139 @@
+/**
+ * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ */
+
+import { Mat4 } from '../../../../mol-math/linear-algebra/3d/mat4';
+import { ElementIndex, Model, Structure, Unit } from '../../../../mol-model/structure';
+import { PluginStateObject as SO, PluginStateTransform } from '../../../../mol-plugin-state/objects';
+import { Task } from '../../../../mol-task';
+import { StateObject, StateTransformer } from '../../../../mol-state';
+import { ParamDefinition as PD } from '../../../../mol-util/param-definition';
+import { SymmetryOperator } from '../../../../mol-math/geometry';
+import { mergeUnits, partitionUnits } from '../util';
+import { Assembly, Symmetry } from '../../../../mol-model/structure/model/properties/symmetry';
+import { ModelSymmetry } from '../../../../mol-model-formats/structure/property/symmetry';
+import { SortedArray } from '../../../../mol-data/int';
+import { GenericInstances, getTransforms } from './preset';
+import { Asset } from '../../../../mol-util/assets';
+import { PluginContext } from '../../../../mol-plugin/context';
+import { deepEqual } from '../../../../mol-util';
+
+function createModelChainMap(model: Model) {
+    const builder = new Structure.StructureBuilder();
+    const units = new Map<string, Unit>();
+
+    const { label_asym_id, _rowCount } = model.atomicHierarchy.chains;
+    const { offsets } = model.atomicHierarchy.chainAtomSegments;
+
+    for (let i = 0; i < _rowCount; i++) {
+        const elements = SortedArray.ofBounds(offsets[i] as ElementIndex, offsets[i + 1] as ElementIndex);
+        const unit = builder.addUnit(Unit.Kind.Atomic, model, SymmetryOperator.Default, elements, Unit.Trait.FastBoundary);
+        units.set(label_asym_id.value(i), unit);
+    }
+
+    return units;
+}
+
+function buildAssembly(model: Model, assembly: Assembly) {
+    const coordinateSystem = SymmetryOperator.create(assembly.id, Mat4.identity(), { assembly: { id: assembly.id, operId: 0, operList: [] } });
+    const assembler = Structure.Builder({
+        coordinateSystem,
+        label: model.label,
+    });
+
+    const units = createModelChainMap(model);
+
+    for (const g of assembly.operatorGroups) {
+        for (const oper of g.operators) {
+            for (const id of g.asymIds!) {
+                const u = units.get(id);
+                if (u) {
+                    assembler.addWithOperator(u, oper);
+                } else {
+                    console.log(`missing asymId '${id}'`);
+                }
+            }
+        }
+    }
+
+    return assembler.getStructure();
+}
+
+const EmptyInstances: GenericInstances<Asset> = {
+    positions: { data: [] },
+    rotations: { variant: 'euler', data: [] }
+};
+
+export { StructureFromGeneric };
+type StructureFromGeneric = typeof StructureFromGeneric
+const StructureFromGeneric = PluginStateTransform.BuiltIn({
+    name: 'structure-from-generic',
+    display: { name: 'Structure from Generic', description: 'Create a molecular structure from Generic models.' },
+    from: SO.Molecule.Model,
+    to: SO.Molecule.Structure,
+    params: {
+        instances: PD.Value<GenericInstances<Asset>>(EmptyInstances),
+        label: PD.Optional(PD.Text('')),
+        cellSize: PD.Numeric(500, { min: 0, max: 10000, step: 100 }),
+    }
+})({
+    apply({ a, params }, plugin: PluginContext) {
+        return Task.create('Build Structure', async ctx => {
+            const transforms = await getTransforms(plugin, params.instances);
+            if (transforms.length === 0) return StateObject.Null;
+
+            const model = a.data;
+            const label = params.label || model.label;
+
+            const base = Structure.ofModel(a.data);
+
+            let structure: Structure;
+            if (transforms.length === 1 && Mat4.isIdentity(transforms[0])) {
+                const symmetry = ModelSymmetry.Provider.get(model);
+                const id = symmetry?.assemblies[0]?.id;
+                const asm = Symmetry.findAssembly(model, id || '');
+                if (asm) {
+                    structure = buildAssembly(model, asm);
+                } else {
+                    const mergedUnits = partitionUnits(base.units, params.cellSize);
+                    structure = Structure.create(mergedUnits, { label });
+                }
+            } else {
+                const assembler = Structure.Builder({ label });
+                const unit = mergeUnits(base.units, 0);
+                for (let i = 0, il = transforms.length; i < il; ++i) {
+                    const t = transforms[i];
+                    const op = SymmetryOperator.create(`op-${i}`, t);
+                    assembler.addWithOperator(unit, op);
+                }
+                structure = assembler.getStructure();
+            }
+
+            const props = { label, description: Structure.elementDescription(structure) };
+            return new SO.Molecule.Structure(structure, props);
+        });
+    },
+    update({ newParams, oldParams }, plugin: PluginContext) {
+        if (deepEqual(newParams, oldParams)) {
+            return StateTransformer.UpdateResult.Unchanged;
+        }
+
+        if (oldParams.instances) releaseInstances(plugin, oldParams.instances);
+        return StateTransformer.UpdateResult.Recreate;
+    },
+    dispose({ b, params }, plugin: PluginContext) {
+        b?.data.customPropertyDescriptors.dispose();
+        if (params?.instances) releaseInstances(plugin, params.instances);
+    }
+});
+
+function releaseInstances(plugin: PluginContext, instances: GenericInstances<Asset>) {
+    if (!Array.isArray(instances.positions.data)) {
+        plugin.managers.asset.release(instances.positions.data.file);
+    }
+    if (!Array.isArray(instances.rotations.data)) {
+        plugin.managers.asset.release(instances.rotations.data.file);
+    }
+}

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

@@ -0,0 +1,581 @@
+/**
+ * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ */
+
+import { Mat4 } from '../../../../mol-math/linear-algebra/3d/mat4';
+import { StateBuilder, StateObjectSelector } from '../../../../mol-state';
+import { PluginContext } from '../../../../mol-plugin/context';
+import { SpacefillRepresentationProvider } from '../../../../mol-repr/structure/representation/spacefill';
+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 { 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';
+import { ModelFromTrajectory, ShapeFromPly, TrajectoryFromGRO, TrajectoryFromMOL, TrajectoryFromMOL2, TrajectoryFromMmCif, TrajectoryFromPDB, TrajectoryFromSDF, TrajectoryFromXYZ } from '../../../../mol-plugin-state/transforms/model';
+import { Euler } from '../../../../mol-math/linear-algebra/3d/euler';
+import { Asset } from '../../../../mol-util/assets';
+import { Clip } from '../../../../mol-util/clip';
+import { StructureFromGeneric } from './model';
+import { getFileNameInfo } from '../../../../mol-util/file-info';
+import { NumberArray } from '../../../../mol-util/type-helpers';
+import { BaseGeometry } from '../../../../mol-geo/geometry/base';
+import { ParamDefinition as PD } from '../../../../mol-util/param-definition';
+
+function getSpacefillParams(color: Color, sizeFactor: number, graphics: GraphicsMode, clipVariant: Clip.Variant) {
+    const gmp = getGraphicsModeProps(graphics === 'custom' ? 'quality' : graphics);
+    return {
+        type: {
+            name: 'spacefill',
+            params: {
+                ...SpacefillRepresentationProvider.defaultValues,
+                ignoreHydrogens: true,
+                instanceGranularity: true,
+                ignoreLight: true,
+                lodLevels: gmp.lodLevels.map(l => {
+                    return {
+                        ...l,
+                        stride: Math.max(1, Math.round(l.stride / Math.pow(sizeFactor, l.scaleBias)))
+                    };
+                }),
+                quality: 'lowest', // avoid 'auto', triggers boundary calc
+                sizeFactor,
+                clip: {
+                    variant: clipVariant,
+                    objects: [],
+                },
+                clipPrimitive: true,
+                approximate: gmp.approximate,
+                alphaThickness: gmp.alphaThickness,
+            },
+        },
+        colorTheme: {
+            name: 'uniform',
+            params: {
+                value: color,
+                saturation: 0,
+                lightness: 0,
+            }
+        },
+        sizeTheme: {
+            name: 'physical',
+            params: {
+                scale: 1,
+            }
+        },
+    };
+}
+
+function getPlyShapeParams(color: Color, clipVariant: Clip.Variant) {
+    return {
+        ...PD.getDefaultValues(BaseGeometry.Params),
+        instanceGranularity: true,
+        ignoreLight: true,
+        clip: {
+            variant: clipVariant,
+            objects: [],
+        },
+        quality: 'custom',
+        doubleSided: true,
+        coloring: {
+            name: 'uniform',
+            params: { color }
+        },
+        grouping: {
+            name: 'none',
+            params: {}
+        },
+        material: {
+            metalness: 0.0,
+            roughness: 1.0,
+            bumpiness: 1.0,
+        },
+        bumpAmplitude: 0.1,
+        bumpFrequency: 0.1 / 10,
+    };
+}
+
+export async function createGenericHierarchy(plugin: PluginContext, file: Asset.File) {
+    const asset = await plugin.runTask(plugin.managers.asset.resolve(file, 'zip'));
+    let manifest: GenericManifest;
+    // TODO: remove special handling for martini prototype
+    if (asset.data['instanced_structure.json']) {
+        const d = asset.data['instanced_structure.json'];
+        const t = utf8Read(d, 0, d.length);
+        const martini = JSON.parse(t) as { model: string, positions: Vec3[], rotations: Vec3[], function: string }[];
+        console.log(martini);
+        manifest = martiniToGeneric(martini);
+    } else if (asset.data['manifest.json']) {
+        const d = asset.data['manifest.json'];
+        const t = utf8Read(d, 0, d.length);
+        manifest = JSON.parse(t) as GenericManifest;
+    } else {
+        throw new Error('no manifest found');
+    }
+    console.log(manifest);
+
+    const state = plugin.state.data;
+    const graphicsMode = MesoscaleState.get(plugin).graphics;
+    const groupParams = getMesoscaleGroupParams(graphicsMode);
+
+    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 } })
+            .commit();
+
+        if (g.children) {
+            for (const c of g.children) {
+                await addGroup(c, group, g.id);
+            }
+        }
+    }
+
+    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 } })
+            .commit();
+
+        if (r.children) {
+            for (const c of r.children!) {
+                await addGroup(c, root, r.id);
+            }
+        }
+    }
+
+    const transformAssets = new Map<string, Asset>();
+    const getTransformAsset = (file: string) => {
+        if (!transformAssets.has(file)) {
+            const d = asset.data[file];
+            transformAssets.set(file, Asset.File(new File([d], file)));
+        }
+        return transformAssets.get(file)!;
+    };
+
+    const getAssetInstances = (instances: GenericInstances<string>): GenericInstances<Asset> => {
+        return {
+            positions: {
+                data: Array.isArray(instances.positions.data)
+                    ? instances.positions.data
+                    : {
+                        file: getTransformAsset(instances.positions.data.file),
+                        view: instances.positions.data.view,
+                    },
+                type: instances.positions.type,
+            },
+            rotations: {
+                data: Array.isArray(instances.rotations.data)
+                    ? instances.rotations.data
+                    : {
+                        file: getTransformAsset(instances.rotations.data.file),
+                        view: instances.rotations.data.view,
+                    },
+                variant: instances.rotations.variant,
+                type: instances.rotations.type,
+            }
+        };
+    };
+
+    await state.transaction(async () => {
+        try {
+            plugin.animationLoop.stop({ noDraw: true });
+            let build: StateBuilder.Root | StateBuilder.To<any> = state.build();
+            for (const ent of manifest.entities) {
+                const d = asset.data[ent.file];
+                const info = getFileNameInfo(ent.file);
+                const isBinary = ['bcif'].includes(info.ext);
+
+                const t = isBinary ? d : utf8Read(d, 0, d.length);
+                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);
+
+                build = build
+                    .toRoot()
+                    .apply(ReadFile, { file, label, isBinary });
+
+                if (['gro', 'cif', 'mmcif', 'mcif', 'bcif', 'pdb', 'ent', 'xyz', 'mol', 'sdf', 'sd', 'mol2'].includes(info.ext)) {
+                    if (['gro'].includes(info.ext)) {
+                        build = build.apply(TrajectoryFromGRO);
+                    } else if (['cif', 'mmcif', 'mcif', 'bcif'].includes(info.ext)) {
+                        build = build.apply(ParseCif).apply(TrajectoryFromMmCif);
+                    } else if (['pdb', 'ent'].includes(info.ext)) {
+                        build = build.apply(TrajectoryFromPDB);
+                    } else if (['xyz'].includes(info.ext)) {
+                        build = build.apply(TrajectoryFromXYZ);
+                    } else if (['mol'].includes(info.ext)) {
+                        build = build.apply(TrajectoryFromMOL);
+                    } else if (['sdf', 'sd'].includes(info.ext)) {
+                        build = build.apply(TrajectoryFromSDF);
+                    } else if (['mol2'].includes(info.ext)) {
+                        build = build.apply(TrajectoryFromMOL2);
+                    }
+
+                    let clipVariant: Clip.Variant = 'pixel';
+                    if (ent.instances) {
+                        if (Array.isArray(ent.instances.positions.data)) {
+                            clipVariant = ent.instances.positions.data.length <= 3 ? 'pixel' : 'instance';
+                        } else {
+                            const byteLength = ent.instances.positions.data.view
+                                ? ent.instances.positions.data.view.byteLength
+                                : asset.data[ent.instances.positions.data.file].length;
+                            clipVariant = byteLength <= 3 * 4 ? 'pixel' : 'instance';
+                        }
+                    }
+
+                    build = build
+                        .apply(ModelFromTrajectory, { modelIndex: 0 })
+                        .apply(StructureFromGeneric, { instances, label })
+                        .apply(StructureRepresentation3D, getSpacefillParams(color, sizeFactor, graphicsMode, clipVariant), { tags });
+                } else if (['ply'].includes(info.ext)) {
+                    if (['ply'].includes(info.ext)) {
+                        const transforms = await getTransforms(plugin, instances);
+                        const clipVariant = transforms.length === 1 ? 'pixel' : 'instance';
+                        build = build
+                            .apply(ParsePly)
+                            .apply(ShapeFromPly, { label, transforms })
+                            .apply(ShapeRepresentation3D, getPlyShapeParams(color, clipVariant), { tags });
+                    }
+                } else {
+                    console.warn(`unknown file format '${info.ext}'`);
+                }
+            }
+            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);
+        } finally {
+            plugin.animationLoop.start();
+        }
+    }).run();
+
+    asset.dispose();
+}
+
+//
+
+type GenericRoot = {
+    id: string
+    label?: string
+    description?: string
+    children: GenericGroup[]
+}
+
+type GenericGroup = {
+    id: string
+    /** reference to `${GenericRoot.id}` */
+    root: string
+    label?: string
+    description?: string
+    children?: GenericGroup[]
+}
+
+type GenericEntity = {
+    /**
+     * the entity file name
+     *
+     * the following extensions/formats are supported
+     *
+     * structures
+     * - gro
+     * - cif, mmcif, mcif, bcif
+     * - pdb, ent
+     * - xyz
+     * - mol
+     * - sdf, sd
+     * - mol2
+     *
+     * meshes
+     * - ply
+     */
+    file: string
+    label?: string
+    description?: string
+    groups: {
+        /** reference to `${GenericGroup.id}` */
+        id: string,
+        /** reference to `${GenericGroup.root}` */
+        root: string
+    }[]
+    /**
+     * defaults to a single, untransformed instance
+     */
+    instances?: GenericInstances<string>
+    /**
+     * defaults to 1 (assuming fully atomic structures)
+     * for C-alpha only structures set to 2
+     * for Martini coarse-grained set to 1.5
+     */
+    sizeFactor?: number
+}
+
+type BinaryData<T extends string | Asset> = {
+    file: T,
+    view?: {
+        byteOffset: number,
+        byteLength: number
+    }
+}
+
+export type GenericInstances<T extends string | Asset> = {
+    /**
+     * translation vectors in Angstrom
+     * [x0, y0, z0, ..., xn, yn, zn] with n = count - 1
+     */
+    positions: {
+        /**
+         * either the data itself or a pointer to binary data
+         */
+        data: number[] | BinaryData<T>
+        /**
+         * how to interpret the data
+         * defaults to `{ kind: 'Array', type: 'Float32' }`
+         */
+        type?: { kind: 'Array', type: 'Float32' }
+        // TODO: maybe worthwhile in the future, mirroring encoders from BinaryCIF
+        // | { kind: 'IntegerPackedFixedPoint', byteCount: number, srcSize: number, factor: number, srcType: 'Float32' }
+    }
+    /**
+     * euler angles in XYZ order
+     * [x0, y0, z0, ..., xn, yn, zn] with n = count - 1
+     *
+     * quaternion rotations in XYZW order
+     * [x0, y0, z0, w0, ..., xn, yn, zn, wn] with n = count - 1
+     *
+     * rotation matrices in row-major order
+     * [m00_0, m01_0, m02_0, ..., m20_n, m21_n, m22_n] with n = count - 1
+     */
+    rotations: {
+        variant: 'euler' | 'quaternion' | 'matrix',
+        /**
+         * either the data itself or a pointer to binary data
+         */
+        data: number[] | BinaryData<T>
+        /**
+         * how to interpret the data
+         * defaults to `{ kind: 'Array', type: 'Float32' }`
+         */
+        type?: { kind: 'Array', type: 'Float32' }
+    }
+}
+
+type GenericFrame = {
+    time: number
+    entities: {
+        file: string
+        instances: GenericInstances<string>
+    }[]
+}
+
+type GenericTrajectory = {
+    label?: string
+    description?: string
+    frames: GenericFrame[]
+}
+
+type GenericManifest = {
+    label?: string
+    description?: string
+    roots: GenericRoot[]
+    entities: GenericEntity[]
+    trajectories?: GenericTrajectory[]
+}
+
+//
+
+const p = Vec3();
+const q = Quat();
+const m = Mat3();
+const e = Euler();
+
+async function getPositions(plugin: PluginContext, p: GenericInstances<Asset>['positions']): Promise<NumberArray> {
+    if (Array.isArray(p.data)) {
+        return p.data;
+    } else {
+        const a = await plugin.runTask(plugin.managers.asset.resolve(p.data.file, 'binary'));
+        const o = p.data.view?.byteOffset || 0;
+        const l = p.data.view?.byteLength || a.data.byteLength;
+        return new Float32Array(a.data.buffer, o + a.data.byteOffset, l / 4);
+    }
+};
+
+async function getRotations(plugin: PluginContext, r: GenericInstances<Asset>['rotations']): Promise<NumberArray> {
+    if (Array.isArray(r.data)) {
+        return r.data;
+    } else {
+        const a = await plugin.runTask(plugin.managers.asset.resolve(r.data.file, 'binary'));
+        const o = r.data.view?.byteOffset || 0;
+        const l = r.data.view?.byteLength || a.data.byteLength;
+        return new Float32Array(a.data.buffer, o + a.data.byteOffset, l / 4);
+    }
+};
+
+export async function getTransforms(plugin: PluginContext, instances?: GenericInstances<Asset>) {
+    const transforms: Mat4[] = [];
+    if (instances) {
+        const positions = await getPositions(plugin, instances.positions);
+        const rotations = await getRotations(plugin, instances.rotations);
+
+        for (let i = 0, il = positions.length / 3; i < il; ++i) {
+            Vec3.fromArray(p, positions, i * 3);
+            if (instances.rotations.variant === 'matrix') {
+                Mat3.fromArray(m, rotations, i * 9);
+                const t = Mat4.fromMat3(Mat4(), m);
+                Mat4.setTranslation(t, p);
+                transforms.push(t);
+            } else if (instances.rotations.variant === 'quaternion') {
+                Quat.fromArray(q, rotations, i * 4);
+                const t = Mat4.fromQuat(Mat4(), q);
+                Mat4.setTranslation(t, p);
+                transforms.push(t);
+            } else if (instances.rotations.variant === 'euler') {
+                Euler.fromArray(e, rotations, i * 3);
+                Quat.fromEuler(q, e, 'XYZ');
+                const t = Mat4.fromQuat(Mat4(), q);
+                Mat4.setTranslation(t, p);
+                transforms.push(t);
+            }
+        }
+    } else {
+        transforms.push(Mat4.identity());
+    }
+
+    return transforms;
+}
+
+//
+
+type MartiniManifest = {
+    model: string,
+    positions: Vec3[],
+    rotations: Vec3[],
+    function: string
+}[]
+
+function martiniToGeneric(martini: MartiniManifest): GenericManifest {
+    const functionRoot: GenericRoot = {
+        id: 'function',
+        label: 'Function',
+        description: 'Functional classification',
+        children: [],
+    };
+    const entities: GenericEntity[] = [];
+
+    const seenGroups = new Set<string>();
+
+    const membraneGroup = {
+        id: 'membane',
+        root: 'function',
+        label: 'Membrane',
+        children: [] as GenericGroup[],
+    };
+    functionRoot.children!.push(membraneGroup);
+    seenGroups.add(membraneGroup.id);
+
+    const lipidsGroup = {
+        id: 'lipid',
+        root: 'function',
+        label: 'Lipid',
+        children: [] as GenericGroup[],
+    };
+    membraneGroup.children!.push(lipidsGroup);
+    seenGroups.add(lipidsGroup.id);
+
+    const upperGroup = {
+        id: 'upper',
+        root: 'function',
+        label: 'Upper Leaflet',
+    };
+    lipidsGroup.children!.push(upperGroup);
+    seenGroups.add(upperGroup.id);
+
+    const lowerGroup = {
+        id: 'lower',
+        root: 'function',
+        label: 'Lower Leaflet',
+    };
+    lipidsGroup.children!.push(lowerGroup);
+    seenGroups.add(lowerGroup.id);
+
+    const memprotGroup = {
+        id: 'memprot',
+        root: 'function',
+        label: 'Transmembrane Protein',
+    };
+    membraneGroup.children!.push(memprotGroup);
+    seenGroups.add(memprotGroup.id);
+
+    for (const e of martini) {
+        const label = e.model.split('.')[0];
+        const group = e.function || 'Metabolite';
+
+        const positions = {
+            data: e.positions.flat().map(x => Math.round((x * 10) * 100) / 100)
+        };
+        const rotations = {
+            data: e.rotations.flat().map(x => Math.round(x * 100) / 100),
+            variant: 'euler' as const,
+        };
+
+        if (group.includes('lower leaflet')) {
+            entities.push({
+                file: e.model,
+                label: label.substring(15),
+                groups: [{ root: 'function', id: 'lower' }],
+                instances: { positions, rotations },
+                sizeFactor: 1.5,
+            });
+        } else if (group.includes('upper leaflet')) {
+            entities.push({
+                file: e.model,
+                label: label.substring(15),
+                groups: [{ root: 'function', id: 'upper' }],
+                instances: { positions, rotations },
+                sizeFactor: 1.5,
+            });
+        } else if (group.length === 4) {
+            entities.push({
+                file: e.model,
+                label: label.substring(17),
+                groups: [{ root: 'function', id: 'memprot' }],
+                instances: { positions, rotations },
+                sizeFactor: 1.5,
+            });
+        } else {
+            if (!seenGroups.has(group)) {
+                functionRoot.children!.push({
+                    id: group,
+                    root: 'function',
+                    label: group,
+                });
+                seenGroups.add(group);
+            }
+            entities.push({
+                file: e.model,
+                label,
+                groups: [{ root: 'function', id: group }],
+                instances: { positions, rotations },
+                sizeFactor: 1.5,
+            });
+        }
+    }
+
+    return {
+        label: 'Martini',
+        description: 'Martini coarse-grained model',
+        roots: [functionRoot],
+        entities,
+    };
+}

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

@@ -0,0 +1,202 @@
+/**
+ * Copyright (c) 2023 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 { SortedArray } from '../../../../mol-data/int';
+import { SymmetryOperator } from '../../../../mol-math/geometry';
+import { Mat4 } from '../../../../mol-math/linear-algebra';
+import { ModelSymmetry } from '../../../../mol-model-formats/structure/property/symmetry';
+import { CustomStructureProperty } from '../../../../mol-model-props/common/custom-structure-property';
+import { ElementIndex, EntityIndex, Model, Structure, Unit } from '../../../../mol-model/structure';
+import { Assembly, Symmetry } from '../../../../mol-model/structure/model/properties/symmetry';
+import { PluginStateObject as PSO, PluginStateTransform } from '../../../../mol-plugin-state/objects';
+import { PluginContext } from '../../../../mol-plugin/context';
+import { StateTransformer } from '../../../../mol-state/transformer';
+import { Task } from '../../../../mol-task';
+import { deepEqual } from '../../../../mol-util';
+import { ParamDefinition as PD } from '../../../../mol-util/param-definition';
+import { partitionUnits } from '../util';
+
+function createModelChainMap(model: Model) {
+    const builder = new Structure.StructureBuilder();
+    const units = new Map<string, Unit>();
+
+    const { label_asym_id, _rowCount } = model.atomicHierarchy.chains;
+    const { offsets } = model.atomicHierarchy.chainAtomSegments;
+
+    for (let i = 0; i < _rowCount; i++) {
+        const elements = SortedArray.ofBounds(offsets[i] as ElementIndex, offsets[i + 1] as ElementIndex);
+        const unit = builder.addUnit(Unit.Kind.Atomic, model, SymmetryOperator.Default, elements, Unit.Trait.FastBoundary);
+        units.set(label_asym_id.value(i), unit);
+    }
+
+    return units;
+}
+
+function buildAssembly(model: Model, assembly: Assembly) {
+    const coordinateSystem = SymmetryOperator.create(assembly.id, Mat4.identity(), { assembly: { id: assembly.id, operId: 0, operList: [] } });
+    const assembler = Structure.Builder({
+        coordinateSystem,
+        label: model.label,
+    });
+
+    const units = createModelChainMap(model);
+
+    for (const g of assembly.operatorGroups) {
+        for (const oper of g.operators) {
+            for (const id of g.asymIds!) {
+                const u = units.get(id);
+                if (u) {
+                    assembler.addWithOperator(u, oper);
+                } else {
+                    console.log(`missing asymId '${id}'`);
+                }
+            }
+        }
+    }
+
+    return assembler.getStructure();
+}
+
+export { MmcifAssembly };
+type MmcifAssembly = typeof MmcifAssembly
+const MmcifAssembly = PluginStateTransform.BuiltIn({
+    name: 'mmcif-assembly',
+    display: { name: 'Mmcif Assembly' },
+    from: PSO.Molecule.Model,
+    to: PSO.Molecule.Structure,
+    params: {
+        id: PD.Text('', { label: 'Asm Id', description: 'Assembly Id (use empty for the 1st assembly)' }),
+    }
+})({
+    canAutoUpdate({ newParams }) {
+        return true;
+    },
+    apply({ a, params }, plugin: PluginContext) {
+        return Task.create('Build Structure', async ctx => {
+            const model = a.data;
+
+            let id = params.id;
+            let asm: Assembly | undefined = void 0;
+            const symmetry = ModelSymmetry.Provider.get(model);
+
+            // if no id is specified, use the 1st assembly.
+            if (!id && symmetry && symmetry.assemblies.length !== 0) {
+                id = symmetry.assemblies[0].id;
+            }
+
+            if (!symmetry || symmetry.assemblies.length === 0) {
+                plugin.log.warn(`Model '${model.entryId}' has no assembly, returning model structure.`);
+            } else {
+                asm = Symmetry.findAssembly(model, id || '');
+                if (!asm) {
+                    plugin.log.warn(`Model '${model.entryId}' has no assembly called '${id}', returning model structure.`);
+                }
+            }
+
+            const base = Structure.ofModel(model);
+            if (!asm) {
+                const label = { label: 'Model', description: Structure.elementDescription(base) };
+                return new PSO.Molecule.Structure(base, label);
+            }
+
+            const s = buildAssembly(model, asm);
+
+            const objProps = { label: `Assembly ${id}`, description: Structure.elementDescription(s) };
+            return new PSO.Molecule.Structure(s, objProps);
+        });
+    },
+    update({ newParams, oldParams }) {
+        return deepEqual(newParams, oldParams)
+            ? StateTransformer.UpdateResult.Unchanged
+            : StateTransformer.UpdateResult.Recreate;
+    },
+    dispose({ b }) {
+        b?.data.customPropertyDescriptors.dispose();
+    }
+});
+
+type UnitsByEntity = Map<EntityIndex, Unit[]>;
+const UnitsByEntity = CustomStructureProperty.createSimple<UnitsByEntity>('units_by_entity', 'root');
+
+function getUnitsByEntity(structure: Structure): UnitsByEntity {
+    if (UnitsByEntity.get(structure).value) {
+        return UnitsByEntity.get(structure).value!;
+    }
+
+    const atomicIndex = structure.model.atomicHierarchy.index;
+    const spheresIndex = structure.model.coarseHierarchy.spheres;
+    const map: UnitsByEntity = new Map();
+    for (const ug of structure.unitSymmetryGroups) {
+        const u = ug.units[0];
+        let e: EntityIndex;
+        if (Unit.isAtomic(u)) {
+            e = atomicIndex.getEntityFromChain(u.chainIndex[u.elements[0]]);
+        } else if (Unit.isSpheres(u)) {
+            e = spheresIndex.getEntityFromChain(u.coarseElements.chainElementSegments.index[u.elements[0]]);
+        } else {
+            continue;
+        }
+
+        if (!map.has(e)) map.set(e, []);
+        const entityUnits = map.get(e)!;
+
+        for (let i = 0, il = ug.units.length; i < il; ++i) {
+            entityUnits.push(ug.units[i]);
+        }
+    }
+
+    UnitsByEntity.set(structure, { value: map }, map);
+    return map;
+}
+
+export { MmcifStructure };
+type MmcifStructure = typeof MmcifStructure
+const MmcifStructure = PluginStateTransform.BuiltIn({
+    name: 'mmcif-structure',
+    display: { name: 'Mmcif Structure' },
+    from: PSO.Root,
+    to: PSO.Molecule.Structure,
+    params: {
+        structureRef: PD.Text(''),
+        entityId: PD.Text(''),
+        cellSize: PD.Numeric(500, { min: 0, max: 10000, step: 100 }),
+    }
+})({
+    canAutoUpdate({ newParams }) {
+        return true;
+    },
+    apply({ a, params, dependencies }) {
+        return Task.create('Build Structure', async ctx => {
+            const parent = dependencies![params.structureRef].data as Structure;
+            const { entities } = parent.model;
+            const idx = entities.getEntityIndex(params.entityId);
+
+            const unitsByEntity = getUnitsByEntity(parent);
+            const units = unitsByEntity.get(idx) || [];
+            const unitCount = units.length;
+
+            let structure: Structure;
+            if (unitCount > 1 && units.every(u => u.conformation.operator.isIdentity)) {
+                const mergedUnits = partitionUnits(units, params.cellSize);
+                structure = Structure.create(mergedUnits);
+            } else {
+                structure = Structure.create(units);
+            }
+
+            const label = entities.data.pdbx_description.value(idx).join(', ') || 'model';
+            return new PSO.Molecule.Structure(structure, { label, description: `${a.description}` });
+        });
+    },
+    update({ newParams, oldParams }) {
+        return deepEqual(newParams, oldParams)
+            ? StateTransformer.UpdateResult.Unchanged
+            : StateTransformer.UpdateResult.Recreate;
+    },
+    dispose({ b }) {
+        b?.data.customPropertyDescriptors.dispose();
+    }
+});

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

@@ -0,0 +1,182 @@
+/**
+ * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ */
+
+import { MmcifFormat } from '../../../../mol-model-formats/structure/mmcif';
+import { PluginStateObject } from '../../../../mol-plugin-state/objects';
+import { StructureRepresentation3D } from '../../../../mol-plugin-state/transforms/representation';
+import { PluginContext } from '../../../../mol-plugin/context';
+import { SpacefillRepresentationProvider } from '../../../../mol-repr/structure/representation/spacefill';
+import { StateObjectRef, StateObjectSelector, StateBuilder } from '../../../../mol-state';
+import { Clip } from '../../../../mol-util/clip';
+import { Color } from '../../../../mol-util/color';
+import { ColorNames } from '../../../../mol-util/color/names';
+import { GraphicsMode, MesoscaleGroup, MesoscaleState, getDistinctBaseColors, getDistinctGroupColors, getGraphicsModeProps, getMesoscaleGroupParams } from '../state';
+import { MmcifAssembly, MmcifStructure } from './model';
+
+function getSpacefillParams(color: Color, scaleFactor: number, graphics: GraphicsMode, clipVariant: Clip.Variant) {
+    const gmp = getGraphicsModeProps(graphics === 'custom' ? 'quality' : graphics);
+    return {
+        type: {
+            name: 'spacefill',
+            params: {
+                ...SpacefillRepresentationProvider.defaultValues,
+                ignoreHydrogens: false,
+                instanceGranularity: false,
+                ignoreLight: true,
+                lodLevels: gmp.lodLevels.map(l => {
+                    return {
+                        ...l,
+                        stride: Math.max(1, Math.round(l.stride / Math.pow(scaleFactor, l.scaleBias)))
+                    };
+                }),
+                quality: 'lowest', // avoid 'auto', triggers boundary calc
+                clip: {
+                    variant: clipVariant,
+                    objects: [],
+                },
+                clipPrimitive: true,
+                approximate: gmp.approximate,
+                alphaThickness: gmp.alphaThickness,
+            },
+        },
+        colorTheme: {
+            name: 'uniform',
+            params: {
+                value: color,
+                saturation: 0,
+                lightness: 0,
+            }
+        },
+        sizeTheme: {
+            name: 'physical',
+            params: {
+                value: 1,
+            }
+        },
+    };
+}
+
+export async function createMmcifHierarchy(plugin: PluginContext, trajectory: StateObjectRef<PluginStateObject.Molecule.Trajectory>) {
+    const builder = plugin.builders.structure;
+    const state = plugin.state.data;
+
+    const model = await builder.createModel(trajectory, { modelIndex: 0 });
+    const { data: entities, subtype } = model.data!.entities;
+
+    const sd = model.data?.sourceData;
+    if (MmcifFormat.is(sd)) {
+        const pdbId = sd.data.db.struct.entry_id.value(0);
+        MesoscaleState.set(plugin, {
+            description: sd.data.db.struct.title.value(0),
+            link: pdbId ? `https://www.rcsb.org/structure/${pdbId}` : ''
+        });
+    }
+
+    const spheresAvgRadius = new Map<string, number>();
+    if (model.data!.coarseHierarchy.isDefined) {
+        const spheresCount = new Map<string, number>();
+        const spheresEntity_id = model.data!.coarseHierarchy.spheres.entity_id;
+        const spheresRadius = model.data!.coarseConformation.spheres.radius;
+        for (let i = 0, il = spheresEntity_id.rowCount; i < il; ++i) {
+            const entitiId = spheresEntity_id.value(i);
+            const radius = spheresRadius[i];
+            if (!spheresCount.has(entitiId)) {
+                spheresCount.set(entitiId, 1);
+                spheresAvgRadius.set(entitiId, radius);
+            } else {
+                spheresCount.set(entitiId, spheresCount.get(entitiId)! + 1);
+                spheresAvgRadius.set(entitiId, spheresAvgRadius.get(entitiId)! + radius);
+            }
+        }
+        spheresAvgRadius.forEach((v, k) => {
+            spheresAvgRadius.set(k, v / spheresCount.get(k)!);
+        });
+    }
+
+    const entGroups = new Map<string, StateObjectSelector>();
+    const entIds = new Map<string, { idx: number, members: Map<number, number> }>();
+    const entColors = new Map<string, Color[]>();
+
+    const graphicsMode = MesoscaleState.get(plugin).graphics;
+    const groupParams = getMesoscaleGroupParams(graphicsMode);
+
+    const base = await state.build()
+        .to(model)
+        .apply(MmcifAssembly, { id: '' })
+        .commit();
+
+    const units = base.data!.units;
+    const willBeMerged = units.length > 1 && units.every(u => u.conformation.operator.isIdentity);
+    const clipVariant = willBeMerged ? 'pixel' : 'instance';
+
+    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 } })
+        .commit();
+
+    const getEntityType = (i: number) => {
+        if (entities.type.value(i) === 'water') return 'water' as const;
+        return subtype.value(i) || 'unknown type';
+    };
+
+    for (let i = 0; i < entities._rowCount; i++) {
+        const t = getEntityType(i);
+        if (!entIds.has(t)) {
+            entIds.set(t, { idx: entIds.size, members: new Map() });
+        }
+        const cm = entIds.get(t)!;
+        cm.members.set(i, cm.members.size);
+    }
+
+    //
+
+    const baseEntColors = getDistinctBaseColors(entIds.size, 0);
+    const entIdEntries = Array.from(entIds.entries());
+    for (let i = 0; i < entIdEntries.length; ++i) {
+        const [t, m] = entIdEntries[i];
+        const groupColors = getDistinctGroupColors(m.members.size, baseEntColors[i], 20, 0);
+        entColors.set(t, groupColors);
+    }
+
+    for (let i = 0; i < entities._rowCount; i++) {
+        const t = getEntityType(i);
+        if (!entGroups.has(t)) {
+            const colorIdx = entIds.get(t)?.idx;
+            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 } })
+                .commit({ revertOnError: true });
+            entGroups.set(t, group);
+        }
+    }
+
+    //
+
+    await state.transaction(async () => {
+        try {
+            const dependsOn = [base.ref];
+            plugin.animationLoop.stop({ noDraw: true });
+            let build: StateBuilder.Root | StateBuilder.To<any> = state.build();
+            for (let i = 0; i < entities._rowCount; i++) {
+                const t = getEntityType(i);
+                const color = entColors.get(t)![entIds.get(t)!.members.get(i)!];
+                const scaleFactor = spheresAvgRadius.get(entities.id.value(i)) || 1;
+
+                build = build
+                    .toRoot()
+                    .apply(MmcifStructure, { structureRef: base.ref, entityId: entities.id.value(i) }, { dependsOn })
+                    .apply(StructureRepresentation3D, getSpacefillParams(color, scaleFactor, graphicsMode, clipVariant), { tags: [`ent:${t}`] });
+            }
+            await build.commit();
+        } catch (e) {
+            console.error(e);
+            plugin.log.error(e);
+        } finally {
+            plugin.animationLoop.start();
+        }
+    }).run();
+}

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

@@ -0,0 +1,138 @@
+/**
+ * Copyright (c) 2022-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ */
+
+import { Mat4 } from '../../../../mol-math/linear-algebra/3d/mat4';
+import { getMatrices, operatorGroupsProvider } from '../../../../mol-model-formats/structure/property/assembly';
+import { Structure, StructureElement, StructureProperties, Trajectory, Unit } from '../../../../mol-model/structure';
+import { Assembly } from '../../../../mol-model/structure/model/properties/symmetry';
+import { PluginStateObject as SO, PluginStateTransform } from '../../../../mol-plugin-state/objects';
+import { Task } from '../../../../mol-task';
+import { Table } from '../../../../mol-data/db';
+import { mmCIF_Schema } from '../../../../mol-io/reader/cif/schema/mmcif';
+import { MmcifFormat } from '../../../../mol-model-formats/structure/mmcif';
+import { arrayFind } from '../../../../mol-data/util';
+import { StateObject, StateTransformer } from '../../../../mol-state';
+import { CifField } from '../../../../mol-io/reader/cif';
+import { ParamDefinition as PD } from '../../../../mol-util/param-definition';
+import { mergeUnits } from '../util';
+import { deepEqual } from '../../../../mol-util';
+
+export { StructureFromPetworld };
+type StructureFromPetworld = typeof StructureFromPetworld
+const StructureFromPetworld = PluginStateTransform.BuiltIn({
+    name: 'structure-from-petworld',
+    display: { name: 'Structure from PetWorld', description: 'Create a molecular structure from PetWorld models.' },
+    from: SO.Molecule.Trajectory,
+    to: SO.Molecule.Structure,
+    params: {
+        modelIndex: PD.Numeric(0),
+        entityIds: PD.Value<string[]>([]),
+    }
+})({
+    apply({ a, params }) {
+        return Task.create('Build Structure', async ctx => {
+            const s = await buildModelsAssembly(a.data, '1', params.modelIndex, params.entityIds).runInContext(ctx);
+            if (!s || !MmcifFormat.is(s.model.sourceData)) return StateObject.Null;
+
+            const { frame } = s.model.sourceData.data;
+            const pdbx_model = frame.categories.pdbx_model.getField('name')!;
+            const label = pdbx_model.str(params.modelIndex);
+            const props = { label, description: Structure.elementDescription(s) };
+            return new SO.Molecule.Structure(s, props);
+        });
+    },
+    update({ newParams, oldParams }) {
+        return deepEqual(newParams, oldParams)
+            ? StateTransformer.UpdateResult.Unchanged
+            : StateTransformer.UpdateResult.Recreate;
+    },
+    dispose({ b }) {
+        b?.data.customPropertyDescriptors.dispose();
+    }
+});
+
+function buildModelsAssembly(trajectory: Trajectory, asmName: string, modelIndex: number, entitiyIds: string[]) {
+    return Task.create('Build Models Assembly', async ctx => {
+        const model = await Task.resolveInContext(trajectory.getFrameAtIndex(modelIndex), ctx);
+        if (!MmcifFormat.is(model.sourceData)) return;
+
+        const { db, frame } = model.sourceData.data;
+        const PDB_model_num = frame.categories.pdbx_struct_assembly_gen.getField('PDB_model_num')!;
+
+        // hack to cache models assemblies
+        if (!(trajectory as any).__modelsAssemblies) {
+            (trajectory as any).__modelsAssemblies = createModelsAssemblies(db.pdbx_struct_assembly, db.pdbx_struct_assembly_gen as StructAssemblyGen, db.pdbx_struct_oper_list, PDB_model_num);
+        }
+        const modelsAssemblies = (trajectory as any).__modelsAssemblies as ModelsAssembly[];
+
+        const modelsAssembly = arrayFind(modelsAssemblies, ma => ma.assembly.id.toLowerCase() === asmName);
+        if (!modelsAssembly) throw new Error(`Models Assembly '${asmName}' is not defined.`);
+
+        const { assembly } = modelsAssembly;
+        const assembler = Structure.Builder();
+        const g = assembly.operatorGroups[modelIndex];
+
+        const structure = Structure.ofModel(model);
+        const l = StructureElement.Location.create(structure);
+        const units = structure.units.filter(u => {
+            l.unit = u;
+            l.element = u.elements[0];
+            return entitiyIds.includes(StructureProperties.entity.id(l));
+        });
+        const unit = mergeUnits(units, 0);
+
+        for (const oper of g.operators) {
+            assembler.addUnit(unit.kind, unit.model, oper, unit.elements, unit.traits | Unit.Trait.FastBoundary, unit.invariantId);
+        }
+
+        return assembler.getStructure();
+    });
+}
+
+//
+
+type StructAssembly = Table<mmCIF_Schema['pdbx_struct_assembly']>
+type StructAssemblyGen = Table<mmCIF_Schema['pdbx_struct_assembly_gen']>
+type StructOperList = Table<mmCIF_Schema['pdbx_struct_oper_list']>
+
+type ModelsAssembly = { assembly: Assembly, modelNums: number[] };
+
+function createModelsAssemblies(pdbx_struct_assembly: StructAssembly, pdbx_struct_assembly_gen: StructAssemblyGen, pdbx_struct_oper_list: StructOperList, PDB_model_num: CifField): ReadonlyArray<ModelsAssembly> {
+    if (!pdbx_struct_assembly._rowCount) return [];
+
+    const matrices = getMatrices(pdbx_struct_oper_list);
+    const assemblies: ModelsAssembly[] = [];
+    for (let i = 0; i < pdbx_struct_assembly._rowCount; i++) {
+        assemblies[assemblies.length] = createModelsAssembly(pdbx_struct_assembly, pdbx_struct_assembly_gen, i, matrices, PDB_model_num);
+    }
+    return assemblies;
+}
+
+type Matrices = Map<string, Mat4>
+type Generator = { assemblyId: string, expression: string, asymIds: string[] }
+
+function createModelsAssembly(pdbx_struct_assembly: StructAssembly, pdbx_struct_assembly_gen: StructAssemblyGen, index: number, matrices: Matrices, PDB_model_num: CifField): ModelsAssembly {
+    const id = pdbx_struct_assembly.id.value(index);
+    const details = pdbx_struct_assembly.details.value(index);
+    const generators: Generator[] = [];
+    const modelNums: number[] = [];
+
+    const { assembly_id, oper_expression, asym_id_list } = pdbx_struct_assembly_gen;
+
+    for (let i = 0, _i = pdbx_struct_assembly_gen._rowCount; i < _i; i++) {
+        if (assembly_id.value(i) !== id) continue;
+        generators[generators.length] = {
+            assemblyId: id,
+            expression: oper_expression.value(i),
+            asymIds: asym_id_list.value(i)
+        };
+        modelNums[modelNums.length] = PDB_model_num.int(i);
+    }
+
+    const assembly = Assembly.create(id, details, operatorGroupsProvider(generators, matrices));
+
+    return { assembly, modelNums };
+}

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

@@ -0,0 +1,134 @@
+/**
+ * Copyright (c) 2022-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ */
+
+import { StateBuilder, StateObjectRef } from '../../../../mol-state';
+import { StructureFromPetworld } from './model';
+import { Color } from '../../../../mol-util/color';
+import { SpacefillRepresentationProvider } from '../../../../mol-repr/structure/representation/spacefill';
+import { StructureRepresentation3D } from '../../../../mol-plugin-state/transforms/representation';
+import { PluginContext } from '../../../../mol-plugin/context';
+import { PluginStateObject } from '../../../../mol-plugin-state/objects';
+import { GraphicsMode, MesoscaleGroup, MesoscaleState, getDistinctBaseColors, getGraphicsModeProps, getMesoscaleGroupParams } from '../state';
+import { ColorNames } from '../../../../mol-util/color/names';
+import { MmcifFormat } from '../../../../mol-model-formats/structure/mmcif';
+import { Task } from '../../../../mol-task';
+
+function getSpacefillParams(color: Color, graphics: GraphicsMode) {
+    const gmp = getGraphicsModeProps(graphics === 'custom' ? 'quality' : graphics);
+    return {
+        type: {
+            name: 'spacefill',
+            params: {
+                ...SpacefillRepresentationProvider.defaultValues,
+                ignoreHydrogens: true,
+                instanceGranularity: true,
+                ignoreLight: true,
+                lodLevels: gmp.lodLevels,
+                quality: 'lowest', // avoid 'auto', triggers boundary calc
+                clip: {
+                    variant: 'instance',
+                    objects: [],
+                },
+                clipPrimitive: true,
+                approximate: gmp.approximate,
+                alphaThickness: gmp.alphaThickness,
+            },
+        },
+        colorTheme: {
+            name: 'uniform',
+            params: {
+                value: color,
+                saturation: 0,
+                lightness: 0,
+            }
+        },
+        sizeTheme: {
+            name: 'physical',
+            params: {
+                scale: 1,
+            }
+        },
+    };
+}
+
+export async function createPetworldHierarchy(plugin: PluginContext, trajectory: StateObjectRef<PluginStateObject.Molecule.Trajectory>) {
+    const cell = StateObjectRef.resolveAndCheck(plugin.state.data, trajectory);
+    const tr = cell?.obj?.data;
+    if (!cell || !tr) return;
+
+    if (!MmcifFormat.is(tr.representative.sourceData)) return;
+
+    const membrane: { modelIndex: number, entityIds: string[] }[] = [];
+    const other: { modelIndex: number, entityIds: string[] }[] = [];
+    for (let i = 0; i < tr.frameCount; ++i) {
+        const m = await Task.resolveInContext(tr.getFrameAtIndex(i));
+        // cannot use m.properties.structAsymMap because petworld models
+        // may assign the same asymId to multiple entities
+        const { label_asym_id, label_entity_id, _rowCount } = m.atomicHierarchy.chains;
+        const membraneIds: string[] = [];
+        const otherIds: string[] = [];
+        const seen = new Set<string>();
+        for (let i = 0; i < _rowCount; i ++) {
+            const entityId = label_entity_id.value(i);
+            if (seen.has(entityId)) continue;
+
+            const asymId = label_asym_id.value(i);
+            if (asymId.startsWith('MEM')) {
+                membraneIds.push(entityId);
+            } else {
+                otherIds.push(entityId);
+            }
+            seen.add(entityId);
+        }
+        if (membraneIds.length) {
+            membrane.push({ modelIndex: i, entityIds: membraneIds });
+        }
+        if (otherIds.length) {
+            other.push({ modelIndex: i, entityIds: otherIds });
+        }
+    }
+
+    const state = plugin.state.data;
+    const graphicsMode = MesoscaleState.get(plugin).graphics;
+    const groupParams = getMesoscaleGroupParams(graphicsMode);
+
+    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 } })
+        .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 } })
+        .commit();
+
+    const colors = getDistinctBaseColors(other.length, 0);
+
+    await state.transaction(async () => {
+        try {
+            plugin.animationLoop.stop({ noDraw: true });
+            let build: StateBuilder.Root | StateBuilder.To<any> = state.build();
+            for (let i = 0, il = membrane.length; i < il; ++i) {
+                build = build
+                    .to(cell)
+                    .apply(StructureFromPetworld, membrane[i])
+                    .apply(StructureRepresentation3D, getSpacefillParams(ColorNames.lightgrey, graphicsMode), { tags: [`ent:mem`] });
+            }
+            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:`] });
+            }
+            await build.commit();
+        } catch (e) {
+            console.error(e);
+            plugin.log.error(e);
+        } finally {
+            plugin.animationLoop.start();
+        }
+    }).run();
+}

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

@@ -0,0 +1,592 @@
+/**
+ * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ */
+
+import { PluginStateObject as PSO, PluginStateTransform } from '../../../mol-plugin-state/objects';
+import { PluginContext } from '../../../mol-plugin/context';
+import { ParamDefinition as PD } from '../../../mol-util/param-definition';
+import { Task } from '../../../mol-task';
+import { Color } from '../../../mol-util/color';
+import { Spheres } from '../../../mol-geo/geometry/spheres/spheres';
+import { Clip } from '../../../mol-util/clip';
+import { escapeRegExp, stringToWords } from '../../../mol-util/string';
+import { Vec3 } from '../../../mol-math/linear-algebra';
+import { ParamMapping } from '../../../mol-util/param-mapping';
+import { EntityNode } from '../ui/entities';
+import { DistinctColorsProps, distinctColors } from '../../../mol-util/color/distinct';
+import { Sphere3D } from '../../../mol-math/geometry';
+import { Hcl } from '../../../mol-util/color/spaces/hcl';
+import { StateObjectCell, StateObjectRef, StateSelection } from '../../../mol-state';
+import { ShapeRepresentation3D, StructureRepresentation3D } from '../../../mol-plugin-state/transforms/representation';
+import { SpacefillRepresentationProvider } from '../../../mol-repr/structure/representation/spacefill';
+import { assertUnreachable } from '../../../mol-util/type-helpers';
+import { MesoscaleExplorerState } from '../app';
+import { saturate } from '../../../mol-math/interpolate';
+
+function getHueRange(hue: number, variability: number) {
+    let min = hue - variability;
+    const minOverflow = (min < 0 ? -min : 0);
+    let max = hue + variability;
+    if (max > 360) min -= max - 360;
+    max += minOverflow;
+    return [Math.max(0, min), Math.min(360, max)] as [number, number];
+}
+
+function getGrayscaleColors(count: number, luminance: number, variability: number) {
+    const out: Color[] = [];
+    for (let i = 0; i < count; ++ i) {
+        const l = saturate(luminance / 100);
+        const v = saturate(variability / 180) * Math.random();
+        const s = Math.random() > 0.5 ? 1 : -1;
+        const d = Math.abs(l + s * v) % 1;
+        out[i] = Color.fromNormalizedRgb(d, d, d);
+    }
+    return out;
+}
+
+export function getDistinctGroupColors(count: number, color: Color, variability: number, shift: number, props?: Partial<DistinctColorsProps>) {
+    const hcl = Hcl.fromColor(Hcl(), color);
+    if (isNaN(hcl[0])) {
+        return getGrayscaleColors(count, hcl[2], variability);
+    }
+
+    if (count === 1) {
+        hcl[1] = 65;
+        hcl[2] = 55;
+        return [Hcl.toColor(hcl)];
+    }
+
+    const colors = distinctColors(count, {
+        hue: getHueRange(hcl[0], variability),
+        chroma: [30, 100],
+        luminance: [50, 100],
+        clusteringStepCount: 0,
+        minSampleCount: 1000,
+        sampleCountFactor: 100,
+        sort: 'none',
+        ...props,
+    });
+
+    if (shift !== 0) {
+        const offset = Math.floor(shift / 100 * count);
+        return [...colors.slice(offset), ...colors.slice(0, offset)];
+    } else {
+        return colors;
+    }
+}
+
+const Colors = [0x377eb8, 0xe41a1c, 0x4daf4a, 0x984ea3, 0xff7f00, 0xffff33, 0xa65628, 0xf781bf] as Color[];
+
+export function getDistinctBaseColors(count: number, shift: number, props?: Partial<DistinctColorsProps>): Color[] {
+    let colors: Color[];
+    if (count <= Colors.length) {
+        colors = Colors.slice(0, count).map(e => Array.isArray(e) ? e[0] : e);
+    } else {
+        colors = distinctColors(count, {
+            hue: [1, 360],
+            chroma: [25, 100],
+            luminance: [30, 100],
+            clusteringStepCount: 0,
+            minSampleCount: 1000,
+            sampleCountFactor: 100,
+            sort: 'none',
+            ...props,
+        });
+    }
+
+    if (shift !== 0) {
+        const offset = Math.floor(shift / 100 * count);
+        return [...colors.slice(offset), ...colors.slice(0, offset)];
+    } else {
+        return colors;
+    }
+}
+
+export const ColorParams = {
+    type: PD.Select('generate', PD.arrayToOptions(['generate', 'uniform', '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' }),
+};
+export type ColorProps = PD.Values<typeof ColorParams>
+
+export const ColorValueParam = PD.Color(Color(0xFFFFFF));
+
+export const RootParams = {
+    type: PD.Select('custom', PD.arrayToOptions(['group-generate', 'group-uniform', 'generate', 'uniform', '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' }),
+};
+
+export const LightnessParams = {
+    lightness: PD.Numeric(0, { min: -6, max: 6, step: 0.1 }),
+};
+export const DimLightness = 6;
+
+export const OpacityParams = {
+    alpha: PD.Numeric(1, { min: 0, max: 1, step: 0.01 }),
+};
+
+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 LodParams = {
+    lodLevels: Spheres.Params.lodLevels,
+    cellSize: Spheres.Params.cellSize,
+    batchSize: Spheres.Params.batchSize,
+    approximate: Spheres.Params.approximate,
+};
+
+export const SimpleClipParams = {
+    type: PD.Select('none', PD.objectToOptions(Clip.Type, t => stringToWords(t))),
+    invert: PD.Boolean(false),
+    position: PD.Group({
+        x: PD.Numeric(0, { min: -100, max: 100, step: 1 }, { immediateUpdate: true }),
+        y: PD.Numeric(0, { min: -100, max: 100, step: 1 }, { immediateUpdate: true }),
+        z: PD.Numeric(0, { min: -100, max: 100, step: 1 }, { immediateUpdate: true }),
+    }, { hideIf: g => g.type === 'none', isExpanded: true }),
+    rotation: PD.Group({
+        axis: PD.Vec3(Vec3.create(1, 0, 0)),
+        angle: PD.Numeric(0, { min: -180, max: 180, step: 1 }, { immediateUpdate: true }),
+    }, { hideIf: g => g.type === 'none', isExpanded: true }),
+    scale: PD.Group({
+        x: PD.Numeric(100, { min: 0, max: 100, step: 1 }, { immediateUpdate: true }),
+        y: PD.Numeric(100, { min: 0, max: 100, step: 1 }, { immediateUpdate: true }),
+        z: PD.Numeric(100, { min: 0, max: 100, step: 1 }, { immediateUpdate: true }),
+    }, { hideIf: g => ['none', 'plane'].includes(g.type), isExpanded: true }),
+};
+export type SimpleClipParams = typeof SimpleClipParams
+export type SimpleClipProps = PD.Values<SimpleClipParams>
+
+export function getClipObjects(values: SimpleClipProps, boundingSphere: Sphere3D): Clip.Props['objects'] {
+    const { center, radius } = boundingSphere;
+
+    const position = Vec3.clone(center);
+    Vec3.add(position, position, Vec3.create(
+        radius * values.position.x / 100,
+        radius * values.position.y / 100,
+        radius * values.position.z / 100
+    ));
+
+    const scale = Vec3.create(values.scale.x, values.scale.y, values.scale.z);
+    Vec3.scale(scale, scale, 2 * radius / 100);
+
+    return [{
+        type: values.type,
+        invert: values.invert,
+        position,
+        scale,
+        rotation: values.rotation
+    }];
+}
+
+export function createClipMapping(node: EntityNode) {
+    return ParamMapping({
+        params: SimpleClipParams,
+        target: (ctx: PluginContext) => {
+            return node.clipValue;
+        }
+    })({
+        values(props, ctx) {
+            if (!props || props.objects.length === 0) {
+                return {
+                    type: 'none',
+                    invert: false,
+                    position: { x: 0, y: 0, z: 0 },
+                    rotation: { axis: Vec3.create(1, 0, 0), angle: 0 },
+                    scale: { x: 100, y: 100, z: 100 },
+                };
+            }
+
+            const { center, radius } = node.plugin.canvas3d!.boundingSphere;
+            const { invert, position, scale, rotation, type } = props.objects[0];
+
+            const p = Vec3.clone(position);
+            Vec3.sub(p, p, center);
+            Vec3.scale(p, p, 100 / radius);
+            Vec3.round(p, p);
+
+            const s = Vec3.clone(scale);
+            Vec3.scale(s, s, 100 / radius / 2);
+            Vec3.round(s, s);
+
+            return {
+                type,
+                invert,
+                position: { x: p[0], y: p[1], z: p[2] },
+                rotation,
+                scale: { x: s[0], y: s[1], z: s[2] },
+            };
+        },
+        update: (s, props) => {
+            if (!props) return;
+
+            const clipObjects = getClipObjects(s, node.plugin.canvas3d!.boundingSphere);
+            props.objects = clipObjects;
+        },
+        apply: async (props, ctx) => {
+            if (props) node.updateClip(props);
+        }
+    });
+}
+
+export const MesoscaleGroupParams = {
+    root: PD.Value<boolean>(false, { isHidden: true }),
+    index: PD.Value<number>(-1, { isHidden: true }),
+    tag: PD.Value<string>('', { isHidden: true }),
+    label: 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 }),
+    lod: PD.Group(LodParams),
+    clip: PD.Group(SimpleClipParams),
+};
+export type MesoscaleGroupProps = PD.Values<typeof MesoscaleGroupParams>;
+
+export class MesoscaleGroupObject extends PSO.Create({ name: 'Mesoscale Group', typeClass: 'Object' }) { }
+
+export const MesoscaleGroup = PluginStateTransform.BuiltIn({
+    name: 'mesoscale-group',
+    display: { name: 'Mesoscale Group' },
+    from: [PSO.Root, MesoscaleGroupObject],
+    to: MesoscaleGroupObject,
+    params: MesoscaleGroupParams,
+})({
+    apply({ a, params }, plugin: PluginContext) {
+        return Task.create('Apply Mesoscale Group', async () => {
+            return new MesoscaleGroupObject({}, { label: params.label });
+        });
+    },
+});
+
+export function getMesoscaleGroupParams(graphicsMode: GraphicsMode): MesoscaleGroupProps {
+    const groupParams = PD.getDefaultValues(MesoscaleGroupParams);
+    if (graphicsMode === 'custom') return groupParams;
+
+    return {
+        ...groupParams,
+        lod: {
+            ...groupParams.lod,
+            ...getGraphicsModeProps(graphicsMode),
+        }
+    };
+}
+
+//
+
+export type LodLevels = typeof SpacefillRepresentationProvider.defaultValues['lodLevels']
+
+export function getLodLevels(graphicsMode: Exclude<GraphicsMode, 'custom'>): LodLevels {
+    switch (graphicsMode) {
+        case 'performance':
+            return [
+                { minDistance: 1, maxDistance: 300, overlap: 0, stride: 1, scaleBias: 1 },
+                { minDistance: 300, maxDistance: 2000, overlap: 0, stride: 40, scaleBias: 3 },
+                { minDistance: 2000, maxDistance: 6000, overlap: 0, stride: 150, scaleBias: 3 },
+                { minDistance: 6000, maxDistance: 10000000, overlap: 0, stride: 300, scaleBias: 2.5 },
+            ];
+        case 'balanced':
+            return [
+                { minDistance: 1, maxDistance: 500, overlap: 0, stride: 1, scaleBias: 1 },
+                { minDistance: 500, maxDistance: 2000, overlap: 0, stride: 15, scaleBias: 3 },
+                { minDistance: 2000, maxDistance: 6000, overlap: 0, stride: 70, scaleBias: 2.7 },
+                { minDistance: 6000, maxDistance: 10000000, overlap: 0, stride: 200, scaleBias: 2.5 },
+            ];
+        case 'quality':
+            return [
+                { minDistance: 1, maxDistance: 1000, overlap: 0, stride: 1, scaleBias: 1 },
+                { minDistance: 1000, maxDistance: 4000, overlap: 0, stride: 10, scaleBias: 3 },
+                { minDistance: 4000, maxDistance: 10000, overlap: 0, stride: 50, scaleBias: 2.7 },
+                { minDistance: 10000, maxDistance: 10000000, overlap: 0, stride: 200, scaleBias: 2.3 },
+            ];
+        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 },
+            ];
+        default:
+            assertUnreachable(graphicsMode);
+    }
+}
+
+export type GraphicsMode = 'ultra' | 'quality' | 'balanced' | 'performance' | 'custom';
+
+export function getGraphicsModeProps(graphicsMode: Exclude<GraphicsMode, 'custom'>) {
+    return {
+        lodLevels: getLodLevels(graphicsMode),
+        approximate: graphicsMode !== 'quality' && graphicsMode !== 'ultra',
+        alphaThickness: graphicsMode === 'performance' ? 15 : 12,
+    };
+}
+
+export function setGraphicsCanvas3DProps(ctx: PluginContext, graphics: GraphicsMode) {
+    const pixelScale = graphics === 'balanced' ? 0.75
+        : graphics === 'performance' ? 0.5 : 1;
+
+    ctx.canvas3dContext?.setProps({ pixelScale });
+
+    ctx.canvas3d?.setProps({
+        postprocessing: {
+            sharpening: pixelScale < 1 ? {
+                name: 'on',
+                params: { sharpness: 0.5, denoise: true }
+            } : { name: 'off', params: {} }
+        }
+    });
+}
+
+//
+
+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 }),
+    link: PD.Value<string>('', { isHidden: true }),
+};
+
+export class MesoscaleStateObject extends PSO.Create<MesoscaleState>({ name: 'Mesoscale State', typeClass: 'Object' }) { }
+
+const MesoscaleStateTransform = PluginStateTransform.BuiltIn({
+    name: 'mesoscale-state',
+    display: { name: 'Mesoscale State' },
+    from: PSO.Root,
+    to: MesoscaleStateObject,
+    params: MesoscaleStateParams,
+})({
+    apply({ a, params }, plugin: PluginContext) {
+        return Task.create('Apply Mesoscale State', async () => {
+            return new MesoscaleStateObject(params);
+        });
+    },
+});
+
+export { MesoscaleState };
+type MesoscaleState = PD.Values<typeof MesoscaleStateParams>;
+const MesoscaleState = {
+    async init(ctx: PluginContext) {
+        const cell = ctx.state.data.selectQ(q => q.ofType(MesoscaleStateObject))[0];
+        if (cell) throw new Error('MesoscaleState already initialized');
+
+        const customState = ctx.customState as MesoscaleExplorerState;
+        const state = await ctx.state.data.build().toRoot().apply(MesoscaleStateTransform, {
+            filter: '',
+            graphics: customState.graphicsMode,
+        }).commit();
+        customState.stateRef = state.ref;
+    },
+    get(ctx: PluginContext): MesoscaleState {
+        const ref = this.ref(ctx);
+        return ctx.state.data.tryGetCellData<MesoscaleStateObject>(ref);
+    },
+    async set(ctx: PluginContext, props: Partial<MesoscaleState>) {
+        const ref = this.ref(ctx);
+        await ctx.state.data.build().to(ref).update(MesoscaleStateTransform, old => Object.assign(old, props)).commit();
+    },
+    ref(ctx: PluginContext): string {
+        const ref = (ctx.customState as MesoscaleExplorerState).stateRef;
+        if (!ref) throw new Error('MesoscaleState not initialized');
+        return ref;
+    },
+    has(ctx: PluginContext): boolean {
+        const ref = (ctx.customState as MesoscaleExplorerState).stateRef || '';
+        return ctx.state.data.cells.has(ref) ? true : false;
+    },
+};
+
+//
+
+export function getRoots(plugin: PluginContext): StateSelection.CellSeq<StateObjectCell<MesoscaleGroupObject>> {
+    const s = plugin.customState as MesoscaleExplorerState;
+    if (!s.stateCache.roots) {
+        s.stateCache.roots = plugin.state.data.select(StateSelection.Generators.rootsOfType(MesoscaleGroupObject));
+    }
+    return s.stateCache.roots;
+}
+
+export function getGroups(plugin: PluginContext, tag?: string): StateSelection.CellSeq<StateObjectCell<MesoscaleGroupObject>> {
+    const s = plugin.customState as MesoscaleExplorerState;
+    const k = `groups-${tag || ''}`;
+    if (!s.stateCache[k]) {
+        const selector = tag !== undefined
+            ? StateSelection.Generators.ofTransformer(MesoscaleGroup).withTag(tag)
+            : StateSelection.Generators.ofTransformer(MesoscaleGroup);
+        s.stateCache[k] = plugin.state.data.select(selector);
+    }
+    return s.stateCache[k];
+}
+
+function _getAllGroups(plugin: PluginContext, tag: string | undefined, list: StateObjectCell[]) {
+    const groups = getGroups(plugin, tag);
+    list.push(...groups);
+    for (const g of groups) {
+        _getAllGroups(plugin, g.params?.values.tag, list);
+    }
+    return list;
+}
+
+export function getAllGroups(plugin: PluginContext, tag?: string) {
+    return _getAllGroups(plugin, tag, []);
+}
+
+export function getAllLeafGroups(plugin: PluginContext, tag: string) {
+    const allGroups = getAllGroups(plugin, tag);
+    allGroups.sort((a, b) => a.params?.values.index - b.params?.values.index);
+    return allGroups.filter(g => {
+        return getEntities(plugin, g.params?.values.tag).length > 0;
+    });
+}
+
+type EntityCells = StateSelection.CellSeq<StateObjectCell<PSO.Molecule.Structure.Representation3D | PSO.Shape.Representation3D>>
+
+export function getEntities(plugin: PluginContext, tag?: string): EntityCells {
+    const s = plugin.customState as MesoscaleExplorerState;
+    const k = `entities-${tag || ''}`;
+    if (!s.stateCache[k]) {
+        const structureSelector = tag !== undefined
+            ? StateSelection.Generators.ofTransformer(StructureRepresentation3D).withTag(tag)
+            : StateSelection.Generators.ofTransformer(StructureRepresentation3D);
+        const shapeSelector = tag !== undefined
+            ? StateSelection.Generators.ofTransformer(ShapeRepresentation3D).withTag(tag)
+            : StateSelection.Generators.ofTransformer(ShapeRepresentation3D);
+        s.stateCache[k] = [
+            ...plugin.state.data.select(structureSelector).filter(c => c.obj!.data.sourceData.elementCount > 0),
+            ...plugin.state.data.select(shapeSelector),
+        ];
+    }
+    return s.stateCache[k];
+}
+
+function getFilterMatcher(filter: string) {
+    return filter.startsWith('"') && filter.endsWith('"')
+        ? new RegExp(`^${escapeRegExp(filter.substring(1, filter.length - 1))}$`, 'g')
+        : new RegExp(escapeRegExp(filter), 'gi');
+}
+
+export function getFilteredEntities(plugin: PluginContext, tag: string, filter: string) {
+    const matcher = getFilterMatcher(filter);
+    return getEntities(plugin, tag).filter(c => getEntityLabel(plugin, c).match(matcher) !== null);
+}
+
+function _getAllEntities(plugin: PluginContext, tag: string | undefined, list: EntityCells) {
+    list.push(...getEntities(plugin, tag));
+    for (const g of getGroups(plugin, tag)) {
+        _getAllEntities(plugin, g.params?.values.tag, list);
+    }
+    return list;
+}
+
+export function getAllEntities(plugin: PluginContext, tag?: string) {
+    return _getAllEntities(plugin, tag, []);
+}
+
+export function getAllFilteredEntities(plugin: PluginContext, tag: string, filter: string) {
+    const matcher = getFilterMatcher(filter);
+    return getAllEntities(plugin, tag).filter(c => getEntityLabel(plugin, c).match(matcher) !== null);
+}
+
+export function getEntityLabel(plugin: PluginContext, cell: StateObjectCell) {
+    return StateObjectRef.resolve(plugin.state.data, cell.transform.parent)?.obj?.label || 'Entity';
+}
+
+//
+
+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;
+
+    if (type === 'group-generate' || type === 'group-uniform') {
+        const groups = getAllLeafGroups(plugin, tag);
+        const baseColors = getDistinctBaseColors(groups.length, shift);
+
+        for (let i = 0; i < groups.length; ++i) {
+            const g = groups[i];
+            const entities = getFilteredEntities(plugin, g.params?.values.tag, filter);
+            let groupColors: Color[] = [];
+
+            if (type === 'group-generate') {
+                const c = g.params?.values.color;
+                groupColors = getDistinctGroupColors(entities.length, baseColors[i], c.variability, c.shift);
+            }
+
+            for (let j = 0; j < entities.length; ++j) {
+                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;
+                        old.type.params.alpha = alpha;
+                        old.type.params.xrayShaded = alpha < 1 ? 'inverted' : false;
+                    } else if (old.coloring) {
+                        old.coloring.params.color = c;
+                        old.coloring.params.lightness = lightness;
+                        old.alpha = alpha;
+                        old.xrayShaded = alpha < 1 ? true : false;
+                    }
+                });
+            }
+
+            update.to(g.transform.ref).update(old => {
+                old.color.type = type === 'group-generate' ? 'generate' : 'uniform';
+                old.color.value = baseColors[i];
+                old.color.lightness = lightness;
+                old.color.alpha = alpha;
+            });
+        }
+    } else if (type === 'generate' || type === 'uniform') {
+        const entities = getAllFilteredEntities(plugin, tag, filter);
+        let groupColors: Color[] = [];
+
+        if (type === 'generate') {
+            groupColors = getDistinctBaseColors(entities.length, shift);
+        }
+
+        for (let j = 0; j < entities.length; ++j) {
+            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;
+                    old.type.params.alpha = alpha;
+                    old.type.params.xrayShaded = alpha < 1 ? 'inverted' : false;
+                } else if (old.coloring) {
+                    old.coloring.params.color = c;
+                    old.coloring.params.lightness = lightness;
+                    old.alpha = alpha;
+                    old.xrayShaded = alpha < 1 ? true : false;
+                }
+            });
+        }
+
+        const others = getAllLeafGroups(plugin, tag);
+        for (const o of others) {
+            update.to(o).update(old => {
+                old.color.type = type === 'generate' ? 'custom' : 'uniform';
+                old.color.value = value;
+                old.color.lightness = lightness;
+                old.color.alpha = alpha;
+            });
+        }
+    }
+
+    await update.commit();
+};
+
+export function expandAllGroups(plugin: PluginContext) {
+    for (const g of getAllGroups(plugin)) {
+        if (g.state.isCollapsed) {
+            plugin.state.data.updateCellState(g.transform.ref, { isCollapsed: false });
+        }
+    }
+};

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

@@ -0,0 +1,87 @@
+/**
+ * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ */
+
+import { OrderedSet, SortedArray } from '../../../mol-data/int';
+import { Box3D, GridLookup3D, PositionData, Sphere3D } from '../../../mol-math/geometry';
+import { Vec3 } from '../../../mol-math/linear-algebra';
+import { ElementIndex, Unit } from '../../../mol-model/structure';
+
+export function mergeUnits(units: readonly Unit[], id: number): Unit {
+    const u = units[0];
+
+    let start = -1 as ElementIndex, end = -1 as ElementIndex;
+    let elements = SortedArray.Empty as SortedArray<ElementIndex>;
+
+    for (let i = 0, il = units.length; i < il; ++i) {
+        const e = units[i].elements;
+        if (SortedArray.isRange(e)) {
+            if (end !== -1 && e[0] === end + 1) {
+                // extend range
+                end = e[e.length - 1];
+            } else {
+                if (end !== -1) {
+                    // pending range
+                    elements = SortedArray.union(elements, SortedArray.ofRange(start, end));
+                }
+                // new range
+                start = e[0];
+                end = e[e.length - 1];
+            }
+        } else {
+            if (end !== -1) {
+                // pending range
+                elements = SortedArray.union(elements, SortedArray.ofRange(start, end));
+                start = -1 as ElementIndex, end = -1 as ElementIndex;
+            }
+            elements = SortedArray.union(elements, e);
+        }
+    }
+
+    if (end !== -1) {
+        // pending range
+        elements = SortedArray.union(elements, SortedArray.ofRange(start, end));
+    }
+
+    return Unit.create(id, id, 0, u.traits | Unit.Trait.MultiChain, u.kind, u.model, u.conformation.operator, elements);
+}
+
+export function partitionUnits(units: readonly Unit[], cellSize: number) {
+    const unitCount = units.length;
+    const mergedUnits: Unit[] = [];
+
+    const box = Box3D.setEmpty(Box3D());
+    const x = new Float32Array(unitCount);
+    const y = new Float32Array(unitCount);
+    const z = new Float32Array(unitCount);
+    const indices = OrderedSet.ofBounds(0, unitCount);
+
+    for (let i = 0, il = unitCount; i < il; ++i) {
+        const v = units[i].boundary.sphere.center;
+        x[i] = v[0];
+        y[i] = v[1];
+        z[i] = v[2];
+        Box3D.add(box, v);
+    }
+    Box3D.expand(box, box, Vec3.create(1, 1, 1));
+
+    const positionData: PositionData = { x, y, z, indices };
+    const boundary = { box, sphere: Sphere3D.fromBox3D(Sphere3D(), box) };
+    const lookup = GridLookup3D(positionData, boundary, Vec3.create(cellSize, cellSize, cellSize));
+
+    const { array, offset, count } = lookup.buckets;
+
+    for (let i = 0, il = offset.length; i < il; ++i) {
+        const start = offset[i];
+        const size = count[i];
+        const cellUnits: Unit[] = [];
+        for (let j = start, jl = start + size; j < jl; ++j) {
+            cellUnits.push(units[array[j]]);
+        }
+        mergedUnits.push(mergeUnits(cellUnits, i));
+    }
+
+    return mergedUnits;
+}

src/apps/mesoscale-explorer/index.html

@@ -0,0 +1,101 @@
+<!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">
+        <link rel="icon" href="./favicon.ico" type="image/x-icon">
+        <title>Mol* Mesoscale Explorer</title>
+        <style>
+            * {
+                margin: 0;
+                padding: 0;
+                box-sizing: border-box;
+            }
+            html, body {
+                width: 100%;
+                height: 100%;
+                overflow: hidden;
+            }
+            hr {
+                margin: 10px;
+            }
+            h1, h2, h3, h4, h5 {
+                margin-top: 5px;
+                margin-bottom: 3px;
+            }
+            button {
+                padding: 2px;
+            }
+            #app {
+                position: absolute;
+                left: 100px;
+                top: 100px;
+                width: 800px;
+                height: 600px;
+            }
+        </style>
+        <link rel="stylesheet" type="text/css" href="molstar.css" />
+    </head>
+    <body>
+        <div id="app"></div>
+        <script type="text/javascript" src="./molstar.js"></script>
+        <script type="text/javascript">
+            function getParam(name, regex) {
+                var r = new RegExp(name + '=' + '(' + regex + ')[&]?', 'i');
+                return decodeURIComponent(((window.location.search || '').match(r) || [])[1] || '');
+            }
+
+            var debugMode = getParam('debug-mode', '[^&]+').trim() === '1';
+            if (debugMode) molstar.setDebugMode(debugMode);
+
+            var timingMode = getParam('timing-mode', '[^&]+').trim() === '1';
+            if (timingMode) molstar.setTimingMode(timingMode);
+
+            var hideControls = getParam('hide-controls', '[^&]+').trim() === '1';
+            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 graphicsMode = getParam('graphics-mode', '[^&]+').trim().toLowerCase();
+
+            molstar.MesoscaleExplorer.create('app', {
+                layoutShowControls: !hideControls,
+                viewportShowExpand: false,
+                preferWebgl1: preferWebgl1,
+                allowMajorPerformanceCaveat: allowMajorPerformanceCaveat,
+                powerPreference: powerPreference || 'high-performance',
+                graphicsMode: graphicsMode || 'quality',
+            }).then(me => {
+                var example = getParam('example', '[^&]+').trim();
+                if (example) {
+                    me.loadExample(example);
+                    return;
+                }
+
+                var url = getParam('url', '[^&]+').trim();
+                var type = getParam('type', '[^&]+').trim();
+                if (url && type) {
+                    me.loadUrl(url, type);
+                    return;
+                }
+
+                var pdb = getParam('pdb', '[^&]+').trim();
+                if (pdb) {
+                    me.loadPdb(pdb);
+                    return;
+                }
+
+                var pdbdev = getParam('pdbdev', '[^&]+').trim();
+                if (pdbdev) {
+                    me.loadPdbDev(pdbdev);
+                    return;
+                }
+
+                window.addEventListener('unload', () => {
+                    // to aid GC
+                    me.dispose();
+                });
+            });
+        </script>
+        <!-- __MOLSTAR_ANALYTICS__ -->
+    </body>
+</html>

src/apps/mesoscale-explorer/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) 2022 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ */
+
+import './favicon.ico';
+import './index.html';
+require('./style.scss');
+export * from './app';

src/apps/mesoscale-explorer/style.scss

@@ -0,0 +1,33 @@
+$default-background:         #2D3E50;
+$font-color:                 #EDF1F2;
+$hover-font-color:           #3B9AD9;
+$entity-current-font-color:  #FFFFFF;
+$msp-btn-remove-background:      #BF3A31;
+$msp-btn-remove-hover-font-color:#ffffff;
+$msp-btn-commit-on-font-color:   #ffffff;
+$entity-badge-font-color:    #ccd4e0;
+
+// used in LOG
+$log-message:          #0CCA5D;
+$log-info:             #5E3673;
+$log-warning:          #FCC937;
+$log-error:            #FD354B;
+
+$logo-background: rgba(0,0,0,0.75);
+
+@function color-lower-contrast($color, $amount) {
+    @return darken($color, $amount);
+}
+
+@function color-increase-contrast($color, $amount) {
+    @return lighten($color, $amount);
+}
+
+@import 'mol-plugin-ui/skin/base/base';
+
+a {
+    color: $font-color;
+    &:hover {
+        color: $hover-font-color;
+    }
+}

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

@@ -0,0 +1,953 @@
+/**
+ * Copyright (c) 2022-2023 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 { 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 { PluginCommands } from '../../../mol-plugin/commands';
+import { State, StateObjectCell, StateSelection, StateTransformer } from '../../../mol-state';
+import { ParameterControls, ParameterMappingControl, ParamOnChange, SelectControl } from '../../../mol-plugin-ui/controls/parameters';
+import { ParamDefinition as PD } from '../../../mol-util/param-definition';
+import { Clip } from '../../../mol-util/clip';
+import { StructureRepresentation3D } from '../../../mol-plugin-state/transforms/representation';
+import { Color } from '../../../mol-util/color';
+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 { 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';
+
+function centerLoci(plugin: PluginContext, loci: Loci, durationMs = 250) {
+    const { canvas3d } = plugin;
+    if (!canvas3d) return;
+
+    const sphere = Loci.getBoundingSphere(loci) || Sphere3D();
+    const snapshot = canvas3d.camera.getCenter(sphere.center);
+    canvas3d.requestCameraReset({ durationMs, snapshot });
+}
+
+export class ModelInfo extends PluginUIComponent<{}, { isDisabled: boolean }> {
+    state = {
+        isDisabled: 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();
+            }
+        });
+    }
+
+    get info() {
+        if (!MesoscaleState.has(this.plugin)) return;
+
+        const state = MesoscaleState.get(this.plugin);
+        if (!state.description && !state.link) return;
+
+        return {
+            description: state.description,
+            link: state.link,
+        };
+    }
+
+    render() {
+        const info = this.info;
+        return info && <>
+            <div className='msp-help-text'>
+                <div>{info.description}</div>
+                <div><a href={info.link} target='_blank'>Source</a></div>
+            </div>
+        </>;
+    }
+}
+
+const SelectionStyleParam = PD.Select('color+outline', PD.objectToOptions({
+    'color+outline': 'Color & Outline',
+    'color': 'Color',
+    'outline': 'Outline'
+} as const));
+type SelectionStyle = typeof SelectionStyleParam['defaultValue']
+
+export class SelectionInfo extends PluginUIComponent<{}, { isDisabled: boolean }> {
+    state = {
+        isDisabled: false,
+    };
+
+    componentDidMount() {
+        this.subscribe(this.plugin.state.data.behaviors.isUpdating, v => {
+            this.setState({ isDisabled: v });
+        });
+
+        this.subscribe(this.plugin.managers.structure.selection.events.changed, e => {
+            if (!this.state.isDisabled) {
+                this.forceUpdate();
+            }
+        });
+    }
+
+    get info() {
+        const info: { label: string, key: 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({
+                    label: cell?.obj?.label || 'Unknown',
+                    key: k,
+                });
+            }
+        });
+        return info;
+    }
+
+    find(label: string) {
+        MesoscaleState.set(this.plugin, { filter: `"${label}"` });
+        if (label) expandAllGroups(this.plugin);
+    };
+
+    remove(key: string) {
+        const e = this.plugin.managers.structure.selection.entries.get(key);
+        if (!e) return;
+
+        const loci = Structure.toStructureElementLoci(e.selection.structure);
+        this.plugin.managers.interactivity.lociSelects.deselect({ loci }, false);
+    }
+
+    center(key: string) {
+        const e = this.plugin.managers.structure.selection.entries.get(key);
+        if (!e) return;
+
+        const loci = Structure.toStructureElementLoci(e.selection.structure);
+        centerLoci(this.plugin, loci);
+    }
+
+    get selection() {
+        const info = this.info;
+        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>
+        </>;
+
+        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>;
+            })}
+        </>;
+    }
+
+    get style() {
+        const p = this.plugin.canvas3d?.props;
+        if (!p) return;
+
+        if (p.renderer.dimStrength === 1 && p.marking.enabled) return 'color+outline';
+        if (p.renderer.dimStrength === 1) return 'color';
+        if (p.marking.enabled) return 'outline';
+    }
+
+    setStyle(value: SelectionStyle) {
+        if (value.includes('color') && value.includes('outline')) {
+            this.plugin.canvas3d?.setProps({
+                renderer: {
+                    dimStrength: 1,
+                },
+                marking: {
+                    enabled: true
+                }
+            });
+        } else if (value.includes('color')) {
+            this.plugin.canvas3d?.setProps({
+                renderer: {
+                    dimStrength: 1,
+                },
+                marking: {
+                    enabled: false
+                }
+            });
+        } else if (value.includes('outline')) {
+            this.plugin.canvas3d?.setProps({
+                renderer: {
+                    dimStrength: 0,
+                    selectStrength: 0.3,
+                },
+                marking: {
+                    enabled: true
+                }
+            });
+        } else {
+            this.plugin.canvas3d?.setProps({
+                renderer: {
+                    dimStrength: 0,
+                    selectStrength: 0,
+                },
+                marking: {
+                    enabled: false
+                }
+            });
+        }
+
+        this.forceUpdate();
+    }
+
+    renderStyle() {
+        const style = this.style || '';
+        return <div style={{ margin: '5px', marginBottom: '10px' }}>
+            <SelectControl name={'Style'} param={SelectionStyleParam} value={style} onChange={(e) => { this.setStyle(e.value); }} />
+        </div>;
+    }
+
+    render() {
+        return <>
+            {this.renderStyle()}
+            {this.selection}
+        </>;
+    }
+}
+
+export class EntityControls extends PluginUIComponent<{}, { isDisabled: boolean }> {
+    filterRef = React.createRef<HTMLInputElement>();
+    prevFilter = '';
+    filterFocus = false;
+
+    state = {
+        isDisabled: false,
+    };
+
+    componentDidMount() {
+        this.subscribe(this.plugin.state.events.object.created, e => {
+            this.forceUpdate();
+        });
+
+        this.subscribe(this.plugin.state.events.object.removed, e => {
+            this.forceUpdate();
+        });
+
+        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 && this.roots.some(r => e.cell === r) || (MesoscaleState.has(this.plugin) && MesoscaleState.ref(this.plugin) === e.ref)) {
+                this.forceUpdate();
+            }
+        });
+    }
+
+    componentDidUpdate(): void {
+        const filter = this.filter;
+        if (this.filterFocus) {
+            this.filterRef.current?.focus();
+            this.prevFilter = filter;
+        }
+    }
+
+    get roots() {
+        return getRoots(this.plugin);
+    }
+
+    setGroupBy = (value: number) => {
+        this.roots.forEach((c, i) => {
+            if (c.state.isHidden && value === i || !c.state.isHidden && value !== i) {
+                PluginCommands.State.ToggleVisibility(this.plugin, { state: c.parent!, ref: c.transform.ref });
+            }
+        });
+    };
+
+    get groupBy() {
+        const roots = this.roots;
+        for (let i = 0, il = roots.length; i < il; ++i) {
+            if (!roots[i].state.isHidden) return i;
+        }
+        return 0;
+    }
+
+    setFilter = (value: string) => {
+        this.filterFocus = true;
+        const filter = value.trim().replace(/\s+/gi, ' ');
+        MesoscaleState.set(this.plugin, { filter });
+        if (filter) expandAllGroups(this.plugin);
+    };
+
+    get filter() {
+        return MesoscaleState.has(this.plugin) ? MesoscaleState.get(this.plugin).filter : '';
+    }
+
+    setGraphics = (graphics: GraphicsMode) => {
+        MesoscaleState.set(this.plugin, { graphics });
+        (this.plugin.customState as MesoscaleExplorerState).graphicsMode = graphics;
+
+        if (graphics === 'custom') return;
+
+        const update = this.plugin.state.data.build();
+
+        const { lodLevels, approximate, alphaThickness } = getGraphicsModeProps(graphics);
+
+        for (const r of getAllEntities(this.plugin)) {
+            update.to(r).update(old => {
+                if (old.type) {
+                    old.type.params.lodLevels = lodLevels;
+                    old.type.params.approximate = approximate;
+                    old.type.params.alphaThickness = alphaThickness;
+                }
+            });
+        }
+
+        for (const g of getAllGroups(this.plugin)) {
+            update.to(g).update(old => {
+                old.lod.lodLevels = lodLevels;
+                old.lod.approximate = approximate;
+            });
+        }
+
+        update.commit();
+
+        setGraphicsCanvas3DProps(this.plugin, graphics);
+    };
+
+    get graphics() {
+        const customState = this.plugin.customState as MesoscaleExplorerState;
+        return MesoscaleState.has(this.plugin) ? MesoscaleState.get(this.plugin).graphics : customState.graphicsMode;
+    }
+
+    renderGraphics() {
+        const graphics = this.graphics;
+        return <div style={{ margin: '5px', marginBottom: '10px' }}>
+            <SelectControl name={'Graphics'} param={MesoscaleStateParams.graphics} value={`${graphics}`} onChange={(e) => { this.setGraphics(e.value); }} />
+        </div>;
+    }
+
+    render() {
+        const roots = this.roots;
+        if (roots.length === 0 || !MesoscaleState.has(this.plugin)) {
+            return <>
+                {this.renderGraphics()}
+            </>;
+        }
+
+        const disabled = this.state.isDisabled;
+        const groupBy = this.groupBy;
+
+        const options: [string, string][] = [];
+        roots.forEach((c, i) => {
+            options.push([`${i}`, c.obj!.label]);
+        });
+        const groupParam = PD.Select(options[0][0], options);
+        const root = roots.length === 1 ? roots[0] : roots[groupBy];
+
+        const filter = this.filter;
+
+        return <>
+            {this.renderGraphics()}
+            <div className={`msp-flex-row msp-control-row`} style={{ margin: '5px', marginBottom: '10px' }}>
+                <input type='text' ref={this.filterRef}
+                    value={filter}
+                    placeholder='Search'
+                    onChange={e => this.setFilter(e.target.value)}
+                    disabled={disabled}
+                    onBlur={() => this.filterFocus = false}
+                />
+                <IconButton svg={CloseSvg} toggleState={false} disabled={disabled} onClick={() => this.setFilter('')} />
+            </div>
+            {options.length > 1 && <div 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} />
+        </>;
+    }
+}
+
+class Node<P extends {}, S extends { isDisabled: boolean }> extends PluginUIComponent<P & { cell: StateObjectCell, depth: number }, S> {
+
+    is(e: State.ObjectEvent) {
+        return e.ref === this.ref && e.state === this.props.cell.parent;
+    }
+
+    get ref() {
+        return this.props.cell.transform.ref;
+    }
+
+    get cell() {
+        return this.props.cell;
+    }
+
+    get roots() {
+        return getRoots(this.plugin);
+    }
+
+    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 && this.is(e)) {
+                this.forceUpdate();
+            }
+        });
+    }
+}
+
+export class GroupNode extends Node<{ filter: string }, { isCollapsed: boolean, action?: 'color' | 'clip' | 'root', isDisabled: boolean }> {
+    state = {
+        isCollapsed: !!this.props.cell.state.isCollapsed,
+        action: undefined,
+        isDisabled: false,
+    };
+
+    toggleExpanded = (e: React.MouseEvent<HTMLElement>) => {
+        PluginCommands.State.ToggleExpanded(this.plugin, { state: this.cell.parent!, ref: this.ref });
+    };
+
+    toggleColor = (e?: React.MouseEvent<HTMLButtonElement, MouseEvent>) => {
+        this.setState({ action: this.state.action === 'color' ? undefined : 'color' });
+    };
+
+    toggleClip = () => {
+        this.setState({ action: this.state.action === 'clip' ? undefined : 'clip' });
+    };
+
+    toggleRoot = () => {
+        this.setState({ action: this.state.action === 'root' ? undefined : 'root' });
+    };
+
+    highlight = (e: React.MouseEvent<HTMLElement>) => {
+        e.preventDefault();
+        this.plugin.canvas3d?.mark({ loci: EveryLoci }, MarkerAction.RemoveHighlight);
+        for (const r of this.allFilteredEntities) {
+            const repr = r.obj?.data.repr;
+            if (repr) {
+                this.plugin.canvas3d?.mark({ repr, loci: EveryLoci }, MarkerAction.Highlight);
+            }
+        }
+    };
+
+    clearHighlight = (e: React.MouseEvent<HTMLElement>) => {
+        e.preventDefault();
+        this.plugin.canvas3d?.mark({ loci: EveryLoci }, MarkerAction.RemoveHighlight);
+        e.currentTarget.blur();
+    };
+
+    get groups() {
+        return getGroups(this.plugin, this.cell.params?.values.tag);
+    }
+
+    get allGroups() {
+        const allGroups = getAllGroups(this.plugin, this.cell.params?.values.tag);
+        allGroups.push(this.cell);
+        return allGroups;
+    }
+
+    get entities() {
+        return getEntities(this.plugin, this.cell.params?.values.tag);
+    }
+
+    get filteredEntities() {
+        return getFilteredEntities(this.plugin, this.cell.params?.values.tag, this.props.filter);
+    }
+
+    get allEntities() {
+        return getAllEntities(this.plugin, this.cell.params?.values.tag);
+    }
+
+    get allFilteredEntities() {
+        return getAllFilteredEntities(this.plugin, this.cell.params?.values.tag, this.props.filter);
+    }
+
+    toggleVisible = (e: React.MouseEvent<HTMLElement>) => {
+        PluginCommands.State.ToggleVisibility(this.plugin, { state: this.cell.parent!, ref: this.ref });
+        const isHidden = this.cell.state.isHidden;
+
+        for (const r of this.allFilteredEntities) {
+            this.plugin.state.data.updateCellState(r.transform.ref, { isHidden });
+        }
+
+        this.plugin.build().to(this.ref).update(old => {
+            old.hidden = isHidden;
+        }).commit();
+    };
+
+    updateColor = (values: ColorProps) => {
+        const update = this.plugin.state.data.build();
+        const { value, type, lightness, alpha } = values;
+
+        const entities = this.filteredEntities;
+
+        let groupColors: Color[] = [];
+
+        if (type === 'generate') {
+            groupColors = getDistinctGroupColors(entities.length, value, values.variability, values.shift);
+        }
+
+        for (let i = 0; i < entities.length; ++i) {
+            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;
+                    old.type.params.alpha = alpha;
+                    old.type.params.xrayShaded = alpha < 1 ? 'inverted' : false;
+                } else {
+                    old.coloring.params.color = c;
+                    old.coloring.params.lightness = lightness;
+                    old.alpha = alpha;
+                    old.xrayShaded = alpha < 1 ? true : false;
+                }
+            });
+        }
+
+        update.to(this.ref).update(old => {
+            old.color = values;
+        });
+
+        for (const r of this.roots) {
+            update.to(r).update(old => {
+                old.color.type = 'custom';
+            });
+        }
+
+        update.commit();
+    };
+
+    updateRoot = async (values: PD.Values) => {
+        await updateColors(this.plugin, values, this.cell.params?.values.tag, this.props.filter);
+
+        const update = this.plugin.state.data.build();
+
+        for (const r of this.roots) {
+            if (r !== this.cell) {
+                update.to(r).update(old => {
+                    old.color.type = 'custom';
+                });
+                const others = getAllLeafGroups(this.plugin, r.params?.values.tag);
+                for (const o of others) {
+                    update.to(o).update(old => {
+                        old.color.type = 'custom';
+                    });
+                }
+            }
+        }
+
+        update.to(this.ref).update(old => {
+            old.color = values;
+        });
+
+        update.commit();
+    };
+
+    updateClip = (values: PD.Values) => {
+        const update = this.plugin.state.data.build();
+        const clipObjects = getClipObjects(values as SimpleClipProps, this.plugin.canvas3d!.boundingSphere);
+
+        for (const r of this.allFilteredEntities) {
+            update.to(r).update(old => {
+                if (old.type) {
+                    old.type.params.clip.objects = clipObjects;
+                } else {
+                    old.clip.objects = clipObjects;
+                }
+            });
+        }
+
+        for (const g of this.allGroups) {
+            update.to(g).update(old => {
+                old.clip = values;
+            });
+        }
+
+        update.commit();
+    };
+
+    updateLod = (values: PD.Values) => {
+        MesoscaleState.set(this.plugin, { graphics: 'custom' });
+        (this.plugin.customState as MesoscaleExplorerState).graphicsMode = 'custom';
+
+        const update = this.plugin.state.data.build();
+
+        for (const r of this.allFilteredEntities) {
+            update.to(r).update(old => {
+                if (old.type) {
+                    old.type.params.lodLevels = values.lodLevels;
+                    old.type.params.cellSize = values.cellSize;
+                    old.type.params.batchSize = values.batchSize;
+                    old.type.params.approximate = values.approximate;
+                }
+            });
+        }
+
+        for (const g of this.allGroups) {
+            update.to(g).update(old => {
+                old.lod = values;
+            });
+        }
+
+        update.commit();
+    };
+
+    update = (props: MesoscaleGroupProps) => {
+        this.plugin.state.data.build().to(this.ref).update(props);
+    };
+
+    renderColor() {
+        const color = this.cell.params?.values.color;
+        if (this.cell.params?.values.color.type === 'uniform') {
+            const style = {
+                backgroundColor: Color.toStyle(color.value),
+                minWidth: 32,
+                width: 32,
+                borderRight: `6px solid ${Color.toStyle(Color.lighten(color.value, color.lightness))}`
+            };
+            return <Button style={style} onClick={this.toggleColor} />;
+        } else if (this.cell.params?.values.color.type === 'generate') {
+            const style = {
+                minWidth: 32,
+                width: 32,
+                borderRight: `6px solid ${Color.toStyle(Color.lighten(color.value, color.lightness))}`
+            };
+            return <IconButton style={style} svg={BrushSvg} toggleState={false} small onClick={this.toggleColor} />;
+        } else {
+            return <IconButton svg={BrushSvg} toggleState={false} small onClick={this.toggleColor} />;
+        }
+    }
+
+    render() {
+        if (this.allFilteredEntities.length === 0) return;
+
+        const state = this.cell.state;
+        const disabled = false;
+        const groupLabel = this.cell.obj!.label;
+        const depth = this.props.depth;
+        const colorValue = this.cell.params?.values.color;
+        const rootValue = this.cell.params?.values.color;
+        const clipValue = this.cell.params?.values.clip;
+        const lodValue = this.cell.params?.values.lod;
+        const isRoot = this.cell.params?.values.root;
+
+        const groups = this.groups;
+        const entities = this.entities;
+
+        const label = <Button className={`msp-btn-tree-label`} noOverflow disabled={disabled}
+            onMouseEnter={this.highlight}
+            onMouseLeave={this.clearHighlight}
+        >
+            <span title={groupLabel}>{groupLabel}</span>
+        </Button>;
+
+        const expand = <IconButton svg={state.isCollapsed ? ArrowRightSvg : ArrowDropDownSvg} flex='20px' disabled={disabled} onClick={this.toggleExpanded} transparent className='msp-no-hover-outline' style={{ visibility: groups.length > 0 || entities.length > 0 ? 'visible' : 'hidden' }} />;
+        const color = (entities.length > 0 && !isRoot) && this.renderColor();
+        const root = (isRoot && this.allGroups.length > 1) && <IconButton svg={BrushSvg} toggleState={false} disabled={disabled} small onClick={this.toggleRoot} />;
+        const clip = <IconButton svg={ContentCutSvg} toggleState={false} disabled={disabled} small onClick={this.toggleClip} />;
+        const visibility = <IconButton svg={state.isHidden ? VisibilityOffOutlinedSvg : VisibilityOutlinedSvg} toggleState={false} disabled={disabled} small onClick={this.toggleVisible} />;
+
+        return <>
+            <div className={`msp-flex-row`} style={{ margin: `1px 5px 1px ${depth * 10 + 5}px` }}>
+                {expand}
+                {label}
+                {root || color}
+                {clip}
+                {visibility}
+            </div>
+            {this.state.action === 'color' && <div style={{ marginRight: 5 }} className='msp-accent-offset'>
+                <ControlGroup header='Color' initialExpanded={true} hideExpander={true} hideOffset={true} onHeaderClick={this.toggleColor}
+                    topRightIcon={CloseSvg} noTopMargin childrenClassName='msp-viewport-controls-panel-controls'>
+                    <ParameterControls params={ColorParams} values={colorValue} onChangeValues={this.updateColor} />
+                </ControlGroup>
+            </div>}
+            {this.state.action === 'clip' && <div style={{ marginRight: 5 }} className='msp-accent-offset'>
+                <ControlGroup header='Clip' initialExpanded={true} hideExpander={true} hideOffset={true} onHeaderClick={this.toggleClip}
+                    topRightIcon={CloseSvg} noTopMargin childrenClassName='msp-viewport-controls-panel-controls'>
+                    <ParameterControls params={SimpleClipParams} values={clipValue} onChangeValues={this.updateClip} />
+                    <ParameterControls params={LodParams} values={lodValue} onChangeValues={this.updateLod} />
+                </ControlGroup>
+            </div>}
+            {this.state.action === 'root' && <div style={{ marginRight: 5 }} className='msp-accent-offset'>
+                <ControlGroup header='Color' initialExpanded={true} hideExpander={true} hideOffset={true} onHeaderClick={this.toggleRoot}
+                    topRightIcon={CloseSvg} noTopMargin childrenClassName='msp-viewport-controls-panel-controls'>
+                    <ParameterControls params={RootParams} values={rootValue} onChangeValues={this.updateRoot} />
+                </ControlGroup>
+            </div>}
+            {(!state.isCollapsed) && <>
+                {groups.map(c => {
+                    return <GroupNode filter={this.props.filter} cell={c} depth={depth + 1} key={c.transform.ref} />;
+                })}
+                {this.filteredEntities.map(c => {
+                    return <EntityNode cell={c} depth={depth + 1} key={c.transform.ref} />;
+                })}
+            </>}
+        </>;
+    }
+}
+
+export class EntityNode extends Node<{}, { action?: 'color' | 'clip', isDisabled: boolean }> {
+    state = {
+        action: undefined,
+        isDisabled: false,
+    };
+
+    clipMapping = createClipMapping(this);
+
+    get groups() {
+        return this.plugin.state.data.select(StateSelection.Generators.ofTransformer(MesoscaleGroup)
+            .filter(c => !!this.cell.transform.tags?.includes(c.params?.values.tag)));
+    }
+
+    toggleVisible = (e: React.MouseEvent<HTMLElement>) => {
+        e.preventDefault();
+        PluginCommands.State.ToggleVisibility(this.plugin, { state: this.props.cell.parent!, ref: this.ref });
+        e.currentTarget.blur();
+    };
+
+    toggleColor = (e?: React.MouseEvent<HTMLButtonElement, MouseEvent>) => {
+        if (e?.ctrlKey) {
+            this.updateLightness({ lightness: this.lightnessValue?.lightness ? 0 : DimLightness });
+            e.preventDefault();
+        } else {
+            this.setState({ action: this.state.action === 'color' ? undefined : 'color' });
+        }
+    };
+
+    toggleClip = () => {
+        this.setState({ action: this.state.action === 'clip' ? undefined : 'clip' });
+    };
+
+    highlight = (e: React.MouseEvent<HTMLElement>) => {
+        e.preventDefault();
+        this.plugin.canvas3d?.mark({ loci: EveryLoci }, MarkerAction.RemoveHighlight);
+        const repr = this.cell?.obj?.data.repr;
+        if (repr) {
+            this.plugin.canvas3d?.mark({ repr, loci: EveryLoci }, MarkerAction.Highlight);
+        }
+        e.currentTarget.blur();
+    };
+
+    clearHighlight = (e: React.MouseEvent<HTMLElement>) => {
+        e.preventDefault();
+        this.plugin.canvas3d?.mark({ loci: EveryLoci }, MarkerAction.RemoveHighlight);
+        e.currentTarget.blur();
+    };
+
+    toggleSelect = (e: React.MouseEvent<HTMLElement>) => {
+        e.preventDefault();
+        const cell = this.cell 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);
+        this.plugin.managers.interactivity.lociSelects.toggle({ loci }, false);
+    };
+
+    center = (e: React.MouseEvent<HTMLElement>) => {
+        e.preventDefault();
+        const cell = this.cell 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);
+        centerLoci(this.plugin, loci);
+    };
+
+    handleClick = (e: React.MouseEvent<HTMLElement>) => {
+        if (e.ctrlKey) {
+            this.toggleSelect(e);
+        } else {
+            this.center(e);
+        }
+    };
+
+    get colorValue(): Color | undefined {
+        return this.cell.transform.params?.colorTheme?.params.value ?? this.cell.transform.params?.coloring?.params.color;
+    }
+
+    get lightnessValue(): { lightness: number } | undefined {
+        return {
+            lightness: this.cell.transform.params?.colorTheme?.params.lightness ?? this.cell.transform.params?.coloring?.params.lightness ?? 0
+        };
+    }
+
+    get opacityValue(): { alpha: number } | undefined {
+        return {
+            alpha: this.cell.transform.params?.type?.params.alpha ?? this.cell.transform.params?.alpha ?? 1
+        };
+    }
+
+    get clipValue(): Clip.Props | undefined {
+        return this.cell.transform.params.type?.params.clip ?? this.cell.transform.params.clip;
+    }
+
+    get lodValue(): PD.Values<typeof LodParams> | undefined {
+        const p = this.cell.transform.params?.type?.params;
+        if (!p) return;
+        return {
+            lodLevels: p.lodLevels,
+            cellSize: p.cellSize,
+            batchSize: p.batchSize,
+            approximate: p.approximate,
+        };
+    }
+
+    get patternValue(): { amplitude: number, frequency: number } | undefined {
+        const p = this.cell.transform.params;
+        if (p.type) return;
+        return {
+            amplitude: p.bumpAmplitude,
+            frequency: p.bumpFrequency * 10,
+        };
+    }
+
+    updateColor: ParamOnChange = ({ value }) => {
+        const update = this.plugin.state.data.build();
+        for (const g of this.groups) {
+            update.to(g.transform.ref).update(old => {
+                old.color.type = 'custom';
+            });
+        }
+        for (const r of this.roots) {
+            update.to(r).update(old => {
+                old.color.type = 'custom';
+            });
+        }
+        update.to(this.ref).update(old => {
+            if (old.colorTheme) {
+                old.colorTheme.params.value = value;
+            } else if (old.coloring) {
+                old.coloring.params.color = value;
+            }
+        });
+        update.commit();
+    };
+
+    updateLightness = (values: PD.Values) => {
+        return this.plugin.build().to(this.ref).update(old => {
+            if (old.colorTheme) {
+                old.colorTheme.params.lightness = values.lightness;
+            } else if (old.coloring) {
+                old.coloring.params.lightness = values.lightness;
+            }
+        }).commit();
+    };
+
+    updateOpacity = (values: PD.Values) => {
+        return this.plugin.build().to(this.ref).update(old => {
+            if (old.type) {
+                old.type.params.alpha = values.alpha;
+                old.type.params.xrayShaded = values.alpha < 1 ? 'inverted' : false;
+            } else {
+                old.alpha = values.alpha;
+                old.xrayShaded = values.alpha < 1 ? true : false;
+            }
+        }).commit();
+    };
+
+    updateClip = (props: Clip.Props) => {
+        const params = this.cell.transform.params;
+        const clip = params.type ? params.type.params.clip : params.clip;
+        if (!PD.areEqual(Clip.Params, clip, props)) {
+            this.plugin.build().to(this.ref).update(old => {
+                if (old.type) {
+                    old.type.params.clip = props;
+                } else {
+                    old.clip = props;
+                }
+            }).commit();
+        }
+    };
+
+    updateLod = (values: PD.Values) => {
+        const params = this.cell.transform.params as StateTransformer.Params<StructureRepresentation3D>;
+        if (!params.type) return;
+
+        MesoscaleState.set(this.plugin, { graphics: 'custom' });
+        (this.plugin.customState as MesoscaleExplorerState).graphicsMode = 'custom';
+
+        if (!deepEqual(params.type.params.lodLevels, values.lodLevels) || params.type.params.cellSize !== values.cellSize || params.type.params.batchSize !== values.batchSize || params.type.params.approximate !== values.approximate) {
+            this.plugin.build().to(this.ref).update(old => {
+                old.type.params.lodLevels = values.lodLevels;
+                old.type.params.cellSize = values.cellSize;
+                old.type.params.batchSize = values.batchSize;
+                old.type.params.approximate = values.approximate;
+            }).commit();
+        }
+    };
+
+    updatePattern = (values: PD.Values) => {
+        return this.plugin.build().to(this.ref).update(old => {
+            if (!old.type) {
+                old.bumpAmplitude = values.amplitude;
+                old.bumpFrequency = values.frequency / 10;
+            }
+        }).commit();
+    };
+
+    render() {
+        const cellState = this.cell.state;
+        const disabled = this.cell.status !== 'error' && this.cell.status !== 'ok';
+        const depth = this.props.depth;
+        const colorValue = this.colorValue;
+        const lightnessValue = this.lightnessValue;
+        const opacityValue = this.opacityValue;
+        const lodValue = this.lodValue;
+        const patternValue = this.patternValue;
+
+        const l = getEntityLabel(this.plugin, this.cell);
+        const label = <Button className={`msp-btn-tree-label msp-type-class-${this.cell.obj!.type.typeClass}`} noOverflow disabled={disabled}
+            onClick={this.handleClick}
+            onMouseEnter={this.highlight}
+            onMouseLeave={this.clearHighlight}
+        >
+            <span title={l}>{l}</span>
+        </Button>;
+
+        const color = colorValue !== undefined && <Button style={{ backgroundColor: Color.toStyle(colorValue), minWidth: 32, width: 32, borderRight: `6px solid ${Color.toStyle(Color.lighten(colorValue, lightnessValue?.lightness || 0))}` }} onClick={this.toggleColor} />;
+        const clip = <IconButton svg={ContentCutSvg} toggleState={false} disabled={disabled} small onClick={this.toggleClip} />;
+        const visibility = <IconButton svg={cellState.isHidden ? VisibilityOffOutlinedSvg : VisibilityOutlinedSvg} toggleState={false} disabled={disabled} small onClick={this.toggleVisible} />;
+
+        return <>
+            <div className={`msp-flex-row`} style={{ margin: `1px 5px 1px ${depth * 10 + 5}px` }}>
+                {label}
+                {color}
+                {clip}
+                {visibility}
+            </div>
+            {this.state.action === 'color' && colorValue !== void 0 && <div style={{ marginRight: 5 }} className='msp-accent-offset'>
+                <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={LightnessParams} values={lightnessValue} onChangeValues={this.updateLightness} />
+                    <ParameterControls params={OpacityParams} values={opacityValue} onChangeValues={this.updateOpacity} />
+                    {patternValue && <ParameterControls params={PatternParams} values={patternValue} onChangeValues={this.updatePattern} />}
+                </ControlGroup>
+            </div>}
+            {this.state.action === 'clip' && <div style={{ marginRight: 5 }} className='msp-accent-offset'>
+                <ControlGroup header='Clip' initialExpanded={true} hideExpander={true} hideOffset={true} onHeaderClick={this.toggleClip}
+                    topRightIcon={CloseSvg} noTopMargin childrenClassName='msp-viewport-controls-panel-controls'>
+                    <ParameterMappingControl mapping={this.clipMapping} />
+                    {lodValue && <ParameterControls params={LodParams} values={lodValue} onChangeValues={this.updateLod} />}
+                </ControlGroup>
+            </div>}
+        </>;
+    }
+}
+
+

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

@@ -0,0 +1,98 @@
+/**
+ * Copyright (c) 2022-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ */
+
+import { Mp4EncoderUI } from '../../../extensions/mp4-export/ui';
+import { PluginUIComponent } from '../../../mol-plugin-ui/base';
+import { SectionHeader } from '../../../mol-plugin-ui/controls/common';
+import { MesoscaleExplorerState } from '../app';
+import { MesoscaleState } from '../data/state';
+import { EntityControls, ModelInfo, SelectionInfo } from './entities';
+import { LoaderControls, ExampleControls, SessionControls, SnapshotControls, DatabaseControls } from './states';
+
+const Spacer = () => <div style={{ height: '2em' }} />;
+
+export class LeftPanel extends PluginUIComponent {
+    render() {
+        const customState = this.plugin.customState as MesoscaleExplorerState;
+
+        return <div className='msp-scrollable-container'>
+            <SectionHeader title='Database' />
+            <DatabaseControls />
+            <Spacer />
+
+            <SectionHeader title='Open' />
+            <LoaderControls />
+            <Spacer />
+
+            {customState.examples?.length && <>
+                <SectionHeader title='Example' />
+                <ExampleControls />
+                <Spacer />
+            </>}
+
+            <SectionHeader title='Session' />
+            <SessionControls />
+            <Spacer />
+
+            <SectionHeader title='Snapshots' />
+            <SnapshotControls />
+            <Spacer />
+
+            <Mp4EncoderUI />
+        </div>;
+    }
+}
+
+export class RightPanel extends PluginUIComponent<{}, { isDisabled: boolean }> {
+    state = {
+        isDisabled: false,
+    };
+
+    get hasModelInfo() {
+        return (
+            MesoscaleState.has(this.plugin) &&
+            !!(MesoscaleState.get(this.plugin).description ||
+                MesoscaleState.get(this.plugin).link)
+        );
+    }
+
+    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();
+            }
+        });
+
+        this.subscribe(this.plugin.managers.structure.selection.events.changed, e => {
+            if (!this.state.isDisabled) {
+                this.forceUpdate();
+            }
+        });
+    }
+
+    render() {
+        return <div className='msp-scrollable-container'>
+            {this.hasModelInfo && <>
+                <SectionHeader title='Model' />
+                <ModelInfo />
+                <Spacer />
+            </>}
+
+            <>
+                <SectionHeader title='Selection' />
+                <SelectionInfo />
+                <Spacer />
+            </>
+
+            <SectionHeader title='Entities' />
+            <EntityControls />
+        </div>;
+    }
+}

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

@@ -0,0 +1,363 @@
+/**
+ * Copyright (c) 2022-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ */
+
+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 { ApplyActionControl } from '../../../mol-plugin-ui/state/apply-action';
+import { LocalStateSnapshotList, LocalStateSnapshotParams, LocalStateSnapshots } from '../../../mol-plugin-ui/state/snapshots';
+import { PluginCommands } from '../../../mol-plugin/commands';
+import { PluginContext } from '../../../mol-plugin/context';
+import { StateAction, StateObjectRef, StateTransform } from '../../../mol-state';
+import { Task } from '../../../mol-task';
+import { Color } from '../../../mol-util/color/color';
+import { getFileNameInfo } from '../../../mol-util/file-info';
+import { ParamDefinition as PD } from '../../../mol-util/param-definition';
+import { ExampleEntry, MesoscaleExplorerState } from '../app';
+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';
+
+function adjustPluginProps(ctx: PluginContext) {
+    ctx.managers.interactivity.setProps({ granularity: 'chain' });
+    ctx.canvas3d?.setProps({
+        multiSample: { mode: 'off' },
+        cameraClipping: { far: false, minNear: 50 },
+        sceneRadiusFactor: 2,
+        renderer: {
+            colorMarker: true,
+            highlightColor: Color(0xffffff),
+            highlightStrength: 0,
+            selectColor: Color(0xffffff),
+            selectStrength: 0,
+            dimColor: Color(0xffffff),
+            dimStrength: 1,
+            markerPriority: 2,
+            interiorColorFlag: false,
+            interiorDarkening: 0.15,
+            exposure: 1.1,
+            xrayEdgeFalloff: 3,
+        },
+        marking: {
+            enabled: true,
+            highlightEdgeColor: Color(0x999999),
+            selectEdgeColor: Color(0xffff00),
+            highlightEdgeStrength: 1,
+            selectEdgeStrength: 1,
+            ghostEdgeStrength: 1,
+            innerEdgeFactor: 2.5,
+            edgeScale: 2,
+        },
+        postprocessing: {
+            occlusion: {
+                name: 'on',
+                params: {
+                    samples: 32,
+                    multiScale: {
+                        name: 'on',
+                        params: {
+                            levels: [
+                                { radius: 2, bias: 1.0 },
+                                { radius: 5, bias: 1.0 },
+                                { radius: 8, bias: 1.0 },
+                                { radius: 11, bias: 1.0 },
+                            ],
+                            nearThreshold: 10,
+                            farThreshold: 1500,
+                        }
+                    },
+                    radius: 5,
+                    bias: 1,
+                    blurKernelSize: 11,
+                    resolutionScale: 1,
+                    color: Color(0x000000),
+                }
+            },
+            shadow: {
+                name: 'on',
+                params: {
+                    bias: 0.6,
+                    maxDistance: 80,
+                    steps: 3,
+                    tolerance: 1.0,
+                }
+            },
+            outline: {
+                name: 'on',
+                params: {
+                    scale: 1,
+                    threshold: 0.15,
+                    color: Color(0x000000),
+                    includeTransparent: false,
+                }
+            }
+        }
+    });
+
+    const { graphics } = MesoscaleState.get(ctx);
+    setGraphicsCanvas3DProps(ctx, graphics);
+}
+
+async function createHierarchy(ctx: PluginContext, ref: string) {
+    const parsed = await MmcifProvider.parse(ctx, ref);
+
+    const tr = StateObjectRef.resolveAndCheck(ctx.state.data, parsed.trajectory)?.obj?.data;
+    if (!tr) throw new Error('no trajectory');
+
+    if (!MmcifFormat.is(tr.representative.sourceData)) {
+        throw new Error('not mmcif');
+    }
+
+    const { frame, db } = tr.representative.sourceData.data;
+
+    let hasCellpackAssemblyMethodDetails = false;
+    const { method_details } = db.pdbx_struct_assembly;
+    for (let i = 0, il = method_details.rowCount; i < il; ++i) {
+        if (method_details.value(i).toUpperCase() === 'CELLPACK') {
+            hasCellpackAssemblyMethodDetails = true;
+            break;
+        }
+    }
+
+    if (frame.categories.pdbx_model) {
+        await createPetworldHierarchy(ctx, parsed.trajectory);
+    } else if (
+        frame.header.toUpperCase().includes('CELLPACK') ||
+        hasCellpackAssemblyMethodDetails
+    ) {
+        await createCellpackHierarchy(ctx, parsed.trajectory);
+    } else {
+        await createMmcifHierarchy(ctx, parsed.trajectory);
+    }
+}
+
+async function reset(ctx: PluginContext) {
+    const customState = ctx.customState as MesoscaleExplorerState;
+    delete customState.stateRef;
+    customState.stateCache = {};
+    ctx.managers.asset.clear();
+
+    await PluginCommands.State.Snapshots.Clear(ctx);
+    await PluginCommands.State.RemoveObject(ctx, { state: ctx.state.data, ref: StateTransform.RootRef });
+
+    await MesoscaleState.init(ctx);
+    adjustPluginProps(ctx);
+}
+
+export async function loadExampleEntry(ctx: PluginContext, entry: ExampleEntry) {
+    const { url, type } = entry;
+    await loadUrl(ctx, url, type);
+    MesoscaleState.set(ctx, {
+        description: entry.description || entry.label,
+        link: entry.link,
+    });
+}
+
+export async function loadUrl(ctx: PluginContext, url: string, type: 'molx' | 'molj' | 'cif' | 'bcif') {
+    if (type === 'molx' || type === 'molj') {
+        await PluginCommands.State.Snapshots.OpenUrl(ctx, { url, type });
+    } else {
+        await reset(ctx);
+        const isBinary = type === 'bcif';
+        const data = await ctx.builders.data.download({ url, isBinary });
+        await createHierarchy(ctx, data.ref);
+    }
+}
+
+export async function loadPdb(ctx: PluginContext, id: string) {
+    await reset(ctx);
+    const url = `https://models.rcsb.org/${id.toUpperCase()}.bcif`;
+    const data = await ctx.builders.data.download({ url, isBinary: true });
+    await createHierarchy(ctx, data.ref);
+}
+
+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`;
+    const data = await ctx.builders.data.download({ url, isBinary: true });
+    await createHierarchy(ctx, data.ref);
+}
+
+//
+
+export const LoadDatabase = StateAction.build({
+    display: { name: 'Database', description: 'Load from Database' },
+    params: (a, ctx: PluginContext) => {
+        return {
+            source: PD.Select('pdb', PD.objectToOptions({ pdb: 'PDB', pdbDev: 'PDB-Dev' })),
+            entry: PD.Text(''),
+        };
+    },
+    from: PluginStateObject.Root
+})(({ params }, ctx: PluginContext) => Task.create('Loading from database...', async taskCtx => {
+    if (params.source === 'pdb') {
+        await loadPdb(ctx, params.entry);
+    } else if (params.source === 'pdbDev') {
+        await loadPdbDev(ctx, params.entry);
+    }
+}));
+
+export const LoadExample = StateAction.build({
+    display: { name: 'Load', description: 'Load an example' },
+    params: (a, ctx: PluginContext) => {
+        const entries = (ctx.customState as MesoscaleExplorerState).examples || [];
+        return {
+            entry: PD.Select(0, entries.map((s, i) => [i, s.label])),
+        };
+    },
+    from: PluginStateObject.Root
+})(({ params }, ctx: PluginContext) => Task.create('Loading example...', async taskCtx => {
+    const entries = (ctx.customState as MesoscaleExplorerState).examples || [];
+    await loadExampleEntry(ctx, entries[params.entry]);
+}));
+
+export const LoadModel = StateAction.build({
+    display: { name: 'Load', description: 'Load a model' },
+    params: {
+        files: PD.FileList({ accept: '.cif,.bcif,.cif.gz,.bcif.gz,.zip', multiple: true, description: 'mmCIF or Cellpack- or Petworld-style cif file.', label: 'File(s)' }),
+    },
+    from: PluginStateObject.Root
+})(({ params }, ctx: PluginContext) => Task.create('Loading model...', async taskCtx => {
+    if (params.files === null || params.files.length === 0) {
+        ctx.log.error('No file(s) selected');
+        return;
+    }
+
+    await reset(ctx);
+
+    const firstFile = params.files[0];
+    const firstInfo = getFileNameInfo(firstFile.file!.name);
+
+    if (firstInfo.name.endsWith('zip')) {
+        try {
+            await createGenericHierarchy(ctx, firstFile);
+        } catch (e) {
+            console.error(e);
+            ctx.log.error(`Error opening file '${firstFile.name}'`);
+        }
+    } else {
+        for (const file of params.files) {
+            try {
+                const info = getFileNameInfo(file.file!.name);
+                if (!['cif', 'bcif'].includes(info.ext)) continue;
+
+                const isBinary = ctx.dataFormats.binaryExtensions.has(info.ext);
+                const { data } = await ctx.builders.data.readFile({ file, isBinary });
+                await createHierarchy(ctx, data.ref);
+            } catch (e) {
+                console.error(e);
+                ctx.log.error(`Error opening file '${file.name}'`);
+            }
+        }
+    }
+}));
+
+//
+
+export class DatabaseControls extends PluginUIComponent {
+    componentDidMount() {
+
+    }
+
+    render() {
+        return <div style={{ margin: '5px' }}>
+            <ApplyActionControl state={this.plugin.state.data} action={LoadDatabase} nodeRef={this.plugin.state.data.tree.root.ref} applyLabel={'Load'} hideHeader />
+        </div>;
+    }
+}
+
+export class LoaderControls extends PluginUIComponent {
+    componentDidMount() {
+
+    }
+
+    render() {
+        return <div style={{ margin: '5px' }}>
+            <ApplyActionControl state={this.plugin.state.data} action={LoadModel} nodeRef={this.plugin.state.data.tree.root.ref} applyLabel={'Load'} hideHeader />
+        </div>;
+    }
+}
+
+export class ExampleControls extends PluginUIComponent {
+    componentDidMount() {
+
+    }
+
+    render() {
+        return <div style={{ margin: '5px' }}>
+            <ApplyActionControl state={this.plugin.state.data} action={LoadExample} nodeRef={this.plugin.state.data.tree.root.ref} applyLabel={'Load'} hideHeader />
+        </div>;
+    }
+}
+
+export async function openState(ctx: PluginContext, file: File) {
+    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.OpenFile(ctx, { file });
+
+    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;
+}
+
+export class SessionControls extends PluginUIComponent {
+    downloadToFileZip = () => {
+        PluginCommands.State.Snapshots.DownloadToFile(this.plugin, { type: 'zip' });
+    };
+
+    open = (e: React.ChangeEvent<HTMLInputElement>) => {
+        if (!e.target.files || !e.target.files[0]) {
+            this.plugin.log.error('No state file selected');
+            return;
+        }
+
+        openState(this.plugin, e.target.files[0]);
+    };
+
+    render() {
+        return <div style={{ margin: '5px' }}>
+            <div className='msp-flex-row'>
+                <Button icon={GetAppSvg} onClick={this.downloadToFileZip} title='Download the state.'>
+                    Download
+                </Button>
+                <div className='msp-btn msp-btn-block msp-btn-action msp-loader-msp-btn-file'>
+                    <Icon svg={OpenInBrowserSvg} inline /> Open <input onChange={this.open} type='file' multiple={false} accept='.molx,.molj' />
+                </div>
+            </div>
+        </div>;
+    }
+}
+
+export class SnapshotControls extends PluginUIComponent<{}> {
+    render() {
+        return <div style={{ margin: '5px' }}>
+            <div style={{ marginBottom: '10px' }}>
+                <LocalStateSnapshotList />
+            </div>
+            <div style={{ marginBottom: '10px' }}>
+                <LocalStateSnapshots />
+            </div>
+
+            <div style={{ marginBottom: '10px' }}>
+                <ExpandGroup header='Snapshot Options' initiallyExpanded={false}>
+                    <LocalStateSnapshotParams />
+                </ExpandGroup>
+            </div>
+        </div>;
+    }
+}

src/apps/viewer/app.ts

@@ -0,0 +1,581 @@
+/**
+ * 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>
+ */
+
+import { ANVILMembraneOrientation } from '../../extensions/anvil/behavior';
+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 { 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 { loadMVSX } from '../../extensions/mvs/components/formats';
+import { loadMVS } 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 { Volseg, VolsegVolumeServerConfig } from '../../extensions/volumes-and-segmentations';
+import { wwPDBChemicalComponentDictionary } from '../../extensions/wwpdb/ccd/behavior';
+import { wwPDBStructConnExtensionFunctions } from '../../extensions/wwpdb/struct-conn';
+import { ZenodoImport } from '../../extensions/zenodo';
+import { SaccharideCompIdMapType } from '../../mol-model/structure/structure/carbohydrates/constants';
+import { Volume } from '../../mol-model/volume';
+import { DownloadStructure, PdbDownloadProvider } from '../../mol-plugin-state/actions/structure';
+import { DownloadDensity } from '../../mol-plugin-state/actions/volume';
+import { PresetTrajectoryHierarchy } from '../../mol-plugin-state/builder/structure/hierarchy-preset';
+import { PresetStructureRepresentations, StructureRepresentationPresetProvider } from '../../mol-plugin-state/builder/structure/representation-preset';
+import { BuiltInCoordinatesFormat } from '../../mol-plugin-state/formats/coordinates';
+import { DataFormatProvider } from '../../mol-plugin-state/formats/provider';
+import { BuiltInTopologyFormat } from '../../mol-plugin-state/formats/topology';
+import { BuiltInTrajectoryFormat } from '../../mol-plugin-state/formats/trajectory';
+import { BuildInVolumeFormat } from '../../mol-plugin-state/formats/volume';
+import { createVolumeRepresentationParams } from '../../mol-plugin-state/helpers/volume-representation-params';
+import { PluginStateObject } from '../../mol-plugin-state/objects';
+import { StateTransforms } from '../../mol-plugin-state/transforms';
+import { TrajectoryFromModelAndCoordinates } from '../../mol-plugin-state/transforms/model';
+import { PluginUIContext } from '../../mol-plugin-ui/context';
+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 { 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';
+import { ObjectKeys } from '../../mol-util/type-helpers';
+
+export { PLUGIN_VERSION as version } from '../../mol-plugin/version';
+export { consoleStats, setDebugMode, setProductionMode, setTimingMode } from '../../mol-util/debug';
+
+const CustomFormats = [
+    ['g3d', G3dProvider] as const
+];
+
+export const ExtensionMap = {
+    'volseg': PluginSpec.Behavior(Volseg),
+    'backgrounds': PluginSpec.Behavior(Backgrounds),
+    'dnatco-ntcs': PluginSpec.Behavior(DnatcoNtCs),
+    'pdbe-structure-quality-report': PluginSpec.Behavior(PDBeStructureQualityReport),
+    'assembly-symmetry': PluginSpec.Behavior(AssemblySymmetry),
+    'rcsb-validation-report': PluginSpec.Behavior(RCSBValidationReport),
+    'anvil-membrane-orientation': PluginSpec.Behavior(ANVILMembraneOrientation),
+    'g3d': PluginSpec.Behavior(G3DFormat),
+    'model-export': PluginSpec.Behavior(ModelExport),
+    'mp4-export': PluginSpec.Behavior(Mp4Export),
+    'geo-export': PluginSpec.Behavior(GeometryExport),
+    'ma-quality-assessment': PluginSpec.Behavior(MAQualityAssessment),
+    'zenodo-import': PluginSpec.Behavior(ZenodoImport),
+    'sb-ncbr-partial-charges': PluginSpec.Behavior(SbNcbrPartialCharges),
+    'wwpdb-chemical-component-dictionary': PluginSpec.Behavior(wwPDBChemicalComponentDictionary),
+    'mvs': PluginSpec.Behavior(MolViewSpec),
+};
+
+const DefaultViewerOptions = {
+    customFormats: CustomFormats as [string, DataFormatProvider][],
+    extensions: ObjectKeys(ExtensionMap),
+    disabledExtensions: [] as string[],
+    layoutIsExpanded: true,
+    layoutShowControls: true,
+    layoutShowRemoteState: true,
+    layoutControlsDisplay: 'reactive' as PluginLayoutControlsDisplay,
+    layoutShowSequence: true,
+    layoutShowLog: true,
+    layoutShowLeftPanel: true,
+    collapseLeftPanel: false,
+    collapseRightPanel: false,
+    disableAntialiasing: PluginConfig.General.DisableAntialiasing.defaultValue,
+    pixelScale: PluginConfig.General.PixelScale.defaultValue,
+    pickScale: PluginConfig.General.PickScale.defaultValue,
+    transparency: PluginConfig.General.Transparency.defaultValue,
+    preferWebgl1: PluginConfig.General.PreferWebGl1.defaultValue,
+    allowMajorPerformanceCaveat: PluginConfig.General.AllowMajorPerformanceCaveat.defaultValue,
+    powerPreference: PluginConfig.General.PowerPreference.defaultValue,
+
+    viewportShowExpand: PluginConfig.Viewport.ShowExpand.defaultValue,
+    viewportShowControls: PluginConfig.Viewport.ShowControls.defaultValue,
+    viewportShowSettings: PluginConfig.Viewport.ShowSettings.defaultValue,
+    viewportShowSelectionMode: PluginConfig.Viewport.ShowSelectionMode.defaultValue,
+    viewportShowAnimation: PluginConfig.Viewport.ShowAnimation.defaultValue,
+    viewportShowTrajectoryControls: PluginConfig.Viewport.ShowTrajectoryControls.defaultValue,
+    pluginStateServer: PluginConfig.State.DefaultServer.defaultValue,
+    volumeStreamingServer: PluginConfig.VolumeStreaming.DefaultServer.defaultValue,
+    volumeStreamingDisabled: !PluginConfig.VolumeStreaming.Enabled.defaultValue,
+    pdbProvider: PluginConfig.Download.DefaultPdbProvider.defaultValue,
+    emdbProvider: PluginConfig.Download.DefaultEmdbProvider.defaultValue,
+    saccharideCompIdMapType: 'default' as SaccharideCompIdMapType,
+    volumesAndSegmentationsDefaultServer: VolsegVolumeServerConfig.DefaultServer.defaultValue,
+    rcsbAssemblySymmetryDefaultServerType: AssemblySymmetryConfig.DefaultServerType.defaultValue,
+    rcsbAssemblySymmetryDefaultServerUrl: AssemblySymmetryConfig.DefaultServerUrl.defaultValue,
+    rcsbAssemblySymmetryApplyColors: AssemblySymmetryConfig.ApplyColors.defaultValue,
+};
+type ViewerOptions = typeof DefaultViewerOptions;
+
+export class Viewer {
+    constructor(public plugin: PluginUIContext) {
+    }
+
+    static async create(elementOrId: string | HTMLElement, options: Partial<ViewerOptions> = {}) {
+        const definedOptions = {} as any;
+        // filter for defined properies only so the default values
+        // are property applied
+        for (const p of Object.keys(options) as (keyof ViewerOptions)[]) {
+            if (options[p] !== void 0) definedOptions[p] = options[p];
+        }
+
+        const o: ViewerOptions = { ...DefaultViewerOptions, ...definedOptions };
+        const defaultSpec = DefaultPluginUISpec();
+
+        const disabledExtension = new Set(o.disabledExtensions ?? []);
+
+        const spec: PluginUISpec = {
+            actions: defaultSpec.actions,
+            behaviors: [
+                ...defaultSpec.behaviors,
+                ...o.extensions.filter(e => !disabledExtension.has(e)).map(e => ExtensionMap[e]),
+            ],
+            animations: [...defaultSpec.animations || []],
+            customParamEditors: defaultSpec.customParamEditors,
+            customFormats: o?.customFormats,
+            layout: {
+                initial: {
+                    isExpanded: o.layoutIsExpanded,
+                    showControls: o.layoutShowControls,
+                    controlsDisplay: o.layoutControlsDisplay,
+                    regionState: {
+                        bottom: 'full',
+                        left: o.collapseLeftPanel ? 'collapsed' : 'full',
+                        right: o.collapseRightPanel ? 'hidden' : 'full',
+                        top: 'full',
+                    }
+                },
+            },
+            components: {
+                ...defaultSpec.components,
+                controls: {
+                    ...defaultSpec.components?.controls,
+                    top: o.layoutShowSequence ? undefined : 'none',
+                    bottom: o.layoutShowLog ? undefined : 'none',
+                    left: o.layoutShowLeftPanel ? undefined : 'none',
+                },
+                remoteState: o.layoutShowRemoteState ? 'default' : 'none',
+            },
+            config: [
+                [PluginConfig.General.DisableAntialiasing, o.disableAntialiasing],
+                [PluginConfig.General.PixelScale, o.pixelScale],
+                [PluginConfig.General.PickScale, o.pickScale],
+                [PluginConfig.General.Transparency, o.transparency],
+                [PluginConfig.General.PreferWebGl1, o.preferWebgl1],
+                [PluginConfig.General.AllowMajorPerformanceCaveat, o.allowMajorPerformanceCaveat],
+                [PluginConfig.General.PowerPreference, o.powerPreference],
+                [PluginConfig.Viewport.ShowExpand, o.viewportShowExpand],
+                [PluginConfig.Viewport.ShowControls, o.viewportShowControls],
+                [PluginConfig.Viewport.ShowSettings, o.viewportShowSettings],
+                [PluginConfig.Viewport.ShowSelectionMode, o.viewportShowSelectionMode],
+                [PluginConfig.Viewport.ShowAnimation, o.viewportShowAnimation],
+                [PluginConfig.Viewport.ShowTrajectoryControls, o.viewportShowTrajectoryControls],
+                [PluginConfig.State.DefaultServer, o.pluginStateServer],
+                [PluginConfig.State.CurrentServer, o.pluginStateServer],
+                [PluginConfig.VolumeStreaming.DefaultServer, o.volumeStreamingServer],
+                [PluginConfig.VolumeStreaming.Enabled, !o.volumeStreamingDisabled],
+                [PluginConfig.Download.DefaultPdbProvider, o.pdbProvider],
+                [PluginConfig.Download.DefaultEmdbProvider, o.emdbProvider],
+                [PluginConfig.Structure.DefaultRepresentationPreset, ViewerAutoPreset.id],
+                [PluginConfig.Structure.SaccharideCompIdMapType, o.saccharideCompIdMapType],
+                [VolsegVolumeServerConfig.DefaultServer, o.volumesAndSegmentationsDefaultServer],
+                [AssemblySymmetryConfig.DefaultServerType, o.rcsbAssemblySymmetryDefaultServerType],
+                [AssemblySymmetryConfig.DefaultServerUrl, o.rcsbAssemblySymmetryDefaultServerUrl],
+                [AssemblySymmetryConfig.ApplyColors, o.rcsbAssemblySymmetryApplyColors],
+            ]
+        };
+
+        const element = typeof elementOrId === 'string'
+            ? document.getElementById(elementOrId)
+            : elementOrId;
+        if (!element) throw new Error(`Could not get element with id '${elementOrId}'`);
+        const plugin = await createPluginUI({
+            target: element,
+            spec,
+            render: renderReact18,
+            onBeforeUIRender: plugin => {
+                // the preset needs to be added before the UI renders otherwise
+                // "Download Structure" wont be able to pick it up
+                plugin.builders.structure.representation.registerPreset(ViewerAutoPreset);
+            }
+        });
+        return new Viewer(plugin);
+    }
+
+    setRemoteSnapshot(id: string) {
+        const url = `${this.plugin.config.get(PluginConfig.State.CurrentServer)}/get/${id}`;
+        return PluginCommands.State.Snapshots.Fetch(this.plugin, { url });
+    }
+
+    loadSnapshotFromUrl(url: string, type: PluginState.SnapshotType) {
+        return PluginCommands.State.Snapshots.OpenUrl(this.plugin, { url, type });
+    }
+
+    loadStructureFromUrl(url: string, format: BuiltInTrajectoryFormat = 'mmcif', isBinary = false, options?: LoadStructureOptions & { label?: string }) {
+        const params = DownloadStructure.createDefaultParams(this.plugin.state.data.root.obj!, this.plugin);
+        return this.plugin.runTask(this.plugin.state.data.applyAction(DownloadStructure, {
+            source: {
+                name: 'url',
+                params: {
+                    url: Asset.Url(url),
+                    format: format as any,
+                    isBinary,
+                    label: options?.label,
+                    options: { ...params.source.params.options, representationParams: options?.representationParams as any },
+                }
+            }
+        }));
+    }
+
+    async loadAllModelsOrAssemblyFromUrl(url: string, format: BuiltInTrajectoryFormat = 'mmcif', isBinary = false, options?: LoadStructureOptions) {
+        const plugin = this.plugin;
+
+        const data = await plugin.builders.data.download({ url, isBinary }, { state: { isGhost: true } });
+        const trajectory = await plugin.builders.structure.parseTrajectory(data, format);
+
+        await this.plugin.builders.structure.hierarchy.applyPreset(trajectory, 'all-models', { useDefaultIfSingleModel: true, representationPresetParams: options?.representationParams });
+    }
+
+    async loadStructureFromData(data: string | number[], format: BuiltInTrajectoryFormat, options?: { dataLabel?: string }) {
+        const _data = await this.plugin.builders.data.rawData({ data, label: options?.dataLabel });
+        const trajectory = await this.plugin.builders.structure.parseTrajectory(_data, format);
+        await this.plugin.builders.structure.hierarchy.applyPreset(trajectory, 'default');
+    }
+
+    loadPdb(pdb: string, options?: LoadStructureOptions) {
+        const params = DownloadStructure.createDefaultParams(this.plugin.state.data.root.obj!, this.plugin);
+        const provider = this.plugin.config.get(PluginConfig.Download.DefaultPdbProvider)!;
+        return this.plugin.runTask(this.plugin.state.data.applyAction(DownloadStructure, {
+            source: {
+                name: 'pdb' as const,
+                params: {
+                    provider: {
+                        id: pdb,
+                        server: {
+                            name: provider,
+                            params: PdbDownloadProvider[provider].defaultValue as any
+                        }
+                    },
+                    options: { ...params.source.params.options, representationParams: options?.representationParams as any },
+                }
+            }
+        }));
+    }
+
+    loadPdbDev(pdbDev: string) {
+        const params = DownloadStructure.createDefaultParams(this.plugin.state.data.root.obj!, this.plugin);
+        return this.plugin.runTask(this.plugin.state.data.applyAction(DownloadStructure, {
+            source: {
+                name: 'pdb-dev' as const,
+                params: {
+                    provider: {
+                        id: pdbDev,
+                        encoding: 'bcif',
+                    },
+                    options: params.source.params.options,
+                }
+            }
+        }));
+    }
+
+    loadEmdb(emdb: string, options?: { detail?: number }) {
+        const provider = this.plugin.config.get(PluginConfig.Download.DefaultEmdbProvider)!;
+        return this.plugin.runTask(this.plugin.state.data.applyAction(DownloadDensity, {
+            source: {
+                name: 'pdb-emd-ds' as const,
+                params: {
+                    provider: {
+                        id: emdb,
+                        server: provider,
+                    },
+                    detail: options?.detail ?? 3,
+                }
+            }
+        }));
+    }
+
+    loadAlphaFoldDb(afdb: string) {
+        const params = DownloadStructure.createDefaultParams(this.plugin.state.data.root.obj!, this.plugin);
+        return this.plugin.runTask(this.plugin.state.data.applyAction(DownloadStructure, {
+            source: {
+                name: 'alphafolddb' as const,
+                params: {
+                    id: afdb,
+                    options: {
+                        ...params.source.params.options,
+                        representation: 'preset-structure-representation-ma-quality-assessment-plddt'
+                    },
+                }
+            }
+        }));
+    }
+
+    loadModelArchive(id: string) {
+        const params = DownloadStructure.createDefaultParams(this.plugin.state.data.root.obj!, this.plugin);
+        return this.plugin.runTask(this.plugin.state.data.applyAction(DownloadStructure, {
+            source: {
+                name: 'modelarchive' as const,
+                params: {
+                    id,
+                    options: params.source.params.options,
+                }
+            }
+        }));
+    }
+
+    /**
+     * @example Load X-ray density from volume server
+        viewer.loadVolumeFromUrl({
+            url: 'https://www.ebi.ac.uk/pdbe/densities/x-ray/1tqn/cell?detail=3',
+            format: 'dscif',
+            isBinary: true
+        }, [{
+            type: 'relative',
+            value: 1.5,
+            color: 0x3362B2
+        }, {
+            type: 'relative',
+            value: 3,
+            color: 0x33BB33,
+            volumeIndex: 1
+        }, {
+            type: 'relative',
+            value: -3,
+            color: 0xBB3333,
+            volumeIndex: 1
+        }], {
+            entryId: ['2FO-FC', 'FO-FC'],
+            isLazy: true
+        });
+     * *********************
+     * @example Load EM density from volume server
+        viewer.loadVolumeFromUrl({
+            url: 'https://maps.rcsb.org/em/emd-30210/cell?detail=6',
+            format: 'dscif',
+            isBinary: true
+        }, [{
+            type: 'relative',
+            value: 1,
+            color: 0x3377aa
+        }], {
+            entryId: 'EMD-30210',
+            isLazy: true
+        });
+     */
+    async loadVolumeFromUrl({ url, format, isBinary }: { url: string, format: BuildInVolumeFormat, isBinary: boolean }, isovalues: VolumeIsovalueInfo[], options?: { entryId?: string | string[], isLazy?: boolean }) {
+        const plugin = this.plugin;
+
+        if (!plugin.dataFormats.get(format)) {
+            throw new Error(`Unknown density format: ${format}`);
+        }
+
+        if (options?.isLazy) {
+            const update = this.plugin.build();
+            update.toRoot().apply(StateTransforms.Data.LazyVolume, {
+                url,
+                format,
+                entryId: options?.entryId,
+                isBinary,
+                isovalues: isovalues.map(v => ({ alpha: 1, volumeIndex: 0, ...v }))
+            });
+            return update.commit();
+        }
+
+        return plugin.dataTransaction(async () => {
+            const data = await plugin.builders.data.download({ url, isBinary }, { state: { isGhost: true } });
+
+            const parsed = await plugin.dataFormats.get(format)!.parse(plugin, data, { entryId: options?.entryId });
+            const firstVolume = (parsed.volume || parsed.volumes[0]) as StateObjectSelector<PluginStateObject.Volume.Data>;
+            if (!firstVolume?.isOk) throw new Error('Failed to parse any volume.');
+
+            const repr = plugin.build();
+            for (const iso of isovalues) {
+                const volume: StateObjectSelector<PluginStateObject.Volume.Data> = parsed.volumes?.[iso.volumeIndex ?? 0] ?? parsed.volume;
+                const volumeData = volume.cell!.obj!.data;
+                repr
+                    .to(volume)
+                    .apply(StateTransforms.Representation.VolumeRepresentation3D, createVolumeRepresentationParams(this.plugin, firstVolume.data!, {
+                        type: 'isosurface',
+                        typeParams: { alpha: iso.alpha ?? 1, isoValue: Volume.adjustedIsoValue(volumeData, iso.value, iso.type) },
+                        color: 'uniform',
+                        colorParams: { value: iso.color }
+                    }));
+            }
+
+            await repr.commit();
+        });
+    }
+
+    /**
+     * @example
+     *  viewer.loadTrajectory({
+     *      model: { kind: 'model-url', url: 'villin.gro', format: 'gro' },
+     *      coordinates: { kind: 'coordinates-url', url: 'villin.xtc', format: 'xtc', isBinary: true },
+     *      preset: 'all-models' // or 'default'
+     *  });
+     */
+    async loadTrajectory(params: LoadTrajectoryParams) {
+        const plugin = this.plugin;
+
+        let model: StateObjectSelector;
+
+        if (params.model.kind === 'model-data' || params.model.kind === 'model-url') {
+            const data = params.model.kind === 'model-data'
+                ? await plugin.builders.data.rawData({ data: params.model.data, label: params.modelLabel })
+                : await plugin.builders.data.download({ url: params.model.url, isBinary: params.model.isBinary, label: params.modelLabel });
+
+            const trajectory = await plugin.builders.structure.parseTrajectory(data, params.model.format ?? 'mmcif');
+            model = await plugin.builders.structure.createModel(trajectory);
+        } else {
+            const data = params.model.kind === 'topology-data'
+                ? await plugin.builders.data.rawData({ data: params.model.data, label: params.modelLabel })
+                : await plugin.builders.data.download({ url: params.model.url, isBinary: params.model.isBinary, label: params.modelLabel });
+
+            const provider = plugin.dataFormats.get(params.model.format);
+            model = await provider!.parse(plugin, data);
+        }
+
+        const data = params.coordinates.kind === 'coordinates-data'
+            ? await plugin.builders.data.rawData({ data: params.coordinates.data, label: params.coordinatesLabel })
+            : await plugin.builders.data.download({ url: params.coordinates.url, isBinary: params.coordinates.isBinary, label: params.coordinatesLabel });
+
+        const provider = plugin.dataFormats.get(params.coordinates.format);
+        const coords = await provider!.parse(plugin, data);
+
+        const trajectory = await plugin.build().toRoot()
+            .apply(TrajectoryFromModelAndCoordinates, {
+                modelRef: model.ref,
+                coordinatesRef: coords.ref
+            }, { dependsOn: [model.ref, coords.ref] })
+            .commit();
+
+        const preset = await plugin.builders.structure.hierarchy.applyPreset(trajectory, params.preset ?? 'default');
+
+        return { model, coords, preset };
+    }
+
+    async loadMvsFromUrl(url: string, format: 'mvsj' | 'mvsx') {
+        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 });
+        } 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 });
+            }));
+        } else {
+            throw new Error(`Unknown MolViewSpec format: ${format}`);
+        }
+    }
+
+    /** 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') {
+        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 });
+        } 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 });
+            }));
+        } else {
+            throw new Error(`Unknown MolViewSpec format: ${format}`);
+        }
+    }
+
+    handleResize() {
+        this.plugin.layout.events.updated.next(void 0);
+    }
+
+    dispose() {
+        this.plugin.dispose();
+    }
+}
+
+export interface LoadStructureOptions {
+    representationParams?: StructureRepresentationPresetProvider.CommonParams
+}
+
+export interface VolumeIsovalueInfo {
+    type: 'absolute' | 'relative',
+    value: number,
+    color: Color,
+    alpha?: number,
+    volumeIndex?: number
+}
+
+export interface LoadTrajectoryParams {
+    model: { kind: 'model-url', url: string, format?: BuiltInTrajectoryFormat /* mmcif */, isBinary?: boolean }
+    | { kind: 'model-data', data: string | number[] | ArrayBuffer | Uint8Array, format?: BuiltInTrajectoryFormat /* mmcif */ }
+    | { kind: 'topology-url', url: string, format: BuiltInTopologyFormat, isBinary?: boolean }
+    | { kind: 'topology-data', data: string | number[] | ArrayBuffer | Uint8Array, format: BuiltInTopologyFormat },
+    modelLabel?: string,
+    coordinates: { kind: 'coordinates-url', url: string, format: BuiltInCoordinatesFormat, isBinary?: boolean }
+    | { kind: 'coordinates-data', data: string | number[] | ArrayBuffer | Uint8Array, format: BuiltInCoordinatesFormat },
+    coordinatesLabel?: string,
+    preset?: keyof PresetTrajectoryHierarchy
+}
+
+export const ViewerAutoPreset = StructureRepresentationPresetProvider({
+    id: 'preset-structure-representation-viewer-auto',
+    display: {
+        name: 'Automatic (w/ Annotation)', group: 'Annotation',
+        description: 'Show standard automatic representation but colored by quality assessment (if available in the model).'
+    },
+    isApplicable(a) {
+        return (
+            !!a.data.models.some(m => QualityAssessment.isApplicable(m, 'pLDDT')) ||
+            !!a.data.models.some(m => QualityAssessment.isApplicable(m, 'qmean'))
+        );
+    },
+    params: () => StructureRepresentationPresetProvider.CommonParams,
+    async apply(ref, params, plugin) {
+        const structureCell = StateObjectRef.resolveAndCheck(plugin.state.data, ref);
+        const structure = structureCell?.obj?.data;
+        if (!structureCell || !structure) return {};
+
+        if (!!structure.models.some(m => QualityAssessment.isApplicable(m, 'pLDDT'))) {
+            return await QualityAssessmentPLDDTPreset.apply(ref, params, plugin);
+        } else if (!!structure.models.some(m => QualityAssessment.isApplicable(m, 'qmean'))) {
+            return await QualityAssessmentQmeanPreset.apply(ref, params, plugin);
+        } else if (!!structure.models.some(m => SbNcbrPartialChargesPropertyProvider.isApplicable(m))) {
+            return await SbNcbrPartialChargesPreset.apply(ref, params, plugin);
+        } else {
+            return await PresetStructureRepresentations.auto.apply(ref, params, plugin);
+        }
+    }
+});
+
+export const PluginExtensions = {
+    wwPDBStructConn: wwPDBStructConnExtensionFunctions,
+    mvs: { MVSData, loadMVS },
+};

src/apps/viewer/embedded.html

@@ -20,8 +20,8 @@
         <div id="app"></div>
         <script type="text/javascript" src="./molstar.js"></script>
         <script type="text/javascript">
-            var viewer = new molstar.Viewer('app', {
-                layoutIsExpanded: false,
+            molstar.Viewer.create('app', {
+                layoutIsExpanded: true,
                 layoutShowControls: false,
                 layoutShowRemoteState: false,
                 layoutShowSequence: true,
@@ -34,10 +34,20 @@
 
                 pdbProvider: 'rcsb',
                 emdbProvider: 'rcsb',
+            }).then(viewer => {
+                viewer.loadPdb('7bv2');
+                viewer.loadEmdb('EMD-30210', { detail: 6 });
+                // viewer.loadAllModelsOrAssemblyFromUrl('https://cs.litemol.org/5ire/full', 'mmcif', false, { representationParams: { theme: { globalName: 'operator-name' } } })
+                // viewer.loadStructureFromUrl('my url', 'pdb', false, {
+                //     representationParams: {
+                //         theme: {
+                //             globalName: 'uniform',
+                //             globalColorParams: { value: 0xff0000 }
+                //         }
+                //     },
+                //     label: 'my structure'
+                // });
             });
-            viewer.loadPdb('7bv2');
-            viewer.loadEmdb('EMD-30210', { detail: 6 });
-            // viewer.loadAllModelsOrAssemblyFromUrl('https://cs.litemol.org/5ire/full', 'mmcif', false, { representationParams: { theme: { globalName: 'operator-name' } } })
         </script>
     </body>
 </html>

src/apps/viewer/index.html

@@ -46,44 +46,85 @@
             }
 
             var debugMode = getParam('debug-mode', '[^&]+').trim() === '1';
-            if (debugMode) molstar.setDebugMode(debugMode, debugMode);
+            if (debugMode) molstar.setDebugMode(debugMode);
+
+            var timingMode = getParam('timing-mode', '[^&]+').trim() === '1';
+            if (timingMode) molstar.setTimingMode(timingMode);
 
-            var disableAntialiasing = getParam('disable-antialiasing', '[^&]+').trim() === '1';
-            var pixelScale = parseFloat(getParam('pixel-scale', '[^&]+').trim() || '1');
-            var disableWboit = getParam('disable-wboit', '[^&]+').trim() === '1';
             var hideControls = getParam('hide-controls', '[^&]+').trim() === '1';
+            var collapseLeftPanel = getParam('collapse-left-panel', '[^&]+').trim() === '1';
             var pdbProvider = getParam('pdb-provider', '[^&]+').trim().toLowerCase();
             var emdbProvider = getParam('emdb-provider', '[^&]+').trim().toLowerCase();
-            var viewer = new molstar.Viewer('app', {
-                disableAntialiasing: disableAntialiasing,
-                pixelScale: pixelScale,
-                enableWboit: !disableWboit,
+            var mapProvider = getParam('map-provider', '[^&]+').trim().toLowerCase();
+            var pixelScale = getParam('pixel-scale', '[^&]+').trim();
+            var pickScale = getParam('pick-scale', '[^&]+').trim();
+            var pickPadding = getParam('pick-padding', '[^&]+').trim();
+            var transparency = getParam('transparency', '[^&]+').trim().toLowerCase();
+            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();
+
+            // console.log('Available extensions: ', Object.keys(molstar.ExtensionMap));
+
+            molstar.Viewer.create('app', {
+                disabledExtensions: [], // anything from Object.keys(molstar.ExtensionMap)
                 layoutShowControls: !hideControls,
                 viewportShowExpand: false,
+                collapseLeftPanel: collapseLeftPanel,
                 pdbProvider: pdbProvider || 'pdbe',
                 emdbProvider: emdbProvider || 'pdbe',
+                volumeStreamingServer: (mapProvider || 'pdbe') === 'rcsb'
+                    ? 'https://maps.rcsb.org'
+                    : 'https://www.ebi.ac.uk/pdbe/densities',
+                pixelScale: parseFloat(pixelScale) || 1,
+                pickScale: parseFloat(pickScale) || 0.25,
+                pickPadding: isNaN(parseFloat(pickPadding)) ? 1 : parseFloat(pickPadding),
+                transparency: transparency || undefined,
+                preferWebgl1: preferWebgl1,
+                allowMajorPerformanceCaveat: allowMajorPerformanceCaveat,
+                powerPreference: powerPreference || 'high-performance',
+            }).then(viewer => {
+                var snapshotId = getParam('snapshot-id', '[^&]+').trim();
+                if (snapshotId) viewer.setRemoteSnapshot(snapshotId);
+
+                var snapshotUrl = getParam('snapshot-url', '[^&]+').trim();
+                var snapshotUrlType = getParam('snapshot-url-type', '[^&]+').toLowerCase().trim() || 'molj';
+                if (snapshotUrl && snapshotUrlType) viewer.loadSnapshotFromUrl(snapshotUrl, snapshotUrlType);
+
+                var structureUrl = getParam('structure-url', '[^&]+').trim();
+                var structureUrlFormat = getParam('structure-url-format', '[a-z]+').toLowerCase().trim();
+                var structureUrlIsBinary = getParam('structure-url-is-binary', '[^&]+').trim() === '1';
+                if (structureUrl) viewer.loadStructureFromUrl(structureUrl, structureUrlFormat, structureUrlIsBinary);
+
+                var mvsUrl = getParam('mvs-url', '[^&]+').trim();
+                var mvsData = getParam('mvs-data', '[^&]+').trim();
+                var mvsFormat = getParam('mvs-format', '[^&]+').trim() || 'mvsj';
+                if (mvsUrl && mvsData) console.error('Cannot specify mvs-url and mvs-data URL parameters at the same time. Ignoring both.');
+                else if (mvsUrl) viewer.loadMvsFromUrl(mvsUrl, mvsFormat);
+                else if (mvsData) viewer.loadMvsData(mvsData, mvsFormat);
+
+
+                var pdb = getParam('pdb', '[^&]+').trim();
+                if (pdb) viewer.loadPdb(pdb);
+
+                var pdbDev = getParam('pdb-dev', '[^&]+').trim();
+                if (pdbDev) viewer.loadPdbDev(pdbDev);
+
+                var emdb = getParam('emdb', '[^&]+').trim();
+                if (emdb) viewer.loadEmdb(emdb);
+
+                var afdb = getParam('afdb', '[^&]+').trim();
+                if (afdb) viewer.loadAlphaFoldDb(afdb);
+
+                var modelArchive = getParam('model-archive', '[^&]+').trim();
+                if (modelArchive) viewer.loadModelArchive(modelArchive);
+
+                window.addEventListener('unload', () => {
+                    // to aid GC
+                    viewer.dispose();
+                });
             });
-
-            var snapshotId = getParam('snapshot-id', '[^&]+').trim();
-            if (snapshotId) viewer.setRemoteSnapshot(snapshotId);
-
-            var snapshotUrl = getParam('snapshot-url', '[^&]+').trim();
-            var snapshotUrlType = getParam('snapshot-url-type', '[^&]+').toLowerCase().trim() || 'molj';
-            if (snapshotUrl && snapshotUrlType) viewer.loadSnapshotFromUrl(snapshotUrl, snapshotUrlType);
-
-            var structureUrl = getParam('structure-url', '[^&]+').trim();
-            var structureUrlFormat = getParam('structure-url-format', '[a-z]+').toLowerCase().trim();
-            var structureUrlIsBinary = getParam('structure-url-is-binary', '[^&]+').trim() === '1';
-            if (structureUrl) viewer.loadStructureFromUrl(structureUrl, structureUrlFormat, structureUrlIsBinary);
-
-            var pdb = getParam('pdb', '[^&]+').trim();
-            if (pdb) viewer.loadPdb(pdb);
-
-            var pdbDev = getParam('pdb-dev', '[^&]+').trim();
-            if (pdbDev) viewer.loadPdbDev(pdbDev);
-
-            var emdb = getParam('emdb', '[^&]+').trim();
-            if (emdb) viewer.loadEmdb(emdb);
         </script>
+        <!-- __MOLSTAR_ANALYTICS__ -->
     </body>
 </html>

src/apps/viewer/index.ts

@@ -1,279 +1,12 @@
 /**
- * Copyright (c) 2018-2020 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2018-2022 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>
  */
 
-import '../../mol-util/polyfill';
-import { createPlugin } from '../../mol-plugin';
-import { DefaultPluginSpec } from '../../mol-plugin/spec';
-import './index.html';
 import './embedded.html';
 import './favicon.ico';
-import { PluginContext } from '../../mol-plugin/context';
-import { PluginCommands } from '../../mol-plugin/commands';
-import { PluginSpec } from '../../mol-plugin/spec';
-import { DownloadStructure, PdbDownloadProvider } from '../../mol-plugin-state/actions/structure';
-import { PluginConfig } from '../../mol-plugin/config';
-import { CellPack } from '../../extensions/cellpack';
-import { RCSBAssemblySymmetry, RCSBValidationReport } from '../../extensions/rcsb';
-import { PDBeStructureQualityReport } from '../../extensions/pdbe';
-import { Asset } from '../../mol-util/assets';
-import { ObjectKeys } from '../../mol-util/type-helpers';
-import { PluginState } from '../../mol-plugin/state';
-import { DownloadDensity } from '../../mol-plugin-state/actions/volume';
-import { PluginLayoutControlsDisplay } from '../../mol-plugin/layout';
-import { BuiltInTrajectoryFormat } from '../../mol-plugin-state/formats/trajectory';
-import { ANVILMembraneOrientation } from '../../extensions/anvil/behavior';
-import { DnatcoConfalPyramids } from '../../extensions/dnatco';
-import { G3DFormat, G3dProvider } from '../../extensions/g3d/format';
-import { DataFormatProvider } from '../../mol-plugin-state/formats/provider';
-import { BuildInVolumeFormat } from '../../mol-plugin-state/formats/volume';
-import { Color } from '../../mol-util/color';
-import { StateObjectSelector } from '../../mol-state';
-import { PluginStateObject } from '../../mol-plugin-state/objects';
-import { StateTransforms } from '../../mol-plugin-state/transforms';
-import { createVolumeRepresentationParams } from '../../mol-plugin-state/helpers/volume-representation-params';
-import { Mp4Export } from '../../extensions/mp4-export';
-import { StructureRepresentationPresetProvider } from '../../mol-plugin-state/builder/structure/representation-preset';
-
+import './index.html';
 require('mol-plugin-ui/skin/light.scss');
-
-export { PLUGIN_VERSION as version } from '../../mol-plugin/version';
-export { setProductionMode, setDebugMode } from '../../mol-util/debug';
-
-const CustomFormats = [
-    ['g3d', G3dProvider] as const
-];
-
-const Extensions = {
-    'cellpack': PluginSpec.Behavior(CellPack),
-    'dnatco-confal-pyramids': PluginSpec.Behavior(DnatcoConfalPyramids),
-    'pdbe-structure-quality-report': PluginSpec.Behavior(PDBeStructureQualityReport),
-    'rcsb-assembly-symmetry': PluginSpec.Behavior(RCSBAssemblySymmetry),
-    'rcsb-validation-report': PluginSpec.Behavior(RCSBValidationReport),
-    'anvil-membrane-orientation': PluginSpec.Behavior(ANVILMembraneOrientation),
-    'g3d': PluginSpec.Behavior(G3DFormat),
-    'mp4-export': PluginSpec.Behavior(Mp4Export)
-};
-
-const DefaultViewerOptions = {
-    customFormats: CustomFormats as [string, DataFormatProvider][],
-    extensions: ObjectKeys(Extensions),
-    layoutIsExpanded: true,
-    layoutShowControls: true,
-    layoutShowRemoteState: true,
-    layoutControlsDisplay: 'reactive' as PluginLayoutControlsDisplay,
-    layoutShowSequence: true,
-    layoutShowLog: true,
-    layoutShowLeftPanel: true,
-    disableAntialiasing: false,
-    pixelScale: 1,
-    enableWboit: true,
-
-    viewportShowExpand: PluginConfig.Viewport.ShowExpand.defaultValue,
-    viewportShowControls: PluginConfig.Viewport.ShowControls.defaultValue,
-    viewportShowSettings: PluginConfig.Viewport.ShowSettings.defaultValue,
-    viewportShowSelectionMode: PluginConfig.Viewport.ShowSelectionMode.defaultValue,
-    viewportShowAnimation: PluginConfig.Viewport.ShowAnimation.defaultValue,
-    pluginStateServer: PluginConfig.State.DefaultServer.defaultValue,
-    volumeStreamingServer: PluginConfig.VolumeStreaming.DefaultServer.defaultValue,
-    volumeStreamingDisabled: !PluginConfig.VolumeStreaming.Enabled.defaultValue,
-    pdbProvider: PluginConfig.Download.DefaultPdbProvider.defaultValue,
-    emdbProvider: PluginConfig.Download.DefaultEmdbProvider.defaultValue,
-};
-type ViewerOptions = typeof DefaultViewerOptions;
-
-export class Viewer {
-    plugin: PluginContext
-
-    constructor(elementOrId: string | HTMLElement, options: Partial<ViewerOptions> = {}) {
-        const o = { ...DefaultViewerOptions, ...options };
-        const defaultSpec = DefaultPluginSpec();
-
-        const spec: PluginSpec = {
-            actions: [...defaultSpec.actions],
-            behaviors: [
-                ...defaultSpec.behaviors,
-                ...o.extensions.map(e => Extensions[e]),
-            ],
-            animations: [...defaultSpec.animations || []],
-            customParamEditors: defaultSpec.customParamEditors,
-            customFormats: o?.customFormats,
-            layout: {
-                initial: {
-                    isExpanded: o.layoutIsExpanded,
-                    showControls: o.layoutShowControls,
-                    controlsDisplay: o.layoutControlsDisplay,
-                },
-                controls: {
-                    ...defaultSpec.layout && defaultSpec.layout.controls,
-                    top: o.layoutShowSequence ? undefined : 'none',
-                    bottom: o.layoutShowLog ? undefined : 'none',
-                    left: o.layoutShowLeftPanel ? undefined : 'none',
-                }
-            },
-            components: {
-                ...defaultSpec.components,
-                remoteState: o.layoutShowRemoteState ? 'default' : 'none',
-            },
-            config: [
-                [PluginConfig.General.DisableAntialiasing, o.disableAntialiasing],
-                [PluginConfig.General.PixelScale, o.pixelScale],
-                [PluginConfig.General.EnableWboit, o.enableWboit],
-                [PluginConfig.Viewport.ShowExpand, o.viewportShowExpand],
-                [PluginConfig.Viewport.ShowControls, o.viewportShowControls],
-                [PluginConfig.Viewport.ShowSettings, o.viewportShowSettings],
-                [PluginConfig.Viewport.ShowSelectionMode, o.viewportShowSelectionMode],
-                [PluginConfig.Viewport.ShowAnimation, o.viewportShowAnimation],
-                [PluginConfig.State.DefaultServer, o.pluginStateServer],
-                [PluginConfig.State.CurrentServer, o.pluginStateServer],
-                [PluginConfig.VolumeStreaming.DefaultServer, o.volumeStreamingServer],
-                [PluginConfig.VolumeStreaming.Enabled, !o.volumeStreamingDisabled],
-                [PluginConfig.Download.DefaultPdbProvider, o.pdbProvider],
-                [PluginConfig.Download.DefaultEmdbProvider, o.emdbProvider]
-            ]
-        };
-
-        const element = typeof elementOrId === 'string'
-            ? document.getElementById(elementOrId)
-            : elementOrId;
-        if (!element) throw new Error(`Could not get element with id '${elementOrId}'`);
-        this.plugin = createPlugin(element, spec);
-    }
-
-    setRemoteSnapshot(id: string) {
-        const url = `${this.plugin.config.get(PluginConfig.State.CurrentServer)}/get/${id}`;
-        return PluginCommands.State.Snapshots.Fetch(this.plugin, { url });
-    }
-
-    loadSnapshotFromUrl(url: string, type: PluginState.SnapshotType) {
-        return PluginCommands.State.Snapshots.OpenUrl(this.plugin, { url, type });
-    }
-
-    loadStructureFromUrl(url: string, format: BuiltInTrajectoryFormat = 'mmcif', isBinary = false, options?: LoadStructureOptions) {
-        const params = DownloadStructure.createDefaultParams(this.plugin.state.data.root.obj!, this.plugin);
-        return this.plugin.runTask(this.plugin.state.data.applyAction(DownloadStructure, {
-            source: {
-                name: 'url',
-                params: {
-                    url: Asset.Url(url),
-                    format: format as any,
-                    isBinary,
-                    options: { ...params.source.params.options, representationParams: options?.representationParams as any },
-                }
-            }
-        }));
-    }
-
-    async loadAllModelsOrAssemblyFromUrl(url: string, format: BuiltInTrajectoryFormat = 'mmcif', isBinary = false, options?: LoadStructureOptions) {
-        const plugin = this.plugin;
-
-        const data = await plugin.builders.data.download({ url, isBinary }, { state: { isGhost: true } });
-        const trajectory = await plugin.builders.structure.parseTrajectory(data, format);
-
-        await this.plugin.builders.structure.hierarchy.applyPreset(trajectory, 'all-models', { useDefaultIfSingleModel: true, representationPresetParams: options?.representationParams });
-    }
-
-    async loadStructureFromData(data: string | number[], format: BuiltInTrajectoryFormat, options?: { dataLabel?: string }) {
-        const _data = await this.plugin.builders.data.rawData({ data, label: options?.dataLabel });
-        const trajectory = await this.plugin.builders.structure.parseTrajectory(_data, format);
-        await this.plugin.builders.structure.hierarchy.applyPreset(trajectory, 'default');
-    }
-
-    loadPdb(pdb: string, options?: LoadStructureOptions) {
-        const params = DownloadStructure.createDefaultParams(this.plugin.state.data.root.obj!, this.plugin);
-        const provider = this.plugin.config.get(PluginConfig.Download.DefaultPdbProvider)!;
-        return this.plugin.runTask(this.plugin.state.data.applyAction(DownloadStructure, {
-            source: {
-                name: 'pdb' as const,
-                params: {
-                    provider: {
-                        id: pdb,
-                        server: {
-                            name: provider,
-                            params: PdbDownloadProvider[provider].defaultValue as any
-                        }
-                    },
-                    options: { ...params.source.params.options, representationParams: options?.representationParams as any },
-                }
-            }
-        }));
-    }
-
-    loadPdbDev(pdbDev: string) {
-        const params = DownloadStructure.createDefaultParams(this.plugin.state.data.root.obj!, this.plugin);
-        return this.plugin.runTask(this.plugin.state.data.applyAction(DownloadStructure, {
-            source: {
-                name: 'pdb-dev' as const,
-                params: {
-                    provider: {
-                        id: pdbDev,
-                        encoding: 'bcif',
-                    },
-                    options: params.source.params.options,
-                }
-            }
-        }));
-    }
-
-    loadEmdb(emdb: string, options?: { detail?: number }) {
-        const provider = this.plugin.config.get(PluginConfig.Download.DefaultEmdbProvider)!;
-        return this.plugin.runTask(this.plugin.state.data.applyAction(DownloadDensity, {
-            source: {
-                name: 'pdb-emd-ds' as const,
-                params: {
-                    provider: {
-                        id: emdb,
-                        server: provider,
-                    },
-                    detail: options?.detail ?? 3,
-                }
-            }
-        }));
-    }
-
-    async loadVolumeFromUrl(url: string, format: BuildInVolumeFormat, isBinary: boolean, isovalues: VolumeIsovalueInfo[], entryId?: string) {
-        const plugin = this.plugin;
-
-        if (!plugin.dataFormats.get(format)) {
-            throw new Error(`Unknown density format: ${format}`);
-        }
-
-        return plugin.dataTransaction(async () => {
-            const data = await plugin.builders.data.download({ url, isBinary, label: entryId }, { state: { isGhost: true } });
-
-            const parsed = await plugin.dataFormats.get(format)!.parse(plugin, data, { entryId });
-            const volume = (parsed.volume || parsed.volumes[0]) as StateObjectSelector<PluginStateObject.Volume.Data>;
-            if (!volume?.isOk) throw new Error('Failed to parse any volume.');
-
-            const repr = plugin.build().to(volume);
-            for (const iso of isovalues) {
-                repr.apply(StateTransforms.Representation.VolumeRepresentation3D, createVolumeRepresentationParams(this.plugin, volume.data!, {
-                    type: 'isosurface',
-                    typeParams: { alpha: iso.alpha ?? 1, isoValue: iso.type === 'absolute' ?  { kind: 'absolute', absoluteValue: iso.value } : { kind: 'relative', relativeValue: iso.value } },
-                    color: 'uniform',
-                    colorParams: { value: iso.color }
-                }));
-            }
-
-            await repr.commit();
-        });
-    }
-
-    handleResize() {
-        this.plugin.layout.events.updated.next();
-    }
-}
-
-export interface LoadStructureOptions {
-    representationParams?: StructureRepresentationPresetProvider.CommonParams
-}
-
-export interface VolumeIsovalueInfo {
-    type: 'absolute' | 'relative',
-    value: number,
-    color: Color,
-    alpha?: number
-}
+export * from './app';

src/cli/chem-comp-dict/create-ions.ts

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 /**
- * Copyright (c) 2020 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2020-2022 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Josh McMenemy <josh.mcmenemy@gmail.com>
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
 
 import * as argparse from 'argparse';
@@ -14,12 +15,12 @@ const writeFile = util.promisify(fs.writeFile);
 
 import { DatabaseCollection } from '../../mol-data/db';
 import { CCD_Schema } from '../../mol-io/reader/cif/schema/ccd';
-import { ensureDataAvailable, readCCD } from './util';
+import { DefaultDataOptions, ensureDataAvailable, readCCD } from './util';
 
 function extractIonNames(ccd: DatabaseCollection<CCD_Schema>) {
     const ionNames: string[] = [];
     for (const k in ccd) {
-        const {chem_comp} = ccd[k];
+        const { chem_comp } = ccd[k];
         if (chem_comp.name.value(0).toUpperCase().includes(' ION')) {
             ionNames.push(chem_comp.id.value(0));
         }
@@ -31,11 +32,11 @@ function extractIonNames(ccd: DatabaseCollection<CCD_Schema>) {
 
 function writeIonNamesFile(filePath: string, ionNames: string[]) {
     const output = `/**
- * Copyright (c) 2020 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2020-2022 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * Code-generated ion names params file. Names extracted from CCD components.
  *
- * @author molstar/chem-comp-dict/create-table cli
+ * @author molstar/chem-comp-dict/create-ions cli
  */
 
 export const IonNames = new Set(${JSON.stringify(ionNames).replace(/"/g, "'").replace(/,/g, ', ')});
@@ -43,8 +44,8 @@ export const IonNames = new Set(${JSON.stringify(ionNames).replace(/"/g, "'").re
     writeFile(filePath, output);
 }
 
-async function run(out: string, forceDownload = false) {
-    await ensureDataAvailable(forceDownload);
+async function run(out: string, options = DefaultDataOptions) {
+    await ensureDataAvailable(options);
     const ccd = await readCCD();
     const ionNames = extractIonNames(ccd);
     if (!fs.existsSync(path.dirname(out))) {
@@ -54,20 +55,25 @@ async function run(out: string, forceDownload = false) {
 }
 
 const parser = new argparse.ArgumentParser({
-    addHelp: true,
+    add_help: true,
     description: 'Extract and save IonNames from CCD.'
 });
-parser.addArgument('out', {
+parser.add_argument('out', {
     help: 'Generated file output path.'
 });
-parser.addArgument([ '--forceDownload', '-f' ], {
-    action: 'storeTrue',
+parser.add_argument('--forceDownload', '-f', {
+    action: 'store_true',
     help: 'Force download of CCD and PVCD.'
 });
+parser.add_argument('--ccdUrl', '-c', {
+    help: 'Fetch the CCD from a custom URL. This forces download of the CCD.',
+    required: false
+});
 interface Args {
     out: string,
     forceDownload?: boolean,
+    ccdUrl?: string
 }
-const args: Args = parser.parseArgs();
+const args: Args = parser.parse_args();
 
-run(args.out, args.forceDownload);
+run(args.out, { forceDownload: args.forceDownload, ccdUrl: args.ccdUrl });

src/cli/chem-comp-dict/create-saccharides.ts

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2022 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ */
+
+import * as argparse from 'argparse';
+import * as path from 'path';
+import util from 'util';
+import fs from 'fs';
+require('util.promisify').shim();
+const writeFile = util.promisify(fs.writeFile);
+
+import { DatabaseCollection } from '../../mol-data/db';
+import { CCD_Schema } from '../../mol-io/reader/cif/schema/ccd';
+import { DefaultDataOptions, ensureDataAvailable, readCCD } from './util';
+
+function extractSaccharideNames(ccd: DatabaseCollection<CCD_Schema>) {
+    const saccharideNames: string[] = [];
+    for (const k in ccd) {
+        const { chem_comp } = ccd[k];
+        const type = chem_comp.type.value(0).toUpperCase();
+        if (type.includes('SACCHARIDE')) {
+            saccharideNames.push(chem_comp.id.value(0));
+        }
+    }
+    // these are extra saccharides that don't have SACCHARIDE in their type
+    saccharideNames.push(
+        'UMQ', // UNDECYL-MALTOSIDE, via GlyFinder
+        'SQD', // SULFOQUINOVOSYLDIACYLGLYCEROL, via GlyFinder
+    );
+    return saccharideNames;
+}
+
+function writeSaccharideNamesFile(filePath: string, ionNames: string[]) {
+    const output = `/**
+ * Copyright (c) 2022 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * Code-generated ion names params file. Names extracted from CCD components.
+ *
+ * @author molstar/cli/chem-comp-dict/create-saccharides
+ */
+
+export const SaccharideNames = new Set(${JSON.stringify(ionNames).replace(/"/g, "'").replace(/,/g, ', ')});
+`;
+    writeFile(filePath, output);
+}
+
+async function run(out: string, options = DefaultDataOptions) {
+    await ensureDataAvailable(options);
+    const ccd = await readCCD();
+    const saccharideNames = extractSaccharideNames(ccd);
+    if (!fs.existsSync(path.dirname(out))) {
+        fs.mkdirSync(path.dirname(out));
+    }
+    writeSaccharideNamesFile(out, saccharideNames);
+}
+
+const parser = new argparse.ArgumentParser({
+    add_help: true,
+    description: 'Extract and save SaccharideNames from CCD.'
+});
+parser.add_argument('out', {
+    help: 'Generated file output path.'
+});
+parser.add_argument('--forceDownload', '-f', {
+    action: 'store_true',
+    help: 'Force download of CCD and PVCD.'
+});
+parser.add_argument('--ccdUrl', '-c', {
+    help: 'Fetch the CCD from a custom URL. This forces download of the CCD.',
+    required: false
+});
+interface Args {
+    out: string,
+    forceDownload?: boolean,
+    ccdUrl?: string
+}
+const args: Args = parser.parse_args();
+
+run(args.out, { forceDownload: args.forceDownload, ccdUrl: args.ccdUrl });

src/cli/chem-comp-dict/create-table.ts

@@ -18,7 +18,7 @@ import { SetUtils } from '../../mol-util/set';
 import { DefaultMap } from '../../mol-util/map';
 import { mmCIF_chemCompBond_schema } from '../../mol-io/reader/cif/schema/mmcif-extras';
 import { ccd_chemCompAtom_schema } from '../../mol-io/reader/cif/schema/ccd-extras';
-import { ensureDataAvailable, getEncodedCif, readCCD, readPVCD } from './util';
+import { DefaultDataOptions, ensureDataAvailable, getEncodedCif, readCCD, readPVCD } from './util';
 
 type CCB = Table<CCD_Schema['chem_comp_bond']>
 type CCA = Table<CCD_Schema['chem_comp_atom']>
@@ -171,7 +171,7 @@ async function createBonds(
         pdbx_aromatic_flag, pdbx_stereo_config, molstar_protonation_variant
     });
 
-    const bondDatabase =  Database.ofTables(
+    const bondDatabase = Database.ofTables(
         CCB_TABLE_NAME,
         { chem_comp_bond: mmCIF_chemCompBond_schema },
         { chem_comp_bond: bondTable }
@@ -239,8 +239,8 @@ function createAtoms(ccd: DatabaseCollection<CCD_Schema>, pvcd: DatabaseCollecti
     );
 }
 
-async function run(out: string, binary = false, forceDownload = false, ccaOut?: string) {
-    await ensureDataAvailable(forceDownload);
+async function run(out: string, binary = false, options = DefaultDataOptions, ccaOut?: string) {
+    await ensureDataAvailable(options);
     const ccd = await readCCD();
     const pvcd = await readPVCD();
 
@@ -265,30 +265,40 @@ const CCB_TABLE_NAME = 'CHEM_COMP_BONDS';
 const CCA_TABLE_NAME = 'CHEM_COMP_ATOMS';
 
 const parser = new argparse.ArgumentParser({
-    addHelp: true,
+    add_help: true,
     description: 'Create a cif file with one big table of all chem_comp_bond entries from the CCD and PVCD.'
 });
-parser.addArgument('out', {
+parser.add_argument('out', {
     help: 'Generated file output path.'
 });
-parser.addArgument([ '--forceDownload', '-f' ], {
-    action: 'storeTrue',
+parser.add_argument('--forceDownload', '-f', {
+    action: 'store_true',
     help: 'Force download of CCD and PVCD.'
 });
-parser.addArgument([ '--binary', '-b' ], {
-    action: 'storeTrue',
+parser.add_argument('--binary', '-b', {
+    action: 'store_true',
     help: 'Output as BinaryCIF.'
 });
-parser.addArgument(['--ccaOut', '-a'], {
+parser.add_argument('--ccaOut', '-a', {
     help: 'Optional generated file output path for chem_comp_atom data.',
     required: false
 });
+parser.add_argument('--ccdUrl', '-c', {
+    help: 'Fetch the CCD from a custom URL. This forces download of the CCD.',
+    required: false
+});
+parser.add_argument('--pvcdUrl', '-p', {
+    help: 'Fetch the PVCD from a custom URL. This forces download of the PVCD.',
+    required: false
+});
 interface Args {
     out: string,
     forceDownload?: boolean,
     binary?: boolean,
-    ccaOut?: string
+    ccaOut?: string,
+    ccdUrl?: string,
+    pvcdUrl?: string
 }
-const args: Args = parser.parseArgs();
+const args: Args = parser.parse_args();
 
-run(args.out, args.binary, args.forceDownload, args.ccaOut);
+run(args.out, args.binary, { forceDownload: args.forceDownload, ccdUrl: args.ccdUrl, pvcdUrl: args.pvcdUrl }, args.ccaOut);

src/cli/chem-comp-dict/util.ts

@@ -35,9 +35,9 @@ export async function ensureAvailable(path: string, url: string, forceDownload =
     }
 }
 
-export async function ensureDataAvailable(forceDownload = false) {
-    await ensureAvailable(CCD_PATH, CCD_URL, forceDownload);
-    await ensureAvailable(PVCD_PATH, PVCD_URL, forceDownload);
+export async function ensureDataAvailable(options: DataOptions) {
+    await ensureAvailable(CCD_PATH, options.ccdUrl || CCD_URL, !!options.ccdUrl || options.forceDownload);
+    await ensureAvailable(PVCD_PATH, options.pvcdUrl || PVCD_URL, !!options.pvcdUrl || options.forceDownload);
 }
 
 export async function readFileAsCollection<S extends Database.Schema>(path: string, schema: S) {
@@ -68,8 +68,18 @@ export function getEncodedCif(name: string, database: Database<Database.Schema>,
     return encoder.getData();
 }
 
+export type DataOptions = {
+    ccdUrl?: string,
+    pvcdUrl?: string,
+    forceDownload?: boolean
+}
+
+export const DefaultDataOptions: DataOptions = {
+    forceDownload: false
+};
+
 const DATA_DIR = path.join(__dirname, '..', '..', '..', '..', 'build/data');
 const CCD_PATH = path.join(DATA_DIR, 'components.cif');
 const PVCD_PATH = path.join(DATA_DIR, 'aa-variants-v1.cif');
-const CCD_URL = 'http://ftp.wwpdb.org/pub/pdb/data/monomers/components.cif';
-const PVCD_URL = 'http://ftp.wwpdb.org/pub/pdb/data/monomers/aa-variants-v1.cif';
+const CCD_URL = 'https://files.wwpdb.org/pub/pdb/data/monomers/components.cif';
+const PVCD_URL = 'https://files.wwpdb.org/pub/pdb/data/monomers/aa-variants-v1.cif';

src/cli/cif2bcif/converter.ts

@@ -71,7 +71,7 @@ function classify(name: string, field: CifField): CifWriter.Field {
 }
 
 export function convert(path: string, asText = false, hints?: EncodingStrategyHint[], filter?: string) {
-    return Task.create<Uint8Array>('BinaryCIF', async ctx => {
+    return Task.create<Uint8Array>('Convert CIF', async ctx => {
         const encodingProvider: BinaryEncodingProvider = hints
             ? CifWriter.createEncodingProviderFromJsonConfig(hints)
             : { get: (c, f) => void 0 };

src/cli/cif2bcif/index.ts

@@ -18,7 +18,7 @@ async function process(srcPath: string, outPath: string, configPath?: string, fi
     const config = configPath ? JSON.parse(fs.readFileSync(configPath, 'utf8')) : void 0;
     const filter = filterPath ? fs.readFileSync(filterPath, 'utf8') : void 0;
 
-    const res = await convert(srcPath, false, config, filter);
+    const res = await convert(srcPath, srcPath.toLowerCase().indexOf('.bcif') > 0, config, filter);
     await write(outPath, res);
 }
 
@@ -37,20 +37,20 @@ function run(args: Args) {
 }
 
 const parser = new argparse.ArgumentParser({
-    addHelp: true,
-    description: 'Convert any CIF file to a BCIF file'
+    add_help: true,
+    description: 'Convert any BCIF file to a CIF file or vice versa'
 });
-parser.addArgument([ 'src' ], {
-    help: 'Source CIF path'
+parser.add_argument('src', {
+    help: 'Source file path'
 });
-parser.addArgument([ 'out' ], {
-    help: 'Output BCIF path'
+parser.add_argument('out', {
+    help: 'Output file path'
 });
-parser.addArgument([ '-c', '--config' ], {
+parser.add_argument('-c', '--config', {
     help: 'Optional encoding strategy/precision config path',
     required: false
 });
-parser.addArgument([ '-f', '--filter' ], {
+parser.add_argument('-f', '--filter', {
     help: 'Optional filter whitelist/blacklist path',
     required: false
 });
@@ -61,7 +61,7 @@ interface Args {
     config?: string
     filter?: string
 }
-const args: Args = parser.parseArgs();
+const args: Args = parser.parse_args();
 
 if (args) {
     run(args);

src/cli/cifschema/index.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Copyright (c) 2017-2020 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2017-2021 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -35,20 +35,16 @@ async function runGenerateSchemaMmcif(name: string, fieldNamesPath: string, type
     const ihmDic = await parseCifText(fs.readFileSync(IHM_DIC_PATH, 'utf8')).run();
     if (ihmDic.isError) throw ihmDic;
 
-    await ensureCarbBranchDicAvailable();
-    const carbBranchDic = await parseCifText(fs.readFileSync(CARB_BRANCH_DIC_PATH, 'utf8')).run();
-    if (carbBranchDic.isError) throw carbBranchDic;
-
-    await ensureCarbCompDicAvailable();
-    const carbCompDic = await parseCifText(fs.readFileSync(CARB_COMP_DIC_PATH, 'utf8')).run();
-    if (carbCompDic.isError) throw carbCompDic;
+    await ensureMaDicAvailable();
+    const maDic = await parseCifText(fs.readFileSync(MA_DIC_PATH, 'utf8')).run();
+    if (maDic.isError) throw maDic;
 
     const mmcifDicVersion = getDicVersion(mmcifDic.result.blocks[0]);
     const ihmDicVersion = getDicVersion(ihmDic.result.blocks[0]);
-    const carbDicVersion = 'draft';
-    const version = `Dictionary versions: mmCIF ${mmcifDicVersion}, IHM ${ihmDicVersion}, CARB ${carbDicVersion}.`;
+    const maDicVersion = getDicVersion(maDic.result.blocks[0]);
+    const version = `Dictionary versions: mmCIF ${mmcifDicVersion}, IHM ${ihmDicVersion}, MA ${maDicVersion}.`;
 
-    const frames: CifFrame[] = [...mmcifDic.result.blocks[0].saveFrames, ...ihmDic.result.blocks[0].saveFrames, ...carbBranchDic.result.blocks[0].saveFrames, ...carbCompDic.result.blocks[0].saveFrames];
+    const frames: CifFrame[] = [...mmcifDic.result.blocks[0].saveFrames, ...ihmDic.result.blocks[0].saveFrames, ...maDic.result.blocks[0].saveFrames];
     const schema = generateSchema(frames);
 
     await runGenerateSchema(name, version, schema, fieldNamesPath, typescript, out, moldbImportPath, addAliases);
@@ -124,23 +120,22 @@ async function getFieldNamesFilter(fieldNamesPath: string): Promise<Filter> {
     const csvFile = parsed.result;
 
     const fieldNamesCol = csvFile.table.getColumn('0');
-    if (!fieldNamesCol) throw 'error getting fields columns';
+    if (!fieldNamesCol) throw new Error('error getting fields columns');
     const fieldNames = fieldNamesCol.toStringArray();
 
     const filter: Filter = {};
     fieldNames.forEach((name, i) => {
-        const [ category, field ] = name.split('.');
+        const [category, field] = name.split('.');
         // console.log(category, field)
-        if (!filter[ category ]) filter[ category ] = {};
-        filter[ category ][ field ] = true;
+        if (!filter[category]) filter[category] = {};
+        filter[category][field] = true;
     });
     return filter;
 }
 
 async function ensureMmcifDicAvailable() { await ensureDicAvailable(MMCIF_DIC_PATH, MMCIF_DIC_URL); }
 async function ensureIhmDicAvailable() { await ensureDicAvailable(IHM_DIC_PATH, IHM_DIC_URL); }
-async function ensureCarbBranchDicAvailable() { await ensureDicAvailable(CARB_BRANCH_DIC_PATH, CARB_BRANCH_DIC_URL); }
-async function ensureCarbCompDicAvailable() { await ensureDicAvailable(CARB_COMP_DIC_PATH, CARB_COMP_DIC_URL); }
+async function ensureMaDicAvailable() { await ensureDicAvailable(MA_DIC_PATH, MA_DIC_URL); }
 async function ensureCifCoreDicAvailable() {
     await ensureDicAvailable(CIF_CORE_DIC_PATH, CIF_CORE_DIC_URL);
     await ensureDicAvailable(CIF_CORE_ENUM_PATH, CIF_CORE_ENUM_URL);
@@ -163,12 +158,10 @@ 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 CARB_BRANCH_DIC_PATH = `${DIC_DIR}/entity_branch-extension.dic`;
-const CARB_BRANCH_DIC_URL = 'https://raw.githubusercontent.com/pdbxmmcifwg/carbohydrate-extension/master/dict/entity_branch-extension.dic';
-const CARB_COMP_DIC_PATH = `${DIC_DIR}/chem_comp-extension.dic`;
-const CARB_COMP_DIC_URL = 'https://raw.githubusercontent.com/pdbxmmcifwg/carbohydrate-extension/master/dict/chem_comp-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';
 
 const CIF_CORE_DIC_PATH = `${DIC_DIR}/cif_core.dic`;
 const CIF_CORE_DIC_URL = 'https://raw.githubusercontent.com/COMCIFS/cif_core/master/cif_core.dic';
@@ -178,44 +171,44 @@ const CIF_CORE_ATTR_PATH = `${DIC_DIR}/templ_attr.cif`;
 const CIF_CORE_ATTR_URL = 'https://raw.githubusercontent.com/COMCIFS/cif_core/master/templ_attr.cif';
 
 const parser = new argparse.ArgumentParser({
-    addHelp: true,
+    add_help: true,
     description: 'Create schema from mmcif dictionary (v50 plus IHM and entity_branch extensions, downloaded from wwPDB)'
 });
-parser.addArgument([ '--preset', '-p' ], {
-    defaultValue: '',
+parser.add_argument('--preset', '-p', {
+    default: '',
     choices: ['', 'mmCIF', 'CCD', 'BIRD', 'CifCore'],
     help: 'Preset name'
 });
-parser.addArgument([ '--name', '-n' ], {
-    defaultValue: '',
+parser.add_argument('--name', '-n', {
+    default: '',
     help: 'Schema name'
 });
-parser.addArgument([ '--out', '-o' ], {
+parser.add_argument('--out', '-o', {
     help: 'Generated schema output path, if not given printed to stdout'
 });
-parser.addArgument([ '--targetFormat', '-tf' ], {
-    defaultValue: 'typescript-molstar',
+parser.add_argument('--targetFormat', '-tf', {
+    default: 'typescript-molstar',
     choices: ['typescript-molstar', 'json-internal'],
     help: 'Target format'
 });
-parser.addArgument([ '--dicPath', '-d' ], {
-    defaultValue: '',
+parser.add_argument('--dicPath', '-d', {
+    default: '',
     help: 'Path to dictionary'
 });
-parser.addArgument([ '--fieldNamesPath', '-fn' ], {
-    defaultValue: '',
+parser.add_argument('--fieldNamesPath', '-fn', {
+    default: '',
     help: 'Field names to include'
 });
-parser.addArgument([ '--forceDicDownload', '-f' ], {
-    action: 'storeTrue',
+parser.add_argument('--forceDicDownload', '-f', {
+    action: 'store_true',
     help: 'Force download of dictionaries'
 });
-parser.addArgument([ '--moldataImportPath', '-mip' ], {
-    defaultValue: 'molstar/lib/mol-data',
+parser.add_argument('--moldataImportPath', '-mip', {
+    default: 'molstar/lib/mol-data',
     help: 'mol-data import path (for typescript target only)'
 });
-parser.addArgument([ '--addAliases', '-aa' ], {
-    action: 'storeTrue',
+parser.add_argument('--addAliases', '-aa', {
+    action: 'store_true',
     help: 'Add field name/path aliases'
 });
 interface Args {
@@ -230,7 +223,7 @@ interface Args {
     moldataImportPath: string
     addAliases: boolean
 }
-const args: Args = parser.parseArgs();
+const args: Args = parser.parse_args();
 
 const FORCE_DIC_DOWNLOAD = args.forceDicDownload;
 

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

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2017-2018 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2017-2022 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -13,15 +13,18 @@ export function getFieldType(type: string, description: string, values?: string[
     switch (type) {
         // mmCIF
         case 'code':
-        case 'ucode':
         case 'line':
-        case 'uline':
         case 'text':
         case 'char':
-        case 'uchar3':
-        case 'uchar1':
         case 'boolean':
             return values && values.length ? EnumCol(values, 'str', description) : StrCol(description);
+        case 'ucode':
+        case 'uline':
+        case 'uchar3':
+        case 'uchar1':
+        case 'uchar5':
+            // only force lower-case for enums
+            return values && values.length ? EnumCol(values.map(x => x.toLowerCase()), 'lstr', description) : StrCol(description);
         case 'aliasname':
         case 'name':
         case 'idname':
@@ -34,6 +37,8 @@ export function getFieldType(type: string, description: string, values?: string[
         case 'seq-one-letter-code':
         case 'author':
         case 'orcid_id':
+        case 'pdbx_PDB_obsoleted_db_id':
+        case 'pdbx_related_db_id':
         case 'sequence_dep':
         case 'pdb_id':
         case 'emd_id':
@@ -47,6 +52,7 @@ export function getFieldType(type: string, description: string, values?: string[
         case 'operation_expression':
         case 'point_symmetry':
         case '4x3_matrix':
+        case '3x4_matrix':
         case '3x4_matrices':
         case 'point_group':
         case 'point_group_helical':
@@ -56,6 +62,7 @@ export function getFieldType(type: string, description: string, values?: string[
         case 'symop':
         case 'exp_data_doi':
         case 'asym_id':
+        case 'uniprot_ptm_id':
             return StrCol(description);
         case 'int':
         case 'non_negative_int':
@@ -66,6 +73,7 @@ export function getFieldType(type: string, description: string, values?: string[
         case 'ec-type':
         case 'ucode-alphanum-csv':
         case 'id_list':
+        case 'entity_id_list':
             return ListCol('str', ',', description);
         case 'id_list_spc':
             return ListCol('str', ' ', description);
@@ -79,9 +87,11 @@ export function getFieldType(type: string, description: string, values?: string[
         case 'List(Real,Real)':
         case 'List(Real,Real,Real,Real)':
         case 'Date':
-        case 'Datetime':
+        case 'DateTime':
         case 'Tag':
         case 'Implied':
+        case 'Word':
+        case 'Uri':
             return wrapContainer('str', ',', description, container);
         case 'Real':
             return wrapContainer('float', ',', description, container);
@@ -145,7 +155,7 @@ function getImportFrames(d: Data.CifFrame, imports: Imports) {
 }
 
 /** get field from given or linked category */
-function getField(category: string, field: string, d: Data.CifFrame, imports: Imports, ctx: FrameData): Data.CifField|undefined {
+function getField(category: string, field: string, d: Data.CifFrame, imports: Imports, ctx: FrameData): Data.CifField | undefined {
     const { categories, links } = ctx;
     const cat = d.categories[category];
     if (cat) {
@@ -187,7 +197,7 @@ function getContainer(d: Data.CifFrame, imports: Imports, ctx: FrameData) {
 function getCode(d: Data.CifFrame, imports: Imports, ctx: FrameData): [string, string[] | undefined, string | undefined ] | undefined {
     const code = getField('item_type', 'code', d, imports, ctx) || getField('type', 'contents', d, imports, ctx);
     if (code) {
-        return [ code.str(0), getEnums(d, imports, ctx), getContainer(d, imports, ctx) ];
+        return [code.str(0), getEnums(d, imports, ctx), getContainer(d, imports, ctx)];
     } else {
         console.log(`item_type.code or type.contents not found for '${d.header}'`);
     }
@@ -232,29 +242,26 @@ const FORCE_INT_FIELDS = [
     '_struct_sheet_range.end_auth_seq_id',
 ];
 
+/**
+ * Note that name and mapped name must share a prefix. This is not always the case in
+ * the cifCore dictionary, but for downstream code to work a container field with the
+ * same prefix as the member fields must be given here and in the field names filter
+ * list.
+ */
 const FORCE_MATRIX_FIELDS_MAP: { [k: string]: string } = {
-    'atom_site_aniso.U_11': 'U',
-    'atom_site_aniso.U_22': 'U',
-    'atom_site_aniso.U_33': 'U',
-    'atom_site_aniso.U_23': 'U',
-    'atom_site_aniso.U_13': 'U',
-    'atom_site_aniso.U_12': 'U',
-    'atom_site_aniso.U_11_su': 'U_su',
-    'atom_site_aniso.U_22_su': 'U_su',
-    'atom_site_aniso.U_33_su': 'U_su',
-    'atom_site_aniso.U_23_su': 'U_su',
-    'atom_site_aniso.U_13_su': 'U_su',
-    'atom_site_aniso.U_12_su': 'U_su',
+    'atom_site_aniso.u_11': 'u', // is matrix_u in the the dic
+    'atom_site_aniso.u_22': 'u',
+    'atom_site_aniso.u_33': 'u',
+    'atom_site_aniso.u_23': 'u',
+    'atom_site_aniso.u_13': 'u',
+    'atom_site_aniso.u_12': 'u',
 };
 const FORCE_MATRIX_FIELDS = Object.keys(FORCE_MATRIX_FIELDS_MAP);
 
 const EXTRA_ALIASES: Database['aliases'] = {
-    'atom_site_aniso.U': [
-        'atom_site_anisotrop_U'
-    ],
-    'atom_site_aniso.U_su': [
-        'atom_site_aniso_U_esd',
-        'atom_site_anisotrop_U_esd',
+    'atom_site_aniso.matrix_u': [
+        'atom_site_anisotrop_U',
+        'atom_site_aniso.U'
     ],
 };
 
@@ -317,7 +324,7 @@ export function generateSchema(frames: CifFrame[], imports: Imports = new Map())
     frames.forEach(d => {
         // category definitions in mmCIF start with '_' and don't include a '.'
         // category definitions in cifCore don't include a '.'
-        if (d.header[0] === '_'  || d.header.includes('.')) return;
+        if (d.header[0] === '_' || d.header.includes('.')) return;
         const categoryName = d.header.toLowerCase();
         // console.log(d.header, d.categoryNames, d.categories)
         let descriptionField: Data.CifField | undefined;
@@ -372,7 +379,7 @@ export function generateSchema(frames: CifFrame[], imports: Imports = new Map())
             const parent_name = item_linked.getField('parent_name');
             if (child_name && parent_name) {
                 for (let i = 0; i < item_linked.rowCount; ++i) {
-                    const childName = child_name.str(i);
+                    const childName: string = child_name.str(i);
                     const parentName = parent_name.str(i);
                     if (childName in links && links[childName] !== parentName) {
                         console.log(`${childName} linked to ${links[childName]}, ignoring link to ${parentName}`);

src/cli/cifschema/util/generate.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2017-2019 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2017-2022 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -8,9 +8,9 @@ import { Database, Filter, Column } from './schema';
 import { indentString } from '../../../mol-util/string';
 import { FieldPath } from '../../../mol-io/reader/cif/schema';
 
-function header (name: string, info: string, moldataImportPath: string) {
+function header(name: string, info: string, moldataImportPath: string) {
     return `/**
- * Copyright (c) 2017-2020 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2017-2022 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * Code-generated '${name}' schema file. ${info}
  *
@@ -22,7 +22,7 @@ import { Database, Column } from '${moldataImportPath}/db';
 import Schema = Column.Schema;`;
 }
 
-function footer (name: string) {
+function footer(name: string) {
     return `
 export type ${name}_Schema = typeof ${name}_Schema;
 export interface ${name}_Database extends Database<${name}_Schema> {};`;
@@ -35,13 +35,17 @@ function getTypeShorthands(schema: Database, fields?: Filter) {
         const { columns } = schema.tables[table];
         Object.keys(columns).forEach(columnName => {
             if (fields && !fields[table][columnName]) return;
-            types.add(schema.tables[table].columns[columnName].type);
+            const col = schema.tables[table].columns[columnName];
+            if (col.type === 'enum') types.add(col.subType);
+            types.add(col.type);
         });
     });
     const shorthands: string[] = [];
     types.forEach(type => {
         switch (type) {
             case 'str': shorthands.push('const str = Schema.str;'); break;
+            case 'ustr': shorthands.push('const ustr = Schema.ustr;'); break;
+            case 'lstr': shorthands.push('const lstr = Schema.lstr;'); break;
             case 'int': shorthands.push('const int = Schema.int;'); break;
             case 'float': shorthands.push('const float = Schema.float;'); break;
             case 'coord': shorthands.push('const coord = Schema.coord;'); break;
@@ -89,7 +93,7 @@ function doc(description: string, spacesCount: number) {
     ].join('\n');
 }
 
-export function generate (name: string, info: string, schema: Database, fields: Filter | undefined, moldataImportPath: string, addAliases: boolean) {
+export function generate(name: string, info: string, schema: Database, fields: Filter | undefined, moldataImportPath: string, addAliases: boolean) {
     const codeLines: string[] = [];
 
     if (fields) {
@@ -128,7 +132,7 @@ export function generate (name: string, info: string, schema: Database, fields:
         codeLines.push('');
         codeLines.push(`export const ${name}_Aliases = {`);
         Object.keys(schema.aliases).forEach(path => {
-            const [ table, columnName ] = path.split('.');
+            const [table, columnName] = path.split('.');
             if (fields && !fields[table]) return;
             if (fields && !fields[table][columnName]) return;
 

src/cli/cifschema/util/helper.ts

@@ -10,8 +10,8 @@ export function parseImportGet(s: string): Import[] {
     // [{'save':hi_ang_Fox_coeffs  'file':templ_attr.cif}   {'save':hi_ang_Fox_c0  'file':templ_enum.cif}]
     // [{"file":'templ_enum.cif' "save":'H_M_ref'}]
     return s.trim().substring(2, s.length - 2).split(/}[ \n\t]*{/g).map(s => {
-        const save = s.match(/('save'|"save"):([^ \t\n]+)/);
-        const file = s.match(/('file'|"file"):([^ \t\n]+)/);
+        const save = s.match(/('save'|"save"):([^ \t\n{}]+)/);
+        const file = s.match(/('file'|"file"):([^ \t\n{}]+)/);
         return {
             save: save ? save[0].substr(7).replace(/['"]/g, '') : undefined,
             file: file ? file[0].substr(7).replace(/['"]/g, '') : undefined

src/cli/cifschema/util/schema.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2017-2019 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2017-2022 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -29,8 +29,8 @@ export function FloatCol(description: string): FloatCol { return { type: 'float'
 export type CoordCol = { type: 'coord' } & BaseCol
 export function CoordCol(description: string): CoordCol { return { type: 'coord', description }; }
 
-export type EnumCol = { type: 'enum', subType: 'int' | 'str', values: string[] } & BaseCol
-export function EnumCol(values: string[], subType: 'int' | 'str', description: string): EnumCol {
+export type EnumCol = { type: 'enum', subType: 'int' | 'str' | 'ustr' | 'lstr', values: string[] } & BaseCol
+export function EnumCol(values: string[], subType: 'int' | 'str' | 'ustr' | 'lstr', description: string): EnumCol {
     return { type: 'enum', description, values, subType };
 }
 
@@ -51,13 +51,13 @@ export function ListCol(subType: 'int' | 'str' | 'float' | 'coord', separator: s
 
 export type Filter = { [ table: string ]: { [ column: string ]: true } }
 
-export function mergeFilters (...filters: Filter[]) {
+export function mergeFilters(...filters: Filter[]) {
     const n = filters.length;
     const mergedFilter: Filter = {};
     const fields: Map<string, number> = new Map();
     filters.forEach(filter => {
         Object.keys(filter).forEach(category => {
-            Object.keys(filter[ category ]).forEach(field => {
+            Object.keys(filter[category]).forEach(field => {
                 const key = `${category}.${field}`;
                 const value = fields.get(key) || 0;
                 fields.set(key, value + 1);

src/cli/lipid-params/index.ts

@@ -70,21 +70,21 @@ export const LipidNames = new Set(${lipidNames.replace(/"/g, "'").replace(/,/g,
 }
 
 const parser = new argparse.ArgumentParser({
-    addHelp: true,
+    add_help: true,
     description: 'Create lipid params (from martini lipids itp)'
 });
-parser.addArgument([ '--out', '-o' ], {
+parser.add_argument('--out', '-o', {
     help: 'Generated lipid params output path, if not given printed to stdout'
 });
-parser.addArgument([ '--forceDownload', '-f' ], {
-    action: 'storeTrue',
+parser.add_argument('--forceDownload', '-f', {
+    action: 'store_true',
     help: 'Force download of martini lipids itp'
 });
 interface Args {
     out: string
     forceDownload: boolean
 }
-const args: Args = parser.parseArgs();
+const args: Args = parser.parse_args();
 
 const FORCE_DOWNLOAD = args.forceDownload;
 

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

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Adam Midlik <midlik@gmail.com>
+ *
+ * Command-line application for printing MolViewSpec tree schema
+ * Build: npm run build
+ * Run:   node lib/commonjs/cli/mvs/mvs-print-schema
+ *        node lib/commonjs/cli/mvs/mvs-print-schema --markdown
+ */
+
+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';
+
+
+/** Command line argument values for `main` */
+interface Args {
+    markdown: boolean,
+}
+
+/** Return parsed command line arguments for `main` */
+function parseArguments(): Args {
+    const parser = new ArgumentParser({ description: 'Command-line application for printing MolViewSpec tree schema.' });
+    parser.add_argument('-m', '--markdown', { action: 'store_true', help: 'Print the schema as markdown instead of plain text.' });
+    const args = parser.parse_args();
+    return { ...args };
+}
+
+/** Main workflow for printing MolViewSpec tree schema. */
+function main(args: Args) {
+    if (args.markdown) {
+        console.log(treeSchemaToMarkdown(MVSTreeSchema, MVSDefaults));
+    } else {
+        console.log(treeSchemaToString(MVSTreeSchema, MVSDefaults));
+    }
+}
+
+main(parseArguments());

src/cli/mvs/mvs-render.ts

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * 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
+ */
+
+import { ArgumentParser } from 'argparse';
+import fs from 'fs';
+import gl from 'gl';
+import jpegjs from 'jpeg-js';
+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 { 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';
+
+
+setFSModule(fs);
+setCanvasModule(require('canvas'));
+
+const DEFAULT_SIZE = '800x800';
+
+/** Command line argument values for `main` */
+interface Args {
+    input: string[],
+    output: string[],
+    size: { width: number, height: number },
+    molj: 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 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)` });
+    const args = parser.parse_args();
+    try {
+        const parts = args.size.split('x');
+        if (parts.length !== 2) throw new Error('Must contain two x-separated parts');
+        args.size = { width: parseIntStrict(parts[0]), height: parseIntStrict(parts[1]) };
+    } catch {
+        parser.error(`argument: --size: invalid image size string: '${args.size}' (must be two x-separated integers (width and height), e.g. '400x300')`);
+    }
+    if (args.input.length !== args.output.length) {
+        parser.error(`argument: --output: must specify the same number of input and output file paths (specified ${args.input.length} input path${args.input.length !== 1 ? 's' : ''} but ${args.output.length} output path${args.output.length !== 1 ? 's' : ''})`);
+    }
+    return { ...args };
+}
+
+/** Main workflow for rendering images from MolViewSpec files */
+async function main(args: Args): Promise<void> {
+    const plugin = await createHeadlessPlugin(args);
+
+    for (let i = 0; i < args.input.length; i++) {
+        const input = args.input[i];
+        const output = args.output[i];
+        console.log(`Processing ${input} -> ${output}`);
+
+        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 });
+
+        fs.mkdirSync(path.dirname(output), { recursive: true });
+        if (args.molj) {
+            await plugin.saveStateSnapshot(withExtension(output, '.molj'));
+        }
+        await plugin.saveImage(output);
+        checkState(plugin);
+    }
+    await plugin.clear();
+    plugin.dispose();
+}
+
+/** Return a new and initiatized HeadlessPlugin */
+async function createHeadlessPlugin(args: Pick<Args, 'size'>): Promise<HeadlessPluginContext> {
+    const externalModules: ExternalModules = { gl, pngjs, 'jpeg-js': jpegjs };
+    const spec = DefaultPluginSpec();
+    spec.behaviors.push(PluginSpec.Behavior(MolViewSpec));
+    const headlessCanvasOptions = defaultCanvas3DParams();
+    const canvasOptions = {
+        ...PD.getDefaultValues(Canvas3DParams),
+        cameraResetDurationMs: headlessCanvasOptions.cameraResetDurationMs,
+        postprocessing: headlessCanvasOptions.postprocessing,
+    };
+    const plugin = new HeadlessPluginContext(externalModules, spec, args.size, { canvas: canvasOptions });
+    try {
+        await plugin.init();
+    } catch (error) {
+        plugin.dispose();
+        throw error;
+    }
+    return plugin;
+}
+
+/** Parse integer, fail early. */
+function parseIntStrict(str: string): number {
+    if (str === '') throw new Error('Is empty string');
+    const result = Number(str);
+    if (isNaN(result)) throw new Error('Is NaN');
+    if (Math.floor(result) !== result) throw new Error('Is not integer');
+    return result;
+}
+
+/** Replace the file extension in `filename` by `extension`. If `filename` has no extension, add it. */
+function withExtension(filename: string, extension: string): string {
+    const oldExtension = path.extname(filename);
+    return filename.slice(0, -oldExtension.length) + extension;
+}
+
+/** Check Mol* state, print and throw error if any cell is not OK. */
+function checkState(plugin: PluginContext): void {
+    const cells = Array.from(plugin.state.data.cells.values());
+    const badCell = cells.find(cell => cell.status !== 'ok');
+    if (badCell) {
+        console.error(`Building Mol* state failed`);
+        console.error(`    Transformer: ${badCell.transform.transformer.id}`);
+        console.error(`    Params: ${onelinerJsonString(badCell.transform.params)}`);
+        console.error(`    Error: ${badCell.errorText}`);
+        console.error(``);
+        throw new Error(`Building Mol* state failed: ${badCell.errorText}`);
+    }
+}
+
+main(parseArguments());

src/cli/mvs/mvs-validate.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Adam Midlik <midlik@gmail.com>
+ *
+ * Command-line application for validating MolViewSpec files
+ * Build: npm run build
+ * Run:   node lib/commonjs/cli/mvs/mvs-validate examples/mvs/1cbs.mvsj
+ */
+
+import { ArgumentParser } from 'argparse';
+import fs from 'fs';
+
+import { setFSModule } from '../../mol-util/data-source';
+import { MVSData } from '../../extensions/mvs/mvs-data';
+
+
+setFSModule(fs);
+
+/** Command line argument values for `main` */
+interface Args {
+    input: string[],
+    no_extra: boolean,
+}
+
+/** Return parsed command line arguments for `main` */
+function parseArguments(): Args {
+    const parser = new ArgumentParser({ description: 'Command-line application for validating MolViewSpec files. Prints validation status (OK/FAILED) to stdout, detailed validation issues to stderr. Exits with a zero exit code if all input files are OK.' });
+    parser.add_argument('input', { nargs: '+', help: 'Input file(s) in .mvsj format' });
+    parser.add_argument('--no-extra', { action: 'store_true', help: 'Treat presence of extra node params as an issue.' });
+    const args = parser.parse_args();
+    return { ...args };
+}
+
+/** Main workflow for validating MolViewSpec files. Returns the number of failed input files. */
+function main(args: Args): number {
+    let nFailed = 0;
+    for (const input of args.input) {
+        const data = fs.readFileSync(input, { encoding: 'utf8' });
+        const mvsData = MVSData.fromMVSJ(data);
+        const issues = MVSData.validationIssues(mvsData, { noExtra: args.no_extra });
+        const status = issues ? 'FAILED' : 'OK';
+        console.log(`${status.padEnd(6)} ${input}`);
+        if (issues) {
+            nFailed++;
+            for (const issue of issues) {
+                console.error(issue);
+            }
+        }
+    }
+    return nFailed;
+}
+
+const nFailed = main(parseArguments());
+if (nFailed > 0) {
+    process.exitCode = 1;
+}

src/cli/state-docs/index.ts

@@ -18,7 +18,6 @@ _.StateTransforms.Data.Download.id;
 
 // Empty plugin context
 const ctx = new PluginContext({
-    actions: [],
     behaviors: []
 });
 

src/cli/structure-info/helpers.ts

@@ -25,7 +25,7 @@ async function readFile(path: string) {
     }
 }
 
-async function parseCif(data: string|Uint8Array) {
+async function parseCif(data: string | Uint8Array) {
     const comp = CIF.parse(data);
     const parsed = await comp.run(p => console.log(Progress.format(p)), 250);
     if (parsed.isError) throw parsed;

src/cli/structure-info/model.ts

@@ -63,7 +63,7 @@ export function printSecStructure(model: Model) {
     const count = residues._rowCount;
     let rI = 0;
     while (rI < count) {
-        let start = rI;
+        const start = rI;
         while (rI < count && key[start] === key[rI]) rI++;
         rI--;
 
@@ -230,21 +230,21 @@ async function runFile(filename: string, args: Args) {
 }
 
 const parser = new argparse.ArgumentParser({
-    addHelp: true,
+    add_help: true,
     description: 'Print info about a structure, mainly to test and showcase the mol-model module'
 });
-parser.addArgument(['--download', '-d'], { help: 'Pdb entry id' });
-parser.addArgument(['--file', '-f'], { help: 'filename' });
+parser.add_argument('--download', '-d', { help: 'Pdb entry id' });
+parser.add_argument('--file', '-f', { help: 'filename' });
 
-parser.addArgument(['--models'], { help: 'print models info', action: 'storeTrue' });
-parser.addArgument(['--seq'], { help: 'print sequence', action: 'storeTrue' });
-parser.addArgument(['--units'], { help: 'print units', action: 'storeTrue' });
-parser.addArgument(['--sym'], { help: 'print symmetry', action: 'storeTrue' });
-parser.addArgument(['--rings'], { help: 'print rings', action: 'storeTrue' });
-parser.addArgument(['--intraBonds'], { help: 'print intra unit bonds', action: 'storeTrue' });
-parser.addArgument(['--interBonds'], { help: 'print inter unit bonds', action: 'storeTrue' });
-parser.addArgument(['--mod'], { help: 'print modified residues', action: 'storeTrue' });
-parser.addArgument(['--sec'], { help: 'print secoundary structure', action: 'storeTrue' });
+parser.add_argument('--models', { help: 'print models info', action: 'store_true' });
+parser.add_argument('--seq', { help: 'print sequence', action: 'store_true' });
+parser.add_argument('--units', { help: 'print units', action: 'store_true' });
+parser.add_argument('--sym', { help: 'print symmetry', action: 'store_true' });
+parser.add_argument('--rings', { help: 'print rings', action: 'store_true' });
+parser.add_argument('--intraBonds', { help: 'print intra unit bonds', action: 'store_true' });
+parser.add_argument('--interBonds', { help: 'print inter unit bonds', action: 'store_true' });
+parser.add_argument('--mod', { help: 'print modified residues', action: 'store_true' });
+parser.add_argument('--sec', { help: 'print secoundary structure', action: 'store_true' });
 interface Args {
     download?: string,
     file?: string,
@@ -260,7 +260,7 @@ interface Args {
     mod?: boolean,
     sec?: boolean,
 }
-const args: Args = parser.parseArgs();
+const args: Args = parser.parse_args();
 
 if (args.download) runDL(args.download, args);
 else if (args.file) runFile(args.file, args);

src/cli/structure-info/volume.ts

@@ -38,7 +38,7 @@ function print(volume: Volume) {
 }
 
 async function doMesh(volume: Volume, filename: string) {
-    const mesh = await Task.create('', runtime => createVolumeIsosurfaceMesh({ runtime }, volume, Theme.createEmpty(), { isoValue: Volume.IsoValue.absolute(1.5) } )).run();
+    const mesh = await Task.create('', runtime => createVolumeIsosurfaceMesh({ runtime }, volume, -1, Theme.createEmpty(), { isoValue: Volume.IsoValue.absolute(1.5) })).run();
     console.log({ vc: mesh.vertexCount, tc: mesh.triangleCount });
 
     // Export the mesh in OBJ format.
@@ -75,13 +75,13 @@ async function run(url: string, meshFilename: string) {
 }
 
 const parser = new argparse.ArgumentParser({
-    addHelp: true,
+    add_help: true,
     description: 'Info about VolumeData from mol-model module'
 });
-parser.addArgument([ '--emdb', '-e' ], {
+parser.add_argument('--emdb', '-e', {
     help: 'EMDB id, for example 8116',
 });
-parser.addArgument([ '--mesh' ], {
+parser.add_argument('--mesh', {
     help: 'Mesh filename',
     required: true
 });
@@ -89,6 +89,6 @@ interface Args {
     emdb?: string,
     mesh: string
 }
-const args: Args = parser.parseArgs();
+const args: Args = parser.parse_args();
 
 run(`https://ds.litemol.org/em/emd-${args.emdb}/cell?detail=4`, args.mesh);

src/examples/alpha-orbitals/controls.tsx

@@ -4,17 +4,16 @@
  * @author David Sehnal <david.sehnal@gmail.com>
  */
 
-import * as React from 'react';
-import * as ReactDOM from 'react-dom';
+import { createRoot } from 'react-dom/client';
 import { AlphaOrbitalsExample } from '.';
 import { ParameterControls } from '../../mol-plugin-ui/controls/parameters';
 import { useBehavior } from '../../mol-plugin-ui/hooks/use-behavior';
 import { PluginContextContainer } from '../../mol-plugin-ui/plugin';
 
 export function mountControls(orbitals: AlphaOrbitalsExample, parent: Element) {
-    ReactDOM.render(<PluginContextContainer plugin={orbitals.plugin}>
+    createRoot(parent).render(<PluginContextContainer plugin={orbitals.plugin}>
         <Controls orbitals={orbitals} />
-    </PluginContextContainer>, parent);
+    </PluginContextContainer>);
 }
 
 function Controls({ orbitals }: { orbitals: AlphaOrbitalsExample }) {

src/examples/alpha-orbitals/index.html

@@ -22,7 +22,23 @@
                 left: 8px;
                 top: 8px;
                 width: 300px;
-            }            
+            }
+            #sponsor {
+                position: absolute;
+                left: 8px;
+                bottom: 8px;
+                font-family: "Helvetica Neue", "Segoe UI", Helvetica, "Source Sans Pro", Arial, sans-serif;
+                font-size: 12px;
+                text-align: center;
+            }
+            #sponsor svg {
+                fill: #128EA4;
+                width: 100px;
+            }
+            #sponsor a {
+                text-decoration: none;
+                color: #128EA4;
+            }
         </style>
         <link rel="stylesheet" type="text/css" href="molstar.css" />
         <script type="text/javascript" src="./index.js"></script>
@@ -30,8 +46,28 @@
     <body>
         <div id="app"></div>
         <div id='controls'></div>
+        <div id='sponsor'>
+            <a href='https://www.entos.ai/envision' target="_blank" rel="noopener">
+                <svg class="makeStyles-root-46" viewBox="0 0 190 36" xmlns="http://www.w3.org/2000/svg"><path d="M32.2591 28.6707C32.2591 32.3914 29.2421 35.407 25.5214 35.407C22.0752 35.407 19.2338 32.8206 18.8325 29.4831V29.4775C18.8143 29.3312 18.8018 29.1835 18.7934 29.0344C18.7934 29.0316 18.7921 29.0274 18.7921 29.0246V29.0177C18.7865 28.902 18.7837 28.7864 18.7837 28.6707C18.7837 26.2557 20.0532 24.1389 21.9609 22.9503C21.9623 22.9489 21.9651 22.9489 21.9665 22.9475C22.0933 22.8666 22.2243 22.7914 22.3581 22.7203C22.3581 22.7203 22.3595 22.7203 22.3595 22.7189C23.3029 22.2173 24.3787 21.933 25.5214 21.933C29.2421 21.933 32.2591 24.9486 32.2591 28.6707Z"></path><path d="M25.5214 14.0692C29.2421 14.0692 32.2591 11.0522 32.2591 7.33146C32.2591 3.61074 29.2421 0.59375 25.5214 0.59375C22.0529 0.59375 19.1962 3.21637 18.8255 6.58592C18.8185 6.67092 18.8116 6.75454 18.8018 6.83815C18.7893 7.00119 18.7837 7.16563 18.7837 7.33146C18.7837 9.73669 20.0434 11.8465 21.94 13.038C22.0891 13.116 22.2355 13.201 22.3776 13.2916C22.3783 13.2923 22.379 13.2926 22.3797 13.293C22.3804 13.2933 22.3811 13.2937 22.3818 13.2944C23.3196 13.7891 24.3871 14.0692 25.5214 14.0692Z"></path><path d="M19.3645 12.4113C20.2926 12.4113 21.1694 12.638 21.94 13.038C20.0434 11.8465 18.7837 9.73669 18.7837 7.33146C18.7837 7.16563 18.7893 7.00119 18.8018 6.83815C18.4688 9.76455 16.1385 12.0866 13.2065 12.4044C13.8545 13.1193 14.3785 13.9484 14.745 14.857C15.7497 13.3798 17.4443 12.4113 19.3645 12.4113Z"></path><path d="M14.7312 21.1249V21.1236C14.1279 20.2331 13.7767 19.1587 13.7767 18.0007V17.9728C13.7767 15.3084 12.2285 13.0035 9.9835 11.911C9.98141 11.9103 9.97967 11.9096 9.97793 11.9089C9.97619 11.9082 9.97444 11.9075 9.97235 11.9068C9.96817 11.904 9.96538 11.9026 9.9612 11.9012C9.95981 11.9012 9.95981 11.8998 9.95981 11.8998C9.9417 11.8915 9.92394 11.8831 9.90618 11.8747C9.8884 11.8664 9.87063 11.858 9.85251 11.8497C9.82046 11.8343 9.78701 11.819 9.75357 11.8051L9.74521 11.8009C8.91745 11.4372 8.0019 11.2351 7.03898 11.2351C3.31826 11.2351 0.30127 14.2521 0.30127 17.9728C0.30127 21.6935 3.31826 24.7105 7.03898 24.7105C7.98797 24.7105 8.89098 24.514 9.71037 24.1601C9.71246 24.1594 9.7142 24.1583 9.71594 24.1573C9.71768 24.1562 9.71943 24.1552 9.72152 24.1545C9.8107 24.1169 9.8985 24.0765 9.9849 24.0333L9.98629 24.0319C10.7625 23.6919 11.6181 23.5037 12.5197 23.5037C12.7524 23.5037 12.9824 23.5163 13.2081 23.54C13.2082 23.5399 13.2081 23.54 13.2081 23.54C15.0168 23.7365 16.5971 24.695 17.6185 26.0885C17.9195 25.1688 18.3752 24.3201 18.9563 23.5732C17.1964 23.4464 15.6635 22.5058 14.7312 21.1249Z"></path><g clip-path="url(#clip0)"><path d="M106.391 18.0021C106.391 11.3724 101.039 6 94.4389 6H88.4585C81.8581 6 76.5061 11.3724 76.5061 18.0021V30.0042H81.2845V18.0021C81.2845 14.0268 84.4941 10.8008 88.4585 10.8008H94.4347C98.395 10.8008 101.609 14.0226 101.609 18.0021V30.0042H106.391V18.0021Z"></path><path d="M149.432 6H142.258C135.653 6 130.301 11.3724 130.301 18.0021C130.301 24.6319 135.653 30.0042 142.258 30.0042H149.432C156.036 30.0042 161.388 24.6319 161.388 18.0021C161.388 11.3724 156.032 6 149.432 6ZM149.432 25.1992H142.258C138.297 25.1992 135.084 21.9774 135.084 17.9979C135.084 14.0183 138.293 10.7966 142.258 10.7966H149.432C153.392 10.7966 156.606 14.0183 156.606 17.9979C156.606 21.9774 153.392 25.1992 149.432 25.1992Z"></path><path d="M74.1151 25.1992H58.5736C55.4526 25.1992 52.804 23.1924 51.8171 20.3983H74.1151V17.9979C74.1151 17.1808 74.1868 16.3807 74.3175 15.5975H51.8171C52.804 12.8033 55.4526 10.7966 58.5736 10.7966H76.0383C77.1475 8.87458 78.6911 7.22773 80.5299 6H58.5736C51.969 6 46.6169 11.3724 46.6169 18.0021C46.6169 24.6276 51.969 30 58.5736 30H74.1151V25.1992Z"></path><path d="M120.74 6H115.958H102.369C104.212 7.22773 105.751 8.87458 106.861 10.8008H115.958V30H120.74V10.8008H129.838C130.947 8.87458 132.486 7.22773 134.329 6H120.74Z"></path><path d="M182.906 15.6017H169.756C168.436 15.6017 167.365 14.5264 167.365 13.2013C167.365 11.8762 168.436 10.8008 169.756 10.8008H188.882V6H169.756C165.796 6 162.582 9.22173 162.582 13.2013C162.582 17.1808 165.791 20.4025 169.756 20.4025H182.906C184.226 20.4025 185.297 21.4779 185.297 22.803C185.297 24.1281 184.226 25.2034 182.906 25.2034H161.852C160.743 27.1297 159.199 28.7765 157.361 30.0042H182.906C186.866 30.0042 190.08 26.7825 190.08 22.803C190.08 18.8234 186.866 15.6017 182.906 15.6017Z"></path></g><defs><clipPath id="clip0"><rect width="190" height="24" fill="white" transform="translate(0 6)"></rect></clipPath></defs></svg>
+                <div>
+                    Entos Envision
+                </div>
+            </a>
+        </div>
         <script>
+            function getParam(name, regex) {
+                var r = new RegExp(name + '=' + '(' + regex + ')[&]?', 'i');
+                return decodeURIComponent(((window.location.search || '').match(r) || [])[1] || '');
+            }
+
+            var debugMode = getParam('debug-mode', '[^&]+').trim() === '1';
+            if (debugMode) AlphaOrbitalsExample.setDebugMode(debugMode);
+
+            var timingMode = getParam('timing-mode', '[^&]+').trim() === '1';
+            if (timingMode) AlphaOrbitalsExample.setTimingMode(timingMode);
+
             AlphaOrbitalsExample.init('app')
         </script>
+        <!-- __MOLSTAR_ANALYTICS__ -->
     </body>
 </html>

src/examples/alpha-orbitals/index.ts

@@ -1,30 +1,33 @@
 /**
- * Copyright (c) 2020 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2020-2022 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author David Sehnal <david.sehnal@gmail.com>
  */
 
+import { BehaviorSubject } from 'rxjs';
+import { debounceTime, skip } from 'rxjs/operators';
+import { AlphaOrbital, Basis } from '../../extensions/alpha-orbitals/data-model';
 import { SphericalBasisOrder } from '../../extensions/alpha-orbitals/spherical-functions';
 import { BasisAndOrbitals, CreateOrbitalDensityVolume, CreateOrbitalRepresentation3D, CreateOrbitalVolume, StaticBasisAndOrbitals } from '../../extensions/alpha-orbitals/transforms';
-import { createPluginAsync } from '../../mol-plugin';
-import { DefaultPluginSpec } from '../../mol-plugin/spec';
+import { canComputeGrid3dOnGPU } from '../../mol-gl/compute/grid3d';
 import { PluginStateObject } from '../../mol-plugin-state/objects';
+import { createPluginUI } from '../../mol-plugin-ui';
+import { renderReact18 } from '../../mol-plugin-ui/react18';
+import { PluginUIContext } from '../../mol-plugin-ui/context';
+import { DefaultPluginUISpec } from '../../mol-plugin-ui/spec';
+import { PluginCommands } from '../../mol-plugin/commands';
 import { PluginConfig } from '../../mol-plugin/config';
-import { PluginContext } from '../../mol-plugin/context';
 import { StateObjectSelector, StateTransformer } from '../../mol-state';
 import { Color } from '../../mol-util/color';
 import { ColorNames } from '../../mol-util/color/names';
 import { ParamDefinition } from '../../mol-util/param-definition';
 import { mountControls } from './controls';
 import { DemoMoleculeSDF, DemoOrbitals } from './example-data';
-import { BehaviorSubject } from 'rxjs';
-import { debounceTime, skip } from 'rxjs/operators';
 import './index.html';
-import { Basis, AlphaOrbital } from '../../extensions/alpha-orbitals/data-model';
-import { PluginCommands } from '../../mol-plugin/commands';
-import { canComputeGrid3dOnGPU } from '../../mol-gl/compute/grid3d';
 require('mol-plugin-ui/skin/light.scss');
 
+import { setDebugMode, setTimingMode, consoleStats } from '../../mol-util/debug';
+
 interface DemoInput {
     moleculeSdf: string,
     basis: Basis,
@@ -50,24 +53,36 @@ type Selectors = {
 }
 
 export class AlphaOrbitalsExample {
-    plugin: PluginContext;
+    plugin: PluginUIContext;
 
     async init(target: string | HTMLElement) {
-        this.plugin = await createPluginAsync(typeof target === 'string' ? document.getElementById(target)! : target, {
-            ...DefaultPluginSpec(),
-            layout: {
-                initial: {
-                    isExpanded: false,
-                    showControls: false
+        const defaultSpec = DefaultPluginUISpec();
+        this.plugin = await createPluginUI({
+            target: typeof target === 'string' ? document.getElementById(target)! : target,
+            render: renderReact18,
+            spec: {
+                ...defaultSpec,
+                layout: {
+                    initial: {
+                        isExpanded: false,
+                        showControls: false
+                    },
                 },
-                controls: { left: 'none', right: 'none', top: 'none', bottom: 'none' },
-            },
-            config: [
-                [PluginConfig.Viewport.ShowExpand, false],
-                [PluginConfig.Viewport.ShowControls, false],
-                [PluginConfig.Viewport.ShowSelectionMode, false],
-                [PluginConfig.Viewport.ShowAnimation, false],
-            ]
+                components: {
+                    controls: { left: 'none', right: 'none', top: 'none', bottom: 'none' },
+                },
+                canvas3d: {
+                    camera: {
+                        helper: { axes: { name: 'off', params: {} } }
+                    }
+                },
+                config: [
+                    [PluginConfig.Viewport.ShowExpand, false],
+                    [PluginConfig.Viewport.ShowControls, false],
+                    [PluginConfig.Viewport.ShowSelectionMode, false],
+                    [PluginConfig.Viewport.ShowAnimation, false],
+                ]
+            }
         });
 
         this.plugin.managers.interactivity.setProps({ granularity: 'element' });
@@ -89,7 +104,7 @@ export class AlphaOrbitalsExample {
     }
 
     readonly params = new BehaviorSubject<ParamDefinition.For<Params>>({} as any);
-    readonly state = new BehaviorSubject<Params>({ show: { name: 'orbital', params: { index: 32 } }, isoValue: 1, gpuSurface: false });
+    readonly state = new BehaviorSubject<Params>({ show: { name: 'orbital', params: { index: 32 } }, isoValue: 1, gpuSurface: true });
 
     private selectors?: Selectors = void 0;
     private basis?: StateObjectSelector<BasisAndOrbitals> = void 0;
@@ -162,11 +177,11 @@ export class AlphaOrbitalsExample {
         return {
             alpha: 0.85,
             color,
-            directVolume: this.state.value.gpuSurface,
             kind,
             relativeIsovalue: this.state.value.isoValue,
             pickable: false,
-            xrayShaded: true
+            xrayShaded: true,
+            tryUseGpu: true
         };
     }
 
@@ -210,4 +225,7 @@ export class AlphaOrbitalsExample {
     }
 }
 
-(window as any).AlphaOrbitalsExample = new AlphaOrbitalsExample();
+(window as any).AlphaOrbitalsExample = new AlphaOrbitalsExample();
+(window as any).AlphaOrbitalsExample.setDebugMode = setDebugMode;
+(window as any).AlphaOrbitalsExample.setTimingMode = setTimingMode;
+(window as any).AlphaOrbitalsExample.consoleStats = consoleStats;

src/examples/basic-wrapper/controls.tsx

@@ -5,7 +5,6 @@
  */
 
 import { PluginUIComponent } from '../../mol-plugin-ui/base';
-import * as React from 'react';
 
 export class CustomToastMessage extends PluginUIComponent {
     render() {

src/examples/basic-wrapper/custom-theme.ts

@@ -0,0 +1,51 @@
+import { isPositionLocation } from '../../mol-geo/util/location-iterator';
+import { Vec3 } from '../../mol-math/linear-algebra';
+import { ColorTheme } from '../../mol-theme/color';
+import { ThemeDataContext } from '../../mol-theme/theme';
+import { Color } from '../../mol-util/color';
+import { ColorNames } from '../../mol-util/color/names';
+import { ParamDefinition as PD } from '../../mol-util/param-definition';
+
+export function CustomColorTheme(
+    ctx: ThemeDataContext,
+    props: PD.Values<{}>
+): ColorTheme<{}> {
+    const { radius, center } = ctx.structure?.boundary.sphere!;
+    const radiusSq = Math.max(radius * radius, 0.001);
+    const scale = ColorTheme.PaletteScale;
+
+    return {
+        factory: CustomColorTheme,
+        granularity: 'vertex',
+        color: location => {
+            if (!isPositionLocation(location)) return ColorNames.black;
+            const dist = Vec3.squaredDistance(location.position, center);
+            const t = Math.min(dist / radiusSq, 1);
+            return ((t * scale) | 0) as Color;
+        },
+        palette: {
+            filter: 'nearest',
+            colors: [
+                ColorNames.red,
+                ColorNames.pink,
+                ColorNames.violet,
+                ColorNames.orange,
+                ColorNames.yellow,
+                ColorNames.green,
+                ColorNames.blue
+            ]
+        },
+        props: props,
+        description: '',
+    };
+}
+
+export const CustomColorThemeProvider: ColorTheme.Provider<{}, 'basic-wrapper-custom-color-theme'> = {
+    name: 'basic-wrapper-custom-color-theme',
+    label: 'Custom Color Theme',
+    category: ColorTheme.Category.Misc,
+    factory: CustomColorTheme,
+    getParams: () => ({}),
+    defaultValues: { },
+    isApplicable: (ctx: ThemeDataContext) => true,
+};

src/examples/basic-wrapper/index.html

@@ -69,8 +69,9 @@
             $('format').value = format;
             $('format').onchange = function (e) { format = e.target.value; }
 
-            BasicMolStarWrapper.init('app' /** or document.getElementById('app') */);
-            BasicMolStarWrapper.setBackground(0xffffff);
+            BasicMolStarWrapper.init('app' /** or document.getElementById('app') */).then(() => {
+                BasicMolStarWrapper.setBackground(0xffffff);
+            });
 
             addControl('Load Asym Unit', () => BasicMolStarWrapper.load({ url: url, format: format }));
             addControl('Load Assembly', () => BasicMolStarWrapper.load({ url: url, format: format, assemblyId: assemblyId }));
@@ -97,6 +98,7 @@
             addHeader('Misc');
 
             addControl('Apply Stripes', () => BasicMolStarWrapper.coloring.applyStripes());
+            addControl('Apply Custom Theme', () => BasicMolStarWrapper.coloring.applyCustomTheme());
             addControl('Default Coloring', () => BasicMolStarWrapper.coloring.applyDefault());
 
             addHeader('Interactivity');

src/examples/basic-wrapper/index.ts

@@ -4,49 +4,61 @@
  * @author David Sehnal <david.sehnal@gmail.com>
  */
 
+import { PDBeStructureQualityReport } from '../../extensions/pdbe';
 import { EmptyLoci } from '../../mol-model/loci';
 import { StructureSelection } from '../../mol-model/structure';
-import { createPlugin } from '../../mol-plugin';
-import { DefaultPluginSpec } from '../../mol-plugin/spec';
 import { AnimateModelIndex } from '../../mol-plugin-state/animation/built-in/model-index';
 import { BuiltInTrajectoryFormat } from '../../mol-plugin-state/formats/trajectory';
+import { createPluginUI } from '../../mol-plugin-ui';
+import { PluginUIContext } from '../../mol-plugin-ui/context';
+import { renderReact18 } from '../../mol-plugin-ui/react18';
+import { DefaultPluginUISpec } from '../../mol-plugin-ui/spec';
 import { PluginCommands } from '../../mol-plugin/commands';
-import { PluginContext } from '../../mol-plugin/context';
 import { Script } from '../../mol-script/script';
+import { Asset } from '../../mol-util/assets';
 import { Color } from '../../mol-util/color';
 import { StripedResidues } from './coloring';
 import { CustomToastMessage } from './controls';
+import { CustomColorThemeProvider } from './custom-theme';
 import './index.html';
 import { buildStaticSuperposition, dynamicSuperpositionTest, StaticSuperpositionTestData } from './superposition';
-import { PDBeStructureQualityReport } from '../../extensions/pdbe';
-import { Asset } from '../../mol-util/assets';
 require('mol-plugin-ui/skin/light.scss');
 
 type LoadParams = { url: string, format?: BuiltInTrajectoryFormat, isBinary?: boolean, assemblyId?: string }
 
 class BasicWrapper {
-    plugin: PluginContext;
+    plugin: PluginUIContext;
 
-    init(target: string | HTMLElement) {
-        this.plugin = createPlugin(typeof target === 'string' ? document.getElementById(target)! : target, {
-            ...DefaultPluginSpec(),
-            layout: {
-                initial: {
-                    isExpanded: false,
-                    showControls: false
+    async init(target: string | HTMLElement) {
+        this.plugin = await createPluginUI({
+            target: typeof target === 'string' ? document.getElementById(target)! : target,
+            render: renderReact18,
+            spec: {
+                ...DefaultPluginUISpec(),
+                layout: {
+                    initial: {
+                        isExpanded: false,
+                        showControls: false
+                    }
                 },
-                controls: {
-                    // left: 'none'
+                components: {
+                    remoteState: 'none'
                 }
-            },
-            components: {
-                remoteState: 'none'
             }
         });
 
         this.plugin.representation.structure.themes.colorThemeRegistry.add(StripedResidues.colorThemeProvider!);
+        this.plugin.representation.structure.themes.colorThemeRegistry.add(CustomColorThemeProvider);
         this.plugin.managers.lociLabels.addProvider(StripedResidues.labelProvider!);
         this.plugin.customModelProperties.register(StripedResidues.propertyProvider, true);
+
+        this.plugin.managers.dragAndDrop.addHandler('custom-wrapper', (files) => {
+            if (files.some(f => f.name.toLowerCase().endsWith('.testext'))) {
+                console.log('.testext File dropped');
+                return true;
+            }
+            return false;
+        });
     }
 
     async load({ url, format = 'mmcif', isBinary = false, assemblyId = '' }: LoadParams) {
@@ -61,7 +73,7 @@ class BasicWrapper {
                 params: { id: assemblyId }
             } : {
                 name: 'model',
-                params: { }
+                params: {}
             },
             showUnitcell: false,
             representationPreset: 'auto'
@@ -75,12 +87,20 @@ class BasicWrapper {
     toggleSpin() {
         if (!this.plugin.canvas3d) return;
 
+        const trackball = this.plugin.canvas3d.props.trackball;
         PluginCommands.Canvas3D.SetSettings(this.plugin, {
-            settings: props => {
-                props.trackball.spin = !props.trackball.spin;
+            settings: {
+                trackball: {
+                    ...trackball,
+                    animate: trackball.animate.name === 'spin'
+                        ? { name: 'off', params: {} }
+                        : { name: 'spin', params: { speed: 1 } }
+                }
             }
         });
-        if (!this.plugin.canvas3d.props.trackball.spin) PluginCommands.Camera.Reset(this.plugin, {});
+        if (this.plugin.canvas3d.props.trackball.animate.name !== 'spin') {
+            PluginCommands.Camera.Reset(this.plugin, {});
+        }
     }
 
     private animateModelIndexTargetFps() {
@@ -93,10 +113,10 @@ class BasicWrapper {
             onceForward: () => { this.plugin.managers.animation.play(AnimateModelIndex, { duration: { name: 'computed', params: { targetFps: this.animateModelIndexTargetFps() } }, mode: { name: 'once', params: { direction: 'forward' } } }); },
             onceBackward: () => { this.plugin.managers.animation.play(AnimateModelIndex, { duration: { name: 'computed', params: { targetFps: this.animateModelIndexTargetFps() } }, mode: { name: 'once', params: { direction: 'backward' } } }); },
             palindrome: () => { this.plugin.managers.animation.play(AnimateModelIndex, { duration: { name: 'computed', params: { targetFps: this.animateModelIndexTargetFps() } }, mode: { name: 'palindrome', params: {} } }); },
-            loop: () => { this.plugin.managers.animation.play(AnimateModelIndex, { duration: { name: 'computed', params: { targetFps: this.animateModelIndexTargetFps() } }, mode: { name: 'loop', params: {} } }); },
+            loop: () => { this.plugin.managers.animation.play(AnimateModelIndex, { duration: { name: 'computed', params: { targetFps: this.animateModelIndexTargetFps() } }, mode: { name: 'loop', params: { direction: 'forward' } } }); },
             stop: () => this.plugin.managers.animation.stop()
         }
-    }
+    };
 
     coloring = {
         applyStripes: async () => {
@@ -106,6 +126,13 @@ class BasicWrapper {
                 }
             });
         },
+        applyCustomTheme: async () => {
+            this.plugin.dataTransaction(async () => {
+                for (const s of this.plugin.managers.structure.hierarchy.current.structures) {
+                    await this.plugin.managers.structure.component.updateRepresentationsTheme(s.components, { color: CustomColorThemeProvider.name as any });
+                }
+            });
+        },
         applyDefault: async () => {
             this.plugin.dataTransaction(async () => {
                 for (const s of this.plugin.managers.structure.hierarchy.current.structures) {
@@ -113,7 +140,7 @@ class BasicWrapper {
                 }
             });
         }
-    }
+    };
 
     interactivity = {
         highlightOn: () => {
@@ -131,7 +158,7 @@ class BasicWrapper {
         clearHighlight: () => {
             this.plugin.managers.interactivity.lociHighlights.highlightOnly({ loci: EmptyLoci });
         }
-    }
+    };
 
     tests = {
         staticSuperposition: async () => {
@@ -162,7 +189,7 @@ class BasicWrapper {
             PluginCommands.Toast.Hide(this.plugin, { key: 'toast-1' });
             PluginCommands.Toast.Hide(this.plugin, { key: 'toast-2' });
         }
-    }
+    };
 }
 
 (window as any).BasicMolStarWrapper = new BasicWrapper();

src/examples/domain-annotation-server/mapping.ts

@@ -38,7 +38,7 @@ type MappingRow = Table.Row<S.mapping>;
 
 function writeDomain(enc: CifWriter.Encoder, domain: DomainAnnotation | undefined) {
     if (!domain) return;
-    enc.writeCategory({ name: `pdbx_${domain.name}_domain_annotation`, instance: () =>  CifWriter.Category.ofTable(domain.domains) });
+    enc.writeCategory({ name: `pdbx_${domain.name}_domain_annotation`, instance: () => CifWriter.Category.ofTable(domain.domains) });
     enc.writeCategory({ name: `pdbx_${domain.name}_domain_mapping`, instance: () => CifWriter.Category.ofTable(domain.mappings) });
 }
 

src/examples/domain-annotation-server/server.ts

@@ -15,7 +15,7 @@ async function getMappings(id: string) {
 };
 
 
-let PORT = process.env.port || 1338;
+const PORT = process.env.port || 1338;
 
 const app = express();
 

src/examples/image-renderer/index.ts

@@ -0,0 +1,94 @@
+/**
+ * Copyright (c) 2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Adam Midlik <midlik@gmail.com>
+ *
+ * Example command-line application generating images of PDB structures
+ * Build: npm install --no-save gl jpeg-js pngjs  // these packages are not listed in dependencies for performance reasons
+ *        npm run build
+ * Run:   node lib/commonjs/examples/image-renderer 1cbs ../outputs_1cbs/
+ */
+
+import { ArgumentParser } from 'argparse';
+import fs from 'fs';
+import path from 'path';
+import gl from 'gl';
+import pngjs from 'pngjs';
+import jpegjs from 'jpeg-js';
+
+import { Download, ParseCif } from '../../mol-plugin-state/transforms/data';
+import { ModelFromTrajectory, StructureComponent, StructureFromModel, TrajectoryFromMmCif } 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, STYLIZED_POSTPROCESSING } from '../../mol-plugin/util/headless-screenshot';
+import { setFSModule } from '../../mol-util/data-source';
+
+
+setFSModule(fs);
+
+interface Args {
+    pdbId: string,
+    outDirectory: string
+}
+
+function parseArguments(): Args {
+    const parser = new ArgumentParser({ description: 'Example command-line application generating images of PDB structures' });
+    parser.add_argument('pdbId', { help: 'PDB identifier' });
+    parser.add_argument('outDirectory', { help: 'Directory for outputs' });
+    const args = parser.parse_args();
+    return { ...args };
+}
+
+async function main() {
+    const args = parseArguments();
+    const url = `https://www.ebi.ac.uk/pdbe/entry-files/download/${args.pdbId}.bcif`;
+    console.log('PDB ID:', args.pdbId);
+    console.log('Source URL:', url);
+    console.log('Outputs:', args.outDirectory);
+
+    // Create a headless plugin
+    const externalModules: ExternalModules = { gl, pngjs, 'jpeg-js': jpegjs };
+    const plugin = new HeadlessPluginContext(externalModules, DefaultPluginSpec(), { width: 800, height: 800 });
+    await plugin.init();
+
+    // Download and visualize data in the plugin
+    const update = plugin.build();
+    const structure = update.toRoot()
+        .apply(Download, { url, isBinary: true })
+        .apply(ParseCif)
+        .apply(TrajectoryFromMmCif)
+        .apply(ModelFromTrajectory)
+        .apply(StructureFromModel);
+    const polymer = structure.apply(StructureComponent, { type: { name: 'static', params: 'polymer' } });
+    const ligand = structure.apply(StructureComponent, { type: { name: 'static', params: 'ligand' } });
+    polymer.apply(StructureRepresentation3D, {
+        type: { name: 'cartoon', params: { alpha: 1 } },
+        colorTheme: { name: 'sequence-id', params: {} },
+    });
+    ligand.apply(StructureRepresentation3D, {
+        type: { name: 'ball-and-stick', params: { sizeFactor: 1 } },
+        colorTheme: { name: 'element-symbol', params: { carbonColor: { name: 'element-symbol', params: {} } } },
+        sizeTheme: { name: 'physical', params: {} },
+    });
+    await update.commit();
+
+    // Export images
+    fs.mkdirSync(args.outDirectory, { recursive: true });
+    await plugin.saveImage(path.join(args.outDirectory, 'basic.png'));
+    await plugin.saveImage(path.join(args.outDirectory, 'basic.jpg'));
+    await plugin.saveImage(path.join(args.outDirectory, 'large.png'), { width: 1600, height: 1200 });
+    await plugin.saveImage(path.join(args.outDirectory, 'large.jpg'), { width: 1600, height: 1200 });
+    await plugin.saveImage(path.join(args.outDirectory, 'stylized.png'), undefined, STYLIZED_POSTPROCESSING);
+    await plugin.saveImage(path.join(args.outDirectory, 'stylized.jpg'), undefined, STYLIZED_POSTPROCESSING);
+    await plugin.saveImage(path.join(args.outDirectory, 'stylized-compressed-jpg.jpg'), undefined, STYLIZED_POSTPROCESSING, undefined, 10);
+
+    // Export state loadable in Mol* Viewer
+    await plugin.saveStateSnapshot(path.join(args.outDirectory, 'molstar-state.molj'));
+
+    // Cleanup
+    await plugin.clear();
+    plugin.dispose();
+}
+
+main();

src/examples/lighting/index.html

@@ -45,8 +45,9 @@
         <div id='controls'></div>
         <div id="app"></div>
         <script>
-            LightingDemo.init('app')
-            LightingDemo.load({ url: 'https://models.rcsb.org/4KTC.bcif', assemblyId: '1' }, 5, 1.3)
+            LightingDemo.init('app').then(() => {
+                LightingDemo.load({ url: 'https://models.rcsb.org/4KTC.bcif', assemblyId: '1' }, 5, 1.3);
+            });
 
             addHeader('Example PDB IDs');
             addControl('4KTC', () => LightingDemo.load({ url: 'https://models.rcsb.org/4KTC.bcif', assemblyId: '1' }, 5, 1.3));
@@ -83,5 +84,6 @@
                 $('controls').appendChild(h);
             }
         </script>
+        <!-- __MOLSTAR_ANALYTICS__ -->
     </body>
 </html>

src/examples/lighting/index.ts

@@ -1,59 +1,104 @@
 /**
- * Copyright (c) 2019 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2019-2023 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
 
 import { Canvas3DProps } from '../../mol-canvas3d/canvas3d';
-import { createPlugin } from '../../mol-plugin';
-import { DefaultPluginSpec } from '../../mol-plugin/spec';
 import { BuiltInTrajectoryFormat } from '../../mol-plugin-state/formats/trajectory';
+import { createPluginUI } from '../../mol-plugin-ui';
+import { PluginUIContext } from '../../mol-plugin-ui/context';
+import { renderReact18 } from '../../mol-plugin-ui/react18';
+import { DefaultPluginUISpec } from '../../mol-plugin-ui/spec';
 import { PluginCommands } from '../../mol-plugin/commands';
-import { PluginContext } from '../../mol-plugin/context';
-import './index.html';
 import { Asset } from '../../mol-util/assets';
+import { Color } from '../../mol-util/color';
+import './index.html';
 require('mol-plugin-ui/skin/light.scss');
 
 type LoadParams = { url: string, format?: BuiltInTrajectoryFormat, isBinary?: boolean, assemblyId?: string }
 
-type _Preset = Pick<Canvas3DProps, 'multiSample' | 'postprocessing' | 'renderer'>
+type _Preset = Pick<Canvas3DProps, 'postprocessing' | 'renderer'>
 type Preset = { [K in keyof _Preset]: Partial<_Preset[K]> }
 
 const Canvas3DPresets = {
-    illustrative: <Preset> {
-        multiSample: {
-            mode: 'temporal' as Canvas3DProps['multiSample']['mode']
-        },
-        postprocessing: {
-            occlusion: { name: 'on', params: { samples: 32, radius: 6, bias: 1.4, blurKernelSize: 15 } },
-            outline: { name: 'on', params: { scale: 1, threshold: 0.1 } }
-        },
-        renderer: {
-            style: { name: 'flat', params: {} }
+    illustrative: {
+        canvas3d: <Preset>{
+            postprocessing: {
+                occlusion: {
+                    name: 'on',
+                    params: {
+                        samples: 32,
+                        multiScale: { name: 'off', params: {} },
+                        radius: 5,
+                        bias: 0.8,
+                        blurKernelSize: 15,
+                        resolutionScale: 1,
+                        color: Color(0x000000),
+                    }
+                },
+                outline: {
+                    name: 'on',
+                    params: {
+                        scale: 1,
+                        threshold: 0.33,
+                        color: Color(0x000000),
+                        includeTransparent: true,
+                    }
+                },
+                shadow: {
+                    name: 'off',
+                    params: {}
+                },
+            },
+            renderer: {
+                ambientIntensity: 1.0,
+                light: []
+            }
         }
     },
-    occlusion: <Preset> {
-        multiSample: {
-            mode: 'temporal' as Canvas3DProps['multiSample']['mode']
-        },
-        postprocessing: {
-            occlusion: { name: 'on', params: { samples: 32, radius: 6, bias: 1.4, blurKernelSize: 15 } },
-            outline: { name: 'off', params: { } }
-        },
-        renderer: {
-            style: { name: 'matte', params: {} }
+    occlusion: {
+        canvas3d: <Preset>{
+            postprocessing: {
+                occlusion: {
+                    name: 'on',
+                    params: {
+                        samples: 32,
+                        multiScale: { name: 'off', params: {} },
+                        radius: 5,
+                        bias: 0.8,
+                        blurKernelSize: 15,
+                        resolutionScale: 1,
+                    }
+                },
+                outline: {
+                    name: 'off',
+                    params: {}
+                },
+                shadow: {
+                    name: 'off',
+                    params: {}
+                },
+            },
+            renderer: {
+                ambientIntensity: 0.4,
+                light: [{ inclination: 180, azimuth: 0, color: Color.fromNormalizedRgb(1.0, 1.0, 1.0),
+                    intensity: 0.6 }]
+            }
         }
     },
-    standard: <Preset> {
-        multiSample: {
-            mode: 'off' as Canvas3DProps['multiSample']['mode']
-        },
-        postprocessing: {
-            occlusion: { name: 'off', params: { } },
-            outline: { name: 'off', params: { } }
-        },
-        renderer: {
-            style: { name: 'matte', params: {} }
+    standard: {
+        canvas3d: <Preset>{
+            postprocessing: {
+                occlusion: { name: 'off', params: {} },
+                outline: { name: 'off', params: {} },
+                shadow: { name: 'off', params: {} },
+            },
+            renderer: {
+                ambientIntensity: 0.4,
+                light: [{ inclination: 180, azimuth: 0, color: Color.fromNormalizedRgb(1.0, 1.0, 1.0),
+                    intensity: 0.6 }]
+            }
         }
     }
 };
@@ -62,21 +107,27 @@ const Canvas3DPresets = {
 type Canvas3DPreset = keyof typeof Canvas3DPresets
 
 class LightingDemo {
-    plugin: PluginContext;
+    plugin: PluginUIContext;
 
     private radius = 5;
     private bias = 1.1;
     private preset: Canvas3DPreset = 'illustrative';
 
-    init(target: string | HTMLElement) {
-        this.plugin = createPlugin(typeof target === 'string' ? document.getElementById(target)! : target, {
-            ...DefaultPluginSpec(),
-            layout: {
-                initial: {
-                    isExpanded: false,
-                    showControls: false
+    async init(target: string | HTMLElement) {
+        this.plugin = await createPluginUI({
+            target: typeof target === 'string' ? document.getElementById(target)! : target,
+            render: renderReact18,
+            spec: {
+                ...DefaultPluginUISpec(),
+                layout: {
+                    initial: {
+                        isExpanded: false,
+                        showControls: false
+                    },
                 },
-                controls: { left: 'none', right: 'none', top: 'none', bottom: 'none' }
+                components: {
+                    controls: { left: 'none', right: 'none', top: 'none', bottom: 'none' }
+                }
             }
         });
 
@@ -85,25 +136,23 @@ class LightingDemo {
 
     setPreset(preset: Canvas3DPreset) {
         const props = Canvas3DPresets[preset];
-        if (props.postprocessing.occlusion?.name === 'on') {
-            props.postprocessing.occlusion.params.radius = this.radius;
-            props.postprocessing.occlusion.params.bias = this.bias;
+        if (props.canvas3d.postprocessing.occlusion?.name === 'on') {
+            props.canvas3d.postprocessing.occlusion.params.radius = this.radius;
+            props.canvas3d.postprocessing.occlusion.params.bias = this.bias;
         }
-        PluginCommands.Canvas3D.SetSettings(this.plugin, { settings: {
-            ...props,
-            multiSample: {
-                ...this.plugin.canvas3d!.props.multiSample,
-                ...props.multiSample
-            },
-            renderer: {
-                ...this.plugin.canvas3d!.props.renderer,
-                ...props.renderer
-            },
-            postprocessing: {
-                ...this.plugin.canvas3d!.props.postprocessing,
-                ...props.postprocessing
-            },
-        }});
+        PluginCommands.Canvas3D.SetSettings(this.plugin, {
+            settings: {
+                ...props,
+                renderer: {
+                    ...this.plugin.canvas3d!.props.renderer,
+                    ...props.canvas3d.renderer
+                },
+                postprocessing: {
+                    ...this.plugin.canvas3d!.props.postprocessing,
+                    ...props.canvas3d.postprocessing
+                },
+            }
+        });
     }
 
     async load({ url, format = 'mmcif', isBinary = true, assemblyId = '' }: LoadParams, radius: number, bias: number) {
@@ -112,7 +161,7 @@ class LightingDemo {
         const data = await this.plugin.builders.data.download({ url: Asset.Url(url), isBinary }, { state: { isGhost: true } });
         const trajectory = await this.plugin.builders.structure.parseTrajectory(data, format);
         const model = await this.plugin.builders.structure.createModel(trajectory);
-        const structure = await this.plugin.builders.structure.createStructure(model, assemblyId ? { name: 'assembly', params: { id: assemblyId } } : { name: 'model', params: { } });
+        const structure = await this.plugin.builders.structure.createStructure(model, assemblyId ? { name: 'assembly', params: { id: assemblyId } } : { name: 'model', params: {} });
 
         const polymer = await this.plugin.builders.structure.tryCreateComponentStatic(structure, 'polymer');
         if (polymer) await this.plugin.builders.structure.representation.addRepresentation(polymer, { type: 'spacefill', color: 'illustrative' });

src/examples/proteopedia-wrapper/index.html

@@ -103,10 +103,11 @@
 
             PluginWrapper.init('app' /** or document.getElementById('app') */, {
                 customColorList: CustomColors
+            }).then(() => {
+                PluginWrapper.setBackground(0xffffff);
+                loadAndSnapshot({ url: url, format: format, isBinary: isBinary, assemblyId: assemblyId, representationStyle: representationStyle });
+                PluginWrapper.toggleSpin();
             });
-            PluginWrapper.setBackground(0xffffff);
-            loadAndSnapshot({ url: url, format: format, isBinary: isBinary, assemblyId: assemblyId, representationStyle: representationStyle });
-            PluginWrapper.toggleSpin();
 
             PluginWrapper.events.modelInfo.subscribe(function (info) {
                 console.log('Model Info', info);

src/examples/proteopedia-wrapper/index.ts

@@ -6,15 +6,16 @@
 
 import * as ReactDOM from 'react-dom';
 import { Canvas3DProps, DefaultCanvas3DParams } from '../../mol-canvas3d/canvas3d';
-import { createPlugin } from '../../mol-plugin';
-import { DefaultPluginSpec } from '../../mol-plugin/spec';
 import { AnimateModelIndex } from '../../mol-plugin-state/animation/built-in/model-index';
 import { createStructureRepresentationParams } from '../../mol-plugin-state/helpers/structure-representation-params';
 import { PluginStateObject, PluginStateObject as PSO } from '../../mol-plugin-state/objects';
 import { StateTransforms } from '../../mol-plugin-state/transforms';
+import { createPluginUI } from '../../mol-plugin-ui';
+import { renderReact18 } from '../../mol-plugin-ui/react18';
+import { PluginUIContext } from '../../mol-plugin-ui/context';
+import { DefaultPluginUISpec } from '../../mol-plugin-ui/spec';
 import { CreateVolumeStreamingInfo, InitVolumeStreaming } from '../../mol-plugin/behavior/dynamic/volume-streaming/transformers';
 import { PluginCommands } from '../../mol-plugin/commands';
-import { PluginContext } from '../../mol-plugin/context';
 import { PluginState } from '../../mol-plugin/state';
 import { MolScriptBuilder as MS } from '../../mol-script/language/builder';
 import { StateBuilder, StateObject, StateSelection } from '../../mol-state';
@@ -41,24 +42,28 @@ class MolStarProteopediaWrapper {
         modelInfo: this._ev<ModelInfo>()
     };
 
-    plugin: PluginContext;
+    plugin: PluginUIContext;
 
-    init(target: string | HTMLElement, options?: {
+    async init(target: string | HTMLElement, options?: {
         customColorList?: number[]
     }) {
-        this.plugin = createPlugin(typeof target === 'string' ? document.getElementById(target)! : target, {
-            ...DefaultPluginSpec(),
-            animations: [
-                AnimateModelIndex
-            ],
-            layout: {
-                initial: {
-                    isExpanded: false,
-                    showControls: false
+        this.plugin = await createPluginUI({
+            target: typeof target === 'string' ? document.getElementById(target)! : target,
+            render: renderReact18,
+            spec: {
+                ...DefaultPluginUISpec(),
+                animations: [
+                    AnimateModelIndex
+                ],
+                layout: {
+                    initial: {
+                        isExpanded: false,
+                        showControls: false
+                    }
+                },
+                components: {
+                    remoteState: 'none'
                 }
-            },
-            components: {
-                remoteState: 'none'
             }
         });
 
@@ -95,7 +100,7 @@ class MolStarProteopediaWrapper {
                 params: { id: assemblyId }
             } : {
                 name: 'model' as const,
-                params: { }
+                params: {}
             }
         };
 
@@ -113,7 +118,7 @@ class MolStarProteopediaWrapper {
         const structure = this.getObj<PluginStateObject.Molecule.Structure>(StateElements.Assembly);
         if (!structure) return;
 
-        const style = _style || { };
+        const style = _style || {};
 
         const update = this.state.build();
 
@@ -229,7 +234,7 @@ class MolStarProteopediaWrapper {
                     params: { id: asmId }
                 } : {
                     name: 'model' as const,
-                    params: { }
+                    params: {}
                 }
             };
             tree.to(StateElements.Assembly).update(StateTransforms.Model.StructureFromModel, p => ({ ...p, ...props }));
@@ -250,13 +255,22 @@ class MolStarProteopediaWrapper {
     setBackground(color: number) {
         if (!this.plugin.canvas3d) return;
         const renderer = this.plugin.canvas3d.props.renderer;
-        PluginCommands.Canvas3D.SetSettings(this.plugin, { settings: { renderer: { ...renderer,  backgroundColor: Color(color) } } });
+        PluginCommands.Canvas3D.SetSettings(this.plugin, { settings: { renderer: { ...renderer, backgroundColor: Color(color) } } });
     }
 
     toggleSpin() {
         if (!this.plugin.canvas3d) return;
         const trackball = this.plugin.canvas3d.props.trackball;
-        PluginCommands.Canvas3D.SetSettings(this.plugin, { settings: { trackball: { ...trackball, spin: !trackball.spin } } });
+        PluginCommands.Canvas3D.SetSettings(this.plugin, {
+            settings: {
+                trackball: {
+                    ...trackball,
+                    animate: trackball.animate.name === 'spin'
+                        ? { name: 'off', params: {} }
+                        : { name: 'spin', params: { speed: 1 } }
+                }
+            }
+        });
     }
 
     viewport = {
@@ -269,8 +283,8 @@ class MolStarProteopediaWrapper {
 
     camera = {
         toggleSpin: () => this.toggleSpin(),
-        resetPosition: () => PluginCommands.Camera.Reset(this.plugin, { })
-    }
+        resetPosition: () => PluginCommands.Camera.Reset(this.plugin, {})
+    };
 
     private animateModelIndexTargetFps() {
         return Math.max(1, this.animate.modelIndex.targetFps | 0);
@@ -282,10 +296,10 @@ class MolStarProteopediaWrapper {
             onceForward: () => { this.plugin.managers.animation.play(AnimateModelIndex, { duration: { name: 'computed', params: { targetFps: this.animateModelIndexTargetFps() } }, mode: { name: 'once', params: { direction: 'forward' } } }); },
             onceBackward: () => { this.plugin.managers.animation.play(AnimateModelIndex, { duration: { name: 'computed', params: { targetFps: this.animateModelIndexTargetFps() } }, mode: { name: 'once', params: { direction: 'backward' } } }); },
             palindrome: () => { this.plugin.managers.animation.play(AnimateModelIndex, { duration: { name: 'computed', params: { targetFps: this.animateModelIndexTargetFps() } }, mode: { name: 'palindrome', params: {} } }); },
-            loop: () => { this.plugin.managers.animation.play(AnimateModelIndex, { duration: { name: 'computed', params: { targetFps: this.animateModelIndexTargetFps() } }, mode: { name: 'loop', params: {} } }); },
+            loop: () => { this.plugin.managers.animation.play(AnimateModelIndex, { duration: { name: 'computed', params: { targetFps: this.animateModelIndexTargetFps() } }, mode: { name: 'loop', params: { direction: 'forward' } } }); },
             stop: () => this.plugin.managers.animation.stop()
         }
-    }
+    };
 
     coloring = {
         evolutionaryConservation: async (params?: { sequence?: boolean, het?: boolean, keepStyle?: boolean }) => {
@@ -306,7 +320,7 @@ class MolStarProteopediaWrapper {
 
             await PluginCommands.State.Update(this.plugin, { state, tree });
         }
-    }
+    };
 
     private experimentalDataElement?: Element = void 0;
     experimentalData = {
@@ -330,17 +344,17 @@ class MolStarProteopediaWrapper {
                 this.experimentalDataElement = void 0;
             }
         }
-    }
+    };
 
     hetGroups = {
         reset: () => {
             const update = this.state.build().delete(StateElements.HetGroupFocusGroup);
             PluginCommands.State.Update(this.plugin, { state: this.state, tree: update });
-            PluginCommands.Camera.Reset(this.plugin, { });
+            PluginCommands.Camera.Reset(this.plugin, {});
         },
         focusFirst: async (compId: string, options?: { hideLabels: boolean, doNotLabelWaters: boolean }) => {
             if (!this.state.transforms.has(StateElements.Assembly)) return;
-            await PluginCommands.Camera.Reset(this.plugin, { });
+            await PluginCommands.Camera.Reset(this.plugin, {});
 
             const update = this.state.build();
 
@@ -397,7 +411,7 @@ class MolStarProteopediaWrapper {
             const snapshot = this.plugin.canvas3d!.camera.getFocus(sphere.center, radius);
             PluginCommands.Camera.SetSnapshot(this.plugin, { snapshot, durationMs: 250 });
         }
-    }
+    };
 
     snapshot = {
         get: (params?: PluginState.SnapshotParams) => {
@@ -420,7 +434,7 @@ class MolStarProteopediaWrapper {
             }
         }
 
-    }
+    };
 }
 
 (window as any).MolStarProteopediaWrapper = MolStarProteopediaWrapper;

src/examples/proteopedia-wrapper/ui/controls.tsx

@@ -4,14 +4,13 @@
  * @author David Sehnal <david.sehnal@gmail.com>
  */
 
-import * as React from 'react';
 import * as ReactDOM from 'react-dom';
+import { PluginUIContext } from '../../../mol-plugin-ui/context';
 import { PluginContextContainer } from '../../../mol-plugin-ui/plugin';
 import { TransformUpdaterControl } from '../../../mol-plugin-ui/state/update-transform';
-import { PluginContext } from '../../../mol-plugin/context';
 import { StateElements } from '../helpers';
 
-export function volumeStreamingControls(plugin: PluginContext, parent: Element) {
+export function volumeStreamingControls(plugin: PluginUIContext, parent: Element) {
     ReactDOM.render(<PluginContextContainer plugin={plugin}>
         <TransformUpdaterControl nodeRef={StateElements.VolumeStreaming} />
     </PluginContextContainer>, parent);

src/extensions/alpha-orbitals/_spec/collocation.spec.ts

@@ -50,7 +50,7 @@ const _testBasis: Basis = {
                 0.025886090588624934,
                 0.019164790004065606,
                 -0.013539970104105408
-            ] as Vec3,
+            ],
             'shells': [
                 {
                     'angularMomentum': [0],
@@ -101,7 +101,7 @@ const _testBasis: Basis = {
                 0.5082729578468134,
                 1.6880351220025265,
                 0.4963443067810461
-            ] as Vec3,
+            ],
             'shells': [
                 {
                     'angularMomentum': [0],
@@ -158,7 +158,7 @@ const _testBasis: Basis = {
                 1.1367367844436005,
                 -0.47018519422670163,
                 -1.356802622574504
-            ] as Vec3,
+            ],
             'shells': [
                 {
                     'angularMomentum': [0],

src/extensions/alpha-orbitals/collocation.ts

@@ -53,7 +53,7 @@ export async function sphericalCollocation(
                     L,
                     shell.coefficients[amIndex++],
                     shell.exponents,
-                    atom.center,
+                    atom.center as unknown as Vec3,
                     cutoffThreshold,
                     alpha
                 );

src/extensions/alpha-orbitals/data-model.ts

@@ -9,6 +9,7 @@ import { Grid } from '../../mol-model/volume';
 import { SphericalBasisOrder } from './spherical-functions';
 import { Box3D, RegularGrid3d } from '../../mol-math/geometry';
 import { arrayMin, arrayMax, arrayRms, arrayMean } from '../../mol-util/array';
+import { ModelFormat } from '../../mol-model-formats/format';
 
 // Note: generally contracted gaussians are currently not supported.
 export interface SphericalElectronShell {
@@ -21,7 +22,7 @@ export interface SphericalElectronShell {
 export interface Basis {
     atoms: {
         // in Bohr units!
-        center: Vec3;
+        center: [number, number, number];
         shells: SphericalElectronShell[];
     }[];
 }
@@ -59,6 +60,17 @@ export interface CubeGrid {
     isovalues?: { negative?: number; positive?: number };
 }
 
+export type CubeGridFormat = ModelFormat<CubeGrid>;
+
+// eslint-disable-next-line
+export function CubeGridFormat(grid: CubeGrid): CubeGridFormat {
+    return { name: 'custom grid', kind: 'cube-grid', data: grid };
+}
+
+export function isCubeGridData(f: ModelFormat): f is CubeGridFormat {
+    return f.kind === 'cube-grid';
+}
+
 export function initCubeGrid(params: CubeGridComputationParams): CubeGridInfo {
     const geometry = params.basis.atoms.map(a => a.center);
     const { gridSpacing: spacing, boxExpand: expand } = params;
@@ -66,7 +78,7 @@ export function initCubeGrid(params: CubeGridComputationParams): CubeGridInfo {
     const count = geometry.length;
     const box = Box3D.expand(
         Box3D(),
-        Box3D.fromVec3Array(Box3D(), geometry),
+        Box3D.fromVec3Array(Box3D(), geometry as unknown as Vec3[]),
         Vec3.create(expand, expand, expand)
     );
     const size = Box3D.size(Vec3(), box);

src/extensions/alpha-orbitals/density.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2020 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2020-2022 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author David Sehnal <david.sehnal@gmail.com>
  */
@@ -8,6 +8,7 @@ import { sortArray } from '../../mol-data/util';
 import { canComputeGrid3dOnGPU } from '../../mol-gl/compute/grid3d';
 import { WebGLContext } from '../../mol-gl/webgl/context';
 import { Task } from '../../mol-task';
+import { isTimingMode } from '../../mol-util/debug';
 import { AlphaOrbital, createGrid, CubeGrid, CubeGridComputationParams, initCubeGrid } from './data-model';
 import { gpuComputeAlphaOrbitalsDensityGridValues } from './gpu/compute';
 
@@ -19,9 +20,9 @@ export function createSphericalCollocationDensityGrid(
 
         let matrix: Float32Array;
         if (canComputeGrid3dOnGPU(webgl)) {
-            // console.time('gpu');
-            matrix = await gpuComputeAlphaOrbitalsDensityGridValues(ctx, webgl!, cubeGrid, orbitals);
-            // console.timeEnd('gpu');
+            if (isTimingMode) webgl.timer.mark('createSphericalCollocationDensityGrid');
+            matrix = await gpuComputeAlphaOrbitalsDensityGridValues(ctx, webgl, cubeGrid, orbitals);
+            if (isTimingMode) webgl.timer.markEnd('createSphericalCollocationDensityGrid');
         } else {
             throw new Error('Missing OES_texture_float WebGL extension.');
         }

src/extensions/alpha-orbitals/orbitals.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2020 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2020-2022 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * Inspired by https://github.com/dgasmith/gau2grid.
  *
@@ -10,12 +10,11 @@ import { sortArray } from '../../mol-data/util';
 import { canComputeGrid3dOnGPU } from '../../mol-gl/compute/grid3d';
 import { WebGLContext } from '../../mol-gl/webgl/context';
 import { Task } from '../../mol-task';
+import { isTimingMode } from '../../mol-util/debug';
 import { sphericalCollocation } from './collocation';
 import { AlphaOrbital, createGrid, CubeGrid, CubeGridComputationParams, initCubeGrid } from './data-model';
 import { gpuComputeAlphaOrbitalsGridValues } from './gpu/compute';
 
-// setDebugMode(true);
-
 export function createSphericalCollocationGrid(
     params: CubeGridComputationParams, orbital: AlphaOrbital, webgl?: WebGLContext
 ): Task<CubeGrid> {
@@ -24,9 +23,9 @@ export function createSphericalCollocationGrid(
 
         let matrix: Float32Array;
         if (canComputeGrid3dOnGPU(webgl)) {
-            // console.time('gpu');
-            matrix = await gpuComputeAlphaOrbitalsGridValues(ctx, webgl!, cubeGrid, orbital);
-            // console.timeEnd('gpu');
+            if (isTimingMode) webgl.timer.mark('createSphericalCollocationGrid');
+            matrix = await gpuComputeAlphaOrbitalsGridValues(ctx, webgl, cubeGrid, orbital);
+            if (isTimingMode) webgl.timer.markEnd('createSphericalCollocationGrid');
         } else {
             // console.time('cpu');
             matrix = await sphericalCollocation(cubeGrid, orbital, ctx);