Package com.irurueta.geometry.estimators

Class DualQuadricRobustEstimator

java.lang.Object
com.irurueta.geometry.estimators.DualQuadricRobustEstimator
Direct Known Subclasses:
LMedSDualQuadricRobustEstimator, MSACDualQuadricRobustEstimator, PROMedSDualQuadricRobustEstimator, PROSACDualQuadricRobustEstimator, RANSACDualQuadricRobustEstimator
public abstract class DualQuadricRobustEstimator extends Object
This is an abstract class for algorithms to robustly find the best dual quadric that fits in a collection of 3D planes. Implementations of this class should be able to detect and discard outliers in order to find the best solution.

  • Field Details

    • MINIMUM_SIZE

      public static final int MINIMUM_SIZE
      Minimum number of 3D planes required to estimate a Dual Quadric.
      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:

    • DEFAULT_ROBUST_METHOD

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

    • listener

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

    • locked

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

    • planes

      protected List<Plane> planes
      List of planes to be used to estimate a dual quadric. Provided list must have a size greater or equal than MINIMUM_SIZE.

    • testPlane

      private com.irurueta.algebra.Matrix testPlane
      Matrix representation of a 3D plane to be reused when computing residuals

    • testDualQ

      private com.irurueta.algebra.Matrix testDualQ
      Matrix representation of a dual quadric to be reused when computing residuals.

  • Constructor Details

    • DualQuadricRobustEstimator

      protected DualQuadricRobustEstimator()
      Constructor.

    • DualQuadricRobustEstimator

      protected DualQuadricRobustEstimator(DualQuadricRobustEstimatorListener listener)
      Constructor.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.

    • DualQuadricRobustEstimator

      protected DualQuadricRobustEstimator(List<Plane> planes)
      Constructor with lines.
      Parameters:
      planes - planes to estimate a dual quadric.
      Throws:
      IllegalArgumentException - if provided list of planes don't have a size greater or equal than MINIMUM_SIZE.

    • DualQuadricRobustEstimator

      protected DualQuadricRobustEstimator(DualQuadricRobustEstimatorListener listener, List<Plane> planes)
      Constructor.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      planes - planes to estimate a dual quadric.
      Throws:
      IllegalArgumentException - if provided list of planes don't have a size greater or equal than MINIMUM_SIZE.

  • Method Details

    • getListener

      public DualQuadricRobustEstimatorListener 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(DualQuadricRobustEstimatorListener listener) throws 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:
      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()
      Indicates if this instance is locked because estimation is being computed.
      Returns:
      true if 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 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.
      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 that 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 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.
      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 converging to a result when calling estimate(), a RobustEstimatorException will be raised.
      Returns:
      maximum allowed number of iterations.

    • setMaxIterations

      public void setMaxIterations(int maxIterations) throws 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.
      LockedException - if this estimator is locked because an estimation is being computed.

    • getPlanes

      public List<Plane> getPlanes()
      Returns list of planes to be used to estimate a dual quadric. Provided list have a size greater or equal than MINIMUM_SIZE.
      Returns:
      list of planes to be used to estimate a dual quadric.

    • setPlanes

      public void setPlanes(List<Plane> planes) throws LockedException
      Sets list of planes to be used to estimate a dual quadric. Provided list must have a size greater or equal than MINIMUM_SIZE.
      Parameters:
      planes - list of planes to be used to estimate a dual quadric.
      Throws:
      IllegalArgumentException - if provided list of planes doesn't have a size greater or equal than MINIMUM_SIZE.
      LockedException - if estimator is locked because a computation is already in progress.

    • isReady

      public boolean isReady()
      Indicates if estimator is ready to start the dual quadric estimation. This is true when MINIMUM_SIZE lines are available.
      Returns:
      true if estimator is ready, false otherwise.

    • getQualityScores

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

    • setQualityScores

      public void setQualityScores(double[] qualityScores) throws LockedException
      Sets quality scores corresponding to each plane. The larger the score value the better the quality of the matching. This implementation makes no action. Subclasses using quality scores must implement proper behaviour.
      Parameters:
      qualityScores - quality scores corresponding to each plane.
      Throws:
      LockedException - if robust estimator is locked because an estimation is already in progress.
      IllegalArgumentException - if provided quality scores length is smaller than MINIMUM_SIZE (i.e. 9 samples).

    • create

      public static DualQuadricRobustEstimator create(com.irurueta.numerical.robust.RobustEstimatorMethod method)
      Creates a dual quadric robust estimator based on plane samples and using provided robust estimator method.
      Parameters:
      method - method of a robust estimator algorithm to estimate bes dual quadric.
      Returns:
      an instance of a dual quadric robust estimator.

    • create

      public static DualQuadricRobustEstimator create(List<Plane> planes, com.irurueta.numerical.robust.RobustEstimatorMethod method)
      Creates a dual quadric robust estimator based on plane samples and using provided planes and robust estimator method.
      Parameters:
      planes - 3D planes to estimate a dual quadric.
      method - method of a robust estimator algorithm to estimate the best dual quadric.
      Returns:
      an instance of a dual quadric robust estimator.
      Throws:
      IllegalArgumentException - if provided list of planes don't have a size greater or equal than MINIMUM_SIZE.

    • create

      public static DualQuadricRobustEstimator create(DualQuadricRobustEstimatorListener listener, com.irurueta.numerical.robust.RobustEstimatorMethod method)
      Creates a dual quadric robust estimator based on plane samples and using provided listener.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      method - method of a robust estimator algorithm to estimate the best dual quadric.
      Returns:
      an instance of a dual quadric robust estimator.

    • create

      public static DualQuadricRobustEstimator create(DualQuadricRobustEstimatorListener listener, List<Plane> planes, com.irurueta.numerical.robust.RobustEstimatorMethod method)
      Creates a dual quadric robust estimator based on plane samples and using provided listener and planes.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      planes - 3D planes to estimate a dual quadric.
      method - method of a robust estimator algorithm to estimate the best dual quadric.
      Returns:
      an instance of a dual quadric robust estimator.
      Throws:
      IllegalArgumentException - if provided list of planes don't have a size greater or equal than MINIMUM_SIZE.

    • create

      public static DualQuadricRobustEstimator create(double[] qualityScores, com.irurueta.numerical.robust.RobustEstimatorMethod method)
      Creates a dual quadric robust estimator based on plane samples and using provided robust estimator method.
      Parameters:
      qualityScores - quality scores corresponding to each provided plane.
      method - method of a robust estimator algorithm to estimate bes dual quadric.
      Returns:
      an instance of a dual quadric robust estimator.
      Throws:
      IllegalArgumentException - if provided quality scores length is smaller than MINIMUM_SIZE (i.e. 9 planes).

    • create

      public static DualQuadricRobustEstimator create(List<Plane> planes, double[] qualityScores, com.irurueta.numerical.robust.RobustEstimatorMethod method)
      Creates a dual quadric robust estimator method based on plane samples and using provided planes and robust estimator method.
      Parameters:
      planes - 3D planes to estimate a dual quadric.
      qualityScores - quality scores corresponding to each provided plane.
      method - method of a robust estimator algorithm to estimate the best dual quadric.
      Returns:
      an instance of a dual quadric robust estimator.
      Throws:
      IllegalArgumentException - if provided list of planes don't have the same size as the list of provided quality scores, or if their size is not greater or equal than MINIMUM_SIZE.

    • create

      public static DualQuadricRobustEstimator create(DualQuadricRobustEstimatorListener listener, double[] qualityScores, com.irurueta.numerical.robust.RobustEstimatorMethod method)
      Creates a dual quadric robust estimator based on plane samples and using provided listener.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      qualityScores - quality scores corresponding to each provided plane.
      method - method of a robust estimator algorithm to estimate the best dual quadric.
      Returns:
      an instance of a dual quadric robust estimator.
      Throws:
      IllegalArgumentException - if provided quality scores length is smaller than MINIMUM_SIZE (i.e. 9 planes).

    • create

      public static DualQuadricRobustEstimator create(DualQuadricRobustEstimatorListener listener, List<Plane> planes, double[] qualityScores, com.irurueta.numerical.robust.RobustEstimatorMethod method)
      Creates a dual conic robust estimator based on 3D plane samples and using provided listener and planes.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      planes - 3D planes to estimate a dual quadric.
      qualityScores - quality scores corresponding to each provided plane.
      method - method of a robust estimator algorithm to estimate the best dual quadric.
      Returns:
      an instance of a dual quadric robust estimator.
      Throws:
      IllegalArgumentException - if provided list of planes don't have the same size as the list of provided quality scores, or it their size is not greater or equal than MINIMUM_SIZE.

    • create

      public static DualQuadricRobustEstimator create()
      Creates a dual quadric robust estimator based on plane samples and using default robust estimator method.
      Returns:
      an instance of a dual quadric robust estimator.

    • create

      public static DualQuadricRobustEstimator create(List<Plane> planes)
      Creates a dual quadric robust estimator based on plane samples and using provided planes and default robust estimator method.
      Parameters:
      planes - 3D planes to estimate a dual quadric.
      Returns:
      an instance of a dual quadric robust estimator.
      Throws:
      IllegalArgumentException - if provided list of planes doesn't have a size greater or equal than MINIMUM_SIZE.

    • create

      public static DualQuadricRobustEstimator create(DualQuadricRobustEstimatorListener listener)
      Creates a dual quadric robust estimator based on plane samples and using provided listener and default robust estimator method.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      Returns:
      an instance of a dual quadric robust estimator.

    • create

      public static DualQuadricRobustEstimator create(DualQuadricRobustEstimatorListener listener, List<Plane> planes)
      Creates a dual quadric robust estimator based on plane samples and using provided listener and lines and default robust estimator method.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      planes - 3D planes to estimate a dual quadric.
      Returns:
      an instance of a dual conic robust estimator.
      Throws:
      IllegalArgumentException - if provided list of planes doesn't have a size greater or equal than MINIMUM_SIZE.

    • create

      public static DualQuadricRobustEstimator create(double[] qualityScores)
      Creates a dual quadric robust estimator based on 3D plane samples and using default robust estimator method.
      Parameters:
      qualityScores - quality scores corresponding to each provided plane.
      Returns:
      an instance of a dual quadric robust estimator.
      Throws:
      IllegalArgumentException - if provided quality scores length is smaller than MINIMUM_SIZE (i.e. 9 planes).

    • create

      public static DualQuadricRobustEstimator create(List<Plane> planes, double[] qualityScores)
      Creates a dual quadric robust estimator based on plane samples and using provided planes and default estimator method.
      Parameters:
      planes - 3D planes to estimate a dual quadric.
      qualityScores - quality scores corresponding to each provided plane.
      Returns:
      an instance of a dual conic robust estimator.
      Throws:
      IllegalArgumentException - if provided list of planes don't have the same size as the list of provided quality scores, or if their size is not greater or equal than MINIMUM_SIZE.

    • create

      public static DualQuadricRobustEstimator create(DualQuadricRobustEstimatorListener listener, double[] qualityScores)
      Creates a dual quadric robust estimator based on plane samples and using provided listener and default estimator method.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      qualityScores - quality scores corresponding to each provided plane
      Returns:
      an instance of a dual quadric robust estimator.
      Throws:
      IllegalArgumentException - if provided quality scores length is smaller than MINIMUM_SIZE (i.e. 9 planes).

    • create

      public static DualQuadricRobustEstimator create(DualQuadricRobustEstimatorListener listener, List<Plane> planes, double[] qualityScores)
      Creates a dual quadric robust estimator based on plane samples and using provided listener and planes and default estimator method.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      planes - 3D planes to estimate a dual quadric.
      qualityScores - quality scores corresponding to each provided plane
      Returns:
      an instance of a dual quadric robust estimator.
      Throws:
      IllegalArgumentException - if provided list of planes don't have the same size as the list of provided quality scores, or if their size is not greater or equal than MINIMUM_SIZE.

    • estimate

      public abstract DualQuadric estimate() throws LockedException, NotReadyException, com.irurueta.numerical.robust.RobustEstimatorException
      Estimates a dual conic using a robust estimator and the best set of 3D planes that fit into the locus of the estimated dual quadric found using the robust estimator.
      Returns:
      a dual quadric.
      Throws:
      LockedException - if robust estimator is locked because an estimation is already in progress.
      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.

    • internalSetPlanes

      private void internalSetPlanes(List<Plane> planes)
      Internal method to set list of planes to be used to estimate a dual quadric. This method does not check whether estimator is locked or not.
      Parameters:
      planes - list of planes to be used to estimate a dual quadric.
      Throws:
      IllegalArgumentException - if provided list of planes doesn't have a size greater or equal than MINIMUM_SIZE.

    • residual

      protected double residual(DualQuadric dq, Plane plane)
      Computes the residual between a dual quadric and a 3D plane.
      Parameters:
      dq - a dual quadric.
      plane - a 3D plane.
      Returns:
      residual.