VISGREP(1)                           General Commands Manual                           VISGREP(1)

NAME
       visgrep - Visual grep, greps for images in another image

SYNOPSIS
       visgrep [options] image.png detect.png match.png ...

DESCRIPTION
       visgrep is a program that greps for image in another image.

       The detect.png and match.png files can also be .pat files.

       All  .pat  files  are created using png2pat(1) or rgb2pat(1). The image.png is scanned for
       detect.pat starting from X,Y given in parameters.  When detect.pat is found, then all  the
       match.pat  files are scanned at an offset of x,y given in parameters. If a match is found,
       then visgrep prints the x,y and index of the item.

       For example, image.png is a screenshot and match1.pat .. match5.pat are images of  letters
       a  to e. Each of these letters is enclosed in a blue box, so detect.pat is an image of the
       upper left corner of the box. This box is not included in the match*.pat  files,  so  they
       are  actually  offset  5 pixels down and 4 pixels to the left.  You might run it like this
       then:

         visgrep -x-4 -y5 image.png match_corner.pat match_a.pat match_b.bat ...

       Etc, with all matches listed. Now suppose the screen showed ace so visgrep might output:

         10,10 0
         50,10 2
         90,10 4

       Showing that match_a.pat (index 0) is at 10,10 on the screen. If no match  is  found  even
       though the detection image is found, the index will be -1.

OPTIONS
       A summary of options is included below.

       -h     Show summary of options.

       -x     Set x offset for detection matching.

       -y     Set y offset for detection matching.

       -X     Start scanning at X.

       -Y     Start scanning at Y.

       -t     Set tolerance for 'fuzzy' matches, higher numbers are more tolerant.

EXIT STATUS
       0      at least one match was made.

       1      no matches were made.

       2      an error occurred.

SEE ALSO
       pat2ppm(1), patextract(1), png2pat(1), rgb2pat(1), xte(1).

AUTHOR
       visgrep was written by Steve Slaven <bpk@hoopajoo.net>.

       This  manual  page  was  written  by  Aurelien  Jarno <aurel32@debian.org>, for the Debian
       project (but may be used by others).

                                          April 20, 2004                               VISGREP(1)

visgrep v1.09
visual grep, greps for images in another image
Author: Steve Slaven - http://hoopajoo.net

usage: visgrep [-hba] [-x x_off] [-y y_off]
          [-w x_off_width] [-h y_off_height]
          [-X start x_off] [-Y start y_off]
          [-d debuglevel] [-t tolerance] image.png detect.png match.png ...

  -h   This help
  -x   Set x offset for detection matching
  -y   Set y offset for detection matching
  -W   Set x offset width for detection matching
  -H   Set y offset height for detection matching
  -X   Start scanning at X
  -Y   Start scanning at Y
  -a   Scan all patterns, not just after matching the detection pattern
       note: this method is much slower because we scan for all images
             at every pixel instead of just at detection points.  Also,
             in this mode the detection image is ignored, there will be
             no matches for tile -1
  -t   Set tolerance for 'fuzzy' matches, higher numbers are more tolerant
  -b   Display 'badness' value, higher numbers mean match is less accurate,
       a badness value of 0 means the match is pixel-perfect

The detect.png and match.png can also be .pat files.

All .pat files are created using png2pat or rgb2pat.  The image.png is
scanned for detect.pat starting from X,Y specified above.  When detect.pat
is found, then all the match.pat files are scanned at an offset of x,y as
specified above.  If a match is found, then visgrep prints the x,y and
index of the item.

image.png must be an 8 bit deep RGB or RGBA png file.
For example, image.png is a screenshot and match1.pat .. to match5.pat are
images of letters a to e.  Each of these letters is enclosed in a blue box,
so detect.pat is an image of the upper left corner of the box.  This box is
not included in the match*.pat files, so they are actually offset 5 pixels
down and 4 pixels to the left.  You might run it like this then:

  visgrep -b -t50 -x-4 -y5 image.png match_corner.pat match_a.pat match_b.pat ...

Etc, with all matches listed.  Now suppose the screen showed 'ace' so
visgrep might output:

0 10,10 0
12 50,10 2
7 90,10 4

Showing that match_a.pat (index 0) is at 10,10 on the screen.  If no match
is found even though the detection image is found, the index will be -1.

The first match was 100% accurate, while the second and third were very slightly
inaccurate, probably due to anti-aliasing on the fonts.

Exit status is 0 for successful match, 1 for no match, and 2 for error.

See the examples page for use cases for different flags