spymicmac.image

spymicmac.image is a collection of tools for working with aerial images.

spymicmac.image.balance_image(img)

Apply contrast-limited adaptive histogram equalization (CLAHE) on an image, then apply a de-noising filter.

Parameters

img (array-like) – the image to balance.

Returns

• img_filt (array-like) – the balanced, filtered image.

spymicmac.image.contrast_enhance(fn_img, mask_value=None, qmin=0.02, qmax=0.98, gamma=1.25)

Enhance image contrast in a three-step process. First, the image is processed with a median filter to reduce noise. Next, a linear contrast stretch is applied, and finally, a gamma adjustment is applied.

Parameters

• fn_img (str) – the image filename.

• mask_value (int|float) – a mask value to use when filtering the image.

• qmin (float) – the minimum quantile to use for the linear contrast stretch (default: 0.02)

• qmax (float) – the maximum quantile to use for the linear contrast stretch (default: 0.98)

• gamma (float) – the value to use for the gamma adjustment

Returns

• enhanced (array-like) – the contrast-enhanced image.

spymicmac.image.find_cross(img, pt, cross, tsize=300)

Find the center of a Reseau mark (cross, or ‘+’ shape).

Parameters

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

• pt (tuple) – the initial search location.

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

• tsize (int) – the search grid half-size (default: 300 -> 601x601)

Returns

• center_i (float) – the row coordinate of the cross center.

• center_j (float) – the column coordinate of the cross center.

spymicmac.image.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.image.find_reseau_border(img, rough_ext, cross, tsize=300)

Find the rough edges of the Reseau field in a KH-9 image.

Parameters

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

• rough_ext (array-like) – the rough location (left, right, top, bottom) of the image border.

• cross (array-like) – a Reseau mark template.

• tsize (int) – the search grid size for the Reseau mark.

Returns

• left_edge (LineString) – the left-side Reseau field border

• right_edge (LineString) – the right-side Reseau field border

spymicmac.image.find_reseau_grid(fn_img, csize=361, tsize=300, nproc=1, 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)

• tsize (int) – the search grid size for the Reseau mark.

• nproc (int) – the number of processors to use, via multiprocessing.Pool (default: 1).

• 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.image.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.image.get_footprint_mask(shpfile, geoimg, filelist, fprint_out=False)

Return a footprint mask for an image.

Parameters

• shpfile (str|GeoDataFrame) – a filename or a GeoDataFrame representation of the footprints.

• geoimg (GeoImg) – the image to create a mask for.

• filelist (list) – a list of image names to use to create the footprint mask.

• fprint_out (bool) – return the polygon representation of the footprint mask.

Returns

• mask (array-like) – the footprint mask

• fprint (shapely.Polygon) – the footprint polygon, if requested.

spymicmac.image.get_footprint_overlap(fprints)

Return the area where image footprints overlap.

Parameters

fprints (GeoDataFrame) – a GeoDataFrame of image footprints

Returns

• intersection (shapely.Polygon) – the overlapping area (cascaded union) of the images.

spymicmac.image.get_rough_frame(img)

Find the rough location of an image frame/border.

Parameters

img (array-like) – the image to find a border for

Returns

• xmin, xmax, ymin, ymax (float) – the left, right, top, and bottom indices for the rough border.

spymicmac.image.get_rough_geotransform(img1, img2, landmask=None, footmask=None, stretch=(0.05, 0.95), equalize=False)

Search for a rough transformation between two images using ORB keypoint matching.

Parameters

• img1 (array-like) – the image to be transformed.

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

• landmask (array-like) – an inclusion mask for img2.

• footmask (array-like) – an exclusion mask for img2.

• stretch (tuple) – the minimum and maximum quantiles to stretch img2 to.

• equalize (bool) – apply CLAHE to img2.

Returns

• img1_tfm (array-like) – the transformed input image.

• Minit (AffineTransform) – the estimated affine transformation between img1 and img2.

• dst_pts, src_pts, inliers (array-like) – the matched points for img2, img1, and the inliers used to estimate Minit.

spymicmac.image.highpass_filter(img)

Subtract a low-pass from an image, to return a highpass filter.

Parameters

img (array-like) – the image to filter.

Returns

• highpass (array-like) – the highpass-filtered image

spymicmac.image.join_hexagon(im_pattern, overlap=2000, blend=True, corona=False)

Join two halves of a scanned KH-9 Hexagon image (or four parts of a scanned KH-4 Corona image).

Parameters

• im_pattern (str) – the base name of the image to use (e.g., DZB1216-500280L002001).

• overlap (int) – the overlap, in pixels, between the image parts.

• blend (bool) – apply a linear blend between the two scanned halves (default: True).

• corona (bool) – image is a KH-4/4A Corona image. If True, looks for four image parts instead of two (default: False).

spymicmac.image.make_binary_mask(img, mult_value=255, erode=0, mask_value=0)

Create a binary mask for an image based on a given mask value. Values equal to mask_value will be given a value of 0 in the mask, while all other values will be set equal to mult_value.

Parameters

• img (array-like) – the image to create a mask for.

• mult_value (int|float) – the value indicating a non-masked value (default: 255).

• erode (int) – the size of the erosion operation to apply (default: 0).

• mask_value (int) – the value to mask in the image (default: 0).

Returns

• mask (array-like) the binary mask.

spymicmac.image.match_halves(left, right, overlap)

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.

Returns

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

spymicmac.image.remove_crosses(fn_img)

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

Parameters

fn_img (str) – the image filename.

spymicmac.image.stretch_image(img, scale=(0, 1), mult=255, outtype=<MagicMock id='140529640252896'>, mask=None)

Apply a linear stretch to an image by clipping and stretching to quantiles.

Parameters

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

• scale (tuple) – a the minimum and maximum quantile to stretch to. (default: (0, 1) - the minimum/maximum values of the image)

• mult (int|float) – a multiplier to scale the result to. (default: 255)

• outtype (numpy.dtype) – the numpy datatype to return the stretched image as. (default: np.uint8)

• mask (array-like) – a mask of pixels to ignore when calculating quantiles.

Returns

• stretched (array-like) – the stretched image.

spymicmac.image.transform_from_fprint(img, geo, fprint)

Using a georeferenced footprint for an image, estimate a Euclidean transform.

Parameters

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

• geo (GeoImg) – the reference image to transform the input image to.

• fprint (shapely.Polygon) – the image footprint to use for transformation.

Returns

• transform (GeometricTransform) – the estimated euclidean transform for the input image.