Class RobustSinglePoint3DTriangulator

java.lang.Object
com.irurueta.ar.sfm.RobustSinglePoint3DTriangulator
Direct Known Subclasses:
LMedSRobustSinglePoint3DTriangulator, MSACRobustSinglePoint3DTriangulator, PROMedSRobustSinglePoint3DTriangulator, PROSACRobustSinglePoint3DTriangulator, RANSACRobustSinglePoint3DTriangulator

public abstract class RobustSinglePoint3DTriangulator extends Object
Abstract class for algorithms to robustly triangulate 3D points from matched 2D points and their corresponding cameras on several views. Robust estimators can be used to estimate a more precise triangulation when there are more than 2 views where points have been matched.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected List<com.irurueta.geometry.PinholeCamera>
    List of cameras associated to the matched 2D point on the same position as the camera on the list.
    protected double
    Amount of confidence expressed as a value between 0.0 and 1.0 (which is equivalent to 100%).
    static final double
    Constant defining default confidence of the estimated result, which is 99%.
    static final int
    Default maximum allowed number of iterations.
    static final float
    Default amount of progress variation before notifying a change in estimation progress.
    static final com.irurueta.numerical.robust.RobustEstimatorMethod
    Default robust estimator method when none is provided.
    static final boolean
    Indicates whether by default a solution to an homogeneous system of equations should be found.
    Listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
    protected boolean
    Indicates if this estimator is locked because an estimation is being computed.
    static final double
    Maximum allowed confidence value.
    static final float
    Maximum allowed value for progress delta.
    protected int
    Maximum allowed number of iterations.
    static final double
    Minimum allowed confidence value.
    static final int
    Minimum allowed number of iterations.
    static final float
    Minimum allowed value for progress delta.
    static final int
    Minimum required number of views to triangulate 3D points.
    protected List<com.irurueta.geometry.Point2D>
    Matched 2D points.
    protected float
    Amount of progress variation before notifying a progress change during estimation.
    protected boolean
    Indicates whether a solution to an homogeneous system of equations should be found.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    Constructor.
    protected
    Constructor.
    protected
    RobustSinglePoint3DTriangulator(List<com.irurueta.geometry.Point2D> points, List<com.irurueta.geometry.PinholeCamera> cameras)
    Constructor.
    protected
    RobustSinglePoint3DTriangulator(List<com.irurueta.geometry.Point2D> points, List<com.irurueta.geometry.PinholeCamera> cameras, RobustSinglePoint3DTriangulatorListener listener)
    Constructor.
  • Method Summary

    Modifier and Type
    Method
    Description
    Creates a robust single 3D point triangulator using default robust method.
    create(com.irurueta.numerical.robust.RobustEstimatorMethod method)
    Creates a robust single 3D point triangulator using provided robust method.
    create(List<com.irurueta.geometry.Point2D> points, List<com.irurueta.geometry.PinholeCamera> cameras)
    Creates a robust single 3D point triangulator using provided points, cameras and default robust method.
    create(List<com.irurueta.geometry.Point2D> points, List<com.irurueta.geometry.PinholeCamera> cameras, double[] qualityScores)
    Creates a robust single 3D point triangulator using provided points, cameras and default robust method.
    create(List<com.irurueta.geometry.Point2D> points, List<com.irurueta.geometry.PinholeCamera> cameras, double[] qualityScores, com.irurueta.numerical.robust.RobustEstimatorMethod method)
    Creates a robust single 3D point triangulator using provided points, cameras and robust method.
    create(List<com.irurueta.geometry.Point2D> points, List<com.irurueta.geometry.PinholeCamera> cameras, com.irurueta.numerical.robust.RobustEstimatorMethod method)
    Creates a robust single 3D point triangulator using provided points, cameras and robust method.
    List<com.irurueta.geometry.PinholeCamera>
    Returns cameras for each view where 2D points are represented.
    double
    Returns amount of confidence expressed as a value between 0.0 and 1.0 (which is equivalent to 100%).
    Returns reference to listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
    int
    Returns maximum allowed number of iterations.
    abstract com.irurueta.numerical.robust.RobustEstimatorMethod
    Returns method being used for robust estimation.
    List<com.irurueta.geometry.Point2D>
    Returns list of matched 2D points on each view.
    float
    Returns amount of progress variation before notifying a progress change during estimation.
    double[]
    Returns quality scores corresponding to each view.
    private void
    internalSetPointsAndCameras(List<com.irurueta.geometry.Point2D> points2D, List<com.irurueta.geometry.PinholeCamera> cameras)
    Internal method to sets list of matched 2D points for each view and their corresponding cameras used to project them.
    boolean
    Indicates whether listener has been provided and is available for retrieval.
    boolean
    Indicates if this instance is locked because triangulation is being computed.
    boolean
    Indicates whether this instance is ready to start the triangulation.
    boolean
    Indicates whether a solution to an homogeneous system of equations should be found.
    void
    setConfidence(double confidence)
    Sets amount of confidence expressed as a value between 0.0 and 1.0 (which is equivalent to 100%).
    void
    Sets listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
    void
    setMaxIterations(int maxIterations)
    Sets maximum allowed number of iterations.
    void
    setPointsAndCameras(List<com.irurueta.geometry.Point2D> points2D, List<com.irurueta.geometry.PinholeCamera> cameras)
    Sets list of matched 2D points for each view and their corresponding cameras used to project them.
    void
    setProgressDelta(float progressDelta)
    Sets amount of progress variation before notifying a progress change during estimation.
    void
    setQualityScores(double[] qualityScores)
    Sets quality scores corresponding to each view.
    void
    setUseHomogeneousSolution(boolean useHomogeneousSolution)
    Sets boolean indicating whether a solution to an homogeneous system of equations should be found.
    abstract com.irurueta.geometry.Point3D
    Triangulates provided matched 2D points being projected by each corresponding camera into a single 3D point.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • DEFAULT_ROBUST_METHOD

      public static final com.irurueta.numerical.robust.RobustEstimatorMethod DEFAULT_ROBUST_METHOD
      Default robust estimator method when none is provided.
    • 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 chose 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_REQUIRED_VIEWS

      public static final int MIN_REQUIRED_VIEWS
      Minimum required number of views to triangulate 3D points.
      See Also:
    • DEFAULT_USE_HOMOGENEOUS_SOLUTION

      public static final boolean DEFAULT_USE_HOMOGENEOUS_SOLUTION
      Indicates whether by default a solution to an homogeneous system of equations should be found.
      See Also:
    • points2D

      protected List<com.irurueta.geometry.Point2D> points2D
      Matched 2D points. Each point in the list is assumed to be projected by the corresponding camera in the list.
    • cameras

      protected List<com.irurueta.geometry.PinholeCamera> cameras
      List of cameras associated to the matched 2D point on the same position as the camera on the list.
    • listener

      Listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
    • useHomogeneousSolution

      protected boolean useHomogeneousSolution
      Indicates whether a solution to an homogeneous system of equations should be found. Typically, this should be true, since even points and cameras at infinity can be used. If points are close and geometry is well-defined, false can be used to solve an inhomogeneous system of equations and obtain a slightly better accuracy.
    • 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.
  • Constructor Details

    • RobustSinglePoint3DTriangulator

      protected RobustSinglePoint3DTriangulator()
      Constructor.
    • RobustSinglePoint3DTriangulator

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

      protected RobustSinglePoint3DTriangulator(List<com.irurueta.geometry.Point2D> points, List<com.irurueta.geometry.PinholeCamera> cameras)
      Constructor.
      Parameters:
      points - Matched 2D points. Each point in the list is assumed to be projected by the corresponding camera in the list.
      cameras - List of cameras associated to the matched 2D point on the same position as the camera on the list.
      Throws:
      IllegalArgumentException - if provided lists don't have the same length or their length is less than 2 views, which is the minimum required to compute triangulation.
    • RobustSinglePoint3DTriangulator

      protected RobustSinglePoint3DTriangulator(List<com.irurueta.geometry.Point2D> points, List<com.irurueta.geometry.PinholeCamera> cameras, RobustSinglePoint3DTriangulatorListener listener)
      Constructor.
      Parameters:
      points - Matched 2D points. Each point in the list is assumed to be projected by the corresponding camera in the list.
      cameras - List of cameras associated to the matched 2D point on the same position as the camera on the list.
      listener - listener to be notified of events such as when estimation starts, ends or its progress significantly changes.
      Throws:
      IllegalArgumentException - if provided lists don't have the same length or their length is less than 2 views, which is the minimum required to compute triangulation.
  • Method Details

    • 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(RobustSinglePoint3DTriangulatorListener listener) throws com.irurueta.geometry.estimators.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:
      com.irurueta.geometry.estimators.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.
    • isUseHomogeneousSolution

      public boolean isUseHomogeneousSolution()
      Indicates whether a solution to an homogeneous system of equations should be found. Typically, this should be true, since even points and cameras at infinity can be used. If points are close and geometry is well-defined, false can be used to solve an inhomogeneous system of equations and obtain a slightly better accuracy.
      Returns:
      true if an homogeneous solution must be found (default value), false otherwise.
    • setUseHomogeneousSolution

      public void setUseHomogeneousSolution(boolean useHomogeneousSolution) throws com.irurueta.geometry.estimators.LockedException
      Sets boolean indicating whether a solution to an homogeneous system of equations should be found. Typically, this should be true, since even points and cameras at infinity can be used. If points are close and geometry is well-defined, false can be used to solve an inhomogeneous system of equations and obtain a slightly better accuracy.
      Parameters:
      useHomogeneousSolution - true if an homogeneous solution will be found, false if an inhomogeneous solution will be found instead.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
    • isLocked

      public boolean isLocked()
      Indicates if this instance is locked because triangulation 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 com.irurueta.geometry.estimators.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.
      com.irurueta.geometry.estimators.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 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 com.irurueta.geometry.estimators.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.
      com.irurueta.geometry.estimators.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 com.irurueta.geometry.estimators.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.
      com.irurueta.geometry.estimators.LockedException - if this estimator is locked because an estimation is being computed.
    • setPointsAndCameras

      public void setPointsAndCameras(List<com.irurueta.geometry.Point2D> points2D, List<com.irurueta.geometry.PinholeCamera> cameras) throws com.irurueta.geometry.estimators.LockedException
      Sets list of matched 2D points for each view and their corresponding cameras used to project them.
      Parameters:
      points2D - list of matched 2D points on each view. Each point in the list is assumed to be projected by the corresponding camera in the list.
      cameras - cameras for each view where 2D points are represented.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      IllegalArgumentException - if provided lists don't have the same length or their length is less than 2 views, which is the minimum required to compute triangulation.
    • getPoints2D

      public List<com.irurueta.geometry.Point2D> getPoints2D()
      Returns list of matched 2D points on each view. Each point in the list is assumed to be projected by the corresponding camera.
      Returns:
      list of matched 2D points on each view.
    • getCameras

      public List<com.irurueta.geometry.PinholeCamera> getCameras()
      Returns cameras for each view where 2D points are represented.
      Returns:
      cameras for each view where 2D points are represented.
    • getQualityScores

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

      public void setQualityScores(double[] qualityScores) throws com.irurueta.geometry.estimators.LockedException
      Sets quality scores corresponding to each view. The larger the score value the better the quality of the view sample. This implementation makes no action. Subclasses using quality scores must implement proper behaviour.
      Parameters:
      qualityScores - quality scores corresponding to each view.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if robust estimator is locked because an estimation is already in progress.
      IllegalArgumentException - if provided quality scores length is smaller than MIN_REQUIRED_VIEWS (i.e. 2 views).
    • isReady

      public boolean isReady()
      Indicates whether this instance is ready to start the triangulation. An instance is ready when both lists of 2D points and cameras are provided, both lists have the same length and at least data for 2 views is provided.
      Returns:
      true if this instance is ready, false otherwise.
    • triangulate

      public abstract com.irurueta.geometry.Point3D triangulate() throws com.irurueta.geometry.estimators.LockedException, com.irurueta.geometry.estimators.NotReadyException, com.irurueta.numerical.robust.RobustEstimatorException
      Triangulates provided matched 2D points being projected by each corresponding camera into a single 3D point. At least 2 matched 2D points and their corresponding 2 cameras are required to compute triangulation. If more views are provided, an averaged solution can be found.
      Returns:
      computed triangulated 3D point.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      com.irurueta.geometry.estimators.NotReadyException - if lists of points and cameras don't have the same length or less than 2 views are provided.
      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.
    • create

      public static RobustSinglePoint3DTriangulator create(com.irurueta.numerical.robust.RobustEstimatorMethod method)
      Creates a robust single 3D point triangulator using provided robust method.
      Parameters:
      method - method of a robust estimator algorithm to estimate the best triangulation.
      Returns:
      an instance of a robust single 3D point triangulator.
    • create

      public static RobustSinglePoint3DTriangulator create(List<com.irurueta.geometry.Point2D> points, List<com.irurueta.geometry.PinholeCamera> cameras, com.irurueta.numerical.robust.RobustEstimatorMethod method)
      Creates a robust single 3D point triangulator using provided points, cameras and robust method.
      Parameters:
      points - matched 2D points. Each point in the list is assumed to be projected by the corresponding camera in the list.
      cameras - list of cameras associated to the matched 2D point on the same position as the camera on the list.
      method - method of a robust estimator algorithm to estimate the best triangulation.
      Returns:
      an instance of a robust single 3D point triangulator.
      Throws:
      IllegalArgumentException - if provided lists don't have the same length or their length is less than 2 views, which is the minimum required to compute triangulation.
    • create

      public static RobustSinglePoint3DTriangulator create(List<com.irurueta.geometry.Point2D> points, List<com.irurueta.geometry.PinholeCamera> cameras, double[] qualityScores, com.irurueta.numerical.robust.RobustEstimatorMethod method)
      Creates a robust single 3D point triangulator using provided points, cameras and robust method.
      Parameters:
      points - matched 2D points. Each point in the list is assumed to be projected by the corresponding camera in the list.
      cameras - list of cameras associated to the matched 2D point on the same position as the camera on the list.
      qualityScores - quality scores corresponding to each point.
      method - method of a robust estimator algorithm to estimate the best triangulation.
      Returns:
      an instance of a robust single 3D point triangulator.
      Throws:
      IllegalArgumentException - if provided lists or quality scores don't have the same length or their length is less than 2 views, which is the minimum required to compute triangulation.
    • create

      public static RobustSinglePoint3DTriangulator create()
      Creates a robust single 3D point triangulator using default robust method.
      Returns:
      an instance of a robust single 3D point triangulator.
    • create

      public static RobustSinglePoint3DTriangulator create(List<com.irurueta.geometry.Point2D> points, List<com.irurueta.geometry.PinholeCamera> cameras)
      Creates a robust single 3D point triangulator using provided points, cameras and default robust method.
      Parameters:
      points - matched 2D points. Each point in the list is assumed to be projected by the corresponding camera in the list.
      cameras - list of cameras associated to the matched 2D point on the same position as the camera on the list.
      Returns:
      an instance of a robust single 3D point triangulator.
      Throws:
      IllegalArgumentException - if provided lists don't have the same length or their length is less than 2 views, which is the minimum required to compute triangulation.
    • create

      public static RobustSinglePoint3DTriangulator create(List<com.irurueta.geometry.Point2D> points, List<com.irurueta.geometry.PinholeCamera> cameras, double[] qualityScores)
      Creates a robust single 3D point triangulator using provided points, cameras and default robust method.
      Parameters:
      points - matched 2D points. Each point in the list is assumed to be projected by the corresponding camera in the list.
      cameras - list of cameras associated to the matched 2D point on the same position as the camera on the list.
      qualityScores - quality scores corresponding to each point.
      Returns:
      an instance of a robust single 3D point triangulator.
      Throws:
      IllegalArgumentException - if provided lists or quality scores don't have the same length or their length is less than 2 views, which is the minimum required to compute triangulation.
    • internalSetPointsAndCameras

      private void internalSetPointsAndCameras(List<com.irurueta.geometry.Point2D> points2D, List<com.irurueta.geometry.PinholeCamera> cameras)
      Internal method to sets list of matched 2D points for each view and their corresponding cameras used to project them. This method does not check whether instance is locked.
      Parameters:
      points2D - list of matched 2D points on each view. Each point in the list is assumed to be projected by the corresponding camera in the list.
      cameras - cameras for each view where 2D points are represented.
      Throws:
      IllegalArgumentException - if provided lists don't have the same length or their length is less than 2 views, which is the minimum required to compute triangulation.