ndpisplit

NAME

  ndpisplit - Extract images from a NDPI (digital pathology) file

USAGE

  ndpisplit [options] file.ndpi

DESCRIPTION

ndpisplit opens file.ndpi and extracts in independant TIFF files the images it contains (by default, all of them).

The names given to the output files are created by adding the specifications of magnification and, when applicable, z-offset (focalization level) after the name of the original image and before the extension. The output files are placed in the directory where the input file is.

OPTIONS

-v

Increase verbosity of warnings and diagnostic messages. This option can be repeated or doubles to increase verbosity further more: -v -v -vvv

-TE

Transmit error messages from the TIFF library (with dialog boxes under Windows) instead of silencing them

-K

Print control data under the form Key:value on stdout

-8

Force output files of split images to use the BigTIFF extension to the TIFF specification (supported by LibTIFF as of version 4.0). This option is needed if an output file is larger than 4 GiB.

-O dir

Output files into directory dir instead of storing them into the directory of the source file.

-s

Subdivide each image into scanned zones, removing blank filling between them, based on the map of scanned zones (experimental)

-sl

Subdivide each image along the slide's axis into scanned zones, removing blank vertical lanes between them (more reliable than -s )

-x[m1[,m2...]]

Extract only images at the specified magnifications m1 , m2 ,... and ignore other images

-z[o1[,o2...]]

Extract only images at the specified focalization levels (z-offsets) z1 , z2 ,... and ignore other images

-ex1,y1,W1,L1[,label1][:x2,...]

Extract only the specified rectangular region(s) of the whole slide (ignoring the option -s even if it was given). The region to be extracted is defined with respect to the region of the slide which was scanned, and the corresponding rectangles on all available images (that is, at all magnifications and all z-offsets) will be extracted. See the examples below.

xn,yn : relative coordinates of the top left corner of the nth rectangle to extract. They have to be real numbers. x=0 is on the left edge of the scanned zone of the slide, x=1 is on the right edge of the scanned zone of the slide. Likewise, y=0 is on the top edge of the scanned zone of the slide and y=1 is on the bottom edge.

Wn,Ln : width and length of the nth rectangle to extract, relative to the dimensions of the scanned region. They have to be real numbers. For instance, W=0.25 means one fourth of the width of the scanned region, while L=1 means the whole length.

labeln : optional label that will be part of the name of the file(s) where the nth extracted rectangle will be stored.

-ExM1[,zO1a[,zO1b...]],x1,y1,W1,L1[,label1][:M2,...]

Extract only the specified rectangular region(s) from the images at the given magnification (and which also match the z-offsets if they are specified), with absolute coordinates in pixels. Unlike -e , this option does not extract the rectangular regions on images at all magnifications, but only a rectangular region at a given magnification.

xMn : magnification of the image from which the nth rectangle should be extracted. Notice the x prefix, before Mn , as in ``x40''.

Onk : optional specifications of z-offsets of the image from which the nth rectangle should be extracted. There may be zero, or several values, as in z-1000,z0,z1000 tice the z prefix.

xn,yn : absolute coordinates, in pixels, of the top left corner of the nth rectangle to extract. x=0,y=0 designates the top left corder of the scanned region of the slide. The maximal values of x and y depend on the NDPI file and may be found by reading the output of ndpisplit run with the -K option. Wn,Ln : absolute width and height, in pixels, of the nth rectangle to extract.

-c[#]C

Specify the compression format of split images. The character C indicates the compression format as for mosaic pieces (option -m below) except that J is not supported: split images are always stored in TIFF files. The optional number # specifies the maximum amount of memory, in MiB, to be used during conversion of the image (1024.000 by default). If it is 0, no memory limit is imposed.

-m[#][c]

Make, in addition to the default TIFF images, mosaics of each produced image which would need more than # MiB of memory to be uncompressed entirely into RAM. The pieces of the mosaic will be chosen so that they need less than # MiB of memory to be uncompressed entirely into RAM (and in accordance with the arguments of the -g option if it is present, see below). If no number is provided, this limit is taken equal to 1024.000. The value 0 stands for ``no limit''. The values have to be nonnegative real numbers. The dimensions of the pieces of the mosaic are computed according to the rules explained below (see -g option).

c This character optionally specifies the compression format of the pieces of the produced mosaic. It can be n for none, l for LZW, j for JPEG compressed TIFF files (the default), J for stand-alone JPEG files. j and J may be followed (optionally) by the requested quality level of the JPEG compression, in the range 1-100. The default quality is the quality of the input image if applicable, 75 if not.

-M[#][c]

Make, in addition to the default TIFF images, mosaics of each produced image. This is the same as -m but a mosaic is produced systematically, even for small images where the mosaic is composed of a single piece.

-g[w]x[h]

Specify the width and height in pixels of each piece of the mosaics which may be produced. If both width and height are given, this option overrides the memory limit given with -m and/or -M default values are the largest dimensions that satisfy memory limit, divide the full image in equal pieces by powers of 2, and are close to each other so that the aspect ratio of the image is close to 1.

-o#[%]

Specify the amount of overlap between mosaic pieces which are adjacent. This amount has to be either an integer number of pixels, or a nonnegative real number indicating a fraction (possibly larger than one) of the width resp. height of the pieces if the suffix % is present. By default, it is 0 .

-p[s[,WxL]]

Extract the preview image(s) only and print a few paremeters (and control data if option -K is given). The nonnegative integer number s is the requested maximum size of a preview image in pixels (default: 1000000). The nonnegative intergers W and L are the requested maximum width and length of a preview image in pixels (default: no request). 0 for either quantity s , W or L stands for ``no limit''. The preview image(s) are the image(s) at the largest available magnification which are smaller than the previous size constrains, or the macroscopic image of the slide (if present) if none complies with these limits.

EXAMPLES

The following splits a NDPI file into multiple TIFF files, one for each magnification and each z level, using the default compression, JPEG :

ndpisplit a.ndpi

The following example splits the lower left quarter of the images inside the file a.ndpi into separate TIFF files, then produces a mosaic from each TIFF file that would require more than 500 MiB of memory to be uncompressed entirely. Pieces of the mosaics will require less than 500 MiB to open and be stored into JPEG files with quality level 60. There will be an overlap of 30 pixels between adjacent mosaic tiles:

ndpisplit -e0,0.75,0.25,0.25 -m500J60 -o30 a.ndpi

The following example extracts, from the images at magnification 40x and z-offsets -100 or 100, a rectangle of 3000x2000 pixels with top left corner at position (1000,0), and saves it in a TIFF file, the name of which ends with the character string ``mylabel'' (followed by .tif ):

ndpisplit -Ex40,z-100,z100,1000,0,3000,2000,mylabel a.ndpi

BUGS

The behaviour of -p is not satisfactory if no image is smaller than the requested limit and the macroscopic image of the slide is absent or too large.

SEE ALSO

ndpi2tiff(1), tiffmakemosaic(1), tifffastcrop(1), tiffsplit(1), tiffcrop(1), libtiff(3TIFF)

Home Page

http://www.imnc.in2p3.fr/pagesperso/deroulers/software/ndpitools/

AUTHOR

Christophe Deroulers

Index

NAME

USAGE

DESCRIPTION

OPTIONS

EXAMPLES

BUGS

SEE ALSO

AUTHOR