Fred's ImageMagick Scripts



    Licensing:

    Copyright © Fred Weinhaus

    My scripts are available free of charge for non-commercial (non-profit) use, ONLY.

    For use of my scripts in commercial (for-profit) environments or non-free applications, please contact me (Fred Weinhaus) for licensing arrangements. My email address is fmw at alink dot net.

    If you: 1) redistribute, 2) incorporate any of these scripts into other free applications or 3) reprogram them in another scripting language, then you must contact me for permission, especially if the result might be used in a commercial or for-profit environment.

    Usage, whether stated or not in the script, is restricted to the above licensing arrangements. It is also subject, in a subordinate manner, to the ImageMagick license, which can be found at: http://www.imagemagick.org/script/license.php

    Please read the Pointers For Use on my home page to properly install and customize my scripts.

DOTPRODUCTCORR


Computes the dot product correlation surface to find where a small image best matches within a larger image.

Download Script

last modified: January 17, 2020



USAGE: dotproductcorr [-s] [-p] [-m mode] [-c color] [-k kind] [-e edge] smallfile largefile corrfile [matchfile]
USAGE: dotproductcorr [-h or -help]

-s .............. stretch the correlation surface to full dynamic range so
................. that the best match is full white; default is unstretched
-p .............. apply a pseudocolor to the correlation surface image;
................. default is no pseudocoloring
-m .... mode .... mode for matchfile output; choices are: draw, overlay or
................. best; draw colored box at best match location, overlay
................. the small image at match location on a one half transparent
................. large image or output the best match subsection;
................. default=draw
-c .... color ... color to use for drawing box on large image where best
................. matched subsection was found; default=black
-t .... type .... type of approach used to combine color correlation results
................. into a single grayscale surface image; choices are: gray,
................. rec709luma, rec601luma, average and rms; default=gray
-e .... edge .... type of edge operator; choices are sobel, prewitt or
................. frei-chen; default=sobel

PURPOSE: To compute the dot product correlation surface on edge extracted images to find where a small image best matches within a larger image.

DESCRIPTION: DOTPRODUCTCORR computes the dot product correlation surface on edge extracted images to find where a small (first) image best matches within a larger (second) image. Since the matching may differ for each channel, the output correlation image will be converted to grayscale. Any alpha channel on either image will be removed automatically before processing. Values in the correlation surface can vary between +1 and -1, with a perfect match being +1. If the correlation surface result is saved to an image format that does not support negative values, the correlation surface will be clamped so that all negative values are zero.

ARGUMENTS:

-s ... Stretch the normalized cross correlation surface image to full dynamic range so that the best match is full white. Default is no stretch

-p ... Apply a pseudocoloring to the normalized cross correlation surface image where red corresponds to the highest values and purple to the lowest values. Default is no pseudocoloring.

-m mode ... MODE is the layout mode for the optional matchfile image. Choices are draw (or d), overlay (or o) or best (or b). Draw simply draws a colored box outline at the best match subsection in the larger image. Overlay inserts the small image at the match location of a 30% opaque version of the larger image. Best outputs the subsection of the larger image that best matches the smaller image. The default="draw". Ignored if no matchfile specified.

-c color ... COLOR is the color to use to draw the outline of the best matching subsection in the larger image when mode=draw. Any valid IM color specification may be used. The default=black.

-t type ... TYPE of approach used to combine color correlation results into a single grayscale surface image. The choices are: gray, rec709luma, rec601luma, average and rms. The default=gray. Note that average and rms require IM 6.8.5.5 or higher.

-e edge ... EDGE is the type of edge operator. The choices are sobel, prewitt or frei-chen (or freichen). The default=sobel

REQUIREMENTS: IM version 6.5.4-7 or higher, but compiled with HDRI enabled in any quantum level of Q8, Q16 or Q32. Also requires the FFTW delegate library.

REFERENCES:
F. Weinhaus and G. Latshaw, Edge Extraction Based Image Correlation, Proceedings SPIE, Vol. 205, 67 - 75, 1979
http://www.codeproject.com/Articles/99457/Edge-Based-Template-Matching
http://en.wikipedia.org/wiki/Dot_product

NOTE: Perfect result may not achieve a match score of 1.0 and may vary with the size of the smaller image due possibly to virtual-pixel edge effects near the boundary of the smaller image in comparison to the edges for the same region in the larger image.

See Fourier Transform Processing with ImageMagick, for more details.

CAVEAT: No guarantee that this script will work on all platforms, nor that trapping of inconsistent parameters is complete and foolproof. Use At Your Own Risk.


EXAMPLES


Small Image
(subsection [64x64+32+27])

Large Image

Edge Extracted Small Image
(magnitude of X and Y Derivatives)

Edge Extracted Large Image
(magnitude of X and Y Derivatives)

Arguments:
(none)
Match Coords: (32,27) And Score In Range 0 to 1: (0.9832)

Correlation Image

Match Location

Arguments:
-p
Match Coords: (32,27) And Score In Range 0 to 1: (0.9832)

Correlation Image

Match Location



Small Image
(subsection [23x14+156+22])

Large Image

Edge Extracted Small Image
(magnitude of X and Y Derivatives)

Edge Extracted Large Image
(magnitude of X and Y Derivatives)

Arguments:
-c white
Match Coords: (156,22) And Score In Range 0 to 1: (0.904073)

Correlation Image

Match Location



What the script does is as follows:

  • Perform X and Y edge detection on the small and large image
  • Create the magnitude of the X and Y derivatives of both the small and large image
  • Divide the X and Y derivative images by the corresponding magnitude images
    for both the small and large image
  • Pad the small derivative images with black to the size of the large derivative images
  • Do correlation of each small derivative image with its corresponding large derivate image
  • Add the two correlation images together and divide by the number of pixels in the original small image

See the script for actual code details. Or for more mathematical detail
see Fourier Transform Processing With ImageMagick