Working with Virtual Slide Images (.VSI) and the Olympus Vs120 Automated Slide Scanner

Do you have one of these?

Olympus Vs120 Slide Scanner

So, you have a Vs120 Slide Scanner and you have terabytes of scanned images all saved as .vsi files. Now what? Right?

First lets quickly go over the Software that Olympus offers.

VS-AWS

This is the acquisition software which should be running on the terminal which controls the scanner. This software is able to view and modify scanned images, but it is not desirable to use the same terminal for both acquisition and image processing.

VS-DESKTOP

This is the image processing software offered by Olympus. This software is generally purchased in conjunction with the scanner itself. Your biophotonics department will likely have this software available to you on one of their multi-use terminals.

OlyVIA

This is the free viewer software available here from Olympus. This software is the best method for viewing your .vsi files. It is incapable, however, of modifying files in any way. You do not have access to any of the image processing tools from VS-Desktop.

Why does any of this matter?

Let me explain the situation I found myself in so that you have an idea of why I wrote this post.

As a research assistant working for a Structural Neuroscience post doc, I was doing fluorescent immunohistochemical staining of fixed tissue sections. These tissue sections were arranged on normal glass slides and scanned using the Vs120 slide scanner. Each slide contained approximately twenty sections, and produced twenty .vsi files at 10x magnification. 

Having scanned around four hundred slides I found myself wondering how to approach data collection on 8000+ files! My post doc needed quantitative data for labeling in specific brain regions, which meant that I would need to match each image to an atlas.

I knew that alignment software was available (a subject that deserves its own post entirely), and I knew that it should not be difficult to transform an atlas image to each section. Just open both files in some editing software, make sure they were the same size, edge detection on the tissue, transform atlas...

Easy right?

Wrong...

How the heck am I supposed to get my .vsi files into a format I can use?

There is the real question this post addresses.

The first thing I tried was using the Olympus VS-Desktop software. After all, it was designed by the same people that made this slide scanner designed to scan a hundred slides at a time. They must have a great way to convert all the numerous and huge data files into something I can take anywhere: .tiff, .btiff, ome-tiff, literally anything besides vsi.

The VS-Desktop software can convert vsi to tiff, but you can only do one image at a time. ONE AT A TIME! Not a big deal if they convert really quickly right? Turns out that converting a single section took just about 15 minutes.

That's right... just converting my images to a usable format was going to take me 2000 hours of point click wait... 

point click wait...  eight thousand times...

point click wait... 120,000 minutes

point click wait... 2000 hours

point click wait... 83.33 days

point click wait... That's almost three months if I don't take any breaks...

point click wait... Maybe I should have gone to medical school...

point click wait...

How "point click wait" works

If you have only a few files, this method is admittedly the easiest and the best.

1. Open your .vsi file in VS-Desktop
2. run EFI processing if you have multiple Z-planes
3. Save As... some new file type

For me the EFI processing was the rate limiting step. I had 3-7 focal planes depending on the sample. In the future I would recommend using as few Z planes as possible to capture the data you need.

It is far easier to re-scan a single sample with more focal planes than it is to re-scan everything with fewer focal planes.

How I eventually worked around the problem

After a few searches and talking to some very knowledgeable people. I found out that the Fiji distribution of ImageJ comes with the ability to open .vsi files via the Bio-Formats import utility.

This utility is not the most efficient thing I have ever used.

After some serious effort I found that I could open my files with the following command.

run("Bio-Formats Importer", "open=["~/filepath/yourdata.vsi"] autoscale color_mode=Custom specify_range split_channels view=Hyperstack stack_order=XYCZT series_1 c_begin_1=1 c_end_1=3 c_step_1=1 z_begin_1=zplane z_end_1=zplane z_step_1=0 series_0_channel_0_red=0 series_0_channel_0_green=0 series_0_channel_0_blue=255 series_0_channel_1_red=0 series_0_channel_1_green=255 series_0_channel_1_blue=0 series_0_channel_2_red=255 series_0_channel_2_green=0 series_0_channel_2_blue=0")

This is of course just a code version of the actual plugin. You can set all these flags in the GUI by running the BioFormats importer in the gui.

For me, the GUI importer would be just as slow as the VS-Desktop method. The point here is that Fiji allows the user to write a macro script to automate the conversion process.

So whats the catch? Well the BioFormats importer is not great at a few things.

• My code only imports a single Z-plane. This means that you have to pick a single Z that you think would be best for the entire dataset. This is not always ideal.
• The autoscale function has a very difficult time adjusting the contrast histogram in a way that displays faint data. 
• The counterstained layers show up beautifully since they have a very strong signal to noise ratio. 
• The GFP/dsRed data is less impressive however. If any artifacts appear in the channel, they generally drown out the sample signal. Likewise, if there is no signal you will have extremely bright autofluorescence.
• This is a problem that I have not fully solved. Essentially I am manually adjusting the contrast on individual sections as I need to work with them. This is the case in OlyVia as well. I generally have to adjust histograms as I count cell bodies.
• Fiji is incapable of exporting .btiff files.
• This has been an issue for several years and has not been addressed. The software is designed to automatically detect a large file size, but seems incapable of writing the headers correctly. This was only an issue for me when another research assistant started doing 3d reconstructions of tissue in Imaris which wanted .btiff files.

With those caveats out of the way, I wrote a macro script that: recursively scans a directory, converts each .vsi to a .tiff and a .jpg, saves the files in the original directory of the .vsi, and moves on to the next file.

My files are saved in a very specific format coming from the scanner I get:

~/scanner saves to this directory/Sample Name_1of4_sample info_scan area counter/Sample Name_1of4_sample info_counter.vsi

Look carefully at this. I am creating a subdirectory for each ROI I scan.

Let's assume that I scan a single slide with 20 sections. I should end up with 20 new folders from the slide scanner. Each one contains a single vsi file and the associated data file or folder depending on the image size.

The image data is then manually organized on the storage server.

• File Server
• My Scans
• Sample 1
• section1
• section1.vsi
• section 2
• section2.vsi
• Sample 2
• section1
• section1.vsi
• section2
• section2.vsi
• Sample 3
• (etc.)

As you can see, each file is isolated from the others. This is perfect for my recursive code because it will save each .tiff alongside the original .vsi so that we get something like:

• File Server
• My Scans
• Sample 1
• section1
• section1.vsi
• section1.jpg
• section1.tiff
• section 2
• section2.vsi
• section2.jpg
• section2.tiff
• Sample 2
• section1
• section1.vsi
• section1.jpg
• section1.tiff
• section2
• section2.vsi
• section2.jpg
• section2.tiff
• Sample 3
• (etc.)

Yay! Now I have all my files in formats I can use easily and quickly in other software.

The .tiff files maintain the composite layer information, meaning that you can break each image back into multiple channels for adjustments. The jpg files however are just for quick previews of the files. I was tired of waiting 30 seconds or a minute for a tiff or a vsi to load to a viewer.

Now, onto the code!

The code I have written, I wrote for myself...

That means it won't work perfectly for everyone. I have tried to comment on everything the code does, so it shouldn't be very tough to adjust the commands to make it work for you.

The macro code is available on Github and I continue to update the code there as I make improvements. The github is probably in .imj format which is just the ImageJ macro language file extension. Whether it is .imj or .txt, fiji should still recognize the code and make it work.

If you have trouble or questions please feel free to get a hold of me via comments or email. My lab collects a great deal of fluorescent image data, so I will be continuing to work on this stuff for a while. Likewise, if you have a method for doing image registration and atlas transformation that can be adapted for me please let me know! I'm a biologist, not a computer scientist haha! Writing all my own code from scratch is hard!

Thanks everyone, and I hope this helps a little!