Package com.irurueta.geometry.estimators

Class MetricTransformation3DEstimator

java.lang.Object
com.irurueta.geometry.estimators.MetricTransformation3DEstimator
public class MetricTransformation3DEstimator extends Object
Estimator of a 3D metric transformation based on point correspondences. A minimum of 4 non-coincident matched 3D input/output points is required for estimation. For some point configurations 3 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: http://stackoverflow.com/questions/13432805/finding-translation-and-scale-on-two-sets-of-points-to-get-least-square-error-in

  • 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 3 points.
      See Also:

    • inputPoints

      private List<Point3D> inputPoints
      3D input points.

    • outputPoints

      private List<Point3D> outputPoints
      3D output points.

    • listener

      private MetricTransformation3DEstimatorListener 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 3 points or not. True allows 3 points, false requires 4.

    • locked

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

  • Constructor Details

    • MetricTransformation3DEstimator

      public MetricTransformation3DEstimator()
      Constructor.

    • MetricTransformation3DEstimator

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

    • MetricTransformation3DEstimator

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

    • MetricTransformation3DEstimator

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

    • MetricTransformation3DEstimator

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

    • MetricTransformation3DEstimator

      public MetricTransformation3DEstimator(List<Point3D> inputPoints, List<Point3D> outputPoints, boolean weakMinimumSizeAllowed)
      Constructor.
      Parameters:
      inputPoints - 3D input points.
      outputPoints - 3D 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 4.

    • MetricTransformation3DEstimator

      public MetricTransformation3DEstimator(MetricTransformation3DEstimatorListener 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.

    • MetricTransformation3DEstimator

      public MetricTransformation3DEstimator(MetricTransformation3DEstimatorListener listener, List<Point3D> inputPoints, List<Point3D> outputPoints, boolean weakMinimumSizeAllowed)
      Constructor.
      Parameters:
      listener - listener to be notified of events such as when estimation starts or ends.
      inputPoints - 3D input points.
      outputPoints - 3D 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 4.

  • Method Details

    • getInputPoints

      public List<Point3D> getInputPoints()
      Returns list of input points to be used to estimate a metric 3D 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 #getMinimumPoints.
      Returns:
      list of input points to be used to estimate a metric 3D transformation.

    • getOutputPoints

      public List<Point3D> getOutputPoints()
      Returns list of output points to be used to estimate a metric 3D 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 #getMinimumPoints.
      Returns:
      list of output points to be used to estimate a metric 3D transformation.

    • setPoints

      public void setPoints(List<Point3D> inputPoints, List<Point3D> outputPoints) throws LockedException
      Sets list of points to be used to estimate a metric 3D 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 #getMinimumPoints.
      Parameters:
      inputPoints - list of input points to be used to estimate an Euclidean 3D transformation.
      outputPoints - list of output points to be used to estimate an Euclidean 3D transformation.
      Throws:
      IllegalArgumentException - if provided lists of points don't have the same size or their size is smaller than #getMinimumPoints.
      LockedException - if estimator is locked because a computation is already in progress.

    • getListener

      public MetricTransformation3DEstimatorListener 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(MetricTransformation3DEstimatorListener 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 3 points or not.
      Returns:
      true allows 3 points, false requires 4.

    • setWeakMinimumSizeAllowed

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

    • getMinimumPoints

      public int getMinimumPoints()
      Required minimum number of point correspondences to start the estimation. Can be either 3 or 4.
      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 metric 3D 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 MetricTransformation3D estimate() throws LockedException, NotReadyException, CoincidentPointsException
      Estimates a metric 3D transformation using the list of matched input and output 3D points. A minimum of 4 matched non-coincident points is required. If more points are provided an LMSE (Least Mean Squared Error) solution will be found.
      Returns:
      estimated metric 3D 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(MetricTransformation3D result) throws LockedException, NotReadyException, CoincidentPointsException
      Estimates a metric 3D transformation using the list of matched input and output 3D points. A minimum of 4 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<Point3D> 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<Point3D> inputPoints, List<Point3D> outputPoints)
      Internal method to set lists of points to be used to estimate a metric 3D transformation. This method does not check whether estimator is locked or not.
      Parameters:
      inputPoints - list of input points to be used to estimate a metric 3D transformation.
      outputPoints - list of output points to be used to estimate a metric 3D transformation.
      Throws:
      IllegalArgumentException - if provided lists of points don't have the same size or their size is smaller than #getMinimumPoints.