File I/O module

#include "diplib/file_io.h"

struct dip::FileInformation

A data structure with information about an image file.

dip::FileInformation dip::ImageReadICS(dip::Image& out, dip::String const& filename, dip::RangeArray const& roi = {}, dip::Range const& channels = {}, dip::String const& mode = "")

Read the image in the ICS file filename and puts it in out.

The ICS image file format (Image Cytometry Standard) can contain images with any dimensionality and data type also supported by DIPlib, and therefore is used as the default image file format.

The function tries to open filename as given first, and if that fails, it appends “.ics” to the name and tries again. If filename has an “.ids” extension, it is replaced with “.ics”.

roi can be set to read in a subset of the pixels in the file. If only one array element is given, it is used for all dimensions. An empty array indicates that all pixels should be read. Otherwise, the array should have as many elements as dimensions are represented in the file. Tensor dimensions are not included in the roi parameter, but are set through the channels parameter.

If mode is "fast", it will attempt to forge out with strides matching those in the file, so that reading is much faster. When reading an ROI this is not possible. When out has an external interface set it might also be impossible to dictate what the strides will look like. In these cases, the flag is ignored.

Information about the file and all metadata are returned in the dip::FileInformation output argument.

dip::FileInformation dip::ImageReadICS(dip::Image& out, dip::String const& filename, dip::UnsignedArray const& origin, dip::UnsignedArray const& sizes = {}, dip::UnsignedArray const& spacing = {}, dip::Range const& channels = {}, dip::String const& mode = "")

This function is an overload of the previous function that defines the ROI using different parameters.

The parameters origin and sizes define a ROI to read in. The ROI is clipped to the image size, so it is safe to specify a ROI that is too large. spacing can be used to read in a subset of the pixels of the chosen ROI. These three parameters are handled as in dip::DefineROI: If origin, sizes or spacing have only one value, that value is repeated for each dimension. For empty arrays, origin defaults to all zeros (i.e. the top left pixel), sizes to image_size - origin (i.e. up to the bottom right pixel), and spacing to all ones (i.e. no subsampling).

See the first overload for this function to learn about the other parameters.

void dip::ImageWriteICS(dip::Image const& image, dip::String const& filename, dip::StringArray const& history = {}, dip::uint significantBits = 0, dip::StringSet const& options = {})

Writes image as an ICS file.

The ICS image file format (Image Cytometry Standard) can contain images with any dimensionality and data type also supported by DIPlib, and therefore is used as the default image file format. Any DIPlib image can be stored as an ICS file, and read back in to yield the exact same data, with the only limitation that the ICS writer (libics) currently throws an exception if the image has more than 10 dimensions. libics can be recompiled to handle higher-dimensional images if necessary.

This function saves the pixel sizes, tensor dimension, color space, and the tensor shape. However, the tensor shape is saved in a custom way and will not be recognized by other software. The “.ics” extension will be added to filename if it’s not there. Overwrites any other file with the same name.

history is a set of strings that are written as history lines, and will be recovered by the dip::FileInformation struct when reading with dip::ImageReadICS or dip::ImageReadICSInfo.

Set significantBits only if the number of significant bits is different from the full range of the data type of image (use 0 otherwise). For example, it can be used to specify that a camera has produced 10-bit output, even though the image is of type dip::DT_UINT16.

options specifies how the ICS file is written, and can contain one or several of these strings:

• "v1" or "v2": ICS v1 writes two files: one with extension ‘.ics’, and one with extension ‘.ids’. The ICS file contains only the header, the IDS file contains only the pixel data. ICS v2 combines these two pieces into a single ‘.ics’ file. "v2" is the default.
• ‘“uncompressed”or '"gzip": Determine whether to compress the pixel data or not. "gzip" is the default.
• "fast": Writes data in the order in which they are in memory, which is faster.

Note that the "fast" option yields a file with permuted dimensions. The software reading the file must be aware of the possibility of permuted dimensions, and check the “order” tag in the file. If the image has non-contiguous data, then the "fast" option is ignored, the image is always saved in the “normal” dimension order

dip::FileInformation dip::ImageReadTIFF(dip::Image& out, dip::String const& filename, dip::Range imageNumbers = Range{0}, dip::RangeArray const& roi = {}, dip::Range const& channels = {}, dip::String const& useColorMap = S::APPLY)

Reads an image from the TIFF file filename and puts it in out.

The function tries to open filename as given first, and if that fails, it appends “.tif” and “.tiff” to the name and tries again.

Multi-page TIFF files contain a series of 2D images, which, if they are the same size, data type and number of samples per pixel, can be regarded as a single 3D image. imageNumbers is a range which indicates which images from the multi-page TIFF file to read. If the range indicates a single page, it is read as a 2D image. In this case, {0} is the first image. Some Zeiss confocal microscopes write TIFF files (with an “.lsm” extension) in which image planes and thumbnails alternate. A range such as {0,-1,2} reads all image planes skipping the thumbnails. It is currently not possible to read multiple pages from a binary or color-mapped image.

roi can be set to read in a subset of the pixels in the 2D image. If only one array element is given, it is used for both dimensions. An empty array indicates that all pixels should be read. Tensor dimensions are not included in the roi parameter, but are set through the channels parameter. It is currently not possible to read an ROI from a binary or a color-mapped image.

Color-mapped (palette) images are read as sRGB images by applying the color map. Set useColorMap to "ignore" to return the color map indices as pixel values, ignoring the color map. With this option set, it becomes possible to read an ROI of a color-mapped image, or to read a multi-paged color-mapped image.

The pixels per inch value in the TIFF file will be used to set the pixel size of out. In the case of multiple 2D slices read as a 3D image, there is no information about the pixel size along the 3rd dimension in the TIFF file. In this case, the pixel size along the 2nd dimension will be copied over to the 3rd one. This is meaningful for isotropic images, but the user should probably adjust that value explicitly if the pixel sizes are needed.

Color TIFF files produce an image with proper color space name set: either sRGB, CMY, CMYK or Lab. Other multi-channel TIFF files are read as vector images without color space information.

TIFF is a very flexible file format. We have to limit the types of images that can be read to the more common ones. These are the most obvious limitations:

• Only 1, 4, 8, 16 and 32 bits per pixel integer grey values are read, as well as 32-bit and 64-bit floating point.
• Only 4 and 8 bits per pixel color-mapped images are read.
• Class Y images (YCbCr) and Log-compressed images (LogLuv or LogL) are not supported.
• Some non-standard compression schemes are not recognized (most notably JPEG2000).

dip::FileInformation dip::ImageReadTIFF(dip::Image& out, dip::String const& filename, dip::Range const& imageNumbers, dip::UnsignedArray const& origin, dip::UnsignedArray const& sizes = {}, dip::UnsignedArray const& spacing = {}, dip::Range const& channels = {}, dip::String const& useColorMap = S::APPLY)

This function is an overload of the previous function that defines the ROI using different parameters.

The parameters origin and sizes define a ROI to read in. The ROI is clipped to the image size, so it is safe to specify a ROI that is too large. spacing can be used to read in a subset of the pixels of the chosen ROI. These three parameters are handled as in dip::DefineROI: If origin, sizes or spacing have only one value, that value is repeated for each dimension. For empty arrays, origin defaults to all zeros (i.e. the top left pixel), sizes to image_size - origin (i.e. up to the bottom right pixel), and spacing to all ones (i.e. no subsampling).

See the first overload for this function to learn about the other parameters.

void dip::ImageReadTIFFSeries(dip::Image& out, dip::StringArray const& filenames, dip::String const& useColorMap = S::APPLY)

Reads a set of 2D TIFF images as a single 3D image.

filenames contains the paths to the TIFF files, which are read in the order given, and concatenated along the 3rd dimension. Only the first page of each TIFF file is read.

Set useColorMap to "ignore" to return the color map indices as pixel values, ignoring the color map. This option only has effect for TIFF files with a color-mapped (palette) image.

void dip::ImageWriteTIFF(dip::Image const& image, dip::String const& filename, dip::String const& compression = "", dip::uint jpegLevel = 80)

Writes image as a TIFF file.

The TIFF image file format is very flexible in how data can be written, but is limited to multiple pages of 2D images. A 3D image will be written as a multi-page TIFF file.

A tensor image will be written as an image with multiple samples per pixel, but the tensor shape will be lost. If the tensor image has color space information, and it is one of the few color spaces known to the TIFF standard, this information will be stored; images in other color spaces are stored without color space information. No color space transformation will be applied. Recognized color spaces are sRGB, CMY, CMYK and Lab. Linear RGB images are currently also tagged as sRGB, though this might not be ideal. It is recommended to transform any color image to the sRGB color space before saving as TIFF.

Pixel sizes, if in units of length, will set the pixels per centimeter value in the TIFF file. For 3D images, the TIFF format has no standard way to store the pixel size along the 3rd dimension, so this value will not be preserved.

The samples of image are written directly to the TIFF file, no matter what their data type is. Complex data are not supported by the TIFF format, but all binary, integer and floating-point types are. However, if the type is not binary, 8-bit or 16-bit unsigned integer, many TIFF readers will not recognize the format. If the image needs to be read by other software, it is recommended to convert the image to dip::DT_UINT8 before saving as TIFF.

If filename does not have an extension, “.tif” will be added. Overwrites any other file with the same name.

compression determines the compression method used when writing the pixel data. It can be one of the following strings:

• "none": no compression.
• "deflate" or "": uses gzip compression. This is the better compression, but is not universally recognized.
• "LZW": uses LZW compression, yielding (typically) only slightly larger files than "deflate". Recognized by most TIFF readers.
• "PackBits": uses run-length encoding, the simplest of the compression methods, and required to be recognized by compliant TIFF readers. Even small amounts of noise can cause this method to yield larger files than "none".
• "JPEG": uses lossy JPEG compression. jpegLevel determines the amount of compression applied. jpegLevel is an integer between 1 and 100, with increasing numbers yielding larger files and fewer compression artifacts.

dip::FileInformation dip::ImageReadJPEG(dip::Image& out, dip::String const& filename)

Reads an image from the JPEG file filename and puts it in out.

The function tries to open filename as given first, and if that fails, it appends “.jpg” and “.jpeg” to the name and tries again.

JPEG images are either gray-scale (scalar) or sRGB images, the color space information will be set accordingly.

The pixels per inch value in the JPEG file will be used to set the pixel size of out.

dip::FileInformation dip::ImageReadJPEG(dip::Image& out, void const* buffer, dip::uint length)

Reads an image from the JPEG-encoded buffer and puts it in out.

buffer must point to length bytes containing a JPEG-encoded image. See dip::ImageReadJPEG for details.

dip::FileInformation dip::ImageReadJPEGInfo(void const* buffer, dip::uint length)

Reads image information and metadata from the JPEG-encoded buffer, without reading the actual pixel data.

buffer must point to length bytes containing a JPEG-encoded image.

void dip::ImageWriteJPEG(dip::Image const& image, dip::String const& filename, dip::uint jpegLevel = 80)

Writes image as a JPEG file.

image must be 2D, and either scalar or with three tensor elements. If the image has three tensor elements, it will be saved as an sRGB image, even if the color space is not sRGB (no color space conversion is done, the data is simply tagged as sRGB). If the image is not dip::DT_UINT8, it will be converted to it (complex numbers are cast to real values by taking their magnitude, and real numbers are rounded and clamped to the output range), no scaling will be applied.

If filename does not have an extension, “.jpg” will be added. Overwrites any other file with the same name.

jpegLevel determines the amount of compression applied. jpegLevel is an integer between 1 and 100, with increasing numbers yielding larger files and fewer compression artifacts.

dip::FileInformation dip::ImageReadPNG(dip::Image& out, dip::String const& filename)

Reads an image from the PNG file filename and puts it in out.

The function tries to open filename as given first, and if that fails, it appends “.png” to the name and tries again.

PNG images are either gray-scale (scalar) or sRGB images, the color space information will be set accordingly. If the image has an alpha channel, it will be the second or fourth tensor element in out.

The pixel size information, if present in the PNG file, will be used to set the pixel size of out.

dip::FileInformation dip::ImageReadPNG(dip::Image& out, void const* buffer, dip::uint length)

Reads an image from the PNG-encoded buffer and puts it in out.

buffer must point to length bytes containing a PNG-encoded image. See dip::ImageReadPNG for details.

dip::FileInformation dip::ImageReadPNGInfo(void const* buffer, dip::uint length)

Reads image information and metadata from the PNG-encoded buffer, without reading the actual pixel data.

buffer must point to length bytes containing a PNG-encoded image.

void dip::ImageWritePNG(dip::Image const& image, dip::String const& filename, dip::sint compressionLevel = 6, dip::StringSet const& filterChoice = {S::ALL}, dip::uint significantBits = 0)

Writes image as a PNG file.

image must be 2D, and have between one and four tensor elements. If the image has three or four tensor elements, it will be saved as an sRGB image, even if the color space is not sRGB (no color space conversion is done, the data is simply tagged as sRGB); otherwise it will be saved as a grayscale image. If the image has two or four tensor elements, the last tensor element is assumed to be the alpha channel. If the image data type is dip::DT_UINT8, dip::DT_UINT16 or dip::DT_BIN, it will be written as-is. Otherwise, the image will be converted to dip::DT_UINT8 (complex numbers are cast to real values by taking their magnitude, and real numbers are rounded and clamped to the output range), no scaling will be applied. Note that binary images are only saved as binary images if they have a single channel. Multi-channel binary images are converted to dip::DT_UINT8 as well.

If filename does not have an extension, “.png” will be added. Overwrites any other file with the same name.

compressionLevel sets the compression level; it’s an integer in the range 0-9, with 0 for no compression, 1 for the fastest method producing the largest output files, and 9 the slowest method producing the smallest output files. The default is 6, which is a good compromise between file size and time.

The special compressionLevel value of -1 sets the deflate algorithm to use run length encoding (RLE), basically limiting match distances to one. This can significantly speed up compression, depending on the data being compressed, and can even produce smaller file sizes for specific images.

filterChoice specifies how the PNG file is filtered during compression. The compression algorithm will try all selected filters on each line, and pick the best one. The set can contain one or several of these strings:

• "disable": No filtering, cannot be combined with the other methods.
• "none": No filtering.
• "sub": Each byte is replaced with the difference between it and the byte to its left.
• "up": Each byte is replaced with the difference between it and the corresponding byte on the previous image line.
• "avg": Each byte is replaced with the difference between it and the average of the corresponding bytes to its left and above it, truncating any fractional part.
• "Paeth": Each byte is replaced with the difference between it and the Paeth predictor of the corresponding bytes to its left, above it, and to its upper left.
• "all": Shortcut for including all five filters. This is the default. Cannot be combined with the other methods.

Note that trying multiple filters adds to the cost. This is again a compromise between file size and time. Picking one filter often leads to significantly smaller files, but not always. Including all filters is guaranteed to produce the smallest files, because no filtering is included as a choice, but is also guaranteed to be the most costly option. If compressionLevel is 0, filterChoice will always be "disable".

Set significantBits only if the number of significant bits is different from the full range of the data type of image (use 0 otherwise). For example, it can be used to specify that a camera has produced 10-bit output, even though the image is of type dip::DT_UINT16.

dip::FileInformation dip::ImageReadNPY(dip::Image& out, dip::String const& filename)

Reads a numeric array from the NumPy NPY file filename and puts it in out.

The function tries to open filename as given first, and if that fails, it appends “.npy” to the name and tries again.

Only NPY files that contain a numeric array are supported, and only version 1.0 NPY files can be read (note that NumPy only writes later version files for more complex non-numeric arrays).

Following the handling of PyDIP, the Python bindings, we reverse the indexing of the array, such that the NumPy array’s first index is the y axis as the second index is the x axis (this is how 2D arrays are treated everywhere in Python). We generalize this to arbitrary dimensions by reversing the indices. A standard C-order NumPy array this way translates to a DIPlib image with Normal strides.

void dip::ImageWriteNPY(dip::Image const& image, dip::String const& filename)

Writes image as a numeric array to a NumPy NPY file.

image must be scalar, use dip::Image::TensorToSpatial to save a tensor image. Any data type is allowed. Metadata (e.g. pixel sizes) are not stored.

If filename does not have an extension, “.npy” will be added. Overwrites any other file with the same name.

Following the handling of PyDIP, the Python bindings, we reverse the indexing of the array, such that the NumPy array’s first index is the y axis as the second index is the x axis (this is how 2D arrays are treated everywhere in Python). We generalize this to arbitrary dimensions by reversing the indices. A DIPlib image with Normal strides is thus translated to a NumPy array with standard C-order.

dip::FileInformation dip::ImageRead(dip::Image& out, dip::String const& filename, dip::String format = "")

#include "diplib/simple_file_io.h"

Reads the image in a file filename, and puts it in out.

format can be one of:

• "ics": The file is an ICS file, use dip::ImageReadICS.
• "tiff": The file is a TIFF file, use dip::ImageReadTIFF. Reads only the first image plane.
• "jpeg": The file is a JPEG file, use dip::ImageReadJPEG.
• "png": The file is a PNG file, use dip::ImageReadPNG.
• "npy": The file is a NumPy NPY file, use dip::ImageReadNPY.
• "bioformats": Use dip::javaio::ImageReadJavaIO to read the file with the Bio-Formats library.
• "": Select the format by looking at the file name extension or the file’s first few bytes. This is the default.

Information about the file and all metadata are returned in the dip::FileInformation output argument.

If DIPjavaio is not linked against, the "bioformats" format will not exist. Note that when linking against the DIPjavaio library, DIP_CONFIG_HAS_DIPJAVAIO should be defined (but might need to be defined manually if not using CMake).

Use the filetype-specific functions directly for more control over how the image is read.

If an exception is thrown saying that the file could not be read as the type indicated by its extension, use the filetype-specific function directly, it will give a more specific reason for why the file could not be read. Especially in the case of TIFF files, which allows data to be stored in an infinite number of ways, the reader cannot be expected to read all possible files.

void dip::ImageWrite(dip::Image const& image, dip::String const& filename, dip::String format = "", dip::String const& compression = "")

#include "diplib/simple_file_io.h"

Writes image to file.

format can be one of:

• "ics" or "icsv2": Create an ICS version 2 file, use dip::ImageWriteICS.
• "icsv1": Create an ICS version 1 file, use dip::ImageWriteICS.
• "tiff": Create a TIFF file, use dip::ImageWriteTIFF.
• "jpeg": Create a JPEG file, use dip::ImageWriteJPEG.
• "png": Create a PNG file, use dip::ImageWritePNG.
• "npy": Create a NumPy NPY file, use dip::ImageWriteNPY.
• "": Select the format by looking at the file name extension. If no extension is present, it uses ICS version 2. This is the default.

The ICS format can store any image, with all its information, such that reading the file using dip::ImageRead or dip::ImageReadICS yields an image that is identical (except the strides might be different).

The TIFF format can store 2D images, as well as 3D images as a series of 2D slides (but this is not yet implemented). A limited set of color spaces are recognized, other color images are stored without color space information. Complex data is not supported, other data types are. But note that images other than 8-bit or 16-bit unsigned integer lead to files that are not recognized by most readers.

The JPEG format can store 2D images with 1 or 3 tensor elements. Tensor images are always tagged as sRGB. Most metadata will be lost. Image data is converted to 8-bit unsigned integer, without scaling.

The PNG format can store 2D images with 1 to 4 tensor elements. Images with 3 or 4 tensor elements are always tagged as sRGB, those with 1 or 2 as grayscale. The 2nd or 4th tensor element is the alpha channel. Image data is converted to 8-bit unsigned integer, without scaling, unless the image is binary or 16-bit unsigned integer.

The NPY format stores raw pixel data for a scalar image. Tensor images cannot be written. All metadata will be lost.

compression determines the compression method used when writing the pixel data. It can be one of the following strings:

• "none": no compression.
• "": gzip compression (default). TIFF files with gzip compression are not universally recognized.
• "LZW", "PackBits", "JPEG": compression formats supported only by the TIFF format.

For the JPEG and NPY formats, compression is ignored.

Use the filetype-specific functions directly for more control over how the image is written. See those functions for more information about the file types and how images are written to them.