Supported file formats

Pi2 supports a limited selection of useful file formats as indicated in the table below. Pi2 can either read full files or small blocks of files, but both operation modes are not supported for all file formats. If you need to read a format not listed here, please contact the authors to check if support for the format could be added.

Type Reading Writing Reading blocks Writing blocks
.raw Yes Yes Yes Yes
.tif Yes Yes Yes Yes
.nrrd Yes Yes No No
.vol/.longvol Yes No Yes No
PyHST .vol Yes No Yes No
.pcr Yes No Yes No
.dcm (DICOM) Yes No No No
NN5 Yes Yes Yes Yes
.tif sequence Yes Yes Yes Yes
.png sequence Yes Yes Yes Yes
.jpg sequence Yes No Yes No
.dcm (DICOM) sequence Yes No Yes No
.tif (2D) Yes Yes Yes Yes
.png (2D) Yes Yes Yes Yes
.jpg (2D) Yes No No No
.dcm (2D DICOM) Yes No No No

All the file formats can be read using the generic read command. Some of the file formats can be read also using specific readX command, where X is the file extension.

Files are written using the writeX command, where X is the file extension. Sequences can be written with the writesequence command.

.raw file format

The pi2 .raw files are equal to those used in Fiji/ImageJ. Basically the .raw file contains only the pixel values in such an order that the fastest changing coordinate is the first image dimension. Pi2 assumes that pixels are represented in the native byte order of the host computer. If this is not the case, byte order can be changed after reading the .raw file by using the swapbyteorder command.

In addition, pi2 supports parsing dimensions of the .raw files from the file name, as long as the file name is in format name_WxHxD.raw or name_WxH.raw, where W, H, and D are the width, height, and depth of the image in pixels.

Pi2 uses .raw format extensively in distributed processing mode as multiple compute nodes can easily write to the same .raw file at the same time (but of course not to the same locations).

Memory-mapped .raw files

An advantage of .raw files is that they can be easily memory-mapped. Memory-mapping means that the file on hard disk is correlated one-to-one to RAM that pi2 uses. If the file is larger than available RAM, the operating system manages reading and writing relevant portions of the file to and from RAM.

Memory-mapping enables relatively efficient processing of files larger than RAM, but it should not be confused with distributed computing possibilities offered by pi2.

Raw files can be memory-mapped with command mapraw that is a (almost) drop-in replacement for the readraw command. That is, after you mapraw an image, it can be used just like any other image but any changes made to it are immediately reflected to disk. Memory-mapped images do not have to be saved using the writeraw command. Any changes are automatically written to the file.

Note that memory-mapping files stored on network shares does not usually work as expected!