← Back to branch summary

~ubuntu-branches/ubuntu/utopic/sikuli/utopic

« back to all changes in this revision

Viewing changes to docs/source/finder.rst

  • Committer: Bazaar Package Importer
  • Author(s): Gilles Filippini
  • Date: 2011-04-16 00:23:53 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20110416002353-cn79cto3c03z5jx1
Tags: 1.0~x~rc2-dfsg1-1
* New upstream release:
  + Redesigned user interface for Sikuli-IDE
  + Support for extensions for Sikuli Script

* debian/control, debian/copyright:
  The package is now maintained by the Debian Java maintainers Team

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/source/finder.rst
 
1
Finder
 
2
======
 
3
 
 
4
.. py:class:: Finder
 
5
 
 
6
A Finder object implements an iterator of matches and allows to search for a visual
 
7
object in an image file that you provide (e.g. a screenshot taken and saved in a
 
8
file before). After setting up the finder object and doing a find operation, you can
 
9
iterate through the found matches if any.
 
10
 
 
11
Important to know:
 
12
 
 
13
*       per definition, an iterator can be stepped through only once - it is empty
 
14
        afterwards
 
15
*       it has to be destroyed using ``finder.destroy()``, especially when
 
16
        used with ``for:`` or ``while:``
 
17
*       when used in a ``with:`` construct, it is destroyed automatically
 
18
 
 
19
Compared with the region based find operation, no exception FindFailed is
 
20
raised in case nothing is found at all (use ``hasNext()`` to check). The finder object 
 
21
can be compared to what you get with ``region.getLastMatches()`` when using :py:meth:`findAll() <Region.findAll>`.
 
22
 
 
23
**Note**: With this version, there is no chance, to get the number of matches in
 
24
advance. If you would iterate through to count, afterwards your finder would be
 
25
empty. So in this case, you have to save your matches somehow (one possible solution
 
26
see example below).
 
27
 
 
28
The workflow always is, that you first do a find operation and afterwards go through the
 
29
matches found. After a complete iteration, the finder object is empty. So you
 
30
could start a new find operation again.
 
31
 
 
32
.. py:class:: Finder
 
33
 
 
34
        .. py:method:: Finder(path-to-imagefile)
 
35
 
 
36
                Create a new finder object.
 
37
 
 
38
                :param path-to-imagefile: filename to a source image to search within
 
39
        
 
40
        .. py:method:: find(path-to-imagefile, [similarity])
 
41
 
 
42
                Find a given image within a source image previously specified in the
 
43
                constructor of the finder object.
 
44
                
 
45
                :param path-to-imagefile: the target image to search for
 
46
                :param similarity: the minimum similarity a match should have. If omitted,
 
47
                        the default is used.
 
48
        
 
49
        .. py:method:: hasNext()
 
50
 
 
51
                Check whether there are more matches available that satisfy the minimum
 
52
                similarity requirement.
 
53
 
 
54
                :return: *True* if more matches exist.
 
55
 
 
56
        .. py:method:: next()
 
57
 
 
58
                Get the next match. 
 
59
 
 
60
                :return: a :py:class:`Match` object.
 
61
 
 
62
                The returnd reference to a match object is no longer available in the finder
 
63
                object afterwards. So if it is needed later on, it has to be saved to
 
64
                another variable.
 
65
 
 
66
 
 
67
Example 1: basic operations using a Finder
 
68
 
 
69
.. sikulicode::
 
70
        
 
71
        # create a Finder with your saved screenshot
 
72
        f = Finder("stars.png")
 
73
        img= "star.png" # the image you are searching
 
74
        
 
75
        f.find(img) # find all matches
 
76
        
 
77
        while f.hasNext(): # loop as long there is a first and more matches
 
78
                print "found: ", f.next() # access the next match in the row
 
79
        
 
80
        print f.hasNext() # is False, because f is empty now
 
81
        f.destroy() # release the memory used by finder
 
82
        
 
83
Example 2: we want to know how many matches (based on the previous example).
 
84
 
 
85
.. sikulicode::
 
86
        
 
87
        # create a Finder with your saved screenshot
 
88
        f = Finder("stars.png")
 
89
        img= "star.png" # the image you are searching
 
90
        
 
91
        f.find(img) # find all matches
 
92
        mm = [] # an empty list
 
93
 
 
94
        while f.hasNext(): # loop as long there is a first and more matches
 
95
                mm.append(f.next())     # access next match and add to mm
 
96
 
 
97
        print f.hasNext() # is False, because f is empty now
 
98
        f.destroy() # release the memory used by finder
 
99
        
 
100
        # now we have our matches saved in the list mm
 
101
        print len(mm) # the number of matches
 
102
 
 
103
        # we want to use our matches
 
104
        for m in mm:
 
105
                print m 
 
 
b'\\ No newline at end of file'