Web-based software for visualization of molecular maps in 2D and 3D
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
ili adding tests Apr 14, 2016
img Updated studies list and README May 4, 2017
js new White-Blue colormap Jul 26, 2018
scripts adding tests Apr 14, 2016
tests Implemented tabs using bootstrap, made the whole layout looking good … Nov 10, 2016
.gitignore 1. Implemented file type extendable file type recognition framework; … Apr 17, 2017
.travis.yml somemore fixes May 12, 2016
LICENSE.md Fixed formatting error in LICENSE.md Feb 15, 2018
README.md Update README.md Mar 7, 2018
Studies.md Updated coral study link to enable textures May 7, 2018
chromext-background.js Converted `ili from app to chrome extension; several UI enhancements Jan 4, 2017
documentation.html.js Made HTML templates be loaded without require.js text plugin May 18, 2017
ili.js Made HTML templates be loaded without require.js text plugin May 18, 2017
init-ili.js Improvement of the previous commit May 17, 2017
layout.css Several fixes for issues when embedding `ili to other pages May 17, 2017
manifest.json Updated the version of Chrome extension to publish it on the web store May 5, 2017
setup.py fixing name May 5, 2016
template.html.js Made HTML templates be loaded without require.js text plugin May 18, 2017



`ili is a visualization app for 3D molecular cartography. For more information about the molecular cartography, please see our recent protocol paper Protsyuk et al. (2017) Nature Protocols.

`ili is being developed mainly by Alexandrov Team at EMBL Heidelberg (contact information) in collaboration with the Dorrestein Lab and the Knight Lab at UCSD.

  • Developers: Ivan Protsyuk, Sergey Ryazanov
  • External contributors:
    • Members of Knight lab: Antonio Gonzalez, Jamie Morton, Jose Navas, Yoshiki Vázquez Baeza
  • Principal investigator: Theodore Alexandrov

Table of contents

Hello bee

For a demonstration, open

       Screenshot of the human example

  • 3D bee example (data provided by Yi Zeng from the Dorrestein Lab, UCSD)

       Screenshot of the bee example

       Screenshot of the 3dmassomics example

Examples from real-life studies

On this page you can find examples of `ili being applied in research.


The best ways of running `ili are either from this website or as a Chrome extension.


`ili takes two files:

  • for 2D mapping: a PNG or JPG file to be used as the background image (example), and a mapping file with intensities and coordinates in CSV format (example)
  • for 3D mapping: a 3D model in STL format (example), and a mapping file with intensities and coordinates in CSV format (example)

To create a mapping file suitable for input, you need two pieces of information: coordinates of your samples on your picture/model and intensities of features you're going to visualize in `ili. Please find the instruction on how to create a CSV table with coordinates here. Rows of the result table correspond to samples. Once you have it, you can add your features as new columns. Finally, you need to save it as a CSV file, and it is ready to be viewed in `ili. Refer to the examples above to have an idea of the final look of the table.

How to use it?

One of the fundamental ideas behind the `ili interface is the simplicity of usage. Therefore, most operations can be performed with keyboard shortcuts.

Action Shortcut on Windows, Linux Shortcut on OS X Alternative
Open files Ctrl+O +O Drag and drop files to `ili window. Also, when you just launched `ili, you can press Open button at the center of the window.
Switch between molecular maps Ctrl+, Ctrl+ + , + Click on a name of an active map above a colorbar at the right-bottom corner of an app window and select another map with mouse.
Find a molecular map by its name Ctrl+F +F Click on a name of an active map above a colorbar at the right-bottom corner of an app window and start typing.
Save view as image Ctrl+S +S NA
Save cartographical snapshot Ctrl+E +E NA

Many other controls for adjusting visualization are available in the `ili sidebar. Three main sections there "2D", "3D" and "Mapping" correspond to settings affecting 2D/3D views and colormaps.

Mouse buttons can be used to adjust point of view on a model/picture.

Action Mouse button Views where available
Rotate model Move mouse holding its left button 3D
Move image Move mouse holding its left button 2D
Zoom Rotate mouse wheel 2D, 3D
Display spot name Click at a spot with left button 2D, 3D
Move model Move mouse holding its right button 3D
Enable/disable model auto-rotation Double-click 3D


You can find a list of ready-made examples in the "Examples" tab in the `ili sidebar. Click on any of them, and necessary files will be loaded to the app automatically.

3D models with texture

In addition to plain models in STL format, `ili also supports 3D models in OBJ format, which can be visualized with textures on top of them. As a prerequisite for that, textures must be saved as images in PNG or JPG format associated with a material definition file in MTL format. Thus, at least three files are needed to visualize a 3D model with texture in `ili: model in OBJ format, material definition file and a texture image. All these file types are compatible with other input files, e.g. mapping files or cartographical snapshots, and can be opened in `ili using regular actions, like drag&drop.

One can find a 3D model of a coral and texture for it here (courtesy of John Burns, University of Hawaii) as an example of appropriate input files for `ili.

Cartographical snapshots

`ili facilitates reproducible data analysis by providing the feature of cartographical snapshots: a complete copy of all visualization settings saved to a file. The file can be reused later or shared with other users, who, afterwards, will be able not only to recover the same view, but also use it as a starting point for further analysis.

The cartographical snapshot is a file in JSON format that can be opened in `ili using drag&drop along with corresponding files of 3D model/image and spatial mapping.

Permanent links to `ili visualization

It is possible to create permanent web-links to `ili visualizations, which can be shared with other people or included into publications, without explicit sharing of the input files. In order to do that, one needs to deposit all necessary input files (model/picture, mapping file and cartographical snapshot(s)) to a public data repository, which can be one of recognized resources in a specific field (e.g. MassIVE, MetaboLights, etc) or an ordinary FTP server. The only requirement to the storage is it should allow downloading files without any authorization. After all the files are uploaded to the storage, a permanent link to `ili visualization can be composed by chaining all links to the files into a single URL, which starts with the `ili address (https://ili.embl.de) followed by question mark and all file links separated by semicolon. Example: https://ili.embl.de/?ftp://massive.ucsd.edu/MSV000081081/updates/2017-05-15_mernst_9ac10437/peak/EHorrida_20160915_Model3_withroots.stl;ftp://massive.ucsd.edu/MSV000081081/updates/2017-05-15_mernst_9ac10437/peak/EHorrida_Model3_features.csv . The order of the files does not matter. Links to visualization of different features in the same dataset or different visualization settings can be created by using different cartographical snapshot files. More examples can be found in the list of studies, where `ili was used.

Any questions?

Feel free to leave your questions and suggestions as issues in this repository or at the "Support" section on the `ili page at Google web store.

How to stay updated

Please sign up to the mailing list by sending an email to ili-toolbox+subscribe@googlegroups.com


  • Why is it called `ili? `ili in Hawaiian means skin and, among others, surface, area, or cover.
  • How to record videos or screencasts in `ili? Please use a third-party software, for example ScreenCastify plugin to Chrome
  • How can I cite `ili in my scientific publication? Please cite Protsyuk et al. (2017) Nature Protocols.


The content of this project is licensed under the Apache 2.0 licence, see the license file.


This project is funded from the European projects 3D-MASSOMICS (FP7 HEALTH program, grant agreement no. 305259), METASPACE (Horizon2020 program, grant agreement no. 634402) and from the internal funds of the European Molecular Biology Laboratory.