Introduction

First of all, IOLink does not allow to open and decode files. It is not its purpose. See IOFormat component for this need.

IOLink defines a set of interfaces, mainly inheriting from View, to enable better inter-libraries communication. It also provides some common implementations of these interfaces, like the memory ImageView for example.

Creation of your first ImageView

You can use IOFormat to open a view onto a specific encoded file, if the format is supported. Or you can implement your own reader, that we call extractors, using the ImageView interface.

But, to simply create an in-memory view, from scratch, you can use ImageViewFactory.

The common interfaces implementations, like the in-memory ImageView, are defined in factories. There is a factory for each kind of view in IOLink, with each method outputting a view of this specific interface. Thus, to create an in-memory ImageView, you will use ImageViewFactory as follows:

ImageView image = ImageViewFactory.Allocate(VectorXu64(100,200), DataTypeId.UINT8)

With this line of code, you requested to create an empty 2-dimensional ImageView whose size is 100 x 200, and each pixel is a 8 bits unsigned value.

As you can see, views are stored through shared pointers (from C++ standard library), and it ensures that the view's memory will be automatically handled. A memory buffer is allocated to store that image's data, and will only be released when last shared pointer on the view is freed.

You could also request for more complex formats, such as a three-dimensional image, by passing a higher dimension vector as the first parameter.

ImageView image = ImageViewFactory.Allocate(new VectorXu64(100, 200, 15), DataTypeId.UINT16)

This time, a larger memory area (100 x 200 x 15 x 2 bytes) is allocated.

This new image could be a video or a volume. In fact, it could be any kind of three-dimensional image. Currently, it does not matter.

Access to image content

Capabilities

ImageView instances support a set of capabilities, that are needed to call some of its methods.

An ImageView capabilities can be tested in different ways:

// tests if this image support the READ capability
image.Capabilities.Has(ImageCapability.READ);
 
// shorter version
image.Support(ImageCapability.READ);

Useful image properties

From your ImageView instance, you have access to basic information about the image: shape, data type, properties, and metadata.

You can access this information directly with an ImageView object:

ImageView image = ImageViewFactory.Allocate(new VectorXu64(100, 200), DataTypeId.UINT8);
 
VectorXu64 shape = image.Shape;
// shape is {100,200}
 
DataType dtype = image.Type;
// type is datatype::UINT8
 
ReadonlyImageProperties properties = image.Properties;
// a collection of properties of the image
 
ReadonlyMetadataNode metadata = image.Metadata;
// the metadata tree of the image

Read pixels

When an ImageView instance supports the READ capability, you can read its pixels. Most of ImageView instances returned by ImageViewFactory support that capability.

You can read one pixel at a time:

ImageView image = ImageViewFactory.Allocate(new VectorXu64(100, 200), DataTypeId.UINT8);
 
byte pixelValue[1];
VectorXu64 index = new VectorXu64(16, 32);
image.Read(index, pixelValue);

With this code, you read the pixel value at position (16,32). The pixelValue variable is of unsigned 8 bits type as in the ImageView data type information.

You also can read a region of your image, as follows:

// create a small region in the image
RegionXu64 region = new RegionXu64(new VectorXu64(0, 0), new VectorXu64(16, 32));
 
// allocate a memory buffer of region size
ulong bufferSize = region.ElementCount * image.Type.ByteCount();
byte buffer[bufferSize];
 
// read the region content into the buffer
image.ReadRegion(region, buffer);
 
// You can make the method returning an array by removing the last argument
byte[] data = image.ReadRegion(region);

Here we read a region defined by its origin and its size in the original image. A memory buffer correctly allocated is needed before calling the method. The RegionXu64 provides a method to get the number of elements in this region.

Write pixels

The WRITE capability of ImageView provides support for methods to write data into the image.

We can write a pixel:

byte pixelValue[] = {15};
VectorXu64 index = new VectorXu64(16, 32);
image.Write(index, pixelValue);

Here we wrote the pixel value 15 at position (16, 32) in our image.

Same thing to write a region of the image:

RegionXu64 region(new VectorXu64(0, 0), new VectorXu64(16, 32));
 
ulong bufferSize = region.ElementCount * image.Type.ByteCount();
byte buffer[bufferSize];
// write data into buffer...
 
image.WriteRegion(region, buffer);

Conclusion

Now, with these examples, you can apply basic Image modifications in memory. See the How To section for more details.

Table of Contents