If you use this software for academic research, please quote:
Deroulers et al., Analyzing huge pathology images
with open source software, Diagnostic
Pathology 8:92 (2013).
And/or if you find this software
useful, please send us an email! This will
help us to get support from our funding agencies to keep working on it.
You can use following address (remove the anti-spam):
christophe.deroulers.nospam@u-paris.fr.
| 64-bit Windows: | ndpi2tiff.exe |
| ndpisplit.exe ndpisplit-m.exe ndpisplit-mJ.exe ndpisplit-s.exe ndpisplit-s-m.exe ndpisplit-s-mJ.exe | |
| 32-bit Windows: | ndpi2tiff.exe |
| ndpisplit.exe ndpisplit-m.exe ndpisplit-mJ.exe ndpisplit-s.exe ndpisplit-s-m.exe ndpisplit-s-mJ.exe | |
| Mac OS 10.6 and later: | Pkg installer |
| Linux x86_64: | ndpi2tiff ndpisplit |
ImageJ plugins |
|
Source code |
Using a Hamamatsu slide scanner such as the NanoZoomer, you may end up with NDPI files that can't always be directly open in standard image analysis software such as ImageJ. NDPITools is a collection of software that can convert NDPI files to standard TIFF files, possibly cutting them into smaller JPEG or TIFF pieces that will better fit into your computer's memory. It comes with a bundle of plugins for ImageJ which enable the use of the software directly inside ImageJ with point-and-click.
The software is open source, distributed under the GNU General Public License v. 3.0 or any later version, at your option. It is based on the libtiff, libjpeg , and libjpeg-turbo software, made free and open by its authors, which we acknowledge.
You can get the software through download (see the links in the frame). We provide some pre-compiled versions. The 32-bit Windows version should run under all versions of Windows (XP, Vista, 7; either 32- or 64-bits) but will produce images which require at most ca. 1 GiB memory. The 64-bit version goes beyond that limit.
Put the file NDPITools_.jar into the plugins directory of ImageJ (you can find out its location by selecting Plugins -> Utilities -> ImageJ Properties in ImageJ's menus). Look for the value of the tag Menus.getPlusInsPath near the middle of the displayed Properties window.
If you only use them through the ImageJ plugins, you can put their files at the same location as NDPITools_.jar (see above).
In the general case, under Mac OS or Linux, you can copy or move the files to a directory listed in your PATH, e.g. /usr/local/bin. Under Mac OS, this will be done automatically if you install from the .pkg file.
To use the ImageJ NDPITools plugins, you can read the specific instructions. The rest of this page deals mainly with the command line NDPITools.
Under Windows, you can simply drag and drop a NDPI file over the .exe file or icon of the program you want to use.
ndpisplit and ndpi2tiff should succeed even on computers having not too much memory.
On all platforms (including Windows, Linux, Mac OS), you can also launch the programs with a command line. Open a shell (e. g. command interpreter, Terminal.app, xterm...) and launch the program by typing its name (preceded by its path if needed) followed by a space then the path to the NDPI file (under Mac OS, the default path is /usr/local/bin). The resulting TIFF or JPEG file(s) will be produced in the directory where the NDPI file resides. Only one NDPI file at a time maybe given on the command line.
We have been advised that .exe files may cause some problems with antivirus software under Windows, especially when launched from ImageJ. The .exe files we publish should be virus-free since they have been made under Unix thanks to MinGW and MinGW-w64. We had no trouble using them with the Avira antivirus under Windows XP.
Quite often, the resulting images at largest magnifications (x20 or x40) will be so huge that they won't fit into memory and, therefore, can't be open with standard software. E.g., the image of a piece of tissue of 1 square centimeter scanned at 40x typically takes 5 Gib of memory. To address this problem, ndpisplit can be run with the options below. For your convenience, we provide in the download section variants of ndpisplit where options have been turned-on by default: e.g., running ndpisplit-mJ.exe is like running ndpisplit with the -mJ option. Otherwise, you can run the programs from a command line and give options after the command name, separated by spaces.
Options -m[memory][compression] and -M[memory][compression], where m stands for mosaic and memory is an optional decimal number, ask ndpisplit to make additional mosaics out of the files that would need more than memory Mib of memory to open (default: 1024.00 Mib = 1 Gib). A mosaic is a set of files that, if glued together, reproduce the full-size image, and such that each file requires less than memory Mib to open. With -m, a mosaic is produced only if there would be at least two pieces (that is, only if one piece would not fulfill the memory requirement); with -M, it is always produced. Pieces of the mosaic are stored in independent files, the name of which is derived from the name of the original image and from the position of the piece inside the mosaic (row and column numbers). Of course, opening one piece at a time is not as convenient as opening the full image, but it's better than nothing.
The optional letter compression indicates how mosaic pieces should be stored: J means a usual JPEG file, j (default) a usual TIFF file using JPEG compression inside, n and l are for TIFF files with 'n'o and 'l'zw (or zip) compression. Letters j and J may be followed with an integer number in the range 0 to 100 to indicate quality of produced JPEG (default is 75).
Example: ndpisplit -m500J60 will split NDPI file into separate TIFF files (one for each magnification and each z level), then produce a mosaic from each TIFF file that would require more than 500 Mib of memory to open. Mosaic tiles will require less than 500 Mib to open and be stored into JPEG files will quality level 60.
If interested in a software to create such mosaics from a general TIFF file, have a look at tiffmakemosaic from the LargeTIFFTools. Of course, you can first run ndpisplit without option, then use tiffmakemosaic if the resulting output is too big.
Option -g[width]x[length], used in addition to options -m or -M, asks ndpisplit to produce mosaic pieces which have the given width and/or length (g stands for geometry). If both width and length are specified, the memory limit possibly given with -m or -M is ignored.
Option -o<amount[%]> for overlap (in addition to -m) asks ndpisplit to add some overlap to pieces of a mosaic it produces. Some (rectangular) parts of one piece of a mosaic will be repeated on the respective adjacent pieces. The quantity to be repeated, amount, can be either an integer number to specify a number of pixels, or a decimal real number followd by the percent % symbol to specify a percentage of the size of one piece.
Example: with ndpisplit -m -o10, a 10-pixels wide (resp. high) rectangular band along the boundary will be repeated on mosaic pieces adjacent by a vertical (resp. horizontal) edge. With ndpisplit -m800 -o50%, the right (resp. bottom) half of each mosaic piece will be identical to the left (resp. top) half of the next piece to the right (resp. next piece below), whatever the size of each piece (which, incidentally, will be computed so that opening the piece requires less than 800 MB of memory).
Option -e[x1,y1,w1,l1[,label1]][:x2,y2,w2,l2[,label2]]... (which can be combined with -m or -M) requests extraction of an arbitrary number of rectangular regions. Each region is specified through the coordinates xi, yi of its top left corner, its width wi, and its length li. All numbers should be between 0 and 1 included: e.g., 0.75,0,0.25,0.25 specifies the top right part of size one fourth (area one sixteenth) of the image. An optional labeli can be specified; it will be appended at the end of the filename(s) (before the extension) where the extracted image will be stored. If no label is given, the first number which is not already used in a corresponding filename will be chosen. The region will be extracted from all available magnifications and z-offsets in the NDPI file.
Option -E[xM1[,zO1a][,zO1b...]],X1,Y1,W1,L1[,label1]][:xM2[,zO2a...]x2,y2,w2,l2[,label2]]... (which can be combined with -m or -M) requests extraction of an arbitrary number of rectangular regions, specified in pixels units, each one from an image at a given magnification. Each region is specified through the magnification xMi (e.g. x40, x10, ...), optionally the z-offsets zOik (e.g. z-1000, z2000, ... in nanometers), the coordinates in pixels units Xi, Yi of its top left corner, its width in pixels Wi, and its length in pixels Li.
For instance, -Ex40,z-100,z100,1000,0,3000,2000 requests extraction, from the images at magnification 40x and z-offsets -100 or 100 (if any), a rectangle of 3000x2000 pixels with top left corner at position (1000,0). An optional labeli can be specified; it will be appended at the end of the filename(s) (before the extension) where the extracted image will be stored. If no label is given, the first number which is not already used in a corresponding filename will be chosen. The region will be extracted from all available magnifications and z-offsets in the NDPI file.
Option -x[m1[,m2...]] requests extracting only images with magnification(s) m1, m2, ... (if any). For instance: ndpisplit -x40,20,2.4 file.ndpi. This option has an impact on all other requests (like -e).
Option -z[o1[,o2...]] requests extracting only images with z-offset(s) o1, o2, ... (if any). For instance: ndpisplit -z1000,0,-2000 file.ndpi. This option has an impact on all other requests (like -e).
Option -s (experimental) asks ndpisplit to extract from each image the actually scanned parts and remove blanks. When scanning a slide with several tissue samples, some slide scanners produce a set of large images that cover the entire area on the slide where samples were placed, but actually scan only the interesting regions (the samples) and fill in the remaining space with blank. In that case, it can be more useful to put each interesting (scanned) zone into a separate file and discard blank, because the resulting files will usually be much smaller than the original image and therefore easier to open, manage and analyze. This option tries to find what regions were actually scanned and to output them into separate files. In that case, the full images are not extracted. You can combine with option -m, which makes then mosaics of the interesting regions. Option -e takes precedence over (inactivates) -s.
See also the full list of options to ndpisplit.
In its versions up to 1.47, core ImageJ is not able to open TIFF files which use JPEG compression. However:
You can use the command Plugins -> NDPITools -> Open TIFF... from the NDPITools plugins which are distributed here; notice that the ImageJ NDPITools plugins can't currently be used with all JVM under Linux, which prevents the opening of the TIFF files with Open TIFF... See the detailed explanations and workarounds in the page about the ImageJ plugins.
Several other plugins manage to do this.
IJ-imageio is one of these plugins. You can download it from SourceForge (version 1.2.4), or find here a local copy of version 1.2.4. Unzip the file and put the resulting ij-ImageIO_.jar file into the plugins subdirectory of the directory where ImageJ is installed. Then, after you restart ImageJ, use the command Plugins->Image IO->Open. Under some versions of Linux, there is the same bug as in the NDPITools plugins.
The LOCI bio-formats plugin is also able to open the compressed TIFF files (it seems to be substantially slower than IJ-imageio). After installing it and restarting ImageJ, use the command Plugins->LOCI->Bio-formats Importer.
Core ImageJ, in its versions up to 1.47, can't open images which have more than 2 billions pixels (2^31). That happens even if you increase the available memory: it is due to an intrinsic limitations to Java arrays, addressed through 32-bits signed integers. (If your image is not that large, you can increase ImageJ's memory using Edit->Options->Memory).
In that case, you may:
The main reason why standard software can't open NDPI files, although NDPI files look internally quite close to TIFF files, is that the largest images inside a NDPI file can be more that 65500 pixels wide or high, whereas the JPEG standard used to compress and decompress them limits the dimensions to 65535 (there are also additional difficulties on 32 bits operating systems). The NDPITools use a special version of libjpeg and a modifed version of libtiff to overcome this and translate NDPI files into more standard TIFF files.
As of July 2011, the LOCI bio-formats ImageJ plugin is able to open NDPI files that contain no image wider or higher than 65500 pixels. (The NDPItools are useful to overcome this limit).
OpenSlide is a library software aiming at opening under a unified framework all virtual microscopy images (slides) formats. It is able to open some of the Hamamatsu formats.
This software was developed by the modelling team of the IMNC laboratory near Paris, France, during a research project funded by the IN2P3 and INSB Institutes of the CNRS and by the Universities Paris Diderot-Paris 7 and Paris South-11.
We thank the Laboratory of Pathology of the Saint-Louis Hospital in Paris (France) (especially Philippe Bertheau, David Ameisen and Fatiha Bouhidel) for the kind access to their slide scanners, and Marc Lartaud and Alexandre Granier from Montpellier RIO Imaging, Christophe Klein from the Cordeliers Research Center, Chloé Gerin now at the ASN, Philippe Mailly from the CIRB, Andrija Stajduhar from the Montreal Neurological Institute and Hospital, Yipei Song from the University of Virginia (USA), and Sander W. van der Laan from the Centraal Diagnostisch Laboratorium of the University Medical Center Utrecht for tests, bug reports, and suggesting improvements.
The NDPITools are the topic of a PLUME index card. Thanks to the PLUME!
Contact: Christophe Deroulers
Hamamatsu, NanoZoomer, Linux, Mac OS and Windows are registered trademarks of their respective owners.