Package com.irurueta.geometry.estimators

Class EuclideanTransformation2DEstimator

java.lang.Object
com.irurueta.geometry.estimators.EuclideanTransformation2DEstimator
public class EuclideanTransformation2DEstimator extends Object
Estimator of a 2D Euclidean transformation based on point correspondences. This estimator uses Kabsch algorithm on 2D. A minimum of 3 non-coincident matched 2D input/output points is required for estimation. For some point configurations 2 points are enough to find a valid solution. If more points are provided an LMSE (Least Mean Squared Error) solution will be found. Based on: https://en.wikipedia.org/wiki/Kabsch_algorithm

  • Field Details

    • MINIMUM_SIZE

      public static final int MINIMUM_SIZE
      Minimum required number of matched points.
      See Also:

    • WEAK_MINIMUM_SIZE

      public static final int WEAK_MINIMUM_SIZE
      For some point configurations a solution can be found with only 2 points.
      See Also:

    • inputPoints

      private List<Point2D> inputPoints
      2D input points.

    • outputPoints

      private List<Point2D> outputPoints
      2D output points.

    • listener

      private EuclideanTransformation2DEstimatorListener listener
      Listener to be notified of events such as when estimation starts or ends.

    • weakMinimumSizeAllowed

      private boolean weakMinimumSizeAllowed
      Indicates whether estimation can start with only 2 points or not. True allows 2 points, false requires 3.

    • locked

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

  • Constructor Details

    • EuclideanTransformation2DEstimator

      public EuclideanTransformation2DEstimator()
      Constructor.

    • EuclideanTransformation2DEstimator

      public EuclideanTransformation2DEstimator(List<Point2D> inputPoints, List<Point2D> outputPoints)
      Constructor.
      Parameters:
      inputPoints - 2D input points.
      outputPoints - 2D input points.
      Throws:
      IllegalArgumentException - if provided lists of points don't have the same size or their size is smaller than 3.

    • EuclideanTransformation2DEstimator

      public EuclideanTransformation2DEstimator(EuclideanTransformation2DEstimatorListener listener)
      Constructor.
      Parameters:
      listener - listener to be notified of events such as when estimation starts or ends.

    • EuclideanTransformation2DEstimator

      public EuclideanTransformation2DEstimator(EuclideanTransformation2DEstimatorListener listener, List<Point2D> inputPoints, List<Point2D> outputPoints)
      Constructor.
      Parameters:
      listener - listener to be notified of events such as when estimation starts or ends.
      inputPoints - 2D input points.
      outputPoints - 2D output points.
      Throws:
      IllegalArgumentException - if provided lists of points don't have the same size or their size is smaller than 3.

    • EuclideanTransformation2DEstimator

      public EuclideanTransformation2DEstimator(boolean weakMinimumSizeAllowed)
      Constructor.
      Parameters:
      weakMinimumSizeAllowed - true allows 3 points, false requires 4.

    • EuclideanTransformation2DEstimator

      public EuclideanTransformation2DEstimator(List<Point2D> inputPoints, List<Point2D> outputPoints, boolean weakMinimumSizeAllowed)
      Constructor.
      Parameters:
      inputPoints - 2D input points.
      outputPoints - 2D input points.
      weakMinimumSizeAllowed - true allows 3 points, false requires 4.
      Throws:
      IllegalArgumentException - if provided lists of points don't have the same size or their size is smaller than 3.

    • EuclideanTransformation2DEstimator

      public EuclideanTransformation2DEstimator(EuclideanTransformation2DEstimatorListener listener, boolean weakMinimumSizeAllowed)
      Constructor.
      Parameters:
      listener - listener to be notified of events such as when estimation starts or ends.
      weakMinimumSizeAllowed - true allows 3 points, false requires 4.

    • EuclideanTransformation2DEstimator

      public EuclideanTransformation2DEstimator(EuclideanTransformation2DEstimatorListener listener, List<Point2D> inputPoints, List<Point2D> outputPoints, boolean weakMinimumSizeAllowed)
      Constructor.
      Parameters:
      listener - listener to be notified of events such as when estimation starts or ends.
      inputPoints - 2D input points.
      outputPoints - 2D output points.
      weakMinimumSizeAllowed - true allows 3 points, false requires 4.
      Throws:
      IllegalArgumentException - if provided lists of points don't have the same size or their size is smaller than 3.

  • Method Details

    • getInputPoints

      public List<Point2D> getInputPoints()
      Returns list of input points to be used to estimate an Euclidean 2D transformation. Each point in the list of input points must be matched with the corresponding point in the list of output points located at the same position. Hence, both input points and output points must have the same size, and their size must be greater or equal than MINIMUM_SIZE.
      Returns:
      list of input points to be used to estimate an Euclidean transformation.

    • getOutputPoints

      public List<Point2D> getOutputPoints()
      Returns list of output points to be used to estimate an Euclidean 2D transformation. Each point in the list of output points must be matched with the corresponding point in the list of input points located at the same position. Hence, both input points and output points must have the same size, and their size must be greater or equal than MINIMUM_SIZE.
      Returns:
      list of input points to be used to estimate an Euclidean transformation.

    • setPoints

      public void setPoints(List<Point2D> inputPoints, List<Point2D> outputPoints) throws LockedException
      Sets list of points to be used to estimate an Euclidean 2D transformation. Points in the list located at the same position are considered to be matched. Hence, both lists must have the same size, and their size must be greater or equal than MINIMUM_SIZE.
      Parameters:
      inputPoints - list of input points ot be used ot estimate an Euclidean 2D transformation.
      outputPoints - list of output points ot be used to estimate an Euclidean 2D transformation.
      Throws:
      IllegalArgumentException - if provided lists of points don't have the same size or their size is smaller than MINIMUM_SIZE.
      LockedException - if estimator is locked because a computation is already in progress.

    • getListener

      public EuclideanTransformation2DEstimatorListener getListener()
      Returns reference to listener to be notified of events such as when estimation starts or ends.
      Returns:
      listener to be notified of events.

    • setListener

      public void setListener(EuclideanTransformation2DEstimatorListener listener) throws LockedException
      Sets listener to be notified of events such as when estimation starts or ends.
      Parameters:
      listener - listener to be notified of events.
      Throws:
      LockedException - if estimator is locked.

    • isWeakMinimumSizeAllowed

      public boolean isWeakMinimumSizeAllowed()
      Indicates whether estimation can start with only 2 points or not.
      Returns:
      true allows 2 points, false requires 3.

    • setWeakMinimumSizeAllowed

      public void setWeakMinimumSizeAllowed(boolean weakMinimumSizeAllowed) throws LockedException
      Specifies whether estimation can start with only 2 points or not.
      Parameters:
      weakMinimumSizeAllowed - true allows 2 points, false requires 3.
      Throws:
      LockedException - if estimator is locked.

    • getMinimumPoints

      public int getMinimumPoints()
      Required minimum number of point correspondences to start the estimation. Can be either 2 or 3.
      Returns:
      minimum number of point correspondences.

    • 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()
      Indicates if this instance is locked because estimation is being computed.
      Returns:
      true if locked, false otherwise.

    • isReady

      public boolean isReady()
      Indicates if estimator is ready to start the Euclidean 2D transformation estimation. This is true when input data (i.e. lists of matched points) are provided and a minimum of MINIMUM_SIZE points are available.
      Returns:
      true if estimator is ready, false otherwise.

    • estimate

      public EuclideanTransformation2D estimate() throws LockedException, NotReadyException, CoincidentPointsException
      Estimates an Euclidean 2D transformation using the list of matched input and output 2D points. A minimum of 3 matched non-coincident points is required. If more points are provided an LMSE (Least Mean Squared Error) solution will be found.
      Returns:
      estimated euclidean 2D transformation.
      Throws:
      LockedException - if estimator is locked.
      NotReadyException - if not enough data has been provided.
      CoincidentPointsException - raised if transformation cannot be estimated for some reason (point configuration degeneracy, duplicate points or numerical instabilities).

    • estimate

      public void estimate(EuclideanTransformation2D result) throws LockedException, NotReadyException, CoincidentPointsException
      Estimates an Euclidean 2D transformation using the list of matched input and output 2D points. A minimum of 3 matched non-coincident points is required. If more points are provided an LMSE (Least Mean Squared Error) solution will be found.
      Parameters:
      result - instance where result will be stored.
      Throws:
      LockedException - if estimator is locked.
      NotReadyException - if not enough data has been provided.
      CoincidentPointsException - raised if transformation cannot be estimated for some reason (point configuration degeneracy, duplicate points or numerical instabilities).

    • computeCentroid

      private static com.irurueta.algebra.Matrix computeCentroid(List<Point2D> points) throws com.irurueta.algebra.AlgebraException
      Computes centroid of provided list of points using inhomogeneous coordinates.
      Parameters:
      points - list of points to compute centroid.
      Returns:
      centroid.
      Throws:
      com.irurueta.algebra.AlgebraException - never thrown.

    • internalSetPoints

      private void internalSetPoints(List<Point2D> inputPoints, List<Point2D> outputPoints)
      Internal method to set lists of points to be used to estimate an Euclidean 2D transformation. This method does not check whether estimator is locked or not.
      Parameters:
      inputPoints - list of input points to be used to estimate an Euclidean 2D transformation.
      outputPoints - list of output points to be used to estimate an Euclidean 2D transformation.
      Throws:
      IllegalArgumentException - if provided lists of points don't have the same size or their size is smaller than #getMinimumPoints.