File I/O module

Reading images from files and writing them to files.

Contents

Modules

module DIPjavaio
An interface to Java file I/O functionality

Classes

struct dip::FileInformation
A data structure with information about an image file.

Functions

auto dip::ImageReadICS(dip::Image& out, dip::String const& filename, dip::RangeArray const& roi = {}, dip::Range const& channels = {}, dip::String const& mode = "") -> dip::FileInformation
Read the image in the ICS file filename and puts it in out.
auto 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 = "") -> dip::FileInformation
This function is an overload of the previous function that defines the ROI using different parameters.
auto dip::ImageReadICSInfo(dip::String const& filename) -> dip::FileInformation
Reads image information and metadata from the ICS file filename, without reading the actual pixel data. See dip::ImageReadICS for more details.
auto dip::ImageIsICS(dip::String const& filename) -> bool
Returns true if the file filename is an ICS file.
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.
auto 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) -> dip::FileInformation
Reads an image from the TIFF file filename and puts it in out.
auto 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) -> dip::FileInformation
This function is an overload of the previous function that defines the ROI using different 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.
auto dip::ImageReadTIFFInfo(dip::String const& filename, dip::uint imageNumber = 0) -> dip::FileInformation
Reads image information and metadata from the TIFF file filename, without reading the actual pixel data.
auto dip::ImageIsTIFF(dip::String const& filename) -> bool
Returns true if the file filename is a TIFF file.
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.
auto dip::ImageReadJPEG(dip::Image& out, dip::String const& filename) -> dip::FileInformation
Reads an image from the JPEG file filename and puts it in out.
auto dip::ImageReadJPEGInfo(dip::String const& filename) -> dip::FileInformation
Reads image information and metadata from the JPEG file filename, without reading the actual pixel data.
auto dip::ImageIsJPEG(dip::String const& filename) -> bool
Returns true if the file filename is a JPEG file.
void dip::ImageWriteJPEG(dip::Image const& image, dip::String const& filename, dip::uint jpegLevel = 80)
Writes image as a JPEG file.
auto dip::FileGetExtensionPosition(dip::String const& filename) -> String::size_type
Returns the location of the dot that separates the extension, or dip::String::npos if there is no dot.
auto dip::FileHasExtension(dip::String const& filename) -> bool
Returns true if the file has an extension.
auto dip::FileGetExtension(dip::String const& filename) -> dip::String
Gets the extension for the given file name, or an empty string if there’s no extension.
auto dip::FileCompareExtension(dip::String const& filename, dip::String const& extension) -> bool
Returns true if the file has the given extension.
auto dip::FileAddExtension(dip::String const& filename, dip::String const& extension) -> dip::String
Adds the given extension to the file name, replacing any existing extension.
auto dip::ImageRead(dip::Image& out, dip::String const& filename, dip::String format = "") -> dip::FileInformation
Reads the image in a file filename, and puts it in out.
void dip::ImageWrite(dip::Image const& image, dip::String const& filename, dip::String format = "", dip::String const& compression = "")
Writes image to file.

Class documentation

struct dip::FileInformation

A data structure with information about an image file.

Variables
dip::String name File name
dip::String fileType File type
dip::DataType dataType Data type for all samples
dip::uint significantBits Number of bits used for each sample
dip::UnsignedArray sizes Size of image in pixels
dip::uint tensorElements Size of pixel in samples
dip::String colorSpace Color space
dip::PixelSize pixelSize Pixel size
dip::PhysicalQuantityArray origin Real-world location of origin pixel
dip::uint numberOfImages Number of images in the file. Currently only TIFF can have more than 1 here.
dip::StringArray history Assorted metadata in the file, in the form of strings.

Function documentation

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.

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::ImageReadICSInfo function.

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.

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 (not yet implemented).

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.

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 us 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.

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::ImageRead(dip::Image& out, dip::String const& filename, dip::String format = "")

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.
  • "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.

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

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.
  • "": Select the format by looking at the file name extension. If no extension is present, it defaults to 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 (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. Tensor images are always tagged as sRGB. Most metadata will be lost. Image data is converted to 8-bit unsigned integer, without scaling.

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 format, 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.