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 will open the NDPI file and split it into
multiple TIFF image files, one for the macroscopic image of the slide,
one for the map of the scanned regions, and one for each z-slice and for
each available magnification of the scanned slide. There are some options to modify the default behaviour
(see below for options devoted specifically to huge files). ndpi2tiff will convert the NDPI file into a more
standard TIFF file that will contain all images (bundled together). Use option
-8 if you expect that the resulting TIFF file will be larger
than 8 GiB: this will force use of the BigTIFF
format (see also here)
supported by the recent versions of LibTIFF. See also the list of all options.
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.
ndpisplit options to deal with huge images 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.
ndpisplit with option -mJ. 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:
ndpisplit to extract only
a part of the NDPI file (if you use the NDPITools ImageJ plugins, select
the region on the preview image, then use the command Extract to
TIFF; on the command line, use the option -e of
ndpisplit);ndpisplit to make a
mosaic out of the image while opening the NDPI file, with the option -m (see above);tiffcrop command, or with ImageMagick, GraphicsMagick,...) , knowing that they can be very slow or even
completely fail ;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.
/usr/local/bin to the search path
for ndpisplit in the ImageJ plugins bundle-g option to ndpisplit to request a
specific width and/or length of mosaic pieces-x, -z, -E to
ndpisplit to restrict extraction to some magnifications and
z-offsets and allow specification of zones to extract in pixel
unitsndpisplit for small images: the processing time is now
proportional to the size of the requested extract and not to the size of
the full image; added capability to save and restore in ImageJ's
prefs file parameters of dialog box of ImageJ plugins bundlendpisplit and any conversion with ndpi2tiff which does
not require a specific tile dimension; fixed regression in making
mosaics of large images with ndpisplit and some minor bugs;
added option -v to ndpi2tiffndpisplit when requesting a
mosaic with non-zero overlapndpisplit and to request a
specific compression format for split images (as well as for mosaic
pieces); the ImageJ plugins now take the screen size into account when
choosing a preview image; fixed bug: value 0 for size limit of preview
image was not correctly interpretedndpisplit
and in the ImageJ plugins. In the ImageJ plugins, the fluorescence type
(if any) is stored as image properties, and the run method of
NDPIToolsPreviewPlugin can now be called with a filename argument. Small
bug fixes in the ImageJ plugins.Save as compressed TIFF... command to the
ImageJ plugins (with choice of compression parameters). This command can
be used in macros. Corrected a bug in the options to the -m
command line switch of ndpisplit and typos in messages.NDPItools now process correctly very large NDPI
files (even when compressed output images are larger than 4GiB). Added
-st option to ndpisplit to extract the scanned zones /
remove the blank filling according to the blank vertical lanes (works
currently better than -s but not for all files) and the
-O option to request that produced files be put in an other
directory than the directory containing the source file. Added
-m option to ndpi2tiff to write in output file
microscopic images only (ignore macroscopic image, map, ...). Corrected
a bug in ndpisplit when options -K and -s
were both given to ndpisplit and a bug in ndpi2tiff
wich prevented small images to be written correctly when a tiled TIFF
output was required.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 team Modeling of the Living of the IJCLab laboratory near Paris, France, during a research project funded by the IN2P3 and INSB Institutes of the CNRS and by the Universities Paris City and Paris-Saclay.
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.