| IOLink C# 1.11.0

Loading...
Searching...
No Matches
Getting started

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