BIOIMAGING AND VSI READER - UNIGE · BIOIMAGING AND OPTICS PLATFORM EPFL–SV–PTBIOP INSTALLATION: DEPENDENCIES The VSI reader is written in the ImageJ macro language and makes

BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

VSI READER

EPFL - SV

BIOIMAGING & OPTICS PLATFORM (PT-BIOP)

O. Burri, R. Guiet

http://biop.epfl.ch

BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

GOAL

The Olympus VS120-SL

microscope is imaging

entire (histological) slides

in bright-field and

fluorescence. This is done

by automatically acquiring

and assembling smaller

tile-regions.

We needed a simple and

efficient way to open and

process the acquired data

in ImageJ.

2 PTBIOP - VSI Reader ActionBar v2.0 2013

BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

CURRENT LIMITATIONS

(IMAGEJ / FIJI)

The .VSI format is partially

supported by the LOCI Bio-

Formats Plugins.

• Problem: Java has an image

size limit of 48’000x48’000

pixels per image. Most scans

performed with a 40x objective

are over 100’000 pixels in each

direction.

• Solution: “Crop on import”

(Implemented by Bio-Formats)


The limitation here is that one does not know in advance where to crop.

? But what settings to use?

BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

INSTALLATION: DEPENDENCIES

The VSI reader is written in the ImageJ macro language and makes use of the ActionBar Plugin as well as LOCI Bioformats for opening the dataset.

LOCI Bioformats is already included in any release of Fiji, but should you have any problems, the following procedure works quite well.

1. Go to the http://loci.wisc.edu/bio-formats/downloads page and get the latest loci-tools.jar file (Stable Build).

2. Go to your Fiji Directory and under “plugins” and “jars”, delete the following files if you find them (Or do it through the updater):

• bio-formats.jar, scifio.jar, loci-common.jar, ome-xml.jar, loci_plugins.jar, metakit.jar, ome-io.jar, ome_plugins.jar, loci-testing-framework.jar, jai_imageio.jar, mdbtools-java.jar, poi-loci.jar, lwf-stubs.jar.

• These files might have «SNAPSHOT» appended to them.

3. Install the stable release of LOCI Tools (loci-tools.jar)


http://loci.wisc.edu/bio-formats/downloads




BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

INSTALLATION: DEPENDENCIES

Installing ActionBar

1. Go to http://imagejdocu.tudor.lu/doku.php?id=plugin:utilities:action_bar:start#downloads

2. Unzip the file and place its contents into the plugins directory of ImageJ/Fiji

3. Dowload the VSI Reader from http://biop.epfl.ch/INFO_completed_projects.html#vsi-reader

4. Unzip the file inside the ActionBar Folder in your Fiji plugins directory.

5. The BIOP_VSI_Reader.ijm and the ‘icons’ folder should be in: %FIJI FOLDER%/plugins/ActionBar/Shared Bars

6. You’ll find the reader in “Fiji -> Plugins->ActionBar->Shared Bars”


The action_bar.jar can be inside the folder

BIOP_VSI_Reader.ijm and the ‘icons’ folder should be in: %FIJI FOLDER%/plugins/ActionBar/Shared Bars

http://imagejdocu.tudor.lu/doku.php?id=plugin:utilities:action_bar:start



http://biop.epfl.ch/INFO_completed_projects.html






BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

INSTALLATION: FIJI UPDATE SITE

We've also setup a Fiji Update Site with some of our macros. To configure, read Fiji's Wiki on Update Sites

1. Go to the Fiji Updater, Select 'Advanced Mode', then 'Manage Update Sites'

2. Under name: Enter 'PTBIOP Update Site'

3. Under url: http://biop.epfl.ch/Fiji-Update

4. The rest is just as in Fiji's tutorial


The VSI Reader will be fully

functional but will be missing the

icons which cannot be managed

in a way that is compatible with

both ActionBar and the Fiji

Update site.

To get the icons, you can get

them from our website. Unzip the

file in the plugins directory.

http://fiji.sc/wiki/index.php/How_to_follow_a_3rd_party_update_site

http://fiji.sc/wiki/index.php/How_to_follow_a_3rd_party_update_site

http://biop.epfl.ch/Fiji-Update



http://biop/INFO_completed_projects.html





BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

ACTIONBAR: LOADING

SELECTIONS

The Action Bar proposed here makes use of

the thumbnails already present in the .VSI

file. It is used to crop the desired region, as

well as to simplify other common tasks.


Series #x: Your Data

Extra things, label, 2X overview, mask, etc…

BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

ACTIONBAR: LOADING

SELECTIONS

The Action Bar proposed here makes use of

the thumbnails already present in the .VSI

file. It is used to crop the desired region, as

well as to simplify other common tasks.


BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

ACTIONBAR DESCRIPTION


Loads current thumbnail selection

Interactive Navigation

Set image calibration Add scalebar (Dialog)

Convert to RGB

Save as TIFF (Dialog)

Add selection to Manager

Remove selection from Manager Clear ROI Manager

Load custom macro

Import all ROIs in ROI

Manager and eventually

apply macro

Save and Load Parameters Save and Load ROIs

Parameters log window. (Do not close)

Downsample selection

Load .VSI File

BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

ACTIONBAR: DOWNSAMPLING

LARGE IMAGES

Very large selections can be downsized to a

size that can be handled by ImageJ: It will

break the section down into small tiles,

resize them and then assemble the final

image.


BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

ACTIONBAR: INTERACTIVE

NAVIGATION

By clicking in the thumbnail, it loads the

current area surrounding the mouse to a

new window in full size. Press ALT to stop.

Note that you can load selections of

arbitrary sizes. The only limit is the time

you’re willing to wait for each preview to

load.


BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

ACTIONBAR: SET CALIBRATION

As Bio-Formats cannot access the metadata from the .VSI file directly, we added a button that calculates the pixel size based on the specifications of our system (Objectives and Cameras). Adjust if needed in the code.


This is required if you wish to place a scalebar.

BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

ACTIONBAR: SET SCALE

Calls the Built-in «Set Scale»

Plugin from ImageJ/Fiji


You must calibrate your image before using the scalebar.

BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

ACTIONBAR: CONVERT TO RGB


Useful for flattening overlays and saving as

JPG for powerpoint presentations. Of little

consequence for brightfield images.

Fluorescent images should be kept as

hyperstacks.

BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

ACTIONBAR: ROIS


Saves, removes and manages ROIs.

Must be used when launching «Process ROIs» as the naming in the ROI Manager is important.

BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

ACTIONBAR: LOAD MACRO


Loads a macro path. This macro will be

called for each ROI that gets loaded when

«Process ROIs» is used.

BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

ACTIONBAR: PROCESS ROIS


Loads each ROI and eventually calls a macro. Then proceeds to save it as a TIFF in a sub-folder named after the original .VSI file. (Macro example at end of presentation)

BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

NOTES / BUGS

Care should be taken when renaming the .VSI file. The folder should be renamed as well without forgetting the underscores (‘_’) before and after the name.

This macro works best when the .VSI file is on a fast HDD and not on a network or USB key.

Mac Users: At time of testing, MacOSX PCs were unable to use this ActionBar, a bug linked to the BioFormats plugin. The BioFormats plugin being updated often, this will probably be resolved in the near future.

Benchmark tests are available in the following slides.


BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

BENCHMARKS

We tested the opening time for images of varying

sizes on different machines which helped us finding

the optimal image size for tiling (using the down-

sampling option), as well as providing a reference for

users concerning the speed of various operations.


Tests performed on the following machines

PC

-1

PC

-2

PC

-3

BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

BENCHMARKS

Average times and standard deviations for opening differently sized images:

(4 positions, 5 repeats, 8 sizes)


Image Size

256 359.5 +/- 61.6 335.3 +/- 78.6 719.3 +/- 91.2

500 463.4 +/- 12.4 535.8 +/- 388.4 904.1 +/- 32.5

1024 756.5 +/- 86.3 937.3 +/- 592.0 1381.9 +/- 111.1

2048 1828.9 +/- 145.9 2295.3 +/- 867.0 3048.3 +/- 209.9

4096 5775.6 +/- 263.8 7013.2 +/- 864.0 8985.5 +/- 368.6

8192 19141.2 +/- 383.1 19967.6 +/- 1803.9 30265.8 +/- 564.4

16384 61086.0 +/- 26478.6 108301.3 +/- 47733.1 115462.6 +/- 50766.7

32768 82364.5 +/- 20497.4 103495.2 +/- 49667.9 140665.1 +/- 5402.8

average (ms) +/- sd average (ms) +/- sd average (ms) +/- sd

PC-1 PC-2 PC-3Image Size ref average (ms)/ ref average (ms)/ ref

256 1.0 0.9 2.0

500 1.0 1.2 2.0

1024 1.0 1.2 1.8

2048 1.0 1.3 1.7

4096 1.0 1.2 1.6

8192 1.0 1.0 1.6

16384 1.0 1.8 1.9

32768 1.0 1.3 1.7

PC-2 PC-3PC-1

It takes about 6-8s to open a 4096x4096 image using LOCI-BioFormats.

It is about twice as slow on a core2 than on an i7 or

Xeon processor. Expect worse performance on

32-bit machines. These tests probably depend on how your

Java Virtual Machine was configured.

PC

-3

PC

-2 P

C-1

BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

BENCHMARKS

Selecting the optimal tile size

Tests from PC-1


The larger the image, the less time per

pixel it takes to open it.

We opted for optimal block sizes around

4096 pixels when rescaling.

Image sizes are NxN pixels

Image Size time/pixel (μs) 256 500 1024 2048 4096 8192 16384 32768

256 5.49 ref 0.34 0.13 0.08 0.06 0.05 0.04 0.01

500 1.85 2.96 ref 0.39 0.24 0.19 0.15 0.12 0.04

1024 0.72 7.60 2.57 ref 0.60 0.48 0.40 0.32 0.11

2048 0.44 12.58 4.25 1.65 ref 0.79 0.65 0.52 0.18

4096 0.34 15.93 5.38 2.10 1.27 ref 0.83 0.66 0.22

8192 0.29 19.23 6.50 2.53 1.53 1.21 ref 0.80 0.27

16384 0.23 24.11 8.15 3.17 1.92 1.51 1.25 ref 0.34

32768 0.08 71.51 24.16 9.41 5.68 4.49 3.72 2.97 ref

Time Per Pixel Ratios (Rows/Columns)

Selected size: 4096px

Tim

e p

er

pix

el (u

s)

# pixels

BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

ACKNOWLEDGEMENTS

A big thank you to all our patient users for

helping us debug this piece of code.

Action Bar author: Jerome Mutterer

LOCI Bio-Formats support: Melissa Linkert

ImageJ: Wayne Rasband

Fiji: Johannes Schindelin, Albert Cardona et al.



http://loci.wisc.edu/software/bio-formats



http://rsb.info.nih.gov/ij/index.html

http://www.nature.com/nmeth/journal/v9/n7/full/nmeth.2019.html

BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP

MACRO EXAMPLE: COUNT NUCLEI

This macro is provided as an example of what you can do when you use the «Run Macro for each Series» option when processing the ROIs.

It has not been used or thouroughly tested and should not be used for quantification without proper validation first.

The code is available in the «Examples» folder of the ActionBar download.


BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP


This macro is provided as an example of what you can do when you use the «Run Macro for each Series» option when processing the ROIs.

It has not been used or thouroughly tested and should not be used for quantification without proper validation first.

The code is available in the «Examples» folder of the ActionBar download.


BIOIMAGING AND

OPTICS PLATFORM

EPFL–SV–PTBIOP


Results


Documents

BIOIMAGING AND VSI READER - UNIGE · BIOIMAGING AND OPTICS PLATFORM EPFL–SV–PTBIOP INSTALLATION: DEPENDENCIES The VSI reader is written in the ImageJ macro language and makes