algorithm allowing registration of features 3d associated to grey signature More...

IPSDKIPLREGISTRATION_API attr::Features3dRegistrationResultPtr	ipsdk::imaproc::registration::greySignedFeatures3dRegistration (const ipsdk::imaproc::attr::Features3dGreySignatureConstPtr &pInGreySignatures3d1, const ipsdk::imaproc::attr::Features3dGreySignatureConstPtr &pInGreySignatures3d2)
	wrapper function for algorithm allowing registration of features 3d associated to grey signature More...

IPSDKIPLREGISTRATION_API attr::Features3dRegistrationResultPtr	ipsdk::imaproc::registration::greySignedFeatures3dRegistration (const ipsdk::imaproc::attr::Features3dGreySignatureConstPtr &pInGreySignatures3d1, const ipsdk::imaproc::attr::Features3dGreySignatureConstPtr &pInGreySignatures3d2, const ipsdk::imaproc::attr::eRegistrationMotionModel3d &inRegMotionModel3d, const ipReal64 inCorrelationThreshold3d, const ipsdk::imaproc::attr::RobustEstimationConfigConstPtr &pInOptRegistrationEstimationConfig)
	wrapper function for algorithm allowing registration of features 3d associated to grey signature More...

Detailed Description

algorithm allowing registration of features 3d associated to grey signature

This algorithm allows automatic computation of a motion transform linking two sets of grey signed features 3d.

This algorithm is composed of two main phasis.

a pairing phasis :

During this phasis, features from first input collection $InGreySignatures3d1$ are associated to features from second collection $InGreySignatures3d2$ . We consider this assignment problem of two sets of input grey signed features 3d as a weighted bipartite assignment problem using correlation of feature signatures as distance. Parameter $InOptCorrelationThreshold3d$ allows to exclude pairs with low correlation value.

a robust motion transform computation phasis :

Robust motion transform computation is by default based on a least median of squares regression technique. This allows to detect and remove outliers formed during pairing phasis. Note that this specific algorithm make the assuption of an outlier ratio lower than 50% (use RANSAC like algorithm to avoid this limitation). Parameter $InOptRegistrationEstimationConfig$ allows to customize behavior of this phasis. See Parametric estimation for more informations on this stage.

Type of computed transformation is controled by $InOptRegMotionModel3d$ parameter.

On output algorithm returned a registration result composed of :

used origin feature signatures
used target feature signatures
the computed transformation allowing to transform data of origin image to target image :
$P_{target}=sR(\chi, \beta, \alpha)P_{origin} + T(T_x, T_y, T_z)$
with :
- a scale factor computed in similarity case (ie. ipsdk::imaproc::attr::eRegistrationMotionModel3d::eRMM3d_Similarity) and equal to 1 in rigid case (ie. ipsdk::imaproc::attr::eRegistrationMotionModel3d::eRMM3d_Rigid).
- $R(\chi, \beta, \alpha)$ a rotation matrix, see Rotations 3d.
- a translation vector
the computed transformation can also be of form :
$\bar{P}_{target}=H \bar{P}_{origin}$
in case of homography motion model (ipsdk::imaproc::attr::eRegistrationMotionModel3d::eRMM2d_Homography) with :
- $\bar{P}$ homogeneous coordinates associated to point
- a 4x4 matrix
a structure agregating indicators about registration results :
- the number of input features in first and second collections
- the number of pairs formed from these two collections (result of pairing phasis)
- the status of robust estimation (see following remark)
- number of detected outliers (greater than 0 if robust estimation has been successfully proceeded)
- root mean square of residuals :
  $\sqrt{\sum_{i=0}^{nbPairs}{\left \|P^i_{target}-\left(sR(\chi, \beta, \alpha)P^i_{origin} + T(T_x, T_y, T_z)\right)\right \|^2}}$
- the collection of made assignments with their coordinates, the associated weight and a flag used to store outlier status of assignment.

Structure agregating indicators should be carefully analyzed by user to check reliability of computed results. Here are some clues to avoid classical pits in robust estimation :

check status of robust estimation, in case where flag RobustEstimationDone is set to false in RobustEstimationResults result structure, algorithm do not have enough pairs of features to process to a robust estimation and switch to simple (non robust) estimation. In this case, algorithm will not support presence of outliers into input data set.
check number of detected outliers, remember that used robust algorithm make the assumption of an outlier ratio lower than 50% (by default).
check value of output rms : a great value for rms means that features are not correctly matched.

See Registration of grey signed features 2d for an illustration of this algorithm applied in 2d case.

See also: https://en.wikipedia.org/wiki/Robust_regression

Attributes description

Attribute description for algorithm :

Name	ToolTip	Default Initializer
ipsdk::imaproc::attr::InGreySignatures3d1	[Input] first collection of features 3d grey signature used during processing	X
ipsdk::imaproc::attr::InGreySignatures3d2	[Input] second collection of features 3d grey signature used during processing	X
ipsdk::imaproc::attr::InOptRegMotionModel3d	[Input Optional] 3d motion model which should be used for computation	X
ipsdk::imaproc::attr::InOptCorrelationThreshold3d	[Input Optional] threshold on 3d correlation scores used during pairs matching	X
ipsdk::imaproc::attr::InOptRegistrationEstimationConfig	[Input Optional] configuration for robust estimation part of features registration	X
ipsdk::imaproc::attr::OutFeatures3dRegistrationResult	[Output] result of features 3d registration algorithm	allocate (_pOutFeatures3dRegistrationResult)

Global Rule description

Global rule description for algorithm :
ipsdk::processor::none ()

Example of Python code :

Example imports

import PyIPSDK
import PyIPSDK.IPSDKIPLFeatureDetection as fd
import PyIPSDK.IPSDKIPLRegistration as registration

Code Example

    # opening of input images
    inImg3d1 = PyIPSDK.loadTiffImageFile(inputImgPath1)
    inImg3d2 = PyIPSDK.loadTiffImageFile(inputImgPath2)
    
    # extraction of grey signed features from first image
    greySignatures1 = registration.extractGreySignedFeatures3d(inImg3d1, 100)
    
    # extraction of grey signed features from second image
    greySignatures2 = registration.extractGreySignedFeatures3d(inImg3d2, 100)
    
    # computation of motion transform between images
    correlationThreshold = 0.95
    estimationConfig = PyIPSDK.EstimationConfig()
    estimationConfig.initLMS(0.48)
    outRegistrationResult = registration.greySignedFeatures3dRegistration(greySignatures1,
                                                                          greySignatures2,
                                                                          PyIPSDK.eRegistrationMotionModel3d.eRMM3d_Similarity,
                                                                          correlationThreshold, estimationConfig)
    transformParams = outRegistrationResult.transform.params
    
    # print of results
    print("Registration results :")
    print("----------------------")
    print("Nb original features : " + str(outRegistrationResult.indicators.nbFeatures1))
    print("Nb target features : " + str(outRegistrationResult.indicators.nbFeatures2))
    print("Nb made pairs : " + str(outRegistrationResult.indicators.nbPairs))
    print("Robust estimation status :")
    print("--------------------------")
    print(outRegistrationResult.indicators.estimationResults.toString())
    print("Estimated motion transform :")
    print("----------------------------")
    print("Scale factor : " + str(transformParams[PyIPSDK.Similarity3d.eTP_Scale]))
    print("Rotation (chi, beta, alpha in radians) : {" + str(transformParams[PyIPSDK.Similarity3d.eTP_Chi]) + ", " + str(transformParams[PyIPSDK.Similarity3d.eTP_Beta]) + ", " + str(transformParams[PyIPSDK.Similarity3d.eTP_Alpha]) + "}")
    print("Translation : {" + str(transformParams[PyIPSDK.Similarity3d.eTP_Tx]) + ", " + str(transformParams[PyIPSDK.Similarity3d.eTP_Ty]) + ", " + str(transformParams[PyIPSDK.Similarity3d.eTP_Tz]) + "}")

Example of C++ code :

Example informations

Associated library

IPSDKIPLRegistration

Header file

#include <IPSDKIPL/IPSDKIPLRegistration/Processor/GreySignedFeatures3dRegistration/GreySignedFeatures3dRegistration.h>

#include <IPSDKIPL/IPSDKIPLRegistration/Processor/ExtractGreySignedFeatures3d/ExtractGreySignedFeatures3d.h>

Code Example

    // Load the input images
    ImagePtr pInImg1 = loadTiffImageFile(inImgFilePath1);
    ImagePtr pInImg2 = loadTiffImageFile(inImgFilePath2);
    // extraction of grey signed features from first image
    Features3dGreySignaturePtr pGreySignatures1 = extractGreySignedFeatures3d(pInImg1, 100);
    // extraction of grey signed features from seconde image
    Features3dGreySignaturePtr pGreySignatures2 = extractGreySignedFeatures3d(pInImg2, 100);
    // computation of motion transform between images
    const ipReal64 correlationThreshold = 0.95;
    const ipReal64 expectedOutlierRatio = 0.48;
    Features3dRegistrationResultPtr pOutRegistrationResult = greySignedFeatures3dRegistration(pGreySignatures1, pGreySignatures2,
                                                                                              eRegistrationMotionModel3d::eRMM3d_Similarity,
                                                                                              correlationThreshold,
                                                                                              createLMSRobustEstimationConfig(expectedOutlierRatio));
    const RegistrationMotionTransform3d& outTransform = pOutRegistrationResult->getNode<Features3dRegistrationResult::Transform>();

See also: GreySignedFeatures3dRegistrationLvl1

Function Documentation

◆ greySignedFeatures3dRegistration() [1/2]

IPSDKIPLREGISTRATION_API attr::Features3dRegistrationResultPtr ipsdk::imaproc::registration::greySignedFeatures3dRegistration	(	const ipsdk::imaproc::attr::Features3dGreySignatureConstPtr &	pInGreySignatures3d1,
		const ipsdk::imaproc::attr::Features3dGreySignatureConstPtr &	pInGreySignatures3d2
	)

wrapper function for algorithm allowing registration of features 3d associated to grey signature

Exceptions

ipsdk::processor::IPSDKBaseProcessingException on failure

◆ greySignedFeatures3dRegistration() [2/2]

IPSDKIPLREGISTRATION_API attr::Features3dRegistrationResultPtr ipsdk::imaproc::registration::greySignedFeatures3dRegistration	(	const ipsdk::imaproc::attr::Features3dGreySignatureConstPtr &	pInGreySignatures3d1,
		const ipsdk::imaproc::attr::Features3dGreySignatureConstPtr &	pInGreySignatures3d2,
		const ipsdk::imaproc::attr::eRegistrationMotionModel3d &	inRegMotionModel3d,
		const ipReal64	inCorrelationThreshold3d,
		const ipsdk::imaproc::attr::RobustEstimationConfigConstPtr &	pInOptRegistrationEstimationConfig
	)

wrapper function for algorithm allowing registration of features 3d associated to grey signature

Exceptions

ipsdk::processor::IPSDKBaseProcessingException on failure