spymicmac.matching

spymicmac.matching is a collection of tools for matching templates in images

spymicmac.matching.cross_template(shape, width=3)

Create a cross-shaped template for matching reseau or fiducial marks.

Parameters:

• shape (int) – the output shape of the template

• width (int) – the width of the cross at the center of the template (default: 3 pixels).

Returns:

cross (array-like) – the cross template

spymicmac.matching.do_match(dest_img, ref_img, mask, pt, srcwin, dstwin)

Find a match between two images using normalized cross-correlation template matching.

Parameters:

• dest_img (array-like) – the image to search for the matching point in.

• ref_img (array-like) – the reference image to use for matching.

• mask (array-like) – a mask indicating areas that should be used for matching.

• pt (array-like) – the index (i, j) to search for a match for.

• srcwin (int) – the half-size of the template window.

• dstwin (int) – the half-size of the search window.

Returns:

• match_pt (tuple) – the matching point (j, i) found in dest_img

• z_corr (float) – number of standard deviations (z-score) above other potential matches

• peak_corr (float) – the correlation value of the matched point

spymicmac.matching.find_crosses(img, cross)

Find all cross markers in an image.

Parameters:

• img (array-like) – the image

• cross (array-like) – the cross template to use

Returns:

grid_df (pandas.DataFrame) – a dataframe of marker locations and offsets

spymicmac.matching.find_fiducials(fn_img, templates, fn_cam=None)

Match the location of fiducial markers for a scanned aerial photo.

Parameters:

• fn_img (str) – the filename of the image to find fiducial markers in.

• templates (dict) – a dict of (name, template) pairs corresponding to each fiducial marker.

• fn_cam (str) – the filename of the MeasuresCamera.xml file for the image. defaults to Ori-InterneScan/MeasuresCamera.xml

spymicmac.matching.find_grid_matches(tfm_img, refgeo, mask, initM=None, spacing=200, srcwin=60, dstwin=600)

Find matches between two images on a grid using normalized cross-correlation template matching.

Parameters:

• tfm_img (array-like) – the image to use for matching.

• refgeo (GeoImg) – the reference image to use for matching.

• mask (array-like) – a mask indicating areas that should be used for matching.

• initM – the model used for transforming the initial, non-georeferenced image.

• spacing (int) – the grid spacing, in pixels (default: 200 pixels)

• srcwin (int) – the half-size of the template window.

• dstwin (int) – the half-size of the search window.

Returns:

gcps (pandas.DataFrame) – a DataFrame with GCP locations, match strength, and other information.

spymicmac.matching.find_kh4_notches(img, size=101)

Find all 4 notches along the top of a KH-4 style image.

Parameters:

• img (array-like) – the image.

• size (int) – the size of the notch template to use.

Returns:

coords (array-like) – a 4x2 array of notch locations

spymicmac.matching.find_match(img, template, how='min', eq=True)

Given an image and a template, find a match using openCV’s normed cross-correlation.

Parameters:

• img (array-like) – the image to find a match in

• template (array-like) – the template to use for matching

• how (str) – determines whether the match is the minimum or maximum correlation (default: min)

• eq (bool) – use a rank equalization filter before matching the templates (default: True)

Returns:

• res (array-like) – the correlation image

• match_i (float) – the row location of the match

• match_j (float) – the column location of the match

spymicmac.matching.find_rail_marks(img)

Find all rail marks along the bottom edge of a KH-4 style image.

Parameters:

img (array-like) – the image to find the rail marks in.

Returns:

coords (array-like) – an Nx2 array of the location of the detected markers.

spymicmac.matching.find_reseau_grid(fn_img, csize=361, return_val=False)

Find the locations of the Reseau marks in a scanned KH-9 image. Locations are saved to Ori-InterneScan/MeasuresIm-:fn_img:.xml.

Parameters:

• fn_img (str) – the image filename.

• csize (int) – the size of the cross template (default: 361 -> 361x361)

• return_val (bool) – return a pandas DataFrame of the Reseau mark locations (default: False).

Returns:

gcps_df (pandas.DataFrame) – a DataFrame of the Reseau mark locations (if return_val=True).

spymicmac.matching.get_dense_keypoints(img, mask, npix=100, nblocks=None, return_des=False)

Find ORB keypoints by dividing an image into smaller parts.

Parameters:

• img (array-like) – the image to use.

• mask (array-like) – a mask to use for keypoint generation.

• npix (int) – the block size (in pixels) to divide the image into.

• nblocks (int) – the number of blocks to divide the image into. If set, overrides value given by npix.

• return_des (bool) – return the keypoint descriptors, as well

Returns:

• keypoints (list) – a list of keypoint locations

• descriptors (list) – if requested, a list of keypoint descriptors.

spymicmac.matching.get_matches(img1, img2, mask1=None, mask2=None, dense=False, npix=100, nblocks=None)

Return keypoint matches found using openCV’s ORB implementation.

Parameters:

• img1 (array-like) – the first image to match

• img2 (array-like) – the second image to match

• mask1 (array-like) – a mask to use for the first image. (default: no mask)

• mask2 (array-like) – a mask to use for the second image. (default: no mask)

• dense (bool) – compute matches over sub-blocks (True) or the entire image (False). (default: False)

Returns:

• keypoints (tuple) – the keypoint locations for the first and second image.

• descriptors (tuple) – the descriptors for the first and second image.

• matches (list) – a list of matching keypoints between the first and second image

spymicmac.matching.make_template(img, pt, half_size)

Return a sub-section of an image to use for matching.

Parameters:

• img (array-like) – the image from which to create the template

• pt (tuple) – the (row, column) center of the template

• half_size (int) – the half-size of the template; template size will be 2 * half_size + 1

Returns:

• template (array-like) – the template

• row_inds (list) – the number of rows above/below the center of the template

• col_inds (list) – the number of columns left/right of the center of the template

spymicmac.matching.match_fairchild_k17(fn_img, size=101, fn_cam=None)

Match the “fiducial” locations for a Fairchild K17B-style camera (4 “wing” style fiducial markers in the middle of each side of the image).

Parameters:

• fn_img (str) – the filename of the image to find fiducial markers in.

• size (int) – the size of the template to use (default: 101 pixels)

• fn_cam (str) – the filename of the MeasuresCamera.xml file for the image. defaults to Ori-InterneScan/MeasuresCamera.xml

spymicmac.matching.match_halves(left, right, overlap, block_size=None)

Find a transformation to join the left and right halves of an image scan.

Parameters:

• left (array-like) – the left-hand image scan.

• right (array-like) – the right-hand image scan.

• overlap (int) – the estimated overlap between the two images, in pixels.

• block_size (int) – the number of rows each sub-block should cover. Defaults to overlap.

Returns:

model (EuclideanTransform) – the estimated Euclidean transformation between the two image halves.

spymicmac.matching.match_reseau_grid(img, coords, cross)

Find the best match for each KH-9 mapping camera reseau grid point, given a list of potential matches.

Parameters:

• img (array-like) – the image to use

• coords (array-like) – the coordinates of the potential matches

• cross (array-like) – the cross template to use.

Returns:

grid_df (pandas.DataFrame) – a DataFrame of grid locations and match points

spymicmac.matching.notch_template(size)

Create a notch-shaped (“^”) template.

Parameters:

size (int) – the size of the template, in pixels

Returns:

template (array-like) – the notch template

spymicmac.matching.ocm_show_wagon_wheels(img, size, width=3, img_border=None)

Find all “wagon wheel” markers in an image.

Parameters:

• img (array-like) – the image

• size (int) – the size of the marker (in pixels)

• width (int) – the width/thickness of the cross, in pixels (default: 3)

• img_border – the approximate top and bottom rows of the image frame. If not set, calls get_rough_frame() on the image.

Returns:

coords an Nx2 array of the location of the detected markers.

spymicmac.matching.remove_crosses(fn_img, nproc=1)

Remove the Reseau marks from a KH-9 image before re-sampling.

Parameters:

• fn_img (str) – the image filename.

• nproc (int) – the number of subprocesses to use (default: 1).

spymicmac.matching.templates_from_meas(fn_img, half_size=100)

Create fiducial templates from points in a MeasuresIm file.

Parameters:

• fn_img (str) – the filename of the image to use. Points for templates will be taken from Ori-InterneScan-Measuresim{fn-img}.xml.

• half_size (int) – the half-size of the template to create, in pixels (default: 100)

Returns:

templates (dict) – a dict of (name, template) pairs for each fiducial marker.

spymicmac.matching.wagon_wheel(size, width=3, mult=255)

Creates a template in the shape of a “wagon wheel” (a cross inscribed in a ring).

Parameters:

• size (int) – the width (and height) of the template, in pixels

• width (int) – the width/thickness of the cross, in pixels

• mult – a multiplier to use for the template [default: 255]

Returns:

template (array-like) the wagon wheel template