Package com.irurueta.ar.epipolar.estimators

Class FundamentalMatrixRobustEstimator

java.lang.Object
com.irurueta.ar.epipolar.estimators.FundamentalMatrixRobustEstimator
Direct Known Subclasses:
LMedSFundamentalMatrixRobustEstimator, MSACFundamentalMatrixRobustEstimator, PROMedSFundamentalMatrixRobustEstimator, PROSACFundamentalMatrixRobustEstimator, RANSACFundamentalMatrixRobustEstimator
public abstract class FundamentalMatrixRobustEstimator extends Object
This is an abstract class for algorithms to robustly find the best Fundamental matrix for provided collections of matched 2D points. Implementations of this class should be able to detect and discard outliers in order to find the best solution.

  • Field Details

    • DEFAULT_ROBUST_METHOD

      public static final com.irurueta.numerical.robust.RobustEstimatorMethod DEFAULT_ROBUST_METHOD
      Default robust estimator method when none is provided.

    • DEFAULT_FUNDAMENTAL_MATRIX_ESTIMATOR_METHOD

      public static final FundamentalMatrixEstimatorMethod DEFAULT_FUNDAMENTAL_MATRIX_ESTIMATOR_METHOD
      Default non-robust method to estimate a fundamental matrix.

    • DEFAULT_REFINE_RESULT

      public static final boolean DEFAULT_REFINE_RESULT
      Indicates that result is refined by default using Levenberg-Marquardt fitting algorithm over found inliers.
      See Also:

    • DEFAULT_KEEP_COVARIANCE

      public static final boolean DEFAULT_KEEP_COVARIANCE
      Indicates that covariance is not kept by default after refining result.
      See Also:

    • DEFAULT_PROGRESS_DELTA

      public static final float DEFAULT_PROGRESS_DELTA
      Default amount of progress variation before notifying a change in estimation progress. By default, this is set to 5%.
      See Also:

    • MIN_PROGRESS_DELTA

      public static final float MIN_PROGRESS_DELTA
      Minimum allowed value for progress delta.
      See Also:

    • MAX_PROGRESS_DELTA

      public static final float MAX_PROGRESS_DELTA
      Maximum allowed value for progress delta.
      See Also:

    • DEFAULT_CONFIDENCE

      public static final double DEFAULT_CONFIDENCE
      Constant defining default confidence of the estimated result, which is 99%. This means that with a probability of 99% estimation will be accurate because chosen sub-samples will be inliers.
      See Also:

    • DEFAULT_MAX_ITERATIONS

      public static final int DEFAULT_MAX_ITERATIONS
      Default maximum allowed number of iterations.
      See Also:

    • MIN_CONFIDENCE

      public static final double MIN_CONFIDENCE
      Minimum allowed confidence value.
      See Also:

    • MAX_CONFIDENCE

      public static final double MAX_CONFIDENCE
      Maximum allowed confidence value.
      See Also:

    • MIN_ITERATIONS

      public static final int MIN_ITERATIONS
      Minimum allowed number of iterations.
      See Also:

    • leftPoints

      protected List<com.irurueta.geometry.Point2D> leftPoints
      List of 2D points corresponding to left view.

    • rightPoints

      protected List<com.irurueta.geometry.Point2D> rightPoints
      List of 2D points corresponding to right view.

    • listener

      protected FundamentalMatrixRobustEstimatorListener listener
      Listener to be notified of events such as when estimation starts, ends or its progress significantly changes.

    • locked

      protected boolean locked
      Indicates if this estimator is locked because an estimation is being computed.

    • progressDelta

      protected float progressDelta
      Amount of progress variation before notifying a progress change during estimation.

    • confidence

      protected double confidence
      Amount of confidence expressed as a value between 0.0 and 1.0 (which is equivalent to 100%). The amount of confidence indicates the probability that the estimated result is correct. Usually this value will be close to 1.0, but not exactly 1.0.

    • maxIterations

      protected int maxIterations
      Maximum allowed number of iterations. When the maximum number of iterations is exceeded, result will not be available, however an approximate result will be available for retrieval.

    • inliersData

      protected com.irurueta.numerical.robust.InliersData inliersData
      Data related to inliers found after estimation.

    • refineResult

      protected boolean refineResult
      Indicates whether result must be refined using Levenberg-Marquardt fitting algorithm over found inliers. If true, inliers will be computed and kept in any implementation regardless of the settings.

    • keepCovariance

      private boolean keepCovariance
      Indicates whether covariance must be kept after refining result. This setting is only taken into account if result is refined.

    • covariance

      private com.irurueta.algebra.Matrix covariance
      Estimated covariance of estimated fundamental matrix. This is only available when result has been refined and covariance is kept.

    • testLine

      private final com.irurueta.geometry.Line2D testLine
      Test line to compute epipolar residuals.

    • fundMatrixEstimator

      private FundamentalMatrixEstimator fundMatrixEstimator
      Internal non robust estimator of fundamental matrix.

  • Constructor Details

    • FundamentalMatrixRobustEstimator

      protected FundamentalMatrixRobustEstimator(FundamentalMatrixEstimatorMethod fundMatrixEstimatorMethod)
      Constructor.
      Parameters:
      fundMatrixEstimatorMethod - method for non-robust fundamental matrix estimator.

    • FundamentalMatrixRobustEstimator

      protected FundamentalMatrixRobustEstimator(FundamentalMatrixEstimatorMethod fundMatrixEstimatorMethod, FundamentalMatrixRobustEstimatorListener listener)
      Constructor.
      Parameters:
      fundMatrixEstimatorMethod - method for non-robust fundamental matrix estimator.
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.

    • FundamentalMatrixRobustEstimator

      protected FundamentalMatrixRobustEstimator(FundamentalMatrixEstimatorMethod fundMatrixEstimatorMethod, List<com.irurueta.geometry.Point2D> leftPoints, List<com.irurueta.geometry.Point2D> rightPoints)
      Constructor with matched 2D points.
      Parameters:
      fundMatrixEstimatorMethod - method for non-robust fundamental matrix estimator.
      leftPoints - 2D points on left view.
      rightPoints - 2D points on right view.
      Throws:
      IllegalArgumentException - if provided list of points do not have the same length or their length is less than 7 points.

    • FundamentalMatrixRobustEstimator

      protected FundamentalMatrixRobustEstimator(FundamentalMatrixEstimatorMethod fundMatrixEstimatorMethod, List<com.irurueta.geometry.Point2D> leftPoints, List<com.irurueta.geometry.Point2D> rightPoints, FundamentalMatrixRobustEstimatorListener listener)
      Constructor with matched 2D points.
      Parameters:
      fundMatrixEstimatorMethod - method for non-robust fundamental matrix estimator.
      leftPoints - 2D points on left view.
      rightPoints - 2D points on right view.
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      Throws:
      IllegalArgumentException - if provided list of points do not have the same length or their length is less than 7 points.

    • FundamentalMatrixRobustEstimator

      protected FundamentalMatrixRobustEstimator()
      Constructor.

  • Method Details

    • getNonRobustFundamentalMatrixEstimatorMethod

      public FundamentalMatrixEstimatorMethod getNonRobustFundamentalMatrixEstimatorMethod()
      Returns non-robust method to estimate a fundamental matrix.
      Returns:
      non-robust method to estimate a fundamental matrix.

    • setNonRobustFundamentalMatrixEstimatorMethod

      public void setNonRobustFundamentalMatrixEstimatorMethod(FundamentalMatrixEstimatorMethod method) throws com.irurueta.geometry.estimators.LockedException
      Sets non-robust method to estimate a fundamental matrix.
      Parameters:
      method - non-robust method to estimate a fundamental matrix.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this fundamental matrix estimator is locked.

    • getLeftPoints

      public List<com.irurueta.geometry.Point2D> getLeftPoints()
      Returns matched 2D points on left view.
      Returns:
      2D points on left view.

    • getRightPoints

      public List<com.irurueta.geometry.Point2D> getRightPoints()
      Returns matched 2D points on right view.
      Returns:
      2D points on right view.

    • setPoints

      public void setPoints(List<com.irurueta.geometry.Point2D> leftPoints, List<com.irurueta.geometry.Point2D> rightPoints) throws com.irurueta.geometry.estimators.LockedException
      Sets matched 2D points on both left and right views.
      Parameters:
      leftPoints - matched 2D points on left view.
      rightPoints - matched 2D points on right view.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this fundamental matrix estimator is locked.
      IllegalArgumentException - if provided matched points on left and right views do not have the same length or if their length is less than 7 points.

    • getListener

      public FundamentalMatrixRobustEstimatorListener getListener()
      Returns reference to listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      Returns:
      listener to be notified of events.

    • setListener

      public void setListener(FundamentalMatrixRobustEstimatorListener listener) throws com.irurueta.geometry.estimators.LockedException
      Sets listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      Parameters:
      listener - listener to be notified of events.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if robust estimator is locked.

    • isListenerAvailable

      public boolean isListenerAvailable()
      Indicates whether listener has been provided and is available for retrieval.
      Returns:
      true if available, false otherwise.

    • isLocked

      public boolean isLocked()
      Returns boolean indicating if estimator is locked because estimation is under progress.
      Returns:
      true if estimator is locked, false otherwise.

    • getProgressDelta

      public float getProgressDelta()
      Returns amount of progress variation before notifying a progress change during estimation.
      Returns:
      amount of progress variation before notifying a progress change during estimation.

    • setProgressDelta

      public void setProgressDelta(float progressDelta) throws com.irurueta.geometry.estimators.LockedException
      Sets amount of progress variation before notifying a progress change during estimation.
      Parameters:
      progressDelta - amount of progress variation before notifying a progress change during estimation.
      Throws:
      IllegalArgumentException - if progress delta is less than zero or greater than 1.
      com.irurueta.geometry.estimators.LockedException - if this estimator is locked because an estimation is being computed.

    • getConfidence

      public double getConfidence()
      Returns amount of confidence expressed as a value between 0.0 and 1.0 (which is equivalent to 100%). The amount of confidence indicates the probability that the estimated result is correct. Usually this value will be close to 1.0, but not exactly 1.0.
      Returns:
      amount of confidence as a value between 0.0 and 1.0.

    • setConfidence

      public void setConfidence(double confidence) throws com.irurueta.geometry.estimators.LockedException
      Sets amount of confidence expressed as a value between 0.0 and 1.0 (which is equivalent to 100%). The amount of confidence indicates the probability that the estimated result is correct. Usually this value will be close to 1.0, but not exactly 1.0.
      Parameters:
      confidence - confidence to be set as a value between 0.0 and 1.0.
      Throws:
      IllegalArgumentException - if provided value is not between 0.0 and 1.0.
      com.irurueta.geometry.estimators.LockedException - if this estimator is locked because an estimator is being computed.

    • getMaxIterations

      public int getMaxIterations()
      Returns maximum allowed number of iterations. If maximum allowed number of iterations is achieved without converting to a result when calling estimate(), a RobustEstimatorException will be raised.
      Returns:
      maximum allowed number of iterations.

    • setMaxIterations

      public void setMaxIterations(int maxIterations) throws com.irurueta.geometry.estimators.LockedException
      Sets maximum allowed number of iterations. When the maximum number of iterations is exceeded, result will not be available, however an approximate result will be available for retrieval.
      Parameters:
      maxIterations - maximum allowed number of iterations to be set.
      Throws:
      IllegalArgumentException - if provided value is less than 1.
      com.irurueta.geometry.estimators.LockedException - if this estimator is locked because an estimation is being computed.

    • getInliersData

      public com.irurueta.numerical.robust.InliersData getInliersData()
      Gets data related to inliers found after estimation.
      Returns:
      data related to inliers found after estimation.

    • isResultRefined

      public boolean isResultRefined()
      Indicates whether result must be refined using Levenberg-Marquardt fitting algorithm over found inliers. If true, inliers will be computed and kept in any implementation regardless of the settings.
      Returns:
      true to refine result, false to simply use result found by robust estimator without further refining.

    • setResultRefined

      public void setResultRefined(boolean refineResult) throws com.irurueta.geometry.estimators.LockedException
      Specifies whether result must be refined using Levenberg-Marquardt fitting algorithm over found inliers.
      Parameters:
      refineResult - true to refine result, false to simply use result found by robust estimator without further refining.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.

    • isCovarianceKept

      public boolean isCovarianceKept()
      Indicates whether covariance must be kept after refining result. This setting is only taken into account if result is refined.
      Returns:
      true if covariance must be kept after refining result, false otherwise.

    • setCovarianceKept

      public void setCovarianceKept(boolean keepCovariance) throws com.irurueta.geometry.estimators.LockedException
      Specifies whether covariance must be kept after refining result. This setting is only taken into account if result is refined.
      Parameters:
      keepCovariance - true if covariance must be kept after refining result, false otherwise.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.

    • getMinRequiredPoints

      public int getMinRequiredPoints()
      Returns minimum number of matched pair of points required to start the estimation.
      Returns:
      minimum number of matched pair of points required to start the estimation.

    • isReady

      public boolean isReady()
      Returns value indicating whether required data has been provided so that fundamental matrix estimation can start. If true, estimator is ready to compute a fundamental matrix, otherwise more data needs to be provided.
      Returns:
      true if estimator is ready, false otherwise.

    • getQualityScores

      public double[] getQualityScores()
      Returns quality scores corresponding to each pair of matched points. The larger the score value the better the quality of the pair of matched points. This implementation always returns null. Subclasses using quality scores must implement proper behaviour.
      Returns:
      quality scores corresponding to each pair of matched points.

    • setQualityScores

      public void setQualityScores(double[] qualityScores) throws com.irurueta.geometry.estimators.LockedException
      Sets quality scores corresponding to each pair of matched points. The larger the score value the better the quality of the pair of matched points. This implementation makes no action. Subclasses using quality scores must implement proper behaviour.
      Parameters:
      qualityScores - quality scores corresponding to each pair of matched points.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if robust estimator is locked because an estimation is already in progress.
      IllegalArgumentException - if provided quality scores length is smaller than minimum required number of homographies.

    • getCovariance

      public com.irurueta.algebra.Matrix getCovariance()
      Gets estimated covariance of estimated fundamental matrix if available. This is only available when result has been refined and covariance is kept.
      Returns:
      estimated covariance or null.

    • estimate

      public abstract FundamentalMatrix estimate() throws com.irurueta.geometry.estimators.LockedException, com.irurueta.geometry.estimators.NotReadyException, com.irurueta.numerical.robust.RobustEstimatorException
      Estimates fundamental matrix.
      Returns:
      estimated fundamental matrix.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if robust estimator is locked because an estimation is already in progress.
      com.irurueta.geometry.estimators.NotReadyException - if provided input data is not enough to start the estimation.
      com.irurueta.numerical.robust.RobustEstimatorException - if estimation fails for any reason (i.e. numerical instability, no solution available, etc).

    • getMethod

      public abstract com.irurueta.numerical.robust.RobustEstimatorMethod getMethod()
      Returns method being used for robust estimation.
      Returns:
      method being used for robust estimation.

    • create

      public static FundamentalMatrixRobustEstimator create(com.irurueta.numerical.robust.RobustEstimatorMethod method)
      Creates a fundamental matrix robust estimator using provided method.
      Parameters:
      method - method of a robust estimator algorithm to estimate the best fundamental matrix.
      Returns:
      an instance of a fundamental matrix robust estimator.

    • create

      public static FundamentalMatrixRobustEstimator create(List<com.irurueta.geometry.Point2D> leftPoints, List<com.irurueta.geometry.Point2D> rightPoints, com.irurueta.numerical.robust.RobustEstimatorMethod method)
      Creates a fundamental matrix robust estimator using provided lists of matched points and provided method.
      Parameters:
      leftPoints - 2D points on left view.
      rightPoints - 2D points on left view.
      method - method of a robust estimator algorithm to estimate the best fundamental matrix.
      Returns:
      an instance of a fundamental matrix robust estimator.
      Throws:
      IllegalArgumentException - if provided list of points do not have the same length or their length is less than 7 points.

    • create

      public static FundamentalMatrixRobustEstimator create(List<com.irurueta.geometry.Point2D> leftPoints, List<com.irurueta.geometry.Point2D> rightPoints, double[] qualityScores, com.irurueta.numerical.robust.RobustEstimatorMethod method)
      Creates a fundamental matrix robust estimator using provided lists of matched points and provided method.
      Parameters:
      leftPoints - 2D points on left view.
      rightPoints - 2D points on left view.
      qualityScores - quality scores corresponding to each pair of matched points.
      method - method of a robust estimator algorithm to estimate the best fundamental matrix.
      Returns:
      an instance of a fundamental matrix robust estimator.
      Throws:
      IllegalArgumentException - if provided list of points do not have the same length or their length is less than 7 points.

    • create

      public static FundamentalMatrixRobustEstimator create()
      Creates a fundamental matrix robust estimator using default method.
      Returns:
      an instance of a fundamental matrix robust estimator.

    • create

      public static FundamentalMatrixRobustEstimator create(List<com.irurueta.geometry.Point2D> leftPoints, List<com.irurueta.geometry.Point2D> rightPoints)
      Creates a fundamental matrix robust estimator using provided lists of matched points and default method.
      Parameters:
      leftPoints - 2D points on left view.
      rightPoints - 2D points on left view.
      Returns:
      an instance of a fundamental matrix robust estimator.
      Throws:
      IllegalArgumentException - if provided list of points do not have the same length or their length is less than 7 points.

    • create

      public static FundamentalMatrixRobustEstimator create(List<com.irurueta.geometry.Point2D> leftPoints, List<com.irurueta.geometry.Point2D> rightPoints, double[] qualityScores)
      Creates a fundamental matrix robust estimator using provided lists of matched points and default method.
      Parameters:
      leftPoints - 2D points on left view.
      rightPoints - 2D points on left view.
      qualityScores - quality scores corresponding to each pair of matched points.
      Returns:
      an instance of a fundamental matrix robust estimator.
      Throws:
      IllegalArgumentException - if provided list of points do not have the same length or their length is less than 7 points.

    • residual

      protected 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).

    • nonRobustEstimate

      protected void nonRobustEstimate(List<FundamentalMatrix> solutions, List<com.irurueta.geometry.Point2D> subsetLeftPoints, List<com.irurueta.geometry.Point2D> subsetRightPoints)
      Estimates a fundamental matrix using a non-robust method and provided subset of matched points and stores the solution in provided array of solutions.
      Parameters:
      solutions - list where solutions will be stored.
      subsetLeftPoints - subset of left view matched points.
      subsetRightPoints - subset of right view matched points.

    • attemptRefine

      protected FundamentalMatrix attemptRefine(FundamentalMatrix fundamentalMatrix)
      Attempts to refine provided solution if refinement is requested. This method returns a refined solution or the same provided solution if refinement is not requested or has failed. If refinement is enabled, and it is requested to keep covariance, this method will also keep covariance of refined fundamental matrix.
      Parameters:
      fundamentalMatrix - fundamental matrix estimated by a robust estimator without refinement.
      Returns:
      solution after refinement (if requested) or the provided non-refined solution if not requested or if refinement failed.

    • getRefinementStandardDeviation

      protected abstract 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.

    • internalSetPoints

      private void internalSetPoints(List<com.irurueta.geometry.Point2D> leftPoints, List<com.irurueta.geometry.Point2D> rightPoints)
      Sets matched 2D points on left and right views. This method does not check whether instance is locked or not.
      Parameters:
      leftPoints - matched 2D points on left view.
      rightPoints - matched 2D points on right view.
      Throws:
      IllegalArgumentException - if provided lists of points don't have the same size.