DGtal
1.5.beta
|
Part of the Image package
Large images like tiled images, HDF5 images, ... can be handled in DGtal.
For this, we provide two important mechanisms: an image factory mechanism and an image cache mechanism with read and write policies.
The image factory is necessary to keep control on the created images. As its responsibility is to create images according to a given domain. The factory can update (flush) the image on disk and also can free the image from memory. Image factory models can associated with specific image formats such as HDF5 which can be activated using a WITH_HDF5 flag during DGtal build (please refer to Building DGtal). This mechanism is a DGtal concept called CImageFactory which is detailed below.
As we want to take also into account large images effectively, we also need a cache mechanism to access to subsets, so called tiles, of such images.
The cache has the responsibility to store tiles and giving us read and write access to them. The reading, writing and updating mechanisms of the cache are controlled with two policies: the read and the write policies. These policies are DGtal concepts called respectively CImageCacheReadPolicy and CImageCacheWritePolicy which are detailed just below.
The cache process is rather simple. It consists of three important methods that are detailed here:
read
function returns true and get the value of an image from cache at a given position given by a point only if that point belongs to an image from cache, else returns false.write
function returns true and set the value of an image from cache at a given position given by a point only if that point belongs to an image from cache, else returns false.update
function update the cache according to the read policy.Any model of the concept CImageFactory must have this nested type:
Moreover, it must have the following methods:
requestImage
, which takes a domain as input parameter and returns an OutputImage pointer on the created image.flushImage
, which takes an OutputImage pointer as input parameter in order to flush/synchronize it on disk.detachImage
, which takes an OutputImage pointer as input parameter in order to delete/release it.Cache policies concepts are divided in two concepts: read and write policies.
Any model of the concept CImageCacheReadPolicy must have this nested type:
Moreover, it must have the following methods:
getPage
, which takes a point as input parameter and returns an ImageContainer pointer on the image that contains the point or NULL if no image in the cache contains that point.getPage
, which takes a domain as input parameter and returns an ImageContainer pointer on the image that contains the domain or NULL if no image in the cache contains that domain.getPageToDetach
, which returns an ImageContainer pointer on the image that we have to detach or NULL if no image have to be detached.updateCache
, which takes a domain as input parameter in order to update the cache according to the defined cache policy.clearCache
, which clears the cache.Any model of the concept CImageCacheWritePolicy must have this nested type:
Moreover, it must have the following methods:
writeInPage
, which takes an ImageContainer pointer, a point and a value for that point as input parameters in order to set the value on the image at the position given by the point.flushPage
, which takes an ImageContainer pointer as input parameter in order to flush the image on disk according to the defined cache policy.Cache policies models are split into read and write policies.
The TiledImage is a simple class that implements a tiled image from a "bigger/original" one from an ImageFactory.
The tiled image is created from an existing image and with four parameters:
Concerning the cache mechanism explained at the top of this document, the accessor operator()
(i.e. the getter) and the setter setValue
are therefore really simple to write for the TiledImage class:
In order to illustrate the next TiledImage usage sample, we are going a) to use these includes:
b) then define these type and variable:
c) then define a simple 16x16 (1,1) to (16,16) image (of 'int' type):
filled with 1 to 256 values like that:
which looks like that with a simple HueShadeColorMap varying from 1 to 256 and with (1,1) the first bottom-left point:
Here is now the construction of a simple 4x4 tiled image with therefore 16 subdomains of the initial image domain. The tiled image is created from an existing image and with four parameters. The first parameter is an alias on the image factory (see ImageFactoryFromImage). The second parameter is an alias on a read policy. The third parameter is an alias on a write policy. The fourth parameter is to set how many tiles we want for each dimension:
In this sample, we are going to work only with the 8 bottom subdomains of the original image.
At the beginning the cache is empty.
First we want to read the point 4,2 (which is in domain 1),
so after that the cache is (domain1,empty). Here is the domain1:
Then we want to read the point 10,6 (which is in domain 7),
so after that the cache is (domain1,domain7). Here is the domain7:
Then we want to set the value of the point 11,7 to 1 (which is in domain 7),
so after that the cache is always (domain1,domain7). Here is the new domain7 after writing:
Then we want to read the point 2,3 (which is in domain 1),
so after that the cache is always (domain1,domain7). Here is the domain1:
Then we want to read the point 16,1 (which is in domain 4),
so after that the cache is (domain7,domain4). Here is the domain4:
Then we want to set the value of the point 16,1 to 128 (which is in domain 4),
so after that the cache is always (domain7,domain4). Here is the new domain4 after writing:
And finally, here is the modified original image after the two writings.