1478 lines
54 KiB
Python
1478 lines
54 KiB
Python
|
'''
|
||
|
|
Multistroke gesture recognizer
|
||
|
|
==============================
|
||
|
|
|
||
|
|
.. versionadded::
|
||
|
|
1.9.0
|
||
|
|
|
||
|
|
.. warning::
|
||
|
|
|
||
|
|
This is experimental and subject to change as long as this warning notice
|
||
|
|
is present.
|
||
|
|
|
||
|
|
See :file:`kivy/examples/demo/multistroke/main.py` for a complete application
|
||
|
|
example.
|
||
|
|
|
||
|
|
Conceptual Overview
|
||
|
|
-------------------
|
||
|
|
|
||
|
|
This module implements the Protractor gesture recognition algorithm.
|
||
|
|
|
||
|
|
:class:`Recognizer` is the search/database API similar to
|
||
|
|
:class:`~kivy.gesture.GestureDatabase`. It maintains a list of
|
||
|
|
:class:`MultistrokeGesture` objects and allows you to search for a
|
||
|
|
user-input gestures among them.
|
||
|
|
|
||
|
|
:class:`ProgressTracker` tracks the progress of a :meth:`Recognizer.recognize`
|
||
|
|
call. It can be used to interact with the running recognizer task, for example
|
||
|
|
forcing it to stop half-way, or analyzing results as they arrive.
|
||
|
|
|
||
|
|
:class:`MultistrokeGesture` represents a gesture in the gesture database
|
||
|
|
(:attr:`Recognizer.db`). It is a container for :class:`UnistrokeTemplate`
|
||
|
|
objects, and implements the heap permute algorithm to automatically generate
|
||
|
|
all possible stroke orders (if desired).
|
||
|
|
|
||
|
|
:class:`UnistrokeTemplate` represents a single stroke path. It's typically
|
||
|
|
instantiated automatically by :class:`MultistrokeGesture`, but sometimes you
|
||
|
|
may need to create them manually.
|
||
|
|
|
||
|
|
:class:`Candidate` represents a user-input gesture that is used to search
|
||
|
|
the gesture database for matches. It is normally instantiated automatically
|
||
|
|
by calling :meth:`Recognizer.recognize`.
|
||
|
|
|
||
|
|
Usage examples
|
||
|
|
--------------
|
||
|
|
|
||
|
|
See :file:`kivy/examples/demo/multistroke/main.py` for a complete application
|
||
|
|
example.
|
||
|
|
|
||
|
|
You can bind to events on :class:`Recognizer` to track the state of all
|
||
|
|
calls to :meth:`Recognizer.recognize`. The callback function will receive an
|
||
|
|
instance of :class:`ProgressTracker` that can be used to analyze and control
|
||
|
|
various aspects of the recognition process ::
|
||
|
|
|
||
|
|
from kivy.vector import Vector
|
||
|
|
from kivy.multistroke import Recognizer
|
||
|
|
|
||
|
|
gdb = Recognizer()
|
||
|
|
|
||
|
|
def search_start(gdb, pt):
|
||
|
|
print("A search is starting with %d tasks" % (pt.tasks))
|
||
|
|
|
||
|
|
def search_stop(gdb, pt):
|
||
|
|
# This will call max() on the result dictionary, so it's best to store
|
||
|
|
# it instead of calling it 3 times consecutively
|
||
|
|
best = pt.best
|
||
|
|
print("Search ended (%s). Best is %s (score %f, distance %f)" % (
|
||
|
|
pt.status, best['name'], best['score'], best['dist'] ))
|
||
|
|
|
||
|
|
# Bind your callbacks to track all matching operations
|
||
|
|
gdb.bind(on_search_start=search_start)
|
||
|
|
gdb.bind(on_search_complete=search_stop)
|
||
|
|
|
||
|
|
# The format below is referred to as `strokes`, a list of stroke paths.
|
||
|
|
# Note that each path shown here consists of two points, ie a straight
|
||
|
|
# line; if you plot them it looks like a T, hence the name.
|
||
|
|
gdb.add_gesture('T', [
|
||
|
|
[Vector(30, 7), Vector(103, 7)],
|
||
|
|
[Vector(66, 7), Vector(66, 87)]])
|
||
|
|
|
||
|
|
# Now you can search for the 'T' gesture using similar data (user input).
|
||
|
|
# This will trigger both of the callbacks bound above.
|
||
|
|
gdb.recognize([
|
||
|
|
[Vector(45, 8), Vector(110, 12)],
|
||
|
|
[Vector(88, 9), Vector(85, 95)]])
|
||
|
|
|
||
|
|
On the next :class:`~kivy.clock.Clock` tick, the matching process starts
|
||
|
|
(and, in this case, completes).
|
||
|
|
|
||
|
|
To track individual calls to :meth:`Recognizer.recognize`, use the return
|
||
|
|
value (also a :class:`ProgressTracker` instance) ::
|
||
|
|
|
||
|
|
# Same as above, but keep track of progress using returned value
|
||
|
|
progress = gdb.recognize([
|
||
|
|
[Vector(45, 8), Vector(110, 12)],
|
||
|
|
[Vector(88, 9), Vector(85, 95)]])
|
||
|
|
|
||
|
|
progress.bind(on_progress=my_other_callback)
|
||
|
|
print(progress.progress) # = 0
|
||
|
|
|
||
|
|
# [ assuming a kivy.clock.Clock.tick() here ]
|
||
|
|
|
||
|
|
print(result.progress) # = 1
|
||
|
|
|
||
|
|
Algorithm details
|
||
|
|
-----------------
|
||
|
|
|
||
|
|
For more information about the matching algorithm, see:
|
||
|
|
|
||
|
|
"Protractor: A fast and accurate gesture recognizer" by Yang Li
|
||
|
|
http://yangl.org/pdf/protractor-chi2010.pdf
|
||
|
|
|
||
|
|
"$N-Protractor" by Lisa Anthony and Jacob O. Wobbrock
|
||
|
|
http://depts.washington.edu/aimgroup/proj/dollar/ndollar-protractor.pdf
|
||
|
|
|
||
|
|
Some of the code is derived from the JavaScript implementation here:
|
||
|
|
http://depts.washington.edu/aimgroup/proj/dollar/ndollar.html
|
||
|
|
'''
|
||
|
|
|
||
|
|
__all__ = ('Recognizer', 'ProgressTracker', 'MultistrokeGesture',
|
||
|
|
'UnistrokeTemplate', 'Candidate')
|
||
|
|
|
||
|
|
import pickle
|
||
|
|
import base64
|
||
|
|
import zlib
|
||
|
|
from re import match as re_match
|
||
|
|
from collections import deque
|
||
|
|
from math import sqrt, pi, radians, acos, atan, atan2, pow, floor
|
||
|
|
from math import sin as math_sin, cos as math_cos
|
||
|
|
from kivy.vector import Vector
|
||
|
|
from kivy.clock import Clock
|
||
|
|
from kivy.event import EventDispatcher
|
||
|
|
from kivy.properties import ListProperty
|
||
|
|
from kivy.compat import PY2
|
||
|
|
from io import BytesIO
|
||
|
|
|
||
|
|
if not PY2:
|
||
|
|
xrange = range
|
||
|
|
|
||
|
|
# Default number of gesture matches per frame
|
||
|
|
# FIXME: relevant number
|
||
|
|
DEFAULT_GPF = 10
|
||
|
|
|
||
|
|
# Algorithm data
|
||
|
|
SQUARESIZE = 250.0
|
||
|
|
ONEDTHRESHOLD = 0.25
|
||
|
|
ORIGIN = Vector(0, 0)
|
||
|
|
|
||
|
|
|
||
|
|
class MultistrokeError(Exception):
|
||
|
|
pass
|
||
|
|
|
||
|
|
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
# Recognizer
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
|
||
|
|
class Recognizer(EventDispatcher):
|
||
|
|
''':class:`Recognizer` provides a gesture database with matching
|
||
|
|
facilities.
|
||
|
|
|
||
|
|
:Events:
|
||
|
|
`on_search_start`
|
||
|
|
Fired when a new search is started using this Recognizer.
|
||
|
|
|
||
|
|
`on_search_complete`
|
||
|
|
Fired when a running search ends, for whatever reason.
|
||
|
|
(use :data:`ProgressTracker.status` to find out)
|
||
|
|
|
||
|
|
:Properties:
|
||
|
|
`db`
|
||
|
|
A :class:`ListProperty` that contains the available
|
||
|
|
:class:`MultistrokeGesture` objects.
|
||
|
|
|
||
|
|
:attr:`db` is a
|
||
|
|
:class:`~kivy.properties.ListProperty` and defaults to []
|
||
|
|
'''
|
||
|
|
|
||
|
|
db = ListProperty([])
|
||
|
|
|
||
|
|
def __init__(self, **kwargs):
|
||
|
|
super(Recognizer, self).__init__(**kwargs)
|
||
|
|
self.register_event_type('on_search_start')
|
||
|
|
self.register_event_type('on_search_complete')
|
||
|
|
|
||
|
|
def filter(self, **kwargs):
|
||
|
|
''':meth:`filter` returns a subset of objects in :attr:`self.db`,
|
||
|
|
according to given criteria. This is used by many other methods of
|
||
|
|
the :class:`Recognizer`; the arguments below can for example be
|
||
|
|
used when calling :meth:`Recognizer.recognize` or
|
||
|
|
:meth:`Recognizer.export_gesture`. You normally don't need to call
|
||
|
|
this directly.
|
||
|
|
|
||
|
|
:Arguments:
|
||
|
|
|
||
|
|
`name`
|
||
|
|
Limits the returned list to gestures where
|
||
|
|
:attr:`MultistrokeGesture.name` matches given regular
|
||
|
|
expression(s). If re.match(name, MultistrokeGesture.name)
|
||
|
|
tests true, the gesture is included in the returned list.
|
||
|
|
Can be a string or an array of strings ::
|
||
|
|
|
||
|
|
gdb = Recognizer()
|
||
|
|
|
||
|
|
# Will match all names that start with a capital N
|
||
|
|
# (ie Next, New, N, Nebraska etc, but not "n" or "next")
|
||
|
|
gdb.filter(name='N')
|
||
|
|
|
||
|
|
# exactly 'N'
|
||
|
|
gdb.filter(name='N$')
|
||
|
|
|
||
|
|
# Nebraska, teletubbies, France, fraggle, N, n, etc
|
||
|
|
gdb.filter(name=['[Nn]', '(?i)T', '(?i)F'])
|
||
|
|
|
||
|
|
`priority`
|
||
|
|
Limits the returned list to gestures with certain
|
||
|
|
:attr:`MultistrokeGesture.priority` values. If specified as an
|
||
|
|
integer, only gestures with a lower priority are returned. If
|
||
|
|
specified as a list (min/max) ::
|
||
|
|
|
||
|
|
# Max priority 50
|
||
|
|
gdb.filter(priority=50)
|
||
|
|
|
||
|
|
# Max priority 50 (same result as above)
|
||
|
|
gdb.filter(priority=[0, 50])
|
||
|
|
|
||
|
|
# Min priority 50, max 100
|
||
|
|
gdb.filter(priority=[50, 100])
|
||
|
|
|
||
|
|
When this option is used, :attr:`Recognizer.db` is
|
||
|
|
automatically sorted according to priority, incurring extra
|
||
|
|
cost. You can use `force_priority_sort` to override this
|
||
|
|
behavior if your gestures are already sorted according to
|
||
|
|
priority.
|
||
|
|
|
||
|
|
`orientation_sensitive`
|
||
|
|
Limits the returned list to gestures that are
|
||
|
|
orientation sensitive (True), gestures that are not orientation
|
||
|
|
sensitive (False) or None (ignore template sensitivity, this is
|
||
|
|
the default).
|
||
|
|
|
||
|
|
`numstrokes`
|
||
|
|
Limits the returned list to gestures that have the specified
|
||
|
|
number of strokes (in :attr:`MultistrokeGesture.strokes`).
|
||
|
|
Can be a single integer or a list of integers.
|
||
|
|
|
||
|
|
`numpoints`
|
||
|
|
Limits the returned list to gestures that have specific
|
||
|
|
:attr:`MultistrokeGesture.numpoints` values. This is provided
|
||
|
|
for flexibility, do not use it unless you understand what it
|
||
|
|
does. Can be a single integer or a list of integers.
|
||
|
|
|
||
|
|
`force_priority_sort`
|
||
|
|
Can be used to override the default sort behavior. Normally
|
||
|
|
:class:`MultistrokeGesture` objects are returned in priority
|
||
|
|
order if the `priority` option is used. Setting this to True
|
||
|
|
will return gestures sorted in priority order, False will
|
||
|
|
return in the order gestures were added. None means decide
|
||
|
|
automatically (the default).
|
||
|
|
|
||
|
|
.. Note ::
|
||
|
|
For improved performance, you can load your gesture
|
||
|
|
database in priority order and set this to False when
|
||
|
|
calling :meth:`Recognizer.recognize`
|
||
|
|
|
||
|
|
`db`
|
||
|
|
Can be set if you want to filter a different list of objects
|
||
|
|
than :attr:`Recognizer.db`. You probably don't want to do this;
|
||
|
|
it is used internally by :meth:`import_gesture`.
|
||
|
|
'''
|
||
|
|
have_filters = False
|
||
|
|
|
||
|
|
kwargs_get = kwargs.get
|
||
|
|
|
||
|
|
name = kwargs_get('name', None)
|
||
|
|
if name is not None:
|
||
|
|
have_filters = True
|
||
|
|
if not isinstance(name, list):
|
||
|
|
name = [name]
|
||
|
|
|
||
|
|
priority = kwargs_get('priority', None)
|
||
|
|
min_p, max_p = None, None
|
||
|
|
if priority is not None:
|
||
|
|
have_filters = True
|
||
|
|
if isinstance(priority, list):
|
||
|
|
min_p, max_p = priority
|
||
|
|
elif isinstance(priority, int):
|
||
|
|
min_p, max_p = None, priority
|
||
|
|
|
||
|
|
numstrokes = kwargs_get('numstrokes', None)
|
||
|
|
if numstrokes is not None:
|
||
|
|
have_filters = True
|
||
|
|
if not isinstance(numstrokes, list):
|
||
|
|
numstrokes = [numstrokes]
|
||
|
|
|
||
|
|
numpoints = kwargs_get('numpoints', None)
|
||
|
|
if numpoints is not None:
|
||
|
|
have_filters = True
|
||
|
|
if not isinstance(numpoints, list):
|
||
|
|
numpoints = [numpoints]
|
||
|
|
|
||
|
|
orientation_sens = kwargs_get('orientation_sensitive', None)
|
||
|
|
if orientation_sens is not None:
|
||
|
|
have_filters = True
|
||
|
|
|
||
|
|
# Prepare a correctly sorted tasklist
|
||
|
|
force_priority_sort = kwargs.get('force_priority_sort', None)
|
||
|
|
force_sort_on = force_priority_sort and True
|
||
|
|
force_sort_off = (force_priority_sort is False) and True
|
||
|
|
|
||
|
|
db = kwargs.get('db', None) or self.db
|
||
|
|
if (force_sort_on or priority) and not force_sort_off:
|
||
|
|
tasklist = sorted(db, key=lambda n: n.priority)
|
||
|
|
else:
|
||
|
|
tasklist = db
|
||
|
|
|
||
|
|
# Now test each gesture in the database against filter criteria
|
||
|
|
out = deque()
|
||
|
|
if not have_filters:
|
||
|
|
out.extend(tasklist)
|
||
|
|
return out
|
||
|
|
|
||
|
|
out_append = out.append
|
||
|
|
for gesture in tasklist:
|
||
|
|
|
||
|
|
if (orientation_sens is not None and
|
||
|
|
orientation_sens != gesture.orientation_sens):
|
||
|
|
continue
|
||
|
|
|
||
|
|
if numpoints and gesture.numpoints not in numpoints:
|
||
|
|
continue
|
||
|
|
|
||
|
|
if numstrokes and len(gesture.strokes) not in numstrokes:
|
||
|
|
continue
|
||
|
|
|
||
|
|
if min_p is not None and gesture.priority < min_p:
|
||
|
|
continue
|
||
|
|
|
||
|
|
if max_p is not None and gesture.priority > max_p:
|
||
|
|
return out
|
||
|
|
|
||
|
|
if name:
|
||
|
|
for f in name:
|
||
|
|
if re_match(f, gesture.name):
|
||
|
|
out_append(gesture)
|
||
|
|
break
|
||
|
|
else:
|
||
|
|
out_append(gesture)
|
||
|
|
|
||
|
|
return out
|
||
|
|
|
||
|
|
def add_gesture(self, name, strokes, **kwargs):
|
||
|
|
'''Add a new gesture to the database. This will instantiate a new
|
||
|
|
:class:`MultistrokeGesture` with `strokes` and append it to self.db.
|
||
|
|
|
||
|
|
.. Note ::
|
||
|
|
If you already have instantiated a :class:`MultistrokeGesture`
|
||
|
|
object and wish to add it, append it to :attr:`Recognizer.db`
|
||
|
|
manually.
|
||
|
|
'''
|
||
|
|
if not strokes:
|
||
|
|
return False
|
||
|
|
self.db.append(
|
||
|
|
MultistrokeGesture(name=name, strokes=strokes, **kwargs)
|
||
|
|
)
|
||
|
|
return True
|
||
|
|
|
||
|
|
def parse_gesture(self, data):
|
||
|
|
'''Parse data formatted by export_gesture(). Returns a list of
|
||
|
|
:class:`MultistrokeGesture` objects. This is used internally by
|
||
|
|
:meth:`import_gesture`, you normally don't need to call this
|
||
|
|
directly.'''
|
||
|
|
io = BytesIO(zlib.decompress(base64.b64decode(data)))
|
||
|
|
|
||
|
|
p = pickle.Unpickler(io)
|
||
|
|
multistrokes = []
|
||
|
|
ms_append = multistrokes.append
|
||
|
|
for multistroke in p.load():
|
||
|
|
strokes = multistroke['strokes']
|
||
|
|
multistroke['strokes'] = [[Vector(
|
||
|
|
x, y) for x, y in line] for line in strokes]
|
||
|
|
ms_append(MultistrokeGesture(**multistroke))
|
||
|
|
return multistrokes
|
||
|
|
|
||
|
|
# FIXME: use a try block, maybe shelve or something
|
||
|
|
def export_gesture(self, filename=None, **kwargs):
|
||
|
|
'''Export a list of :class:`MultistrokeGesture` objects. Outputs a
|
||
|
|
base64-encoded string that can be decoded to a Python list with
|
||
|
|
the :meth:`parse_gesture` function or imported directly to
|
||
|
|
:attr:`self.db` using :meth:`Recognizer.import_gesture`. If
|
||
|
|
`filename` is specified, the output is written to disk, otherwise
|
||
|
|
returned.
|
||
|
|
|
||
|
|
This method accepts optional :meth:`Recognizer.filter` arguments.
|
||
|
|
'''
|
||
|
|
io = BytesIO()
|
||
|
|
p = pickle.Pickler(io, protocol=0)
|
||
|
|
multistrokes = []
|
||
|
|
defaults = {'priority': 100, 'numpoints': 16, 'stroke_sens': True,
|
||
|
|
'orientation_sens': False, 'angle_similarity': 30.0}
|
||
|
|
dkeys = defaults.keys()
|
||
|
|
|
||
|
|
for multistroke in self.filter(**kwargs):
|
||
|
|
m = dict(defaults)
|
||
|
|
m = {'name': multistroke.name}
|
||
|
|
for attr in dkeys:
|
||
|
|
m[attr] = getattr(multistroke, attr)
|
||
|
|
m['strokes'] = tuple([(p.x, p.y) for p in line]
|
||
|
|
for line in multistroke.strokes)
|
||
|
|
multistrokes.append(m)
|
||
|
|
p.dump(multistrokes)
|
||
|
|
|
||
|
|
if filename:
|
||
|
|
f = open(filename, 'wb')
|
||
|
|
f.write(base64.b64encode(zlib.compress(io.getvalue(), 9)))
|
||
|
|
f.close()
|
||
|
|
else:
|
||
|
|
return base64.b64encode(zlib.compress(io.getvalue(), 9))
|
||
|
|
|
||
|
|
# FIXME: match them all with protractor, and don't load exacts? or
|
||
|
|
# just compare the data or something; seems better to do this on import
|
||
|
|
# than on every subsequent call to recognize(). And fix it in general,
|
||
|
|
# too.
|
||
|
|
def import_gesture(self, data=None, filename=None, **kwargs):
|
||
|
|
'''Import a list of gestures as formatted by :meth:`export_gesture`.
|
||
|
|
One of `data` or `filename` must be specified.
|
||
|
|
|
||
|
|
This method accepts optional :meth:`Recognizer.filter` arguments,
|
||
|
|
if none are specified then all gestures in specified data are
|
||
|
|
imported.'''
|
||
|
|
if filename is not None:
|
||
|
|
with open(filename, "rb") as infile:
|
||
|
|
data = infile.read()
|
||
|
|
elif data is None:
|
||
|
|
raise MultistrokeError('import_gesture needs data= or filename=')
|
||
|
|
|
||
|
|
new = self.filter(db=self.parse_gesture(data), **kwargs)
|
||
|
|
if new:
|
||
|
|
self.db.extend(new)
|
||
|
|
|
||
|
|
def transfer_gesture(self, tgt, **kwargs):
|
||
|
|
'''Transfers :class:`MultistrokeGesture` objects from
|
||
|
|
:attr:`Recognizer.db` to another :class:`Recognizer` instance `tgt`.
|
||
|
|
|
||
|
|
This method accepts optional :meth:`Recognizer.filter` arguments.
|
||
|
|
'''
|
||
|
|
if hasattr(tgt, 'db') and isinstance(tgt.db, list):
|
||
|
|
send = self.filter(**kwargs)
|
||
|
|
if send:
|
||
|
|
tgt.db.append(None)
|
||
|
|
tgt.db[-1:] = send
|
||
|
|
return True
|
||
|
|
|
||
|
|
def prepare_templates(self, **kwargs):
|
||
|
|
'''This method is used to prepare :class:`UnistrokeTemplate` objects
|
||
|
|
within the gestures in self.db. This is useful if you want to minimize
|
||
|
|
punishment of lazy resampling by preparing all vectors in advance. If
|
||
|
|
you do this before a call to :meth:`Recognizer.export_gesture`, you
|
||
|
|
will have the vectors computed when you load the data later.
|
||
|
|
|
||
|
|
This method accepts optional :meth:`Recognizer.filter` arguments.
|
||
|
|
|
||
|
|
`force_numpoints`, if specified, will prepare all templates to the
|
||
|
|
given number of points (instead of each template's preferred n; ie
|
||
|
|
:data:`UnistrokeTemplate.numpoints`). You normally don't want to
|
||
|
|
do this.'''
|
||
|
|
for gesture in self.filter(**kwargs):
|
||
|
|
for tpl in gesture:
|
||
|
|
n = kwargs.get('force_numpoints', tpl.numpoints)
|
||
|
|
tpl.prepare(n)
|
||
|
|
|
||
|
|
def recognize(self, strokes, goodscore=None, timeout=0, delay=0, **kwargs):
|
||
|
|
'''Search for gestures matching `strokes`. Returns a
|
||
|
|
:class:`ProgressTracker` instance.
|
||
|
|
|
||
|
|
This method accepts optional :meth:`Recognizer.filter` arguments.
|
||
|
|
|
||
|
|
:Arguments:
|
||
|
|
|
||
|
|
`strokes`
|
||
|
|
A list of stroke paths (list of lists of
|
||
|
|
:class:`~kivy.vector.Vector` objects) that will be matched
|
||
|
|
against gestures in the database. Can also be a
|
||
|
|
:class:`Candidate` instance.
|
||
|
|
|
||
|
|
.. Warning ::
|
||
|
|
|
||
|
|
If you manually supply a :class:`Candidate` that has a
|
||
|
|
skip-flag, make sure that the correct filter arguments
|
||
|
|
are set. Otherwise the system will attempt to load vectors
|
||
|
|
that have not been computed. For example, if you set
|
||
|
|
`skip_bounded` and do not set `orientation_sensitive` to
|
||
|
|
False, it will raise an exception if an
|
||
|
|
orientation_sensitive :class:`UnistrokeTemplate`
|
||
|
|
is encountered.
|
||
|
|
|
||
|
|
`goodscore`
|
||
|
|
If this is set (between 0.0 - 1.0) and a gesture score is
|
||
|
|
equal to or higher than the specified value, the search is
|
||
|
|
immediately halted and the on_search_complete event is
|
||
|
|
fired (+ the on_complete event of the associated
|
||
|
|
:class:`ProgressTracker` instance). Default is None (disabled).
|
||
|
|
|
||
|
|
`timeout`
|
||
|
|
Specifies a timeout (in seconds) for when the search is
|
||
|
|
aborted and the results returned. This option applies only
|
||
|
|
when `max_gpf` is not 0. Default value is 0, meaning all
|
||
|
|
gestures in the database will be tested, no matter how long
|
||
|
|
it takes.
|
||
|
|
|
||
|
|
`max_gpf`
|
||
|
|
Specifies the maximum number of :class:`MultistrokeGesture`
|
||
|
|
objects that can be processed per frame. When exceeded, will
|
||
|
|
cause the search to halt and resume work in the next frame.
|
||
|
|
Setting to 0 will complete the search immediately (and block
|
||
|
|
the UI).
|
||
|
|
|
||
|
|
.. Warning ::
|
||
|
|
|
||
|
|
This does not limit the number of
|
||
|
|
:class:`UnistrokeTemplate` objects matched! If a single
|
||
|
|
gesture has a million templates, they will all be
|
||
|
|
processed in a single frame with max_gpf=1!
|
||
|
|
|
||
|
|
`delay`
|
||
|
|
Sets an optional delay between each run of the recognizer
|
||
|
|
loop. Normally, a run is scheduled for the next frame until
|
||
|
|
the tasklist is exhausted. If you set this, there will be an
|
||
|
|
additional delay between each run (specified in seconds).
|
||
|
|
Default is 0, resume in the next frame.
|
||
|
|
|
||
|
|
`force_numpoints`
|
||
|
|
forces all templates (and candidate) to be prepared to a
|
||
|
|
certain number of points. This can be useful for example if
|
||
|
|
you are evaluating templates for optimal n (do not use this
|
||
|
|
unless you understand what it does).
|
||
|
|
'''
|
||
|
|
GPF = kwargs.get('max_gpf', DEFAULT_GPF)
|
||
|
|
|
||
|
|
# Obtain a list of MultistrokeGesture objects matching filter arguments
|
||
|
|
tasklist = self.filter(**kwargs)
|
||
|
|
|
||
|
|
# Initialize the candidate and result objects
|
||
|
|
cand = self._candidate(strokes)
|
||
|
|
result = ProgressTracker(cand, len(tasklist))
|
||
|
|
|
||
|
|
# This is done to inform caller if they bind to on_complete and there
|
||
|
|
# is nothing to do; perhaps should just return None?
|
||
|
|
if not tasklist:
|
||
|
|
result.status = 'complete'
|
||
|
|
self.dispatch('on_search_complete', result)
|
||
|
|
|
||
|
|
def result_hack(dt):
|
||
|
|
result.dispatch('on_complete')
|
||
|
|
Clock.schedule_once(result_hack)
|
||
|
|
return result
|
||
|
|
|
||
|
|
# This callback is scheduled once per frame until completed
|
||
|
|
def _recognize_tick(dt):
|
||
|
|
start_gc = result._completed
|
||
|
|
stop_now = False
|
||
|
|
|
||
|
|
while not stop_now and (tasklist and not result._break_flag) and \
|
||
|
|
(not GPF or (result._completed - start_gc < GPF)):
|
||
|
|
|
||
|
|
if (timeout and
|
||
|
|
Clock.get_time() - result._start_time >= timeout):
|
||
|
|
result.status = 'timeout'
|
||
|
|
stop_now = True
|
||
|
|
break
|
||
|
|
|
||
|
|
# Get the best distance and number of matching operations done
|
||
|
|
gesture = tasklist.popleft()
|
||
|
|
tpl, d, res, mos = gesture.match_candidate(
|
||
|
|
cand, **kwargs)
|
||
|
|
|
||
|
|
if tpl is not None:
|
||
|
|
score = result._add_result(gesture, d, tpl, res)
|
||
|
|
if goodscore is not None and score >= goodscore:
|
||
|
|
result.status = 'goodscore'
|
||
|
|
stop_now = True
|
||
|
|
|
||
|
|
result._match_ops += mos
|
||
|
|
result._completed += 1
|
||
|
|
result.dispatch('on_progress')
|
||
|
|
|
||
|
|
# The loop has ended. Prepare to dispatch 'complete'
|
||
|
|
def _dispatch():
|
||
|
|
result.dispatch('on_complete')
|
||
|
|
self.dispatch('on_search_complete', result)
|
||
|
|
return False
|
||
|
|
|
||
|
|
# Dispatch or reschedule another run
|
||
|
|
if not tasklist:
|
||
|
|
result.status = 'complete'
|
||
|
|
return _dispatch()
|
||
|
|
elif result._break_flag:
|
||
|
|
result.status = 'stop'
|
||
|
|
return _dispatch()
|
||
|
|
elif stop_now:
|
||
|
|
return _dispatch()
|
||
|
|
else:
|
||
|
|
Clock.schedule_once(_recognize_tick, delay)
|
||
|
|
return True
|
||
|
|
# End _recognize_tick()
|
||
|
|
|
||
|
|
self.dispatch('on_search_start', result)
|
||
|
|
if not GPF:
|
||
|
|
_recognize_tick(0)
|
||
|
|
else:
|
||
|
|
Clock.schedule_once(_recognize_tick, 0)
|
||
|
|
|
||
|
|
return result
|
||
|
|
|
||
|
|
def _candidate(self, strokes, **kwargs):
|
||
|
|
# recognize() helper function, do not use directly. Set up a
|
||
|
|
# Candidate object from arguments. Either use a specified object
|
||
|
|
# or make a new one from strokes and apply safe skip_* settings to
|
||
|
|
# use less resources.
|
||
|
|
if isinstance(strokes, Candidate):
|
||
|
|
return strokes
|
||
|
|
|
||
|
|
if (not isinstance(strokes, list) or not len(strokes) or not
|
||
|
|
isinstance(strokes[0], list)):
|
||
|
|
raise MultistrokeError('recognize() needs strokes= '
|
||
|
|
'list or Candidate')
|
||
|
|
|
||
|
|
cand = Candidate(strokes)
|
||
|
|
o_filter = kwargs.get('orientation_sensitive', None)
|
||
|
|
if o_filter is False:
|
||
|
|
cand.skip_bounded = True
|
||
|
|
elif o_filter is True:
|
||
|
|
cand.skip_invariant = True
|
||
|
|
|
||
|
|
return cand
|
||
|
|
|
||
|
|
# Default event handlers
|
||
|
|
def on_search_start(self, result):
|
||
|
|
pass
|
||
|
|
|
||
|
|
def on_search_complete(self, result):
|
||
|
|
pass
|
||
|
|
|
||
|
|
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
# ProgressTracker
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
|
||
|
|
class ProgressTracker(EventDispatcher):
|
||
|
|
'''Represents an ongoing (or completed) search operation. Instantiated and
|
||
|
|
returned by the :meth:`Recognizer.recognize` method when it is called. The
|
||
|
|
`results` attribute is a dictionary that is updated as the recognition
|
||
|
|
operation progresses.
|
||
|
|
|
||
|
|
.. Note ::
|
||
|
|
You do not need to instantiate this class.
|
||
|
|
|
||
|
|
:Arguments:
|
||
|
|
`candidate`
|
||
|
|
:class:`Candidate` object to be evaluated
|
||
|
|
`tasks`
|
||
|
|
Total number of gestures in tasklist (to test against)
|
||
|
|
|
||
|
|
:Events:
|
||
|
|
`on_progress`
|
||
|
|
Fired for every gesture that is processed
|
||
|
|
`on_result`
|
||
|
|
Fired when a new result is added, and it is the first match
|
||
|
|
for the `name` so far, or a consecutive match with better score.
|
||
|
|
`on_complete`
|
||
|
|
Fired when the search is completed, for whatever reason.
|
||
|
|
(use `ProgressTracker.status` to find out)
|
||
|
|
|
||
|
|
:Attributes:
|
||
|
|
`results`
|
||
|
|
A dictionary of all results (so far). The key is the name of the
|
||
|
|
gesture (ie :attr:`UnistrokeTemplate.name` usually inherited from
|
||
|
|
:class:`MultistrokeGesture`). Each item in the dictionary is a
|
||
|
|
dict with the following entries:
|
||
|
|
|
||
|
|
`name`
|
||
|
|
Name of the matched template (redundant)
|
||
|
|
`score`
|
||
|
|
Computed score from 1.0 (perfect match) to 0.0
|
||
|
|
`dist`
|
||
|
|
Cosine distance from candidate to template (low=closer)
|
||
|
|
`gesture`
|
||
|
|
The :class:`MultistrokeGesture` object that was matched
|
||
|
|
`best_template`
|
||
|
|
Index of the best matching template (in
|
||
|
|
:attr:`MultistrokeGesture.templates`)
|
||
|
|
`template_results`
|
||
|
|
List of distances for all templates. The list index
|
||
|
|
corresponds to a :class:`UnistrokeTemplate` index in
|
||
|
|
gesture.templates.
|
||
|
|
|
||
|
|
`status`
|
||
|
|
`search`
|
||
|
|
Currently working
|
||
|
|
`stop`
|
||
|
|
Was stopped by the user (:meth:`stop` called)
|
||
|
|
`timeout`
|
||
|
|
A timeout occurred (specified as `timeout=` to recognize())
|
||
|
|
`goodscore`
|
||
|
|
The search was stopped early because a gesture with a high
|
||
|
|
enough score was found (specified as `goodscore=` to
|
||
|
|
recognize())
|
||
|
|
`complete`
|
||
|
|
The search is complete (all gestures matching filters were
|
||
|
|
tested)
|
||
|
|
'''
|
||
|
|
def __init__(self, candidate, tasks, **kwargs):
|
||
|
|
self.status = 'search'
|
||
|
|
self.candidate = candidate
|
||
|
|
self.results = {}
|
||
|
|
self.tasks = tasks
|
||
|
|
self._start_time = Clock.get_time()
|
||
|
|
self._match_ops = 0
|
||
|
|
self._completed = 0
|
||
|
|
self._break_flag = False
|
||
|
|
|
||
|
|
# fired by recognize()
|
||
|
|
self.register_event_type('on_complete')
|
||
|
|
self.register_event_type('on_progress')
|
||
|
|
|
||
|
|
# fired locally
|
||
|
|
self.register_event_type('on_result')
|
||
|
|
super(ProgressTracker, self).__init__(**kwargs)
|
||
|
|
|
||
|
|
@property
|
||
|
|
def progress(self):
|
||
|
|
'''Returns the progress as a float, 0 is 0% done, 1 is 100%. This
|
||
|
|
is a Python property.'''
|
||
|
|
if not self.tasks:
|
||
|
|
return 1
|
||
|
|
return self._completed / float(self.tasks)
|
||
|
|
|
||
|
|
@property
|
||
|
|
def best(self):
|
||
|
|
'''Return the best match found by recognize() so far. It returns a
|
||
|
|
dictionary with three keys, 'name', 'dist' and 'score' representing
|
||
|
|
the template's name, distance (from candidate path) and the
|
||
|
|
computed score value. This is a Python property.'''
|
||
|
|
results = self.results # to avoid too many self. lookups
|
||
|
|
if not results:
|
||
|
|
return {'name': None, 'dist': None, 'score': 0}
|
||
|
|
b = max(results, key=lambda r: results[r]['score'])
|
||
|
|
return {
|
||
|
|
'name': results[b]['name'],
|
||
|
|
'dist': results[b]['dist'],
|
||
|
|
'score': results[b]['score']
|
||
|
|
}
|
||
|
|
|
||
|
|
def stop(self):
|
||
|
|
'''Raises a stop flag that is checked by the search process. It will
|
||
|
|
be stopped on the next clock tick (if it is still running).'''
|
||
|
|
self._break_flag = True
|
||
|
|
|
||
|
|
def _add_result(self, gesture, dist, tpl, res):
|
||
|
|
# Add a result; used internally by the recognize() function
|
||
|
|
if tpl <= len(res):
|
||
|
|
n = gesture.templates[tpl].name
|
||
|
|
else:
|
||
|
|
return 0.
|
||
|
|
|
||
|
|
if n not in self.results or dist < self.results[n]['dist']:
|
||
|
|
self.results[n] = {
|
||
|
|
'name': n,
|
||
|
|
'dist': dist,
|
||
|
|
'gesture': gesture,
|
||
|
|
'best_template': tpl,
|
||
|
|
'template_results': res
|
||
|
|
}
|
||
|
|
|
||
|
|
if not dist:
|
||
|
|
self.results[n]['score'] = 1.0
|
||
|
|
else:
|
||
|
|
self.results[n]['score'] = 1.0 - (dist / pi)
|
||
|
|
|
||
|
|
self.dispatch('on_result', self.results[n])
|
||
|
|
return self.results[n]['score']
|
||
|
|
else:
|
||
|
|
return 0.
|
||
|
|
|
||
|
|
def on_complete(self):
|
||
|
|
pass
|
||
|
|
|
||
|
|
def on_progress(self):
|
||
|
|
pass
|
||
|
|
|
||
|
|
def on_result(self, result):
|
||
|
|
pass
|
||
|
|
|
||
|
|
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
# MultistrokeGesture
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
|
||
|
|
class MultistrokeGesture(object):
|
||
|
|
''':class:`MultistrokeGesture` represents a gesture. It maintains a set of
|
||
|
|
`strokes` and generates unistroke (ie :class:`UnistrokeTemplate`)
|
||
|
|
permutations that are used for evaluating candidates against this gesture
|
||
|
|
later.
|
||
|
|
|
||
|
|
:Arguments:
|
||
|
|
`name`
|
||
|
|
Identifies the name of the gesture - it is returned to you in the
|
||
|
|
results of a :meth:`Recognizer.recognize` search. You can have any
|
||
|
|
number of MultistrokeGesture objects with the same name; many
|
||
|
|
definitions of one gesture. The same name is given to all the
|
||
|
|
generated unistroke permutations. Required, no default.
|
||
|
|
`strokes`
|
||
|
|
A list of paths that represents the gesture. A path is a list of
|
||
|
|
Vector objects::
|
||
|
|
|
||
|
|
gesture = MultistrokeGesture('my_gesture', strokes=[
|
||
|
|
[Vector(x1, y1), Vector(x2, y2), ...... ], # stroke 1
|
||
|
|
[Vector(), Vector(), Vector(), Vector() ] # stroke 2
|
||
|
|
#, [stroke 3], [stroke 4], ...
|
||
|
|
])
|
||
|
|
|
||
|
|
For template matching purposes, all the strokes are combined to a
|
||
|
|
single list (unistroke). You should still specify the strokes
|
||
|
|
individually, and set `stroke_sensitive` True (whenever possible).
|
||
|
|
|
||
|
|
Once you do this, unistroke permutations are immediately generated
|
||
|
|
and stored in `self.templates` for later, unless you set the
|
||
|
|
`permute` flag to False.
|
||
|
|
`priority`
|
||
|
|
Determines when :func:`Recognizer.recognize` will attempt to match
|
||
|
|
this template, lower priorities are evaluated first (only if
|
||
|
|
a priority `filter` is used). You should use lower priority on
|
||
|
|
gestures that are more likely to match. For example, set user
|
||
|
|
templates at lower number than generic templates. Default is 100.
|
||
|
|
`numpoints`
|
||
|
|
Determines the number of points this gesture should be resampled to
|
||
|
|
(for matching purposes). The default is 16.
|
||
|
|
`stroke_sensitive`
|
||
|
|
Determines if the number of strokes (paths) in this gesture is
|
||
|
|
required to be the same in the candidate (user input) gesture
|
||
|
|
during matching. If this is False, candidates will always be
|
||
|
|
evaluated, disregarding the number of strokes. Default is True.
|
||
|
|
`orientation_sensitive`
|
||
|
|
Determines if this gesture is orientation sensitive. If True,
|
||
|
|
aligns the indicative orientation with the one of eight base
|
||
|
|
orientations that requires least rotation. Default is True.
|
||
|
|
`angle_similarity`
|
||
|
|
This is used by the :func:`Recognizer.recognize` function when a
|
||
|
|
candidate is evaluated against this gesture. If the angles between
|
||
|
|
them are too far off, the template is considered a non-match.
|
||
|
|
Default is 30.0 (degrees)
|
||
|
|
`permute`
|
||
|
|
If False, do not use Heap Permute algorithm to generate different
|
||
|
|
stroke orders when instantiated. If you set this to False, a
|
||
|
|
single UnistrokeTemplate built from `strokes` is used.
|
||
|
|
'''
|
||
|
|
def __init__(self, name, strokes=None, **kwargs):
|
||
|
|
self.name = name
|
||
|
|
self.priority = kwargs.get('priority', 100)
|
||
|
|
self.numpoints = kwargs.get('numpoints', 16)
|
||
|
|
self.stroke_sens = kwargs.get('stroke_sensitive', True)
|
||
|
|
self.orientation_sens = kwargs.get('orientation_sensitive', True)
|
||
|
|
self.angle_similarity = kwargs.get('angle_similarity', 30.0)
|
||
|
|
self.strokes = []
|
||
|
|
|
||
|
|
if strokes is not None:
|
||
|
|
self.strokes = strokes
|
||
|
|
if kwargs.get('permute', True):
|
||
|
|
self.permute()
|
||
|
|
else:
|
||
|
|
self.templates = [UnistrokeTemplate(name,
|
||
|
|
points=[i for sub in strokes for i in sub],
|
||
|
|
numpoints=self.numpoints,
|
||
|
|
orientation_sensitive=self.orientation_sens)]
|
||
|
|
|
||
|
|
def angle_similarity_threshold(self):
|
||
|
|
return radians(self.angle_similarity)
|
||
|
|
|
||
|
|
def add_stroke(self, stroke, permute=False):
|
||
|
|
'''Add a stroke to the self.strokes list. If `permute` is True, the
|
||
|
|
:meth:`permute` method is called to generate new unistroke templates'''
|
||
|
|
self.strokes.append(stroke)
|
||
|
|
if permute:
|
||
|
|
self.permute()
|
||
|
|
|
||
|
|
def get_distance(self, cand, tpl, numpoints=None):
|
||
|
|
'''Compute the distance from this Candidate to a UnistrokeTemplate.
|
||
|
|
Returns the Cosine distance between the stroke paths.
|
||
|
|
|
||
|
|
`numpoints` will prepare both the UnistrokeTemplate and Candidate path
|
||
|
|
to n points (when necessary), you probably don't want to do this.
|
||
|
|
'''
|
||
|
|
n = numpoints
|
||
|
|
if n is None or n < 2:
|
||
|
|
n = self.numpoints
|
||
|
|
|
||
|
|
# optimal_cosine_distance() inlined here for performance
|
||
|
|
v1 = tpl.get_vector(n)
|
||
|
|
v2 = cand.get_protractor_vector(n, tpl.orientation_sens)
|
||
|
|
|
||
|
|
a = 0.0
|
||
|
|
b = 0.0
|
||
|
|
|
||
|
|
for i in xrange(0, len(v1), 2):
|
||
|
|
a += (v1[i] * v2[i]) + (v1[i + 1] * v2[i + 1])
|
||
|
|
b += (v1[i] * v2[i + 1]) - (v1[i + 1] * v2[i])
|
||
|
|
|
||
|
|
angle = atan(b / a)
|
||
|
|
|
||
|
|
# If you put the below directly into math.acos(), you will get a domain
|
||
|
|
# error when a=1.0 and angle=0.0 (ie math_cos(angle)=1.0). It seems to
|
||
|
|
# be because float representation of 1.0*1.0 is >1.0 (ie 1.00000...001)
|
||
|
|
# and this is problematic for math.acos().
|
||
|
|
# If you try math.acos(1.0*1.0) in interpreter it does not happen,
|
||
|
|
# only with exact match at runtime
|
||
|
|
result = a * math_cos(angle) + b * math_sin(angle)
|
||
|
|
|
||
|
|
# FIXME: I'm sure there is a better way to do it but..
|
||
|
|
if result >= 1:
|
||
|
|
result = 1
|
||
|
|
elif result <= -1: # has not happened to me, but I leave it here.
|
||
|
|
result = -1
|
||
|
|
return acos(result)
|
||
|
|
|
||
|
|
def match_candidate(self, cand, **kwargs):
|
||
|
|
'''Match a given candidate against this MultistrokeGesture object. Will
|
||
|
|
test against all templates and report results as a list of four
|
||
|
|
items:
|
||
|
|
|
||
|
|
`index 0`
|
||
|
|
Best matching template's index (in self.templates)
|
||
|
|
`index 1`
|
||
|
|
Computed distance from the template to the candidate path
|
||
|
|
`index 2`
|
||
|
|
List of distances for all templates. The list index
|
||
|
|
corresponds to a :class:`UnistrokeTemplate` index in
|
||
|
|
self.templates.
|
||
|
|
`index 3`
|
||
|
|
Counter for the number of performed matching operations, ie
|
||
|
|
templates matched against the candidate
|
||
|
|
'''
|
||
|
|
best_d = float('infinity')
|
||
|
|
best_tpl = None
|
||
|
|
mos = 0
|
||
|
|
out = []
|
||
|
|
|
||
|
|
if (self.stroke_sens and len(self.strokes) != len(cand.strokes)):
|
||
|
|
return (best_tpl, best_d, out, mos)
|
||
|
|
|
||
|
|
skip_bounded = cand.skip_bounded
|
||
|
|
skip_invariant = cand.skip_invariant
|
||
|
|
get_distance = self.get_distance
|
||
|
|
ang_sim_threshold = self.angle_similarity_threshold()
|
||
|
|
|
||
|
|
for idx, tpl in enumerate(self.templates):
|
||
|
|
# Handle a theoretical case where a MultistrokeGesture is composed
|
||
|
|
# manually and the orientation_sensitive flag is True, and contains
|
||
|
|
# a UnistrokeTemplate that has orientation_sensitive=False (or vice
|
||
|
|
# versa). This would cause KeyError - requesting nonexistent vector
|
||
|
|
if tpl.orientation_sens:
|
||
|
|
if skip_bounded:
|
||
|
|
continue
|
||
|
|
elif skip_invariant:
|
||
|
|
continue
|
||
|
|
|
||
|
|
# Count as a match operation now, since the call to get_
|
||
|
|
# angle_similarity below will force vector calculation,
|
||
|
|
# even if it doesn't make it to get_distance
|
||
|
|
mos += 1
|
||
|
|
|
||
|
|
# Note: With this implementation, we always resample the candidate
|
||
|
|
# to *any* encountered UnistrokeTemplate numpoints here, the filter
|
||
|
|
# is only applied to MultistrokeGesture. See theoretical case
|
||
|
|
# above; should not matter normally.
|
||
|
|
n = kwargs.get('force_numpoints', tpl.numpoints)
|
||
|
|
|
||
|
|
# Skip if candidate/gesture angles are too far off
|
||
|
|
ang_sim = cand.get_angle_similarity(tpl, numpoints=n)
|
||
|
|
if ang_sim > ang_sim_threshold:
|
||
|
|
continue
|
||
|
|
|
||
|
|
# Get the distance between cand/tpl paths
|
||
|
|
d = get_distance(cand, tpl, numpoints=n)
|
||
|
|
out.append(d)
|
||
|
|
|
||
|
|
if d < best_d:
|
||
|
|
best_d = d
|
||
|
|
best_tpl = idx
|
||
|
|
|
||
|
|
return (best_tpl, best_d, out, mos)
|
||
|
|
|
||
|
|
def permute(self):
|
||
|
|
'''Generate all possible unistroke permutations from self.strokes and
|
||
|
|
save the resulting list of UnistrokeTemplate objects in self.templates.
|
||
|
|
|
||
|
|
Quote from http://faculty.washington.edu/wobbrock/pubs/gi-10.2.pdf ::
|
||
|
|
|
||
|
|
We use Heap Permute [16] (p. 179) to generate all stroke orders
|
||
|
|
in a multistroke gesture. Then, to generate stroke directions for
|
||
|
|
each order, we treat each component stroke as a dichotomous
|
||
|
|
[0,1] variable. There are 2^N combinations for N strokes, so we
|
||
|
|
convert the decimal values 0 to 2^N-1, inclusive, to binary
|
||
|
|
representations and regard each bit as indicating forward (0) or
|
||
|
|
reverse (1). This algorithm is often used to generate truth tables
|
||
|
|
in propositional logic.
|
||
|
|
|
||
|
|
See section 4.1: "$N Algorithm" of the linked paper for details.
|
||
|
|
|
||
|
|
.. Warning ::
|
||
|
|
|
||
|
|
Using heap permute for gestures with more than 3 strokes
|
||
|
|
can result in very large number of templates (a 9-stroke
|
||
|
|
gesture = 38 million templates). If you are dealing with
|
||
|
|
these types of gestures, you should manually compose
|
||
|
|
all the desired stroke orders.
|
||
|
|
'''
|
||
|
|
# Seed with index of each stroke
|
||
|
|
self._order = [i for i in xrange(0, len(self.strokes))]
|
||
|
|
|
||
|
|
# Prepare ._orders
|
||
|
|
self._orders = []
|
||
|
|
self._heap_permute(len(self.strokes))
|
||
|
|
del self._order
|
||
|
|
|
||
|
|
# Generate unistroke permutations
|
||
|
|
self.templates = [UnistrokeTemplate(
|
||
|
|
self.name,
|
||
|
|
points=permutation,
|
||
|
|
numpoints=self.numpoints,
|
||
|
|
orientation_sensitive=self.orientation_sens
|
||
|
|
) for permutation in self._make_unistrokes()]
|
||
|
|
del self._orders
|
||
|
|
|
||
|
|
def _heap_permute(self, n):
|
||
|
|
# Heap Permute algorithm
|
||
|
|
self_order = self._order
|
||
|
|
if n == 1:
|
||
|
|
self._orders.append(self_order[:])
|
||
|
|
else:
|
||
|
|
i = 0
|
||
|
|
for i in xrange(0, n):
|
||
|
|
self._heap_permute(n - 1)
|
||
|
|
if n % 2 == 1:
|
||
|
|
tmp = self_order[0]
|
||
|
|
self_order[0] = self_order[n - 1]
|
||
|
|
self_order[n - 1] = tmp
|
||
|
|
else:
|
||
|
|
tmp = self_order[i]
|
||
|
|
self_order[i] = self_order[n - 1]
|
||
|
|
self_order[n - 1] = tmp
|
||
|
|
|
||
|
|
def _make_unistrokes(self):
|
||
|
|
# Create unistroke permutations from self.strokes
|
||
|
|
unistrokes = []
|
||
|
|
unistrokes_append = unistrokes.append
|
||
|
|
self_strokes = self.strokes
|
||
|
|
for r in self._orders:
|
||
|
|
b = 0
|
||
|
|
while b < pow(2, len(r)): # use b's bits for directions
|
||
|
|
unistroke = []
|
||
|
|
unistroke_append = unistroke.append
|
||
|
|
for i in xrange(0, len(r)):
|
||
|
|
pts = self_strokes[r[i]][:]
|
||
|
|
if (b >> i) & 1 == 1: # is b's bit at index i 1?
|
||
|
|
pts.reverse()
|
||
|
|
unistroke_append(None)
|
||
|
|
unistroke[-1:] = pts
|
||
|
|
|
||
|
|
unistrokes_append(unistroke)
|
||
|
|
b += 1
|
||
|
|
return unistrokes
|
||
|
|
|
||
|
|
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
# UnistrokeTemplate
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
|
||
|
|
class UnistrokeTemplate(object):
|
||
|
|
'''Represents a (uni)stroke path as a list of Vectors. Normally, this class
|
||
|
|
is instantiated by MultistrokeGesture and not by the programmer directly.
|
||
|
|
However, it is possible to manually compose UnistrokeTemplate objects.
|
||
|
|
|
||
|
|
:Arguments:
|
||
|
|
`name`
|
||
|
|
Identifies the name of the gesture. This is normally inherited from
|
||
|
|
the parent MultistrokeGesture object when a template is generated.
|
||
|
|
`points`
|
||
|
|
A list of points that represents a unistroke path. This is normally
|
||
|
|
one of the possible stroke order permutations from a
|
||
|
|
MultistrokeGesture.
|
||
|
|
`numpoints`
|
||
|
|
The number of points this template should (ideally) be resampled to
|
||
|
|
before the matching process. The default is 16, but you can use a
|
||
|
|
template-specific settings if that improves results.
|
||
|
|
`orientation_sensitive`
|
||
|
|
Determines if this template is orientation sensitive (True) or
|
||
|
|
fully rotation invariant (False). The default is True.
|
||
|
|
|
||
|
|
.. Note::
|
||
|
|
You will get an exception if you set a skip-flag and then attempt to
|
||
|
|
retrieve those vectors.
|
||
|
|
'''
|
||
|
|
def __init__(self, name, points=None, **kwargs):
|
||
|
|
self.name = name
|
||
|
|
self.numpoints = kwargs.get('numpoints', 16)
|
||
|
|
self.orientation_sens = kwargs.get('orientation_sensitive', True)
|
||
|
|
|
||
|
|
self.db = {}
|
||
|
|
self.points = []
|
||
|
|
|
||
|
|
if points is not None:
|
||
|
|
self.points = points
|
||
|
|
|
||
|
|
def add_point(self, p):
|
||
|
|
'''Add a point to the unistroke/path. This invalidates all previously
|
||
|
|
computed vectors.'''
|
||
|
|
self.points.append(p)
|
||
|
|
# All previously computed data is now void.
|
||
|
|
self.db = {}
|
||
|
|
|
||
|
|
# Used to lazily prepare the template
|
||
|
|
def _get_db_key(self, key, numpoints=None):
|
||
|
|
n = numpoints and numpoints or self.numpoints
|
||
|
|
if n not in self.db:
|
||
|
|
self.prepare(n)
|
||
|
|
return self.db[n][key]
|
||
|
|
|
||
|
|
def get_start_unit_vector(self, numpoints=None):
|
||
|
|
return self._get_db_key('startvector', numpoints)
|
||
|
|
|
||
|
|
def get_vector(self, numpoints=None):
|
||
|
|
return self._get_db_key('vector', numpoints)
|
||
|
|
|
||
|
|
def get_points(self, numpoints=None):
|
||
|
|
return self._get_db_key('points', numpoints)
|
||
|
|
|
||
|
|
def prepare(self, numpoints=None):
|
||
|
|
'''This function prepares the UnistrokeTemplate for matching given a
|
||
|
|
target number of points (for resample). 16 is optimal.'''
|
||
|
|
|
||
|
|
if not self.points:
|
||
|
|
raise MultistrokeError('prepare() called without self.points')
|
||
|
|
|
||
|
|
# How many points are we resampling to?
|
||
|
|
n = numpoints or self.numpoints
|
||
|
|
if not n or n < 2:
|
||
|
|
raise MultistrokeError('prepare() called with invalid numpoints')
|
||
|
|
|
||
|
|
p = resample(self.points, n)
|
||
|
|
radians = indicative_angle(p)
|
||
|
|
p = rotate_by(p, -radians)
|
||
|
|
p = scale_dim(p, SQUARESIZE, ONEDTHRESHOLD)
|
||
|
|
|
||
|
|
if self.orientation_sens:
|
||
|
|
p = rotate_by(p, +radians) # restore
|
||
|
|
|
||
|
|
p = translate_to(p, ORIGIN)
|
||
|
|
|
||
|
|
# Now store it using the number of points in the resampled path as the
|
||
|
|
# dict key. On the next call to get_*, it will be returned instead of
|
||
|
|
# recomputed. Implicitly, you must reset self.db or call prepare() for
|
||
|
|
# all the keys once you manipulate self.points.
|
||
|
|
self.db[n] = {
|
||
|
|
# Compute STARTANGLEINDEX as n/8:
|
||
|
|
'startvector': start_unit_vector(p, (n / 8)),
|
||
|
|
'vector': vectorize(p, self.orientation_sens)
|
||
|
|
}
|
||
|
|
|
||
|
|
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
# Candidate
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
|
||
|
|
class Candidate(object):
|
||
|
|
'''Represents a set of unistroke paths of user input, ie data to be matched
|
||
|
|
against a :class:`UnistrokeTemplate` object using the Protractor algorithm.
|
||
|
|
By default, data is precomputed to match both rotation bounded and fully
|
||
|
|
invariant :class:`UnistrokeTemplate` objects.
|
||
|
|
|
||
|
|
:Arguments:
|
||
|
|
`strokes`
|
||
|
|
See :data:`MultistrokeGesture.strokes` for format example. The
|
||
|
|
Candidate strokes are simply combined to a unistroke in the order
|
||
|
|
given. The idea is that this will match one of the unistroke
|
||
|
|
permutations in `MultistrokeGesture.templates`.
|
||
|
|
`numpoints`
|
||
|
|
The Candidate's default N; this is only for a fallback, it is not
|
||
|
|
normally used since n is driven by the UnistrokeTemplate we are
|
||
|
|
being compared to.
|
||
|
|
`skip_bounded`
|
||
|
|
If True, do not generate/store rotation bounded vectors
|
||
|
|
`skip_invariant`
|
||
|
|
If True, do not generate/store rotation invariant vectors
|
||
|
|
|
||
|
|
Note that you WILL get errors if you set a skip-flag and then attempt to
|
||
|
|
retrieve the data.'''
|
||
|
|
def __init__(self, strokes=None, numpoints=16, **kwargs):
|
||
|
|
self.skip_invariant = kwargs.get('skip_invariant', False)
|
||
|
|
self.skip_bounded = kwargs.get('skip_bounded', False)
|
||
|
|
|
||
|
|
self.numpoints = numpoints
|
||
|
|
self.db = {}
|
||
|
|
self.strokes = []
|
||
|
|
|
||
|
|
if strokes is not None:
|
||
|
|
self.strokes = strokes
|
||
|
|
|
||
|
|
def add_stroke(self, stroke):
|
||
|
|
'''Add a stroke to the candidate; this will invalidate all
|
||
|
|
previously computed vectors'''
|
||
|
|
self.points.append(stroke)
|
||
|
|
self.db = {}
|
||
|
|
|
||
|
|
# Used to lazily prepare the candidate
|
||
|
|
def _get_db_key(self, key, numpoints, orientation_sens):
|
||
|
|
n = numpoints and numpoints or self.numpoints
|
||
|
|
if n not in self.db:
|
||
|
|
self.prepare(n)
|
||
|
|
|
||
|
|
prefix = orientation_sens and 'bound_' or 'inv_'
|
||
|
|
return self.db[n][prefix + key]
|
||
|
|
|
||
|
|
def get_start_unit_vector(self, numpoints, orientation_sens):
|
||
|
|
'''(Internal use only) Get the start vector for this Candidate,
|
||
|
|
with the path resampled to `numpoints` points. This is the first
|
||
|
|
step in the matching process. It is compared to a
|
||
|
|
UnistrokeTemplate object's start vector to determine angle
|
||
|
|
similarity.'''
|
||
|
|
return self._get_db_key('startvector', numpoints, orientation_sens)
|
||
|
|
|
||
|
|
def get_protractor_vector(self, numpoints, orientation_sens):
|
||
|
|
'''(Internal use only) Return vector for comparing to a
|
||
|
|
UnistrokeTemplate with Protractor'''
|
||
|
|
return self._get_db_key('vector', numpoints, orientation_sens)
|
||
|
|
|
||
|
|
def get_angle_similarity(self, tpl, **kwargs):
|
||
|
|
'''(Internal use only) Compute the angle similarity between this
|
||
|
|
Candidate and a UnistrokeTemplate object. Returns a number that
|
||
|
|
represents the angle similarity (lower is more similar).'''
|
||
|
|
n = kwargs.get('numpoints', self.numpoints)
|
||
|
|
|
||
|
|
# angle_between_unit_vectors() inlined here for performance
|
||
|
|
v1x, v1y = self.get_start_unit_vector(n, tpl.orientation_sens)
|
||
|
|
v2x, v2y = tpl.get_start_unit_vector(n)
|
||
|
|
|
||
|
|
n = (v1x * v2x + v1y * v2y)
|
||
|
|
# FIXME: Domain error on float representation of 1.0 (exact match)
|
||
|
|
# (see comments in MultistrokeGesture.get_distance())
|
||
|
|
if n >= 1:
|
||
|
|
return 0.0
|
||
|
|
if n <= -1:
|
||
|
|
return pi
|
||
|
|
return acos(n)
|
||
|
|
|
||
|
|
def prepare(self, numpoints=None):
|
||
|
|
'''Prepare the Candidate vectors. self.strokes is combined to a single
|
||
|
|
unistroke (connected end-to-end), resampled to :attr:`numpoints`
|
||
|
|
points, and then the vectors are calculated and stored in self.db (for
|
||
|
|
use by `get_distance` and `get_angle_similarity`)'''
|
||
|
|
n = numpoints and numpoints or self.numpoints
|
||
|
|
|
||
|
|
# Inlined combine_strokes() for performance
|
||
|
|
points = [i for sub in self.strokes for i in sub]
|
||
|
|
points = resample(points, n)
|
||
|
|
radians = indicative_angle(points)
|
||
|
|
points = rotate_by(points, -radians)
|
||
|
|
points = scale_dim(points, SQUARESIZE, ONEDTHRESHOLD)
|
||
|
|
|
||
|
|
# Compute STARTANGLEINDEX as n / 8
|
||
|
|
angidx = n / 8
|
||
|
|
cand = {}
|
||
|
|
|
||
|
|
# full rotation invariance
|
||
|
|
if not self.skip_invariant:
|
||
|
|
inv_points = translate_to(points, ORIGIN)
|
||
|
|
cand['inv_startvector'] = start_unit_vector(inv_points, angidx)
|
||
|
|
cand['inv_vector'] = vectorize(inv_points, False)
|
||
|
|
|
||
|
|
# rotation bounded invariance
|
||
|
|
if not self.skip_bounded:
|
||
|
|
bound_points = rotate_by(points, +radians) # restore
|
||
|
|
bound_points = translate_to(bound_points, ORIGIN)
|
||
|
|
cand['bound_startvector'] = start_unit_vector(bound_points, angidx)
|
||
|
|
cand['bound_vector'] = vectorize(bound_points, True)
|
||
|
|
|
||
|
|
self.db[n] = cand
|
||
|
|
|
||
|
|
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
# Helper functions from this point on. This is all directly related to the
|
||
|
|
# recognition algorithm, and is almost 100% transcription from the JavaScript
|
||
|
|
# -----------------------------------------------------------------------------
|
||
|
|
def resample(points, n):
|
||
|
|
# Resample a path to `n` points
|
||
|
|
if not len(points) or not n or n < 2:
|
||
|
|
raise MultistrokeError('resample() called with invalid arguments')
|
||
|
|
|
||
|
|
interval = path_length(points) / (n - 1)
|
||
|
|
D = 0.0
|
||
|
|
i = 1
|
||
|
|
newpoints = [points[0]]
|
||
|
|
workpoints = points[:]
|
||
|
|
newpoints_len = 1
|
||
|
|
workpoints_len = len(points)
|
||
|
|
|
||
|
|
new_append = newpoints.append
|
||
|
|
work_insert = workpoints.insert
|
||
|
|
while i < len(workpoints):
|
||
|
|
p1 = workpoints[i - 1]
|
||
|
|
p2 = workpoints[i]
|
||
|
|
d = distance(p1, p2)
|
||
|
|
|
||
|
|
if D + d >= interval:
|
||
|
|
qx = p1[0] + ((interval - D) / d) * (p2[0] - p1[0])
|
||
|
|
qy = p1[1] + ((interval - D) / d) * (p2[1] - p1[1])
|
||
|
|
q = Vector(qx, qy)
|
||
|
|
new_append(q)
|
||
|
|
work_insert(i, q) # q is the next i
|
||
|
|
newpoints_len += 1
|
||
|
|
workpoints_len += 1
|
||
|
|
D = 0.0
|
||
|
|
else:
|
||
|
|
D += d
|
||
|
|
|
||
|
|
i += 1
|
||
|
|
|
||
|
|
# rounding error; insert the last point
|
||
|
|
if newpoints_len < n:
|
||
|
|
new_append(points[-1])
|
||
|
|
|
||
|
|
return newpoints
|
||
|
|
|
||
|
|
|
||
|
|
def indicative_angle(points):
|
||
|
|
cx, cy = centroid(points)
|
||
|
|
return atan2(cy - points[0][1], cx - points[0][0])
|
||
|
|
|
||
|
|
|
||
|
|
def rotate_by(points, radians):
|
||
|
|
# Rotate points around centroid
|
||
|
|
cx, cy = centroid(points)
|
||
|
|
cos = math_cos(radians)
|
||
|
|
sin = math_sin(radians)
|
||
|
|
newpoints = []
|
||
|
|
newpoints_append = newpoints.append
|
||
|
|
|
||
|
|
for i in xrange(0, len(points)):
|
||
|
|
qx = (points[i][0] - cx) * cos - (points[i][1] - cy) * sin + cx
|
||
|
|
qy = (points[i][0] - cx) * sin + (points[i][1] - cy) * cos + cy
|
||
|
|
newpoints_append(Vector(qx, qy))
|
||
|
|
|
||
|
|
return newpoints
|
||
|
|
|
||
|
|
|
||
|
|
def scale_dim(points, size, oneDratio):
|
||
|
|
bbox_x, bbox_y, bbox_w, bbox_h = bounding_box(points)
|
||
|
|
|
||
|
|
if bbox_h == 0 or bbox_w == 0:
|
||
|
|
raise MultistrokeError(
|
||
|
|
'scale_dim() called with invalid points: h:{}, w:{}'
|
||
|
|
.format(bbox_h, bbox_w))
|
||
|
|
|
||
|
|
# 1D or 2D gesture test
|
||
|
|
uniformly = min(bbox_w / bbox_h, bbox_h / bbox_w) <= oneDratio
|
||
|
|
|
||
|
|
if uniformly:
|
||
|
|
qx_size = size / max(bbox_w, bbox_h)
|
||
|
|
qy_size = size / max(bbox_w, bbox_h)
|
||
|
|
else:
|
||
|
|
qx_size = size / bbox_w
|
||
|
|
qy_size = size / bbox_h
|
||
|
|
|
||
|
|
newpoints = []
|
||
|
|
newpoints_append = newpoints.append
|
||
|
|
|
||
|
|
for p in points:
|
||
|
|
qx = p[0] * qx_size
|
||
|
|
qy = p[1] * qy_size
|
||
|
|
newpoints_append(Vector(qx, qy))
|
||
|
|
|
||
|
|
return newpoints
|
||
|
|
|
||
|
|
|
||
|
|
def translate_to(points, pt):
|
||
|
|
# Translate points around centroid
|
||
|
|
cx, cy = centroid(points)
|
||
|
|
ptx, pty = pt
|
||
|
|
newpoints = []
|
||
|
|
for p in points:
|
||
|
|
qx = p[0] + ptx - cx
|
||
|
|
qy = p[1] + pty - cy
|
||
|
|
newpoints.append(Vector(qx, qy))
|
||
|
|
return newpoints
|
||
|
|
|
||
|
|
|
||
|
|
def vectorize(points, use_bounded_rotation_invariance):
|
||
|
|
# Helper function for the Protractor algorithm
|
||
|
|
cos = 1.0
|
||
|
|
sin = 0.0
|
||
|
|
|
||
|
|
if use_bounded_rotation_invariance:
|
||
|
|
ang = atan2(points[0][1], points[0][0])
|
||
|
|
bo = (pi / 4.) * floor((ang + pi / 8.) / (pi / 4.))
|
||
|
|
cos = math_cos(bo - ang)
|
||
|
|
sin = math_sin(bo - ang)
|
||
|
|
|
||
|
|
sum = 0.0
|
||
|
|
vector = []
|
||
|
|
vector_len = 0
|
||
|
|
vector_append = vector.append
|
||
|
|
|
||
|
|
for px, py in points:
|
||
|
|
newx = px * cos - py * sin
|
||
|
|
newy = py * cos + px * sin
|
||
|
|
vector_append(newx)
|
||
|
|
vector_append(newy)
|
||
|
|
vector_len += 2
|
||
|
|
sum += newx ** 2 + newy ** 2
|
||
|
|
|
||
|
|
magnitude = sqrt(sum)
|
||
|
|
for i in xrange(0, vector_len):
|
||
|
|
vector[i] /= magnitude
|
||
|
|
|
||
|
|
return vector
|
||
|
|
|
||
|
|
|
||
|
|
def centroid(points):
|
||
|
|
x = 0.0
|
||
|
|
y = 0.0
|
||
|
|
points_len = len(points)
|
||
|
|
|
||
|
|
for i in xrange(0, points_len):
|
||
|
|
x += points[i][0]
|
||
|
|
y += points[i][1]
|
||
|
|
|
||
|
|
x /= points_len
|
||
|
|
y /= points_len
|
||
|
|
|
||
|
|
return Vector(x, y)
|
||
|
|
|
||
|
|
|
||
|
|
def bounding_box(points):
|
||
|
|
minx = float('infinity')
|
||
|
|
miny = float('infinity')
|
||
|
|
maxx = float('-infinity')
|
||
|
|
maxy = float('-infinity')
|
||
|
|
|
||
|
|
for px, py in points:
|
||
|
|
if px < minx:
|
||
|
|
minx = px
|
||
|
|
if px > maxx:
|
||
|
|
maxx = px
|
||
|
|
if py < miny:
|
||
|
|
miny = py
|
||
|
|
if py > maxy:
|
||
|
|
maxy = py
|
||
|
|
|
||
|
|
return (minx, miny, maxx - minx + 1, maxy - miny + 1)
|
||
|
|
|
||
|
|
|
||
|
|
def path_length(points):
|
||
|
|
d = 0.0
|
||
|
|
for i in xrange(1, len(points)):
|
||
|
|
d += distance(points[i - 1], points[i])
|
||
|
|
return d
|
||
|
|
|
||
|
|
|
||
|
|
def distance(p1, p2):
|
||
|
|
dx = p2[0] - p1[0]
|
||
|
|
dy = p2[1] - p1[1]
|
||
|
|
return sqrt(dx ** 2 + dy ** 2)
|
||
|
|
|
||
|
|
|
||
|
|
def start_unit_vector(points, index):
|
||
|
|
i = int(index)
|
||
|
|
vx, vy = points[i][0] - points[0][0], points[i][1] - points[0][1]
|
||
|
|
length = sqrt(vx ** 2 + vy ** 2)
|
||
|
|
return Vector(vx / length, vy / length)
|