matcher.cpu_ring_matcher — CPU Based Ring Matching¶
The matcher.cpu_ring_matcher module implements a ring
matcher.
New in version 0.1.0.
- autocnet.matcher.cpu_ring_matcher.add_correspondences(in_feats, ref_feats, tar_feats, ref_desc, tar_desc, xextent, yextent, ring, n_x_cells=5, n_y_cells=5, target_points=5, **kwargs)[source]¶
Given a set of input features and x/y extents lay a regular grid over the area defined by the extents and find correspondences within each grid cell that does not have any existing correspondences.
Then number of cells are defined by the n_x/y_cells parameters.
- Parameters
in_feats (ndarray) – (n,m) input features with the first column being x-coordinate in image space and the second column being y-coordinate.
ref_feats (np.ndarray) – where the first 2 columns are the x,y coordinates in pixel space, columns 3 & 4 are the x,y coordinates in m or km in the same reference as the target features
tar_feats (np.ndarray) – where the first 2 columns are the x,y coordinates in pixel space, columns 3 & 4 are the x,y coordinates in m or km in the same reference as the reference features
ref_desc (np.ndarray) – (m, n) where m are the individual SIFT features and n are the descriptor length (usually 128)
tar_desc (np.ndarray) – (m, n) where m are the individual SIFT features and n are the descriptor length (usually 128)
xextent (tuple) – in the form (minx, maxx)
yextent (tuple) – in the form (miny, maxy)
ring (tuple) – in the form (min_ring, max_ring)
n_x_cells (int) – the number of cells to generate in the x direction
n_y_cells (int) – the number of cells to generate in the y direction
target_points (int) – The desired number of points to identify a correspondence
- autocnet.matcher.cpu_ring_matcher.check_pidx_duplicates(pidx)[source]¶
Given a ring match generted set of indices, apply outlier detection to ensure no duplicates exist in either the reference column or the source column. If duplicates do exist, remove the rows; the solution is ambiguous.
- autocnet.matcher.cpu_ring_matcher.directed_ring_match(ref_feats, tar_feats, ref_desc, tar_desc, ring_min, ring_max, target_points=15, tolerance_value=0.02)[source]¶
Given an input set of reference features and target features, attempt to find correspondences within a given ring, where the ring is defined by min and max radii. This is a directed version of the ring_match function, in that this function assumes that the correspondence is within the defined ring.
This implementation is inspired by and uses the ring_match implementation above, developed by Sidiropoulos and Muller.
- Parameters
ref_feats (np.ndarray) – where the first 2 columns are the x,y coordinates in pixel space, columns 3 & 4 are the x,y coordinates in m or km in the same reference as the target features
tar_feats (np.ndarray) – where the first 2 columns are the x,y coordinates in pixel space, columns 3 & 4 are the x,y coordinates in m or km in the same reference as the reference features
ref_desc (np.ndarray) – (m, n) where m are the individual SIFT features and n are the descriptor length (usually 128)
tar_desc (np.ndarray) – (m, n) where m are the individual SIFT features and n are the descriptor length (usually 128)
ring_min (numeric) – The inner distance of the ring
ring_max (numeric) – The outer distance of the ring
- target_pointsint
The number of points that constitute a valid match
- tolerancefloat
The tolerance for outlier detection in point ordering between estimated resolutions
- Returns
xref (ndarray) – (n,4) array of the correspondences selected from the ref_feats input
xtar (ndarray) – (n,4) array of the correspondences selected from the tar_feats input
p_idx (ndarray) – (n,2) array of the indices in the ref_feats and tar_feats input arrays
- autocnet.matcher.cpu_ring_matcher.dynamically_grow_array(array, m, dtype=None)[source]¶
Given an array, dynamically grow the array vertically with an m,n array of zeros
- Parameters
array (ndarray) – The array to be grown
m (int) – The number of new rows to add
dtype (obj) – A numpy data type that is used for the new entries. A dynamically grown array will upcast to the most complex data type.
- Returns
array – The expanded array
- Return type
ndarray
- autocnet.matcher.cpu_ring_matcher.points_in_ring(distance_vector, inner_radius, outer_radius)[source]¶
Returns the indices of all points within a given distance from a distance vector. The vector is assumed to be 1d.
- Parameters
distance_vector (ndarray) – (n,1) array of distances between a point and a set of points
inner_radius (float) – The lower threshold for the ring
outer_radius (float) – The outer threshold for the ring
- Returns
(n,1) array of booleans where all correspondences inside of the array are True
- Return type
ndarray
- autocnet.matcher.cpu_ring_matcher.ransac_permute(ref_points, tar_points, tolerance_val, target_points)[source]¶
Given a set of reference points and target points, compute the geometric distances between pairs of points in the reference set and pairs of points in the target set. Points for which the ratio of the distances is within plus or minus 1 - tolerance_value are considered to be good matches.
If a valid solution is not found, this func returns three empty lists.
- Parameters
ref_points (ndarray) – A (n, 2) array of points where the first column is the x pixel location and the second column is the y pixel location. Additional columns are ignored. These points are from one image.
tar_points (ndarray) – A (n,2) array as above, for a second image.
tolerance_value (float) – On the range [-1, 1], the computed ratio must be within 1 +- tolerance to be considered a match
target_points (int) – The minimum number of points required to return a valid answer
- Returns
ref_points (ndarray) – (n,2) subset of the input ref_points
tar_points (ndarray) – (n,2) subset of the input tar points
f2 (ndarray) – of indices for valid points
References
Sidiropoulos and J.-P. Muller, A systematic solution to multi-instrument co-registration of high-resolution planetary images to an orthorectified baseline, IEEE Transactions on Geoscience and Remote Sensing, 2017
- autocnet.matcher.cpu_ring_matcher.ring_match(ref_feats, tar_feats, ref_desc, tar_desc, ring_radius=4000, max_radius=40000, target_points=15, tolerance_val=0.02, iteration_break_point=200)[source]¶
Apply the University College London ring matching technique that seeks to match target feats to a number of reference features.
- Parameters
ref_feats (np.ndarray) – where the first 2 columns are the x,y coordinates in pixel space, columns 3 & 4 are the x,y coordinates in m or km in the same reference as the target features
tar_feats (np.ndarray) – where the first 2 columns are the x,y coordinates in pixel space, columns 3 & 4 are the x,y coordinates in m or km in the same reference as the reference features
ref_desc (np.ndarray) – (m, n) where m are the individual SIFT features and n are the descriptor length (usually 128)
tar_desc (np.ndarray) – (m, n) where m are the individual SIFT features and n are the descriptor length (usually 128)
ring_radius (numeric) – The width of a ring for matching. In the same units as the x,y coordinates for the features, e.g. if the ref_feats and tar_feats are provided in pixel space and meters, the ring_radius should be expressed in meters
max_radius (numeric) – The maximum radius to be tested. This is the maxixum distance a given correspondence could be from the initial estimate.
target_points (int) – The number of points that constitute a valid match
tolerance (float) – The tolerance for outlier detection in point ordering between estimated resolutions
- Returns
xref (ndarray) – (n,4) array of the correspondences selected from the ref_feats input
xtar (ndarray) – (n,4) array of the correspondences selected from the tar_feats input
p_idx (ndarray) – (n,2) array of the indices in the ref_feats and tar_feats input arrays
References
Sidiropoulos and J.-P. Muller, A systematic solution to multi-instrument co-registration of high-resolution planetary images to an orthorectified baseline, IEEE Transactions on Geoscience and Remote Sensing, 2017
- autocnet.matcher.cpu_ring_matcher.ring_match_one(x, y, ref_feats, tar_feats, ref_desc, tar_desc, ring, search_radius=600, max_search_radius=600, target_points=5)[source]¶
Given an x,y coordinate where a match is desired, find all candidates within some search radius and attempt to generate a match. If no matches are identified expand the search radius by search_radius and search again. Once a match is identified (by calling the directed matcher and finding a geometric consensus with at least target_points), the match closest to the given x,y is returned.
- Parameters
x (int) – x coordinate in image space
y (int) – y coordinate in image space
ref_feats (np.ndarray) – where the first 2 columns are the x,y coordinates in pixel space, columns 3 & 4 are the x,y coordinates in m or km in the same reference as the target features
tar_feats (np.ndarray) – where the first 2 columns are the x,y coordinates in pixel space, columns 3 & 4 are the x,y coordinates in m or km in the same reference as the reference features
ref_desc (np.ndarray) – (m, n) where m are the individual SIFT features and n are the descriptor length (usually 128)
tar_desc (np.ndarray) – (m, n) where m are the individual SIFT features and n are the descriptor length (usually 128)
ring (tuple) – in the form (min_ring, max_ring)
search_radius (numeric) – The radius of the search extent in image pixels
target_points (int) – The desired number of points to identify a correspondence
- autocnet.matcher.cpu_ring_matcher.sift_match(a, b, thresh=1.5)[source]¶
vl_ubcmatch from the vlfeat toolbox for MatLab. This is Lowe’s prescribed implementation for disambiguating descriptors.
- Parameters
a (np.ndarray) – (m,) a singular descriptors where the m-dimension are the descriptor lengths. For SIFT m=128. This is reshaped from a vector to an array.
b (np.ndarray) – (n,m) where the n-dimension are the individual features and the m-dimension are the elements of the descriptor.
thresh (float) – The threshold for disambiguating correspondences. From Lowe. If best * thresh < second_best, a match has been found.
- Returns
best – Index for the best match
- Return type
int
References
Sidiropoulos and J.-P. Muller, A systematic solution to multi-instrument co-registration of high-resolution planetary images to an orthorectified baseline, IEEE Transactions on Geoscience and Remote Sensing, 2017