[](https://badge.fury.io/py/molviewspec)
[](https://github.com/molstar/mol-view-spec/blob/master/CHANGELOG.md)
MolViewSpec
=============
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
## 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
```
Find the package at: https://pypi.org/project/molviewspec/
### Setting up the environment
```
micromamba env create -f ./environment.yaml
micromamba activate mol-view-spec-dev
```
### Running the server
```
cd molviewspec
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?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
MolViewSpec is supported in Mol* via an [official extension](https://github.com/molstar/molstar/tree/master/src/extensions/mvs).
Raw data
{
"_id": null,
"home_page": "https://github.com/molstar/mol-view-spec",
"name": "molviewspec",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "molecular graphics, scientific visualization, web graphics, view specification, scene building, Mol*",
"author": "Sebastian Bittrich, Adam Midlik, David Sehnal",
"author_email": "sebastian.bittrich@rcsb.org, midlik@ebi.ac.uk, david.sehnal@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/2d/3e/9ced1268b1846e72967f2d86175fb802038237528730e32bfae1771fd1ad/molviewspec-1.2.1.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/molviewspec)\n[](https://github.com/molstar/mol-view-spec/blob/master/CHANGELOG.md)\n\nMolViewSpec\n=============\n\nMolViewSpec (*.msvj) is a JSON-based file format that is used to describe visual scenes or views used in molecular \nvisualization.\nIt adopts declarative data-driven approach to describe, load, render, and visually deliver molecular structures, along\nwith 3D representations, coloring schemes, and associated structural, biological, or functional annotations.\nThis Python toolkit allows for describing the information required for representing a molecular view state as data in a nested \ntree format that can be consumed by visualization software tools such as \n[Mol*](https://github.com/molstar/molstar/tree/master/src/extensions/mvs).\n\nWhen using MolViewSpec, please cite:\n\nSebastian 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.\n\n## The Idea behind MolViewSpec\n\nIn the long run, MolViewSpec aims to re-imagine how users define molecular scenes by detaching this process from any \nconcrete 3D viewer.\n\nMolViewSpec's workflow is:\n1. `define scene using MolViewSpec`\n2. `generic state description as .msvj`\n3. `open in any MolViewSpec-compatible 3D viewer`\n\nOpposed to the traditional workflow that locks users into using a specific 3D viewer, such as:\n1. `define scene in Mol*`\n2. `Mol*-specific state format`\n3. `open only in Mol*`\n\n\n## See the MolViewSpec in Action\nColab Notebook: https://colab.research.google.com/drive/1O2TldXlS01s-YgkD9gy87vWsfCBTYuz9\n\n\n## Access Type Definitions\nAll type definitions can be found here:\n- using a dedicated Server endpoint: http://localhost:9000/api/v1/utils/models/openapi.json\n- same content as static file: https://molstar.org/mol-view-spec-docs/files/molviewspec-v1-openapi-schema.json\n- in Markdown: https://molstar.org/mol-view-spec-docs/tree-schema/\n\n\n## Description of the MolViewSpec State Tree\nMolViewSpec provides a generic description of typical visual scenes that may occur as part of molecular visualizations.\nA tree format allows the composition of complex scene descriptors by combining reoccurring nodes that serve as\nbuilding blocks.\n\nNodes can be nested to allow chaining of operations as child nodes will be applied to the result of the operation\ndescribed by its parent node.\n\nThe corresponding MolViewSpec tree is provided in JSON and may look like this:\n```json\n{\n \"root\": {\n \"kind\": \"root\",\n \"children\": [\n {\n \"kind\": \"download\",\n \"params\": {\n \"url\": \"https://files.wwpdb.org/download/1cbs.cif\"\n },\n \"children\": [\n {\n \"kind\": \"parse\",\n \"params\": {\n \"format\": \"mmcif\"\n },\n \"children\": [\n {\n \"kind\": \"structure\",\n \"params\": {\n \"type\": \"model\"\n },\n \"children\": [\n {\n \"kind\": \"component\",\n \"params\": {\n \"selector\": \"all\"\n },\n \"children\": [\n {\n \"kind\": \"representation\",\n \"params\": {\n \"type\": \"cartoon\"\n }\n }\n ]\n }\n ]\n }\n ]\n }\n ]\n }\n ]\n },\n \"metadata\": {\n \"version\": \"0.1\",\n \"timestamp\": \"2023-11-16T11:41:07.421220\"\n }\n}\n```\n\nMol* is the reference implementation for reading MolViewSpec files.\n\n\n### The Tree Root\n\nEvery tree starts with a single `root` node, which contains all nodes in a structure fashion, and a `metadata` node,\nwhich can hold additional information such as a `version` tag as well as the `timestamp` when a view was created.\n\n```json\n{\n \"root\": {},\n \"metadata\": {\n \"version\": \"0.1\",\n \"timestamp\": \"2023-11-16T11:41:07.421220\"\n }\n}\n```\n\n\n### The `root` Node\n\nAll nodes of the tree must define their `kind` and may have 0 or more child nodes (`children`).\nThe `root` is a special node with a `kind` of `root` that contains a collection of `children`.\n\n```json\n{\n \"kind\": \"root\",\n \"children\": []\n}\n```\n\n\n### The `download` Node\n\nNode types other than the `root` may contain an optional `params` property. A common action is loading of 3D structure\ndata. This is done using a node of `kind` `download`. In this context, `params` can for example provide the `url` from\nwhich data will be loaded from.\n\n```json\n{\n \"kind\": \"download\",\n \"children\": [],\n \"params\": {\n \"url\": \"https://files.wwpdb.org/download/1cbs.cif\"\n }\n}\n```\n\n\n### The `parse` Node\n\nThe previous `download` operation merely obtains the resources from the specified URL. To make it available to the\nviewer, the data must be parsed. This operation expects that the `format` is defined (in this case mmCIF is parsed).\n\n```json\n{\n \"kind\": \"parse\",\n \"children\": [],\n \"params\": {\n \"format\": \"mmcif\"\n }\n}\n```\n\n\n### The `structure` Node\n\nThere are different ways to load the content of a mmCIF file. Common actions are loading the 1st biological assembly or\nloading the deposited coordinates (also called \"asymmetric unit\" or \"model coordinates\").\nThe action is defined as `kind`. In this example, the `model` coordinates are loaded.\n\n```json\n{\n \"kind\": \"structure\",\n \"children\": [],\n \"params\": {\n \"kind\": \"model\"\n }\n}\n```\n\n\n### The `component` Node\n\nAt this point, the loaded file is available in the viewer but nothing is visualized yet. Several selection (called\n\"components\") can be created. The example creates a component that includes everything using a `selector` set to `all`.\nOther options could be a selection for protein chains, nucleic acids, ligands etc.\nComponents are reusable groups of atoms, residues, or chains, which can be interacted with programmatically.\n\n```json\n{\n \"kind\": \"component\",\n \"children\": [],\n \"params\": {\n \"selector\": \"all\"\n }\n}\n```\n\n\n### The `representation` Node\n\nThe `representation` nodes applies to previously created components, which is provided by the parent node of a\n`representation` node. Representations are dedicated visuals that constitute a component. In this example, the selection\nfrom above -- which selects the entire structure -- and depicts it as cartoon by specifying `cartoon` as `type`.\n\n```json\n{\n \"kind\": \"representation\",\n \"params\": {\n \"type\": \"cartoon\"\n }\n}\n```\n\n\n### Expanding the Tree\nNodes can have 0 or more nodes as children. It is, for example, possible to create multiple `component` nodes based on a\nparticular `structure` node to create different representations for different types of molecules.\n\n\n### Development\n\n### Install from PyPI\n```shell\npip install molviewspec\n```\n\nFind the package at: https://pypi.org/project/molviewspec/\n\n### Setting up the environment\n\n```\nmicromamba env create -f ./environment.yaml\nmicromamba activate mol-view-spec-dev\n```\n\n### Running the server\n\n```\ncd molviewspec\npython serve.py # or make serve\n```\n\nwill run the server on `localhost:9000` with reload mode on.\n\n- API Docs: `http://localhost:9000/docs`\n- Example: `http://localhost:9000/api/v1/examples/load?id=1tqn`\n\n### Testing API examples\n\nStart the server and run\n\n```\ncd molviewspec\npython test_server.py\n```\n\nWill call all API endpoint that can be called without arguments.\n\n### Formatting the Project\n\n```\ncd molviewspec\nmake format\nmake mypy\n```\n\n### Publishing the Python Library\n\n- Set version (in https://github.com/molstar/mol-view-spec/blob/master/molviewspec/molviewspec/__init__.py)\n- Create a GitHub release\n- Tag will automatically publish to PyPI\n\n\n## Mol* Extension \n\nMolViewSpec is supported in Mol* via an [official extension](https://github.com/molstar/molstar/tree/master/src/extensions/mvs).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate Mol* views using this simple Python library, which allows you to compose complex scenes in a step-wise manner.",
"version": "1.2.1",
"project_urls": {
"Download": "https://github.com/molstar/mol-view-spec/archive/v1.2.1.tar.gz",
"Homepage": "https://github.com/molstar/mol-view-spec"
},
"split_keywords": [
"molecular graphics",
" scientific visualization",
" web graphics",
" view specification",
" scene building",
" mol*"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f71cd742386798af0cc6a65db3278a172df741e446b31c3b3dfef58c1128896b",
"md5": "0e531f9d994601af7109d382c28333c0",
"sha256": "8c65464571356876602ae64827cfc5c3fb429454e6243300e0e608fcb51937a8"
},
"downloads": -1,
"filename": "molviewspec-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0e531f9d994601af7109d382c28333c0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 23339,
"upload_time": "2025-02-27T00:57:26",
"upload_time_iso_8601": "2025-02-27T00:57:26.250606Z",
"url": "https://files.pythonhosted.org/packages/f7/1c/d742386798af0cc6a65db3278a172df741e446b31c3b3dfef58c1128896b/molviewspec-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2d3e9ced1268b1846e72967f2d86175fb802038237528730e32bfae1771fd1ad",
"md5": "01de1005254a9debfa0127f0677df6f6",
"sha256": "32d759e3e60c52c9da52a634ab0d744832f3540baa48e276f0b5c58031b640cb"
},
"downloads": -1,
"filename": "molviewspec-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "01de1005254a9debfa0127f0677df6f6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 26282,
"upload_time": "2025-02-27T00:57:27",
"upload_time_iso_8601": "2025-02-27T00:57:27.832106Z",
"url": "https://files.pythonhosted.org/packages/2d/3e/9ced1268b1846e72967f2d86175fb802038237528730e32bfae1771fd1ad/molviewspec-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-27 00:57:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "molstar",
"github_project": "mol-view-spec",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "molviewspec"
}
JSON
