Package com.irurueta.ar.sfm

Class SinglePoint3DTriangulator

java.lang.Object
com.irurueta.ar.sfm.SinglePoint3DTriangulator
Direct Known Subclasses:
LMSEHomogeneousSinglePoint3DTriangulator, LMSEInhomogeneousSinglePoint3DTriangulator, WeightedHomogeneousSinglePoint3DTriangulator, WeightedInhomogeneousSinglePoint3DTriangulator
public abstract class SinglePoint3DTriangulator extends Object
Base class to triangulate matched 2D points into a single 3D one by using 2D points correspondences on different views along with the corresponding cameras on each of those views. Subclasses will implement different types of triangulators that can provide either LMSE or weighted solutions using either homogeneous or inhomogeneous systems of equations. Inhomogeneous methods are suitable only for cases where finite points and cameras are being used. If points or cameras are located very far or at infinity, triangulation will fail when using inhomogeneous methods. Homogeneous methods are suitable for any case, however, if points and cameras are close and well-defined, inhomogeneous methods might yield better accuracy (although the difference is minimal).

  • Field Details

    • DEFAULT_TYPE

      public static final Point3DTriangulatorType DEFAULT_TYPE
      Default triangulator type.

    • MIN_REQUIRED_VIEWS

      public static final int MIN_REQUIRED_VIEWS
      Minimum required number of views to triangulate 3D points.
      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

      protected SinglePoint3DTriangulatorListener listener
      Listener to handle events generated by instances of this class.

    • locked

      protected boolean locked
      Indicates whether this instance is locked doing computations.

  • Constructor Details

    • SinglePoint3DTriangulator

      protected SinglePoint3DTriangulator()
      Constructor.

    • SinglePoint3DTriangulator

      protected SinglePoint3DTriangulator(List<com.irurueta.geometry.Point2D> points2D, List<com.irurueta.geometry.PinholeCamera> cameras)
      Constructor.
      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 - camera 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.

    • SinglePoint3DTriangulator

      protected SinglePoint3DTriangulator(SinglePoint3DTriangulatorListener listener)
      Constructor.
      Parameters:
      listener - listener to notify events generated by instances of this class.

    • SinglePoint3DTriangulator

      protected SinglePoint3DTriangulator(List<com.irurueta.geometry.Point2D> points2D, List<com.irurueta.geometry.PinholeCamera> cameras, SinglePoint3DTriangulatorListener listener)
      Constructor.
      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.
      listener - listener to notify events generated by instances of this class.
      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

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

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

    • isLocked

      public boolean isLocked()
      Indicates whether this instance is locked because computations are being done.
      Returns:
      true if instance is locked, false otherwise.

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

    • getListener

      public SinglePoint3DTriangulatorListener getListener()
      Returns listener to be notified of events generated by instances of this class.
      Returns:
      listener to be notified of events generated by instances of this class.

    • setListener

      public void setListener(SinglePoint3DTriangulatorListener listener) throws com.irurueta.geometry.estimators.LockedException
      Sets listener to be notified of events generated by instances of this class.
      Parameters:
      listener - listener to be notified of events generated by instances of this class.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.

    • triangulate

      public com.irurueta.geometry.Point3D triangulate() throws com.irurueta.geometry.estimators.LockedException, com.irurueta.geometry.estimators.NotReadyException, Point3DTriangulationException
      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.
      Point3DTriangulationException - if triangulation fails for some other reason (i.e. degenerate geometry, numerical instabilities, etc.).

    • triangulate

      public void triangulate(com.irurueta.geometry.Point3D result) throws com.irurueta.geometry.estimators.LockedException, com.irurueta.geometry.estimators.NotReadyException, Point3DTriangulationException
      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.
      Parameters:
      result - instance where data for triangulated 3D point is stored.
      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.
      Point3DTriangulationException - if triangulation fails for some other reason (i.e. degenerate geometry, numerical instabilities, etc.).

    • areValidPointsAndCameras

      public static boolean areValidPointsAndCameras(List<com.irurueta.geometry.Point2D> points2D, List<com.irurueta.geometry.PinholeCamera> cameras)
      Indicates whether provided points and cameras are valid to start the triangulation. In order to triangulate points, at least two cameras and their corresponding 2 matched 2D points are required. If more views are provided, an averaged solution can be found.
      Parameters:
      points2D - list of matched points on each view.
      cameras - cameras for each view where 2D points are represented.
      Returns:
      true if data is enough to start triangulation, false otherwise.

    • create

      public static SinglePoint3DTriangulator create(Point3DTriangulatorType type)
      Creates a new 3D point triangulator instance using provided type.
      Parameters:
      type - a triangulator type.
      Returns:
      a 3D point triangulator instance.

    • create

      public static SinglePoint3DTriangulator create(List<com.irurueta.geometry.Point2D> points2D, List<com.irurueta.geometry.PinholeCamera> cameras, Point3DTriangulatorType type)
      Creates a new 3D point triangulator instance using provided lists of points and corresponding cameras along with provided type.
      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 - camera for each view where 2D points are represented.
      type - a triangulator type.
      Returns:
      a 3D point triangulator instance.
      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 SinglePoint3DTriangulator create(List<com.irurueta.geometry.Point2D> points2D, List<com.irurueta.geometry.PinholeCamera> cameras, double[] weights, Point3DTriangulatorType type)
      Creates a new 3D point triangulator instance using provided lists of points, weights and corresponding cameras along with provided type.
      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 - camera for each view where 2D points are represented.
      weights - weights assigned to each view.
      type - a triangulator type.
      Returns:
      a 3D point triangulator instance.
      Throws:
      IllegalArgumentException - if provided lists or weights 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 SinglePoint3DTriangulator create(SinglePoint3DTriangulatorListener listener, Point3DTriangulatorType type)
      Creates a new 3D point triangulator instance using provided listener and type.
      Parameters:
      listener - listener to notify events generated by instances of this class.
      type - a triangulator type.
      Returns:
      a 3D point triangulator instance.

    • create

      public static SinglePoint3DTriangulator create(List<com.irurueta.geometry.Point2D> points2D, List<com.irurueta.geometry.PinholeCamera> cameras, SinglePoint3DTriangulatorListener listener, Point3DTriangulatorType type)
      Creates a new 3D point triangulator instance using provided lists of points and corresponding cameras, listener and provided type.
      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 - camera for each view where 2D points are represented.
      listener - listener to notify events generated by instances of this class.
      type - a triangulator type.
      Returns:
      a 3D point triangulator instance.
      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 SinglePoint3DTriangulator create(List<com.irurueta.geometry.Point2D> points2D, List<com.irurueta.geometry.PinholeCamera> cameras, double[] weights, SinglePoint3DTriangulatorListener listener, Point3DTriangulatorType type)
      Creates a new 3D point triangulator instance using provided lists of points, weights, corresponding cameras, listener and provided type.
      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 - camera for each view where 2D points are represented.
      weights - weights assigned to each view.
      listener - listener to notify events generated by instances of this class.
      type - a triangulator type.
      Returns:
      a 3D point triangulator instance.
      Throws:
      IllegalArgumentException - if provided lists or weights 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 SinglePoint3DTriangulator create()
      Creates a new 3D point triangulator instance using default type.
      Returns:
      a 3D point triangulator instance.

    • create

      public static SinglePoint3DTriangulator create(List<com.irurueta.geometry.Point2D> points2D, List<com.irurueta.geometry.PinholeCamera> cameras)
      Creates a new 3D point triangulator instance using provided lists of points and corresponding cameras along with default type.
      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 - camera for each view where 2D points are represented.
      Returns:
      a 3D point triangulator instance.
      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 SinglePoint3DTriangulator create(List<com.irurueta.geometry.Point2D> points2D, List<com.irurueta.geometry.PinholeCamera> cameras, double[] weights)
      Creates a new 3D point triangulator instance using provided lists of points, weights and corresponding cameras along with default type.
      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 - camera for each view where 2D points are represented.
      weights - weights assigned to each view.
      Returns:
      a 3D point triangulator instance.
      Throws:
      IllegalArgumentException - if provided lists or weights 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 SinglePoint3DTriangulator create(SinglePoint3DTriangulatorListener listener)
      Creates a new 3D point triangulator instance using provided listener and default type.
      Parameters:
      listener - listener to notify events generated by instances of this class.
      Returns:
      a 3D point triangulator instance.

    • create

      public static SinglePoint3DTriangulator create(List<com.irurueta.geometry.Point2D> points2D, List<com.irurueta.geometry.PinholeCamera> cameras, SinglePoint3DTriangulatorListener listener)
      Creates a new 3D point triangulator instance using provided lists of points and corresponding cameras, listener and default type.
      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 - camera for each view where 2D points are represented.
      listener - listener to notify events generated by instances of this class.
      Returns:
      a 3D point triangulator instance.
      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 SinglePoint3DTriangulator create(List<com.irurueta.geometry.Point2D> points2D, List<com.irurueta.geometry.PinholeCamera> cameras, double[] weights, SinglePoint3DTriangulatorListener listener)
      Creates a new 3D point triangulator instance using provided lists of points, weights, corresponding cameras, listener and default type.
      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 - camera for each view where 2D points are represented.
      weights - weights assigned to each view.
      listener - listener to notify events generated by instances of this class.
      Returns:
      a 3D point triangulator instance.
      Throws:
      IllegalArgumentException - if provided lists or weights don't have the same length or their length is less than 2 views, which is the minimum required to compute triangulation.

    • getType

      public abstract Point3DTriangulatorType getType()
      Returns type of triangulator (a combination of homogeneous or inhomogeneous type along with an LMSE or weighted strategy).
      Returns:
      type of triangulator.

    • triangulate

      protected abstract void triangulate(List<com.irurueta.geometry.Point2D> points2D, List<com.irurueta.geometry.PinholeCamera> cameras, com.irurueta.geometry.Point3D result) throws Point3DTriangulationException
      Internal method to triangulate 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 is found. This method does not check whether instance is locked or ready.
      Parameters:
      points2D - 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.
      result - instance where triangulated 3D point is stored.
      Throws:
      Point3DTriangulationException - if triangulation fails for some other reason (i.e. degenerate geometry, numerical instabilities, etc.).

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