Kivy-examples 2.3.1.dev0__py3-none-any.whl

kivy/geometry.py

@@ -0,0 +1,121 @@
+'''
+Geometry utilities
+==================
+
+This module contains some helper functions for geometric calculations.
+'''
+
+__all__ = ('circumcircle', 'minimum_bounding_circle')
+
+from kivy.vector import Vector
+
+
+def circumcircle(a, b, c):
+    '''
+    Computes the circumcircle of a triangle defined by a, b, c.
+    See: http://en.wikipedia.org/wiki/Circumscribed_circle
+
+    :Parameters:
+        `a`: iterable containing at least 2 values (for x and y)
+            The 1st point of the triangle.
+        `b`: iterable containing at least 2 values (for x and y)
+            The 2nd point of the triangle.
+        `c`: iterable containing at least 2 values (for x and y)
+            The 3rd point of the triangle.
+
+    :Return:
+        A tuple that defines the circle :
+         * The first element in the returned tuple is the center as (x, y)
+         * The second is the radius (float)
+    '''
+    P = Vector(a[0], a[1])
+    Q = Vector(b[0], b[1])
+    R = Vector(c[0], c[1])
+
+    mPQ = (P + Q) * .5
+    mQR = (Q + R) * .5
+
+    numer = -(- mPQ.y * R.y + mPQ.y * Q.y + mQR.y * R.y - mQR.y * Q.y -
+              mPQ.x * R.x + mPQ.x * Q.x + mQR.x * R.x - mQR.x * Q.x)
+    denom = (-Q.x * R.y + P.x * R.y - P.x * Q.y +
+             Q.y * R.x - P.y * R.x + P.y * Q.x)
+
+    t = numer / denom
+
+    cx = -t * (Q.y - P.y) + mPQ.x
+    cy = t * (Q.x - P.x) + mPQ.y
+
+    return ((cx, cy), (P - (cx, cy)).length())
+
+
+def minimum_bounding_circle(points):
+    '''
+    Returns the minimum bounding circle for a set of points.
+
+    For a description of the problem being solved, see the `Smallest Circle
+    Problem <http://en.wikipedia.org/wiki/Smallest_circle_problem>`_.
+
+    The function uses Applet's Algorithm, the runtime is ``O(h^3, *n)``,
+    where h is the number of points in the convex hull of the set of points.
+    **But** it runs in linear time in almost all real world cases.
+    See: http://tinyurl.com/6e4n5yb
+
+    :Parameters:
+        `points`: iterable
+            A list of points (2 tuple with x,y coordinates)
+
+    :Return:
+        A tuple that defines the circle:
+            * The first element in the returned tuple is the center (x, y)
+            * The second the radius (float)
+
+    '''
+    points = [Vector(p[0], p[1]) for p in points]
+
+    if len(points) == 1:
+        return (points[0].x, points[0].y), 0.0
+
+    if len(points) == 2:
+        p1, p2 = points
+        return (p1 + p2) * .5, ((p1 - p2) * .5).length()
+
+    # determine a point P with the smallest y value
+    P = min(points, key=lambda p: p.y)
+
+    # find a point Q such that the angle of the line segment
+    # PQ with the x axis is minimal
+    def x_axis_angle(q):
+        if q == P:
+            return 1e10  # max val if the same, to skip
+        return abs((q - P).angle((1, 0)))
+    Q = min(points, key=x_axis_angle)
+
+    for p in points:
+        # find R such that angle PRQ is minimal
+        def angle_pq(r):
+            if r in (P, Q):
+                return 1e10  # max val if the same, to skip
+            return abs((r - P).angle(r - Q))
+        R = min(points, key=angle_pq)
+
+        # check for case 1 (angle PRQ is obtuse), the circle is determined
+        # by two points, P and Q. radius = |(P-Q)/2|, center = (P+Q)/2
+        if angle_pq(R) > 90.0:
+            return (P + Q) * .5, ((P - Q) * .5).length()
+
+        # if angle RPQ is obtuse, make P = R, and try again
+        if abs((R - P).angle(Q - P)) > 90:
+            P = R
+            continue
+
+        # if angle PQR is obtuse, make Q = R, and try again
+        if abs((P - Q).angle(R - Q)) > 90:
+            Q = R
+            continue
+
+        # all angles were acute..we just need the circle through the
+        # two points furthest apart!
+        break
+
+    # find the circumcenter for triangle given by P,Q,R
+    return circumcircle(P, Q, R)

kivy/gesture.py

@@ -0,0 +1,424 @@
+'''
+Gesture recognition
+===================
+
+This class allows you to easily create new
+gestures and compare them::
+
+    from kivy.gesture import Gesture, GestureDatabase
+
+    # Create a gesture
+    g = Gesture()
+    g.add_stroke(point_list=[(1,1), (3,4), (2,1)])
+    g.normalize()
+
+    # Add it to the database
+    gdb = GestureDatabase()
+    gdb.add_gesture(g)
+
+    # And for the next gesture, try to find it!
+    g2 = Gesture()
+    # ...
+    gdb.find(g2)
+
+.. warning::
+
+   You don't really want to do this: it's more of an example of how
+   to construct gestures dynamically. Typically, you would
+   need a lot more points, so it's better to record gestures in a file and
+   reload them to compare later. Look in the examples/gestures directory for
+   an example of how to do that.
+
+'''
+
+__all__ = ('Gesture', 'GestureDatabase', 'GesturePoint', 'GestureStroke')
+
+import pickle
+import base64
+import zlib
+import math
+
+from kivy.vector import Vector
+
+from io import BytesIO
+
+
+class GestureDatabase(object):
+    '''Class to handle a gesture database.'''
+
+    def __init__(self):
+        self.db = []
+
+    def add_gesture(self, gesture):
+        '''Add a new gesture to the database.'''
+        self.db.append(gesture)
+
+    def find(self, gesture, minscore=0.9, rotation_invariant=True):
+        '''Find a matching gesture in the database.'''
+        if not gesture:
+            return
+
+        best = None
+        bestscore = minscore
+        for g in self.db:
+            score = g.get_score(gesture, rotation_invariant)
+            if score < bestscore:
+                continue
+            bestscore = score
+            best = g
+        if not best:
+            return
+        return (bestscore, best)
+
+    def gesture_to_str(self, gesture):
+        '''Convert a gesture into a unique string.'''
+        io = BytesIO()
+        p = pickle.Pickler(io)
+        p.dump(gesture)
+        data = base64.b64encode(zlib.compress(io.getvalue(), 9))
+        return data
+
+    def str_to_gesture(self, data):
+        '''Convert a unique string to a gesture.'''
+        io = BytesIO(zlib.decompress(base64.b64decode(data)))
+        p = pickle.Unpickler(io)
+        gesture = p.load()
+        return gesture
+
+
+class GesturePoint:
+
+    def __init__(self, x, y):
+        '''Stores the x,y coordinates of a point in the gesture.'''
+        self.x = float(x)
+        self.y = float(y)
+
+    def scale(self, factor):
+        ''' Scales the point by the given factor.'''
+        self.x *= factor
+        self.y *= factor
+        return self
+
+    def __repr__(self):
+        return 'Mouse_point: %f,%f' % (self.x, self.y)
+
+
+class GestureStroke:
+    ''' Gestures can be made up of multiple strokes.'''
+
+    def __init__(self):
+        ''' A stroke in the gesture.'''
+        self.points = list()
+        self.screenpoints = list()
+
+    # These return the min and max coordinates of the stroke
+    @property
+    def max_x(self):
+        if len(self.points) == 0:
+            return 0
+        return max(self.points, key=lambda pt: pt.x).x
+
+    @property
+    def min_x(self):
+        if len(self.points) == 0:
+            return 0
+        return min(self.points, key=lambda pt: pt.x).x
+
+    @property
+    def max_y(self):
+        if len(self.points) == 0:
+            return 0
+        return max(self.points, key=lambda pt: pt.y).y
+
+    @property
+    def min_y(self):
+        if len(self.points) == 0:
+            return 0
+        return min(self.points, key=lambda pt: pt.y).y
+
+    def add_point(self, x, y):
+        '''
+        add_point(x=x_pos, y=y_pos)
+        Adds a point to the stroke.
+        '''
+        self.points.append(GesturePoint(x, y))
+        self.screenpoints.append((x, y))
+
+    def scale_stroke(self, scale_factor):
+        '''
+        scale_stroke(scale_factor=float)
+        Scales the stroke down by scale_factor.
+        '''
+        self.points = [pt.scale(scale_factor) for pt in self.points]
+
+    def points_distance(self, point1, point2):
+        '''
+        points_distance(point1=GesturePoint, point2=GesturePoint)
+        Returns the distance between two GesturePoints.
+        '''
+        x = point1.x - point2.x
+        y = point1.y - point2.y
+        return math.sqrt(x * x + y * y)
+
+    def stroke_length(self, point_list=None):
+        '''Finds the length of the stroke. If a point list is given,
+           finds the length of that list.
+        '''
+        if point_list is None:
+            point_list = self.points
+        gesture_length = 0.0
+        if len(point_list) <= 1:  # If there is only one point -> no length
+            return gesture_length
+        for i in range(len(point_list) - 1):
+            gesture_length += self.points_distance(
+                point_list[i], point_list[i + 1])
+        return gesture_length
+
+    def normalize_stroke(self, sample_points=32):
+        '''Normalizes strokes so that every stroke has a standard number of
+           points. Returns True if stroke is normalized, False if it can't be
+           normalized. sample_points controls the resolution of the stroke.
+        '''
+        # If there is only one point or the length is 0, don't normalize
+        if len(self.points) <= 1 or self.stroke_length(self.points) == 0.0:
+            return False
+
+        # Calculate how long each point should be in the stroke
+        target_stroke_size = \
+            self.stroke_length(self.points) / float(sample_points)
+        new_points = list()
+        new_points.append(self.points[0])
+
+        # We loop on the points
+        prev = self.points[0]
+        src_distance = 0.0
+        dst_distance = target_stroke_size
+        for curr in self.points[1:]:
+            d = self.points_distance(prev, curr)
+            if d > 0:
+                prev = curr
+                src_distance = src_distance + d
+
+                # The new point need to be inserted into the
+                # segment [prev, curr]
+                while dst_distance < src_distance:
+                    x_dir = curr.x - prev.x
+                    y_dir = curr.y - prev.y
+                    ratio = (src_distance - dst_distance) / d
+                    to_x = x_dir * ratio + prev.x
+                    to_y = y_dir * ratio + prev.y
+                    new_points.append(GesturePoint(to_x, to_y))
+                    dst_distance = self.stroke_length(self.points) / \
+                        float(sample_points) * len(new_points)
+
+        # If this happens, we are into troubles...
+        if not len(new_points) == sample_points:
+            raise ValueError('Invalid number of strokes points; got '
+                             '%d while it should be %d' %
+                             (len(new_points), sample_points))
+
+        self.points = new_points
+        return True
+
+    def center_stroke(self, offset_x, offset_y):
+        '''Centers the stroke by offsetting the points.'''
+        for point in self.points:
+            point.x -= offset_x
+            point.y -= offset_y
+
+
+class Gesture:
+    '''A python implementation of a gesture recognition algorithm by
+    Oleg Dopertchouk: http://www.gamedev.net/reference/articles/article2039.asp
+
+    Implemented by Jeiel Aranal (chemikhazi@gmail.com),
+    released into the public domain.
+    '''
+
+    # Tolerance for evaluation using the '==' operator
+    DEFAULT_TOLERANCE = 0.1
+
+    def __init__(self, tolerance=None):
+        '''
+        Gesture([tolerance=float])
+        Creates a new gesture with an optional matching tolerance value.
+        '''
+        self.width = 0.
+        self.height = 0.
+        self.gesture_product = 0.
+        self.strokes = list()
+        if tolerance is None:
+            self.tolerance = Gesture.DEFAULT_TOLERANCE
+        else:
+            self.tolerance = tolerance
+
+    def _scale_gesture(self):
+        ''' Scales down the gesture to a unit of 1.'''
+        # map() creates a list of min/max coordinates of the strokes
+        # in the gesture and min()/max() pulls the lowest/highest value
+        min_x = min([stroke.min_x for stroke in self.strokes])
+        max_x = max([stroke.max_x for stroke in self.strokes])
+        min_y = min([stroke.min_y for stroke in self.strokes])
+        max_y = max([stroke.max_y for stroke in self.strokes])
+        x_len = max_x - min_x
+        self.width = x_len
+        y_len = max_y - min_y
+        self.height = y_len
+        scale_factor = max(x_len, y_len)
+        if scale_factor <= 0.0:
+            return False
+        scale_factor = 1.0 / scale_factor
+        for stroke in self.strokes:
+            stroke.scale_stroke(scale_factor)
+        return True
+
+    def _center_gesture(self):
+        ''' Centers the Gesture.points of the gesture.'''
+        total_x = 0.0
+        total_y = 0.0
+        total_points = 0
+
+        for stroke in self.strokes:
+            # adds up all the points inside the stroke
+            stroke_y = sum([pt.y for pt in stroke.points])
+            stroke_x = sum([pt.x for pt in stroke.points])
+            total_y += stroke_y
+            total_x += stroke_x
+            total_points += len(stroke.points)
+        if total_points == 0:
+            return False
+        # Average to get the offset
+        total_x /= total_points
+        total_y /= total_points
+        # Apply the offset to the strokes
+        for stroke in self.strokes:
+            stroke.center_stroke(total_x, total_y)
+        return True
+
+    def add_stroke(self, point_list=None):
+        '''Adds a stroke to the gesture and returns the Stroke instance.
+           Optional point_list argument is a list of the mouse points for
+           the stroke.
+        '''
+        self.strokes.append(GestureStroke())
+        if isinstance(point_list, list) or isinstance(point_list, tuple):
+            for point in point_list:
+                if isinstance(point, GesturePoint):
+                    self.strokes[-1].points.append(point)
+                elif isinstance(point, list) or isinstance(point, tuple):
+                    if len(point) != 2:
+                        raise ValueError("Stroke entry must have 2 values max")
+                    self.strokes[-1].add_point(point[0], point[1])
+                else:
+                    raise TypeError("The point list should either be "
+                                    "tuples of x and y or a list of "
+                                    "GesturePoint objects")
+        elif point_list is not None:
+            raise ValueError("point_list should be a tuple/list")
+        return self.strokes[-1]
+
+    def normalize(self, stroke_samples=32):
+        '''Runs the gesture normalization algorithm and calculates the dot
+        product with self.
+        '''
+        if not self._scale_gesture() or not self._center_gesture():
+            self.gesture_product = False
+            return False
+        for stroke in self.strokes:
+            stroke.normalize_stroke(stroke_samples)
+        self.gesture_product = self.dot_product(self)
+
+    def get_rigid_rotation(self, dstpts):
+        '''
+        Extract the rotation to apply to a group of points to minimize the
+        distance to a second group of points. The two groups of points are
+        assumed to be centered. This is a simple version that just picks
+        an angle based on the first point of the gesture.
+        '''
+        if len(self.strokes) < 1 or len(self.strokes[0].points) < 1:
+            return 0
+        if len(dstpts.strokes) < 1 or len(dstpts.strokes[0].points) < 1:
+            return 0
+        p = dstpts.strokes[0].points[0]
+        target = Vector([p.x, p.y])
+        source = Vector([p.x, p.y])
+        return source.angle(target)
+
+    def dot_product(self, comparison_gesture):
+        ''' Calculates the dot product of the gesture with another gesture.'''
+        if len(comparison_gesture.strokes) != len(self.strokes):
+            return -1
+        if getattr(comparison_gesture, 'gesture_product', True) is False or \
+           getattr(self, 'gesture_product', True) is False:
+            return -1
+        dot_product = 0.0
+        for stroke_index, (my_stroke, cmp_stroke) in enumerate(
+                list(zip(self.strokes, comparison_gesture.strokes))):
+            for pt_index, (my_point, cmp_point) in enumerate(
+                    list(zip(my_stroke.points, cmp_stroke.points))):
+                dot_product += (my_point.x * cmp_point.x +
+                                my_point.y * cmp_point.y)
+        return dot_product
+
+    def rotate(self, angle):
+        g = Gesture()
+        for stroke in self.strokes:
+            tmp = []
+            for j in stroke.points:
+                v = Vector([j.x, j.y]).rotate(angle)
+                tmp.append(v)
+            g.add_stroke(tmp)
+        g.gesture_product = g.dot_product(g)
+        return g
+
+    def get_score(self, comparison_gesture, rotation_invariant=True):
+        ''' Returns the matching score of the gesture against another gesture.
+        '''
+        if isinstance(comparison_gesture, Gesture):
+            if rotation_invariant:
+                # get orientation
+                angle = self.get_rigid_rotation(comparison_gesture)
+
+                # rotate the gesture to be in the same frame.
+                comparison_gesture = comparison_gesture.rotate(angle)
+
+            # this is the normal "orientation" code.
+            score = self.dot_product(comparison_gesture)
+            if score <= 0:
+                return score
+            score /= math.sqrt(
+                self.gesture_product * comparison_gesture.gesture_product)
+            return score
+
+    def __eq__(self, comparison_gesture):
+        ''' Allows easy comparisons between gesture instances.'''
+        if isinstance(comparison_gesture, Gesture):
+            # If the gestures don't have the same number of strokes, its
+            # definitely not the same gesture
+            score = self.get_score(comparison_gesture)
+            if (score > (1.0 - self.tolerance) and
+                    score < (1.0 + self.tolerance)):
+                return True
+            else:
+                return False
+        else:
+            return NotImplemented
+
+    def __ne__(self, comparison_gesture):
+        result = self.__eq__(comparison_gesture)
+        if result is NotImplemented:
+            return result
+        else:
+            return not result
+
+    def __lt__(self, comparison_gesture):
+        raise TypeError("Gesture cannot be evaluated with <")
+
+    def __gt__(self, comparison_gesture):
+        raise TypeError("Gesture cannot be evaluated with >")
+
+    def __le__(self, comparison_gesture):
+        raise TypeError("Gesture cannot be evaluated with <=")
+
+    def __ge__(self, comparison_gesture):
+        raise TypeError("Gesture cannot be evaluated with >=")

kivy/graphics/__init__.py

@@ -0,0 +1,126 @@
+'''
+Graphics
+========
+
+This package assembles many low level functions used for drawing. The whole
+graphics package is compatible with OpenGL ES 2.0 and has many rendering
+optimizations.
+
+The basics
+----------
+
+For drawing on a screen, you will need :
+
+    1. a :class:`~kivy.graphics.instructions.Canvas` object.
+    2. :class:`~kivy.graphics.instructions.Instruction` objects.
+
+Each :class:`~kivy.uix.widget.Widget`
+in Kivy already has a :class:`Canvas` by default. When you create
+a widget, you can create all the instructions needed for drawing. If
+`self` is your current widget, you can do::
+
+    from kivy.graphics import *
+    with self.canvas:
+        # Add a red color
+        Color(1., 0, 0)
+
+        # Add a rectangle
+        Rectangle(pos=(10, 10), size=(500, 500))
+
+The instructions :class:`Color` and :class:`Rectangle` are automatically added
+to the canvas object and will be used when the window is drawn.
+
+.. note::
+
+    Kivy drawing instructions are not automatically relative to the position
+    or size of the widget. You, therefore, need to consider these factors when
+    drawing. In order to make your drawing instructions relative to the widget,
+    the instructions need either to be
+    declared in the :mod:`KvLang <kivy.lang>` or bound to pos and size changes.
+    Please see :ref:`adding_widget_background` for more detail.
+
+GL Reloading mechanism
+----------------------
+
+.. versionadded:: 1.2.0
+
+During the lifetime of the application, the OpenGL context might be lost. This
+happens:
+
+- when the window is resized on OS X or the Windows platform and you're
+  using pygame as a window provider. This is due to SDL 1.2. In the SDL 1.2
+  design, it needs to recreate a GL context everytime the window is
+  resized. This was fixed in SDL 1.3 but pygame is not yet available on it
+  by default.
+
+- when Android releases the app resources: when your application goes to the
+  background, Android might reclaim your opengl context to give the
+  resource to another app. When the user switches back to your application, a
+  newly created gl context is given to your app.
+
+Starting from 1.2.0, we have introduced a mechanism for reloading all the
+graphics resources using the GPU: Canvas, FBO, Shader, Texture, VBO,
+and VertexBatch:
+
+- VBO and VertexBatch are constructed by our graphics instructions. We have all
+  the data needed to reconstruct when reloading.
+
+- Shader: same as VBO, we store the source and values used in the
+  shader so we are able to recreate the vertex/fragment/program.
+
+- Texture: if the texture has a source (an image file or atlas), the image
+  is reloaded from the source and reuploaded to the GPU.
+
+You should cover these cases yourself:
+
+- Textures without a source: if you manually created a texture and manually
+  blit data / a buffer to it, you must handle the reloading yourself. Check the
+  :doc:`api-kivy.graphics.texture` to learn how to manage that case. (The text
+  rendering already generates the texture and handles the reloading. You
+  don't need to reload text yourself.)
+
+- FBO: if you added / removed / drew things multiple times on the FBO, we
+  can't reload it. We don't keep a history of the instructions put on it.
+  As for textures without a source, check the :doc:`api-kivy.graphics.fbo` to
+  learn how to manage that case.
+
+'''
+
+from kivy.graphics.instructions import Callback, Canvas, CanvasBase, \
+    ContextInstruction, Instruction, InstructionGroup, RenderContext, \
+    VertexInstruction
+from kivy.graphics.context_instructions import BindTexture, Color, \
+    PushState, ChangeState, PopState, MatrixInstruction, ApplyContextMatrix, \
+    PopMatrix, PushMatrix, Rotate, Scale, Translate, LoadIdentity, \
+    UpdateNormalMatrix, gl_init_resources
+from kivy.graphics.vertex_instructions import Bezier, BorderImage, Ellipse, \
+    GraphicException, Line, Mesh, Point, Quad, Rectangle, RoundedRectangle, \
+    Triangle, SmoothLine, SmoothRectangle, SmoothEllipse, \
+    SmoothRoundedRectangle, SmoothQuad, SmoothTriangle
+from kivy.graphics.stencil_instructions import StencilPop, StencilPush, \
+    StencilUse, StencilUnUse
+from kivy.graphics.gl_instructions import ClearColor, ClearBuffers
+from kivy.graphics.fbo import Fbo
+from kivy.graphics.boxshadow import BoxShadow
+from kivy.graphics.scissor_instructions import ScissorPush, ScissorPop
+
+# very hacky way to avoid pyflakes warning...
+__all__ = (Bezier.__name__, BindTexture.__name__, BorderImage.__name__,
+           Callback.__name__, Canvas.__name__, CanvasBase.__name__,
+           Color.__name__, ContextInstruction.__name__,
+           Ellipse.__name__, Fbo.__name__, GraphicException.__name__,
+           Instruction.__name__, InstructionGroup.__name__,
+           Line.__name__, SmoothLine.__name__, MatrixInstruction.__name__,
+           Mesh.__name__, Point.__name__, PopMatrix.__name__,
+           PushMatrix.__name__, Quad.__name__, Rectangle.__name__,
+           RenderContext.__name__, Rotate.__name__, Scale.__name__,
+           StencilPop.__name__, StencilPush.__name__, StencilUse.__name__,
+           StencilUnUse.__name__, Translate.__name__, Triangle.__name__,
+           VertexInstruction.__name__, ClearColor.__name__,
+           ClearBuffers.__name__, gl_init_resources.__name__,
+           PushState.__name__, ChangeState.__name__, PopState.__name__,
+           ApplyContextMatrix.__name__, UpdateNormalMatrix.__name__,
+           LoadIdentity.__name__, BoxShadow.__name__, SmoothEllipse.__name__,
+           SmoothRoundedRectangle.__name__, SmoothRectangle.__name__,
+           SmoothQuad.__name__, SmoothTriangle.__name__,
+           )