Package com.irurueta.ar.epipolar.estimators

Class HomographyDecomposer

java.lang.Object
com.irurueta.ar.epipolar.estimators.HomographyDecomposer
public class HomographyDecomposer extends Object
Decomposes a 2D homography to extract its internal geometry structure. There are four possible solutions, with two that are physically possible. The physically possible solution can be found by imposing a positive depth constraint (reconstructed points must lie in front of the cameras). An homography matrix is defined as H = (R + (1/d)*T*NT), where R is a 3x3 rotation matrix, d is the distance of the plane, N is the plane's normal, T is the translation vector. The decomposition works by computing the SVD of HTH and then following the procedure defined in O. Faugeras, Motion and structure from motion in a piecewise planar environment.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    EQUAL_SINGULAR_VALUE_THRESHOLD
    Threshold to determine that two singular values are equal.
    private com.irurueta.geometry.Transformation2D
    homography
    2D transformation relating two views (left view to right view).
    private com.irurueta.geometry.PinholeCameraIntrinsicParameters
    leftIntrinsics
    Intrinsic parameters to be used on left view.
    private HomographyDecomposerListener
    listener
    Listener to handle events raised by this instance.
    private boolean
    locked
    Indicates whether decomposer is locked while computing decomposition.
    static final int
    NUM_COORDS_3D
    Number of inhomogeneous coordinates in 3D.
    private com.irurueta.geometry.PinholeCameraIntrinsicParameters
    rightIntrinsics
    Intrinsic parameters to be used on right view.

  • Constructor Summary

    Constructors
    Constructor
    Description
    HomographyDecomposer()
    Constructor.
    HomographyDecomposer(com.irurueta.geometry.Transformation2D homography, com.irurueta.geometry.PinholeCameraIntrinsicParameters leftIntrinsics, com.irurueta.geometry.PinholeCameraIntrinsicParameters rightIntrinsics)
    Constructor.
    HomographyDecomposer(com.irurueta.geometry.Transformation2D homography, com.irurueta.geometry.PinholeCameraIntrinsicParameters leftIntrinsics, com.irurueta.geometry.PinholeCameraIntrinsicParameters rightIntrinsics, HomographyDecomposerListener listener)
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    private static boolean
    areThreeDifferentSingularValues(double[] singularValues)
    Determines whether there are three different singular values or not.
    private static boolean
    areTwoEqualSingularValues(double[] singularValues)
    Determines whether there are two equal singular values or not.
    private com.irurueta.algebra.Matrix
    computeNormalizedCoordinatesHomographyMatrix()
    Computes homography matrix in terms of normalized point coordinates by taking into account intrinsic camera parameters on left and right views.
    List<HomographyDecomposition>
    decompose()
    Decomposes homography into possible solutions containing possible 3D rotation, 3D translation and normal and distance of the plane relating two views via provided homography.
    void
    decompose(List<HomographyDecomposition> result)
    Decomposes homography into possible solutions containing possible 3D rotation, 3D translation and normal and distance of the plane relating two views via provided homography.
    private int
    decomposeAllFromSingularValues(double[] singularValues, List<double[]> n, List<com.irurueta.algebra.Matrix> r, List<double[]> t, List<Double> d)
    Decompose solutions from singular values.
    private double
    decomposeFromSingularValues(double[] singularValues, double[] n, com.irurueta.algebra.Matrix r, double[] t, boolean positive1, boolean positive3)
    Decomposes one possible solution using provided singular values and signs
    private double
    decomposeFromThreeDifferentSingularValuesNegative(double d1, double d2, double d3, double[] n, com.irurueta.algebra.Matrix r, double[] t, boolean positive1, boolean positive3)
    Generates one homography decomposition using provided singular values and assuming that there are three different singular values and that d2 is negative.
    private double
    decomposeFromThreeDifferentSingularValuesPositive(double d1, double d2, double d3, double[] n, com.irurueta.algebra.Matrix r, double[] t, boolean positive1, boolean positive3)
    Generates one homography decomposition using provided singular values and assuming that there are three different singular values and that d2 is positive.
    private double
    decomposeFromTwoDifferentSingularValuesNegative(double d1, double d2, double d3, double[] n, com.irurueta.algebra.Matrix r, double[] t, boolean positive3)
    Generates one homography decomposition using provided singular values and assuming that there are two equal singular values and that d2 is negative.
    private double
    decomposeFromTwoDifferentSingularValuesPositive(double d1, double d2, double d3, double[] n, com.irurueta.algebra.Matrix r, double[] t, boolean positive3)
    Generates one homography decomposition using provided singular values and assuming that there are two equal singular values and that d2 is positive.
    com.irurueta.geometry.Transformation2D
    getHomography()
    Gets 2D transformation relating two views (left view to right view).
    com.irurueta.geometry.PinholeCameraIntrinsicParameters
    getLeftIntrinsics()
    Gets intrinsic parameters to be used on left view.
    HomographyDecomposerListener
    getListener()
    Gets listener to handle events raised by this instance.
    com.irurueta.geometry.PinholeCameraIntrinsicParameters
    getRightIntrinsics()
    Gets intrinsic parameters to be used on right view.
    boolean
    isLocked()
    Indicates whether estimator is locked while computing decomposition.
    boolean
    isReady()
    Indicates whether decomposer is ready to start the decomposition when all required data has been provided.
    void
    setHomography(com.irurueta.geometry.Transformation2D homography)
    Sets 2D transformation relating two views (left view to right view).
    void
    setLeftIntrinsics(com.irurueta.geometry.PinholeCameraIntrinsicParameters leftIntrinsics)
    Sets intrinsic parameters to be used on left view.
    void
    setListener(HomographyDecomposerListener listener)
    Sets listener to handle events raised by this instance.
    void
    setRightIntrinsics(com.irurueta.geometry.PinholeCameraIntrinsicParameters rightIntrinsics)
    Sets intrinsic parameters to be used on right view.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • NUM_COORDS_3D

      public static final int NUM_COORDS_3D
      Number of inhomogeneous coordinates in 3D.
      See Also:

    • EQUAL_SINGULAR_VALUE_THRESHOLD

      public static final double EQUAL_SINGULAR_VALUE_THRESHOLD
      Threshold to determine that two singular values are equal.
      See Also:

    • homography

      private com.irurueta.geometry.Transformation2D homography
      2D transformation relating two views (left view to right view).

    • leftIntrinsics

      private com.irurueta.geometry.PinholeCameraIntrinsicParameters leftIntrinsics
      Intrinsic parameters to be used on left view.

    • rightIntrinsics

      private com.irurueta.geometry.PinholeCameraIntrinsicParameters rightIntrinsics
      Intrinsic parameters to be used on right view.

    • listener

      private HomographyDecomposerListener listener
      Listener to handle events raised by this instance.

    • locked

      private boolean locked
      Indicates whether decomposer is locked while computing decomposition.

  • Constructor Details

    • HomographyDecomposer

      public HomographyDecomposer()
      Constructor.

    • HomographyDecomposer

      public HomographyDecomposer(com.irurueta.geometry.Transformation2D homography, com.irurueta.geometry.PinholeCameraIntrinsicParameters leftIntrinsics, com.irurueta.geometry.PinholeCameraIntrinsicParameters rightIntrinsics)
      Constructor.
      Parameters:
      homography - 2D transformation relating two views (left view to right view).
      leftIntrinsics - intrinsic parameters to be used on left view.
      rightIntrinsics - intrinsic parameters to be used on right view.

    • HomographyDecomposer

      public HomographyDecomposer(com.irurueta.geometry.Transformation2D homography, com.irurueta.geometry.PinholeCameraIntrinsicParameters leftIntrinsics, com.irurueta.geometry.PinholeCameraIntrinsicParameters rightIntrinsics, HomographyDecomposerListener listener)
      Constructor.
      Parameters:
      homography - 2D transformation relating two views (left view to right view).
      leftIntrinsics - intrinsic parameters to be used on left view.
      rightIntrinsics - intrinsic parameters to be used on right view.
      listener - listener to attend events generated by this instance.

  • Method Details

    • getHomography

      public com.irurueta.geometry.Transformation2D getHomography()
      Gets 2D transformation relating two views (left view to right view).
      Returns:
      2D transformation relating two views.

    • setHomography

      public void setHomography(com.irurueta.geometry.Transformation2D homography) throws com.irurueta.geometry.estimators.LockedException
      Sets 2D transformation relating two views (left view to right view).
      Parameters:
      homography - 2D transformation relating two views.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.

    • getLeftIntrinsics

      public com.irurueta.geometry.PinholeCameraIntrinsicParameters getLeftIntrinsics()
      Gets intrinsic parameters to be used on left view.
      Returns:
      intrinsic parameters to be used on left view.

    • setLeftIntrinsics

      public void setLeftIntrinsics(com.irurueta.geometry.PinholeCameraIntrinsicParameters leftIntrinsics) throws com.irurueta.geometry.estimators.LockedException
      Sets intrinsic parameters to be used on left view.
      Parameters:
      leftIntrinsics - intrinsic parameters to be used on left view.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.

    • getRightIntrinsics

      public com.irurueta.geometry.PinholeCameraIntrinsicParameters getRightIntrinsics()
      Gets intrinsic parameters to be used on right view.
      Returns:
      intrinsic parameters to be used on right view.

    • setRightIntrinsics

      public void setRightIntrinsics(com.irurueta.geometry.PinholeCameraIntrinsicParameters rightIntrinsics) throws com.irurueta.geometry.estimators.LockedException
      Sets intrinsic parameters to be used on right view.
      Parameters:
      rightIntrinsics - intrinsic parameters to be used on right view.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.

    • getListener

      public HomographyDecomposerListener getListener()
      Gets listener to handle events raised by this instance.
      Returns:
      listener to handle events raised by this instance.

    • setListener

      public void setListener(HomographyDecomposerListener listener)
      Sets listener to handle events raised by this instance.
      Parameters:
      listener - listener to handle events raised by this instance.

    • isLocked

      public boolean isLocked()
      Indicates whether estimator is locked while computing decomposition.
      Returns:
      true if decomposer is locked, false otherwise.

    • isReady

      public boolean isReady()
      Indicates whether decomposer is ready to start the decomposition when all required data has been provided.
      Returns:
      true if decomposer is ready, false otherwise.

    • decompose

      public List<HomographyDecomposition> decompose() throws com.irurueta.geometry.estimators.LockedException, com.irurueta.geometry.estimators.NotReadyException, HomographyDecomposerException
      Decomposes homography into possible solutions containing possible 3D rotation, 3D translation and normal and distance of the plane relating two views via provided homography.
      Returns:
      possible solutions.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if decomposer is locked.
      com.irurueta.geometry.estimators.NotReadyException - if decomposer is not ready.
      HomographyDecomposerException - if decomposition fails for some other reason (i.e. numerical instabilities).

    • decompose

      public void decompose(List<HomographyDecomposition> result) throws com.irurueta.geometry.estimators.LockedException, com.irurueta.geometry.estimators.NotReadyException, HomographyDecomposerException
      Decomposes homography into possible solutions containing possible 3D rotation, 3D translation and normal and distance of the plane relating two views via provided homography.
      Parameters:
      result - instance where possible solutions will be stored.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if decomposer is locked.
      com.irurueta.geometry.estimators.NotReadyException - if decomposer is not ready.
      HomographyDecomposerException - if decomposition fails for some other reason (i.e. numerical instabilities).

    • decomposeAllFromSingularValues

      private int decomposeAllFromSingularValues(double[] singularValues, List<double[]> n, List<com.irurueta.algebra.Matrix> r, List<double[]> t, List<Double> d) throws HomographyDecomposerException
      Decompose solutions from singular values.
      Parameters:
      singularValues - input singular values.
      n - list containing possible plane normals.
      r - list containing possible camera rotations.
      t - list containing possible camera translations.
      d - list of distances to plane.
      Returns:
      number of solutions.
      Throws:
      HomographyDecomposerException - if decomposition fails (i.e. numerical instabilities, etc).

    • areThreeDifferentSingularValues

      private static boolean areThreeDifferentSingularValues(double[] singularValues)
      Determines whether there are three different singular values or not.
      Parameters:
      singularValues - singular values to be checked.
      Returns:
      true if there are three different singular values, false otherwise.

    • areTwoEqualSingularValues

      private static boolean areTwoEqualSingularValues(double[] singularValues)
      Determines whether there are two equal singular values or not.
      Parameters:
      singularValues - singular values to be checked.
      Returns:
      true if there are two equal singular values, false otherwise.

    • decomposeFromSingularValues

      private double decomposeFromSingularValues(double[] singularValues, double[] n, com.irurueta.algebra.Matrix r, double[] t, boolean positive1, boolean positive3) throws HomographyDecomposerException
      Decomposes one possible solution using provided singular values and signs
      Parameters:
      singularValues - singular values to use for
      n - array where plane normal will be store.
      r - matrix where rotation will be stored.
      t - array where translation will be stored.
      positive1 - sign of 1st coordinate of plane normal.
      positive3 - sign of 2nd coordinate of plane normal.
      Returns:
      plane distance.
      Throws:
      HomographyDecomposerException - if decomposition is undetermined when all three singular values are equal.

    • decomposeFromTwoDifferentSingularValuesNegative

      private double decomposeFromTwoDifferentSingularValuesNegative(double d1, double d2, double d3, double[] n, com.irurueta.algebra.Matrix r, double[] t, boolean positive3)
      Generates one homography decomposition using provided singular values and assuming that there are two equal singular values and that d2 is negative.
      Parameters:
      d1 - 1st singular value.
      d2 - 2nd singular value.
      d3 - 3rd singular value.
      n - plane normal.
      r - rotation.
      t - translation.
      positive3 - true to assume positive x3, false otherwise.
      Returns:
      distance to plane.

    • decomposeFromTwoDifferentSingularValuesPositive

      private double decomposeFromTwoDifferentSingularValuesPositive(double d1, double d2, double d3, double[] n, com.irurueta.algebra.Matrix r, double[] t, boolean positive3)
      Generates one homography decomposition using provided singular values and assuming that there are two equal singular values and that d2 is positive.
      Parameters:
      d1 - 1st singular value.
      d2 - 2nd singular value.
      d3 - 3rd singular value.
      n - plane normal.
      r - rotation.
      t - translation.
      positive3 - true to assume positive x3, false otherwise.
      Returns:
      distance to plane.

    • decomposeFromThreeDifferentSingularValuesNegative

      private double decomposeFromThreeDifferentSingularValuesNegative(double d1, double d2, double d3, double[] n, com.irurueta.algebra.Matrix r, double[] t, boolean positive1, boolean positive3)
      Generates one homography decomposition using provided singular values and assuming that there are three different singular values and that d2 is negative.
      Parameters:
      d1 - 1st singular value.
      d2 - 2nd singular value.
      d3 - 3rd singular value.
      n - plane normal.
      r - rotation.
      t - translation.
      positive1 - true to assume positive x1, false otherwise.
      positive3 - true to assume positive x3, false otherwise.
      Returns:
      distance to plane.

    • decomposeFromThreeDifferentSingularValuesPositive

      private double decomposeFromThreeDifferentSingularValuesPositive(double d1, double d2, double d3, double[] n, com.irurueta.algebra.Matrix r, double[] t, boolean positive1, boolean positive3)
      Generates one homography decomposition using provided singular values and assuming that there are three different singular values and that d2 is positive.
      Parameters:
      d1 - 1st singular value.
      d2 - 2nd singular value.
      d3 - 3rd singular value.
      n - plane normal.
      r - rotation.
      t - translation.
      positive1 - true to assume positive x1, false otherwise.
      positive3 - true to assume positive x3, false otherwise.
      Returns:
      distance to plane.

    • computeNormalizedCoordinatesHomographyMatrix

      private com.irurueta.algebra.Matrix computeNormalizedCoordinatesHomographyMatrix() throws com.irurueta.algebra.AlgebraException
      Computes homography matrix in terms of normalized point coordinates by taking into account intrinsic camera parameters on left and right views.
      Returns:
      normalized homography matrix
      Throws:
      com.irurueta.algebra.AlgebraException - if there are numerical instabilities.