Manipulating sub-parts of images with IPSDK. More...

Functions
template<typename ImageType >
static BoolResult	ipsdk::image::SubImageExtractor::extractPlan (const ipUInt64 zPlanIdx, const ipUInt64 cPlanIdx, const ipUInt64 tPlanIdx, ImageType &inputImage, boost::shared_ptr< ImageType > &pSubImage)
	extraction of a sub image composed of a single plan from an other image More...

template<typename ImageType >
static BoolResult	ipsdk::image::SubImageExtractor::extractVolume (const ipUInt64 cPlanIdx, const ipUInt64 tPlanIdx, ImageType &inputImage, boost::shared_ptr< ImageType > &pSubImage)
	extraction of a sub image composed of a 3d volume from an other image More...

template<typename ImageType >
static BoolResult	ipsdk::image::SubImageExtractor::extractColor (const ipUInt64 zPlanIdx, const ipUInt64 tPlanIdx, ImageType &inputImage, boost::shared_ptr< ImageType > &pSubImage)
	extraction of a sub image composed of color plans from an other image More...

template<typename ImageType >
static BoolResult	ipsdk::image::SubImageExtractor::extractTemporal (const ipUInt64 zPlanIdx, const ipUInt64 cPlanIdx, ImageType &inputImage, boost::shared_ptr< ImageType > &pSubImage)
	extraction of a sub image composed of sequence plans from an other image More...

template<typename ImageType >
static BoolResult	ipsdk::image::SubImageExtractor::extractColorVolume (const ipUInt64 tPlanIdx, ImageType &inputImage, boost::shared_ptr< ImageType > &pSubImage)
	extraction of a sub image composed of a color 3d volume from an other image More...

template<typename ImageType >
static BoolResult	ipsdk::image::SubImageExtractor::extractTemporalVolume (const ipUInt64 cPlanIdx, ImageType &inputImage, boost::shared_ptr< ImageType > &pSubImage)
	extraction of a sub image composed of a sequence 3d volume from an other image More...

template<typename ImageType >
static BoolResult	ipsdk::image::SubImageExtractor::extractTemporalColor (const ipUInt64 zPlanIdx, ImageType &inputImage, boost::shared_ptr< ImageType > &pSubImage)
	extraction of a sub image composed of sequence color plans from an other image More...

template<typename ImageType >
static BoolResult	ipsdk::image::SubImageExtractor::extractSubSequence (const ipUInt64 temporalStartOffset, const ipUInt64 temporalSize, ImageType &inputImage, boost::shared_ptr< ImageType > &pSubImage)
	extraction of a sub image composed of a sub sequence from an other image More...

template<typename ImageType >
static BoolResult	ipsdk::image::SubImageExtractor::extractSubVolume (const ipUInt64 volStartOffset, const ipUInt64 volSize, ImageType &inputImage, boost::shared_ptr< ImageType > &pSubImage)
	extraction of a sub image composed of a sub volume from an other image More...

template<typename ImageType >
static BoolResult	ipsdk::image::SubImageExtractor::extractCudaSubImage (const ipUInt64 deviceIdx, ImageType &inputImage, boost::shared_ptr< ImageType > &pSubImage)
	extraction of a sub image composed located on Cuda devices / A Cuda image can be splitted and dispatched on several devices / This function returns the buffer of a specific device / More...

template<typename ImageType >
static BoolResult	ipsdk::image::SubImageExtractor::concatenateSequences (const std::vector< boost::shared_ptr< ImageType > > &inputImages, boost::shared_ptr< ImageType > &pSubImage)
	generation of a sub image composed of the concatenation of 2 or more sequence images More...

template<typename ImageType >
static BoolResult	ipsdk::image::SubImageExtractor::concatenateVolumes (const std::vector< boost::shared_ptr< ImageType > > &inputImages, boost::shared_ptr< ImageType > &pSubImage)
	generation of a sub image composed of the volume concatenation of 2 or more 3d images More...

Detailed Description

Manipulating sub-parts of images with IPSDK.

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)

Function Documentation

◆ extractPlan()

template<typename ImageType >

static BoolResult ipsdk::image::SubImageExtractor::extractPlan	(	const ipUInt64	zPlanIdx,
		const ipUInt64	cPlanIdx,
		const ipUInt64	tPlanIdx,
		ImageType &	inputImage,
		boost::shared_ptr< ImageType > &	pSubImage
	)

static

extraction of a sub image composed of a single plan from an other image

Exceptions

ipsdk::image::IPSDKImageException	if zPlanIdx >= inputImage.getSizeZ()
ipsdk::image::IPSDKImageException	if cPlanIdx >= inputImage.getSizeC()
ipsdk::image::IPSDKImageException	if tPlanIdx >= inputImage.getSizeT()

Returns: false in case of failure

◆ extractVolume()

template<typename ImageType >

static BoolResult ipsdk::image::SubImageExtractor::extractVolume	(	const ipUInt64	cPlanIdx,
		const ipUInt64	tPlanIdx,
		ImageType &	inputImage,
		boost::shared_ptr< ImageType > &	pSubImage
	)

static

extraction of a sub image composed of a 3d volume from an other image

Exceptions

ipsdk::image::IPSDKImageException	if cPlanIdx >= inputImage.getSizeC()
ipsdk::image::IPSDKImageException	if tPlanIdx >= inputImage.getSizeT()
ipsdk::image::IPSDKImageException	if inputImage.getVolumeGeometryType() != eVolumeGeometryType::eVGT_3d

Returns: false in case of failure

◆ extractColor()

template<typename ImageType >

static BoolResult ipsdk::image::SubImageExtractor::extractColor	(	const ipUInt64	zPlanIdx,
		const ipUInt64	tPlanIdx,
		ImageType &	inputImage,
		boost::shared_ptr< ImageType > &	pSubImage
	)

static

extraction of a sub image composed of color plans from an other image

Exceptions

ipsdk::image::IPSDKImageException	if zPlanIdx >= inputImage.getSizeZ()
ipsdk::image::IPSDKImageException	if tPlanIdx >= inputImage.getSizeT()
ipsdk::image::IPSDKImageException	if inputImage.getColorGeometryType() == eColorGeometryType::eCGT_Grey

Returns: false in case of failure

◆ extractTemporal()

template<typename ImageType >

static BoolResult ipsdk::image::SubImageExtractor::extractTemporal	(	const ipUInt64	zPlanIdx,
		const ipUInt64	cPlanIdx,
		ImageType &	inputImage,
		boost::shared_ptr< ImageType > &	pSubImage
	)

static

extraction of a sub image composed of sequence plans from an other image

Exceptions

ipsdk::image::IPSDKImageException	if zPlanIdx >= inputImage.getSizeZ()
ipsdk::image::IPSDKImageException	if cPlanIdx >= inputImage.getSizeC()
ipsdk::image::IPSDKImageException	if inputImage.getTemporalGeometryType() != eTemporalGeometryType::eTGT_Sequence

Returns: false in case of failure

◆ extractColorVolume()

template<typename ImageType >

static BoolResult ipsdk::image::SubImageExtractor::extractColorVolume	(	const ipUInt64	tPlanIdx,
		ImageType &	inputImage,
		boost::shared_ptr< ImageType > &	pSubImage
	)

static

extraction of a sub image composed of a color 3d volume from an other image

Exceptions

ipsdk::image::IPSDKImageException	if tPlanIdx >= inputImage.getSizeT()
ipsdk::image::IPSDKImageException	if inputImage.getVolumeGeometryType() != eVolumeGeometryType::eVGT_3d
ipsdk::image::IPSDKImageException	if inputImage.getColorGeometryType() == eColorGeometryType::eCGT_Grey

Returns: false in case of failure

◆ extractTemporalVolume()

template<typename ImageType >

static BoolResult ipsdk::image::SubImageExtractor::extractTemporalVolume	(	const ipUInt64	cPlanIdx,
		ImageType &	inputImage,
		boost::shared_ptr< ImageType > &	pSubImage
	)

static

extraction of a sub image composed of a sequence 3d volume from an other image

Exceptions

ipsdk::image::IPSDKImageException	if cPlanIdx >= inputImage.getSizeC()
ipsdk::image::IPSDKImageException	if inputImage.getVolumeGeometryType() != eVolumeGeometryType::eVGT_3d
ipsdk::image::IPSDKImageException	if inputImage.getTemporalGeometryType() != eTemporalGeometryType::eTGT_Sequence

Returns: false in case of failure

◆ extractTemporalColor()

template<typename ImageType >

static BoolResult ipsdk::image::SubImageExtractor::extractTemporalColor	(	const ipUInt64	zPlanIdx,
		ImageType &	inputImage,
		boost::shared_ptr< ImageType > &	pSubImage
	)

static

extraction of a sub image composed of sequence color plans from an other image

Exceptions

ipsdk::image::IPSDKImageException	if zPlanIdx >= inputImage.getSizeZ()
ipsdk::image::IPSDKImageException	if inputImage.getColorGeometryType() == eColorGeometryType::eCGT_Grey
ipsdk::image::IPSDKImageException	if inputImage.getTemporalGeometryType() != eTemporalGeometryType::eTGT_Sequence

Returns: false in case of failure

◆ extractSubSequence()

template<typename ImageType >

static BoolResult ipsdk::image::SubImageExtractor::extractSubSequence	(	const ipUInt64	temporalStartOffset,
		const ipUInt64	temporalSize,
		ImageType &	inputImage,
		boost::shared_ptr< ImageType > &	pSubImage
	)

static

extraction of a sub image composed of a sub sequence from an other image

Exceptions

ipsdk::image::IPSDKImageException	if temporalSize == 0
ipsdk::image::IPSDKImageException	if inputImage.getTemporalGeometryType() != eTemporalGeometryType::eTGT_Sequence
ipsdk::image::IPSDKImageException	if temporalStartOffset + temporalSize >= inputImage.getSizeT()

Returns: false in case of failure

◆ extractSubVolume()

template<typename ImageType >

static BoolResult ipsdk::image::SubImageExtractor::extractSubVolume	(	const ipUInt64	volStartOffset,
		const ipUInt64	volSize,
		ImageType &	inputImage,
		boost::shared_ptr< ImageType > &	pSubImage
	)

static

extraction of a sub image composed of a sub volume from an other image

Exceptions

ipsdk::image::IPSDKImageException	if volumeSize == 0
ipsdk::image::IPSDKImageException	if inputImage.getVolumeGeometryType() != eVolumeGeometryType::eVGT_Volume
ipsdk::image::IPSDKImageException	if volStartOffset + volSize >= inputImage.getSizeZ()

Returns: false in case of failure

◆ extractCudaSubImage()

template<typename ImageType >

static BoolResult ipsdk::image::SubImageExtractor::extractCudaSubImage	(	const ipUInt64	deviceIdx,
		ImageType &	inputImage,
		boost::shared_ptr< ImageType > &	pSubImage
	)

static

extraction of a sub image composed located on Cuda devices / A Cuda image can be splitted and dispatched on several devices / This function returns the buffer of a specific device /

/

Exceptions

ipsdk::image::IPSDKImageException if / deviceIdx >= number of buffer composing the entire image /

◆ concatenateSequences()

template<typename ImageType >

static BoolResult ipsdk::image::SubImageExtractor::concatenateSequences	(	const std::vector< boost::shared_ptr< ImageType > > &	inputImages,
		boost::shared_ptr< ImageType > &	pSubImage
	)

static

generation of a sub image composed of the concatenation of 2 or more sequence images

Exceptions

ipsdk::image::IPSDKImageException	if all input images have not the same size along x-axis
ipsdk::image::IPSDKImageException	if all input images have not the same size along y-axis
ipsdk::image::IPSDKImageException	if all input images have not the same size along z-axis
ipsdk::image::IPSDKImageException	if all input images have not the same number of color channels
ipsdk::image::IPSDKImageException	if all input images have not the same color geometry type
ipsdk::image::IPSDKImageException	if all input images have not the same volume geometry type

Returns: false in case of failure

◆ concatenateVolumes()

template<typename ImageType >

static BoolResult ipsdk::image::SubImageExtractor::concatenateVolumes	(	const std::vector< boost::shared_ptr< ImageType > > &	inputImages,
		boost::shared_ptr< ImageType > &	pSubImage
	)

static

generation of a sub image composed of the volume concatenation of 2 or more 3d images

Exceptions

ipsdk::image::IPSDKImageException	if all images have not the same size along x-axis
ipsdk::image::IPSDKImageException	if all images have not the same size along y-axis
ipsdk::image::IPSDKImageException	if all images have not the same sequence size
ipsdk::image::IPSDKImageException	if all images have not the same temporal geometry type
ipsdk::image::IPSDKImageException	if all images have not the same number of color channels
ipsdk::image::IPSDKImageException	if all images have not the same color geometry type

Returns: false in case of failure

Functions

Detailed Description

Introduction

Extract a sub-image

Extract a sub-image fragment in C++

Extract a sub-image in Python

Concatenate several images

Concatenate several images in C++

Concatenate several images in Python

Function Documentation

◆ extractPlan()

◆ extractVolume()

◆ extractColor()

◆ extractTemporal()

◆ extractColorVolume()

◆ extractTemporalVolume()

◆ extractTemporalColor()

◆ extractSubSequence()

◆ extractSubVolume()

◆ extractCudaSubImage()

◆ concatenateSequences()

◆ concatenateVolumes()