tissuumaps / tissuumapscore

TissUUmaps is a browser-based tool for fast visualization and exploration of millions of data points overlaying a tissue sample. TissUUmaps can be used as a web service or locally in your computer, and allows users to share regions of interest and local statistics.

TissUUmaps - UU is for Uppsala University ;)

⚠️ This repository hosts the core javascript / html code of the TissUUmaps application. For more information on installation, usage and demo of the TissUUmaps application, go to the TissUUmaps web page or the TissUUmaps GitHub.

The information below are for TissUUmaps 1.0 and shouldn't be needed for most users.

TissUUmaps is a lightweight viewer that uses basic web tools to visualize gene expression data or any kind of point data on top of whole slide images.

You can easily use it locally, or remotely creating a server.

TissUUmaps tries to keep it minimal so the setup doesn't become complicated. You can use more advanced libraries if you want but we try to make it simple, just HTML, JavaScript and CSS.

Images are display with OpenSeadragon, point data is displayed by D3, and everything else is done by TissUUmaps.

How to start

Since we don't want to use external servers to serve our images, let's convert them to an open pyramidal format where we can see individual tiles and OpenSeadragon can easily load the correct tile for you. It is called Deep Zoom Image. OpenSeadragon can import other formats, for more information go here Supported Tile Sources

This image sumarizes the process of converting a whole slide image into a DZI. As long as OpenSlide can open the format, then the program VIPS will be able to convert it to a DZI.

VIPS is a super powerful image processing library. It offers a specific command to convert an image to DZI. For example:

vips dzsave slide.ndpi --tile-size=254 --overlap=1 --depth onepixel --suffix .jpg[Q=90] mySlide

Info: More on VIPS dzsave here How does DZI work? Interesting blog post here

Enter TissUUmaps

Once you have your tiled DZ image in the computer where you will use TissUUmaps, you can clone this repository. In the HTML file index.html you just need to tell TissUUmaps where your image is. To do this, check the last script tag in the HTML and change the value of tmapp.fixed_file

<script>

    document.getElementById("project_title").innerText = "Project title";
    $(document).ready(function () {
        tmapp.fixed_file = "path/to/mySlide.dzi";
        tmapp.registerActions();
        tmapp.init();
    });
</script>

Your own local web!

For safety reasons, your browser and your computer need to know where data comes from. For this purpose, you need to set up your own local web server. There are many different choices. We can recommend for example, the web server addon from Chrome, or if you have Apache you can use it, or node.js. More info on how to allow your browser to use local files in our TissUUmaps website https://tissuumaps.research.it.uu.se/howto.html#section-setup and in the videos below.

All set!

Once you have your pyramidal image and your HTML set then you can open it in any browser and see TissUUmaps displaying your slide. You can use the right panel to load point data and explore.

Javascript documentation

You can find the javascript documentation generated using JSDoc 3.6.7 here.

tissuumapscore's Issues

GeoJSON Support

Hi all,

Is there currently a way to convert GeoJSON (https://geojson.org/) polygons to those types that are supported by TissUUmaps?

I am not exactly sure what the input formatting is for your polygon csv type

Cross-shaped markers are not displayed

Hej,

I have noticed that when selecting "Cross" as marker shape, the markers are not displayed. When changing to any other shape they are drawn correctly. I am using Tissuumaps with Google Chrome.

Update view is slow on big datasets, even if we don't change any marker settings

It would be nice to check what needs to be reuploaded to the GPU when updating the view.

Exporting region problem

When I try to export the csv containg the data of a region I get an error in the browser

Uncaught InternalError: allocation size overflow
    pointsInRegionsToCSV https://tissuumaps.research.it.uu.se/video/js/utils/regionUtils.js:1123
    registerActions https://tissuumaps.research.it.uu.se/video/js/tmapp.js:31

It's very few points in space but it has maybe some 100 features associated to it.

I reduced the features to maybe 20 and then it managed to save a csv after a long time and it contained incorrect information. For example, I have a global ID that is an integer, and it was saved as a float and the number was lost, it was a column full of 0.0.

One field that caused trouble (I dont know why) is that I have a string in it, containing a stringified json. And when that filed is present, even thought it is a string, the csv sometimes exported, sometimes, not.

And lastly sometimes the export contains a weird new column that the original data doesn't have. It looks like the response type of an http request it starts with:
data:text/csv;base64 and then a super long hexstring that mightbe the csv itself, so theres a csv within the csv. Or something like that

Exporting screen capture problem

When I try to take a screen capture, the paths don't match the size of the image.

Ex:

I didn't explore this issue further, I just tried the plugin for clustering the points and exported from the menu on TissUUmaps GUI (v3.0.10.1).

Running plugins in Tissuumaps server mode

Hi!

This is not really an issue, but rather a question. Where can I find instructions on how to load plugins into the server-based web viewer?
I really like the "FeatureSpace" plugin and would like to use it on a Tissuemaps instance running on a server instead of locally. Please let me know if this is possible.

Thanks
Mena

Loading consecutive CSV files with no background image makes incorrect viewer dimensions

Hi,
I am running tissuMaps on windows, I am only using a cell coordinates and marker file. It was working smoothly but when I tried with a file generated from a whole slide image, was not able to display all the cells even after zooming out to 100%.

plot displaying all the cells in R

Cells displayed in tissuMaps

Also, even when all the cells are displayed, when zooming, cells on left or right are masked as if zooming was only possible in the center of the plot.

Region interface and js console

In the view of the regions, when a name is undefined maybe it's better just to not show the column instead of showing a column with many "undefined" printed.

Also there are too many console.log calls in regionutils:1004 and 1014, please don't include them in released versions it's only for debugging.

Drawing regions seem to bugged

Hello!

When serving locally from a deep zoom image the example.html
the region drawing seems to have some issues.

I have changed the script in the bottom part to

<script>

    document.getElementById("project_title").innerText = "Project title";
    // ----------
    $(document).ready(function () {

        tmapp.fixed_file = "dzi_images/dzi_test.dzi";
        tmapp.slideFilename = "dzi_test"
	    tmapp.layers =[
            {
                name:"Density",
                tileSource:"dzi_images/dzi_test_dens.dzi"}, 
            {
                name: "Class", 
                tileSource:"dzi_images/dzi_test_clf.dzi"
            }
        ];
        
        tmapp.registerActions();
        tmapp.init();
    });

</script>

And cannot draw any regions. Is there something I have missed?

Is it possible to save in a project all the parameters used (colors, shapes and grouping variables)?

Hi,
I am loading only csv files with X and Y positions in addition to marker intensities and other variables. It would be nice if one can save all the visualization parameters used for each sample to reload them later on. Is that currently possible?

Exporting image in web tool.

Ignore this. It was a problem on my end.