Finds the cropped image inside the original image.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long. 2.3KB


Build Status codecov

Finds the cropped image in the original one.

Made with ❤ and powered by OpenCV.


Clone the repo and install.

  • $ git clone && cd waldo
  • $ python install

Usage via CLI

The usage via CLI is pretty simple:

Usage: subimage image1.jpeg image2.jpeg --display[Optional]

Args --display will give you a nice tiny graphical window to show the result.

Once installed, the binary subimage will be available in the path.

To find the top left position:

$ subimage images\landing.JPG images\landing-face.JPG

You can also pass --display arg to enable graphical interface to show the result.

$ subimage images\landing.JPG images\landing-face.JPG

Using as Library

You can use functionality as an standalone library as well in other programs.

>>> from subimage import SubImage
>>> sub_image = SubImage(first_image_path='images/puzzle.png', second_image_path='images/waldo.png')
>>> sub_image.find_match()
>>> sub_image.tell_top_left()
Top Left: (1300, 852)
>>> sub_image.display() # It will open up a graphical window and shows the result
Exit with pressing 0 (zero).

To find more detailed examples of how to use the library you may have a look at tests/ test case file.


In case you don’t want to install the library would like to try it:

  • $ git clone && cd waldo
  • $ pip install -r requirements-dev.txt

Since you have not installed it, therefore no subimage binary/script will be available, in order to access it, call the as follow:

$ python image1.jpeg image2.jpeg --display[Optional]


The implementation is well tested and all the tests can be run via:

$ python test

Code Coverage

To review the code coverage report run:

$ python coverage

It will generate the code coverage, printed on screen and saved in HTML format under htmlcov/ dir.


On every push travis-CI will trigger the tests and report the code coverage.