Applies PCA to a sequence image to reduce its dimensionality. More...

IPSDKIPLCLASSIFICATION_API PCAReductionResults	ipsdk::imaproc::classif::pcaReductionImg (const ipsdk::image::ImageConstPtr &pInSeqImg)
	wrapper function for reduction of the dimensionality of a sequence image using PCA More...

IPSDKIPLCLASSIFICATION_API PCAReductionResults	ipsdk::imaproc::classif::pcaReductionImg (const ipsdk::image::ImageConstPtr &pInSeqImg, const ipsdk::imaproc::attr::PCAReductionParamsConstPtr &pParams)
	wrapper function for reduction of the dimensionality of a sequence image using PCA More...

IPSDKIPLCLASSIFICATION_API PCAReductionResults	ipsdk::imaproc::classif::pcaReductionImg (const ipsdk::image::ImageConstPtr &pInSeqImg, const ipsdk::image::ImagePtr &pOutImg)
	wrapper function for reduction of the dimensionality of a sequence image using PCA More...

IPSDKIPLCLASSIFICATION_API PCAReductionResults	ipsdk::imaproc::classif::pcaReductionMaskImg (const ipsdk::image::ImageConstPtr &pInSeqImg, const ipsdk::image::ImageConstPtr &pInOptSingleGreyMaskImg)
	wrapper function for reduction of the dimensionality of a sequence image using PCA and using a mask More...

IPSDKIPLCLASSIFICATION_API PCAReductionResults	ipsdk::imaproc::classif::pcaReductionMaskImg (const ipsdk::image::ImageConstPtr &pInSeqImg, const ipsdk::imaproc::attr::PCAReductionParamsConstPtr &pParams, const ipsdk::image::ImageConstPtr &pInOptSingleGreyMaskImg)
	wrapper function for reduction of the dimensionality of a sequence image using PCA and using a mask More...

IPSDKIPLCLASSIFICATION_API PCAReductionResults	ipsdk::imaproc::classif::pcaReductionMaskImg (const ipsdk::image::ImageConstPtr &pInSeqImg, const ipsdk::image::ImageConstPtr &pInOptSingleGreyMaskImg, const ipsdk::image::ImagePtr &pOutImg)
	wrapper function for reduction of the dimensionality of a sequence image using PCA and using a mask More...

Detailed Description

Applies PCA to a sequence image to reduce its dimensionality.

The primary function of this algorithm is to reduce the temporal dimensionality of an input image (whose sequence elements are assumed to be 0-meaned and have a standard deviation of 1), while preserving the most significant part of information of it. To do that, first the image is reinterpreted as a matrix M with imgSizeC*imgSizeT rows and imgSizeX*imgSizeY*imgSizeZ columns. Each row is made of the pixel values of a sequence element of the input sequence of images.

A principal component analysis is then applied on this matrix M. It consists in:

constructing the covariance matrix $M \times M^T$ (square matrix of dimension $(imgSizeC*imgSizeT) \times (imgSizeC*imgSizeT)$ )
computing the eigen vectors and eigen values on this covariance matrix
keeping the eigen vectors that correspond to the largest eigen values (the principal components)
projecting the initial image on these retained vectors to obtain the output image. The output image has the following property: its sequence elements are completely decorrelated.

The number of largest eigen values retained cannot exceed the number of rows of the matrix, ie. the temporal size multiplied by the number of color channels of the input image. There are several ways for the user to choose the number of the largest eigen values retained (ie. the temporal dimensionality of the output image), depending on the value of InOptPCAReductionParams attribute:

if the parameter and the output image are left uninitialized, this number is initialized to the rank of the covariance matrix
if the parameter is left uninitialized and if the output image is allocated by the user, this number is set to the temporal size of the output image
if the parameter is initialized with the "number of expected sequence elements" criterion, this number is set to the value specfied by the user
if the parameter is initialized with the "variance threshold" criterion (see code example below), this number is set to the lowest number n of largest eigen values that satisfy the following formula: $\frac{\sum\limits_{i=1}^n \lambda_i}{\sum\limits_{i=1}^{sizeC*sizeT} \lambda_i} \geq varianceThresholdValue$ , assuming that ${\lambda_i}$ is the collection of eigen values sorted in decreasing order.

The different signatures of the $ pcaReductionImg $ wrapper functions all return the results in a PCAReductionResults structure, that contains:

the _pOutImg field, that contains the resulting reduced image
the _pEigenValues field, that contains all the eigen values of the covariance matrix, sorted in decreasing order
the _pEigenVectors field, that contains the corresponding eigen vectors (the ith element of the jth vector will be at position j * covariance_matrix_dimension + i in the collection)
the _matrixRank field, that contains the rank of the covariance matrix

Note: It is possible to use only a subet of data, this is done by providing an additional mask image to the algorithm. In this case, the data where the mask equals True are used.

Attributes description

Attribute description for algorithm :

Name	ToolTip	Default Initializer
ipsdk::imaproc::attr::InHomogeneousImg	[Input] Homogeneous image	X
ipsdk::imaproc::attr::InOptSingleGreyMaskImg	[Input Optional] Binary image for masking operation for each (x, y, z) coordinate regardless to (c, t) coordinates	X
ipsdk::imaproc::attr::InOptPCAReductionParams	[Input Optional] Parameters for sequence image dimensionality reduction using a PCA	X
ipsdk::imaproc::attr::OutOptSeqImg	[Output Optional] sequence image for processing operation	X
ipsdk::imaproc::attr::OutPCAEigenValues	[Output] Eigen values of matrix computed for PCA	ipsdk::processor::allocate (_pOutPCAEigenValues)
ipsdk::imaproc::attr::OutPCAEigenVectors	[Output] Eigen vectors of matrix computed for PCA	ipsdk::processor::allocate (_pOutPCAEigenVectors)
ipsdk::imaproc::attr::OutPCAMatrixRank	[Output] Rank of the matrix computed in PCA	X

Global Rule description

Global rule description for algorithm :
ipsdk::processor::ifIsSet (_pOutOptSeqImg,
ipsdk::imaproc::matchSize (eMatchImageSizeType::eMIST_3d,_pInHomogeneousImg,_pOutOptSeqImg) &&
ipsdk::processor::If (
ipsdk::processor::isSet (_pInOptPCAReductionParams), ipsdk::processor::isEqual<attr::PCAReductionParams::Criterion>(_pInOptPCAReductionParams,attr::ePCAReductionCriterion::ePCARC_ExpectedNbEltsInSequence) && matchSize<attr::PCAReductionParams::NbExpectedElementsInSequence>(eMatchImageSizeType::eMIST_T,eMatchImageSizeScale::eMISS_FullSize,_pOutOptSeqImg,_pInOptPCAReductionParams),
img1SizeTLowerEqualImg2SizeCSizeTProduct (_pInHomogeneousImg,_pOutOptSeqImg))) &&
ipsdk::processor::If (
ipsdk::processor::isSet (_pInOptPCAReductionParams) && ipsdk::processor::isEqual<attr::PCAReductionParams::Criterion>(_pInOptPCAReductionParams,attr::ePCAReductionCriterion::ePCARC_ExpectedNbEltsInSequence),
expectedEltInOutSeqLowerEqualInImgSizeCSizeTProduct (_pInHomogeneousImg,_pInOptPCAReductionParams),
ipsdk::processor::none ()) &&
ipsdk::processor::ifIsSet (_pInOptSingleGreyMaskImg,
ipsdk::imaproc::matchSize (eMatchImageSizeType::eMIST_3d,_pInHomogeneousImg,_pInOptSingleGreyMaskImg))

Example of Python code :

Example imports

import PyIPSDK

import PyIPSDK.IPSDKIPLClassification as classif

Code Example

    # opening of input image
    inImg = PyIPSDK.loadTiffImageFile(inputImgPath)
    
    outImg, outEigenValues, outEigenVectors, outMatrixRank = classif.pcaReductionImg(inImg)

Example of C++ code :

Example informations

Associated library

IPSDKIPLClassification

Header file

#include <IPSDKIPL/IPSDKIPLClassification/Processor/PCAReductionImg/PCAReductionImg.h>

Code Example

    // load input image from file
    ImagePtr pInImg = loadTiffImageFile(inputImgPath);
    // apply PCA reduction algorithm on input image; we only keep the first principal
    // sequence elements, that satisfy the variance threshold criterion, with a variance
    // threshold that equals to 0.9
    PCAReductionResults res = pcaReductionImg(pInImg, attr::createVarianceThresholdForPCAReduction(0.9f));
    // retrieve resulting reduced image
    ImagePtr pOutImg = res._pOutImg;

See also: PCAReductionImgLvl1

Function Documentation

◆ pcaReductionImg() [1/3]

IPSDKIPLCLASSIFICATION_API PCAReductionResults ipsdk::imaproc::classif::pcaReductionImg ( const ipsdk::image::ImageConstPtr & pInSeqImg )

wrapper function for reduction of the dimensionality of a sequence image using PCA

Exceptions