IPSDK Concepts documentation See full documentation

Introduction

An IPSDK sub-image represents one or several planes extracted from an image. Hence, it is possible to easily extract a frame or a sub-sequence from an image sequence, a channel from a color volume sequence resulting to a grey level volume sequence, etc.

The result is not a copy of the initial image but a pointer to the same buffer. This means that its geometry information only differs for the Z, color and temporal dimensions in order to correspond to the sub-image features. The sizes along the x an y axis and its buffer type remain unchanged. To obtain a copy of a sub-image (including in the x and y dimensions), please see the getROI2dImg or getROI3dImg algorithm in the IPSDKIPLUtility module of the IPSDKIPL documentation.

Extract a sub-image

Extract a sub-image fragment in C++

All the possible image extraction functions are documented in this page. In order to use them, the following header must be included :

#include <IPSDKImage/Fragment/Extractor/SubImageExtractor.h>

We illustrate by examples how to use these functions. We also consider that the initial image pInImg is a 3d color image sequence, i.e. sizeZ, sizeC and sizeT > 1. The following figure represents this image. In this example, the image contains 4 frames and each frame is represented by three adjacent cubes (red, green and blue) corresponding to the color channels of the 3d data. The channels are divided into three slices, which means that we chose sizeZ == 3.

In the first example, we simply extract a plan from the initial image.

// Example 1 : Extract a 2d grey level slice
ImagePtr pSubImg_Plan;
SubImageExtractor::extractPlan(0, 2, 1, *pInImg, pSubImg_Plan);

The extracted plan is the blue channel (color index = 2) of the first slice (volume index = 0) in the second frame (index = 1). Thus, we will get pSubImg_Plan->getSizeZ() == pSubImg_Plan->getSizeC() == pSubImg_Plan->getSizeT() == 1.

The figure bellow illustrates the result :

The second example shows how to extract the 3d grey level image corresponding to the blue channel (color index = 2) from the second frame (index = 1) of the initial color volume sequence.

// Example 2 : Extract a 3d grey level volume
ImagePtr pSubImg_Volume;
SubImageExtractor::extractVolume(2, 1, *pInImg, pSubImg_Volume);

Here, pSubImg_Volume->getSizeZ() == pInImg->getSizeZ() and pSubImg_Volume->getSizeC() == pSubImg_Volume->getSizeT() == 1.

The result can be represented by the figure below :

In the third example, the result corresponds to the three channels of the first slice (volume index = 0) in the second frame (index = 1) : pSubImg_Color->getSizeZ() == 1, pSubImg_Color->getSizeC() == pInImg->getSizeC() and pSubImg_Color->getSizeT() == 1.

// Example 3 : Extract a 2d color channel from a slice of a frame
ImagePtr pSubImg_Color;
SubImageExtractor::extractColor(0, 1, *pInImg, pSubImg_Color);

The following figure illustrates the result :

In the same way, the fourth example shows how to extract the blue channel (color index = 2) of the first slice (volume index = 0) from each frame : pSubImg_Temporal->getSizeZ() == pSubImg_Temporal->getSizeC() == 1 and pSubImg_Temporal->getSizeT() == pInImg->getSizeT().

// Example 4 : Extract a 2d channel sequence from a 3d color sequence
ImagePtr pSubImg_Temporal;
SubImageExtractor::extractTemporal(0, 2, *pInImg, pSubImg_Temporal);

The result can be represented by the figure below :

The result of the fifth example is the second frame (index = 1) : a color volume.

// Example 5 : Extract a 3d color volume
ImagePtr pSubImg_ColorVolume;
SubImageExtractor::extractColorVolume(1, *pInImg, pSubImg_ColorVolume);

In this case, we have pSubImg_ColorVolume->getSizeZ() == pInImg->getSizeZ(), pSubImg_ColorVolume->getSizeC() == pInImg->getSizeC() and pSubImg_ColorVolume->getSizeT() == 1.

Here is the result of the example :

In the 6th example, the result is a sequence of grey level data : only the blue channel is kept for each slice of each frame of the volume sequence : pSubImg_TemporalVolume->getSizeZ() == pInImg->getSizeZ(), pSubImg_TemporalVolume->getSizeC() == 1 and pSubImg_TemporalVolume->getSizeT() == pInImg->getSizeT().

// Example 6 : Extract a 3d grey level volume sequence
ImagePtr pSubImg_TemporalVolume;
SubImageExtractor::extractTemporalVolume(2, *pInImg, pSubImg_TemporalVolume);

The following figure illustrates the result :

In the 7th example, the result is a sequence of 2d color data : only the first slice (volume index = 0) is extracted : pSubImg_TemporalColor->getSizeZ() == 1, pSubImg_TemporalColor->getSizeC() == pInImg->getSizeC() and pSubImg_TemporalColor->getSizeT() == pInImg->getSizeT().

// Example 7 : Extract a 2d color image sequence
ImagePtr pSubImg_TemporalColor;
SubImageExtractor::extractTemporalColor(2, *pInImg, pSubImg_TemporalColor);

The following figure illustrates the result :

The result of the 8th example is a sub sequence of the initial image : in this case we keep only the frames 3 and 4 : we set temporalStartOffset == temporalSize == 2. Hence, we have pSubImg_SubSequence->getSizeZ() == pInImg->getSizeZ(), pSubImg_SubSequence->getSizeC() == pInImg->getSizeC() and pSubImg_SubSequence->getSizeT() == temporalSize.

// Example 8 : Extract a sub-sequence
ImagePtr pSubImg_SubSequence;
SubImageExtractor::extractSubSequence(2, 2, *pInImg, pSubImg_SubSequence);

The following figure illustrates the result :

Finally, the 9th example shows how to extract a sub volume from each volume of the initial image sequence. In this case, we exrtact the two first slices from each initial color volume. The dimensions of the resulting sub-image are pSubImg_SubVolume->getSizeZ() == volSize, pSubImg_SubVolume->getSizeC() == pInImg->getSizeC() and pSubImg_SubVolume->getSizeT() == pInImg->getSizeT().

// Example 9 : Extract a 3d sub-volume, the sub volume can have 1 or 3 channel(s) and sizeT >= 1
ImagePtr pSubImg_SubVolume;
SubImageExtractor::extractSubVolume(0, 2, *pInImg, pSubImg_SubVolume);

The result can be represented by the figure :

The volumes appear thiner than in the first figure. Indeed, extractSubVolume() reduces the number of slices, which means that the sub image has a lower size along the z-axis.

Extract a sub-image in Python

IPSDK have wrappers allowing to use these functions in Python. Here are the Python translation of the examples above :

# Do not forget to import the IPSDK library
import PyIPSDK

# Load the initial image
inImg = PyIPSDK.loadTiffImageFile(imgPath)

# Example 1
subImg_Plan = PyIPSDK.extractPlan(0, 2, 1, inImg);

# Example 2
subImg_Volume = PyIPSDK.extractVolume(2, 1, inImg);

# Example 3
subImg_Color = PyIPSDK.extractColor(0, 1, inImg);

# Example 4
subImg_Temporal = PyIPSDK.extractTemporal(0, 2, inImg);

# Example 5
subImg_ColorVolume = PyIPSDK.extractColorVolume(1, inImg);

# Example 6
subImg_TemporalVolume = PyIPSDK.extractTemporalVolume(2, inImg);

# Example 7
subImg_TemporalColor = PyIPSDK.extractTemporalColor(0, inImg);

# Example 8
subImg_SubSequence = PyIPSDK.extractSubSequence(temporalStartOffset, temporalSize, inImg);

# Example 9
subImg_SubVolume = PyIPSDK.extractSubVolume(volStartOffset, volSize, inImg);

If the reader has already seen the Numpy array brigde page, he may want to convert these sub-images into Python numpy arrays. However, this is not possible since the extraction result is a sub-image of the initial data and has a different IPSDK type.

If the user wants to get a numpy array from an IPSDK image, he must convert the hole image into a numpy arrays first and then use numpy functionnalities to extract the sub-data.

Concatenate several images

IPSDK allows to concatenate two or more images, whether along the Z-axis or the temporal dimension (the images must have the same size along the other dimensions). This is done by the functions concatenateVolumes and concatenateSequences respectively.

Concatenate several images in C++

// Declare the image collection
std::vector<ImagePtr> vImages;
vImages.push_back(pInImg1);
vImages.push_back(pInImg2);
ImagePtr pConcatImg;

// Concatenate allong the z-axis
SubImageExtractor::concatenateVolumes(vImages, pConcatImg);

// Concatenate allong the temporal dimension
SubImageExtractor::concatenateSequences(vImages, pConcatImg);

Concatenate several images in Python

Unlike the C++ functions where we can concatenate more than two images, the Python versions allow to concatenate only 2 images :

volConcatImg = PyIPSDK.concatenateVolumes(img1, img2)
seqConcatImg = PyIPSDK.concatenateSequences(img1, img2)