Fundamentals

Table of Contents

• Open an Image
  • Initialization
  • Retrieve view from a file path
  • Load in memory from a file path
  • Get a view from an URI
  • Get a view from any accessor
• Open a stack of files
  • Using a pattern
  • Using a file list
• Export to a format
  • Generic method
  • Advanced method
• Helpers
  • Using formats
• Configuration
  • Logger

Open an Image

Initialization

IOFormat does not necessarily need to be initialized, but it is a way to force plugins to be loaded at start-up, to avoid some latency during the first opening at runtime.

ioformat::init();

Retrieve view from a file path

IOFormat provides methods to directly retrieve a view from a path. The filename extension will determine the format, and thus the extractor to instantiate. Theoretically, IOFormat can handle any kind of format, so this method cannot directly return an ImageView. You will have to check first the type of view returned, and then transform it.

An important note, when opening a resource with openView, only a handle to the resource is kept, the data of the view is not copied in memory, or will be reduced to a minimum.

Concerning images, IOFormat can return three kinds of view:

• ImageView (Readable at minimum)
• MultiImageView (Readable at minimum)
• LodImageView (Readable at minimum)

If a problem happened during the opening, an error will be raised.

auto view = ioformat::openView("tmp/image.tiff");
 
if (iolink::ImageViewProvider::isImage(view))
{
  auto imgView = iolink::ImageViewProvider::toImage(view);
 
  // process image
}
else if (iolink::MultiImageViewProvider::isMultiImage(view))
{
  auto stackView = iolink::MultiImageViewProvider::toMultiImage(view);
 
  // process multi image
}

Load in memory from a file path

Users can decide to directly load in memory the full content of the loaded image. That way, the view is directly created in memory, through a specific method.

For now, this functionality is only for singles-frame images. If the given file contains more than one frame, the method will rise an exception.

auto image = ioformat::readImage("tmp/image.bmp");

Get a view from an URI

You have the possibility to load a view from a URI. This allows to load an image with a network protocol for example.

Remark: In the case of HTTP, the server must support HTTP range requests.

Two methods are available for two distinct cases:

• URI allows to retrieve remote file extension, and thus its supposed format
• URI does not allow to identify file format. Format must be specified at method call.

iolink::Uri uri("https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png");
auto view = ioformat::openView(uri);

If the file format cannot be identified with its URI, its format must be specified:

// for example, a PHP request can point toward an image, but nothing in the request indicates file format
iolink::Uri uri("http://google.com?id=1&name=wayne");
auto view = ioformat::openView(uri, "PNG");

Get a view from any accessor

For any other cases, you can use an accessor as a container for your image to decode. You can have a look into the 'accessor concept' section in IOLink user-guide for more details.

Once you have an accessor to your content, IOFormat provides a method to create a view onto this accessor. On the other hand, you have to specify the format of your data.

Remark: IOLink provides a factory to create a view onto an accessor, but with raw data only (not encoded). This one is different, since data are encoded in the accessor, and only IOFormat has capacities to decode them.

// you have an accessor onto an encoded image (whatever it comes from)
std::shared_ptr<iolink::DataAccess> accessor = .... ;
 
// you know your data represent a PNG image
auto view = ioformat::openView(accessor, "PNG");

Open a stack of files

Using a pattern

The StackReader factory can be used to aggregate files which names follow a pattern into an ImageView. Methods from this factory usually take a pattern and the interpretation of the stacking dimension. The pattern format is quite simple: variable parts of the path are indicated with a wildcard "*". The wildcard must only be in the last segment of the pattern. For example some/dir/img_*.png is valid, where some/dir_*/img_*.png is invalid.

• openImageFromPattern will not load anything in memory, so it is useful for out-of-core mechanics.
• readImageFromPattern will stack the files and then load the resulting view in memory for better performance.

std::shared<iolink::ImageView> img = ioformat::StackReader::openImageFromPattern("some/dir/img_*.png", iolink::ImageDimension::SLICE);

Using a file list

A file list is a file where each line is a path to an image, StackReader::openListFile will open such a file list and create a stacked image using the listed images in order. The StackReader::loadListFile variant do all the same, and then load the stacked image in memory.

Example of an image list:

some/path/to/file.ext
some/other/path/to/file.ext

Code example to load a list file:

std::shared<iolink::ImageView> img = ioformat::StackReader::openImageFromListFile("some/dir/stack.lst", iolink::ImageDimension::SLICE);

Export to a format

Exporting a view into a specific format means encoding your view content into this format. But each format has its own specificities, limitations, and can request some parameters (compression, color, etc.). Hence, each format needs a specific writer.

Generic method

If you need to export your view content into a file or stream, the easiest way is to use the dedicated method. The appropriate writer plugin will be used internally. Default options of writers will be used for encoding.

This is a simple code example:

auto image = iolink::ImageViewFactory::allocate(iolink::VectorXu64{64, 64}, iolink::DataTypeId::UINT8);
 
// image is encoded in PNG in the given file (extension of the file path determines the format)
ioformat::writeView(image, "tmp/image.png");
 
auto outputStream = iolink::StreamAccessFactory::openFile("tmp/image.raw");
 
ioformat::writeView(image, outputStream, "PNG"); // image is encoded in PNG and stored in the given stream
ioformat::writeView(image, outputStream, "MRC"); // image is encoded in MRC and stored in the given stream

Advanced method

You can use advanced API methods to automatically let IOFormat choose the appropriate writer according to the desired output format or the plugin to use directly. All these methods return a writer which could then be used for advanced configuration.

Important remark: a writer can only be used for one writing. If you need to write your data a second time, another writer shall be created.

Following methods are provided in IOFormat API:

static std::shared_ptr<iolink::Writer> openWriter(std::shared_ptr<iolink::View> image,
                                                  const std::string& pathFile);
static std::shared_ptr<iolink::Writer> openWriter(std::shared_ptr<iolink::View> image,
                                                    std::shared_ptr<iolink::StreamAccess> dst,
                                                    const std::string& format);
static std::shared_ptr<iolink::Writer> openWriter(std::shared_ptr<iolink::View> image,
                                                    std::shared_ptr<iolink::StreamAccess> dst,
                                                    const std::string& format,
                                                    const std::string& plugin);

Finally, you can use your created writer as following:

auto image = iolink::ImageViewFactory::allocate(iolink::VectorXu64{64, 64}, iolink::DataTypeId::UINT8);
 
// in this case, we only need to retrieve any writer for a Jpeg compression to
// export data into a "toto.jpeg" file
auto writer = ioformat::openWriter(image, "tmp/toto.jpeg");
 
if (writer)
{
  // using writers allow you to configure the encoding
  writer->setOption("quality", 70); // compression quality is set here
 
  // data are encoded
  writer->writeAll();
}
 
// destroy writer, else it keeps an handle on created file
writer.reset();

With the Writer object, you have possibility to set options for the writing step. In the previous example, the "quality" of compression can be customized.

Helpers

IOFormat API provides some helpers.

Using formats

Some IOFormat APIs require to provide the format to encode or decode a data through a stream. This format is given as a characters string and should textually match with one of the formats supported by the internal plugins.

Example: To encode a view into a stream with JPEG format, you have to specify "JPEG" as format.

A helper exists to easily convert an extension (i.e "jpg" or "png") into a format recognized by IOFormat APIs.

The following example shows how to encode your view into a specific extension which format you don't know:

auto image = iolink::ImageViewFactory::allocate(iolink::VectorXu64{64, 64}, iolink::DataTypeId::UINT8);
 
auto outputStream = iolink::StreamAccessFactory::openFile("tmp/image.raw")
 
// you need to know the format associated to this extension
// if extension is not handled, an exception is raised
std::string format = ioformat::formatFromExtension("ali");
 
// you can now retrieve a writer for this format
auto writer = ioformat::openWriter(image, outputStream, format);

Configuration

Logger

IOFormat can log messages with different level of criticity:

• LOG_OFF: No logging at all
• LOG_CRITICAL: Severe errors that cause premature termination.
• LOG_ERR: runtime errors or unexpected conditions.
• LOG_WARNING: Use of deprecated APIs, poor use of API, "almost" errors, other runtime situations that are undesirable or unexpected, but not necessarily "wrong".
• LOG_INFO: Interesting runtime events (startup/shutdown).
• LOG_DEBUG: Detailed information on the flow through the system.
• LOG_TRACE: Only for "tracing" the code and trying to find one part of a function specifically

User is free to select the level of messages which he's interested to display at runtime.

By default, IOFormat log level is initialized with IOLink log level. Its level can only be specified by initializing a Logger object. before any other IOFormat API call.

iolink::Logger::init(iolink::LogLevel::LOG_INFO);
ioformat::Logger::init(iolink::LogLevel::LOG_ERR);
 
auto view = ioformat::openView("car.png");

In the previous example, the IOLink log level is set at INFO level, and the IOFormat log level is set at the ERROR level.

iolink::Logger::init(iolink::LogLevel::LOG_INFO)
auto view = ioformat::openView("car.png");

In this other example, only the IOLink log level is set. The IOFormat log level is internally initialized at the same level as IOLink.

auto view = ioformat::openView("car.png");
ioformat::Logger::init(iolink::LogLevel::LOG_INFO);

In this last example, the IOFormat log level is set after an IOFormat API call. This last line has no effect.