tweaks

add external-structure theme

.eslintignore

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

.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",
@@ -55,7 +55,8 @@
         "block-spacing": "error",
         "keyword-spacing": "off",
         "space-before-blocks": "error",
-        "semi-spacing": "error"
+        "semi-spacing": "error",
+        "no-constant-binary-expression": "error"
     },
     "overrides": [
         {
@@ -107,6 +108,7 @@
                     "1tbs", { "allowSingleLine": true }
                 ],
                 "@typescript-eslint/comma-spacing": "error",
+                "@typescript-eslint/space-infix-ops": "error",
                 "@typescript-eslint/space-before-function-paren": ["error", {
                     "anonymous": "always",
                     "named": "never",

.github/pull_request_template.md

@@ -0,0 +1,11 @@
+<!-- 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`
+- [ ] (Optional but encouraged) Improved documentation in `docs`

.github/workflows/docs.yml

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

.github/workflows/node.yml

@@ -1,6 +1,10 @@
+name: Build
+
 on:
   push:
+    branches: master
   pull_request:
+    branches: master
 
 jobs:
   build:
@@ -9,12 +13,12 @@ jobs:
     - uses: actions/checkout@v2
     - uses: actions/setup-node@v2
       with:
-        node-version: 17
+        node-version: 18
     - run: npm ci
     - run: sudo apt-get install xvfb
     - name: Lint
       run: npm run lint
     - name: Test
-      run: xvfb-run --auto-servernum npm run jest
+      run: npm install --no-save "gl@^6.0.2" && xvfb-run --auto-servernum npm run jest
     - name: Build
       run: npm run build

.gitignore

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

.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"

CHANGELOG.md

@@ -3,9 +3,974 @@ All notable changes to this project will be documented in this file, following t
 
 Note that since we don't clearly distinguish between a public and private interfaces there will be changes in non-major versions that are potentially breaking. If we make breaking changes to less used interfaces we will highlight it in here.
 
-
 ## [Unreleased]
 
+- Volume UI improvements
+  - Render all volume entries instead of selecting them one-by-one
+  - Toggle visibility of all volumes
+  - More accessible iso value control
+- Support wheel event on sliders
+- MolViewSpec extension:
+  - Add validation for discriminated union params
+  - Primitives: remove triangle_colors, line_colors, have implicit grouping instead; rename many parameters
+- Add `external-structure` theme that colors any geometry by structure properties
+- Support float and half-float data type for direct-volume rendering and GPU isosurface extraction
+- Minor documentation updates
+- Fix plugin mouse interactions when CSS `scale` transform is applied
+
+## [v4.10.0] - 2024-12-15
+
+- Add `ModelWithCoordinates` decorator transform.
+- Fix outlines on transparent background using illumination mode (#1364)
+- Fix transparent depth texture artifacts using illumination mode
+- Fix marking of consecutive gap elements (#876)
+- Allow React 19 in dependencies
+- Fix missing deflate header if `CompressionStream` is available
+- Fix is_iOS check for NodeJS
+- Added PluginCommands.Camera.FocusObject
+- Plugin state snapshot can have instructions to focus objects (PluginState.Snapshot.camera.focus)
+- MolViewSpec extension: Support for multi-state files (animations)
+- Fix units transform data not fully updated when structure child changes
+- Fix `addIndexPairBonds` quadratic runtime case
+- Use adjoint matrix to transform normals in shaders
+- Fix resize handling in `tests/browser`
+
+## [v4.9.1] - 2024-12-05
+
+- Fix iOS check when running on Node
+
+## [v4.9.0] - 2024-12-01
+
+- Fix artifacts when using xray shading with high xrayEdgeFalloff values
+- Enable double rounded capping on tubular helices
+- Fix single residue tubular helices not showing up
+- Fix outlines on volume and surface reps that do not disappear (#1326)
+- Add example `glb-export`
+- Membrane orientation: Improve `isApplicable` check and error handling (#1316)
+- Fix set fenceSync to null after deleteSync.
+- Fix operator key-based `IndexPairBonds` assignment
+    - Don't add bonds twice
+    - Add `IndexPairs.bySameOperator` to avoid looping over all bonds for each unit
+- Add `Structure.intraUnitBondMapping`
+- Add more structure-based visuals to avoid too many (small) render-objects
+    - `structure-intra-bond`, `structure-ellipsoid-mesh`, `structure-element-point`, `structure-element-cross`
+- Upgrade to express v5 (#1311)
+- Fix occupancy check using wrong index for inter-unit bond computation (@rxht, #1321)
+- Fix transparent SSAO for image rendering, e.g., volumne slices (#1332)
+- Fix bonds not shown with `ignoreHydrogens` on (#1315)
+    - Better handle mmCIF files with no entities defined by using `label_asym_id`
+    - Show bonds in water chains when `ignoreHydorgensVariant` is `non-polar`
+- Add MembraneServer API, generating data to be consumed in the context of MolViewSpec
+- Fix `StructConn.isExhaustive` for partial models (e.g., returned by the model server)
+- Refactor value swapping in molstar-math to fix SWC (Next.js) build (#1345)
+- Fix transform data not updated when structure child changes
+- Fix `PluginStateSnapshotManager.syncCurrent` to work as expected on re-loaded states.
+- Fix do not compute implicit hydrogens when unit is explicitly protonated (#1257)
+- ModelServer and VolumeServer: support for input files from Google Cloud Storage (gs://)
+- Fix color of missing partial charges for SB partial charges extension
+
+## [v4.8.0] - 2024-10-27
+
+- Add SSAO support for transparent geometry
+- Fix SSAO color not updating
+- Improve blending of overlapping outlines from transparent & opaque geometries
+- Default to `blended` transparency on iOS due to `wboit` not being supported.
+- Fix direct-volume with fog off (and on with `dpoit`) and transparent background on (#1286)
+- Fix missing pre-multiplied alpha for `blended` & `wboit` with no fog (#1284)
+- Fix backfaces visible using blended transparency on impostors (#1285)
+- Fix StructureElement.Loci.isSubset() only considers common units (#1292)
+- Fix `Scene.opacityAverage` calculation never 1
+- Fix bloom in illumination mode
+- Fix `findPredecessorIndex` bug when repeating values
+- MolViewSpec: Support for transparency and custom properties
+- MolViewSpec: MVP Support for geometrical primitives (mesh, lines, line, label, distance measurement)
+- Mesoscale Explorer: Add support for 4-character PDB IDs (e.g., 8ZZC) in PDB-Dev loader
+- Fix Sequence View in Safari 18
+- Improve performance of `IndexPairBonds` assignment when operator keys are available
+- ModelArchive QualityAssessment extension:
+    - Add support for ma_qa_metric_local_pairwise mmCIF category
+    - Add PAE plot component
+- Add new AlphaFoldDB-PAE example app
+- Add support for LAMMPS data and dump formats
+- Remove extra anti-aliasing from text shader (fixes #1208 & #1306)
+
+## [v4.7.1] - 2024-09-30
+
+- Improve `resolutionMode` (#1279)
+    - Add `auto` that picks `scaled` for mobile devices and `native` elsewhere
+    - Add `resolution-mode` Viewer GET param
+    - Add `PluginConfig.General.ResolutionMode` config item
+
+## [v4.7.0] - 2024-09-29
+
+- Add illumination mode
+    - Path-traced SSGI
+    - Automatic thickness (estimate)
+        - Base thickness as max(backface depth) - min(frontface depth)
+        - Per object density factor to adjust thickness
+    - Progressively trace samples to keep viewport interactive
+    - Toggle on/off by pressing "G"
+    - `illumination` Viewer GET param
+- Enables dXrayShaded define when rendering depth
+- Fix handling of PDB files that have chains with same id separated by TER record (#1245)
+- Sequence Panel: Improve visuals of unmodeled sequence positions (#1248)
+- Fix no-compression xtc parser (#1258)
+- Mol2 Reader: Fix mol2 status_bit read error (#1251)
+- Fix shadows with multiple lights
+- Fix impostor sphere interior normal when using orthographic projection
+- Add `resolutionMode` parameter to `Canvas3DContext`
+    - `scaled`, divides by `devicePixelRatio`
+    - `native`, no changes
+- Add `CustomProperty.Context.errorContext` to support reporting errors during loading of custom properties (#1254)
+    - Use in MolViewSpec extension
+- Mesoscale Explorer: fix color & style issues
+- Remove use of deprecated SASS explicit color functions
+- Allow "Components" section to display nested components created by "Apply Action > Selection".
+
+## [v4.6.0] - 2024-08-28
+
+- Add round-caps option on tubular alpha helices
+- Fix missing Sequence UI update on state object removal (#1219)
+- Improved prmtop format support (CTITLE, %COMMENT)
+- Avoid calculating bonds for water units when `ignoreHydrogens` is on
+- Add `Water` trait to `Unit`
+- Improve entity-id coloring for structures with multiple models from the same source (#1221)
+- Wrap screenshot & image generation in a `Task`
+- AlphaFold DB: Add BinaryCIF support when fetching data
+- PDB-Dev: Add support for 4-character PDB IDs (e.g., 8ZZC)
+- Fix polymer-gap visual coloring with cartoon theme
+- Add formal-charge color theme (#328)
+- Add more coloring options to cartoon theme
+- Use `CompressionStream` Browser API when available
+- Add `pdbx_structure_determination_methodology` mmcif field and `Model` helpers
+- Fix cartoon representation not updated when secondary structure changes
+- Add Zhang-Skolnick secondary-structure assignment method which handles coarse-grained models (#49)
+- Calculate bonds for coarse-grained models
+- VolumeServer: Add `health-check` endpoint + `healthCheckPath` config prop to report service health
+- ModelServer: Add `health-check` endpoint + `healthCheckPath` config prop to report service health
+
+## [v4.5.0] - 2024-07-28
+
+- Separated postprocessing passes
+- Take into account explicit hydrogens when computing hydrogen bonds
+- Fix DoF with pixel ratios =! 1
+- Fix DoF missing transparent depth
+- Fix trackball pinch zoom and add pan
+- Fix aromatic link rendering when `adjustCylinderLength` is true
+- Change trackball animate spin speed unit to radians per second
+- Fix `mol-plugin-ui/skin/base/components/misc.scss` syntax to be in line with latest Sass syntax
+- Handle missing theme updates
+    - Fix trajectory-index color-theme not always updated (#896)
+    - Fix bond cylinders not updated on size-theme change with `adjustCylinderLength` enabled (#1215)
+- Use `OES_texture_float_linear` for SSAO when available
+
+## [v4.4.1] - 2024-06-30
+
+- Clean `solidInterior` transparent cylinders
+- Create a transformer to deflate compressed data
+- Adjust Quick Styles panel button labels
+- Improve camera interpolation code (interpolate camera rotation instead of just position)
+- Mesoscale Explorer
+    - Add `illustrative` coloring option
+    - Press 'C' to toggle between center and zoom & center on click
+    - Add entities selection description
+    - Clicking a leaf node in the right panel tree will center each instance in turn
+    - Add measurement controls to right panel
+    - Mouse left click on label with snapshot key will load snapshot
+    - Mouse hover over label with protein name highlight entities with the same name
+    - Custom ViewportSnapshotDescription with custom MarkdowAnchor
+        - \# other snapshots with a given key \[...](#key)
+        - i highlight a protein with a given NAME \[...](iNAME)
+        - g highlight a group with a given group type and group name \[...](ggrouptype.groupname)
+        - h URLs with a given link \[...](http...)
+    - Snapshot description panel window size and text can be resized and hidden with new icons
+    - Add styles controls to right panel
+    - Add viewport settings to left panel
+    - Add app info component to left panel with interactive tour and doc link
+- Fixes SSAO edge artifacts (#1122)
+    - Add `reuseOcclusion` parameter to multi-sample pass
+    - Add `blurDepthBias` parameter to occlusion pass
+    - Handle near clip in SSAO blur
+- Support reading score from B-factor in pLDDT color theme
+- Add Cel-shading support
+    - `celShaded` geometry parameter
+    - `celSteps` renderer parameter
+- Add the ability to customize the Snapshot Description component via `PluginUISpec.components.viewport.snapshotDescription`
+- Add `doNotDisposeCanvas3DContext` option to `PluginContext.dispose`
+- Remove support for density data from edmaps.rcsb.org
+
+## [v4.3.0] - 2024-05-26
+
+- Fix State Snapshots export animation (#1140)
+- Add depth of field (dof) postprocessing effect
+- Add `SbNcbrTunnels` extension for for visualizing tunnels in molecular structures from ChannelsDB (more info in [tunnels.md](./docs/docs/extensions/tunnels.md))
+- Fix edge case in minimizing RMSD transform computation
+
+## [v4.2.0] - 2024-05-04
+
+- Add emissive material support
+- Add bloom post-processing
+- MolViewSpec extension: `loadMVS` supports `keepCamera` parameter
+- Return StateTransform selectors from measurements API (addDistance, addAngle, etc.)
+- Refactor transparency rendering
+    - More uniform behavior for blended, wboit, dpoit
+    - Fix issues with text & image geometry
+- Fix render-spheres example (#1100)
+    - Wrong step size in sphere geometry boundingSphere & groupmapping
+    - Handle empty `instanceGrid` in renderer & renderable
+- Fix bond assignment from `IndexPairBonds`
+    - Can not always be cached in `ElementSetIntraBondCache`
+    - Wrong operator checks in `findPairBonds`
+- Fix SSAO artifacts (@corredD, #1082)
+- Fix bumpiness artifacts (#1107, #1084)
+
+## [v4.1.0] - 2024-03-31
+
+- Add `VolumeTransform` to translate/rotate a volume like in a structure superposition
+- Fix BinaryCIF encoder edge cases caused by re-encoding an existing BinaryCIF file
+- Fix edge-case where width/height in InputObserver are not correct
+- Fix transparency rendering fallback (#1058)
+- Fix SSAO broken when `OES_texture_float_linear` is unavailable
+- Add `normalOffset` to `external-volume` color theme
+    - This can give results similar to pymol's surface_ramp_above_mode=1
+- Add `rotation` parameter to skybox background
+
+## [v4.0.1] - 2024-02-19
+
+- Fix BinaryCIF decoder edge cases. Fixes mmCIF model export from data provided by ModelServer.
+- MolViewSpec extension: support for MVSX file format
+- Revert "require WEBGL_depth_texture extension" & "remove renderbuffer use"
+
+## [v4.0.0] - 2024-02-04
+
+- Add Mesoscale Explorer app for investigating large systems
+- [Breaking] Remove `cellpack` extension (superseded by Mesoscale Explorer app)
+- [Breaking] Set minimal node.js version to 18
+- [Breaking] Generalize rcsb/assembly-symmetry/ extension
+    - Move to assembly-symmetry/
+    - Remove RCSB specific dependencies and prefixes
+- [Breaking] Require `WEBGL_depth_texture` webgl extension
+    - Remove `renderbuffer` use
+- [Breaking] Change build target to ES2018
+    - Custom builds only require ES6 for dependencies like immer.js
+- [Breaking] Changed `createPluginUI`
+    - The function now takes a single `options` argument
+    - The caller must specify a `render` method that mounts the Mol* react component to DOM
+        - A default `renderReact18` method is provided, but needs to be imported separately
+        - To support React 16 and 17, `ReactDOM.render` can be passed
+- Improve `SetUtils` performance using ES6 features
+- [Breaking] Reduce memory usage of `SymmetryOperator.ArrayMapping`
+    - Requires calling methods from instance
+- [Breaking] Fix `mol-model/structure/model/properties/seconday-structure.ts` file name (#938)
+- [Breaking] Add `Canvas3DContext` runtime props
+    - Props: pixelScale, pickScale, transparency (blended, wboit, dpoit)
+    - Replaces instantiation-time attribs
+- [Breaking] Change default compile target to ES2018
+- [Breaking] Add culling & LOD support
+    - Cull per-object and per-instance
+    - Cull based on frustum and camera distance
+    - LOD visibility based on camera distance
+    - Special LOD mode for spheres with automatic levels
+    - Occlusion culling (only WebGL2)
+        - Hi-Z pass
+        - Cull based on previous frame's Hi-Z buffer
+- Add stochastic/dithered transparency to fade overlapping LODs in and out
+- Add "Automatic Detail" preset that shows surface/cartoon/ball & stick based on camera distance
+
+## [v3.45.0] - 2024-02-03
+
+- Add color interpolation to impostor cylinders
+- MolViewSpec components are applicable only when the model has been loaded from MolViewSpec
+- Add `snapshotKey` and `tooltip` params to loci `LabelRepresentation`
+- Update `FocusLoci` behavior to support `snapshotKey` param
+  - Clicking a visual with `snapshotKey` will trigger that snapshot
+- Render multiline loci label tooltips as Markdown
+- `ParamDefinition.Text` updates:
+  - Support `multiline` inputs
+  - Support `placeholder` parameter
+  - Support `disableInteractiveUpdates` to only trigger updates once the control loses focus
+- Move dependencies related to the headless context from optional deps to optional peer deps
+
+## [v3.44.0] - 2024-01-06
+
+- Add new `cartoon` visuals to support atomic nucleotide base with sugar
+- Add `thicknessFactor` to `cartoon` representation for scaling nucleotide block/ring/atomic-fill visuals
+- Use bonds from `_struct_conn` in mmCIF files that use `label_seq_id`
+- Fix measurement label `offsetZ` default: not needed when `scaleByRadius` is enbaled
+- Support for label rendering in HeadlessPluginContext
+- MolViewSpec extension
+  - Support all X11 colors
+  - Support relative URIs
+  - CLI tools: mvs-validate, mvs-render, mvs-print-schema
+  - Labels applied in one node
+- ModelServer SDF/MOL2 ligand export: fix atom indices when additional atoms are present
+- Avoid showing (and calculating) inter-unit bonds for huge structures
+- Fixed `DragOverlay` on WebKit/Safari browsers
+
+## [v3.43.1] - 2023-12-04
+
+- Fix `react-markdown` dependency
+
+## [v3.43.0] - 2023-12-02
+
+- Fix `State.tryGetCellData` (return type & data check)
+- Don't change camera.target unless flyMode or pointerLock are enabled
+- Handle empty CIF files
+- Snapshot improvements:
+    - Add `key` property
+    - Ability to existing snapshot name, key, and description
+    - Support markdown in descriptions (ignores all HTML tags)
+    - Ability to link to snapshots by key from descriptions
+    - Separate UI control showing description of the current snapshot
+- Do not activate drag overlay for non-file content
+- Add `structure-element-sphere` visual to `spacefill` representation
+- Fix missing `await` in `HeadlessPluginContext.saveStateSnapshot`
+- Added support for providing custom sequence viewers to the plugin spec
+- MolViewSpec extension (MVS)
+- Add URL parameters `mvs-url`, `mvs-data`, `mvs-format`
+- Add drag&drop for `.mvsj` files
+- Fix `bumpiness` scaling with `ignoreLight` enabled
+- Add `transforms` & `label` params to `ShapeFromPly`
+- Optimize `LociSelectManager.selectOnly` to avoid superfluous loci set operations
+- Dispose of viewer on `unload` event to aid GC
+
+## [v3.42.0] - 2023-11-05
+
+- Fix handling of PDB files with insertion codes (#945)
+- Fix de-/saturate of colors with no hue
+- Improve `distinctColors` function
+    - Add `sort` and `sampleCountFactor` parameters
+    - Fix clustering issues
+- Add `clipPrimitive` option to spheres geometry, clipping whole spheres instead of cutting them
+- Add `DragAndDropManager`
+- Add `options` support for default bond labels
+
+## [v3.41.0] - 2023-10-15
+
+- Add `PluginContext.initialized` promise & support for it in the `Plugin` UI component.
+- Fix undesired interaction between settings panel and the panel on the right.
+- Add ability to customize server parameters for `RCSBAssemblySymmetry`.
+
+## [v3.40.1] - 2023-09-30
+
+- Do not call `updateFocusRepr` if default `StructureFocusRepresentation` isn't present.
+- Treat "tap" as a click in `InputObserver`
+- ModelServer ligand queries: fix atom count reported by SDF/MOL/MOL2 export
+- CCD extension: Make visuals for aromatic bonds configurable
+- Add optional `file?: CifFile` to `MmcifFormat.data`
+- Add support for webgl extensions
+    - `WEBGL_clip_cull_distance`
+    - `EXT_conservative_depth`
+    - `WEBGL_stencil_texturing`
+    - `EXT_clip_control`
+- Add `MultiSampleParams.reduceFlicker` (to be able to switch it off)
+- Add `alphaThickness` parameter to adjust alpha of spheres for radius
+- Ability to hide "right" panel from simplified viewport controls
+- Add `blockIndex` parameter to TrajectoryFromMmCif
+- Fix bounding sphere calculation for "element-like" visuals
+- Fix RCSB PDB validation report URL
+- Add sharpening postprocessing option
+- Take pixel-ratio into account for outline scale
+- Gracefully handle missing HTMLImageElement
+- Fix pixel-ratio changes not applied to all render passes
+
+## [v3.39.0] - 2023-09-02
+
+- Add some elements support for `guessElementSymbolString` function
+- Faster bounding rectangle calculation for imposter spheres
+- Allow toggling of hydrogens as part of `LabelTextVisual`
+
+## [v3.38.3] - 2023-07-29
+
+- Fix imposter spheres not updating, e.g. in trajectories (broke in v3.38.0)
+
+## [v3.38.2] - 2023-07-24
+
+- Don't rely solely on `chem_comp_atom` when detecting CCD files (#877)
+- Actually support non-physical keys in `Bindings.Trigger.code`
+
+## [v3.38.1] - 2023-07-22
+
+- Fix pixel-scale not updated in SSAO pass
+
+## [v3.38.0] - 2023-07-18
+
+- Fix display issue with SIFTS mapping
+- Support non-physical keys in `Bindings.Trigger.code`
+- Update `getStateSnapshot` to only overwrite current snapshot if it was created automatically
+- Fix distinct palette's `getSamples` infinite loop
+- Add 'NH2', 'FOR', 'FMT' to `CommonProteinCaps`
+- Add `opened` event to `PluginStateSnapshotManager`
+- Properly switch-off fog
+- Add `approximate` option for spheres rendering
+- Reduce `Spheres` memory usage
+    - Derive mapping from VertexID
+    - Pull position and group from texture
+- Add `Euler` math primitive
+- Add stride option to element sphere & point visuals
+- Add `disabledExtensions` field to default viewer's options
+- Add `LRUCache.remove`
+- Add 'Chain Instance' and 'Uniform' options for 'Carbon Color' param (in Color Theme: Element Symbol)
+
+## [v3.37.1] - 2023-06-20
+
+- Fix issues with wboit/dpoit in large scenes
+- Fix lines, text, points rendering (broken in v3.37.0)
+
+## [v3.37.0] - 2023-06-17
+
+- Add `inverted` option to `xrayShaded` parameter
+- Model-export extension: Add ability to set a file name for structures
+- Add `contextHash` to `SizeTheme`
+- Add mipmap-based blur for image backgrounds
+
+## [v3.36.1] - 2023-06-11
+
+- Allow parsing of CCD ligand files
+- Add dedicated wwPDB CCD extension to align and visualize ideal & model CCD coordinates
+- Make operators in `IndexPairBonds` a directed property
+- Remove erroneous bounding-box overlap test in `Structure.eachUnitPair`
+- Fix `EdgeBuilder.addNextEdge` for loop edges
+- Optimize inter unit bond compute
+- Ensure consistent state for volume representation (#210)
+- Improve SSAO for thin geometry (e.g. lines)
+- Add snapshot support for structure selections
+- Add `nucleicProfile` parameter to cartoon representation
+- Add `cartoon` theme with separate colorings for for mainchain and sidechain visuals
+
+## [v3.35.0] - 2023-05-14
+
+- Enable odd dash count (1,3,5)
+- Add principal axes spec and fix edge cases
+- Add a uniform color theme for NtC tube that still paints residue and segment dividers in a different color
+- Mesh exporter improvements
+    - Support points & lines in glTF export
+    - Set alphaMode and doubleSided in glTF export
+    - Fix flipped cylinder caps
+- Fix bond assignments `struct_conn` records referencing waters
+- Add StructConn extension providing functions for inspecting struct_conns
+- Fix `PluginState.setSnapshot` triggering unnecessary state updates
+- Fix an edge case in the `mol-state`'s `State` when trying to apply a transform to an existing Null object
+- Add `SbNcbrPartialCharges` extension for coloring and labeling atoms and residues by partial atomic charges
+  - uses custom mmcif categories `_sb_ncbr_partial_atomic_charges_meta` and `_sb_ncbr_partial_atomic_charges` (more info in [README.md](./src/extensions/sb-ncbr/README.md))
+- Parse HEADER record when reading PDB file
+- Support `ignoreHydrogens` in interactions representation
+- Add hydroxyproline (HYP) commonly present in collagen molecules to the list of amino acids
+- Fix assemblies for Archive PDB files (do not generate unique `label_asym_id` if `REMARK 350` is present)
+- Add additional functions to `core.math` in `mol-script`
+    - `cantorPairing`, `sortedCantorPairing`, `invertCantorPairing`,
+    - `trunc`, `sign`
+
+## [v3.34.0] - 2023-04-16
+
+- Avoid `renderMarkingDepth` for fully transparent renderables
+- Remove `camera.far` doubling workaround
+- Add `ModifiersKeys.areNone` helper function
+- Do not render NtC tube segments unless all required atoms are present in the structure
+- Fix rendering issues caused by VAO reuse
+- Add "Zoom All", "Orient Axes", "Reset Axes" buttons to the "Reset Camera" button
+- Improve trackball move-state handling when key bindings use modifiers
+- Fix rendering with very small viewport and SSAO enabled
+- Fix `.getAllLoci` for structure representations with `structure.child`
+- Fix `readAllLinesAsync` refering to dom length property
+- Make mol-util/file-info node compatible
+- Add `eachLocation` to representation/visual interface
+
+## [v3.33.0] - 2023-04-02
+
+- Handle resizes of viewer element even when window remains the same size
+- Throttle canvas resize events
+- Selection toggle buttons hidden if selection mode is off
+- Camera focus loci bindings allow reset on click-away to be overridden
+- Input/controls improvements
+    - Move or fly around the scene using keys
+    - Pointer lock to look around scene
+    - Toggle spin/rock animation using keys
+- Apply bumpiness as lightness variation with `ignoreLight`
+- Remove `JSX` reference from `loci-labels.ts`
+- Fix overpaint/transparency/substance smoothing not updated when geometry changes
+- Fix camera project/unproject when using offset viewport
+- Add support for loading all blocks from a mmcif file as a trajectory
+- Add `Frustum3D` and `Plane3D` math primitives
+- Include `occupancy` and `B_iso_or_equiv` when creating `Conformation` from `Model`
+- Remove LazyImports (introduced in v3.31.1)
+
+## [v3.32.0] - 2023-03-20
+
+- Avoid rendering of fully transparent renderables
+- Add occlusion color parameter
+- Fix issue with outlines and orthographic camera
+- Reduce over-blurring occlusion at larger view distances
+- Fix occlusion artefact with non-canvas viewport and pixel-ratio > 1
+- Update nodejs-shims conditionals to handle polyfilled document object in NodeJS environment.
+- Ensure marking edges are at least one pixel wide
+- Add exposure parameter to renderer
+- Only trigger marking when mouse is directly over canvas
+- Fix blurry occlusion in screenshots
+- [Breaking] Add `setFSModule` to `mol-util/data-source` instead of trying to trick WebPack
+
+## [v3.31.4] - 2023-02-24
+
+- Allow link cylinder/line `dashCount` set to '0'
+- Stop animation loop when disposing `PluginContext` (thanks @gfrn for identifying the issue)
+
+## [v3.31.3] - 2023-02-22
+
+- Fix impostor bond visuals not correctly updating on `sizeFactor` changes
+- Fix degenerate case in PCA
+- Fix near clipping avoidance in impostor shaders
+- Update `fs` import in `data-source.ts`
+
+## [v3.31.2] - 2023-02-12
+
+- Fix exit code of volume pack executable (pack.ts). Now exits with non-0 status when an error happens
+- Remove pca transform from components ui focus (too distracting)
+- Fix artefacts with opaque outlines behind transparent objects
+- Fix polymer trace visual not updating
+- Fix use of `WEBGL_provoking_vertex`
+
+## [v3.31.1] - 2023-02-05
+
+- Improve Component camera focus based on the PCA of the structure and the following rules:
+    - The first residue should be in first quadrant if there is only one chain
+    - The average position of the residues of the first chain should be in the first quadrant if there is more than one chain
+- Add `HeadlessPluginContext` and `HeadlessScreenshotHelper` to be used in Node.js
+- Add example `image-renderer`
+- Fix wrong offset when rendering text with orthographic projection
+- Update camera/handle helper when `devicePixelRatio` changes
+- Add various options to customize the axes camera-helper
+- Fix issue with texture-mesh color smoothing when changing themes
+- Add fast boundary helper and corresponding unit trait
+- Add Observable for Canvas3D commits
+
+## [v3.30.0] - 2023-01-29
+
+- Improve `Dnatco` extension
+    - Factor out common code in `Dnatco` extension
+    - Add `NtC tube` visual. Applicable for structures with NtC annotation
+    - [Breaking] Rename `DnatcoConfalPyramids` to `DnatcoNtCs`
+- Improve boundary calculation performance
+- Add option to create & include images in state snapshots
+- Fix SSAO artefacts with high bias values
+- Fix SSAO resolution scale parameter handling
+- Improve outlines, visually more stable at different view distances
+
+## [v3.29.0] - 2023-01-15
+
+- `meshes` extension: Fixed a bug in mesh visualization (show backfaces when opacity < 1)
+- Add color quick select control to Volume controls
+- Fix `dropFiles` bug
+- Fix some cyclic imports and reduce the use of const enums. This should make it easier to use the library with the `isolatedModules: true` TS config.
+- Fix `dropFiles` bug (#679)
+- Add `input type='color'` picker to `CombinedColorControl`
+- Set `ParameterMappingControl` disabled when state is updating
+- Performance tweaks
+    - Update clip `defines` only when changed
+    - Check for identity in structure/unit areEqual methods
+    - Avoid cloning of structure representation parameters
+    - Make SymmetryOperator.createMapping monomorphic
+    - Improve bonding-sphere calculation
+    - Defer Scene properties calculation (markerAverage, opacityAverage, hasOpaque)
+    - Improve checks in in UnitsRepresentation setVisualState
+- Add StructureElement.Loci.forEachLocation
+- Add RepresentationRegistry.clear and ThemeRegistry.clear
+- Add generic Loci support for overpaint, substance, clipping themes
+- Add `.getCenter` and `.center` to `Camera`
+- Add support to dim unmarked groups
+- Add support for marker edge strength
+
+## [v3.28.0] - 2022-12-20
+
+- Show histogram in direct volume control point settings
+- Add `solidInterior` parameter to sphere/cylinder impostors
+- [Breaking] Tweak `ignoreHydrogens` non-polar handling (introduced in 3.27.0)
+- Add `meshes` and `volumes-and-segmentations` extensions
+    - See https://molstarvolseg.ncbr.muni.cz/ for more info
+- Fix missing support for info in `ParamDefinition.Converted`
+- Add support for multi-visual volume representations
+- Improve volume isosurface bounding-sphere
+- Add basic volume segmentation support to core
+    - Add `Volume.Segment` model
+    - Add `Segmentation` custom volume property
+    - Add `SegmentRepresentation` representation
+    - Add `volume-segment` color theme
+- Fix GPU marching cubes failing for large meshes with webgl2 (due to use of float16)
+
+## [v3.27.0] - 2022-12-15
+
+- Add an `includeTransparent` parameter to hide/show outlines of components that are transparent
+- Fix 'once' for animations of systems with many frames
+- Better guard against issue (black fringes) with bumpiness in impostors
+- Improve impostor shaders
+    - Fix sphere near-clipping with orthographic projection
+    - Fix cylinder near-clipping
+    - Add interior cylinder caps
+    - Add per-pixel object clipping
+- Fix `QualityAssessment` assignment bug for structures with different auth vs label sequence numbering
+- Refresh `ApplyActionControl`'s param definition when toggling expanded state
+- Fix `struct_conn` bond assignment for ions
+- Ability to show only polar hydrogens
+
+## [v3.26.0] - 2022-12-04
+
+- Support for ``powerPreference`` webgl attribute. Add ``PluginConfig.General.PowerPreference`` and ``power-preference`` Viewer GET param.
+- Excluded common protein caps `NME` and `ACE` from the ligand selection query
+- Add screen-space shadow post-processing effect
+- Add "Structure Molecular Surface" visual
+- Add `external-volume` theme (coloring of arbitrary geometries by user-selected volume)
+
+## [v3.25.1] - 2022-11-20
+
+- Fix edge-case in `Structure.eachUnitPair` with single-element units
+- Fix 'auto' structure-quality for coarse models
+
+## [v3.25.0] - 2022-11-16
+
+- Fix handling of gzipped assets (reverts #615)
+
+## [v3.24.0] - 2022-11-13
+
+- Make `PluginContext.initContainer` checkered canvas background optional
+- Store URL of downloaded assets to detect zip/gzip based on extension (#615)
+- Add optional `operator.key`; can be referenced in `IndexPairBonds`
+- Add overpaint/transparency/substance theme strength to representations
+- Fix viewport color for transparent background
+
+## [v3.23.0] - 2022-10-19
+
+- Add `PluginContext.initContainer/mount/unmount` methods; these should make it easier to reuse a plugin context with both custom and built-in UI
+- Add `PluginContext.canvas3dInitialized`
+- `createPluginUI` now resolves after the 3d canvas has been initialized
+- Change EM Volume Streaming default from `Whole Structure` to `Auto`
+
+## [v3.22.0] - 2022-10-17
+
+- Replace `VolumeIsosurfaceParams.pickingGranularity` param with `Volume.PickingGranuality`
+
+## [v3.21.0] - 2022-10-17
+
+- Add `VolumeIsosurfaceParams.pickingGranularity` param
+- Prevent component controls collapsing when option is selected
+
+## [v3.20.0] - 2022-10-16
+
+- [Breaking] Rename the ``model-index`` color theme to ``trajectory-index``
+- Add a new ``model-index`` color theme that uniquely colors each loaded model
+- Add the new ``model-index`` and ``structure-index`` color themes as an option for the carbon color in the ``element-symbol`` and ``ilustrative`` color themes
+- Add ``structure-index`` color theme that uniquely colors each root structure
+- Add ``nearest`` method to ``Lookup3D``
+- Add mipmap-based blur for skybox backgrounds
+
+## [v3.19.0] - 2022-10-01
+
+- Fix "empty textures" error on empty canvas
+- Optimize BinaryCIF integer packing encoder
+- Fix dual depth peeling when post-processing is off or when rendering direct-volumes
+- Add ``cameraClipping.minNear`` parameter
+- Fix black artifacts on specular highlights with transparent background
+
+## [v3.18.0] - 2022-09-17
+
+- Integration of Dual depth peeling - OIT method
+- Stereo camera improvements
+    - Fix param updates not applied
+    - Better param ranges and description
+    - Add timer.mark for left/right camera
+
+## [v3.17.0] - 2022-09-11
+
+- [Fix] Clone ``Canvas3DParams`` when creating a ``Canvas3D`` instance to prevent shared state between multiple instances
+- Add ``includeResidueTest`` option to ``alignAndSuperposeWithSIFTSMapping``
+- Add ``parentDisplay`` param for interactions representation.
+- [Experimental] Add support for PyMOL, VMD, and Jmol atom expressions in selection scripts
+- Support for ``failIfMajorPerformanceCaveat`` webgl attribute. Add ``PluginConfig.General.AllowMajorPerformanceCaveat`` and ``allow-major-performance-caveat`` Viewer GET param.
+- Fix handling of PDB TER records (#549)
+- Add support for getting multiple loci from a representation (``.getAllLoci()``)
+- Add ``key`` property to intra- and inter-bonds for referencing source data
+- Fix click event triggered after move
+
+## [v3.16.0] - 2022-08-25
+
+- Support ``globalColorParams`` and ``globalSymmetryParams`` in common representation params
+- Support ``label`` parameter in ``Viewer.loadStructureFromUrl``
+- Fix ``ViewportHelpContent`` Mouse Controls section
+
+## [v3.15.0] - 2022-08-23
+
+- Fix wboit in Safari >=15 (add missing depth renderbuffer to wboit pass)
+- Add 'Around Camera' option to Volume streaming
+- Avoid queuing more than one update in Volume streaming
+
+## [v3.14.0] - 2022-08-20
+
+- Expose inter-bonds compute params in structure
+- Improve performance of inter/intra-bonds compute
+- Fix defaultAttribs handling in Canvas3DContext.fromCanvas
+- Confal pyramids extension improvements
+    - Add custom labels to Confal pyramids
+    - Improve naming of some internal types in Confal pyramids extension coordinate
+    - Add example mmCIF file with categories necessary to display Confal pyramids
+    - Change the lookup logic of NtC steps from residues
+- Add support for download of gzipped files
+- Don't filter IndexPairBonds by element-based rules in MOL/SDF and MOL2 (without symmetry) models
+- Fix Glycam Saccharide Names used by default
+- Fix GPU surfaces rendering in Safari with WebGL2
+- Add ``fov`` (Field of View) Canvas3D parameter
+- Add ``sceneRadiusFactor`` Canvas3D parameter
+- Add background pass (skybox, image, horizontal/radial gradient)
+    - Set simple-settings presets via ``PluginConfig.Background.Styles``
+    - Example presets in new backgrounds extension
+    - Load skybox/image from URL or File (saved in session)
+    - Opacity, saturation, lightness controls for skybox/image
+    - Coverage (viewport or canvas) controls for image/gradient
+- [Breaking] ``AssetManager`` needs to be passed to various graphics related classes
+- Fix SSAO renderable initialization
+- Reduce number of webgl state changes
+    - Add ``viewport`` and ``scissor`` to state object
+    - Add ``hasOpaque`` to scene object
+- Handle edge cases where some renderables would not get (correctly) rendered
+    - Fix text background rendering for opaque text
+    - Fix helper scenes not shown when rendering directly to draw target
+- Fix ``CustomElementProperty`` coloring not working
+
+## [v3.13.0] - 2022-07-24
+
+- Fix: only update camera state if manualReset is off (#494)
+- Improve handling principal axes of points in a plane
+- Add 'material' annotation support for textures
+- More effort to avoid using ``flat`` qualifier in shaders: add ``dVaryingGroup``
+- Enable ``immediateUpdate`` for iso level in isosurface and volume streaming controls
+- Add support to download CCD from configurable URL
+
+## [v3.12.1] - 2022-07-20
+
+- Fix plugin behavior dispose logic to correctly unsubscribe observables.
+
+## [v3.12.0] - 2022-07-17
+
+- Add ``colorMarker`` option to Renderer. This disables the highlight and select marker at a shader level for faster rendering of large scenes in some cases.
+- Bind shared textures only once per pass, not for each render item
+- Fix missing 'material' annotation for some uniforms, causing unnecessary uniform updates
+- Remove use of ``isnan`` in impostor shaders, not needed and causing slowdown
+- Avoid using ``flat`` qualifier in shaders, causing slowdown
+- Improve CellPack's ``adjustStyle`` option (disable ``colorMarker``, set component options, enable marking w/o ghost)
+- Scan all entities when looking for ``struct_conn`` entries (fixes issue when the same ``label_asym_id`` is used in more than one entity)
+
+## [v3.11.0] - 2022-07-04
+
+- Add ``instanceGranularity`` option for marker, transparency, clipping, overpaint, substance data to save memory
+- CellPack extension tweaks
+    - Use instancing to create DNA/RNA curves to save memory
+    - Enable ``instanceGranularity`` by default
+    - Add ``adjustStyle`` option to LoadCellPackModel action (stylized, no multi-sample, no far clipping, chain picking)
+- Structure Superposition now respects pivot's coordinate system
+
+## [v3.10.2] - 2022-06-26
+
+- Fix superfluous shader varying
+- Improve use of gl_VertexID when possible
+
+## [v3.10.1] - 2022-06-26
+
+- Fix groupCount when updating TextureMesh-based visuals
+
+## [v3.10.0] - 2022-06-24
+
+- Add support for Glycam saccharide names
+- Add ``PluginConfig.Viewport.ShowTrajectoryControls`` config option
+
+## [v3.9.1] - 2022-06-19
+
+- Fix missing ``super.componentWillUnmount()`` calls (@simeonborko)
+- Fix missing ``uGroupCount`` update for visuals
+- Fix missing aromatic bond display
+
+## [v3.9.0] - 2022-05-30
+
+- Improve picking by using drawbuffers (when available) to reduce number of drawcalls
+- GPU timing support
+    - Add ``timing-mode`` Viewer GET param
+    - Add support for webgl timer queries
+    - Add timer marks around GPU render & compute operations
+- Volume Server CIF: Add check that a data block contains volume data before parsing
+- Fix ``Scene.clear`` not clearing primitives & volumes arrays (@JonStargaryen)
+- Fix rendering volumes when wboit is switched off and postprocessing is enabled
+
+## [v3.8.2] - 2022-05-22
+
+- Fix ``Scene.opacityAverage`` not taking xray shaded into account
+
+## [v3.8.1] - 2022-05-14
+
+- Fix issues with marking camera/handle helper (#433)
+- Fix issues with array uniforms when running with headless-gl
+- Fix Polymer Chain Instance coloring
+- Improve performance of scene marker/opacity average calculation
+
+## [v3.8.0] - 2022-04-30
+
+- Add support for outlines around transparent objects
+- Improve per-group transparency when wboit is switched off
+- Improve ``ColorTheme`` typing with ``ColorType`` generic.
+    - Defaults to ``ColorTypeLocation``
+    - Set when using ``ColorTypeDirect`` or ``ColorTypeGrid``
+- Fix case handling of ``struct_conf`` mmCIF enumeration field (#425)
+- Fix ``allowTransparentBackfaces`` for per-group transparency
+- Fix ``FormatRegistry.isApplicable`` returning true for unregistered formats
+- Fix: handle building of ``GridLookup3D`` with zero cell size
+- Fix ``ignoreLight`` for direct-volume rendering with webgl1
+- Fix (non-black) outlines when using transparent background
+
+## [v3.7.0] - 2022-04-13
+
+- Fix ``xrayShaded`` for texture-mesh geometries
+- [Breaking] Change ``allowTransparentBackfaces`` to ``transparentBackfaces`` with options ``off``, ``on``, ``opaque``. This was only added in 3.6.0, so allowing a breaking change here.
+    - ``off``: don't show (default)
+    - ``on``: show with transparency
+    - ``opaque``: show fully opaque
+- Add option to disable file drop overlay.
+
+## [v3.6.2] - 2022-04-05
+
+- ModelServer ligand queries: fixes for alternate locations, additional atoms & UNL ligand
+- React 18 friendly ``useBehavior`` hook.
+
+## [v3.6.1] - 2022-04-03
+
+- Fix React18 related UI regressions.
+
+## [v3.6.0] - 2022-04-03
+
+- Check that model and coordinates have same element count when creating a trajectory
+- Fix aromatic rings assignment: do not mix flags and planarity test
+- Improve bonds assignment of coarse grained models: check for IndexPairBonds and exhaustive StructConn
+- Fix unit mapping in bondedAtomicPairs MolScript query
+- Improve pdb parsing: handle non unique atom and chain names (fixes #156)
+- Fix volume streaming for entries with multiple contour lists
+- Add ``allowTransparentBackfaces`` parameter to support double-sided rendering of transparent geometries
+- Fix handling of case insensitive mmCIF enumeration fields (including entity.type)
+- Fix ``disable-wboit`` Viewer GET param
+- Add support for React 18.
+    - Used by importing ``createPluginUI`` from ``mol-plugin-ui/react18``;
+    - In Mol* 4.0, React 18 will become the default option.
+
+## [v3.5.0] - 2022-03-25
+
+- Fix issues with bounding-sphere & color-smoothing (mostly for small geometries)
+- Support BCIF => CIF conversion in ``cif2bcif`` CLI tool
+
+## [v3.4.0] - 2022-03-13
+
+- Fix handling of mmcif with empty ``label_*`` fields
+- Improve saccharide detection (compare against list from CCD)
+- Fix legend label of hydrophobicity color theme
+- Add ``LoadTrajectory`` action
+- Add ``CustomImportControls`` to left panel
+- Add Zenodo import extension (load structures, trajectories, volumes, and zip files)
+- Fix loading of some compressed files within sessions
+- Fix wrong element assignment for atoms with Charmm ion names
+- Fix handling of empty symmetry cell data
+- Add support for ``trr`` and ``nctraj`` coordinates files
+- Add support for ``prmtop`` and ``top`` topology files
+
+## [v3.3.1] - 2022-02-27
+
+- Fix issue with unit boundary reuse (do at visual level instead)
+- Add option to ignore ions for inter-unit bond computation
+
+## [v3.3.0] - 2022-02-27
+
+- Fix parsing contour-level from emdb v3 header files
+- Fix invalid CSS (#376)
+- Fix "texture not renderable" & "texture not bound" warnings (#319)
+- Fix visual for bonds between two aromatic rings
+- Fix visual for delocalized bonds (parsed from mmcif and mol2)
+- Fix ring computation algorithm
+- Add ``UnitResonance`` property with info about delocalized triplets
+- Resolve marking in main renderer loop to improve overall performance
+- Use ``throttleTime`` instead of ``debounceTime`` in sequence viewer for better responsiveness
+- Change line geometry default ``scaleFactor`` to 2 (3 is too big after fixing line rendering)
+- Trajectory animation performance improvements
+    - Reuse ``Model.CoarseGrained`` for coordinate trajectories
+    - Avoid calculating ``InterUnitBonds`` when ``Structure.parent`` ones are empty
+    - Reuse unit boundary if sphere has not changed too much
+    - Don't show 'inter-bond' and 'element-cross' visuals in line representations of polymerAndLigand preset
+- Fix additional mononucleotides detected as polymer components
+- Fix and improve ``canRemap`` handling in ``IntraUnitBonds``
+- Reuse occlusion for secondary passes during multi-sampling
+- Check if marking passes are needed before doing them
+- Add ``resolutionScale`` parameter to allow trading quality of occlusion for performance
+
+## [v3.2.0] - 2022-02-17
+
+- Rename "best database mapping" to "SIFTS Mapping"
+- Add schema and export support for ``atom_site.pdbx_sifts_xref_*`` fields
+- Add schema export support for ``atom_site.pdbx_label_index`` field
+- Add `traceOnly` parameter to chain/UniProt-based structure alignment
+- Store ``IndexPairBonds`` as a dynamic property.
+
+## [v3.1.0] - 2022-02-06
+
+- Fix ``xrayShaded`` & ``ignoreLight`` params not working at the same time
+- Add ``ignoreLight`` to component params
+- Tweaks for cleaner default representation style
+    - Cartoon: use ``nucleotide-ring`` instead of ``nucleotide-block``
+    - Focus: use ``xrayShaded`` instead of opacity; adjust target size; don't show non-covalent interactions twice
+- Fix representation preset side effects (changing post-processing parameters, see #363)
+- Add Quick Styles panel (default, illustrative, stylized)
+- Fix exported structure missing secondary-structure categories (#364)
+- Fix volume streaming error message: distinguish between missing data and server error (#364)
+
+## [v3.0.2] - 2022-01-30
+
+- Fix color smoothing of elongated structures (by fixing ``Sphere.expand`` for spheres with highly directional extrema)
+- Fix entity label not displayed when multiple instances of the same entity are highlighted
+- Fix empty elements created in ``StructureElement.Loci.extendToAllInstances``
+- Measurement options tweaks (allow larger ``textSize``; make ``customText`` essential)
+- Fix visual visibility sync edge case when changing state snapshots
+
+## [v3.0.1] - 2022-01-27
+
+- Fix marking pass not working with ``transparentBackground``
+- Fix pdbe xray maps url not https
+- Fix entity-id color theme broken for non-IHM models
+- Improve/fix marking of ``InteractionsInterUnitVisual`` (mark when all contact-feature members are given)
+- Add missing "entity-id" and "enity-source" options for carbon coloring to "element-symbol" color theme
+- Fix VolumeServer/query CLI
+- Support automatic iso-value adjustment for VolumeServer data in ``Viewer.loadVolumeFromUrl``
+- Emit drag event whenever started within viewport (not only for non-empty loci)
+
+## [v3.0.0] - 2022-01-23
+
+- Assembly handling tweaks:
+    - Do not include suffix for "identity assembly operators"
+    - Do not include assembly-related categories to export if the structure was composed from an assembly
+    - Special case for ``structAsymMap`` if Mol* asym id operator mapping is present
+- Support for opening ZIP files with multiple entries
+- Add Model Export extension
+- Bugfix: Automatically treat empty string as "non-present" value in BinaryCIF writer.
+- Fix coarse model support in entity-id color theme
+- Fix marking of carbohydrate visuals (whole chain could get marked instead of single residue)
+- Add custom colors to "element-symbol", "molecule-type", "residue-name", and "secondary-structure" themes
+- Support/bugfixes for ``atom_site.pdbx_sifts_xref`` categories
+- Improve/fix marking of ``InteractionsIntraUnitVisual`` (mark when all contact-feature members are given)
+
+## [v3.0.0-dev.10] - 2022-01-17
+
+- Fix ``getOperatorsForIndex``
+- Pass animation info (current frame & count) to state animations
+    - Fix camera stutter for "camera spin" animation
+- Add formal charge parsing support for MOL/SDF files (thanks @ptourlas)
+- [Breaking] Cleaner looking ``MembraneOrientationVisuals`` defaults
+- [Breaking] Add rock animation to trackball controls
+    - Add ``animate`` to ``TrackballControlsParams``, remove ``spin`` and ``spinSpeed``
+    - Add ``animate`` to ``SimpleSettingsParams``, remove ``spin``
+- Add "camera rock" state animation
+- Add support for custom colors to "molecule-type" theme
+- [Breaking] Add style parameter to "illustrative" color theme
+    - Defaults to "entity-id" style instead of "chain-id"
+- Add "illustrative" representation preset
+
 ## [v3.0.0-dev.9] - 2022-01-09
 
 - Add PDBj as a ``pdb-provider`` option

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,6 +1,6 @@
 [![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*
@@ -11,6 +11,13 @@ When using Mol*, please cite:
 
 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.
 
+### Protein Data Bank Integrations
+
+- 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/`):
@@ -113,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**
@@ -131,7 +137,7 @@ 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/commonjs/servers/model/preprocess -i file.cif -ob file.bcif
 
@@ -141,6 +147,11 @@ 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
@@ -152,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

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

docs/README.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

docs/docs/extensions/mvs/index.md

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

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

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

docs/docs/extensions/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/docs/extensions/tunnels.md

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

docs/docs/index.md

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

docs/docs/misc/exporting-components.md

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

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

@@ -1,3 +1,5 @@
+# Interesting PDB Entries
+
 * Cyclic polymers (1sfi, 6dny, 1HVZ)
 * B-DNA (1bna)
 * Missing carbonyl oxygen (1gfl)
@@ -13,18 +15,20 @@
     * 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)
 * Discontinuous chains, i.e. gaps in the sequence (3sn6)
 * Lots of sheets (1cbs)
 * DNA (2np2, 1d66)
-* C-alpha only (2rcj)
+* C-alpha only (2RCJ, 6ZIG, 5AJ2)
 * Not cyclic, but termini are backbone-only and within distance but seqIds are not compatible (6SW3)
 * Close backbone atoms but not linked (e.g. 4HIV)
 * Non-standard residues
     * 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)
@@ -34,7 +38,14 @@
     * ACE (many, e.g. 5AGU, 1E1X)
     * ACY in 7ABY
     * NH2 (many, e.g. 6Y13)
-
-Assembly symmetries
-* 5M30 (Assembly 1, C3 local and pseudo)
-* 1RB8 (Assembly 1, I global)
+* 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)

docs/docs/plugin/custom-library.md

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

docs/docs/plugin/data-state.md

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

docs/docs/plugin/examples.md

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

docs/docs/plugin/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/docs/plugin/instance.md

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

docs/docs/plugin/selections.md

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

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

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

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

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

docs/docs/plugin/viewer-state.md

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

docs/mkdocs.yml

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

docs/model-server/readme.md

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

docs/state/transforms.md

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

docs/volume-server/README.md

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

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": "3.0.0-dev.9",
+  "version": "4.10.0",
   "description": "A comprehensive macromolecular library.",
   "homepage": "https://github.com/molstar/molstar#readme",
   "repository": {
@@ -13,14 +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\"",
@@ -28,7 +28,7 @@
     "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-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",
@@ -48,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",
@@ -75,7 +78,9 @@
       "node_modules",
       "lib"
     ],
-    "testURL": "http://localhost/",
+    "testEnvironmentOptions": {
+      "url": "http://localhost/"
+    },
     "testRegex": "\\.spec\\.ts$"
   },
   "author": "Mol* Contributors",
@@ -86,77 +91,116 @@
     "Á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>",
+    "Ryan DiRisio <rjdiris@gmail.com>",
+    "Dušan Veľký <dvelky@mail.muni.cz>",
+    "Neli Fonseca <neli@ebi.ac.uk>",
+    "Paul Pillot <paul.pillot@tandemai.com>",
+    "Herman Bergwerf <post@hbergwerf.nl>",
+    "Eric E <etongfu@outlook.com>",
+    "Xavier Martinez <xavier.martinez.xm@gmail.com>",
+    "Alex Chan <smalldirkalex@gmail.com>",
+    "Simeon Borko <simeon.borko@gmail.com>"
   ],
   "license": "MIT",
   "devDependencies": {
-    "@graphql-codegen/add": "^3.1.0",
-    "@graphql-codegen/cli": "^2.3.0",
-    "@graphql-codegen/time": "^3.1.0",
-    "@graphql-codegen/typescript": "^2.4.1",
-    "@graphql-codegen/typescript-graphql-files-modules": "^2.1.0",
-    "@graphql-codegen/typescript-graphql-request": "^4.3.1",
-    "@graphql-codegen/typescript-operations": "^2.2.1",
-    "@types/cors": "^2.8.12",
-    "@types/gl": "^4.1.0",
-    "@types/jest": "^27.0.3",
-    "@typescript-eslint/eslint-plugin": "^5.5.0",
-    "@typescript-eslint/parser": "^5.5.0",
+    "@types/cors": "^2.8.17",
+    "@types/gl": "^6.0.5",
+    "@types/jest": "^29.5.14",
+    "@types/pngjs": "^6.0.5",
+    "@types/react": "^18.3.16",
+    "@types/react-dom": "^18.3.5",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
     "benchmark": "^2.1.4",
-    "concurrently": "^6.4.0",
-    "cpx2": "^4.0.0",
-    "crypto-browserify": "^3.12.0",
-    "css-loader": "^6.5.1",
-    "eslint": "^8.3.0",
+    "concurrently": "^9.1.0",
+    "cpx2": "^8.0.0",
+    "crypto-browserify": "^3.12.1",
+    "css-loader": "^7.1.2",
+    "eslint": "^8.57.1",
     "extra-watch-webpack-plugin": "^1.0.3",
     "file-loader": "^6.2.0",
-    "fs-extra": "^10.0.0",
-    "graphql": "^15.7.2",
-    "http-server": "^14.0.0",
-    "jest": "^27.3.1",
-    "mini-css-extract-plugin": "^2.4.5",
+    "fs-extra": "^11.2.0",
+    "http-server": "^14.1.1",
+    "jest": "^29.7.0",
+    "jpeg-js": "^0.4.4",
+    "mini-css-extract-plugin": "^2.9.2",
     "path-browserify": "^1.0.1",
     "raw-loader": "^4.0.2",
-    "sass": "^1.43.5",
-    "sass-loader": "^12.3.0",
-    "simple-git": "^2.47.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "sass": "^1.83.0",
+    "sass-loader": "^16.0.4",
+    "simple-git": "^3.27.0",
     "stream-browserify": "^3.0.0",
-    "style-loader": "^3.3.1",
-    "ts-jest": "^27.0.7",
-    "typescript": "^4.5.2",
-    "webpack": "^5.64.4",
-    "webpack-cli": "^4.9.1"
+    "style-loader": "^4.0.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.7.2",
+    "webpack": "^5.97.1",
+    "webpack-cli": "^5.1.4"
   },
   "dependencies": {
-    "@types/argparse": "^2.0.10",
-    "@types/benchmark": "^2.1.1",
-    "@types/compression": "1.7.2",
-    "@types/express": "^4.17.13",
-    "@types/node": "^16.11.10",
-    "@types/node-fetch": "^2.5.12",
-    "@types/react": "^17.0.37",
-    "@types/react-dom": "^17.0.11",
-    "@types/swagger-ui-dist": "3.30.1",
+    "@types/argparse": "^2.0.17",
+    "@types/benchmark": "^2.1.5",
+    "@types/compression": "1.7.5",
+    "@types/express": "^5.0.0",
+    "@types/node": "^18.19.68",
+    "@types/node-fetch": "^2.6.12",
+    "@types/swagger-ui-dist": "3.30.5",
     "argparse": "^2.0.1",
-    "body-parser": "^1.19.0",
-    "compression": "^1.7.4",
+    "compression": "^1.7.5",
     "cors": "^2.8.5",
-    "express": "^4.17.1",
+    "express": "^5.0.1",
     "h264-mp4-encoder": "^1.0.12",
-    "immer": "^9.0.7",
-    "immutable": "^3.8.2",
-    "node-fetch": "^2.6.2",
-    "rxjs": "^7.4.0",
-    "swagger-ui-dist": "^4.1.1",
-    "tslib": "^2.3.1",
-    "util.promisify": "^1.1.1",
+    "immer": "^10.1.1",
+    "immutable": "^5.0.3",
+    "io-ts": "^2.2.22",
+    "node-fetch": "^2.7.0",
+    "react-markdown": "^9.0.1",
+    "rxjs": "^7.8.1",
+    "swagger-ui-dist": "^5.18.2",
+    "tslib": "^2.8.1",
+    "util.promisify": "^1.1.2",
     "xhr2": "^0.2.1"
   },
   "peerDependencies": {
-    "react": "^17.0.2",
-    "react-dom": "^17.0.2"
+    "@google-cloud/storage": "^7.14.0",
+    "canvas": "^2.11.2",
+    "gl": "^6.0.2",
+    "jpeg-js": "^0.4.4",
+    "pngjs": "^6.0.0",
+    "react": ">=16.14.0",
+    "react-dom": ">=16.14.0"
   },
-  "optionalDependencies": {
-    "gl": "^4.9.2"
+  "peerDependenciesMeta": {
+    "@google-cloud/storage": {
+      "optional": true
+    },
+    "canvas": {
+      "optional": true
+    },
+    "gl": {
+      "optional": true
+    },
+    "jpeg-js": {
+      "optional": true
+    },
+    "pngjs": {
+      "optional": true
+    }
   }
 }

scripts/deploy.js

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2019-2021 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>
  */
@@ -15,7 +15,7 @@ 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 -->`;
+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) {
@@ -39,6 +39,14 @@ function copyViewer() {
     addAnalytics(path.resolve(viewerDeployPath, 'index.html'));
 }
 
+function copyMe() {
+    console.log('\n###', 'copy me files');
+    const meBuildPath = path.resolve(buildDir, '../build/mesoscale-explorer/');
+    const meDeployPath = path.resolve(localPath, 'me/viewer/');
+    fse.copySync(meBuildPath, meDeployPath, { overwrite: true });
+    addAnalytics(path.resolve(meDeployPath, 'index.html'));
+}
+
 function copyDemos() {
     console.log('\n###', 'copy demos files');
     const lightingBuildPath = path.resolve(buildDir, '../build/examples/lighting/');
@@ -53,8 +61,13 @@ function copyDemos() {
 }
 
 function copyFiles() {
-    copyViewer();
-    copyDemos();
+    try {
+        copyViewer();
+        copyMe();
+        copyDemos();
+    } catch (e) {
+        console.error(e);
+    }
 }
 
 if (!fs.existsSync(localPath)) {

src/apps/docking-viewer/index.ts

@@ -9,6 +9,7 @@ import { Structure } from '../../mol-model/structure';
 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';
@@ -58,20 +59,22 @@ class Viewer {
     }
 
     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,
+        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,
-        } };
+                viewportShowExpand: true,
+                viewportShowControls: false,
+                viewportShowSettings: false,
+                viewportShowSelectionMode: false,
+                viewportShowAnimation: false,
+            }
+        };
         const defaultSpec = DefaultPluginUISpec();
 
         const spec: PluginUISpec = {
@@ -126,7 +129,7 @@ class Viewer {
             ? document.getElementById(elementOrId)
             : elementOrId;
         if (!element) throw new Error(`Could not get element with id '${elementOrId}'`);
-        const plugin = await createPluginUI(element, spec);
+        const plugin = await createPluginUI({ target: element, spec, render: renderReact18 });
 
         (plugin.customState as any) = {
             colorPalette: {
@@ -135,18 +138,16 @@ class Viewer {
             }
         };
 
-        plugin.behaviors.canvas3d.initialized.subscribe(v => {
-            if (v) {
-                PluginCommands.Canvas3D.SetSettings(plugin, { settings: {
-                    renderer: {
-                        ...plugin.canvas3d!.props.renderer,
-                        backgroundColor: ColorNames.white,
-                    },
-                    camera: {
-                        ...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: {} } }
+                }
             }
         });
 
@@ -166,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');

src/apps/docking-viewer/viewport.tsx

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2020 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2020-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
  */
@@ -31,7 +31,8 @@ function shinyStyle(plugin: PluginContext) {
         postprocessing: {
             ...plugin.canvas3d!.props.postprocessing,
             occlusion: { name: 'off', params: {} },
-            outline: { name: 'off', params: {} }
+            shadow: { name: 'off', params: {} },
+            outline: { name: 'off', params: {} },
         }
     } });
 }
@@ -43,17 +44,13 @@ function occlusionStyle(plugin: PluginContext) {
         },
         postprocessing: {
             ...plugin.canvas3d!.props.postprocessing,
-            occlusion: { name: 'on', params: {
-                samples: 64,
-                radius: 8,
-                bias: 1.0,
-                blurKernelSize: 13
-            } },
             outline: { name: 'on', params: {
                 scale: 1.0,
                 threshold: 0.33,
                 color: Color(0x0000),
-            } }
+                includeTransparent: true,
+            } },
+            shadow: { name: 'off', params: {} },
         }
     } });
 }
@@ -201,14 +198,14 @@ 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, 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 }, color: InteractionTypeColorThemeProvider }, { tag: 'interactions' }),
+            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' }),
         };
 

src/apps/mesoscale-explorer/app.ts

@@ -0,0 +1,297 @@
+/**
+ * Copyright (c) 2022-2024 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';
+import { MesoViewportSnapshotDescription } from './ui/entities';
+
+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,
+    illumination: boolean,
+    stateRef?: string,
+    driver?: any,
+    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,
+    resolutionMode: PluginConfig.General.ResolutionMode.defaultValue,
+    illumination: false,
+
+    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,
+    driver: undefined
+};
+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',
+                viewport: {
+                    snapshotDescription: MesoViewportSnapshotDescription,
+                }
+            },
+            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.General.ResolutionMode, o.resolutionMode],
+                [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();
+                    // extend the array with file tour.json if it exists
+                    const tour = await plugin.fetch({ url: '../examples/tour.json', type: 'json' }).run();
+                    if (tour) {
+                        examples = examples?.concat(tour);
+                    }
+                } catch (e) {
+                    console.log(e);
+                }
+
+                (plugin.customState as MesoscaleExplorerState) = {
+                    examples,
+                    graphicsMode: o.graphicsMode,
+                    illumination: o.illumination,
+                    driver: o.driver,
+                    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,98 @@
+/**
+ * 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';
+import { StructureElement } from '../../../mol-model/structure';
+
+const B = ButtonsType;
+const M = ModifiersKeys;
+const Trigger = Binding.Trigger;
+const Key = Binding.TriggerKey;
+
+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}'),
+    keyCenterOnly: Binding([Key('C')], 'Center Only Toggle', 'Press ${triggers}'),
+};
+
+export const MesoFocusLociParams = {
+    minRadius: PD.Numeric(8, { min: 1, max: 50, step: 1 }),
+    extraRadius: PD.Numeric(4, { min: 1, max: 50, step: 1 }, { description: 'Value added to the bounding-sphere radius of the Loci' }),
+    durationMs: PD.Numeric(250, { min: 0, max: 1000, step: 1 }, { description: 'Camera transition duration' }),
+    centerOnly: PD.Boolean(true, { description: 'Keep current camera distance' }),
+    bindings: PD.Value(DefaultMesoFocusLociBindings, { isHidden: true }),
+};
+type MesoFocusLociProps = PD.Values<typeof MesoFocusLociParams>
+
+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, centerOnly } = this.params;
+                const radius = Math.max(sphere.radius + extraRadius, minRadius);
+
+                if (Binding.match(clickCenter, button, modifiers)) {
+                    // left mouse button
+                    if (Loci.isEmpty(current.loci)) {
+                        PluginCommands.Camera.Reset(this.ctx, { });
+                        return;
+                    }
+                    if (StructureElement.Loci.is(current.loci)) {
+                        if (centerOnly) {
+                            const snapshot = canvas3d.camera.getCenter(sphere.center);
+                            canvas3d.requestCameraReset({ durationMs, snapshot });
+                        } else {
+                            this.ctx.managers.camera.focusSphere(sphere, this.params);
+                        }
+                    }
+                } else if (Binding.match(clickCenterFocus, button, modifiers)) {
+                    // right mouse button
+                    if (Loci.isEmpty(current.loci)) {
+                        PluginCommands.Camera.Reset(this.ctx, { });
+                        return;
+                    }
+                    if (centerOnly) {
+                        const snapshot = canvas3d.camera.getCenter(sphere.center, radius);
+                        canvas3d.requestCameraReset({ durationMs, snapshot });
+                    } else {
+                        this.ctx.managers.camera.focusSphere(sphere, this.params);
+                    }
+                }
+            });
+
+            this.subscribeObservable(this.ctx.behaviors.interaction.key, ({ code, key, modifiers }) => {
+                if (!this.ctx.canvas3d) return;
+                const b = { ...DefaultMesoFocusLociBindings, ...this.params.bindings };
+                const { centerOnly } = this.params;
+
+                if (Binding.matchKey(b.keyCenterOnly, code, modifiers, key)) {
+                    this.params.centerOnly = !centerOnly;
+                }
+            });
+        }
+    },
+    params: () => MesoFocusLociParams,
+    display: { name: 'Camera Meso Focus Loci on Canvas' }
+});

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

@@ -0,0 +1,208 @@
+/**
+ * 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';
+import { MesoscaleState, expandAllGroups, getCellDescription, getEveryEntity } from '../data/state';
+
+const B = ButtonsType;
+const M = ModifiersKeys;
+const Trigger = Binding.Trigger;
+
+const DefaultMesoSelectLociBindings = {
+    click: Binding([
+        Trigger(B.Flag.Primary, M.create())
+    ], 'Click', 'Click element using ${triggers}'),
+    clickToggleSelect: Binding([
+        Trigger(B.Flag.Primary, M.create({ shift: true })),
+        Trigger(B.Flag.Primary, M.create({ control: true })),
+    ], '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 { click, clickToggleSelect } = this.params.bindings;
+                if (Binding.match(clickToggleSelect, button, modifiers)) {
+                    if (Loci.isEmpty(current.loci)) {
+                        this.ctx.managers.interactivity.lociSelects.deselectAll();
+                        return;
+                    }
+                    const loci = Loci.normalize(current.loci, modifiers.control ? 'entity' : 'chain');
+                    this.ctx.managers.interactivity.lociSelects.toggle({ loci }, false);
+                    if (StructureElement.Loci.is(current.loci)) {
+                        const cell = this.ctx.helpers.substructureParent.get(current.loci.structure);
+                        const d = getCellDescription(cell!);
+                        MesoscaleState.set(this.ctx, { focusInfo: `${d}` });
+                    }
+                }
+                if (Binding.match(click, button, modifiers)) {
+                    if (Loci.isEmpty(current.loci)) {
+                        MesoscaleState.set(this.ctx, { focusInfo: '', filter: '' });
+                        return;
+                    }
+                    const snapshotKey = current.repr?.props?.snapshotKey?.trim() ?? '';
+                    if (snapshotKey) {
+                        this.ctx.managers.snapshot.applyKey(snapshotKey);
+                    } else {
+                        if (StructureElement.Loci.is(current.loci)) {
+                            const cell = this.ctx.helpers.substructureParent.get(current.loci.structure);
+                            const d = getCellDescription(cell!);
+                            MesoscaleState.set(this.ctx, { focusInfo: `${d}`, filter: `${cell?.obj?.label}` });
+                            expandAllGroups(this.ctx);
+                        }
+                    }
+                }
+            });
+            this.ctx.managers.interactivity.lociSelects.addProvider(this.lociMarkProvider);
+
+            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 (StructureElement.Loci.is(current.loci)) {
+                        if (modifiers.control) {
+                            this.ctx.managers.interactivity.lociHighlights.highlightOnly({ repr: current.repr, loci: EveryLoci }, false);
+                        } else {
+                            const loci = Loci.normalize(current.loci, 'chain');
+                            this.ctx.managers.interactivity.lociHighlights.highlightOnly({ repr: current.repr, loci }, false);
+                        }
+                    }
+                }
+
+                if (Loci.isEmpty(current.loci)) {
+                    this.ctx.behaviors.labels.highlight.next({ labels: [] });
+                    this.ctx.canvas3d?.mark({ loci: EveryLoci }, MarkerAction.RemoveHighlight);
+                } else {
+                    const labels: string[] = [];
+                    if (StructureElement.Loci.is(current.loci)) {
+                        const cell = this.ctx.helpers.substructureParent.get(current.loci.structure);
+                        const d = getCellDescription(cell!);
+                        labels.push(d);
+                    } else {
+                        const loci = Loci.normalize(current.loci, this.ctx.managers.interactivity.props.granularity);
+                        if (loci.kind === 'group-loci') {
+                            if ('shape' in current.loci && current.loci.shape.geometry.kind === 'text') {
+                                const qname = current.repr?.props.customText;
+                                // highlight protein with same name
+                                const entities = getEveryEntity(this.ctx, qname);
+                                for (const r of entities) {
+                                    const repr = r.obj?.data.repr;
+                                    if (repr) {
+                                        this.ctx.canvas3d?.mark({ repr, loci: EveryLoci }, MarkerAction.Highlight);
+                                    }
+                                }
+                            }
+                            labels.push(loci.shape.getLabel(0, 0));
+                        }
+                    }
+                    this.ctx.behaviors.labels.highlight.next({ labels });
+                }
+            });
+            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,175 @@
+/**
+ * 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) || [];
+
+            const structure = Structure.create(units);
+            const description_label = entities.data.pdbx_description.value(idx)[0] || 'model';
+            const label = description_label.split('.').at(-1) || a.label;
+            const description = entities.data.pdbx_parent_entity_id.value(idx) || label;
+            return new PSO.Molecule.Structure(structure, { label, description: description }); // `${a.description}`
+        });
+    },
+    dispose({ b }) {
+        b?.data.customPropertyDescriptors.dispose();
+    }
+});

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

@@ -0,0 +1,227 @@
+/**
+ * Copyright (c) 2019-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ *
+ * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ * @author Ludovic Autin <ludovic.autin@gmail.com>
+ */
+
+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()
+        .apply(MesoscaleGroup, { ...groupParams, root: true, index: -1, tag: 'comp:', label: 'compartment', color: { type: 'custom', illustrative: false, value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: 'group:comp:', state: { isCollapsed: false, isHidden: groupParams.hidden } })
+        .commit();
+
+    const funcRoot = await state.build()
+        .toRoot()
+        .apply(MesoscaleGroup, { ...groupParams, root: true, index: -1, tag: 'func:', label: 'function', color: { type: 'custom', illustrative: false, value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: 'group:func:', state: { isCollapsed: false, isHidden: groupParams.hidden } })
+        .commit();
+
+    if (entities._rowCount > 1) {
+        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)
+                        .apply(MesoscaleGroup, { ...groupParams, root: parent === compRoot, index: colorIdx, tag: `comp:${n}`, label, color: { type: 'generate', illustrative: false, value: color, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: [`group:comp:${n}`, `comp:${p}`], state: { isCollapsed: true, isHidden: groupParams.hidden } })
+                        .commit({ revertOnError: true });
+                    compGroups.set(n, group);
+                }
+            }
+
+            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)
+                    .apply(MesoscaleGroup, { ...groupParams, index: colorIdx, tag: `func:${f}`, label: f, color: { type: 'custom', illustrative: false, value: color, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: [`group:func:${f}`, 'func:'], state: { isCollapsed: true, isHidden: groupParams.hidden } })
+                    .commit({ revertOnError: true });
+                funcGroups.set(f, group);
+            }
+        }
+
+        //
+
+        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,140 @@
+/**
+ * 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('')),
+        description: 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: params.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,578 @@
+/**
+ * Copyright (c) 2023-2024 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 } 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, description: g.description, color: { type: 'custom', illustrative: false, value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: [`group:${g.root}:${g.id}`, g.root === parent ? `${g.root}:` : `${g.root}:${parent}`], state: { isCollapsed: true, isHidden: groupParams.hidden } })
+            .commit();
+
+        if (g.children) {
+            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, description: r.description, color: { type: 'custom', illustrative: false, value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: `group:${r.id}:`, state: { isCollapsed: false, isHidden: groupParams.hidden } })
+            .commit();
+
+        if (r.children) {
+            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 sizeFactor = ent.sizeFactor || 1;
+                const tags = ent.groups.map(({ id, root }) => `${root}:${id}`);
+                const instances = ent.instances && getAssetInstances(ent.instances);
+                const description = ent.description;
+                const label = ent.label || ent.file.split('.')[0];
+                build = build
+                    .toRoot()
+                    .apply(ReadFile, { file, label, isBinary });
+
+                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, description })
+                        .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();
+        } 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,203 @@
+/**
+ * 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);
+            }
+            // could also use _struct_ref.pdbx_db_accession to point to uniprot with _struct_ref.db_name == UNP
+            const label = entities.data.pdbx_description.value(idx).join(', ') || 'model';
+            const description = `*Entity id* ${entities.data.id.value(idx)} *src_method* ${entities.data.src_method.value(idx)} *type* ${entities.data.type.value(idx)}`;
+            return new PSO.Molecule.Structure(structure, { label, description: description });
+        });
+    },
+    update({ newParams, oldParams }) {
+        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-2024 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()
+        .apply(MesoscaleGroup, { ...groupParams, root: true, index: -1, tag: 'ent:', label: 'entity', color: { type: 'custom', illustrative: false, value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: 'group:ent:', state: { isCollapsed: false, isHidden: groupParams.hidden } })
+        .commit();
+
+    const getEntityType = (i: number) => {
+        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', illustrative: false, value: color, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: `ent:`, state: { isCollapsed: true, isHidden: groupParams.hidden } })
+                .commit({ revertOnError: true });
+            entGroups.set(t, group);
+        }
+    }
+
+    //
+
+    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,140 @@
+/**
+ * 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 pdbx_description = frame.categories.pdbx_model.getField('description')!;
+            const description = pdbx_description ? pdbx_description.str(params.modelIndex) : Structure.elementDescription(s);
+            const label = pdbx_model.str(params.modelIndex);
+            const props = { label, description: description };
+            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-2024 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()
+        .apply(MesoscaleGroup, { ...groupParams, root: true, index: -1, tag: `ent:`, label: 'entity', color: { type: 'generate', illustrative: false, value: ColorNames.white, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: ['group:ent:'], state: { isCollapsed: false, isHidden: groupParams.hidden } })
+        .commit({ revertOnError: true });
+
+    await state.build()
+        .to(group)
+        .apply(MesoscaleGroup, { ...groupParams, index: undefined, tag: `ent:mem`, label: 'Membrane', color: { type: 'uniform', illustrative: false, value: ColorNames.lightgrey, variability: 20, shift: 0, lightness: 0, alpha: 1, emissive: 0 } }, { tags: ['group:ent:mem', 'ent:', '__no_group_color__'], state: { isCollapsed: true, isHidden: groupParams.hidden } })
+        .commit();
+
+    const colors = getDistinctBaseColors(other.length, 0);
+
+    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', '__no_group_color__'] });
+            }
+            for (let i = 0, il = other.length; i < il; ++i) {
+                build = build
+                    .to(cell)
+                    .apply(StructureFromPetworld, other[i])
+                    .apply(StructureRepresentation3D, getSpacefillParams(colors[i], graphicsMode), { tags: ['ent:'] });
+            }
+            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,689 @@
+/**
+ * Copyright (c) 2023-2024 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';
+import { Material } from '../../../mol-util/material';
+
+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'])),
+    illustrative: PD.Boolean(false, { description: 'Illustrative style', hideIf: p => p.type === 'custom' }),
+    value: PD.Color(Color(0xFFFFFF), { hideIf: p => p.type === 'custom' }),
+    variability: PD.Numeric(20, { min: 1, max: 180, step: 1 }, { hideIf: p => p.type !== 'generate' }),
+    shift: PD.Numeric(0, { min: 0, max: 100, step: 1 }, { hideIf: p => !p.type.includes('generate') }),
+    lightness: PD.Numeric(0, { min: -6, max: 6, step: 0.1 }, { hideIf: p => p.type === 'custom' }),
+    alpha: PD.Numeric(1, { min: 0, max: 1, step: 0.01 }, { hideIf: p => p.type === 'custom' }),
+    emissive: PD.Numeric(0, { min: 0, max: 1, step: 0.01 }, { hideIf: p => p.type === 'custom' }),
+};
+export type ColorProps = PD.Values<typeof ColorParams>
+
+export const ColorValueParam = PD.Color(Color(0xFFFFFF));
+
+export const RootParams = {
+    type: PD.Select('custom', PD.arrayToOptions(['group-generate', 'group-uniform', 'generate', 'uniform', 'custom'])),
+    illustrative: PD.Boolean(false, { description: 'Illustrative style', hideIf: p => p.type === 'custom' }),
+    value: PD.Color(Color(0xFFFFFF), { hideIf: p => p.type !== 'uniform' }),
+    variability: PD.Numeric(20, { min: 1, max: 180, step: 1 }, { hideIf: p => p.type !== 'group-generate' }),
+    shift: PD.Numeric(0, { min: 0, max: 100, step: 1 }, { hideIf: p => !p.type.includes('generate') }),
+    lightness: PD.Numeric(0, { min: -6, max: 6, step: 0.1 }, { hideIf: p => p.type === 'custom' }),
+    alpha: PD.Numeric(1, { min: 0, max: 1, step: 0.01 }, { hideIf: p => p.type === 'custom' }),
+    emissive: PD.Numeric(0, { min: 0, max: 1, step: 0.01 }, { hideIf: p => p.type === 'custom' }),
+};
+
+export const LightnessParams = {
+    lightness: PD.Numeric(0, { min: -6, max: 6, step: 0.1 }),
+};
+export const DimLightness = 6;
+
+export const IllustrativeParams = {
+    illustrative: PD.Boolean(false, { description: 'Illustrative style' }),
+};
+
+export const OpacityParams = {
+    alpha: PD.Numeric(1, { min: 0, max: 1, step: 0.01 }),
+};
+
+export const EmissiveParams = {
+    emissive: PD.Numeric(0, { min: 0, max: 1, step: 0.01 }),
+};
+
+export const celShaded = {
+    celShaded: PD.Boolean(false, { description: 'Cel Shading light for stylized rendering of representations' })
+};
+
+export type celShadedProps = PD.Values<typeof celShaded>;
+
+
+export const PatternParams = {
+    frequency: PD.Numeric(1, { min: 0, max: 1, step: 0.01 }),
+    amplitude: PD.Numeric(1, { min: 0, max: 1, step: 0.01 }),
+};
+
+export const StyleParams = {
+    ignoreLight: PD.Boolean(false, { description: 'Ignore light for stylized rendering of representations' }),
+    materialStyle: Material.getParam(),
+    celShaded: PD.Boolean(false, { description: 'Cel Shading light for stylized rendering of representations' }),
+};
+
+export const LodParams = {
+    lodLevels: Spheres.Params.lodLevels,
+    cellSize: Spheres.Params.cellSize,
+    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 }),
+    description: PD.Value<string>('', { isHidden: true }),
+    hidden: PD.Boolean(false),
+    color: PD.Group(RootParams),
+    lightness: PD.Numeric(0, { min: -6, max: 6, step: 0.1 }),
+    alpha: PD.Numeric(1, { min: 0, max: 1, step: 0.01 }),
+    emissive: PD.Numeric(0, { min: 0, max: 1, step: 0.01 }),
+    lod: PD.Group(LodParams),
+    clip: PD.Group(SimpleClipParams),
+};
+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, description: params.description });
+        });
+    },
+});
+
+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: 5000, overlap: 0, stride: 1, scaleBias: 1 },
+                { minDistance: 5000, maxDistance: 10000, overlap: 0, stride: 10, scaleBias: 3 },
+                { minDistance: 10000, maxDistance: 30000, overlap: 0, stride: 50, scaleBias: 2.5 },
+                { minDistance: 30000, maxDistance: 10000000, overlap: 0, stride: 200, scaleBias: 2 },
+            ];
+        default:
+            assertUnreachable(graphicsMode);
+    }
+}
+
+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 }),
+    focusInfo: PD.Value<string>('', { isHidden: true }),
+    link: PD.Value<string>('', { isHidden: true }),
+    textSizeDescription: PD.Numeric(14, { min: 1, max: 100, step: 1 }, { isHidden: true }),
+    index: PD.Value<number>(-1, { isHidden: true })
+};
+
+export class MesoscaleStateObject extends PSO.Create<MesoscaleState>({ name: 'Mesoscale State', typeClass: 'Object' }) { }
+
+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) {
+    if (!filter) return getEntities(plugin, tag);
+    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) {
+    if (!filter) return getAllEntities(plugin, tag);
+    const matcher = getFilterMatcher(filter);
+    return getAllEntities(plugin, tag).filter(c => getEntityLabel(plugin, c).match(matcher) !== null);
+}
+
+export function getEveryEntity(plugin: PluginContext, filter?: string, tag?: string) {
+    if (filter) {
+        const matcher = getFilterMatcher(filter);
+        return getAllEntities(plugin, tag).filter(c => getEntityLabel(plugin, c).match(matcher) !== null);
+    } else {
+        return getAllEntities(plugin, tag);
+    }
+}
+
+export function getEntityLabel(plugin: PluginContext, cell: StateObjectCell) {
+    return StateObjectRef.resolve(plugin.state.data, cell.transform.parent)?.obj?.label || 'Entity';
+}
+
+export function getCellDescription(cell: StateObjectCell) {
+    // markdown style for description
+    return '**' + cell?.obj?.label + '**\n\n' + cell?.obj?.description;
+}
+
+export function getEntityDescription(plugin: PluginContext, cell: StateObjectCell) {
+    const s = StateObjectRef.resolve(plugin.state.data, cell.transform.parent);
+    const d = getCellDescription(s!);
+    return d;
+}
+
+export async function updateStyle(plugin: PluginContext, options: { ignoreLight: boolean, material: Material, celShaded: boolean, illustrative: boolean }) {
+    const update = plugin.state.data.build();
+    const { ignoreLight, material, celShaded, illustrative } = options;
+
+    const entities = getAllEntities(plugin);
+
+    for (let j = 0; j < entities.length; ++j) {
+        update.to(entities[j]).update(old => {
+            if (old.type) {
+                const value = old.colorTheme.name === 'illustrative'
+                    ? old.colorTheme.params.style.params.value
+                    : old.colorTheme.params.value;
+                const lightness = old.colorTheme.name === 'illustrative'
+                    ? old.colorTheme.params.style.params.lightness
+                    : old.colorTheme.params.lightness;
+                if (illustrative) {
+                    old.colorTheme = { name: 'illustrative', params: { style: { name: 'uniform', params: { value, lightness } } } };
+                } else {
+                    old.colorTheme = { name: 'uniform', params: { value, lightness } };
+                }
+                old.type.params.ignoreLight = ignoreLight;
+                old.type.params.material = material;
+                old.type.params.celShaded = celShaded;
+            }
+        });
+    }
+
+    await update.commit();
+};
+
+export async function updateColors(plugin: PluginContext, values: PD.Values, tag: string, filter: string) {
+    const update = plugin.state.data.build();
+    const { type, illustrative, value, shift, lightness, alpha, emissive } = values;
+    if (type === 'group-generate' || type === 'group-uniform') {
+        const leafGroups = getAllLeafGroups(plugin, tag);
+        const rootLeafGroups = getRoots(plugin).filter(g => g.params?.values.tag === tag && getEntities(plugin, g.params?.values.tag).length > 0);
+        const groups = [...leafGroups, ...rootLeafGroups];
+        const baseColors = getDistinctBaseColors(groups.length, shift);
+
+        for (let i = 0; i < groups.length; ++i) {
+            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) {
+                        if (illustrative) {
+                            old.colorTheme = { name: 'illustrative', params: { style: { name: 'uniform', params: { value: c, lightness: lightness } } } };
+                        } else {
+                            old.colorTheme = { name: 'uniform', params: { value: c, lightness: lightness } };
+                        }
+                        old.type.params.alpha = alpha;
+                        old.type.params.xrayShaded = alpha < 1 ? 'inverted' : false;
+                        old.type.params.emissive = emissive;
+                    } else if (old.coloring) {
+                        old.coloring.params.color = c;
+                        old.coloring.params.lightness = lightness;
+                        old.alpha = alpha;
+                        old.xrayShaded = alpha < 1 ? true : false;
+                        old.emissive = emissive;
+                    }
+                });
+            }
+
+            update.to(g.transform.ref).update(old => {
+                old.color.type = type === 'group-generate' ? 'generate' : 'uniform';
+                old.color.illustrative = illustrative;
+                old.color.value = baseColors[i];
+                old.color.lightness = lightness;
+                old.color.alpha = alpha;
+                old.color.emissive = emissive;
+            });
+        }
+    } else if (type === 'generate' || type === 'uniform') {
+        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) {
+                    if (illustrative) {
+                        old.colorTheme = { name: 'illustrative', params: { style: { name: 'uniform', params: { value: c, lightness: lightness } } } };
+                    } else {
+                        old.colorTheme = { name: 'uniform', params: { value: c, lightness: lightness } };
+                    }
+                    old.type.params.alpha = alpha;
+                    old.type.params.xrayShaded = alpha < 1 ? 'inverted' : false;
+                    old.type.params.emissive = emissive;
+                } else if (old.coloring) {
+                    old.coloring.params.color = c;
+                    old.coloring.params.lightness = lightness;
+                    old.alpha = alpha;
+                    old.xrayShaded = alpha < 1 ? true : false;
+                    old.emissive = emissive;
+                }
+            });
+        }
+
+        const others = getAllLeafGroups(plugin, tag);
+        for (const o of others) {
+            update.to(o).update(old => {
+                old.color.type = type === 'generate' ? 'custom' : 'uniform';
+                old.color.illustrative = illustrative;
+                old.color.value = value;
+                old.color.lightness = lightness;
+                old.color.alpha = alpha;
+                old.color.emissive = emissive;
+            });
+        }
+    }
+
+    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/embedded.html

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

src/apps/mesoscale-explorer/index.html

@@ -0,0 +1,109 @@
+<!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">
+        <link rel="stylesheet" href="../extras/driver.css"/>
+        <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 src="../extras/driver.js.iife.js"></script>
+        <script type="text/javascript" src="./molstar.js"></script>
+        <script type="text/javascript">
+            const driver = window.driver ? window.driver.js.driver() : undefined;
+
+            function getParam(name, regex) {
+                var r = new RegExp(name + '=' + '(' + regex + ')[&]?', 'i');
+                return decodeURIComponent(((window.location.search || '').match(r) || [])[1] || '');
+            }
+
+            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();
+            var illumination = getParam('illumination', '[^&]+').trim() === '1';
+            var resolutionMode = getParam('resolution-mode', '[^&]+').trim().toLowerCase();
+
+            molstar.MesoscaleExplorer.create('app', {
+                layoutShowControls: !hideControls,
+                viewportShowExpand: false,
+                preferWebgl1: preferWebgl1,
+                allowMajorPerformanceCaveat: allowMajorPerformanceCaveat,
+                powerPreference: powerPreference || 'high-performance',
+                graphicsMode: graphicsMode || 'quality',
+                illumination: illumination,
+                resolutionMode: resolutionMode || 'auto',
+                driver: driver
+            }).then(me => {
+                var example = getParam('example', '[^&]+').trim();
+                if (example) {
+                    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,68 @@
+@use "sass:color";
+
+$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 color.adjust($color, $lightness: -$amount, $space: hsl);
+}
+
+@function color-increase-contrast($color, $amount) {
+    @return color.adjust($color, $lightness: $amount, $space: hsl);
+}
+
+@import 'mol-plugin-ui/skin/base/base';
+@import 'mol-plugin-ui/skin/base/variables';
+
+a {
+    color: $font-color;
+    &:hover {
+        color: $hover-font-color;
+    }
+}
+
+
+.msp-snapshot-description-me {
+    background: color.change($default-background, $alpha: 0.5, $space: rgb);
+
+    position: absolute;
+    height: 50vh; // 50% of the viewport height
+    left: 0;
+    top: $control-spacing + $row-height;
+    padding: (0.66 * $control-spacing) $control-spacing;
+
+    resize: both; /* Allows resizing in both directions */
+    overflow: auto; /* Adjust as needed */
+
+    a {
+        text-decoration: underline;
+        cursor: pointer;
+        color: $font-color;
+    }
+
+    ul, ol {
+        padding-left: $control-spacing + 4px;
+    }
+
+    &.hidden {
+        display: none;
+    }
+
+    &.shown {
+        display: block; // or 'flex', 'grid', etc. depending on your layout
+    }
+}

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

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

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

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

src/apps/viewer/app.ts

@@ -1,70 +1,95 @@
 /**
- * Copyright (c) 2018-2022 mol* contributors, licensed under MIT, See LICENSE file for more info.
+ * Copyright (c) 2018-2024 mol* contributors, licensed under MIT, See LICENSE file for more info.
  *
  * @author David Sehnal <david.sehnal@gmail.com>
  * @author Alexander Rose <alexander.rose@weirdbyte.de>
+ * @author Neli Fonseca <neli@ebi.ac.uk>
+ * @author Adam Midlik <midlik@gmail.com>
  */
 
 import { ANVILMembraneOrientation } from '../../extensions/anvil/behavior';
-import { CellPack } from '../../extensions/cellpack';
-import { DnatcoConfalPyramids } from '../../extensions/dnatco';
+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 } from '../../extensions/model-archive/quality-assessment/behavior';
-import { QualityAssessmentPLDDTPreset, QualityAssessmentQmeanPreset } from '../../extensions/model-archive/quality-assessment/behavior';
+import { MAQualityAssessment, MAQualityAssessmentConfig, QualityAssessmentPLDDTPreset, QualityAssessmentQmeanPreset } from '../../extensions/model-archive/quality-assessment/behavior';
 import { QualityAssessment } from '../../extensions/model-archive/quality-assessment/prop';
+import { ModelExport } from '../../extensions/model-export';
 import { Mp4Export } from '../../extensions/mp4-export';
+import { MolViewSpec } from '../../extensions/mvs/behavior';
+import { loadMVSX } from '../../extensions/mvs/components/formats';
+import { loadMVS, MolstarLoadingExtension } from '../../extensions/mvs/load';
+import { MVSData } from '../../extensions/mvs/mvs-data';
 import { PDBeStructureQualityReport } from '../../extensions/pdbe';
-import { RCSBAssemblySymmetry, RCSBValidationReport } from '../../extensions/rcsb';
+import { RCSBValidationReport } from '../../extensions/rcsb';
+import { AssemblySymmetry, AssemblySymmetryConfig } from '../../extensions/assembly-symmetry';
+import { SbNcbrPartialCharges, SbNcbrPartialChargesPreset, SbNcbrPartialChargesPropertyProvider, SbNcbrTunnels } from '../../extensions/sb-ncbr';
+import { Volseg, VolsegVolumeServerConfig } from '../../extensions/volumes-and-segmentations';
+import { wwPDBChemicalComponentDictionary } from '../../extensions/wwpdb/ccd/behavior';
+import { wwPDBStructConnExtensionFunctions } from '../../extensions/wwpdb/struct-conn';
+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 { BuildInStructureFormat } from '../../mol-plugin-state/formats/structure';
+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 { createPluginUI } from '../../mol-plugin-ui';
 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 { PluginConfig, PluginConfigItem } from '../../mol-plugin/config';
 import { PluginLayoutControlsDisplay } from '../../mol-plugin/layout';
 import { PluginSpec } from '../../mol-plugin/spec';
 import { PluginState } from '../../mol-plugin/state';
 import { StateObjectRef, StateObjectSelector } from '../../mol-state';
+import { Task } from '../../mol-task';
 import { Asset } from '../../mol-util/assets';
 import { Color } from '../../mol-util/color';
 import '../../mol-util/polyfill';
 import { ObjectKeys } from '../../mol-util/type-helpers';
 
 export { PLUGIN_VERSION as version } from '../../mol-plugin/version';
-export { setDebugMode, setProductionMode } from '../../mol-util/debug';
+export { consoleStats, setDebugMode, setProductionMode, setTimingMode } from '../../mol-util/debug';
 
 const CustomFormats = [
     ['g3d', G3dProvider] as const
 ];
 
-const Extensions = {
-    'cellpack': PluginSpec.Behavior(CellPack),
-    'dnatco-confal-pyramids': PluginSpec.Behavior(DnatcoConfalPyramids),
+export const ExtensionMap = {
+    'volseg': PluginSpec.Behavior(Volseg),
+    'backgrounds': PluginSpec.Behavior(Backgrounds),
+    'dnatco-ntcs': PluginSpec.Behavior(DnatcoNtCs),
     'pdbe-structure-quality-report': PluginSpec.Behavior(PDBeStructureQualityReport),
-    'rcsb-assembly-symmetry': PluginSpec.Behavior(RCSBAssemblySymmetry),
+    '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),
+    'tunnels': PluginSpec.Behavior(SbNcbrTunnels),
 };
 
 const DefaultViewerOptions = {
     customFormats: CustomFormats as [string, DataFormatProvider][],
-    extensions: ObjectKeys(Extensions),
+    extensions: ObjectKeys(ExtensionMap),
+    disabledExtensions: [] as string[],
     layoutIsExpanded: true,
     layoutShowControls: true,
     layoutShowRemoteState: true,
@@ -77,20 +102,31 @@ const DefaultViewerOptions = {
     disableAntialiasing: PluginConfig.General.DisableAntialiasing.defaultValue,
     pixelScale: PluginConfig.General.PixelScale.defaultValue,
     pickScale: PluginConfig.General.PickScale.defaultValue,
-    pickPadding: PluginConfig.General.PickPadding.defaultValue,
-    enableWboit: PluginConfig.General.EnableWboit.defaultValue,
+    transparency: PluginConfig.General.Transparency.defaultValue,
     preferWebgl1: PluginConfig.General.PreferWebGl1.defaultValue,
+    allowMajorPerformanceCaveat: PluginConfig.General.AllowMajorPerformanceCaveat.defaultValue,
+    powerPreference: PluginConfig.General.PowerPreference.defaultValue,
+    resolutionMode: PluginConfig.General.ResolutionMode.defaultValue,
+    illumination: false,
 
     viewportShowExpand: PluginConfig.Viewport.ShowExpand.defaultValue,
     viewportShowControls: PluginConfig.Viewport.ShowControls.defaultValue,
     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,
+
+    config: [] as [PluginConfigItem, any][],
 };
 type ViewerOptions = typeof DefaultViewerOptions;
 
@@ -99,14 +135,23 @@ export class Viewer {
     }
 
     static async create(elementOrId: string | HTMLElement, options: Partial<ViewerOptions> = {}) {
-        const o = { ...DefaultViewerOptions, ...options };
+        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.map(e => Extensions[e]),
+                ...o.extensions.filter(e => !disabledExtension.has(e)).map(e => ExtensionMap[e]),
             ],
             animations: [...defaultSpec.animations || []],
             customParamEditors: defaultSpec.customParamEditors,
@@ -138,14 +183,17 @@ export class Viewer {
                 [PluginConfig.General.DisableAntialiasing, o.disableAntialiasing],
                 [PluginConfig.General.PixelScale, o.pixelScale],
                 [PluginConfig.General.PickScale, o.pickScale],
-                [PluginConfig.General.PickPadding, o.pickPadding],
-                [PluginConfig.General.EnableWboit, o.enableWboit],
+                [PluginConfig.General.Transparency, o.transparency],
                 [PluginConfig.General.PreferWebGl1, o.preferWebgl1],
+                [PluginConfig.General.AllowMajorPerformanceCaveat, o.allowMajorPerformanceCaveat],
+                [PluginConfig.General.PowerPreference, o.powerPreference],
+                [PluginConfig.General.ResolutionMode, o.resolutionMode],
                 [PluginConfig.Viewport.ShowExpand, o.viewportShowExpand],
                 [PluginConfig.Viewport.ShowControls, o.viewportShowControls],
                 [PluginConfig.Viewport.ShowSettings, o.viewportShowSettings],
                 [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],
@@ -153,6 +201,12 @@ export class Viewer {
                 [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],
+                ...(o.config ?? []),
             ]
         };
 
@@ -160,13 +214,17 @@ export class Viewer {
             ? document.getElementById(elementOrId)
             : elementOrId;
         if (!element) throw new Error(`Could not get element with id '${elementOrId}'`);
-        const plugin = await createPluginUI(element, spec, {
+        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);
             }
         });
+        plugin.canvas3d?.setProps({ illumination: { enabled: o.illumination } });
         return new Viewer(plugin);
     }
 
@@ -179,7 +237,7 @@ export class Viewer {
         return PluginCommands.State.Snapshots.OpenUrl(this.plugin, { url, type });
     }
 
-    loadStructureFromUrl(url: string, format: BuiltInTrajectoryFormat = 'mmcif', isBinary = false, options?: LoadStructureOptions) {
+    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: {
@@ -188,6 +246,7 @@ export class Viewer {
                     url: Asset.Url(url),
                     format: format as any,
                     isBinary,
+                    label: options?.label,
                     options: { ...params.source.params.options, representationParams: options?.representationParams as any },
                 }
             }
@@ -267,7 +326,10 @@ export class Viewer {
             source: {
                 name: 'alphafolddb' as const,
                 params: {
-                    id: afdb,
+                    provider: {
+                        id: afdb,
+                        encoding: 'bcif'
+                    },
                     options: {
                         ...params.source.params.options,
                         representation: 'preset-structure-representation-ma-quality-assessment-plddt'
@@ -357,11 +419,13 @@ export class Viewer {
 
             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(parsed.volumes?.[iso.volumeIndex ?? 0] ?? parsed.volume)
+                    .to(volume)
                     .apply(StateTransforms.Representation.VolumeRepresentation3D, createVolumeRepresentationParams(this.plugin, firstVolume.data!, {
                         type: 'isosurface',
-                        typeParams: { alpha: iso.alpha ?? 1, isoValue: iso.type === 'absolute' ? { kind: 'absolute', absoluteValue: iso.value } : { kind: 'relative', relativeValue: iso.value } },
+                        typeParams: { alpha: iso.alpha ?? 1, isoValue: Volume.adjustedIsoValue(volumeData, iso.value, iso.type) },
                         color: 'uniform',
                         colorParams: { value: iso.color }
                     }));
@@ -371,6 +435,34 @@ export class Viewer {
         });
     }
 
+    loadFullResolutionEMDBMap(emdbId: string, options: { isoValue: Volume.IsoValue, color?: Color }) {
+        const plugin = this.plugin;
+        const numericId = parseInt(emdbId.toUpperCase().replace('EMD-', ''));
+        const url = `https://ftp.ebi.ac.uk/pub/databases/emdb/structures/EMD-${numericId}/map/emd_${numericId}.map.gz`;
+
+        return plugin.dataTransaction(async () => {
+            const data = await plugin.build().toRoot()
+                .apply(StateTransforms.Data.Download, { url, isBinary: true, label: emdbId }, { state: { isGhost: true } })
+                .apply(StateTransforms.Data.DeflateData)
+                .commit();
+
+            const parsed = await plugin.dataFormats.get('ccp4')!.parse(plugin, data, { entryId: emdbId });
+            const firstVolume = (parsed.volume || parsed.volumes[0]) as StateObjectSelector<PluginStateObject.Volume.Data>;
+            if (!firstVolume?.isOk) throw new Error('Failed to parse any volume.');
+
+            const volume: StateObjectSelector<PluginStateObject.Volume.Data> = parsed.volumes?.[0] ?? parsed.volume;
+            await plugin.build()
+                .to(volume)
+                .apply(StateTransforms.Representation.VolumeRepresentation3D, createVolumeRepresentationParams(this.plugin, firstVolume.data!, {
+                    type: 'isosurface',
+                    typeParams: { alpha: 1, isoValue: options.isoValue },
+                    color: 'uniform',
+                    colorParams: { value: options.color ?? Color(0x33BB33) }
+                }))
+                .commit();
+        });
+    }
+
     /**
      * @example
      *  viewer.loadTrajectory({
@@ -382,7 +474,7 @@ export class Viewer {
     async loadTrajectory(params: LoadTrajectoryParams) {
         const plugin = this.plugin;
 
-        let model: StateObjectSelector, coords: StateObjectSelector;
+        let model: StateObjectSelector;
 
         if (params.model.kind === 'model-data' || params.model.kind === 'model-url') {
             const data = params.model.kind === 'model-data'
@@ -400,14 +492,12 @@ export class Viewer {
             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 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);
-            coords = await provider!.parse(plugin, data);
-        }
+        const provider = plugin.dataFormats.get(params.coordinates.format);
+        const coords = await provider!.parse(plugin, data);
 
         const trajectory = await plugin.build().toRoot()
             .apply(TrajectoryFromModelAndCoordinates, {
@@ -421,9 +511,55 @@ export class Viewer {
         return { model, coords, preset };
     }
 
+    async loadMvsFromUrl(url: string, format: 'mvsj' | 'mvsx', options?: { replaceExisting?: boolean, keepCamera?: boolean, extensions?: MolstarLoadingExtension<any>[] }) {
+        if (format === 'mvsj') {
+            const data = await this.plugin.runTask(this.plugin.fetch({ url, type: 'string' }));
+            const mvsData = MVSData.fromMVSJ(data);
+            await loadMVS(this.plugin, mvsData, { sanityChecks: true, sourceUrl: url, ...options });
+        } else if (format === 'mvsx') {
+            const data = await this.plugin.runTask(this.plugin.fetch({ url, type: 'binary' }));
+            await this.plugin.runTask(Task.create('Load MVSX file', async ctx => {
+                const parsed = await loadMVSX(this.plugin, ctx, data);
+                await loadMVS(this.plugin, parsed.mvsData, { sanityChecks: true, sourceUrl: parsed.sourceUrl, ...options });
+            }));
+        } else {
+            throw new Error(`Unknown MolViewSpec format: ${format}`);
+        }
+    }
+
+    /** Load MolViewSpec from `data`.
+     * If `format` is 'mvsj', `data` must be a string or a Uint8Array containing a UTF8-encoded string.
+     * If `format` is 'mvsx', `data` must be a Uint8Array or a string containing base64-encoded binary data prefixed with 'base64,'. */
+    async loadMvsData(data: string | Uint8Array, format: 'mvsj' | 'mvsx', options?: { replaceExisting?: boolean, keepCamera?: boolean, extensions?: MolstarLoadingExtension<any>[] }) {
+        if (typeof data === 'string' && data.startsWith('base64')) {
+            data = Uint8Array.from(atob(data.substring(7)), c => c.charCodeAt(0)); // Decode base64 string to Uint8Array
+        }
+        if (format === 'mvsj') {
+            if (typeof data !== 'string') {
+                data = new TextDecoder().decode(data); // Decode Uint8Array to string using UTF8
+            }
+            const mvsData = MVSData.fromMVSJ(data);
+            await loadMVS(this.plugin, mvsData, { sanityChecks: true, sourceUrl: undefined, ...options });
+        } else if (format === 'mvsx') {
+            if (typeof data === 'string') {
+                throw new Error("loadMvsData: if `format` is 'mvsx', then `data` must be a Uint8Array or a base64-encoded string prefixed with 'base64,'.");
+            }
+            await this.plugin.runTask(Task.create('Load MVSX file', async ctx => {
+                const parsed = await loadMVSX(this.plugin, ctx, data as Uint8Array);
+                await loadMVS(this.plugin, parsed.mvsData, { sanityChecks: true, sourceUrl: parsed.sourceUrl, ...options });
+            }));
+        } else {
+            throw new Error(`Unknown MolViewSpec format: ${format}`);
+        }
+    }
+
     handleResize() {
         this.plugin.layout.events.updated.next(void 0);
     }
+
+    dispose() {
+        this.plugin.dispose();
+    }
 }
 
 export interface LoadStructureOptions {
@@ -441,11 +577,11 @@ export interface VolumeIsovalueInfo {
 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: BuildInStructureFormat, isBinary?: boolean }
-    | { kind: 'topology-data', data: string | number[] | ArrayBuffer | Uint8Array, format: BuildInStructureFormat },
+    | { 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: BuildInStructureFormat, isBinary?: boolean }
-    | { kind: 'coordinates-data', data: string | number[] | ArrayBuffer | Uint8Array, format: BuildInStructureFormat },
+    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
 }
@@ -472,8 +608,20 @@ export const ViewerAutoPreset = StructureRepresentationPresetProvider({
             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 },
+    modelArchive: {
+        qualityAssessment: {
+            config: MAQualityAssessmentConfig
+        }
+    }
+};

src/apps/viewer/embedded.html

@@ -38,6 +38,15 @@
                 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'
+                // });
             });
         </script>
     </body>

src/apps/viewer/index.html

@@ -46,7 +46,10 @@
             }
 
             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 hideControls = getParam('hide-controls', '[^&]+').trim() === '1';
             var collapseLeftPanel = getParam('collapse-left-panel', '[^&]+').trim() === '1';
@@ -56,10 +59,17 @@
             var pixelScale = getParam('pixel-scale', '[^&]+').trim();
             var pickScale = getParam('pick-scale', '[^&]+').trim();
             var pickPadding = getParam('pick-padding', '[^&]+').trim();
-            var disableWboit = getParam('disable-wboit', '[^&]+').trim() === '1';
-            var preferWebgl1 = getParam('prefer-webgl1', '[^&]+').trim() === '1';
+            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();
+            var illumination = getParam('illumination', '[^&]+').trim() === '1';
+            var resolutionMode = getParam('resolution-mode', '[^&]+').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,
@@ -71,8 +81,12 @@
                 pixelScale: parseFloat(pixelScale) || 1,
                 pickScale: parseFloat(pickScale) || 0.25,
                 pickPadding: isNaN(parseFloat(pickPadding)) ? 1 : parseFloat(pickPadding),
-                enableWboit: !disableWboit,
+                transparency: transparency || undefined,
                 preferWebgl1: preferWebgl1,
+                allowMajorPerformanceCaveat: allowMajorPerformanceCaveat,
+                powerPreference: powerPreference || 'high-performance',
+                illumination: illumination,
+                resolutionMode: resolutionMode || 'auto'
             }).then(viewer => {
                 var snapshotId = getParam('snapshot-id', '[^&]+').trim();
                 if (snapshotId) viewer.setRemoteSnapshot(snapshotId);
@@ -86,6 +100,14 @@
                 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);
 
@@ -100,6 +122,11 @@
 
                 var modelArchive = getParam('model-archive', '[^&]+').trim();
                 if (modelArchive) viewer.loadModelArchive(modelArchive);
+
+                window.addEventListener('unload', () => {
+                    // to aid GC
+                    viewer.dispose();
+                });
             });
         </script>
         <!-- __MOLSTAR_ANALYTICS__ -->

src/apps/viewer/index.ts

@@ -9,4 +9,4 @@ import './embedded.html';
 import './favicon.ico';
 import './index.html';
 require('mol-plugin-ui/skin/light.scss');
-export * from './app';
+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,7 +15,7 @@ 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[] = [];
@@ -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))) {
@@ -64,10 +65,15 @@ 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, 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']>
@@ -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();
 
@@ -283,12 +283,22 @@ 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.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);
 }
 
@@ -38,13 +38,13 @@ function run(args: Args) {
 
 const parser = new argparse.ArgumentParser({
     add_help: true,
-    description: 'Convert any CIF file to a BCIF file'
+    description: 'Convert any BCIF file to a CIF file or vice versa'
 });
 parser.add_argument('src', {
-    help: 'Source CIF path'
+    help: 'Source file path'
 });
 parser.add_argument('out', {
-    help: 'Output BCIF path'
+    help: 'Output file path'
 });
 parser.add_argument('-c', '--config', {
     help: 'Optional encoding strategy/precision config path',

src/cli/cifschema/index.ts

@@ -158,10 +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 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/MA-dictionary/master/mmcif_ma.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';

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':
@@ -38,6 +41,7 @@ export function getFieldType(type: string, description: string, values?: string[
         case 'pdbx_related_db_id':
         case 'sequence_dep':
         case 'pdb_id':
+        case 'pdb_id_u': // should be case insensitve, but can't express that
         case 'emd_id':
         // todo, consider adding specialised fields
         case 'yyyy-mm-dd':
@@ -49,6 +53,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':
@@ -58,6 +63,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':
@@ -68,6 +74,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);
@@ -85,6 +92,7 @@ export function getFieldType(type: string, description: string, values?: string[
         case 'Tag':
         case 'Implied':
         case 'Word':
+        case 'Uri':
             return wrapContainer('str', ',', description, container);
         case 'Real':
             return wrapContainer('float', ',', description, container);
@@ -148,7 +156,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) {
@@ -226,13 +234,19 @@ const FORCE_INT_FIELDS = [
     '_atom_site.id',
     '_atom_site.auth_seq_id',
     '_atom_site_anisotrop.id',
+    '_atom_site_anisotrop.pdbx_auth_seq_id',
     '_pdbx_struct_mod_residue.auth_seq_id',
+    '_pdbx_unobs_or_zero_occ_residues.auth_seq_id',
     '_struct_conf.beg_auth_seq_id',
     '_struct_conf.end_auth_seq_id',
     '_struct_conn.ptnr1_auth_seq_id',
     '_struct_conn.ptnr2_auth_seq_id',
     '_struct_sheet_range.beg_auth_seq_id',
     '_struct_sheet_range.end_auth_seq_id',
+    '_struct_site.pdbx_auth_seq_id',
+    '_struct_site_gen.auth_seq_id',
+    '_struct_mon_prot_cis.auth_seq_id',
+    '_struct_mon_prot_cis.pdbx_auth_seq_id_2',
 ];
 
 /**

src/cli/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>
  */
@@ -10,7 +10,7 @@ import { FieldPath } from '../../../mol-io/reader/cif/schema';
 
 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}
  *
@@ -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;

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 };
 }
 

src/cli/lipid-params/index.ts

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

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

@@ -0,0 +1,40 @@
+#!/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 { 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));
+    } else {
+        console.log(treeSchemaToString(MVSTreeSchema));
+    }
+}
+
+main(parseArguments());

src/cli/mvs/mvs-render.ts

@@ -0,0 +1,171 @@
+#!/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
+ * From Molstar NPM package:
+ *     npm install molstar canvas gl jpeg-js pngjs
+ *     npx mvs-render -i examples/mvs/1cbs.mvsj -o ../outputs/1cbs.png --size 800x600 --molj
+ * From Molstar source code:
+ *     npm install
+ *     npm install --no-save canvas gl jpeg-js pngjs  // these packages are not listed in Mol* dependencies for performance reasons
+ *     npm run build
+ *     node lib/commonjs/cli/mvs/mvs-render -i examples/mvs/1cbs.mvsj -o ../outputs/1cbs.png --size 800x600 --molj
+ */
+
+import { ArgumentParser } from 'argparse';
+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 { 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';
+
+
+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,
+    no_extensions: boolean,
+}
+
+/** Return parsed command line arguments for `main` */
+function parseArguments(): Args {
+    const parser = new ArgumentParser({ description: 'Command-line application for rendering images from MolViewSpec files' });
+    parser.add_argument('-i', '--input', { required: true, nargs: '+', help: 'Input file(s) in .mvsj or .mvsx format. File format is inferred from the file extension.' });
+    parser.add_argument('-o', '--output', { required: true, nargs: '+', help: 'File path(s) for output files (one output path for each input file). Output format is inferred from the file extension (.png or .jpg)' });
+    parser.add_argument('-s', '--size', { help: `Output image resolution, {width}x{height}. Default: ${DEFAULT_SIZE}.`, default: DEFAULT_SIZE });
+    parser.add_argument('-m', '--molj', { action: 'store_true', help: `Save Mol* state (.molj) in addition to rendered images (use the same output file paths but with .molj extension)` });
+    parser.add_argument('-n', '--no-extensions', { action: 'store_true', help: `Do not apply builtin MVS-loading extensions (not a part of standard MVS specification)` });
+    const args = parser.parse_args();
+    try {
+        const parts = args.size.split('x');
+        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, extensions: args.no_extensions ? [] : undefined });
+
+        fs.mkdirSync(path.dirname(output), { recursive: true });
+        if (args.molj) {
+            await plugin.saveStateSnapshot(withExtension(output, '.molj'));
+        }
+        if (output.toLowerCase().endsWith('.mp4')) {
+            await plugin.saveAnimation(output);
+        } else {
+            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));
+    spec.behaviors.push(PluginSpec.Behavior(Mp4Export));
+    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());