vispy 0.15.0__cp313-cp313-win_amd64.whl

vispy/scene/node.py

@@ -0,0 +1,644 @@
+# -*- 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 weakref
+from contextlib import contextmanager
+
+from ..util.event import Event, EmitterGroup
+from ..visuals.transforms import (NullTransform, BaseTransform, 
+                                  ChainTransform, create_transform,
+                                  TransformSystem)
+
+
+class Node(object):
+    """Base class representing an object in a scene.
+
+    A group of nodes connected through parent-child relationships define a 
+    scenegraph. Nodes may have any number of children.
+
+    Each Node defines a ``transform`` property, which describes the position,
+    orientation, scale, etc. of the Node relative to its parent. The Node's
+    children inherit this property, and then further apply their own
+    transformations on top of that. 
+
+    With the ``transform`` property, each Node implicitly defines a "local" 
+    coordinate system, and the Nodes and edges in the scenegraph can be thought
+    of as coordinate systems connected by transformation functions.
+
+    Parameters
+    ----------
+    parent : Node
+        The parent of the Node.
+    name : str
+        The name used to identify the node.
+    transforms : instance of TransformSystem | None
+        The associated transforms.
+    """
+
+    # Needed to allow subclasses to repr() themselves before Node.__init__()
+    _name = None
+
+    def __init__(self, parent=None, name=None, transforms=None):
+        self.name = name
+        self._visible = True
+        self._canvas = None
+        self._document_node = None
+        self._scene_node = None
+        self._opacity = 1.0
+        self._order = 0
+        self._picking = False
+
+        # clippers inherited from parents
+        self._clippers = weakref.WeakKeyDictionary()  # {node: clipper}
+
+        # whether this widget should clip its children
+        self._clip_children = False
+        self._clipper = None
+
+        self.transforms = (TransformSystem() if transforms is None else 
+                           transforms)
+
+        # Add some events to the emitter groups:
+        events = ['canvas_change', 'parent_change', 'children_change', 
+                  'transform_change', 'mouse_press', 'mouse_move',
+                  'mouse_release', 'mouse_wheel', 'key_press', 'key_release',
+                  'gesture_zoom', 'gesture_rotate']
+        # Create event emitter if needed (in subclasses that inherit from
+        # Visual, we already have an emitter to share)
+        if not hasattr(self, 'events'):
+            self.events = EmitterGroup(source=self, auto_connect=True,
+                                       update=Event)
+        self.events.add(**dict([(ev, Event) for ev in events]))
+
+        self._children = []
+        self._transform = NullTransform()
+        self._parent = None
+        if parent is not None:
+            self.parent = parent
+
+        self._document = None
+
+    @property
+    def visible(self):
+        """Whether this node should be drawn or not. Only applicable to
+        nodes that can be drawn.
+        """
+        return self._visible
+
+    @visible.setter
+    def visible(self, val):
+        self._visible = bool(val)
+        self.update()
+
+    @property
+    def name(self):
+        return self._name
+
+    @name.setter
+    def name(self, n):
+        self._name = n
+
+    @property
+    def opacity(self):
+        return self._opacity
+
+    @opacity.setter
+    def opacity(self, o):
+        self._opacity = o
+        self._update_opacity()
+
+    def _update_opacity(self):
+        pass
+
+    def _set_clipper(self, node, clipper):
+        """Assign a clipper that is inherited from a parent node.
+
+        If *clipper* is None, then remove any clippers for *node*.
+        """
+        pass
+
+    @property
+    def clip_children(self):
+        """Boolean indicating whether children of this node will inherit its
+        clipper.
+        """
+        return self._clip_children
+
+    @clip_children.setter
+    def clip_children(self, clip):
+        if self._clip_children == clip:
+            return
+        self._clip_children = clip
+
+        for ch in self.children:
+            ch._set_clipper(self, self.clipper) 
+
+    @property
+    def clipper(self):
+        """A visual filter that can be used to clip visuals to the boundaries
+        of this node.
+        """
+        return self._clipper
+
+    @property
+    def order(self):
+        """A value used to determine the order in which nodes are drawn.
+
+        Greater values are drawn later. Children are always drawn after their
+        parent.
+        """
+        return self._order
+
+    @order.setter
+    def order(self, o):
+        self._order = o
+        self.update()
+
+    @property
+    def children(self):
+        """A copy of the list of children of this node. Do not add
+        items to this list, but use ``x.parent = y`` instead.
+        """
+        return list(self._children)
+
+    @property
+    def parent(self):
+        """The parent of this node in the scenegraph.
+
+        Nodes inherit coordinate transformations and some filters (opacity and
+        clipping by default) from their parents. Setting this property assigns
+        a new parent, changing the topology of the scenegraph.
+
+        May be set to None to remove this node (and its children) from a
+        scenegraph.
+        """
+        if self._parent is None:
+            return None
+        else:
+            return self._parent()
+
+    @parent.setter
+    def parent(self, parent):
+        if not isinstance(parent, (Node, type(None))):
+            raise ValueError('Parent must be Node instance or None (got %s).'
+                             % parent.__class__.__name__)
+        prev = self.parent
+        if parent is prev:
+            return
+        if prev is not None:
+            prev._remove_child(self)
+            # remove all clippers inherited from parents
+            for k in list(self._clippers):
+                self._set_clipper(k, None)
+        if parent is None:
+            self._set_canvas(None)
+            self._parent = None
+        else:
+            self._set_canvas(parent.canvas)
+            self._parent = weakref.ref(parent)
+            parent._add_child(self)
+            # inherit clippers from parents
+            p = parent
+            while p is not None:
+                if p.clip_children:
+                    self._set_clipper(p, p.clipper)
+                p = p.parent
+
+        self.events.parent_change(new=parent, old=prev)
+        self._update_trsys(None)
+        self.update()
+
+    def _add_child(self, node):
+        self._children.append(node)
+        self.events.children_change(added=node)
+        node.events.children_change.connect(self.events.children_change)
+        self.events.parent_change.connect(node.events.parent_change)
+
+    def _remove_child(self, node):
+        self._children.remove(node)
+        self.events.children_change(removed=node)
+        node.events.children_change.disconnect(self.events.children_change)
+        self.events.parent_change.disconnect(node.events.parent_change)
+
+    def on_parent_change(self, event):
+        """Parent change event handler
+
+        Parameters
+        ----------
+        event : instance of Event
+            The event.
+        """
+        self._scene_node = None
+
+    def is_child(self, node):
+        """Check if a node is a child of the current node
+
+        Parameters
+        ----------
+        node : instance of Node
+            The potential child.
+
+        Returns
+        -------
+        child : bool
+            Whether or not the node is a child.
+        """
+        if node in self.children:
+            return True
+        for c in self.children:
+            if c.is_child(node):
+                return True
+        return False
+
+    @property
+    def canvas(self):
+        """The canvas in which this node's scenegraph is being drawn."""
+        if self._canvas is None:
+            return None
+        else:
+            return self._canvas()
+
+    @property
+    def document_node(self):
+        """The node to be used as the document coordinate system.
+
+        By default, the document node is `self.root_node`.
+        """
+        if self._document_node is None:
+            return self.root_node
+        return self._document_node
+
+    @document_node.setter
+    def document_node(self, doc):
+        self._document_node = doc
+        self._update_transform()
+
+    @property
+    def scene_node(self):
+        """The first ancestor of this node that is a SubScene instance, or self
+        if no such node exists.
+        """
+        if self._scene_node is None:
+            from .subscene import SubScene
+            p = self.parent
+            while True:
+                if isinstance(p, SubScene) or p is None:
+                    self._scene_node = p and weakref.ref(p)
+                    break
+                p = p.parent
+            if self._scene_node is None:
+                self._scene_node = weakref.ref(self)
+        return self._scene_node()
+
+    @property
+    def root_node(self):
+        node = self
+        while True:
+            p = node.parent
+            if p is None:
+                return node
+            node = p
+
+    def _set_canvas(self, c):
+        old = self.canvas
+        if old is c:
+            return
+
+        # Use canvas/framebuffer transforms from canvas
+        self.transforms.canvas = c
+        if c is None:
+            self._canvas = None
+        else:
+            self._canvas = weakref.ref(c)
+            tr = c.transforms
+            self.transforms.canvas_transform = tr.canvas_transform
+            self.transforms.framebuffer_transform = tr.framebuffer_transform
+
+        # update all children
+        for ch in self.children:
+            ch._set_canvas(c)
+
+        self.events.canvas_change(old=old, new=c)
+
+    def update(self):
+        """
+        Emit an event to inform listeners that properties of this Node have
+        changed. Also request a canvas update.
+        """
+        self.events.update()
+        c = getattr(self, 'canvas', None)
+        if c is not None:
+            c.update(node=self)
+
+    @property
+    def document(self):
+        """The document is an optional property that is an node representing
+        the coordinate system from which this node should make physical 
+        measurements such as px, mm, pt, in, etc. This coordinate system 
+        should be used when determining line widths, font sizes, and any
+        other lengths specified in physical units.
+
+        The default is None; in this case, a default document is used during
+        drawing (usually this is supplied by the SceneCanvas).
+        """
+        return self._document
+
+    @document.setter
+    def document(self, doc):
+        if doc is not None and not isinstance(doc, Node):
+            raise TypeError("Document property must be Node or None.")
+        self._document = doc
+        self.update()
+
+    @property
+    def transform(self):
+        """The transform that maps the local coordinate frame to the
+        coordinate frame of the parent.
+        """
+        return self._transform
+
+    @transform.setter
+    def transform(self, tr):
+        # Other nodes might be interested in this information, but turning it
+        # on by default is too expensive.
+        assert isinstance(tr, BaseTransform)
+        if tr is not self._transform:
+            self._transform = tr
+            self._update_trsys(None)
+
+    def set_transform(self, type_, *args, **kwargs):
+        """Create a new transform of *type* and assign it to this node.
+
+        All extra arguments are used in the construction of the transform.
+
+        Parameters
+        ----------
+        type_ : str
+            The transform type.
+        *args : tuple
+            Arguments.
+        **kwargs : dict
+            Keywoard arguments.
+        """
+        self.transform = create_transform(type_, *args, **kwargs)
+
+    def _update_trsys(self, event):
+        """Called when  has changed.
+
+        This allows the node and its children to react (notably, VisualNode
+        uses this to update its TransformSystem).
+
+        Note that this method is only called when one transform is replaced by
+        another; it is not called if an existing transform internally changes
+        its state.
+        """
+        for ch in self.children:
+            ch._update_trsys(event)
+        self.events.transform_change()
+        self.update()
+
+    def parent_chain(self):
+        """
+        Return the list of parents starting from this node. The chain ends
+        at the first node with no parents.
+        """
+        chain = [self]
+        while True:
+            try:
+                parent = chain[-1].parent
+            except Exception:
+                break
+            if parent is None:
+                break
+            chain.append(parent)
+        return chain
+
+    def describe_tree(self, with_transform=False):
+        """Create tree diagram of children
+
+        Parameters
+        ----------
+        with_transform : bool
+            If true, add information about node transform types.
+
+        Returns
+        -------
+        tree : str
+            The tree diagram.
+        """
+        # inspired by https://github.com/mbr/asciitree/blob/master/asciitree.py
+        return self._describe_tree('', with_transform)
+
+    def _describe_tree(self, prefix, with_transform):
+        """Helper function to actuall construct the tree"""
+        extra = ': "%s"' % self.name if self.name is not None else ''
+        if with_transform:
+            extra += (' [%s]' % self.transform.__class__.__name__)
+        output = ''
+        if len(prefix) > 0:
+            output += prefix[:-3]
+            output += '  +--'
+        output += '%s%s\n' % (self.__class__.__name__, extra)
+
+        n_children = len(self.children)
+        for ii, child in enumerate(self.children):
+            sub_prefix = prefix + ('   ' if ii+1 == n_children else '  |')
+            output += child._describe_tree(sub_prefix, with_transform)
+        return output
+
+    def common_parent(self, node):
+        """
+        Return the common parent of two entities
+
+        If the entities have no common parent, return None.
+
+        Parameters
+        ----------
+        node : instance of Node
+            The other node.
+
+        Returns
+        -------
+        parent : instance of Node | None
+            The parent.
+        """
+        p1 = self.parent_chain()
+        p2 = node.parent_chain()
+        for p in p1:
+            if p in p2:
+                return p
+        return None
+
+    def node_path_to_child(self, node):
+        """Return a list describing the path from this node to a child node
+
+        If *node* is not a (grand)child of this node, then raise RuntimeError.
+
+        Parameters
+        ----------
+        node : instance of Node
+            The child node.
+
+        Returns
+        -------
+        path : list | None
+            The path.
+        """
+        if node is self:
+            return []
+
+        # Go up from the child node as far as we can
+        path1 = [node]
+        child = node
+        while child.parent is not None:
+            child = child.parent
+            path1.append(child)
+            # Early exit
+            if child is self:
+                return list(reversed(path1))
+
+        # Verify that we're not cut off
+        if path1[-1].parent is None:
+            raise RuntimeError('%r is not a child of %r' % (node, self))
+
+        def _is_child(path, parent, child):
+            path.append(parent)
+            if child in parent.children:
+                return path
+            else:
+                for c in parent.children:
+                    possible_path = _is_child(path[:], c, child)
+                    if possible_path:
+                        return possible_path
+            return None
+
+        # Search from the parent towards the child
+        path2 = _is_child([], self, path1[-1])
+        if not path2:
+            raise RuntimeError('%r is not a child of %r' % (node, self))
+
+        # Return
+        return path2 + list(reversed(path1))
+
+    def node_path(self, node):
+        """Return two lists describing the path from this node to another
+
+        Parameters
+        ----------
+        node : instance of Node
+            The other node.
+
+        Returns
+        -------
+        p1 : list
+            First path (see below).
+        p2 : list
+            Second path (see below).
+
+        Notes
+        -----
+        The first list starts with this node and ends with the common parent
+        between the endpoint nodes. The second list contains the remainder of
+        the path from the common parent to the specified ending node.
+
+        For example, consider the following scenegraph::
+
+            A --- B --- C --- D
+                   \
+                    --- E --- F
+
+        Calling `D.node_path(F)` will return::
+
+            ([D, C, B], [E, F])
+
+        """
+        p1 = self.parent_chain()
+        p2 = node.parent_chain()
+        cp = None
+        for p in p1:
+            if p in p2:
+                cp = p
+                break
+        if cp is None:
+            raise RuntimeError("No single-path common parent between nodes %s "
+                               "and %s." % (self, node))
+
+        p1 = p1[:p1.index(cp)+1]
+        p2 = p2[:p2.index(cp)][::-1]
+        return p1, p2
+
+    def node_path_transforms(self, node):
+        """Return the list of transforms along the path to another node.
+
+        The transforms are listed in reverse order, such that the last 
+        transform should be applied first when mapping from this node to 
+        the other.
+
+        Parameters
+        ----------
+        node : instance of Node
+            The other node.
+
+        Returns
+        -------
+        transforms : list
+            A list of Transform instances.
+        """
+        a, b = self.node_path(node)
+        return ([n.transform for n in a[:-1]] + 
+                [n.transform.inverse for n in b])[::-1]
+
+    def node_transform(self, node):
+        """
+        Return the transform that maps from the coordinate system of
+        *self* to the local coordinate system of *node*.
+
+        Note that there must be a _single_ path in the scenegraph that connects
+        the two entities; otherwise an exception will be raised.
+
+        Parameters
+        ----------
+        node : instance of Node
+            The other node.
+
+        Returns
+        -------
+        transform : instance of ChainTransform
+            The transform.
+        """
+        return ChainTransform(self.node_path_transforms(node))
+
+    def __repr__(self):
+        name = "" if self.name is None else " name="+self.name
+        return "<%s%s at 0x%x>" % (self.__class__.__name__, name, id(self))
+
+    @property
+    def picking(self):
+        """Boolean that determines whether this node (and its children) are
+        drawn in picking mode.
+        """
+        return self._picking
+
+    @picking.setter
+    def picking(self, p):
+        for c in self.children:
+            c.picking = p
+        self._picking = p
+
+    @contextmanager
+    def set_picking(self, *, picking=True):
+        """Context manager to temporarily set picking for this node and its children.
+
+        Note that this function will not alter the picking mode unless/until
+        the context manager is entered (using the `with` statement). Use
+        :py:attr:`~.picking` for setting the picking mode directly.
+        """
+        old_picking = self.picking
+        try:
+            self.picking = picking
+            yield self.picking
+        finally:
+            self.picking = old_picking

vispy/scene/subscene.py

@@ -0,0 +1,20 @@
+# -*- 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
+
+from .node import Node
+
+
+class SubScene(Node):
+    """A Node subclass that serves as a marker and parent node for certain
+    branches of the scenegraph.
+
+    SubScene nodes are used as the top-level node for the internal scenes of
+    a canvas and a view box.
+    """
+
+    def __init__(self, **kwargs):
+        Node.__init__(self, **kwargs)
+        self.document = self