Package com.irurueta.ar.epipolar.refiners

Class FundamentalMatrixRefiner

java.lang.Object

com.irurueta.geometry.refiners.Refiner<T>

com.irurueta.geometry.refiners.InliersDataRefiner<T>

com.irurueta.geometry.refiners.PairMatchesAndInliersDataRefiner<FundamentalMatrix,com.irurueta.geometry.Point2D,com.irurueta.geometry.Point2D>

com.irurueta.ar.epipolar.refiners.FundamentalMatrixRefiner

public class FundamentalMatrixRefiner
extends com.irurueta.geometry.refiners.PairMatchesAndInliersDataRefiner<FundamentalMatrix,com.irurueta.geometry.Point2D,com.irurueta.geometry.Point2D>

Refines a fundamental matrix by taking into account an initial estimation, inlier matches and their residuals. This class can be used to find a solution that minimizes error of inliers in LMSE terms. Typically, a refiner is used by a robust estimator, however it can also be useful in some other situations.

Field Summary

Fields

Modifier and Type	Field	Description
private double	refinementStandardDeviation	Standard deviation used for Levenberg-Marquardt fitting during refinement.
private final com.irurueta.geometry.Line2D	testLine	Test line to compute epipolar residuals.

Fields inherited from class com.irurueta.geometry.refiners.PairMatchesAndInliersDataRefiner

samples1, samples2

Fields inherited from class com.irurueta.geometry.refiners.InliersDataRefiner

inliers, numInliers, residuals

Fields inherited from class com.irurueta.geometry.refiners.Refiner

covariance, DEFAULT_KEEP_COVARIANCE, initialEstimation, keepCovariance, listener, locked

Constructor Summary

Constructors

Constructor	Description
FundamentalMatrixRefiner()	Constructor.
FundamentalMatrixRefiner(FundamentalMatrix initialEstimation, boolean keepCovariance, com.irurueta.numerical.robust.InliersData inliersData, List<com.irurueta.geometry.Point2D> samples1, List<com.irurueta.geometry.Point2D> samples2, double refinementStandardDeviation)	Constructor.
FundamentalMatrixRefiner(FundamentalMatrix initialEstimation, boolean keepCovariance, BitSet inliers, double[] residuals, int numInliers, List<com.irurueta.geometry.Point2D> samples1, List<com.irurueta.geometry.Point2D> samples2, double refinementStandardDeviation)	Constructor.

Method Summary

Modifier and Type	Method	Description
double	getRefinementStandardDeviation()	Gets standard deviation used for Levenberg-Marquardt fitting during refinement.
FundamentalMatrix	refine()	Refines provided initial estimation.
boolean	refine(FundamentalMatrix result)	Refines provided initial estimation.
private double	residual(FundamentalMatrix fundamentalMatrix, com.irurueta.geometry.Point2D leftPoint, com.irurueta.geometry.Point2D rightPoint)	Computes the residual between a fundamental matrix and a pair of matched points.
void	setRefinementStandardDeviation(double refinementStandardDeviation)	Sets standard deviation used for Levenberg-Marquardt fitting during refinement.
private double	totalResidual(FundamentalMatrix fundamentalMatrix)	Computes total residual among all provided inlier samples.

Methods inherited from class com.irurueta.geometry.refiners.PairMatchesAndInliersDataRefiner

getSamples1, getSamples2, isReady, setSamples1, setSamples2

Methods inherited from class com.irurueta.geometry.refiners.InliersDataRefiner

getInliers, getNumInliers, getResiduals, getTotalSamples, setInliers, setInliersData, setNumInliers, setResiduals

Methods inherited from class com.irurueta.geometry.refiners.Refiner

getCovariance, getInitialEstimation, getListener, isCovarianceKept, isLocked, setCovarianceKept, setInitialEstimation, setListener

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

testLine

private final com.irurueta.geometry.Line2D testLine

Test line to compute epipolar residuals.

refinementStandardDeviation

private double refinementStandardDeviation

Standard deviation used for Levenberg-Marquardt fitting during refinement. Returned value gives an indication of how much variance each residual has. Typically, this value is related to the threshold used on each robust estimation, since residuals of found inliers are within the range of such threshold.

Constructor Details

FundamentalMatrixRefiner

public FundamentalMatrixRefiner()

Constructor.

FundamentalMatrixRefiner

public FundamentalMatrixRefiner(FundamentalMatrix initialEstimation,
 boolean keepCovariance,
 BitSet inliers,
 double[] residuals,
 int numInliers,
 List<com.irurueta.geometry.Point2D> samples1,
 List<com.irurueta.geometry.Point2D> samples2,
 double refinementStandardDeviation)

Constructor.

Parameters:

initialEstimation - initial estimation to be set.

keepCovariance - true if covariance of estimation must be kept after refinement, false otherwise.

inliers - set indicating which of the provided matches are inliers.

residuals - residuals for matched samples.

numInliers - number of inliers on initial estimation.

samples1 - 1st set of paired samples.

samples2 - 2nd set of paired samples.

refinementStandardDeviation - standard deviation used for Levenberg-Marquardt fitting.

FundamentalMatrixRefiner

public FundamentalMatrixRefiner(FundamentalMatrix initialEstimation,
 boolean keepCovariance,
 com.irurueta.numerical.robust.InliersData inliersData,
 List<com.irurueta.geometry.Point2D> samples1,
 List<com.irurueta.geometry.Point2D> samples2,
 double refinementStandardDeviation)

Constructor.

Parameters:

initialEstimation - initial estimation to be set.

keepCovariance - true if covariance of estimation must be kept after refinement, false otherwise.

inliersData - inlier data, typically obtained from a robust estimator.

samples1 - 1st set of paired samples.

samples2 - 2nd set of paired samples.

refinementStandardDeviation - standard deviation used for Levenberg-Marquardt fitting.

Method Details

getRefinementStandardDeviation

public double getRefinementStandardDeviation()

Gets standard deviation used for Levenberg-Marquardt fitting during refinement. Returned value gives an indication of how much variance each residual has. Typically, this value is related to the threshold used on each robust estimation, since residuals of found inliers are within the range of such threshold.

Returns:

standard deviation used for refinement.

setRefinementStandardDeviation

public void setRefinementStandardDeviation(double refinementStandardDeviation)
                                    throws com.irurueta.geometry.estimators.LockedException

Sets standard deviation used for Levenberg-Marquardt fitting during refinement. Returned value gives an indication of how much variance each residual has. Typically, this value is related to the threshold used on each robust estimation, since residuals of found inliers are within the range of such threshold.

Parameters:

refinementStandardDeviation - standard deviation used for refinement.

Throws:

com.irurueta.geometry.estimators.LockedException - if estimator is locked.

refine

public FundamentalMatrix refine()
                         throws com.irurueta.geometry.estimators.NotReadyException,
com.irurueta.geometry.estimators.LockedException,
com.irurueta.geometry.refiners.RefinerException

Refines provided initial estimation.

Specified by:

refine in class com.irurueta.geometry.refiners.Refiner<FundamentalMatrix>

Returns:

refined estimation.

Throws:

com.irurueta.geometry.estimators.NotReadyException - if not enough input data has been provided.

com.irurueta.geometry.estimators.LockedException - if estimator is locked because refinement is already in progress.

com.irurueta.geometry.refiners.RefinerException - if refinement fails for some reason (e.g. unable to converge to a result).

refine

public boolean refine(FundamentalMatrix result)
               throws com.irurueta.geometry.estimators.NotReadyException,
com.irurueta.geometry.estimators.LockedException,
com.irurueta.geometry.refiners.RefinerException

Refines provided initial estimation. This method always sets a value into provided result instance regardless of the fact that error has actually improved in LMSE terms or not.

Specified by:

refine in class com.irurueta.geometry.refiners.Refiner<FundamentalMatrix>

Parameters:

result - instance where refined estimation will be stored.

Returns:

true if result improves (decreases) in LMSE terms respect to initial estimation, false if no improvement has been achieved.

Throws:

com.irurueta.geometry.estimators.NotReadyException - if not enough input data has been provided.

com.irurueta.geometry.estimators.LockedException - if estimator is locked because refinement is already in progress.

com.irurueta.geometry.refiners.RefinerException - if refinement fails for some reason (e.g. unable to converge to a result).

residual

private double residual(FundamentalMatrix fundamentalMatrix,
 com.irurueta.geometry.Point2D leftPoint,
 com.irurueta.geometry.Point2D rightPoint)

Computes the residual between a fundamental matrix and a pair of matched points.

Parameters:

fundamentalMatrix - a fundamental matrix.

leftPoint - left 2D point.

rightPoint - right 2D point.

Returns:

residual (distance of point to epipolar line).

totalResidual

private double totalResidual(FundamentalMatrix fundamentalMatrix)

Computes total residual among all provided inlier samples.

Parameters:

fundamentalMatrix - a fundamental matrix.

Returns:

total residual.