Package com.irurueta.ar.sfm

Class PlanarBestFundamentalMatrixEstimatorAndReconstructor

java.lang.Object
com.irurueta.ar.sfm.PlanarBestFundamentalMatrixEstimatorAndReconstructor
public class PlanarBestFundamentalMatrixEstimatorAndReconstructor extends Object
This class takes matched pairs of 2D points corresponding to a planar scene, estimates an homography relating both sets of points, decomposes such homography induced by the 3D plane on the scene, and uses such decomposition to determine the best epipolar geometry (e.g. fundamental matrix) by using the essential matrix and provided intrinsic camera parameters on both views corresponding to both sets of points to reconstruct points and choose the solution that produces the largest amount of points located in front of both cameras. This class requires 2 sets of matched 2D points and the intrinsic parameters of the cameras in both views, hence cameras must be calibrated in some way before using this class. This class is similar to PlanarFundamentalMatrixEstimator but picks the best solution by reconstructing the 3D points in the scene and choosing the solution that produces the largest amount of points located in front of both cameras.

  • Field Details

    • MINIMUM_SIZE

      public static final int MINIMUM_SIZE
      Minimum number of matched points required to find a solution.
      See Also:

    • leftPoints

      private List<com.irurueta.geometry.Point2D> leftPoints
      List of matched 2D points in the left view.

    • rightPoints

      private List<com.irurueta.geometry.Point2D> rightPoints
      List of matched 2D points in the right view.

    • leftIntrinsics

      private com.irurueta.geometry.PinholeCameraIntrinsicParameters leftIntrinsics
      Intrinsic parameters for the camera on the left view.

    • rightIntrinsics

      private com.irurueta.geometry.PinholeCameraIntrinsicParameters rightIntrinsics
      Intrinsic parameters for the camera on the right view.

    • listener

      private PlanarBestFundamentalMatrixEstimatorAndReconstructorListener listener
      Listener to attend events generated by this instance.

    • locked

      private boolean locked
      Indicates whether this instance is locked while computing a solution.

    • homographyEstimator

      private com.irurueta.geometry.estimators.PointCorrespondenceProjectiveTransformation2DRobustEstimator homographyEstimator
      Homography estimator relating both views.

    • essentialCameraEstimatorCorrectorType

      private CorrectorType essentialCameraEstimatorCorrectorType
      Type of corrector to use to triangulate matched points using the corresponding essential matrix or null if no corrector needs to be used.

    • homography

      private com.irurueta.geometry.ProjectiveTransformation2D homography
      Estimated homography.

    • fundamentalMatrix

      private FundamentalMatrix fundamentalMatrix
      Best estimated fundamental matrix.

    • triangulatedPoints

      private List<com.irurueta.geometry.Point3D> triangulatedPoints
      Best estimated triangulated points.

    • validTriangulatedPoints

      private BitSet validTriangulatedPoints
      Contains booleans indicating which of the best triangulated points are valid (i.e. lie in front of both estimated cameras) or not.

    • estimatedLeftCamera

      private com.irurueta.geometry.PinholeCamera estimatedLeftCamera
      Best estimated camera for left view.

    • estimatedRightCamera

      private com.irurueta.geometry.PinholeCamera estimatedRightCamera
      Best estimated camera for right view.

  • Constructor Details

    • PlanarBestFundamentalMatrixEstimatorAndReconstructor

      public PlanarBestFundamentalMatrixEstimatorAndReconstructor()
      Constructor.

    • PlanarBestFundamentalMatrixEstimatorAndReconstructor

      public PlanarBestFundamentalMatrixEstimatorAndReconstructor(List<com.irurueta.geometry.Point2D> leftPoints, List<com.irurueta.geometry.Point2D> rightPoints, com.irurueta.geometry.PinholeCameraIntrinsicParameters leftIntrinsics, com.irurueta.geometry.PinholeCameraIntrinsicParameters rightIntrinsics)
      Constructor.
      Parameters:
      leftPoints - list of matched 2D points in the left view.
      rightPoints - list of matched 2D points in the right view.
      leftIntrinsics - intrinsic parameters for the camera on the left view.
      rightIntrinsics - intrinsic parameters for the camera on the right view.
      Throws:
      IllegalArgumentException - if provided list of matched points do not contain enough points or if they have different sizes.

    • PlanarBestFundamentalMatrixEstimatorAndReconstructor

      public PlanarBestFundamentalMatrixEstimatorAndReconstructor(List<com.irurueta.geometry.Point2D> leftPoints, List<com.irurueta.geometry.Point2D> rightPoints, com.irurueta.geometry.PinholeCameraIntrinsicParameters leftIntrinsics, com.irurueta.geometry.PinholeCameraIntrinsicParameters rightIntrinsics, PlanarBestFundamentalMatrixEstimatorAndReconstructorListener listener)
      Constructor.
      Parameters:
      leftPoints - list of matched 2D points in the left view.
      rightPoints - list of matched 2D points in the right view.
      leftIntrinsics - intrinsic parameters for the camera on the left view.
      rightIntrinsics - intrinsic parameters for the camera on the right view.
      listener - listener to be notified of events generated by this instance.
      Throws:
      IllegalArgumentException - if provided list of matched points do not contain enough points or if they have different sizes.

  • Method Details

    • getLeftPoints

      public List<com.irurueta.geometry.Point2D> getLeftPoints()
      Gets list of matched 2D points in the left view.
      Returns:
      list of matched 2D points in the left view.

    • setLeftPoints

      public void setLeftPoints(List<com.irurueta.geometry.Point2D> leftPoints) throws com.irurueta.geometry.estimators.LockedException
      Sets list of matched 2D points in the left view.
      Parameters:
      leftPoints - list of matched 2D points in the left view.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      IllegalArgumentException - if provided points do not have enough points.

    • getRightPoints

      public List<com.irurueta.geometry.Point2D> getRightPoints()
      Gets list of matched 2D points in the right view.
      Returns:
      list of matched 2D points in the right view.

    • setRightPoints

      public void setRightPoints(List<com.irurueta.geometry.Point2D> rightPoints) throws com.irurueta.geometry.estimators.LockedException
      Sets list of matched 2D points in the right view.
      Parameters:
      rightPoints - list of matched 2D points in the right view.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      IllegalArgumentException - if provided points do not have enough points.

    • setLeftAndRightPoints

      public void setLeftAndRightPoints(List<com.irurueta.geometry.Point2D> leftPoints, List<com.irurueta.geometry.Point2D> rightPoints) throws com.irurueta.geometry.estimators.LockedException
      Sets lists of matched 2D points in the left and right views.
      Parameters:
      leftPoints - list of matched 2D points in the left view.
      rightPoints - list of matched 2D points in the right view.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      IllegalArgumentException - if provided points do not have enough points or lists have different sizes.

    • getLeftIntrinsics

      public com.irurueta.geometry.PinholeCameraIntrinsicParameters getLeftIntrinsics()
      Gets intrinsic parameters for the camera on the left view.
      Returns:
      intrinsic parameters for the camera on the left view.

    • setLeftIntrinsics

      public void setLeftIntrinsics(com.irurueta.geometry.PinholeCameraIntrinsicParameters leftIntrinsics) throws com.irurueta.geometry.estimators.LockedException
      Sets intrinsic parameters for the camera on the left view.
      Parameters:
      leftIntrinsics - intrinsic parameters for the camera on the left view.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.

    • getRightIntrinsics

      public com.irurueta.geometry.PinholeCameraIntrinsicParameters getRightIntrinsics()
      Gets intrinsic parameters for the camera on the right view.
      Returns:
      intrinsic parameters for the camera on the right view.

    • setRightIntrinsics

      public void setRightIntrinsics(com.irurueta.geometry.PinholeCameraIntrinsicParameters rightIntrinsics) throws com.irurueta.geometry.estimators.LockedException
      Sets intrinsic parameters for the camera on the right view.
      Parameters:
      rightIntrinsics - intrinsic parameters for the camera on the right view.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.

    • getHomographyEstimator

      public com.irurueta.geometry.estimators.PointCorrespondenceProjectiveTransformation2DRobustEstimator getHomographyEstimator()
      Gets internal homography estimator.
      Returns:
      internal homography estimator.

    • setHomographyEstimator

      public void setHomographyEstimator(com.irurueta.geometry.estimators.PointCorrespondenceProjectiveTransformation2DRobustEstimator homographyEstimator) throws com.irurueta.geometry.estimators.LockedException
      Sets internal homography estimator.
      Parameters:
      homographyEstimator - internal homography estimator.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.
      NullPointerException - if provided estimator is null.

    • getEssentialCameraEstimatorCorrectorType

      public CorrectorType getEssentialCameraEstimatorCorrectorType()
      Gets type of corrector to use to triangulate matched points using the corresponding essential matrix or null if no corrector needs to be used.
      Returns:
      corrector to use for triangulation or null.

    • setEssentialCameraEstimatorCorrectorType

      public void setEssentialCameraEstimatorCorrectorType(CorrectorType correctorType) throws com.irurueta.geometry.estimators.LockedException
      Sets type of corrector to use to triangulate matched points using the corresponding essential matrix or null if no corrector needs to be used.
      Parameters:
      correctorType - corrector to use for triangulation or null.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.

    • getHomographyConfidence

      public double getHomographyConfidence()
      Gets amount of confidence on homography estimation 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.

    • setHomographyConfidence

      public void setHomographyConfidence(double confidence) throws com.irurueta.geometry.estimators.LockedException
      Sets amount of confidence on homography estimation 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 estimator is locked.

    • getHomographyMaxIterations

      public int getHomographyMaxIterations()
      Returns maximum allowed number of iterations for homography estimation.
      Returns:
      maximum allowed number of iterations.

    • setHomographyMaxIterations

      public void setHomographyMaxIterations(int maxIterations) throws com.irurueta.geometry.estimators.LockedException
      Sets maximum allowed number of iterations for homography estimation.
      Parameters:
      maxIterations - maximum allowed number of iterations.
      Throws:
      IllegalArgumentException - if provided value is less than 1.
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.

    • isHomographyRefined

      public boolean isHomographyRefined()
      Indicates whether result of homography estimation is refined.
      Returns:
      true to refine homography result, false to simply use result found by robust estimation without further refining.

    • setHomographyRefined

      public void setHomographyRefined(boolean refineResult) throws com.irurueta.geometry.estimators.LockedException
      Specifies whether homography estimation must be refined or not.
      Parameters:
      refineResult - true to refine homography result, false to simply use result found by robust estimator without further refining.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.

    • isHomographyCovarianceKept

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

    • setHomographyCovarianceKept

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

    • getHomographyCovariance

      public com.irurueta.algebra.Matrix getHomographyCovariance()
      Gets covariance for estimated homography if available. This is only available when homography has been refined and covariance is kept.
      Returns:
      estimated homography covariance or null.

    • getHomographyMethod

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

    • getQualityScores

      public double[] getQualityScores()
      Returns quality scores corresponding to each pair of matched points. This is used for homography estimation. The larger the score value the better the quality of the matching.
      Returns:
      quality scores for each pair of matched points.

    • setQualityScores

      public void setQualityScores(double[] qualityScore) throws com.irurueta.geometry.estimators.LockedException
      Sets quality scores corresponding to each pair of matched points. This is used for homography estimation. The larger the score value the better the quality of the matching.
      Parameters:
      qualityScore - quality scores corresponding to eac pair of matched points.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.
      IllegalArgumentException - if provided quality scores length is smaller than minimum required size (4 points).

    • getListener

      public PlanarBestFundamentalMatrixEstimatorAndReconstructorListener getListener()
      Gets listener to attend events generated by this instance.
      Returns:
      listener to attend events generated by this instance.

    • setListener

      public void setListener(PlanarBestFundamentalMatrixEstimatorAndReconstructorListener listener)
      Sets listener to attend events generated by this instance.
      Parameters:
      listener - listener to attend events generated by this instance.

    • isLocked

      public boolean isLocked()
      Indicates whether this instance is locked while computing a solution.
      Returns:
      true if this instance is locked, false otherwise.

    • isReady

      public boolean isReady()
      Indicates whether this instance is ready to start the estimation when all required data has been provided.
      Returns:
      true if this instance is ready, false otherwise.

    • getHomography

      public com.irurueta.geometry.ProjectiveTransformation2D getHomography()
      Gets estimated homography.
      Returns:
      estimated homography.

    • getFundamentalMatrix

      public FundamentalMatrix getFundamentalMatrix()
      Gets best estimated fundamental matrix.
      Returns:
      best estimated fundamental matrix.

    • getTriangulatedPoints

      public List<com.irurueta.geometry.Point3D> getTriangulatedPoints()
      Gets best estimated triangulated points.
      Returns:
      best estimated triangulated points.

    • getValidTriangulatedPoints

      public BitSet getValidTriangulatedPoints()
      Gets set containing booleans indicating which of the best triangulated points are valid (i.e. lie in front of both estimated cameras) or not.
      Returns:
      set indicating which of the best triangulated points are valid.

    • getEstimatedLeftCamera

      public com.irurueta.geometry.PinholeCamera getEstimatedLeftCamera()
      Gets best estimated camera for left view.
      Returns:
      best estimated camera for left view.

    • getEstimatedRightCamera

      public com.irurueta.geometry.PinholeCamera getEstimatedRightCamera()
      Gets best estimated camera for right view.
      Returns:
      best estimated camera for right view.

    • estimateAndReconstruct

      public void estimateAndReconstruct() throws com.irurueta.geometry.estimators.LockedException, com.irurueta.geometry.estimators.NotReadyException, FundamentalMatrixEstimatorException
      Estimates homography, the best fundamental matrix, their cameras and reconstructs matched points.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.
      com.irurueta.geometry.estimators.NotReadyException - if estimator is not ready because required data is missing.
      FundamentalMatrixEstimatorException - if something fails, typically due to numerical instabilities.

    • internalSetLeftAndRightPoints

      private void internalSetLeftAndRightPoints(List<com.irurueta.geometry.Point2D> leftPoints, List<com.irurueta.geometry.Point2D> rightPoints)
      Internal method that sets list of matched 2D points in the left and right views.
      Parameters:
      leftPoints - list of matched 2D points in the left view.
      rightPoints - list of matched 2D points in the right view.
      Throws:
      IllegalArgumentException - if provided points do not have enough points or lists have different sizes.

    • enableHomographyInliersEstimation

      private void enableHomographyInliersEstimation()
      Ensures that inlier estimation is enabled on homography estimator.