transformation.fundamental_matrix — Fundamental Matrices¶
The transformation.fundamental_matrix module contains methods for computing the fundamental matrix between two images and assessing error. The fundamental matrix defines the projection from a point in one image to an epipolar line in the other. This module supports multiple methods for F matrix computation.
New in version 0.1.0.
- autocnet.transformation.fundamental_matrix.compute_epipolar_lines(F, x, index=None)[source]¶
Given a fundamental matrix and a set of homogeneous points
- Parameters
F (ndarray) – of shape (3,3) that represents the fundamental matrix
x (ndarray) – of shape (n, 3) of homogeneous coordinates
- Returns
lines – of shape (n,3) of epipolar lines in standard form
- Return type
ndarray
- autocnet.transformation.fundamental_matrix.compute_fundamental_error(F, x, x1)[source]¶
Compute the fundamental error using the idealized error metric.
Ideal error is defined by $x^{intercal}Fx = 0$, where $x$ are all matchpoints in a given image and $x^{intercal}F$ defines the standard form of the epipolar line in the second image.
This method assumes that x and x1 are ordered such that x[0] correspondes to x1[0].
- Parameters
F (ndarray) – (3,3) Fundamental matrix
x (arraylike) – (n,2) or (n,3) array of homogeneous coordinates
x1 (arraylike) – (n,2) or (n,3) array of homogeneous coordinates with the same length as argument x
- Returns
F_error – n,1 vector of reprojection errors
- Return type
ndarray
- autocnet.transformation.fundamental_matrix.compute_fundamental_matrix(kp1, kp2, method='mle', reproj_threshold=2.0, confidence=0.99, mle_reproj_threshold=0.5)[source]¶
Given two arrays of keypoints compute the fundamental matrix. This function accepts two dataframe of keypoints that have
- Parameters
kp1 (arraylike) – (n, 2) of coordinates from the source image
kp2 (ndarray) – (n, 2) of coordinates from the destination image
- method{‘ransac’, ‘lmeds’, ‘normal’, ‘8point’}
The openCV algorithm to use for outlier detection
- reproj_thresholdfloat
The maximum distances in pixels a reprojected points can be from the epipolar line to be considered an inlier
- confidencefloat
[0, 1] that the estimated matrix is correct
- Returns
F (ndarray) – A 3x3 fundamental matrix
mask (pd.Series) – A boolean mask identifying those points that are valid.
Notes
While the method is user definable, if the number of input points is < 7, normal outlier detection is automatically used, if 7 > n > 15, least medians is used, and if 7 > 15, ransac can be used.
- autocnet.transformation.fundamental_matrix.compute_reprojection_error(F, x, x1, index=None)[source]¶
Given a set of matches and a known fundamental matrix, compute distance between match points and the associated epipolar lines.
The distance between a point and the associated epipolar line is computed as: $d =
rac{lvert ax_{0} + by_{0} + c vert}{sqrt{a^{2} + b^{2}}}$.
- Fndarray
(3,3) Fundamental matrix
- xarraylike
(n,2) or (n,3) array of homogeneous coordinates
- x1arraylike
(n,2) or (n,3) array of homogeneous coordinates with the same length as argument x
- F_errorndarray
n,1 vector of reprojection errors
- autocnet.transformation.fundamental_matrix.enforce_singularity_constraint(F)[source]¶
The fundamental matrix should be rank 2. In instances when it is not, the singularity constraint should be enforced. This is forces epipolar lines to be conincident.
- Parameters
F (ndarray) – (3,3) Fundamental Matrix
- Returns
F – (3,3) Singular Fundamental Matrix
- Return type
ndarray
References
- Hartley2003
- autocnet.transformation.fundamental_matrix.epipolar_distance(lines, pts)[source]¶
Given a set of epipolar lines and a set of points, compute the euclidean distance between each point and the corresponding epipolar line
- Parameters
lines (ndarray) – of shape (n,3) of epipolar lines in standard form
pts (ndarray) – of shape (n, 3) of homogeneous coordinates
- autocnet.transformation.fundamental_matrix.update_fundamental_mask(F, x1, x2, threshold=1.0, index=None, method='reprojection')[source]¶
Given a Fundamental matrix and two sets of points, compute the reprojection error between x1 and x2. A mask is returned with all repojection errors greater than the error set to false.
- Parameters
F (ndarray) – (3,3) Fundamental matrix
x1 (arraylike) – (n,2) or (n,3) array of homogeneous coordinates
x2 (arraylike) – (n,2) or (n,3) array of homogeneous coordinates
threshold (float) – The new upper limit for error. If using reprojection this is measured in pixels (the default). If using fundamental, the idealized error is 0. Values +- 0.05 should be good.
index (ndarray) – Optional index for mapping between reprojective error and an associated dataframe (e.g., an indexed matches dataframe).
- Returns
mask
- Return type
dataframe