NICE_Core/core/tutorial/01_imageio.md

Tutorial 01 - Basic Image I/O Operations

In this first tutorial you will learn how to read and write image files and how images are represented in NICE.

Prerequisites

If you need support for a specific image file format other than PGM/PPM, you have to compile nice-core yourself and add the necessary libraries and CMake flags.

The sample code for this tutorial does not have any dependencies other than nice-core. You can find it in the tutorial/progs subfolder.

Images in memory

NICE provides a common generic interface for grayscale and multi-channel images. The corresponding classes are ImageT and ColorImageT, both subclasses of GrayColorImageCommonImplementationT which contains the most basic image access methods. Those are used by many of the other modules. You can find typical use cases in the next tutorials.

Image files

In NICE, instances of ImageT or ColorImageT do not have to exist on disk. Files are different, completely independent objects. The ImageFile class serves as a pointer to a file in the file system.

An instance of ImageFile can be read from or written to, but it does not modify the file in any way unless you call those methods.

Constructing an ImageFile is simple:

ImageFile file("path/to/file.pgm");

This does not touch the file at all and it doesn't need to exist. If it does exist, you can read the image file into memory like this:

Image image_in_memory;
file.reader(&image_in_memory);

After making our changes to the image (in memory), we can write them to the file:

file.writer(&image_in_memory);

Header information

Sometimes it can be useful to access metadata without reading the whole image into memory. ImageFile provides the getHeader method for this. It reads the file and returns an instance of Header with the fields width, height, bitdepth, channel.

Formats

Note that ImageFile attemtps to determine the file format by looking at the file name. You can override this behaviour by providing the type parameter using the Format enumeration.

Supported file formats include PGM/PPM out of the box and those provided by libpng, libjpeg and libimagemagick++.

The sample images do not need any additional libraries.