Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: molstar/mol-view-spec
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: v0.1.3
Choose a base ref
...
head repository: molstar/mol-view-spec
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: master
Choose a head ref
Loading
Showing with 4,097 additions and 29,566 deletions.
  1. +9 −0 .github/pull_request_template.md
  2. +41 −0 CHANGELOG.md
  3. +255 −7 README.md
  4. +0 −566 docs/MVS-tree-documentation.md
  5. +0 −2 frontend/.eslintignore
  6. +0 −125 frontend/.eslintrc.json
  7. +0 −23 frontend/.gitignore
  8. +0 −46 frontend/README.md
  9. +0 −18 frontend/jest.config.json
  10. +0 −22,805 frontend/package-lock.json
  11. +0 −54 frontend/package.json
  12. BIN frontend/public/favicon.ico
  13. +0 −43 frontend/public/index.html
  14. BIN frontend/public/logo192.png
  15. BIN frontend/public/logo512.png
  16. +0 −25 frontend/public/manifest.json
  17. +0 −3 frontend/public/robots.txt
  18. +0 −38 frontend/src/App.css
  19. +0 −10 frontend/src/App.test.tsx
  20. +0 −135 frontend/src/App.tsx
  21. +0 −100 frontend/src/app-model/app-model.ts
  22. +0 −81 frontend/src/app-model/mvs-extension/additions/annotation-color-theme.ts
  23. +0 −50 frontend/src/app-model/mvs-extension/additions/annotation-label/representation.ts
  24. +0 −117 frontend/src/app-model/mvs-extension/additions/annotation-label/visual.ts
  25. +0 −381 frontend/src/app-model/mvs-extension/additions/annotation-prop.ts
  26. +0 −111 frontend/src/app-model/mvs-extension/additions/annotation-structure-component.ts
  27. +0 −69 frontend/src/app-model/mvs-extension/additions/annotation-tooltips-prop.ts
  28. +0 −50 frontend/src/app-model/mvs-extension/additions/custom-label/representation.ts
  29. +0 −109 frontend/src/app-model/mvs-extension/additions/custom-label/visual.ts
  30. +0 −79 frontend/src/app-model/mvs-extension/additions/custom-tooltips-prop.ts
  31. +0 −164 frontend/src/app-model/mvs-extension/additions/multilayer-color-theme.ts
  32. +0 −81 frontend/src/app-model/mvs-extension/additions/selector.ts
  33. +0 −114 frontend/src/app-model/mvs-extension/behavior.ts
  34. +0 −119 frontend/src/app-model/mvs-extension/camera.ts
  35. +0 −50 frontend/src/app-model/mvs-extension/helpers/_spec/atom-ranges.spec.ts
  36. +0 −54 frontend/src/app-model/mvs-extension/helpers/_spec/utils.spec.ts
  37. +0 −138 frontend/src/app-model/mvs-extension/helpers/atom-ranges.ts
  38. +0 −131 frontend/src/app-model/mvs-extension/helpers/indexing.ts
  39. +0 −88 frontend/src/app-model/mvs-extension/helpers/label-text.ts
  40. +0 −35 frontend/src/app-model/mvs-extension/helpers/param-definition.ts
  41. +0 −92 frontend/src/app-model/mvs-extension/helpers/schemas.ts
  42. +0 −320 frontend/src/app-model/mvs-extension/helpers/selections.ts
  43. +0 −307 frontend/src/app-model/mvs-extension/helpers/utils.ts
  44. +0 −344 frontend/src/app-model/mvs-extension/load-helpers.ts
  45. +0 −214 frontend/src/app-model/mvs-extension/load.ts
  46. +0 −63 frontend/src/app-model/mvs-extension/mvs-data.ts
  47. +0 −107 frontend/src/app-model/mvs-extension/tree/generic/_spec/params-schema.spec.ts
  48. +0 −134 frontend/src/app-model/mvs-extension/tree/generic/params-schema.ts
  49. +0 −188 frontend/src/app-model/mvs-extension/tree/generic/tree-schema.ts
  50. +0 −131 frontend/src/app-model/mvs-extension/tree/generic/tree-utils.ts
  51. +0 −60 frontend/src/app-model/mvs-extension/tree/molstar/conversion.ts
  52. +0 −64 frontend/src/app-model/mvs-extension/tree/molstar/molstar-tree.ts
  53. +0 −249 frontend/src/app-model/mvs-extension/tree/mvs/mvs-builder.ts
  54. +0 −105 frontend/src/app-model/mvs-extension/tree/mvs/mvs-defaults.ts
  55. +0 −272 frontend/src/app-model/mvs-extension/tree/mvs/mvs-tree.ts
  56. +0 −73 frontend/src/app-model/mvs-extension/tree/mvs/param-types.ts
  57. +0 −13 frontend/src/index.css
  58. +0 −19 frontend/src/index.tsx
  59. +0 −1 frontend/src/logo.svg
  60. +0 −1 frontend/src/react-app-env.d.ts
  61. +0 −15 frontend/src/reportWebVitals.ts
  62. +0 −5 frontend/src/setupTests.ts
  63. +0 −26 frontend/tsconfig.json
  64. +44 −0 landing/public/examples/annotations/annotations-1h9t.cif
  65. +0 −34 landing/public/examples/annotations/annotations.cif
  66. +143 −134 landing/public/examples/annotations/state.mvsj
  67. BIN landing/public/examples/annotations/thumb.png
  68. +1 −1 landing/public/examples/basic/state.mvsj
  69. +1 −1 landing/public/examples/components/state.mvsj
  70. +1 −1 landing/public/examples/label/state.mvsj
  71. +193 −0 landing/public/examples/primitives/state.mvsj
  72. BIN landing/public/examples/primitives/thumb.png
  73. +2 −2 landing/public/examples/superposition/state.mvsj
  74. +1 −1 landing/public/examples/symmetry/state.mvsj
  75. +208 −0 landing/public/examples/volumes/state.mvsj
  76. BIN landing/public/examples/volumes/thumb.png
  77. BIN landing/public/img/ihm-restraints.png
  78. BIN landing/public/img/kinases.png
  79. +133 −81 landing/src/App.tsx
  80. +204 −58 landing/src/examples.tsx
  81. +14 −3 landing/src/index.css
  82. +0 −188 molviewspec/README.md
  83. +1 −0 molviewspec/README.md
  84. +1,066 −78 molviewspec/app/api/examples.py
  85. +4 −0 molviewspec/app/api/utils.py
  86. +12 −2 molviewspec/molviewspec/__init__.py
  87. +1,059 −89 molviewspec/molviewspec/builder.py
  88. +642 −69 molviewspec/molviewspec/nodes.py
  89. +16 −0 molviewspec/molviewspec/utils.py
  90. 0 molviewspec/py.typed
  91. +47 −0 molviewspec/test_server.py
9 changes: 9 additions & 0 deletions .github/pull_request_template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
<!-- Thank you for contributing to mol-view-spec -->

# Description


## Actions

- [ ] Added description of changes to the `[Unreleased]` section of `CHANGELOG.md`
- [ ] (Optional but encouraged) Added example(s) for new feature(s) in this PR to `app/api/examples.py`
41 changes: 41 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Change Log
All notable changes to this project will be documented in this file, following the suggestions of [Keep a CHANGELOG](http://keepachangelog.com/). This project adheres to [Semantic Versioning](http://semver.org/).

## [v1.2.1] - 2025-02-26

- State-related nodes are now exported by the package

## [v1.2.0] - 2025-02-25

- Focus node
- Can be on root
- Focus node radius, radius_factor, radius_extent parameters
- Breaking: Change `transparency` to `opacity`
- Breaking: Renamed geometrical primitive `line` to `tube`
- Breaking: Change multiple geometrical primitive parameters
- Multi-state data model tweaks
- Support for representation-specific parameters (customize presentation visuals)
- Add `coarse` component kind
- Add `spacefill` representation
- Add `carbohydrate` representation
- Add `element_granularity` field to component expressions
- Add I/HM basic restraints example
- Add primitives: ellipse, ellipsoid, box, arrow, angle
- Add basic support for volumetric data (map, volume server)
- Add membrane orientation examples


## [v1.1.0] - 2024-12-09

- Support for multiple states in one `.msvj` file
- Configurable transitions/animations between states
- Configurable opacity of representations
- Add support for additional/custom properties on each node ("vendor-specific properties")
- This allows users to store custom data
- Mol* can be instructed to show non-covalent interactions by providing vendor-specific properties
- Fixes several issues with defined types
- Support `ref` property on `Node` which enables referencing nodes by this value
- Geometrical primitives support (experimental and under development)

## [v1.0.0] - 2024-04-10
- Initial release
262 changes: 255 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,233 @@
[![PyPI version](https://badge.fury.io/py/molviewspec.svg)](https://badge.fury.io/py/molviewspec)
[![Changelog](https://img.shields.io/badge/changelog--lightgrey.svg?style=flat)](https://github.com/molstar/mol-view-spec/blob/master/CHANGELOG.md)

MolViewSpec
=============

## See the MolViewSpec Python Library in Action
MolViewSpec (*.msvj) is a JSON-based file format that is used to describe visual scenes or views used in molecular
visualization.
It adopts declarative data-driven approach to describe, load, render, and visually deliver molecular structures, along
with 3D representations, coloring schemes, and associated structural, biological, or functional annotations.
This Python toolkit allows for describing the information required for representing a molecular view state as data in a nested
tree format that can be consumed by visualization software tools such as
[Mol*](https://github.com/molstar/molstar/tree/master/src/extensions/mvs).

When using MolViewSpec, please cite:

Sebastian Bittrich, Adam Midlik, Mihaly Varadi, Sameer Velankar, Stephen K. Burley, Jasmine Y. Young, David Sehnal, Brinda Vallat: Describing and Sharing Molecular Visualizations Using the MolViewSpec Toolkit, Current Protocols, 2024; https://doi.org/10.1002/cpz1.1099.

## The Idea behind MolViewSpec

In the long run, MolViewSpec aims to re-imagine how users define molecular scenes by detaching this process from any
concrete 3D viewer.

MolViewSpec's workflow is:
1. `define scene using MolViewSpec`
2. `generic state description as .msvj`
3. `open in any MolViewSpec-compatible 3D viewer`

Opposed to the traditional workflow that locks users into using a specific 3D viewer, such as:
1. `define scene in Mol*`
2. `Mol*-specific state format`
3. `open only in Mol*`


## See the MolViewSpec in Action
Colab Notebook: https://colab.research.google.com/drive/1O2TldXlS01s-YgkD9gy87vWsfCBTYuz9

## Install from PyPI

## Access Type Definitions
All type definitions can be found here:
- using a dedicated Server endpoint: http://localhost:9000/api/v1/utils/models/openapi.json
- same content as static file: https://molstar.org/mol-view-spec-docs/files/molviewspec-v1-openapi-schema.json
- in Markdown: https://molstar.org/mol-view-spec-docs/tree-schema/


## Description of the MolViewSpec State Tree
MolViewSpec provides a generic description of typical visual scenes that may occur as part of molecular visualizations.
A tree format allows the composition of complex scene descriptors by combining reoccurring nodes that serve as
building blocks.

Nodes can be nested to allow chaining of operations as child nodes will be applied to the result of the operation
described by its parent node.

The corresponding MolViewSpec tree is provided in JSON and may look like this:
```json
{
"root": {
"kind": "root",
"children": [
{
"kind": "download",
"params": {
"url": "https://files.wwpdb.org/download/1cbs.cif"
},
"children": [
{
"kind": "parse",
"params": {
"format": "mmcif"
},
"children": [
{
"kind": "structure",
"params": {
"type": "model"
},
"children": [
{
"kind": "component",
"params": {
"selector": "all"
},
"children": [
{
"kind": "representation",
"params": {
"type": "cartoon"
}
}
]
}
]
}
]
}
]
}
]
},
"metadata": {
"version": "0.1",
"timestamp": "2023-11-16T11:41:07.421220"
}
}
```

Mol* is the reference implementation for reading MolViewSpec files.


### The Tree Root

Every tree starts with a single `root` node, which contains all nodes in a structure fashion, and a `metadata` node,
which can hold additional information such as a `version` tag as well as the `timestamp` when a view was created.

```json
{
"root": {},
"metadata": {
"version": "0.1",
"timestamp": "2023-11-16T11:41:07.421220"
}
}
```


### The `root` Node

All nodes of the tree must define their `kind` and may have 0 or more child nodes (`children`).
The `root` is a special node with a `kind` of `root` that contains a collection of `children`.

```json
{
"kind": "root",
"children": []
}
```


### The `download` Node

Node types other than the `root` may contain an optional `params` property. A common action is loading of 3D structure
data. This is done using a node of `kind` `download`. In this context, `params` can for example provide the `url` from
which data will be loaded from.

```json
{
"kind": "download",
"children": [],
"params": {
"url": "https://files.wwpdb.org/download/1cbs.cif"
}
}
```


### The `parse` Node

The previous `download` operation merely obtains the resources from the specified URL. To make it available to the
viewer, the data must be parsed. This operation expects that the `format` is defined (in this case mmCIF is parsed).

```json
{
"kind": "parse",
"children": [],
"params": {
"format": "mmcif"
}
}
```


### The `structure` Node

There are different ways to load the content of a mmCIF file. Common actions are loading the 1st biological assembly or
loading the deposited coordinates (also called "asymmetric unit" or "model coordinates").
The action is defined as `kind`. In this example, the `model` coordinates are loaded.

```json
{
"kind": "structure",
"children": [],
"params": {
"kind": "model"
}
}
```


### The `component` Node

At this point, the loaded file is available in the viewer but nothing is visualized yet. Several selection (called
"components") can be created. The example creates a component that includes everything using a `selector` set to `all`.
Other options could be a selection for protein chains, nucleic acids, ligands etc.
Components are reusable groups of atoms, residues, or chains, which can be interacted with programmatically.

```json
{
"kind": "component",
"children": [],
"params": {
"selector": "all"
}
}
```


### The `representation` Node

The `representation` nodes applies to previously created components, which is provided by the parent node of a
`representation` node. Representations are dedicated visuals that constitute a component. In this example, the selection
from above -- which selects the entire structure -- and depicts it as cartoon by specifying `cartoon` as `type`.

```json
{
"kind": "representation",
"params": {
"type": "cartoon"
}
}
```


### Expanding the Tree
Nodes can have 0 or more nodes as children. It is, for example, possible to create multiple `component` nodes based on a
particular `structure` node to create different representations for different types of molecules.


### Development

### Install from PyPI
```shell
pip install molviewspec
```
@@ -14,8 +237,8 @@ Find the package at: https://pypi.org/project/molviewspec/
### Setting up the environment

```
mamba env create -f ./environment.yaml
conda activate mol-view-spec-dev
micromamba env create -f ./environment.yaml
micromamba activate mol-view-spec-dev
```

### Running the server
@@ -28,9 +251,34 @@ python serve.py # or make serve
will run the server on `localhost:9000` with reload mode on.

- API Docs: `http://localhost:9000/docs`
- Example: `http://localhost:9000/api/v1/examples/load/1tqn`
- Example: `http://localhost:9000/api/v1/examples/load?id=1tqn`

### Testing API examples

Start the server and run

```
cd molviewspec
python test_server.py
```

Will call all API endpoint that can be called without arguments.

### Formatting the Project

```
cd molviewspec
make format
make mypy
```

### Publishing the Python Library

- Set version (in https://github.com/molstar/mol-view-spec/blob/master/molviewspec/molviewspec/__init__.py)
- Create a GitHub release
- Tag will automatically publish to PyPI


### Mol* Extension
## Mol* Extension

MolViewSpec is supported in Mol* via an [official extension](https://github.com/molstar/molstar/tree/master/src/extensions/mvs).
MolViewSpec is supported in Mol* via an [official extension](https://github.com/molstar/molstar/tree/master/src/extensions/mvs).
Loading