Question about opening .vsi files in QuPath (0.1.2)

[Martin Roth]

Hi,
I just discovered QuPath when looking for a convenient way to open .vsi files on an GNU/Linux system. Great success! However, I am completely new to digital microscopy and don't  know anything about the different tools, programs or file formats.
My goal is to be able to open and view a bunch of .vsi files, obtained from my university, on my Arch Linux installation. I've come across an issue, where only the smallest magnification is shown when open said files (zooming in doesn't work). When opening the sample .vsi file found at http://biop.epfl.ch/TOOL_VSI_Reader.html, zooming simply works fine. Both the sample file and the other files have one .vsi file (~ 2 Mib) and a subdirectory with a similar file name (~ 250-300 Mib in size). I think I read that there are different versions of the .vsi file format and that the plugin that QuPath uses to open them might not have full support for all. Is this correct? Is there something that I have forgotten in order to make QuPath open all the .vsi files that I have?

PS.
QuPath is really neat!

[micros...@gmail.com]

I am not familiar with .vsi, but have you tried the following?

https://github.com/qupath/qupath-bioformats-extension

There were some images I have had trouble opening that worked better with that installed.  Another thing to check is whether the naming scheme is consistent within the associated files.

I was completely new to digital microscopy just six months ago as well!  I strongly recommend Peter's handbook on images.  While it does focus on IF, plenty of it is applicable to brightfield as well, and I found if very useful since my background was completely lacking any microscopy experience when I started.

https://petebankhead.gitbooks.io/imagej-intro/content/

[Martin Roth]

It is some proprietary format developed by Olympus. I found this: https://www.openmicroscopy.org/site/support/bio-formats5.3/formats/cellsens-vsi.html
Bioformats gives partial support for the .vsi file format it seems, but not fully (for the aforementioned reason). I did install the qupatch-bioformats-extension and bioformats_package extensions. Otherwise I suppose the files wouldn't have loaded at all.

Good point. I tried renaming the subfolders associated with the .vsi files but it doesn't seem to make a difference. I will play around with that a little further.
Maybe better support will be added in the future.

And thanks for the book tip. I will definitely check it out. :)

[Pete]

Hi,

I also don't have much direct experience of VSI images, although I'm slowly learning more... mostly from people who have been trying them out in QuPath, and letting me know a bit about what works and what doesn’t.

As far as I’m aware, the ‘VSI Reader Actionbar' from BIOP uses Bio-Formats as well - so if you can open the image there, it should work in QuPath too, and vice versa.  Should…. but doesn’t always.

There are a few issues that I know about with handling VSI in QuPath:

- When you open the image directly, QuPath usually opens the label first - not the actual whole slide image that you want.  To open the whole slide (with zooming in/out) you need to go into the 'Image' tab on the left of the screen, click on 'Image list' and double-click on the image you want.  This is a bit inconvenient…. but it should work.

This happens because QuPath isn’t recognizing properly that the macro and label images should go into the ‘Associated image’ list, and it is adding them to the ‘Image list’ instead.

The ‘Image list’ is meant to be used whenever the same file can contain lots of different images of similar importance.  This happens with some microscopy file formats supported by Bio-Formats, where one file often contains lots of images.  All of these might be required for analysis.

The ‘Associated images’ are meant to be the label or macro image associated with a single slide.  They are accessible when the image they are associated with is opened, but otherwise they are hidden.  They generally aren’t needed for analysis.

So, unfortunately, it appears that with VSI files QuPath puts the macro and label images into the image list and, even more unfortunately, opens one of them by default instead of the whole slide image that you probably want.  This is why it looks like you can’t zoom in and the image is very low resolution.

However, the good news is that this is only because the wrong image has been opened.  The whole slide image is still there - it just takes a few extra clicks to find and open it.

- When you add a VSI image to a project, QuPath tends to add the macro image and label to the project as well.  This is for the same reason as described above.  If you want to remove these from your project, you need to go to the 'Project' tab (again on the left of the screen), right-click on what you don't want, and click 'Remove image'.  This is also a bit inconvenient…. but doesn’t stop things working.

Note: you could also script the removal of these unwanted images if you have a lot, or - probably more easily - open your .qpproj file in a text editor and remove them there.

- When adding images to a project, the names aren’t very informative.  This happens because QuPath shows the name stored in the file, not the name of the file itself.  You can try right-clicking on the image name under the ‘Project’ panel and renaming from there.  However, I haven’t used this feature enough myself to be confident that the old name doesn’t reappear from time to time in other parts of the user interface.

- Sometimes the full-resolution image can’t be opened at all, and an error message pops up (generally ‘Null pointer exception’).  This happens because the VSI file contains an ‘image pyramid’ and the Bio-Formats extension for QuPath is very strict when it calculates the sizes that each image should have within that pyramid.  Sometimes the VSI images don’t meet QuPath’s strict criteria, and QuPath is a bit brutal in how it deals with this situation.  It just skips those images in the pyramid, with the end result that it can’t be used at all.

This isn’t really easy to deal with for now from a user perspective, since it requires the QuPath Bio-Formats extension to be updated to relax the pyramid criteria.  I haven’t had an opportunity to make a fix for this available yet, although I hope to be able to do so in the future.  However, as far as I’m aware it only affects a subset of VSI files.  I’m not sure how widespread the problem is, and I’d be interested to know if you encounter it as well.

---

Hopefully this gives enough information to make more progress in using QuPath for your VSI images.  From the description in the original post, I think the best thing is to create a new QuPath project and add several VSI files to it.  You might need to rename them too.

Since I don’t have any VSI images of my own, I am dependent on others to know where the troubles lie… so if you find any more issues, or want to discuss workarounds for any of the existing ones, just let me know.

Pete