IO Module

Pylene provides some input/output utilities, which are described below. To this aim, it uses some third-party libraries, which are only used to read and write images.

Print image

Include <mln/io/imprint.hpp>

template<class I> void imprint(I &&image, bool print_border = false)

Display an image as characters in the output stream. It is based on the {fmt} library so the image can be printed only if a formatter for the image value is defined.

Template Parameters:

I – The image type

Parameters:

image – The image to print
print_border – Boolean to print the border if any (default: false)

Freeimage plugin

A plugin to read and write some common image format is provided and relies on the FreeImage library. This plugin is contained in the component Pylene::IO-freeimage, which depends on Pylene::Core. When using it, do not forget to add it in the CMakeLists.txt as below:

target_link_libraries(my_executable PRIVATE Pylene::IO-freeimage)

Supported formats (from here).

Reading image

The input type handled by the FreeImage plugin for reading are the following:

unsigned int on 8 bits.
[unsigned] int (on 16 and 32 bits).
Floating point values (float and double).
Boolean values for binary images (bool).
Color values on 24 bits (RGB triplet on 8 bits each).

Include <mln/io/imread.hpp>

void imread(const std::string &filename, mln::ndbuffer_image &out)

Reads an image located at filename and stores its content in the buffer out.

Parameters:

filename – The filename to an image
out – The output image

Throws:

std::runtime_error – When the file format is not supported by FreeImage, when the image located at filename does not exists, when the input type is not handled by the plugin or in case static image type are used (mln::ndimage<T>), where the static type of the image does not correspond to the type of the image stored in the file.

void imread_from_bytes(std::span<const std::byte> data, mln::ndbuffer_image &out)

Reads an image frm an in-memory buffer and stores its content in the buffer out.

Parameters:

data – The buffer containing the image
out – The output image

Throws:

std::runtime_error – When the file format is not supported by FreeImage, when the image located at filename does not exists, when the input type is not handled by the plugin or in case static image type are used (mln::ndimage<T>), where the static type of the image does not correspond to the type of the image stored in the file.

Example

#include <mln/core/image/ndimage.hpp>
#include <mln/io/imread.hpp>

...

mln::image2d<std::uint8_t> ima;
mln::io::imread("/path/to/an/image", ima);

mln::ndbuffer_image imread(const std::string &filename)

mln::ndbuffer_image imread_from_bytes(std::span<const std::byte> data)

Reads an image located at filename or from an in-memory buffer and returns a dynamic buffer with the image contained in.

Parameters:: filename – The filename to an image
Returns:: A dynamic buffer with the image contained in.
Throws:: std::runtime_error – When the file format is not supported by FreeImage, when the image located at filename does not exists, when the input type is not handled by the plugin or in case static image type are used (mln::ndimage<T>), where the static type of the image does not correspond to the type of the image stored in the file.

Example

#include <mln/core/image/ndimage.hpp>
#include <mln/io/imread.hpp>

...

auto ima = mln::io::imread("/path/to/an/image");

// Dynamic handling of the type
if (ima.sample_type() == mln::sample_type_id::UINT8)
{
    auto casted = ima.cast_to<std::uint8_t, 2>();
    if (casted) // casted is a pointer. Returns nullptr in case of wrong conversion
        my_algorithm(*casted);
}
else if (ima.sample_type() == mln::sample_type_id::RGB8)
{
    ...
}
else
{
    throw std::invalid_argument("Image format not handled");
}

Writing images

Include <mln/io/imsave.hpp>

template<class I> void imsave(I &&ima, const std::string &filename)

template<class I> void imsave_to_bytes(I &&ima, const std::string &filename, std::vector<std::byte> &out)

template<class I> void imsave(I &&ima, const char *filename)

template<class I> void imsave_to_bytes(I &&ima, const char *filename, std::vector<std::byte> &out)

Save the image ima in the file filename. The file format is deduced from the extension of the filename. In the overload with out, the image is saved in-memory the buffer out, instead of being saved in a file.

Template Parameters:

I – The output image type (should be defined on a 2D cubical domain)

Parameters:

ima – The image to save
filename – The filename of the output image file

Throws:

std::runtime_error – When the image is not supported for writing (domain or value space), when the file format is not supported or when the image has not been saved.

Example

#include <mln/io/imsave.hpp>

...

auto ima = ...
mln::io::imsave(ima, "/path/to/the/output/image");

CFITSIO plugin

A common file format for astronomy images is the Flexible Image Transport System (FITS). The CFITSIO library handles the reading and the writing of these image. The Pylene library has a plugin only to read these images around CFITSIO. It only handles standard FITS file (this can be checked using FITSVERIFY).

This plugin is contained in the component Pylene::IO-fits, which depends on Pylene::Core. When using it, do not forget to add it in the CMakeLists.txt as below:

target_link_libraries(my_executable PRIVATE Pylene::IO-fits)

Reading images

Include <mln/io/fits/imread.hpp>

mln::ndbuffer_image imread(const std::string &filename, int ind = 0)

Read a FITS file located at filename and return the image in the HDU indexed at ind.

Parameters:

filename – The filename of the FITS file
ind – The index of the HDU containing the image

Returns:

An image

Throws:

std::runtime_error – When the file is incorrect, when the index ind is incorrect, when the HDU at ind is not an image or when the number of dimension is not handled (should be in [1 - 4]).

void imread(const std::string &filename, mln::ndbuffer_image &out, int ind = 0)

Read a FITS file located at filename and store the image in the HDU indexed at ind in the image out.

Parameters:

filename – The filename of the FITS file
out – The output image
ind – The index of the HDU containing the image

Throws:

std::runtime_error – When the file is incorrect, when the index ind is incorrect, when the HDU at ind is not an image or when the number of dimension is not handled (should be in [1 - 4]).