vispy 0.14.0__cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

vispy/visuals/transforms/__init__.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Vispy Development Team. All Rights Reserved.
+# Distributed under the (new) BSD License. See LICENSE.txt for more info.
+"""
+Provides classes representing different transform types suitable for
+use with visuals and scenes.
+"""
+
+
+from .base_transform import BaseTransform  # noqa
+from .linear import (NullTransform, STTransform,  # noqa
+                     MatrixTransform)  # noqa
+from .nonlinear import LogTransform, PolarTransform  # noqa
+from .interactive import PanZoomTransform
+from .chain import ChainTransform  # noqa
+from ._util import arg_to_array, arg_to_vec4, as_vec4, TransformCache  # noqa
+from .transform_system import TransformSystem
+
+__all__ = ['NullTransform', 'STTransform',
+           'MatrixTransform', 'LogTransform', 'PolarTransform',
+           'ChainTransform', 'TransformSystem', 'PanZoomTransform']
+
+transform_types = {}
+for o in list(globals().values()):
+    try:
+        if issubclass(o, BaseTransform) and o is not BaseTransform:
+            name = o.__name__[:-len('Transform')].lower()
+            transform_types[name] = o
+    except TypeError:
+        continue
+
+
+def create_transform(type, *args, **kwargs):
+    return transform_types[type](*args, **kwargs)

vispy/visuals/transforms/_util.py

@@ -0,0 +1,191 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Vispy Development Team. All Rights Reserved.
+# Distributed under the (new) BSD License. See LICENSE.txt for more info.
+
+from __future__ import division
+
+import functools
+
+import numpy as np
+from ...util import logger
+from functools import wraps
+
+
+def arg_to_array(func):
+    """
+    Decorator to convert argument to array.
+
+    Parameters
+    ----------
+    func : function
+        The function to decorate.
+
+    Returns
+    -------
+    func : function
+        The decorated function.
+    """
+    @wraps(func)
+    def fn(self, arg, *args, **kwargs):
+        """Function
+
+        Parameters
+        ----------
+        arg : array-like
+            Argument to convert.
+        *args : tuple
+            Arguments.
+        **kwargs : dict
+            Keyword arguments.
+
+        Returns
+        -------
+        value : object
+            The return value of the function.
+        """
+        return func(self, np.array(arg), *args, **kwargs)
+    return fn
+
+
+def as_vec4(obj, default=(0, 0, 0, 1)):
+    """
+    Convert `obj` to 4-element vector (numpy array with shape[-1] == 4)
+
+    Parameters
+    ----------
+    obj : array-like
+        Original object.
+    default : array-like
+        The defaults to use if the object does not have 4 entries.
+
+    Returns
+    -------
+    obj : array-like
+        The object promoted to have 4 elements.
+
+    Notes
+    -----
+    `obj` will have at least two dimensions.
+
+    If `obj` has < 4 elements, then new elements are added from `default`.
+    For inputs intended as a position or translation, use default=(0,0,0,1).
+    For inputs intended as scale factors, use default=(1,1,1,1).
+
+    """
+    obj = np.atleast_2d(obj)
+    # For multiple vectors, reshape to (..., 4)
+    if obj.shape[-1] < 4:
+        new = np.empty(obj.shape[:-1] + (4,), dtype=obj.dtype)
+        new[:] = default
+        new[..., :obj.shape[-1]] = obj
+        obj = new
+    elif obj.shape[-1] > 4:
+        raise TypeError("Array shape %s cannot be converted to vec4"
+                        % (obj.shape, ))
+    return obj
+
+
+def arg_to_vec4(func):
+    """
+    Decorator for converting argument to vec4 format suitable for 4x4 matrix
+    multiplication.
+
+    [x, y]      =>  [[x, y, 0, 1]]
+
+    [x, y, z]   =>  [[x, y, z, 1]]
+
+    [[x1, y1],      [[x1, y1, 0, 1],
+     [x2, y2],  =>   [x2, y2, 0, 1],
+     [x3, y3]]       [x3, y3, 0, 1]]
+
+    If 1D input is provided, then the return value will be flattened.
+    Accepts input of any dimension, as long as shape[-1] <= 4
+
+    Alternatively, any class may define its own transform conversion interface
+    by defining a _transform_in() method that returns an array with shape
+    (.., 4), and a _transform_out() method that accepts the same array shape
+    and returns a new (mapped) object.
+
+    """
+
+    @functools.wraps(func)
+    def wrapper(self_, arg, *args, **kwargs):
+        if isinstance(arg, (tuple, list, np.ndarray)):
+            arg = np.array(arg)
+            flatten = arg.ndim == 1
+            arg = as_vec4(arg)
+
+            ret = func(self_, arg, *args, **kwargs)
+            if flatten and ret is not None:
+                return ret.flatten()
+            return ret
+        elif hasattr(arg, '_transform_in'):
+            arr = arg._transform_in()
+            ret = func(self_, arr, *args, **kwargs)
+            return arg._transform_out(ret)
+        else:
+            raise TypeError("Cannot convert argument to 4D vector: %s" % arg)
+
+    return wrapper
+
+
+class TransformCache(object):
+    """Utility class for managing a cache of ChainTransforms.
+
+    This is an LRU cache; items are removed if they are not accessed after
+    *max_age* calls to roll().
+
+    Notes
+    -----
+    This class is used by SceneCanvas to ensure that ChainTransform instances
+    are re-used across calls to draw_visual(). SceneCanvas creates one
+    TransformCache instance for each top-level visual drawn, and calls
+    roll() on each cache before drawing, which removes from the cache any
+    transforms that were not accessed during the last draw cycle.
+    """
+
+    def __init__(self, max_age=1):
+        self._cache = {}  # maps {key: [age, transform]}
+        self.max_age = max_age
+
+    def get(self, path):
+        """Get a transform from the cache that maps along *path*, which must
+        be a list of Transforms to apply in reverse order (last transform is
+        applied first).
+
+        Accessed items have their age reset to 0.
+        """
+        key = tuple(map(id, path))
+        item = self._cache.get(key, None)
+        if item is None:
+            logger.debug("Transform cache miss: %s", key)
+            item = [0, self._create(path)]
+            self._cache[key] = item
+        item[0] = 0  # reset age for this item
+
+        # make sure the chain is up to date
+        # tr = item[1]
+        # for i, node in enumerate(path[1:]):
+        #    if tr.transforms[i] is not node.transform:
+        #        tr[i] = node.transform
+
+        return item[1]
+
+    def _create(self, path):
+        # import here to avoid import cycle
+        from .chain import ChainTransform
+        return ChainTransform(path)
+
+    def roll(self):
+        """Increase the age of all items in the cache by 1. Items whose age
+        is greater than self.max_age will be removed from the cache.
+        """
+        rem = []
+        for key, item in self._cache.items():
+            if item[0] > self.max_age:
+                rem.append(key)
+            item[0] += 1
+
+        for key in rem:
+            logger.debug("TransformCache remove: %s", key)
+            del self._cache[key]

vispy/visuals/transforms/base_transform.py

@@ -0,0 +1,233 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Vispy Development Team. All Rights Reserved.
+# Distributed under the (new) BSD License. See LICENSE.txt for more info.
+
+"""
+API Issues to work out:
+
+  - MatrixTransform and STTransform both have 'scale' and 'translate'
+    attributes, but they are used in very different ways. It would be nice
+    to keep this consistent, but how?
+
+  - Need a transform.map_rect function that returns the bounding rectangle of
+    a rect after transformation. Non-linear transforms might need to work
+    harder at this, but we can provide a default implementation that
+    works by mapping a selection of points across a grid within the original
+    rect.
+"""
+
+from __future__ import division
+
+from ..shaders import Function
+from ...util.event import EventEmitter
+
+
+class BaseTransform(object):
+    """
+    BaseTransform is a base class that defines a pair of complementary
+    coordinate mapping functions in both python and GLSL.
+
+    All BaseTransform subclasses define map() and imap() methods that map
+    an object through the forward or inverse transformation, respectively.
+
+    The two class variables glsl_map and glsl_imap are instances of
+    shaders.Function that define the forward- and inverse-mapping GLSL
+    function code.
+
+    Optionally, an inverse() method returns a new transform performing the
+    inverse mapping.
+
+    Note that although all classes should define both map() and imap(), it
+    is not necessarily the case that imap(map(x)) == x; there may be instances
+    where the inverse mapping is ambiguous or otherwise meaningless.
+    """
+
+    glsl_map = None  # Must be GLSL code
+    glsl_imap = None
+
+    # Flags used to describe the transformation. Subclasses should define each
+    # as True or False.
+    # (usually used for making optimization decisions)
+
+    # If True, then for any 3 colinear points, the
+    # transformed points will also be colinear.
+    Linear = None
+
+    # The transformation's effect on one axis is independent
+    # of the input position along any other axis.
+    Orthogonal = None
+
+    # If True, then the distance between two points is the
+    # same as the distance between the transformed points.
+    NonScaling = None
+
+    # Scale factors are applied equally to all axes.
+    Isometric = None
+
+    def __init__(self):
+        self._inverse = None
+        self._dynamic = False
+        self.changed = EventEmitter(source=self, type='transform_changed')
+        if self.glsl_map is not None:
+            self._shader_map = Function(self.glsl_map)
+        if self.glsl_imap is not None:
+            self._shader_imap = Function(self.glsl_imap)
+
+    def map(self, obj):
+        """
+        Return *obj* mapped through the forward transformation.
+
+        Parameters
+        ----------
+            obj : tuple (x,y) or (x,y,z)
+                  array with shape (..., 2) or (..., 3)
+        """
+        raise NotImplementedError()
+
+    def imap(self, obj):
+        """
+        Return *obj* mapped through the inverse transformation.
+
+        Parameters
+        ----------
+            obj : tuple (x,y) or (x,y,z)
+                  array with shape (..., 2) or (..., 3)
+        """
+        raise NotImplementedError()
+
+    @property
+    def inverse(self):
+        """The inverse of this transform."""
+        if self._inverse is None:
+            self._inverse = InverseTransform(self)
+        return self._inverse
+
+    @property
+    def dynamic(self):
+        """Boolean flag that indicates whether this transform is expected to 
+        change frequently.
+
+        Transforms that are flagged as dynamic will not be collapsed in 
+        ``ChainTransform.simplified``. This allows changes to the transform
+        to propagate through the chain without requiring the chain to be
+        re-simplified.
+        """
+        return self._dynamic
+
+    @dynamic.setter
+    def dynamic(self, d):
+        self._dynamic = d
+
+    def shader_map(self):
+        """
+        Return a shader Function that accepts only a single vec4 argument
+        and defines new attributes / uniforms supplying the Function with
+        any static input.
+        """
+        return self._shader_map
+
+    def shader_imap(self):
+        """See shader_map."""
+        return self._shader_imap
+
+    def _shader_object(self):
+        """This method allows transforms to be assigned directly to shader
+        template variables. 
+
+        Example::
+
+            code = 'void main() { gl_Position = $transform($position); }'
+            func = shaders.Function(code)
+            tr = STTransform()
+            func['transform'] = tr  # use tr's forward mapping for $function
+        """
+        return self.shader_map()
+
+    def update(self, *args):
+        """Called to inform any listeners that this transform has changed."""
+        self.changed(*args)
+
+    def __mul__(self, tr):
+        """
+        Transform multiplication returns a new transform that is equivalent to
+        the two operands performed in series.
+
+        By default, multiplying two Transforms `A * B` will return
+        ChainTransform([A, B]). Subclasses may redefine this operation to
+        return more optimized results.
+
+        To ensure that both operands have a chance to simplify the operation,
+        all subclasses should follow the same procedure. For `A * B`:
+
+        1. A.__mul__(B) attempts to generate an optimized transform product.
+        2. If that fails, it must:
+
+               * return super(A).__mul__(B) OR
+               * return NotImplemented if the superclass would return an
+                 invalid result.
+
+        3. When BaseTransform.__mul__(A, B) is called, it returns 
+           NotImplemented, which causes B.__rmul__(A) to be invoked.
+        4. B.__rmul__(A) attempts to generate an optimized transform product.
+        5. If that fails, it must:
+
+               * return super(B).__rmul__(A) OR
+               * return ChainTransform([B, A]) if the superclass would return
+                 an invalid result.
+
+        6. When BaseTransform.__rmul__(B, A) is called, ChainTransform([A, B])
+           is returned.
+        """
+        # switch to __rmul__ attempts.
+        # Don't use the "return NotImplemted" trick, because that won't work if
+        # self and tr are of the same type.
+        return tr.__rmul__(self)
+
+    def __rmul__(self, tr):
+        return ChainTransform([tr, self])
+
+    def __repr__(self):
+        return "<%s at 0x%x>" % (self.__class__.__name__, id(self))
+
+    def __del__(self):
+        # we can remove ourselves from *all* events in this situation.
+        self.changed.disconnect()
+
+
+class InverseTransform(BaseTransform):
+    def __init__(self, transform):
+        BaseTransform.__init__(self)
+        self._inverse = transform
+        self.map = transform.imap
+        self.imap = transform.map
+
+    @property
+    def Linear(self):
+        return self._inverse.Linear
+
+    @property
+    def Orthogonal(self):
+        return self._inverse.Orthogonal
+
+    @property
+    def NonScaling(self):
+        return self._inverse.NonScaling
+
+    @property
+    def Isometric(self):
+        return self._inverse.Isometric
+
+    @property
+    def shader_map(self):
+        return self._inverse.shader_imap
+
+    @property
+    def shader_imap(self):
+        return self._inverse.shader_map
+
+    def __repr__(self):
+        return ("<Inverse of %r>" % repr(self._inverse))
+
+
+# import here to avoid import cycle; needed for BaseTransform.__mul__.
+from .chain import ChainTransform  # noqa