Package com.irurueta.numerical.robust

Class RANSACRobustEstimator<T>

java.lang.Object
com.irurueta.numerical.robust.RobustEstimator<T>
com.irurueta.numerical.robust.RANSACRobustEstimator<T>
Type Parameters:
T - type of object to be estimated.
public class RANSACRobustEstimator<T> extends RobustEstimator<T>
This class implements RANSAC (RANdom SAmple Consensus) algorithm to robustly estimate a data model. RANSAC is based on the idea that given a proportion of outliers (that is estimated while the algorithm is run), it is needed a certain number of random sub-samples to obtain required data with a certain level of confidence. To determine whether a sample is an outlier or not, provided constant threshold is used. If a threshold cannot be determined beforehand, then it is better to use LMedS algorithm, at the expense of slightly less accurate results.

  • Field Details

    • 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:

    • MIN_THRESHOLD

      public static final double MIN_THRESHOLD
      Minimum allowed threshold to determine inliers.
      See Also:

    • DEFAULT_COMPUTE_AND_KEEP_INLIERS

      public static final boolean DEFAULT_COMPUTE_AND_KEEP_INLIERS
      Indicates that by default inliers will only be computed but not kept.
      See Also:

    • DEFAULT_COMPUTE_AND_KEEP_RESIDUALS

      public static final boolean DEFAULT_COMPUTE_AND_KEEP_RESIDUALS
      Indicates that by default residuals will only be computed but not kept.
      See Also:

    • confidence

      private double confidence
      Amount of confidence expressed as a value between 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

      private 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.

    • subsetSelector

      private SubsetSelector subsetSelector
      Instance in charge of picking random subsets of samples.

    • nIters

      private int nIters
      Number of iterations to be done to obtain required confidence.

    • bestResult

      private T bestResult
      Best solution that has been found so far during an estimation.

    • bestInliersData

      private RANSACRobustEstimator.RANSACInliersData bestInliersData
      Data related to inliers found for best result.

    • computeAndKeepInliers

      private boolean computeAndKeepInliers
      Indicates whether inliers must be computed and kept.

    • computeAndKeepResiduals

      private boolean computeAndKeepResiduals
      Indicates whether residuals must be computed and kept.

  • Constructor Details

    • RANSACRobustEstimator

      public RANSACRobustEstimator()
      Constructor.

    • RANSACRobustEstimator

      public RANSACRobustEstimator(RANSACRobustEstimatorListener<T> listener)
      Constructor with listener.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes, as well as in charge of picking samples and doing per-iteration estimations.

  • Method Details

    • getConfidence

      public double getConfidence()
      Returns amount of confidence expressed as a value between 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 LockedException
      Sets amount of confidence expressed as a value between 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 estimation is being computed.

    • getMaxIterations

      public int getMaxIterations()
      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.
      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.

    • getNIters

      public int getNIters()
      Returns number of iterations to be done to obtain required confidence.
      Returns:
      number of iterations to be done to obtain required confidence.

    • getBestResult

      public T getBestResult()
      Returns best solution that has been found so far during an estimation.
      Returns:
      best solution that has been found so far during an estimation.

    • getBestInliersData

      public RANSACRobustEstimator.RANSACInliersData getBestInliersData()
      Gets data related to inliers found for best result.
      Returns:
      data related to inliers found for best result.

    • isComputeAndKeepInliersEnabled

      public boolean isComputeAndKeepInliersEnabled()
      Indicates whether inliers must be computed and kept.
      Returns:
      true if inliers must be computed and kept, false if inliers only need to be computed but not kept.

    • setComputeAndKeepInliersEnabled

      public void setComputeAndKeepInliersEnabled(boolean computeAndKeepInliers) throws LockedException
      Specifies whether inliers must be computed and kept.
      Parameters:
      computeAndKeepInliers - true if inliers must be computed and kept, false if inliers only need to be computed but not kept.
      Throws:
      LockedException - if estimator is locked.

    • isComputeAndKeepResidualsEnabled

      public boolean isComputeAndKeepResidualsEnabled()
      Indicates whether residuals must be computed and kept.
      Returns:
      true if residuals must be computed and kept, false if residuals only need to be computed but not kept.

    • setComputeAndKeepResidualsEnabled

      public void setComputeAndKeepResidualsEnabled(boolean computeAndKeepResiduals) throws LockedException
      Specifies whether residuals must be computed and kept.
      Parameters:
      computeAndKeepResiduals - true if residuals must be computed and kept, false if residuals only need to be computed but not kept.
      Throws:
      LockedException - if estimator is locked.

    • isReady

      public boolean isReady()
      Indicates if estimator is ready to start the estimation process.
      Overrides:
      isReady in class RobustEstimator<T>
      Returns:
      true if ready, false otherwise.

    • estimate

      public T estimate() throws LockedException, NotReadyException, RobustEstimatorException
      Robustly estimates an instance of T.
      Specified by:
      estimate in class RobustEstimator<T>
      Returns:
      estimated object.
      Throws:
      LockedException - if robust estimator is locked.
      NotReadyException - if provided input data is not enough to start the estimation.
      RobustEstimatorException - if estimation fails for any reason (i.e. numerical instability, no solution available, etc).

    • getInliersData

      public InliersData getInliersData()
      Returns data about inliers once estimation has been done.
      Specified by:
      getInliersData in class RobustEstimator<T>
      Returns:
      data about inliers or null if estimation has not been done.

    • getMethod

      public RobustEstimatorMethod getMethod()
      Returns method being used for robust estimation.
      Specified by:
      getMethod in class RobustEstimator<T>
      Returns:
      method being used for robust estimation.