litemol
v2.4.2
Published
A library/plugin for handling 3D structural molecular data (not only) in the browser.
Downloads
720
Maintainers
Readme
What is LiteMol
LiteMol is a library/plugin for handling 3D structural molecular data (not only) in the browser. It is written in TypeScript (and compiled to JavaScript). LiteMol features include, but are not limited to, displaying 3D coordinates of molecules and density maps.
You can see LiteMol in action here.
The program is being developed by David Sehnal from the CEITEC/Masaryk University in Brno, Czech Republic in collaboration (especially with Mandar Deshpande) with PDBe in Hinxton, Cambridge, UK.
Read more about LiteMol in Nature Methods.
Table of Contents
- Getting Started
- Project Structure Overview
- Building
- License
- Support
- Contributing
- Releases and Roadmap
- Citing
- FAQ
Getting Started
This repository provides the source code for the LiteMol molecular visualizer. Several examples of usage are also provided. It is recommended to use TypeScript for building apps based on LiteMol (or any other non-trivial JavaScript app for that matter), because you will get code completion and type checking.
- An initial walkthrough for how to go about including LiteMol in your web pages can be found in the FAQ section and in the SimpleController example.
- Auto-generated source code documentation is available here.
- If you are interested in using LiteMol for simple visualization and do not need any special functionality, you can use the PDB Component Library that provides an Angular wrapper for LiteMol.
- A walkthrough for integrating LiteMol is available here.
- For basic information about extending LiteMol see the extending document.
- For feature overview and usage of the
Viewer
app please refer to our wiki.
Project Structure Overview
The LiteMol library code is structured into four modules:
Core
- parsing, basic data representationVisualization
- wrapper around WebGL + geometryBootstrap
- higher level wrapper around Core and VisualizationPlugin
- React based UI
Auto-generated source code documentation is available here.
Additionally, the LiteMol Viewer application is available:
Viewer
- Host for plugin, integration with the PDBe services (electron density, validation, etc.) and CoordinateServer
Examples
See the Examples folder.
Building
Install Node.js (tested on version 8).
LiteMol is written in TypeScript and needs to be compiled to JavaScript before use. To build it, use
npm install -g gulp
npm install
gulp
On Windows, it might be required to install the package windows-build-tools
before the npm intall
command:
npm install windows-build-tools -g
Any subsequent full LiteMol builds can be done using just the command
gulp
To build the minified version of the plugin and the stylesheets, use
gulp
gulp Dist-min
This will create the files dist/js/LiteMol-*.min.js
and dist/css/LiteMol-plugin*.min.css
.
When embedding the plugin in your pages, do not forget to include the dist/css
and dist/fonts
folders with
the required style sheets and fonts.
Modifying Examples
Go to the Examples folder to learn how to modify individual examples.
License
This project is licensed under the Apache 2.0 license. See the LICENSE
file for more info.
Support
If you have any questions or feature requests, do not hesitate to email the author, use the GitHub forum, or the LiteMol mailing list.
Makes sure to check out the documentation and examples.
Contributing
We would like to know about your use cases of the program, bug reports, and feature requests.
Our plan is to make a stable LiteMol Core Library (this repository) and allow users to contribute by writing extensions handling their specific use cases of the application. The extension support is currently under development (see the Roadmap below).
Releases and Roadmap
LiteMol is still in active development. All things in this section are a subject to change (especially based on user feedback). Currently, our priority is to improve these things:
- Creating documentation and adding more usage examples.
- Fixing bugs in the code.
Releases
The latest stable release of LiteMol is the version 2.
Migration summary can be found here.
Short term goals
These features are planned to be introduced in version 3:
Core features
- Improving extension support:
- Streamline the process of extension creation.
- Support for dynamic extension loading.
- Support for saving and restoring the state of the application.
- Improved internal data representation of molecules.
Long term goals
These features are on our TODO list. Feature requests from users are always welcome.
Core features
- Visualization of molecular dynamics.
- Animation support:
- Animating camera.
- Animating individual parts of the scene.
- Support for additional input formats (e.g. MOL2, but mostly driven by user demand).
Non-core features
- Additional display modes.
- Basic support for PyMOL-like scripting.
- Collaborative features:
- Annotation.
- Sharing of a single app session between multiple users.
Citing
Sehnal,D., Deshpande,M., Vařeková,R.S., Mir,S., Berka,K., Midlik,A., Pravda,L., Velankar,S. and Koča,J. (2017) LiteMol suite: interactive web-based visualization of large-scale macromolecular structure data. Nat. Methods, 14, 1121–1122, doi:10.1038/nmeth.4499.
FAQ
How do I include LiteMol in my page?
You can include the plugin as shown in the src/Viewer
folder. For a simple use case,
please check the SimpleController
examples. For further examples, please refer to examples
directory.
Alternatively, you can use the Angular LiteMol wrapper from the PDB Component Library.
What are the simplest steps to load a molecule in LiteMol?
Start by downloading the code:
git clone https://github.com/dsehnal/LiteMol.git
or download it as ZIP. No building is required, only the
dist
folder in the archive is needed.From
dist
folder, copy the folderscss
,fonts
, and the filejs/LiteMol-plugin.js
(orjs/LiteMol-plugin.min.js
for production).Include the CSS and JavaScript in your page:
<link rel="stylesheet" href="css/LiteMol-plugin.css" type="text/css" /> <script src="js/LiteMol-plugin.js"></script>
You can include
css/LiteMol-plugin-light.css
orcss/LiteMol-plugin-blue.css
for different color schemes.For production, include
LiteMol-plugin.min.js
andcss/LiteMol-plugin.min.css
instead.Create a target for the plugin:
<div id="litemol" style="width: 640px; height: 480px; margin-top: 200px; position: relative"></div>
Create the plugin instance:
var plugin = LiteMol.Plugin.create({ target: '#litemol' });
Load the molecule:
plugin.loadMolecule({ id: '1tqn', url: 'https://www.ebi.ac.uk/pdbe/static/entry/1tqn_updated.cif', format: 'cif' // default });
To load a file in the PDB format, use
url: 'https://www.ebi.ac.uk/pdbe/entry-files/download/pdb1tqn.ent', format: 'pdb'
If you decide to use a different URL and it does not work, make sure that the server in question supports cross-origin requests.
Please check the SimpleController example for more information.
What external dependencies do I need to include LiteMol?
LiteMol does not require any external dependencies.
How do I change the color scheme of the plugin?
LiteMol is available with 3 colors schemes: Dark (default), Light, and Blue. The palette can be changed by including a different css file from the dist/css
folder.
If this is not enough for your needs, you can easily customize the color palette. Add your palette to src/Plugin/Skin/colors
using an existing palette as a template and
create new src/Plugin/Skin/LiteMol-plugin-MYTHEME.scss
that refences your new colors. Edit the function CSS
in gulpfile.js
to include the -MYTHEME
affix and rebuild
LiteMol. Your theme will then appear in dist/css
.
Can I contribute to LiteMol?
Please refer to the Contributing section of this file.
How do I subscribe to the mailing list?
Here.