Package org.opensourcephysics.media.core

Class TemplateMatcher

java.lang.Object
org.opensourcephysics.media.core.TemplateMatcher
public class TemplateMatcher extends Object
A class to find the best match of a template image in a target image. The match location is estimated to sub-pixel accuracy by assuming the distribution of match scores near a peak is Gaussian.
Version:
1.0
Author:
Douglas Brown

  • Constructor Details

    • TemplateMatcher

      public TemplateMatcher(BufferedImage image, Shape maskShape)
      Constructs a TemplateMatcher object. If a mask shape is specified, then only pixels that are entirely inside the mask are included in the template.
      Parameters:
      image - the image to match
      maskShape - a shape to define inside pixels (may be null)

  • Method Details

    • setTemplate

      public void setTemplate(BufferedImage image)
      Sets the template to be used for the next search. The new template dimensions must match those of the previous template.
      Parameters:
      image - the template image

    • getWorkingPixels

      public int[] getWorkingPixels()
      Gets the working image pixels used to generate the template.
      Parameters:
      pixels - int[] of pixels. If null, it will be created
      Returns:
      the filled pixels array

    • getTemplate

      public BufferedImage getTemplate()
      Gets the template. Includes only pixels inside the mask.
      Returns:
      the template

    • buildTemplate

      public BufferedImage buildTemplate(BufferedImage image, int alphaInput, int alphaOriginal)
      Builds the template from an input image. The input image dimensions must match the original. The input and original are overlaid onto the working image, from which the template is generated. Pixels that fall outside the mask are ignored in the f template.
      Parameters:
      image - the input image
      alphaInput - the opacity with which the input image is overlaid (0-255)
      alphaOriginal - the opacity with which the original image is overlaid (0-255)
      Returns:
      the template

    • getAlphas

      public int[] getAlphas()
      Gets the alphas used to build the most recent template.
      Returns:
      int[] {alphaInput, alphaOriginal}

    • setIndex

      public void setIndex(int index)
      Sets the index.
      Parameters:
      index - the index

    • getIndex

      public int getIndex()
      Gets the index. Note: index is not set internally, but only with calls to setIndex().
      Returns:
      the index

    • setWorkingPixels

      public void setWorkingPixels(int[] pixels)
      Sets the working image pixels used to generate the template.
      Parameters:
      pixels - int[] of pixels

    • getMatchLocation

      public TPoint getMatchLocation(BufferedImage target, Rectangle searchRect, int[][] searchPts)
      Gets the template location at which the best match occurs in a rectangle. May return null. Template matching process: 1. At each test position in the search area, find the RGB square deviation ("RGBSqD": sum of squares of rgb differences of all pixels) between the template and video image. Note that the RGBSqD is zero for a perfect match and larger for poorer matches. 2. Determine the average RGBSqD for all test positions. 3. Define the position for which the RGBSqD is minimum as the "working" best match. Define the peak height ("PH") of this match to be PH = (avgRGBSqD/matchRGBSqD)-1. Note that the PH may vary from zero to infinity. 4. If the PH exceeds the "Automark" setting, the match is deemed to be a good one (i.e., significantly better than average). 5. For sub-pixel accuracy, fit a parabola to the RGBSqD of the best match and its immediate vertical and horizontal neighbors. 6. The final best match (sub-pixel) is the position of the minimum of the polynomial fit. 7. The curvature of the parabolic fit is used to explicitly estimate the uncertainty of the fit. If uncertainty > 1 pixel then the peak height is divided by that uncertainty. This assures that very wide fits are not treated as good fits.
      Parameters:
      target - the image to search
      searchRect - the rectangle to search within the target image
      searchPts - optional [x, y] points to search within the rectangle (may be null)
      Returns:
      the optimized template location at which the best match, if any, is found

    • getMatchImage

      public BufferedImage getMatchImage()
      Gets the most recent match image.
      Returns:
      the best match image

    • getMatchWidthAndHeight

      public double[] getMatchWidthAndHeight()
      Returns the width and height of the peak for the most recent match. The peak height is the ratio meanSqPixelDiff/matchSqPixelDiff. The peak width is the mean of the vertical and horizontal Gaussian fit widths. This data can be used to determine whether a match is acceptable. A peak height greater than 5 is a reasonable standard for acceptability. Special cases: 1. If the match is perfect, then the height is infinite and the width NaN. 2. If the searchRect fell outside the target image, then no match was possible and both the width and height are NaN. 3. If there were no points to search along the 1D x-axis path, then the height is NaN and the width is negative. 4. If the Gaussian fit optimization was not successful (either horizontally or vertically) then the height is finite and the width is NaN.
      Returns:
      double[2] {mean Gaussian width, height}

    • getValue

      public static int getValue(int a, int argb)
      Method to get the color value
      Parameters:
      a - 0-255 alpha
      argb - current color value
      Returns:
      the integer value

    • getValue

      public static int getValue(int a, int r, int g, int b)
      Method to get the color value
      Parameters:
      a - 0-255 alpha
      r - 0-255 red
      g - 0-255 green
      b - 0-255 blue
      Returns:
      the integer value

    • getAlpha

      public static int getAlpha(int value)
      Method to get the alpha component from a color value
      Parameters:
      value - the color value
      Returns:
      0-255 alpha component

    • getRed

      public static int getRed(int value)
      Method to get the red component from a color value
      Parameters:
      value - the color value
      Returns:
      0-255 red component

    • getGreen

      public static int getGreen(int value)
      Method to get the green component from a color value
      Parameters:
      value - the color value
      Returns:
      0-255 green component

    • getBlue

      public static int getBlue(int value)
      Method to get the blue component from a color value
      Parameters:
      value - the color value
      Returns:
      0-255 blue component

    • getSearchPoints

      public int[][] getSearchPoints(Rectangle searchRect, double x0, double y0, double theta, int lineSpread)
      Gets an array of points [x, y] that lie within pixels in a rectangle and along a line.
      Parameters:
      searchRect - the rectangle
      x0 - the x-component of a point on the line
      y0 - the y-component of a point on the line
      theta - the angle of the line
      lineSpread - ignored, not yet implemented
      Returns:
      array of search points [x, y]