jmbuhr / quarto-molstar Goto Github PK

View Code? Open in Web Editor NEW

40.0 3.0 4.0 8.1 MB

Shortcode to embed proteins and trajectories with Mol*

Home Page: https://jmbuhr.de/quarto-molstar/

License: MIT License

CSS 7.16% Lua 3.83% HTML 42.23% JavaScript 46.78%

quarto quarto-extension

quarto-molstar's Introduction

Molstar (Mol*) Extension for Quarto

This extension provides shortcodes for molstar in quarto. Molstar can display macro-molecules such as proteins as well as molcular dynamics trajectories in an interactive viewer. You can see it in action e.g. in the RCSB Protein Data Base: https://www.rcsb.org/, where it provides the 3d view for entries. Follow me, if you want this right in your quarto reports (html only).

Installing

quarto install extension jmbuhr/quarto-molstar

This will install the extension under the _extensions subdirectory. If you're using version control, you will want to check in this directory.

Using

Usage examples are in index.qmd, which you can see rendered locally and served with GitHub pages here: https://jmbuhr.de/quarto-molstar/

Likewise, the example rendered as a revealjs presentation (presentation.qmd) is served here: https://jmbuhr.de/quarto-molstar/presentation.html

Limitations

Self-contained htmls: Molstar viewers for local files are empty when the file is not served by a webserver such as quarto preview or GitHub pages. This means it will not display your molecule when you simply open the rendered html with a browser, even if you set the html to be self-contained. The reason for this is the Same-origin Policy, a security measure in web browsers. It and similar policies prevent that one document can access resources it is not supposed to access. For example, an html document you downloaded is not allowed to execute code that reads personal files on your computer. This also prevents it from loading your molecules from local paths.

For plain text formats in the mol-url shortcode, such as pdb and xyz, you can enable a custom option that circumvents this limitation by embedding them straight into the html as a string. Add molstar: embed to your yml frontmatter to use this.
Resources like local structures that have to be loaded need to be added manually via https://quarto.org/docs/reference/projects/core.html in order to be copied to the publish directory until support for automatic resource discovery (#7).
revealjs presentations now use iframes instead of a normal div to work around #1, which is why you might have to address those differently for custom styling if you plan to use the same source for html and revealjs output.

Update Mol* (extension developement)

The js and css files where downloaded from the molstar web viewer in order to be up to date but also self-contained and functional without an internet connection.

cd _extensions/molstar/assets
rm molstar.js
wget https://cdn.jsdelivr.net/npm/molstar@latest/build/viewer/molstar.js
rm molstar.css
wget https://cdn.jsdelivr.net/npm/molstar@latest/build/viewer/molstar.css

quarto-molstar's People

Contributors

Stargazers

Watchers

Forkers

kjelljorner bradyajohnston hankewiedanke zachcp

quarto-molstar's Issues

Pass more options to molstar viewer creation

e.g. #4 (comment)

Local files aren't moved with website building.

An issue I was running into while trying to get the snapshots working in #6 , was that when trialling it on a quarto blog, while the molstar.molj file was in the correct location with the original index.qmd document, upon actual rendering of the website with quarto render or quarto preview everything was copied to the docs folder, but the molstar.molj was left behind and thus broke the URL.

Is there a way to mark specific files inside of the Lua / Pandoc to be treated as assets by Quarto? I assume that would fix the problem. Similar to what is done with images and other assets already inside of Quarto.

Adding volume visualization

I actually found that there is a function exposed in app.ts for displaying surfaces. I used the following code and was able to get something. The loadVolumeFromUrl could probably be adapted in the same way as you do for the other ones.

test = html`<div id="test"></div>`
molstar.Viewer.create(test, {layoutIsExpanded: false, layoutShowControls: false}).then(viewer => {
viewer.loadStructureFromUrl("./traj.xyz", "xyz")
viewer.loadVolumeFromUrl(
    {url: './density.cube',
    format: 'cube',
    isBinary: false},
    [{type: "absolute",
     alpha: 1,
     value: 0.001, 
        }
        ]
    )
});

Resolution is not great, but it seems to work, and the visualization can be adjusted later in the viewer

Archive.zip

molrender and molar support

Hi,
Congratulations, great tool and it works nicely with quarto.
Do you think it would be possible to add molrender and molAR capabilities to this extension?
Thanks.

opening molstar with different type

hey quarto is there any way to render Mol* with different type 3D representation for example gaussian surface as default not as cartoon. in your given code viewer.loadStructureFromUrl("./www/traj.xyz", "xyz")

viewer initially only shows black screen in revealjs

Some viewers (not all) initially only show a black screen when embedded in a revealjs presentation.
The app is correctly displayed after one of the following:

resize the window
click e.g. the options or full-screen button (buttons are visible, just not the protein)
enter / exit revealjs full screen (press F)

When I used to embed molstar manually I would use iframes of an external html file, in which case the issue didn't seem to occur. So what is happening here?

Support for MolViewSpec output?

I recently came across the mol-view-spec repo and it seems like a great way to programatically setup more complicated views that can be distributed. How difficult do you think it would be to support this format in quarto-molstar?

quick styles are not contained to one viewer

Looks like with the addition of the example snapshot, which uses a quick style "Stylized", all other apps in the document use this style on startup as well. Changing the style in one app changes it for the other apps as well, as soon as they are hovered afterwards.

Is this a bug or a feature?

Revealjs MOLSTAR

Hey,
I love this plugin for quarto.

But I have following issue:
Molstar does not load any structure when rendering quarto to revealjs.

See below a minimal working example for html (working) and revealjs export:

---
title: "t"
subtitle: 't'
author: "t"
date: "2023/09/15"
to: html
---

{{< mol-rcsb 1f16 >}}

---
title: "t"
subtitle: 't'
author: "t"
date: "2023/09/15"
format:
    revealjs:
        theme: [serif,style.css]
        smaller: true
to: revealjs
---

{{< mol-rcsb 1f16 >}}

Maybe I am doing something wrong?
Thank you for your help :)

quarto version: 1.3.450
plugin: v0.1.2