spymicmac.matching

spymicmac.matching#

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

declassified images#

spymicmac.matching.match_halves(left, right, overlap, block_size=None)[source]#

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

Parameters:

  • left (ndarray[Any, dtype[_ScalarType_co]]) – the left-hand image scan.

  • right (ndarray[Any, dtype[_ScalarType_co]]) – 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 – the estimated Euclidean transformation between the two image halves.

Return type:

EuclideanTransform

KH-9 Hexagon mapping camera#

spymicmac.matching.find_reseau_grid(fn_img, csize=361, return_val=False)[source]#

Find the locations of the Réseau marks in a scanned KH-9 image. Locations are saved to Ori-InterneScan/MeasuresIm-{fn_img}.xml.

Parameters:

  • fn_img (str | Path) – the image filename.

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

  • return_val (bool) – return a pandas DataFrame of the Réseau mark locations

Returns:

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

Return type:

DataFrame | None

spymicmac.matching.remove_crosses(fn_img, nproc=1)[source]#

Remove the Réseau marks from a KH-9 image before re-sampling.

Parameters:

  • fn_img (str | Path) – the image filename

  • nproc (int) – the number of subprocesses to use

Return type:

None

panoramic cameras#

spymicmac.matching.find_rail_marks(img, marker)[source]#

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

Parameters:

  • img (ndarray[Any, dtype[_ScalarType_co]]) – the image to find the rail marks in.

  • marker (ndarray[Any, dtype[_ScalarType_co]]) – the marker template to use for matching

Returns:

coords – Nx2 array of the location (row, col) of the detected markers.

Return type:

ndarray[Any, dtype[_ScalarType_co]]

spymicmac.matching.find_kh4_notches(img, size=101)[source]#

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

Parameters:

  • img (ndarray[Any, dtype[_ScalarType_co]]) – the image.

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

Returns:

coords – a 4x2 array of notch locations

Return type:

ndarray[Any, dtype[_ScalarType_co]]

spymicmac.matching.ocm_show_wagon_wheels(img, size, width=3, img_border=None)[source]#

Find all “wagon wheel” markers in an image.

Parameters:

  • img (ndarray[Any, dtype[_ScalarType_co]]) – the image

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

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

  • img_border (tuple[int, int] | None) – 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.

Return type:

ndarray[Any, dtype[_ScalarType_co]]

fiducial markers#

generic templates#

spymicmac.matching.templates_from_meas(fn_img, half_size=100, threshold=False)[source]#

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

  • threshold (bool) – return binary templates based on otsu thresholding

Returns:

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

Return type:

dict

spymicmac.matching.find_fiducials(fn_img, templates, fn_cam=None, thresh_tol=0.9, npeaks=5, min_dist=1, angle=None, use_frame=True, tsize=None, threshold=True, dual=False)[source]#

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 | Path | None) – the filename of the MeasuresIm file for the template image, if templates are created using templates_from_meas().

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

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

  • min_dist (int) – the minimum distance allowed between potential peaks

  • angle (float | None) – the angle by which to rotate the points in MeasuresCam

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

  • tsize (int | None) – target half-size to use for matching (default: calculated based on image size)

  • threshold (bool) – use a local threshold to help find matches

  • dual (bool) – match using both thresholding and not thresholding to help find matches

Returns:

the mean residual between the matches and the fiducial marker locations

Return type:

float

camera-specific templates#

spymicmac.matching.match_fairchild(fn_img, size, model, data_strip, fn_cam=None, dot_size=4, **kwargs)[source]#

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

Parameters:

  • fn_img (str | Path) – 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 | Path) – the filename of the MeasuresCamera.xml file corresponding to the image

  • dot_size (int) – the half-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:

the mean residual between the matches and the fiducial marker locations

Return type:

float

spymicmac.matching.match_wild_rc(fn_img, size, model, data_strip='left', fn_cam=None, width=3, circle_size=None, ring_width=7, gap=9, vgap=None, dot_size=None, pad=10, **kwargs)[source]#

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 | Path) – 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 | Path) – the filename of the MeasuresCamera.xml file corresponding to the image (default: Ori-InterneScan/MeasuresCamera.xml)

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

  • circle_size (int | None) – 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 for RC10 models.

  • gap (int) – the width, in pixels, of the gap in the middle of the cross

  • vgap (int | None) – the height, in pixels, of the gap in the middle of the cross (default: same as gap)

  • dot_size (int | None) – the half-size, in pixels, of the dot in the middle of the cross (default: no dot)

  • pad (int) – the size of the padding around the outside of the cross to include

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

Returns:

the mean residual betweent he matches and the fiducial marker locations

Return type:

float

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

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:

the mean residual between the matches and the fiducial marker locations

Return type:

float

general matching#

spymicmac.matching.get_dense_keypoints(img, mask, npix=100, nblocks=None, return_des=False, use_skimage=False, detector_kwargs={})[source]#

Find ORB keypoints by dividing an image into smaller parts.

Parameters:

  • img (ndarray[Any, dtype[_ScalarType_co]]) – the image to use.

  • mask (ndarray[Any, dtype[_ScalarType_co]]) – 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

  • use_skimage (bool) – use the scikit-image implementation of ORB rather than OpenCV

  • detector_kwargs (dict) – additional keyword arguments to pass when creating the ORB detector. For details, see the documentation for cv2.ORB_create or skimage.feature.ORB.

Returns:

  • keypoints – a list of keypoint locations

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

Return type:

tuple[list, …]

spymicmac.matching.find_matches(tfm_img, refgeo, mask, points=None, initM=None, strategy='grid', spacing=200, srcwin=60, dstwin=600)[source]#

Find matches between two images using normalized cross-correlation template matching. If point locations are not given, generates a two-dimensional grid of evenly spaced points.

Parameters:

  • tfm_img (ndarray[Any, dtype[_ScalarType_co]]) – the image to use for matching.

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

  • mask (ndarray[Any, dtype[_ScalarType_co]]) – a mask indicating areas that should be used for matching.

  • points (GeoDataFrame | None) – a GeoDataFrame of point locations

  • initM (ProjectiveTransform | None) – the model used for transforming the initial, non-georeferenced image.

  • strategy (str) – strategy for generating points. Must be one of ‘grid’ or ‘random’. Note that if ‘random’ is used, density is the approximate number of points, rather than the distance between grid points

  • spacing (int) – the grid spacing, in pixels

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

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

Returns:

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

Return type:

DataFrame

matching templates#

spymicmac.matching.cross_template(shape, width=3, angle=None, no_border=False)[source]#

Create a cross-shaped template for matching Réseau 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

  • angle (float) – the angle to rotate the template by (default: no rotation)

  • no_border (bool) – do not include a border around the cross

Returns:

cross – the cross template

Return type:

ndarray[Any, dtype[_ScalarType_co]]

spymicmac.matching.inscribed_cross(size, cross_size, width=3, angle=45)[source]#

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.

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

Returns:

template – the output template

Return type:

ndarray[Any, dtype[_ScalarType_co]]

spymicmac.matching.notch_template(size)[source]#

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

Parameters:

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

Returns:

template – the notch template

Return type:

ndarray[Any, dtype[_ScalarType_co]]

spymicmac.matching.padded_dot(size, disk_size)[source]#

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 – the disk with a padding of zeros around it

Return type:

ndarray[Any, dtype[_ScalarType_co]]

spymicmac.matching.wagon_wheel(size, width=3, mult=255, circle_size=None, circle_width=None, angle=None)[source]#

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 (int | float) – a multiplier to use for the template

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

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

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

Returns:

template the wagon wheel template

Return type:

ndarray[Any, dtype[_ScalarType_co]]

Contents