# 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:

```c++
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:

```c++
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:
```c++
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.