Package com.irurueta.ar.epipolar

Class FundamentalMatrix

java.lang.Object
com.irurueta.ar.epipolar.FundamentalMatrix
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
EssentialMatrix
public class FundamentalMatrix extends Object implements Serializable
The fundamental matrix describes the epipolar geometry for a pair of cameras. Epipoles are the projections of the opposite camera against the other. By means of point correspondences it is possible to estimate the fundamental matrix, which can later be used to estimate the associated pair of cameras.
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    FUNDAMENTAL_MATRIX_COLS
    Number of columns of fundamental matrix.
    static final int
    FUNDAMENTAL_MATRIX_RANK
    Rank of fundamental matrix.
    static final int
    FUNDAMENTAL_MATRIX_ROWS
    Number of rows of fundamental matrix.
    protected com.irurueta.algebra.Matrix
    internalMatrix
    Contains the internal representation of the fundamental matrix, which is a 3x3 matrix having rank 2 defined up to scale.
    protected com.irurueta.geometry.Point2D
    leftEpipole
    Epipole for left view.
    protected boolean
    normalized
    Indicates whether fundamental matrix has been normalized.
    protected com.irurueta.geometry.Point2D
    rightEpipole
    Epipole for right view.

  • Constructor Summary

    Constructors
    Constructor
    Description
    FundamentalMatrix()
    Constructor.
    FundamentalMatrix(com.irurueta.algebra.Matrix internalMatrix)
    Constructor.
    FundamentalMatrix(com.irurueta.geometry.PinholeCamera leftCamera, com.irurueta.geometry.PinholeCamera rightCamera)
    Constructor from a pair of cameras.
    FundamentalMatrix(com.irurueta.geometry.Transformation2D homography, com.irurueta.geometry.Point2D rightEpipole)
    Constructor from an homography and right epipole.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    areEpipolesAvailable()
    Indicates whether epipoles have been computed and are available for retrieval.
    void
    computeEpipoles()
    Computes the left and right epipoles of this instance.
    void
    generateCamerasInArbitraryProjectiveSpace(com.irurueta.geometry.PinholeCamera leftCamera, com.irurueta.geometry.PinholeCamera rightCamera)
    Generates a pair of cameras in any arbitrary projective space which produce this fundamental matrix.
    void
    generateCamerasInArbitraryProjectiveSpace(com.irurueta.geometry.PinholeCamera leftCamera, com.irurueta.geometry.PinholeCamera rightCamera, double referencePlaneDirectorVectorX, double referencePlaneDirectorVectorY, double referencePlaneDirectorVectorZ, double scaleFactor)
    Generates a pair of cameras in any arbitrary projective space which produce this fundamental matrix.
    com.irurueta.algebra.Matrix
    getInternalMatrix()
    Returns a copy of the internal matrix assigned to this instance.
    com.irurueta.geometry.Line2D
    getLeftEpipolarLine(com.irurueta.geometry.Point2D rightPoint)
    Returns epipolar line on left view corresponding to point on right view.
    com.irurueta.geometry.Point2D
    getLeftEpipole()
    Returns left epipole, which corresponds to the center of right camera projected on left view.
    com.irurueta.geometry.Line2D
    getRightEpipolarLine(com.irurueta.geometry.Point2D leftPoint)
    Returns epipolar line on right view corresponding to point on left view.
    com.irurueta.geometry.Point2D
    getRightEpipole()
    Returns right epipole, which corresponds to the center of left camera projected on right view.
    private void
    internalSetFromHomography(com.irurueta.geometry.Transformation2D homography, com.irurueta.geometry.Point2D rightEpipole)
    Internal method to sets fundamental matrix from provided 2D homography and right epipole.
    private void
    internalSetFromPairOfCameras(com.irurueta.geometry.PinholeCamera leftCamera, com.irurueta.geometry.PinholeCamera rightCamera)
    Internal method to set fundamental matrix from provided a pair of cameras.
    private void
    internalSetInternalMatrix(com.irurueta.algebra.Matrix internalMatrix)
    Method used internally to set the internal matrix associated to this instance.
    boolean
    isInternalMatrixAvailable()
    Indicates whether this instance has its internal matrix set.
    boolean
    isNormalized()
    Indicates whether this instance is currently normalized or not.
    static boolean
    isValidInternalMatrix(com.irurueta.algebra.Matrix internalMatrix)
    Returns a boolean indicating whether provided matrix is a valid fundamental matrix (i.e. has size 3x3 and rank 2).
    void
    leftEpipolarLine(com.irurueta.geometry.Point2D rightPoint, com.irurueta.geometry.Line2D result)
    Computes epipolar line on left view corresponding to point on right view.
    void
    normalize()
    Normalizes the internal representation of this instance.
    void
    rightEpipolarLine(com.irurueta.geometry.Point2D leftPoint, com.irurueta.geometry.Line2D result)
    Computes epipolar line on right view corresponding to point on left view.
    void
    setFromHomography(com.irurueta.geometry.Transformation2D homography, com.irurueta.geometry.Point2D rightEpipole)
    Sets fundamental matrix from provided 2D homography and right epipole.
    void
    setFromPairOfCameras(com.irurueta.geometry.PinholeCamera leftCamera, com.irurueta.geometry.PinholeCamera rightCamera)
    Sets fundamental matrix from provided pair of cameras.
    void
    setInternalMatrix(com.irurueta.algebra.Matrix internalMatrix)
    Sets internal matrix associated to this instance.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • FUNDAMENTAL_MATRIX_ROWS

      public static final int FUNDAMENTAL_MATRIX_ROWS
      Number of rows of fundamental matrix.
      See Also:

    • FUNDAMENTAL_MATRIX_COLS

      public static final int FUNDAMENTAL_MATRIX_COLS
      Number of columns of fundamental matrix.
      See Also:

    • FUNDAMENTAL_MATRIX_RANK

      public static final int FUNDAMENTAL_MATRIX_RANK
      Rank of fundamental matrix.
      See Also:

    • internalMatrix

      protected com.irurueta.algebra.Matrix internalMatrix
      Contains the internal representation of the fundamental matrix, which is a 3x3 matrix having rank 2 defined up to scale.

    • normalized

      protected boolean normalized
      Indicates whether fundamental matrix has been normalized. Normalization can be used to increase the accuracy of estimations, since fundamental matrix is defined up to scale.

    • leftEpipole

      protected com.irurueta.geometry.Point2D leftEpipole
      Epipole for left view. Corresponds to the projection of the center of the right camera on the left view.

    • rightEpipole

      protected com.irurueta.geometry.Point2D rightEpipole
      Epipole for right view. Corresponds to the projection of the center of the left camera on the right view.

  • Constructor Details

    • FundamentalMatrix

      public FundamentalMatrix()
      Constructor.

    • FundamentalMatrix

      public FundamentalMatrix(com.irurueta.algebra.Matrix internalMatrix) throws InvalidFundamentalMatrixException
      Constructor.
      Parameters:
      internalMatrix - matrix to be set internally.
      Throws:
      InvalidFundamentalMatrixException - if provided matrix is not 3x3 or does not have rank 2.

    • FundamentalMatrix

      public FundamentalMatrix(com.irurueta.geometry.PinholeCamera leftCamera, com.irurueta.geometry.PinholeCamera rightCamera) throws InvalidPairOfCamerasException
      Constructor from a pair of cameras.
      Parameters:
      leftCamera - camera corresponding to left view.
      rightCamera - camera corresponding to right view.
      Throws:
      InvalidPairOfCamerasException - if provided cameras do not span a valid epipolar geometry (i.e. they are planed in a degenerate configuration).

    • FundamentalMatrix

      public FundamentalMatrix(com.irurueta.geometry.Transformation2D homography, com.irurueta.geometry.Point2D rightEpipole) throws InvalidFundamentalMatrixException
      Constructor from an homography and right epipole.
      Parameters:
      homography - 2D homography.
      rightEpipole - right epipole.
      Throws:
      InvalidFundamentalMatrixException - if resulting fundamental matrix is invalid, typically because of numerical instabilities.

  • Method Details

    • getInternalMatrix

      public com.irurueta.algebra.Matrix getInternalMatrix() throws com.irurueta.geometry.NotAvailableException
      Returns a copy of the internal matrix assigned to this instance.
      Returns:
      copy of the internal matrix.
      Throws:
      com.irurueta.geometry.NotAvailableException - if internal matrix has not yet been provided.

    • setInternalMatrix

      public void setInternalMatrix(com.irurueta.algebra.Matrix internalMatrix) throws InvalidFundamentalMatrixException
      Sets internal matrix associated to this instance. This method makes a copy of provided matrix.
      Parameters:
      internalMatrix - matrix to be assigned to this instance.
      Throws:
      InvalidFundamentalMatrixException - if provided matrix is not 3x3 or does not have rank 2.

    • internalSetInternalMatrix

      private void internalSetInternalMatrix(com.irurueta.algebra.Matrix internalMatrix) throws InvalidFundamentalMatrixException
      Method used internally to set the internal matrix associated to this instance. This method makes a copy of provided matrix.
      Parameters:
      internalMatrix - matrix to be assigned to this instance.
      Throws:
      InvalidFundamentalMatrixException - if provided matrix is not 3x3 or does not have rank 2.

    • isValidInternalMatrix

      public static boolean isValidInternalMatrix(com.irurueta.algebra.Matrix internalMatrix)
      Returns a boolean indicating whether provided matrix is a valid fundamental matrix (i.e. has size 3x3 and rank 2).
      Parameters:
      internalMatrix - matrix to be checked.
      Returns:
      true if provided matrix is a valid fundamental matrix, false otherwise.

    • setFromPairOfCameras

      public void setFromPairOfCameras(com.irurueta.geometry.PinholeCamera leftCamera, com.irurueta.geometry.PinholeCamera rightCamera) throws InvalidPairOfCamerasException
      Sets fundamental matrix from provided pair of cameras.
      Parameters:
      leftCamera - camera corresponding to left view.
      rightCamera - camera corresponding to right view.
      Throws:
      InvalidPairOfCamerasException - if provided cameras do not span a valid epipolar geometry (i.e. they are planed in a degenerate configuration).

    • internalSetFromPairOfCameras

      private void internalSetFromPairOfCameras(com.irurueta.geometry.PinholeCamera leftCamera, com.irurueta.geometry.PinholeCamera rightCamera) throws InvalidPairOfCamerasException
      Internal method to set fundamental matrix from provided a pair of cameras.
      Parameters:
      leftCamera - camera corresponding to left view.
      rightCamera - camera corresponding to right view.
      Throws:
      InvalidPairOfCamerasException - if provided cameras do not span a valid epipolar geometry (i.e. they are planed in a degenerate configuration).

    • setFromHomography

      public void setFromHomography(com.irurueta.geometry.Transformation2D homography, com.irurueta.geometry.Point2D rightEpipole) throws InvalidFundamentalMatrixException
      Sets fundamental matrix from provided 2D homography and right epipole.
      Parameters:
      homography - 2D homography.
      rightEpipole - right epipole.
      Throws:
      InvalidFundamentalMatrixException - if resulting fundamental matrix is invalid, typically because of numerical instabilities.

    • internalSetFromHomography

      private void internalSetFromHomography(com.irurueta.geometry.Transformation2D homography, com.irurueta.geometry.Point2D rightEpipole) throws InvalidFundamentalMatrixException
      Internal method to sets fundamental matrix from provided 2D homography and right epipole.
      Parameters:
      homography - 2D homography.
      rightEpipole - right epipole.
      Throws:
      InvalidFundamentalMatrixException - if resulting fundamental matrix is invalid, typically because of numerical instabilities.

    • isInternalMatrixAvailable

      public boolean isInternalMatrixAvailable()
      Indicates whether this instance has its internal matrix set.
      Returns:
      true if internal matrix has been set, false otherwise.

    • getLeftEpipolarLine

      public com.irurueta.geometry.Line2D getLeftEpipolarLine(com.irurueta.geometry.Point2D rightPoint) throws com.irurueta.geometry.estimators.NotReadyException
      Returns epipolar line on left view corresponding to point on right view.
      Parameters:
      rightPoint - a point on the right view.
      Returns:
      epipolar line on left view.
      Throws:
      com.irurueta.geometry.estimators.NotReadyException - if internal matrix has not yet been set.

    • leftEpipolarLine

      public void leftEpipolarLine(com.irurueta.geometry.Point2D rightPoint, com.irurueta.geometry.Line2D result) throws com.irurueta.geometry.estimators.NotReadyException
      Computes epipolar line on left view corresponding to point on right view.
      Parameters:
      rightPoint - a point on the right view.
      result - line instance where result will be stored.
      Throws:
      com.irurueta.geometry.estimators.NotReadyException - if internal matrix has not yet been set.

    • getRightEpipolarLine

      public com.irurueta.geometry.Line2D getRightEpipolarLine(com.irurueta.geometry.Point2D leftPoint) throws com.irurueta.geometry.estimators.NotReadyException
      Returns epipolar line on right view corresponding to point on left view.
      Parameters:
      leftPoint - a point on the left view.
      Returns:
      epipolar line on right view.
      Throws:
      com.irurueta.geometry.estimators.NotReadyException - if internal matrix has not yet been set.

    • rightEpipolarLine

      public void rightEpipolarLine(com.irurueta.geometry.Point2D leftPoint, com.irurueta.geometry.Line2D result) throws com.irurueta.geometry.estimators.NotReadyException
      Computes epipolar line on right view corresponding to point on left view.
      Parameters:
      leftPoint - a point on the left view.
      result - line instance where result will be stored.
      Throws:
      com.irurueta.geometry.estimators.NotReadyException - if internal matrix has not yet been set.

    • getLeftEpipole

      public com.irurueta.geometry.Point2D getLeftEpipole() throws com.irurueta.geometry.NotAvailableException
      Returns left epipole, which corresponds to the center of right camera projected on left view.
      Returns:
      left epipole.
      Throws:
      com.irurueta.geometry.NotAvailableException - if epipoles haven't been computed.

    • getRightEpipole

      public com.irurueta.geometry.Point2D getRightEpipole() throws com.irurueta.geometry.NotAvailableException
      Returns right epipole, which corresponds to the center of left camera projected on right view.
      Returns:
      right epipole.
      Throws:
      com.irurueta.geometry.NotAvailableException - if epipoles haven't been computed.

    • normalize

      public void normalize() throws com.irurueta.geometry.estimators.NotReadyException
      Normalizes the internal representation of this instance. Normalization is done to increase accuracy of computations with this instance.
      Throws:
      com.irurueta.geometry.estimators.NotReadyException - if internal matrix has not already been set.

    • isNormalized

      public boolean isNormalized()
      Indicates whether this instance is currently normalized or not.
      Returns:
      true if this instance is normalized, false otherwise.

    • computeEpipoles

      public void computeEpipoles() throws com.irurueta.geometry.estimators.NotReadyException, InvalidFundamentalMatrixException
      Computes the left and right epipoles of this instance.
      Throws:
      com.irurueta.geometry.estimators.NotReadyException - if an internal matrix has not yet been provided.
      InvalidFundamentalMatrixException - if internal matrix is numerically unstable and epipoles couldn't be computed.

    • areEpipolesAvailable

      public boolean areEpipolesAvailable()
      Indicates whether epipoles have been computed and are available for retrieval.
      Returns:
      true if epipoles are available, false otherwise.

    • generateCamerasInArbitraryProjectiveSpace

      public void generateCamerasInArbitraryProjectiveSpace(com.irurueta.geometry.PinholeCamera leftCamera, com.irurueta.geometry.PinholeCamera rightCamera, double referencePlaneDirectorVectorX, double referencePlaneDirectorVectorY, double referencePlaneDirectorVectorZ, double scaleFactor) throws InvalidFundamentalMatrixException, com.irurueta.geometry.estimators.NotReadyException
      Generates a pair of cameras in any arbitrary projective space which produce this fundamental matrix. This method can be used to obtain a pair of cameras related by this fundamental matrix in order to initialize geometry and get an initial set of cameras. However, because cameras are in any arbitrary projective space, they need to be transformed into a metric space using a Dual Absolute Quadric estimator.
      Parameters:
      leftCamera - instance where left camera will be stored.
      rightCamera - instance where right camera will be stored.
      referencePlaneDirectorVectorX - x coordinate of reference plane director vector. This can be any arbitrary value, however typically the reference plane is assumed to be the plane at infinity, hence the value typically is zero.
      referencePlaneDirectorVectorY - y coordinate of reference plane director vector. This can be any arbitrary value, however typically the reference plane is assumed to be the plane at infinity, hence the value typically is zero.
      referencePlaneDirectorVectorZ - z coordinate of reference plane director vector. This can be any arbitrary value, however typically the reference plane is assumed to be the plane at infinity, hence the value typically is zero.
      scaleFactor - scale factor defining the length of the baseline in a metric stratum. This can be any value, since cameras are obtained in an arbitrary projective stratum. However, even if the stratum was metric, cameras can only be defined up to scale. A typical value is a scale factor of one.
      Throws:
      InvalidFundamentalMatrixException - if internal matrix is numerically unstable and epipoles couldn't be computed.
      com.irurueta.geometry.estimators.NotReadyException - if an internal matrix has not yet been provided.

    • generateCamerasInArbitraryProjectiveSpace

      public void generateCamerasInArbitraryProjectiveSpace(com.irurueta.geometry.PinholeCamera leftCamera, com.irurueta.geometry.PinholeCamera rightCamera) throws InvalidFundamentalMatrixException, com.irurueta.geometry.estimators.NotReadyException
      Generates a pair of cameras in any arbitrary projective space which produce this fundamental matrix. This method can be used to obtain a pair of cameras related by this fundamental matrix in order to initialize geometry and get an initial set of cameras. However, because cameras are in any arbitrary projective space, they need to be transformed into a metric space using a Dual Absolute Quadric estimator. This method assumes that the reference plane is the plane at infinity and that scale factor is one.
      Parameters:
      leftCamera - instance where left camera will be stored.
      rightCamera - instance where right camera will be stored.
      Throws:
      InvalidFundamentalMatrixException - if internal matrix is numerically unstable and epipoles couldn't be computed.
      com.irurueta.geometry.estimators.NotReadyException - if an internal matrix has not yet been provided.