### Install Deno Jupyter and Run Notebook

Source: https://github.com/molstar/mol-view-spec/blob/master/molviewspec-ts/README.md

Installs Deno Jupyter and launches a specific notebook using uvx. Requires deno and UV to be installed.

```sh
# requires deno and UV
denp jupyter --install 
uvx --from jupyter-core jupyter lab test-data/notebooks-ts/01_kras_structure_visualization.ipynb
```

--------------------------------

### Test MolViewSpec Server API Examples

Source: https://github.com/molstar/mol-view-spec/blob/master/README.md

Run tests for API endpoints that can be called without arguments after starting the server.

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

--------------------------------

### Create Basic Molecular Visualization with MolViewSpec

Source: https://context7.com/molstar/mol-view-spec/llms.txt

Use `create_builder()` to start building a visualization. This example downloads, parses, and visualizes a PDB structure, applying different representations and colors to polymer and ligand components. It also sets canvas background and camera position before exporting the state.

```python
from molviewspec import create_builder

# Create a new builder instance
builder = create_builder()

# Download, parse, and visualize a PDB structure
structure = (
    builder
    .download(url="https://www.ebi.ac.uk/pdbe/entry-files/1cbs.bcif")
    .parse(format="bcif")
    .model_structure()
)

# Add cartoon representation for polymer with green color
(
    structure
    .component(selector="polymer")
    .representation(type="cartoon")
    .color(color="green")
)

# Add ball-and-stick for ligand with magenta color
(
    structure
    .component(selector="ligand")
    .representation(type="ball_and_stick")
    .color(color="#cc3399")
)

# Set canvas background and camera position
builder.canvas(background_color="#ffffee")
builder.camera(target=[17, 21, 27], position=[41, 34, 69], up=[-0.129, 0.966, -0.224])

# Export the state
state = builder.get_state(title="Example Visualization")
print(state.model_dump_json(exclude_none=True, indent=2))
```

--------------------------------

### Install MolViewSpec

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks/04_color_themes.ipynb

Install the molviewspec library using pip.

```python
# Install molviewspec
!pip install molviewspec
```

--------------------------------

### Install MolViewSpec

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks/02_mvsx_mvsj_stories_ui.ipynb

Install the molviewspec library using pip.

```python
# !pip install molviewspec
```

--------------------------------

### Install Dependencies and Run Streamlit App

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/streamlit/README.md

Install the necessary Python packages and then run the Streamlit application.

```bash
pip install molviewspec streamlit
```

```bash
streamlit run app.py
```

--------------------------------

### MVSX Archive Creation Example

Source: https://github.com/molstar/mol-view-spec/blob/master/docs/docs/index.md

Command-line examples demonstrating the correct and incorrect methods for creating an MVSX (ZIP archive) file. The MVSX format bundles the MVSJ file with other assets like annotations or structure files.

```bash
$ ls example/
annotations-1h9t.cif   index.mvsj
$ zip -r example.mvsx example/            # Wrong, won't create a valid MVSX file
$ cd example/; zip -r ../example.mvsx *   # Correct
```

--------------------------------

### Install MkDocs Material

Source: https://github.com/molstar/mol-view-spec/blob/master/docs/README.md

Install the MkDocs Material theme for building the documentation. Requires Python 3.x.

```bash
pip install mkdocs-material
```

--------------------------------

### Start Jupyter Notebook Server

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks-ts/README.md

Starts the Jupyter notebook server to access and run notebooks.

```bash
jupyter notebook
```

--------------------------------

### Serve MkDocs Documentation Locally

Source: https://github.com/molstar/mol-view-spec/blob/master/docs/README.md

Serve the MkDocs documentation locally to preview changes. Ensure MkDocs is installed.

```bash
mkdocs serve
```

--------------------------------

### Run MolViewSpec Server

Source: https://github.com/molstar/mol-view-spec/blob/master/README.md

Start the development server on localhost:9000 with reload mode enabled.

```shell
cd molviewspec
python serve.py # or make serve
```

--------------------------------

### Deno Jupyter Kernel Installation

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks-ts/README.md

Instructions for installing the Deno Jupyter kernel.

```APIDOC
## Deno Jupyter Kernel Installation

### Description
This section provides the command to install the Deno Jupyter kernel, which is required to run the MolViewSpec TypeScript notebooks.

### Command
```bash
den o jupyter --install
```

### Troubleshooting Permissions
If you encounter permission errors during installation or execution, run Jupyter with elevated permissions:

```bash
den o jupyter --allow-read --allow-write --allow-net
```
```

--------------------------------

### Install Deno Jupyter Kernel

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks-ts/README.md

Installs the Deno kernel for Jupyter notebooks.

```bash
deno jupyter --install
```

--------------------------------

### Install MolViewSpec from PyPI

Source: https://github.com/molstar/mol-view-spec/blob/master/README.md

Install the molviewspec package using pip.

```shell
pip install molviewspec
```

--------------------------------

### Basic Structure Visualization Example

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks-ts/README.md

Loads a PDB structure, parses it, and applies a blue color to the polymer component using the MolViewSpec builder.

```typescript
const builder = createBuilder();

builder
  .download('https://files.wwpdb.org/download/1cbs.cif')
  .parse('mmcif')
  .modelStructure()
  .component('polymer')
  .representation()
  .color('blue');

const state = builder.getState();
```

--------------------------------

### GET /api/v1/examples/data/{id}/json-annotations

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/README.md

Lists all available JSON annotation file names for a specific entry.

```APIDOC
## GET /api/v1/examples/data/{id}/json-annotations

### Description
Lists the names of all `.json` annotation files within the specified entry's folder.

### Method
GET

### Endpoint
/api/v1/examples/data/{id}/json-annotations

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the data entry.

### Response
#### Success Response (200)
- **fileNames** (array of strings) - A list of JSON annotation file names.
```

--------------------------------

### GET /api/v1/examples/data/{id}/json/{name}

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/README.md

Retrieves a specific JSON annotation file for a given entry.

```APIDOC
## GET /api/v1/examples/data/{id}/json/{name}

### Description
Returns the content of a specific JSON annotation file (`{name}.json`) from the specified entry's folder.

### Method
GET

### Endpoint
/api/v1/examples/data/{id}/json/{name}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the data entry.
- **name** (string) - Required - The name of the JSON annotation file (without the .json extension).
```

--------------------------------

### MolViewSpec Download Node Example

Source: https://github.com/molstar/mol-view-spec/blob/master/README.md

The 'download' node is used for loading 3D structure data, providing a 'url' in its 'params'.

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

--------------------------------

### Install Mol* Package

Source: https://github.com/molstar/mol-view-spec/blob/master/docs/docs/mvs-molstar-extension/index.md

Install the Mol* package from npm to use its CLI tools. This command includes necessary dependencies for canvas and image processing.

```bash
npm install molstar canvas gl jpeg-js pngjs
```

--------------------------------

### GET /api/v1/examples/data/{id}/molecule

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/README.md

Retrieves the CIF file for a specific molecule entry.

```APIDOC
## GET /api/v1/examples/data/{id}/molecule

### Description
Returns the `molecule.cif` file for the specified entry ID.

### Method
GET

### Endpoint
/api/v1/examples/data/{id}/molecule

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the data entry.
```

--------------------------------

### Instance ID Examples for Crystals

Source: https://github.com/molstar/mol-view-spec/blob/master/docs/docs/selectors.md

Illustrates the format of instance IDs used for distinguishing crystal symmetry instances, following mmCIF recommendations.

```text
e.g. `1_555`, `2_454`
```

```text
e.g. `1_(11)15`, `1_1(11)5`, `1_11(15)` (instead of ambiguous `1_1115`)
```

```text
e.g. `1_(-1)1(-1)`
```

--------------------------------

### GET /api/v1/examples/data/{id}/molecule-and-cif-annotations

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/README.md

Retrieves both molecule CIF and CIF annotations for a specific entry.

```APIDOC
## GET /api/v1/examples/data/{id}/molecule-and-cif-annotations

### Description
Returns a concatenated file containing both `molecule.cif` and `annotations.cif` for the specified entry ID.

### Method
GET

### Endpoint
/api/v1/examples/data/{id}/molecule-and-cif-annotations

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the data entry.
```

--------------------------------

### Markdown Syntax for Camera Controls

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks-ts/05_markdown_commands.ipynb

Provides examples of markdown links to control the camera view, specifically for centering and resetting the camera.

```markdown
[center](!center-camera)
```

```markdown
[reset](!reset-camera)
```

--------------------------------

### Advanced Snapshot Example with Multiple States

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks-ts/02_mvsx_mvsj_stories_ui.ipynb

Builds a story with multiple states and transitions, demonstrating saving intermediate states and retrieving all states for MVSJ.

```typescript
const builder1 = createBuilder();

const struct1 = builder1
  .download({ url: 'https://files.wwpdb.org/download/1cbs.cif' })
  .parse({ format: 'mmcif' })
  .modelStructure();

struct1
  .component({ selector: "polymer" })
  .representation({ type: "cartoon" })
  .color({ color: "blue" });

// Save first state and continue
builder1.saveState({
  title: "Overview",
  description: "Full structure view",
  linger_duration_ms: 2000,
});

// Build second state
const struct2 = builder1
  .download({ url: 'https://files.wwpdb.org/download/1cbs.cif' })
  .parse({ format: 'mmcif' })
  .modelStructure();

struct2
  .component({ selector: "ligand" })
  .representation({ type: 'ball_and_stick' })
  .color({ color: "red" });

// Get all states
const multipleStates = builder1.getStates({
  title: "Structure Story",
  description: "A story showing different views of the structure",
});

console.log(JSON.stringify(multipleStates, null, 2));
await molstarNotebook(multipleStates)
```

--------------------------------

### GET /api/v1/examples/data/{id}/cif-annotations

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/README.md

Retrieves CIF annotations for a specific molecule entry.

```APIDOC
## GET /api/v1/examples/data/{id}/cif-annotations

### Description
Returns the `annotations.cif` file for the specified entry ID. The response includes `data_{id}_annotations` prepended to the file content.

### Method
GET

### Endpoint
/api/v1/examples/data/{id}/cif-annotations

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier for the data entry.
```

--------------------------------

### MolViewSpec State Tree Example

Source: https://github.com/molstar/mol-view-spec/blob/master/README.md

This JSON structure defines a molecular visualization scene, including downloading a PDB file, parsing it, and applying a cartoon representation. It demonstrates the nested, declarative nature of MolViewSpec.

```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-11T11:41:07.421220"
  }
}
```

--------------------------------

### MolViewSpec Parse Node Example

Source: https://github.com/molstar/mol-view-spec/blob/master/README.md

The 'parse' node is used to parse downloaded data, specifying the 'format' in its 'params'.

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

--------------------------------

### MolViewSpec Component Node Example

Source: https://github.com/molstar/mol-view-spec/blob/master/README.md

The 'component' node creates reusable groups of atoms, residues, or chains, using a 'selector' like 'all'.

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

--------------------------------

### Load and Visualize Structure from URL

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks-ts/01_kras_structure_visualization.ipynb

Loads a structure from a URL, parses it, and visualizes all components in cyan cartoon representation. This example demonstrates a basic visualization flow.

```typescript
const builder3 = createBuilder();

// Note: In TypeScript, you would typically use a data URI or reference to embedded data
// For demonstration purposes, we show the structure with a URL
const structure3 = builder3
  .download({ url: 'https://files.wwpdb.org/download/1cbs.cif' })
  .parse({ format: 'mmcif' })
  .modelStructure();

structure3
  .component({ selector: "all" })
  .representation({ type: "cartoon" })
  .color({ color: "cyan" });

const state3 = builder3.getState();
// console.log(JSON.stringify(state3, null, 2));

await molstarNotebook(state3)
```

--------------------------------

### Create Builder and Enter Primitives Mode

Source: https://github.com/molstar/mol-view-spec/blob/master/docs/docs/primitives.md

Initialize a builder instance and enter the primitives mode to start defining geometric shapes. Customization options like opacity can be applied at this stage.

```python
builder = create_builder()
builder.primitives(opacity=0.66)
```

--------------------------------

### Load and Visualize Structure Data

Source: https://context7.com/molstar/mol-view-spec/llms.txt

Load molecular structure data from a URL and apply representations. This example shows loading a BCIF file, parsing it, and styling polymer and ligand components.

```python
from molviewspec import create_builder

builder = create_builder()

# Load structure
structure = (
    builder
    .download(url="https://www.ebi.ac.uk/pdbe/entry-files/1tqn.bcif")
    .parse(format="bcif")
    .model_structure()
)
structure.component(selector="polymer").representation(type="cartoon").color(color="white")
ligand = structure.component(selector="ligand")
ligand.representation(type="ball_and_stick").color(color="yellow")
ligand.focus(radius=14, radius_extent=5)
```

--------------------------------

### MolViewSpec JSON State Tree Example

Source: https://github.com/molstar/mol-view-spec/blob/master/molviewspec/README.md

This JSON structure defines a molecular visualization scene. It includes steps for downloading a PDB file, parsing it, and applying a cartoon representation to all components. Use this as a template for creating your own MolViewSpec files.

```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"
  }
}
```

--------------------------------

### Load and Visualize Volumetric Data (MAP)

Source: https://context7.com/molstar/mol-view-spec/llms.txt

Load volumetric data from a CCP4 map file and visualize it as an isosurface. This example sets the relative isovalue, wireframe visibility, color, and opacity.

```python
# Load density from CCP4 map file
volume = (
    builder
    .download(url="https://www.ebi.ac.uk/pdbe/entry-files/1tqn.ccp4")
    .parse(format="map")
    .volume()
)
(
    volume
    .representation(type="isosurface", relative_isovalue=1.5, show_wireframe=True)
    .color(color="blue")
    .opacity(opacity=0.5)
```

--------------------------------

### Query and Visualize Density from PDBe Volume Server

Source: https://context7.com/molstar/mol-view-spec/llms.txt

Query electron density data from the PDBe Volume Server for a specific region. This example loads a 2Fo-Fc map and a Fo-Fc difference map, applying different representations and colors.

```python
# Query density from PDBe Volume Server for specific region
volume_data = (
    builder
    .download(url="https://www.ebi.ac.uk/pdbe/densities/x-ray/1tqn/box/-22,-33,-22/-7,-10,-1?detail=3")
    .parse(format="bcif")
)

# 2Fo-Fc map (electron density)
(
    volume_data
    .volume(channel_id="2FO-FC")
    .representation(type="isosurface", relative_isovalue=1.5, show_wireframe=True, show_faces=False)
    .color(color="blue")
    .opacity(opacity=0.3)
)

# Fo-Fc difference map (positive - green, negative - red)
fo_fc = volume_data.volume(channel_id="FO-FC")
(
    fo_fc
    .representation(type="isosurface", relative_isovalue=3.0, show_wireframe=True)
    .color(color="green")
    .opacity(opacity=0.4)
)
(
    fo_fc
    .representation(type="isosurface", relative_isovalue=-3.0, show_wireframe=True)
    .color(color="red")
    .opacity(opacity=0.4)
```

--------------------------------

### Combine Mol* Markdown Commands in a Link

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks-ts/05_markdown_commands.ipynb

Multiple Mol* markdown commands can be combined within a single link to create complex interactive behaviors. This example shows highlighting, focusing, and centering the camera simultaneously.

```markdown
[text](!highlight-refs=ref1&focus-refs=ref1&center-camera)
```

--------------------------------

### Set up MolViewSpec Development Environment

Source: https://github.com/molstar/mol-view-spec/blob/master/README.md

Create and activate a development environment using micromamba.

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

--------------------------------

### Download, Parse, and Model Structure

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks/06_animations.ipynb

Create a builder, download a PDB file from a URL, parse it, and model the structure. This is a foundational step for most operations.

```python
builder = mvs.create_builder()
structure = (
    builder.download(url=f"https://files.wwpdb.org/download/1cbs.cif")
        .parse(format="mmcif")
        .model_structure()
)
```

--------------------------------

### MVSJ (MolViewSpec JSON) Encoding Example

Source: https://github.com/molstar/mol-view-spec/blob/master/docs/docs/index.md

An example of a MolViewSpec tree encoded in MVSJ format, which is a JSON representation with additional metadata. This format is used for storing and transmitting MVS data.

```json
{
  "metadata": {
    "title": "Example MolViewSpec - 1cbs with labelled protein and ligand",
    "version": "1",
    "timestamp": "2023-11-24T10:38:17.483Z"
  },
  "root": {
    "kind": "root",
    "children": [
      {
        "kind": "download",
        "params": {"url": "https://www.ebi.ac.uk/pdbe/entry-files/1cbs.bcif"},
        "children": [
          {
            "kind": "parse",
            "params": {"format": "bcif"},
            "children": [
    ...
}
```

--------------------------------

### Build and Load MVS View in HTML

Source: https://github.com/molstar/mol-view-spec/blob/master/docs/docs/mvs-molstar-extension/integration.md

This example shows how to build an MVS view directly within an HTML script tag. It includes setting up the Molstar viewer and loading the constructed MVS data. Relative references in the MVS view will be resolved against the URL of this HTML page.

```html
<!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>
        <div id="viewer3" 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
            molstar.Viewer
                .create('viewer3', { layoutIsExpanded: false, layoutShowControls: false })
                .then(viewer => molstar.PluginExtensions.mvs.loadMVS(viewer.plugin, mvsData, { sourceUrl: undefined, sanityChecks: true, replaceExisting: false }));
        </script>
    </body>
</html>
```

--------------------------------

### Initialize Molstar Notebook Builder

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks/01_kras_structure_visualization.ipynb

Initializes the Molstar notebook builder with specified data and dimensions. Use this to pass additional arguments to the Molstar viewer.

```python
builder.molstar_notebook(data={'local.cif': cif_data}, width=500, height=400)
```

--------------------------------

### Select Whole Chain A

Source: https://github.com/molstar/mol-view-spec/blob/master/docs/docs/selectors.md

Example of a component expression to select all atoms belonging to chain 'A'.

```typescript
selector: { label_asym_id: 'A' }
```

--------------------------------

### Download, Parse, and Model Structure

Source: https://context7.com/molstar/mol-view-spec/llms.txt

Initializes the builder, downloads a structure file from a URL, parses it, and models the structure for further manipulation.

```python
from molviewspec import create_builder

builder = create_builder()
structure = (
    builder
    .download(url="https://www.ebi.ac.uk/pdbe/entry-files/1cbs.bcif")
    .parse(format="bcif")
    .model_structure()
)
```

--------------------------------

### Run All MolViewSpec Tests

Source: https://github.com/molstar/mol-view-spec/blob/master/README.md

Execute both the server and all registered unit tests using the 'make test' command.

```shell
cd molviewspec
make test
```

--------------------------------

### Configure Build Script for Molstar Landing Page

Source: https://github.com/molstar/mol-view-spec/blob/master/landing/README.md

Add this script to your package.json to specify the base path for the build. Run 'npm run build' after configuration.

```json
"build": "tsc && vite build --base=/mol-view-spec/"
```

--------------------------------

### MolViewSpec Representation Node Example

Source: https://github.com/molstar/mol-view-spec/blob/master/README.md

The 'representation' node applies visuals to components, specifying the 'type' of depiction, such as 'cartoon'.

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

--------------------------------

### Download and Parse Structure Data in MolViewSpec

Source: https://context7.com/molstar/mol-view-spec/llms.txt

Demonstrates downloading structure data from URLs and parsing it into different formats like mmCIF, BinaryCIF, SDF, and MOL. It also shows how to load assembly and crystal symmetry structures.

```python
from molviewspec import create_builder

builder = create_builder()

# Download and parse mmCIF format
structure_mmcif = (
    builder
    .download(url="https://files.wwpdb.org/download/1cbs.cif")
    .parse(format="mmcif")
    .model_structure()
)

# Download and parse BinaryCIF format (more efficient)
structure_bcif = (
    builder
    .download(url="https://www.ebi.ac.uk/pdbe/entry-files/1tqn.bcif")
    .parse(format="bcif")
    .model_structure()
)

# Load assembly structure (biological unit)
assembly = (
    builder
    .download(url="https://www.ebi.ac.uk/pdbe/entry-files/1hda.bcif")
    .parse(format="bcif")
    .assembly_structure(assembly_id="1")  # First assembly
)

# Load crystal symmetry structure
crystal = (
    builder
    .download(url="https://www.ebi.ac.uk/pdbe/entry-files/1cbs.bcif")
    .parse(format="bcif")
    .symmetry_structure(ijk_min=[-1, -1, -1], ijk_max=[1, 1, 1])
)

# Load SDF/MOL format for small molecules
ligand = (
    builder
    .download(url="https://example.org/molecule.sdf")
    .parse(format="sdf")
    .model_structure()
)
```

--------------------------------

### Create and Configure a Molecular Visualization

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks/02_mvsx_mvsj_stories_ui.ipynb

This snippet demonstrates how to create a visualization builder, download a PDB file, parse it, and apply a blue cartoon representation. It then creates an MVSX object for viewing or saving.

```python
builder = mvs.create_builder()

assets = {
    "1cbs.cif": "https://files.wwpdb.org/download/1cbs.cif",
    # To use a local file:
    # "1cbs.cif": "./local/path/to/1cbs.cif",
}

(    builder.download(url="1cbs.cif")
        .parse(format="mmcif")
        .model_structure()
        .component()
        .representation()
        .color(color="blue")
)

mvsx = mvs.MVSX(
    data=builder.get_state(),
    assets=assets
)

# uncomment to save to a local file
# mvsx.dump("./local/path/to/1cbs.mvsx")

# uncomment to view using Mol* Stories app
# mvs.molstar_notebook(mvsx, ui="stories")  # or mvsx.molstar_notebook(ui="stories")

# uncomment to show default view in Mol* viewer
print(mvsx)
```

--------------------------------

### Labeling without group_id

Source: https://github.com/molstar/mol-view-spec/blob/master/docs/docs/annotations.md

This example demonstrates how to create individual labels for each residue when the 'group_id' field is not used. Each row results in a separate label.

```cif
data_annotation
loop_
_labels.label_asym_id
_labels.label_seq_id
_labels.color
_labels.label
A 100 pink 'Substrate binding site'
A 150 pink 'Substrate binding site'
A 170 pink 'Substrate binding site'
A 200 blue 'Inhibitor binding site'
A 220 blue 'Inhibitor binding site'
A 300 lime 'Glycosylation site'
A 330 lime 'Glycosylation site'
```

--------------------------------

### Create and Configure Molecular Structure

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks/05_markdown_commands.ipynb

Build a molecular structure by downloading a PDB file, parsing it, and defining representations and colors for different components like polymers and ligands.

```python
builder = mvs.create_builder()

assets = {
    "1cbs.cif": "https://files.wwpdb.org/download/1cbs.cif",
    "logo.png": "https://molstar.org/img/molstar-logo.png",
}

model = (
    builder.download(url="1cbs.cif")
        .parse(format="mmcif")
        .model_structure()
)
(
    model.component(selector="polymer")
        .representation(ref="polymer")
        .color(color="blue")
)
(
    model.component(selector="ligand")
        .representation(ref="ligand")
        .color(color="red")
)
```

--------------------------------

### Interpolate Animation Color

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks/06_animations.ipynb

Define a color interpolation for the animation. This example sets up a continuous color transition from blue to red over 1000 milliseconds.

```python
anim.interpolate(
    kind="color",
    target_ref="color",
    duration_ms=1000,
    property="color",
    palette={
        "kind": "continuous",
        "colors": ["blue", "red"]
    }
)
```

--------------------------------

### Basic MolViewSpec Structure with Markdown

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks-ts/05_markdown_commands.ipynb

Demonstrates creating a molecular structure with polymer and ligand components, defining representations, and embedding interactive markdown descriptions with highlight, focus, color, and camera controls.

```typescript
const builder = createBuilder();

// Define assets
const assets = {
  "1cbs.cif": "https://files.wwpdb.org/download/1cbs.cif",
  "logo.png": "https://molstar.org/img/molstar-logo.png",
};

const model = builder
  .download({ url: "1cbs.cif" })
  .parse({ format: "mmcif" })
  .modelStructure();

// Create polymer representation with reference
model
  .component({ selector: "polymer" })
  .representation({ type: "cartoon" }, undefined, undefined, "polymer")
  .color({ color: "blue" });

// Create ligand representation with reference
model
  .component({ selector: "ligand" })
  .representation({ type: "ball_and_stick" }, undefined, undefined, "ligand")
  .color({ color: "red" });

// Create state with markdown description containing commands
const markdownDescription = `
# 1CBS Structure

Cellular retinoic-acid-binding protein 2 (CRABP-II)

## Highlight/Focus Controls:

- ![blue](!color-swatch=blue) [polymer](!highlight-refs=polymer&focus-refs=polymer)
- ![red](!color-swatch=red) [ligand](!highlight-refs=ligand&focus-refs=ligand)
- [both](!highlight-refs=polymer,ligand&focus-refs=polymer,ligand)

## Color Palette Table

This table shows different color palettes:

|name|visual|
|---:|---|
|viridis|![viridis](!color-palette-name=viridis)|
|rainbow (discrete)|![simple-rainbow](!color-palette-name=simple-rainbow&color-palette-discrete)|
|custom|![custom](!color-palette-colors=red,#00ff00,rgb(0,0,255))|

## Camera Controls

- [center](!center-camera) - Center the camera on the structure
- [reset](!reset-camera) - Reset camera to initial position

## Image Embedding

![Mol* Logo](logo.png)
`;

const state = builder.getState({
  title: "1CBS with Markdown Commands",
  description: markdownDescription,
  description_format: "markdown",
});

// Create MVSX with assets
const mvsx = new MVSX(state, assets);

console.log("State with markdown commands:");
console.log(JSON.stringify(state, null, 2));
console.log("\nAssets:");
console.log(JSON.stringify(assets, null, 2));

await molstarNotebook(mvsx)
```

--------------------------------

### Union Component Expression: Select Chains A, B, C

Source: https://github.com/molstar/mol-view-spec/blob/master/docs/docs/selectors.md

Example of a union component expression selecting atoms from chains 'A', 'B', or 'C'.

```typescript
selector: [{ label_asym_id: 'A' }, { label_asym_id: 'B' }, { label_asym_id: 'C' }];
```

--------------------------------

### Animate Multiple Properties Simultaneously

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks-ts/06_animations.ipynb

Use this to run multiple animations, such as color and opacity changes, at the same time. Animations can have different start times and durations.

```typescript
const builder4 = createBuilder();

const struct4 = builder4
  .download({ url: 'https://files.wwpdb.org/download/1cbs.cif' })
  .parse({ format: 'mmcif' })
  .modelStructure();

// Polymer with color and opacity references
struct4
  .component({ selector: "polymer" })
  .representation({ type: "cartoon" })
  .color({ color: "blue", ref: "poly_color" })
  .opacity({ opacity: 1.0, ref: "poly_opacity" });

// Ligand with different animation
struct4
  .component({ selector: "ligand" })
  .representation({ type: "ball_and_stick" })
  .color({ color: "red", ref: "lig_color" });

// Expected API:
// const anim4 = builder4.animation();
// 
// // Animate polymer color
// anim4.interpolate({
//   kind: "color",
//   target_ref: "poly_color",
//   property: "color",
//   duration_ms: 3000,
//   palette: { kind: "continuous", colors: ["blue", "cyan"] },
// });
// 
// // Animate polymer opacity
// anim4.interpolate({
//   kind: "scalar",
//   target_ref: "poly_opacity",
//   property: "opacity",
//   duration_ms: 3000,
//   from: 1.0,
//   to: 0.5,
//   easing: "cubic-in-out",
// });
// 
// // Animate ligand color (delayed start)
// anim4.interpolate({
//   kind: "color",
//   target_ref: "lig_color",
//   property: "color",
//   start_ms: 1000,  // Start after 1 second
//   duration_ms: 2000,
//   palette: { kind: "continuous", colors: ["red", "yellow"] },
// });

const snapshot4 = builder4.getSnapshot({
  title: "Multiple Animations",
  description: "Animating color and opacity simultaneously",
  linger_duration_ms: 4000,
});

// Manually add multiple animations for demonstration
snapshot4.animation = {
  kind: "animation",
  params: {
    frame_time_ms: 16.666666666666668,
    autoplay: true,
    loop: false,
  },
  children: [
    {
      kind: "interpolate",
      params: {
        target_ref: "poly_color",
        property: "color",
        start_ms: 0,
        duration_ms: 3000,
        kind: "color",
        palette: { kind: "continuous", colors: ["blue", "cyan"] },
      },
    },
    {
      kind: "interpolate",
      params: {
        target_ref: "poly_opacity",
        property: "opacity",
        start_ms: 0,
        duration_ms: 3000,
        kind: "scalar",
        start: 1.0,
        end: 0.5,
        easing: "cubic-in-out",
      },
    },
    {
      kind: "interpolate",
      params: {
        target_ref: "lig_color",
        property: "color",
        start_ms: 1000,
        duration_ms: 2000,
        kind: "color",
        palette: { kind: "continuous", colors: ["red", "yellow"] },
      },
    },
  ],
};

// Wrap snapshot in States object with proper metadata
const states4 = {
  kind: "multiple" as const,
  metadata: {
    title: "Multiple Animations",
    description: "Polymer and ligand animated together",
    timestamp: new Date().toISOString(),
    version: "1.8.1",
  },
  snapshots: [snapshot4],
};

// console.log(JSON.stringify(states4, null, 2));

await molstarNotebook(states4)
```

--------------------------------

### Create a MolViewSpec Snapshot

Source: https://github.com/molstar/mol-view-spec/blob/master/docs/docs/animations.md

Use the builder to define a scene and invoke `get_snapshot()` to obtain a snapshot instance. Snapshots can include custom titles and descriptions with markup.

```python
snapshot1 = builder.get_snapshot(
    title="1tqn",
    description="""
### 1tqn with ligand and electron density map
- 2FO-FC at 1.5σ, blue
- FO-FC (positive) at 3σ, green
- FO-FC (negative) at -3σ, red
""",
)
```

--------------------------------

### MVS Tree Representation (Direct Colors)

Source: https://github.com/molstar/mol-view-spec/blob/master/docs/docs/annotations.md

An example of how colors are applied directly within the MVS tree using individual color nodes with selectors.

```text
- representation {type: "cartoon"}
  - color {selector: {label_asym_id: "A"}, color: "#00ff00"}
  - color {selector: {label_asym_id: "B"}, color: "blue"}
  - color {selector: {label_asym_id: "B", beg_label_seq_id: 100, end_label_seq_id: 200}, color: "skyblue"}
  - color {selector: {label_asym_id: "B", beg_label_seq_id: 150, end_label_seq_id: 160}, color: "lightblue"}
```

--------------------------------

### Load and Visualize Molecular Structure with Ligand Focus

Source: https://github.com/molstar/mol-view-spec/blob/master/docs/docs/volumes.md

Loads a molecular structure, styles the polymer and ligand components, and focuses on the ligand. This sets up the scene before adding density data.

```python
builder = create_builder()

structure = builder.download(url=_url_for_mmcif("1tqn")).parse(format="mmcif").model_structure()
structure.component(selector="polymer").representation(type="cartoon").color(color="white")
ligand = structure.component(selector="ligand")
ligand.representation(type="ball_and_stick").color(custom={"molstar_color_theme_name": "element-symbol"})
ligand.focus(up=[0.98, -0.19, 0], direction=[-28.47, -17.66, -16.32], radius=14, radius_extent=5)
```

--------------------------------

### MolViewSpec Structure Node Example

Source: https://github.com/molstar/mol-view-spec/blob/master/README.md

The 'structure' node defines how to load content from a mmCIF file, specifying 'kind' like 'model' for deposited coordinates.

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

--------------------------------

### Validate MolViewSpec Files using npx

Source: https://github.com/molstar/mol-view-spec/blob/master/docs/docs/mvs-molstar-extension/index.md

After installing the Mol* package, you can use `npx` to run the validation tool. This is an alternative to directly executing the node script.

```bash
npx mvs-validate ...
```

--------------------------------

### Print MolViewSpec Schema as Markdown

Source: https://github.com/molstar/mol-view-spec/blob/master/docs/docs/mvs-molstar-extension/index.md

Use this command to generate the MolViewSpec tree schema formatted as markdown. Ensure you have the MolViewSpec package installed or are running from the repository.

```bash
node lib/commonjs/cli/mvs/mvs-print-schema.js --markdown
```

--------------------------------

### Component Expression: Select Residue Range in Chain

Source: https://context7.com/molstar/mol-view-spec/llms.txt

Select a specific range of residues within a given chain by providing start and end sequence IDs.

```python
structure.component(selector={
    "label_asym_id": "B",
    "beg_label_seq_id": 100,
    "end_label_seq_id": 200
})
```

--------------------------------

### Apply Transformation to a Specific Component

Source: https://context7.com/molstar/mol-view-spec/llms.txt

Apply transformations to individual components within a structure. This example transforms a ligand component and applies a specific representation and color.

```python
# Apply transformation to a component only
comp = structure.component(selector="ligand")
comp.transform(translation=[5, 5, 5])
comp.representation(type="ball_and_stick").color(color="green")
```

--------------------------------

### Markdown Syntax for Image References

Source: https://github.com/molstar/mol-view-spec/blob/master/test-data/notebooks-ts/05_markdown_commands.ipynb

Demonstrates how to reference and embed images from the defined assets within markdown descriptions.

```markdown
![alt text](asset_name.png)
```

--------------------------------

### Labeling with group_id

Source: https://github.com/molstar/mol-view-spec/blob/master/docs/docs/annotations.md

This example shows how to group residues using the 'group_id' field to create fewer, more complex labels. Residues with the same 'group_id' are grouped under a single label.

```cif
data_annotation
loop_
_labels.group_id
_labels.label_asym_id
_labels.label_seq_id
_labels.color
_labels.label
1 A 100 pink 'Substrate binding site'
1 A 150 pink 'Substrate binding site'
1 A 170 pink 'Substrate binding site'
2 A 200 blue 'Inhibitor binding site'
2 A 220 blue 'Inhibitor binding site'
. A 300 lime 'Glycosylation site'
. A 330 lime 'Glycosylation site'
```