spymicmac.matching

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

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

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).

• angle (float) – the angle to rotate the template by (default: None).

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, thresh_tol=0.9, npeaks=5, min_dist=1, angle=None, use_frame=True)

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

• thresh_tol (float) – the minimum relative peak intensity to use for detecting matches (default: 0.9)

• npeaks (int) – maximum number of potential matches to accept for each fiducial marker template (default: 5)

• min_dist (int) – the minimum distance allowed between potential peaks (default: not set)

• angle (int) – the angle by which to rotate the points in MeasuresCam (default: do not rotate)

• use_frame (bool) – use the rough image frame to try to find fiducial markers (default: True)

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 (Raster) – 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)

• npix (int) – the block size (in pixels) to divide the image into, if doing dense matching (default: 100).

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

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.inscribed_cross(size, cross_size, width=3, angle=45)

Create a cross-shaped template inscribed inside of a circle for matching fiducial marks.

Parameters:

• size (int) – the half-size of the template. Final size will be (2 * size + 1, 2 * size + 1).

• cross_size (int) – the size of the cross template to create

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

• angle (float) – the angle to rotate the template by (default: None).

Returns:

template (array-like) – the output template

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(fn_img, size, model, data_strip, fn_cam=None, dot_size=4, **kwargs)

Match the fiducial locations for a Fairchild-style camera (4 fiducial markers markers on the side).

Parameters:

• fn_img (str) – the filename of the image to match

• size (int) – the size of the marker to match

• model (str) – the type of fiducial marker: T11 style with either checkerboard-style markers (T11S) or dot style markers (T11D), side + corner dot style markers (T12), or K17 style (“wing” style markers). Must be one of [K17, T11S, T11D, T12].

• data_strip (str) – the location of the data strip in the image (left, right, top, bot). For T11 style cameras, the data strip should be along the left-hand side; for K17 style cameras, the “data strip” (focal length indicator) should be on the right-hand side. Be sure to check your images, as the scanned images may be rotated relative to this expectation.

• fn_cam (str) – the filename of the MeasuresCamera.xml file corresponding to the image

• dot_size (int) – the size of the dot to use for T11D style fiducial markers (default: 4 -> 9x9)

• kwargs – additional keyword arguments to pass to matching.find_fiducials()

Returns:

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.match_wild_rc(fn_img, size, model, data_strip='left', fn_cam=None, circle_size=None, ring_width=7, **kwargs)

Match the fiducial locations for a Wild RC-style camera (4 cross/bulls-eye markers in the corner, possibly 4 bulls-eye markers along the sides).

Parameters:

• fn_img (str) – the filename of the image to match

• size (int) – the size of the marker to match

• model (str) – whether the camera is an RC5/RC8 (4 corner markers) or RC10-style (corner + midside markers)

• data_strip (str) – the location of the data strip in the image (left, right, top, bot). Most calibration reports assume the data strip is along the left-hand side, but scanned images may be rotated relative to this.

• fn_cam (str) – the filename of the MeasuresCamera.xml file corresponding to the image (default: Ori-InterneScan/MeasuresCamera.xml)

• circle_size (int) – the size of the circle in which to inscribe the cross-shaped marker (default: no circle)

• ring_width (int) – the width of the ring if the marker(s) are a cross inscribed with a ring. Only used if

• kwargs – additional keyword arguments to pass to matching.find_fiducials()

Returns:

spymicmac.matching.match_zeiss_rmk(fn_img, size, dot_size, data_strip='left', fn_cam=None, corner_size=None, **kwargs)

Match the fiducial locations for a Zeiss RMK-style camera (4 dot-shaped markers on the side, possibly 4 cross-shaped markers in the corners).

Parameters:

• fn_img (str) – the filename of the image to match

• size (int) – the size of the marker to match

• dot_size (int) – the size of the dot marker to match

• data_strip (str) – the location of the data strip in the image (left, right, top, bot). Most calibration reports assume the data strip is along the left-hand side, but scanned images may be rotated relative to this.

• fn_cam (str) – the filename of the MeasuresCamera.xml file corresponding to the image

• corner_size (int) – the size of the corner markers (default: do not find corner markers)

• kwargs – additional keyword arguments to pass to matching.find_fiducials()

Returns:

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.padded_dot(size, disk_size)

Pad a disk-shaped marker with zeros. Works for, e.g., Zeiss RMK mid-side fiducials.

Parameters:

• size (int) – the size of the padded template

• disk_size (int) – the half-size of the disk to use

Returns:

padded (array-like) – the disk with a padding of zeros around it

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, circle_size=None, circle_width=None, angle=None)

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]

• circle_size (int) – the size of the circle to inscribe the cross into (default: same as cross size)

• circle_width (int) – the width of the ring to inscribe the cross into (default: same as cross width)

• angle (float) – the angle by which to rotate the cross (default: do not rotate)

Returns:

template (array-like) the wagon wheel template