OpenGLContext 3.0.0a1__py3-none-any.whl

OpenGLContext/move/direct.py

@@ -0,0 +1,156 @@
+"""Interactions for navigating the context"""
+from gettext import gettext as _
+from OpenGLContext.move import movementmanager
+import math
+
+class Direct( movementmanager.MovementManager ):
+    """OpenGLContext's original manipulation for the view platform"""
+    commands = movementmanager.MovementManager.commands + [
+        # User-name, key, function-name
+        (_('Forward'), 'forward','forward'),
+        (_('Back'), 'backward','backward' ),
+        (_('Up'), 'up','up' ),
+        (_('Down'), 'down', 'down' ),
+        (_('Left'), 'left', 'left' ),
+        (_('Right'), 'right', 'right' ),
+        
+        (_('Turn Up'), 'turnup', 'turnup' ),
+        (_('Turn Down'), 'turndown', 'turndown' ),
+        (_('Turn Left'), 'turnleft', 'turnleft' ),
+        (_('Turn Right'), 'turnright', 'turnright' ),
+        
+        (_('Straighten'), 'straighten','straighten'),
+        
+        (_('Faster'), 'faster', 'faster' ),
+        (_('Slower'), 'slower','slower' ),
+    ]
+    commandBindings = dict(
+        forward=dict( eventType='keyboard', name='<up>', state=1, modifiers=(0,0,0) ),
+        backward=dict( eventType='keyboard', name='<down>', state=1, modifiers=(0,0,0) ),
+        up=dict( eventType='keyboard', name='<up>', state=1, modifiers=(0,0,1)),
+        turnup=dict(eventType='keyboard', name='<up>', state=1, modifiers=(0,1,0)),
+        turndown=dict(eventType='keyboard', name='<down>', state=1, modifiers=(0,1,0)),
+        down=dict(eventType='keyboard', name='<down>', state=1, modifiers=(0,0,1),),
+        turnleft=dict(eventType='keyboard', name='<left>', state=1, modifiers=(0,0,0),),
+        left=dict(eventType='keyboard', name='<left>', state=1, modifiers=(0,0,1)),
+        turnright=dict(eventType='keyboard', name='<right>', state=1, modifiers=(0,0,0),),
+        right=dict(eventType='keyboard', name='<right>', state=1, modifiers=(0,0,1),),
+        straighten=dict(eventType='keypress', name='-', modifiers=(0,0,0),),
+        slower=dict(eventType='keypress', name='[', modifiers=(0,0,0),),
+        faster=dict(eventType='keypress', name=']', modifiers=(0,0,0),),
+        examine=dict(eventType='mousebutton', button=1, state = 1, modifiers=(0,0,0),),
+    )
+    STEPDISTANCE = 0.5 # 1/2 of a unit
+    TURNANGLE = math.pi/32
+
+    ### LOGO-like commands...
+    def turn (self, deltaOrientation= (0,1,0,math.pi/4) ):
+        """Apply rotation within the current orientation
+
+        In essence, this allows you to "turn your head"
+        which gives you the commonly useful ability to
+        function from your own frame of reference.
+
+        For example:
+            turn( 1,0,0,angle ) will rotate the camera up
+                from its current view orientation
+            turn( 0,1,0,angle ) will rotate the camera about
+                the current horizon
+
+        This method is implemented almost entirely within
+        the quaternion class.  Quaternion's have considerable
+        advantages for this type of work, as they do not
+        become "warped" with successive rotations.
+        """
+        self.platform.setOrientation( self.platform.relativeOrientation( deltaOrientation ) )
+        self.context.triggerRedraw(1)
+
+    def stepRelative( self, x=0,y=0,z=0 ):
+        """Step this distance in relative (view) coordinates"""
+        self.platform.moveRelative( x=x,y=y,z=z )
+        self.context.triggerRedraw(1)
+
+    def forward( self, event ):
+        """(callback) Move platform forward by STEPDISTANCE
+
+        triggers redraw after completion
+        """
+        self.stepRelative( z = -self.STEPDISTANCE )
+    def backward( self, event ):
+        """(callback) Move platform backward by STEPDISTANCE
+
+        triggers redraw after completion
+        """
+        self.stepRelative( z = self.STEPDISTANCE )
+    def up( self, event ):
+        """(callback) Move platform upward by STEPDISTANCE
+
+        triggers redraw after completion
+        """
+        self.stepRelative( y = self.STEPDISTANCE )
+    def down( self, event ):
+        """(callback) Move platform downward by STEPDISTANCE
+
+        triggers redraw after completion
+        """
+        self.stepRelative( y = -self.STEPDISTANCE )
+    def left( self, event ):
+        """(callback) Move platform left by STEPDISTANCE
+
+        triggers redraw after completion
+        """
+        self.stepRelative( x = -self.STEPDISTANCE )
+    def right( self, event ):
+        """(callback) Move platform right by STEPDISTANCE
+
+        triggers redraw after completion
+        """
+        self.stepRelative( x = self.STEPDISTANCE )
+    def turnup( self, event ):
+        """(callback) Rotates "head" backward (looks upward) by TURNANGLE
+
+        triggers redraw after completion
+        """
+        self.turn( (1.0,0.0,0.0, self.TURNANGLE) )
+    def turndown( self, event ):
+        """(callback) Rotates "head" forward (looks downward) by TURNANGLE
+
+        triggers redraw after completion
+        """
+        self.turn( (1.0,0.0,0.0, -self.TURNANGLE) )
+    def turnleft( self, event ):
+        """(callback) Rotates "head" to the left by TURNANGLE
+
+        triggers redraw after completion
+        """
+        self.turn( (0.0,1.0,0.0, self.TURNANGLE) )
+    def turnright( self, event ):
+        """(callback) Rotates "head" to the right by TURNANGLE
+
+        triggers redraw after completion
+        """
+        self.turn( (0.0,1.0,0.0, -self.TURNANGLE) )
+    def straighten( self, event ):
+        """(callback) Straightens the platform orientation
+
+        Attempts to make the orientation equal to the
+        y-axis orientation of the current orientation.
+
+        In other words, tries to make the camera's horizon
+        equal to the object-space horizon (the x,z plane)
+        without altering the y-axis orientation.
+
+        See:
+            OpenGLContext.viewplatform.ViewPlatform.straighten
+        
+        triggers redraw after completion
+        """
+        self.platform.straighten()
+        self.context.triggerRedraw(1)
+        
+    def faster( self, event ):
+        """Increase our walking speed"""
+        self.STEPDISTANCE *= 1.5
+    def slower( self, event ):
+        """Decrease our walking speed"""
+        self.STEPDISTANCE /= 1.5

OpenGLContext/move/dragwatcher.py

@@ -0,0 +1,42 @@
+"""Semantics for fractional and absolute dragging"""
+
+class DragWatcher(object):
+    """Class providing semantics for fractional and absolute dragging
+
+    With this class you can track the start position of a drag action
+    and query for both absolute distance dragged, and distance as a
+    fraction of the distance to the edges of the window.
+    """
+    def __init__ (self, startX, startY, totalX, totalY ):
+        """Initialise the DragWatcher
+
+        startX, startY -- initial coordinates for the drag
+        totalX, totalY -- overall dimensions of the context
+        """
+        self.start = startX, startY
+        self.total = totalX, totalY
+    def fractions (self, newX, newY ):
+        """Calculate fractional delta from the start point
+
+        newX, newY -- new selection point from which to calculate
+        """
+        if (newX, newY) == self.start:
+            return 0.0,0.0
+        values = []
+        for index, item in ((0, newX), (1, newY)):
+            if item < self.start[index]:
+                value = float(item-self.start[index])/ self.start[index]
+            else:
+                value = float(item-self.start[index])/ (self.total[index]-self.start[index])
+            values.append (value)
+        return values
+    def distances (self, newX, newY ):
+        """Calculate absolute distances from start point
+
+        newX, newY -- new selection point from which to calculate
+        """
+        if (newX, newY) == self.start:
+            return 0,0
+        else:
+            return newX-self.start[0], newY-self.start[1]
+        

OpenGLContext/move/examinemanager.py

@@ -0,0 +1,100 @@
+"""Interaction mode for examining objects"""
+import math
+
+from OpenGLContext.events import eventmanager
+
+#: How far a drag from where it started to the edge of the window turns the
+#: view: **half a circle**.  The trackball's own default is a full one, which
+#: put the far side of the model half a window away and made a nudge a quarter
+#: turn -- with nothing that could be called examining in between.  Half a turn
+#: to the edge is what a VRML browser has always done, and it means the whole
+#: of an object is reachable in one drag while a small movement is a small look.
+EXAMINE_DRAG_ANGLE = math.pi
+
+class ExamineManager ( eventmanager.EventManager):
+    """Interaction EventManager for "Examine" mode
+
+    This interaction manager implements an examine mode
+    similar to that found in VRML97 browsers.  Pointing
+    to an object and dragging up/down left/right causes
+    the viewpoint to orbit around the object as if the
+    object were held in the hand and being rotated.
+
+    The manager uses the trackball thereby the dragwatcher
+    to provide screen-relative scaling of the input.  In
+    other words, distances are measured as fractions of
+    the distance to the edge of the screen.
+    """
+    type = "examine"
+    def __init__ (self, context, platform, center, event):
+        """Initialise the ExamineManager
+
+        context -- Context instance
+        platform -- ViewPlatform instance
+        center -- object-space coordinates about which to revolve
+        event -- event which began the examine interaction.
+        """
+        self.platform = platform
+        self.client = context
+        eventmanager.EventManager.__init__ (self)
+        width, height = self.client.getViewPort()
+        self.button = event.button
+        self.OnBuildTrackball( platform, center, event, width, height )
+        self.OnBind()
+    ### client API
+    def update( self, event ):
+        '''Update the examine trackball with new mouse event
+
+        This updates the internal position, then triggers a
+        redraw of the context.
+        '''
+        position, orientation = self.trackball.update(* event.getPickPoint() )
+        self.platform.position = position
+        self.platform.quaternion = orientation
+        self.client.triggerRedraw(1)
+    def release( self, event ):
+        """Trigger cleanup of the examine mode"""
+        self.OnUnBind()
+    def cancel(self, event):
+        """Cancel the examine mode, return to original position and orientation"""
+        position, orientation = self.trackball.cancel ()
+        self.OnUnBind()
+        self.platform.position = position
+        self.platform.quaternion = orientation
+        self.client.triggerRedraw(1)
+
+    ### Customisation points
+    def OnBuildTrackball( self, platform, center, event, width, height ):
+        """Build the trackball object
+        Customisation point for those wanting to use a different
+        trackball implementation."""
+        from OpenGLContext.move import trackball
+        self.trackball = trackball.Trackball (
+            platform.position, platform.quaternion,
+            center,
+            event.getPickPoint()[0],event.getPickPoint()[1],
+            width, height,
+            dragAngle = EXAMINE_DRAG_ANGLE,
+        )
+        
+    def OnBind( self ):
+        """Bind the events needing binding to run the examine mode
+        Customisation point for those needing custom controls"""
+        self.client.captureEvents("mousebutton", self)
+        self.client.captureEvents("mousemove", self)
+    def OnUnBind( self ):
+        """UnBind the events for the examine mode
+        Customisation point for those needing custom controls"""
+        self.client.captureEvents("mousemove", None)
+        self.client.captureEvents("mousebutton", None)
+    def ProcessEvent (self, event):
+        """Respond to events from the system
+        Customisation point for those needing custom controls"""
+        if event.type == "mousemove":
+            self.update (event)
+        elif event.type == "mousebutton":
+            if event.button == self.button and event.state == 0: # mouse released
+                self.release (event)
+            elif event.state == 0: # mouse released, not our button, cancel
+                self.cancel( event )
+        

OpenGLContext/move/followcam.py

@@ -0,0 +1,121 @@
+"""A fixed-offset follow camera for third-person / overhead demos.
+
+The camera sits at a constant offset from a target and looks at it — no user
+control, no orbiting.  Each frame the caller sets the target (usually a moving
+object's position) and calls :meth:`apply`, which writes the position and
+orientation onto a :class:`~OpenGLContext.move.viewplatform.ViewPlatform`.
+
+It also supports **holding**: freeze on the current target and ignore new ones
+until released.  The marble demo uses this to keep the view locked on the square a
+marble fell from while the respawn penalty elapses, instead of chasing the marble
+into the void.
+
+Orientation convention: this targets the **core-profile** view path, where
+``ViewPlatform`` builds the modelview from ``modelMatrix`` /
+``quaternion.matrix``.  :func:`look_at_orientation` returns the VRML axis-angle
+that (after ``setOrientation`` negates it, as it does for every VRML orientation)
+places the target on the camera's view -Z axis — verified end-to-end against
+``ViewPlatform.modelMatrix`` in ``tests/test_followcam.py``.
+"""
+from typing import Any, Optional, Tuple
+
+import numpy as np
+
+
+def _normalize(v: Any) -> np.ndarray:
+    v = np.asarray(v, dtype='d')
+    n = np.linalg.norm(v)
+    return v / n if n > 1e-12 else v
+
+
+def look_at_orientation(eye: Any, target: Any,
+                        up: Any = (0.0, 1.0, 0.0)) -> Tuple[float, float, float, float]:
+    """VRML axis-angle ``(x, y, z, radians)`` orienting a camera at ``eye`` to
+    look at ``target``.
+
+    Builds the camera basis (right, up, backward) in world space and converts the
+    resulting rotation matrix to an axis-angle.  ``up`` is the desired world up;
+    pass a different up (e.g. ``(0,0,-1)``) when looking straight down, where the
+    default up is degenerate.
+    """
+    eye = np.asarray(eye, dtype='d')
+    target = np.asarray(target, dtype='d')
+
+    backward = _normalize(eye - target)             # camera local +Z
+    right = _normalize(np.cross(_normalize(up), backward))  # camera local +X
+    true_up = np.cross(backward, right)             # camera local +Y
+    # Columns are where the camera's local x/y/z land in world space (the
+    # camera-local → world rotation).  ViewPlatform.setOrientation negates the
+    # angle and the core modelMatrix consumes it so this basis becomes the view.
+    R = np.column_stack([right, true_up, backward])
+    return _matrix_to_axis_angle(R)
+
+
+def _matrix_to_axis_angle(R: np.ndarray) -> Tuple[float, float, float, float]:
+    """Convert a 3×3 rotation matrix to VRML axis-angle ``(x, y, z, radians)``."""
+    trace = np.trace(R)
+    cos_angle = np.clip((trace - 1.0) / 2.0, -1.0, 1.0)
+    angle = np.arccos(cos_angle)
+    if angle < 1e-9:
+        return (0.0, 1.0, 0.0, 0.0)
+    if angle > np.pi - 1e-6:
+        # Near 180°: axis from the largest diagonal term, sign-recovered off-diagonal.
+        d = np.array([R[0, 0], R[1, 1], R[2, 2]])
+        k = int(np.argmax(d))
+        axis = np.zeros(3)
+        axis[k] = np.sqrt(max((R[k, k] + 1.0) / 2.0, 0.0))
+        other = [(k + 1) % 3, (k + 2) % 3]
+        for j in other:
+            axis[j] = R[k, j] / (2.0 * axis[k]) if axis[k] > 1e-9 else 0.0
+        axis = _normalize(axis)
+        return (float(axis[0]), float(axis[1]), float(axis[2]), float(angle))
+    axis = np.array([R[2, 1] - R[1, 2],
+                     R[0, 2] - R[2, 0],
+                     R[1, 0] - R[0, 1]])
+    axis = _normalize(axis)
+    return (float(axis[0]), float(axis[1]), float(axis[2]), float(angle))
+
+
+class FollowCamera:
+    """Drive a ``ViewPlatform`` to a fixed offset from a target, looking at it."""
+
+    def __init__(self, platform: Any, offset: Any = (0.0, 14.0, 14.0),
+                 up: Any = (0.0, 1.0, 0.0)) -> None:
+        self.platform = platform
+        self.offset = np.asarray(offset, dtype='d')
+        self.up = np.asarray(up, dtype='d')
+        self._target = np.zeros(3)
+        self._held_target: Optional[np.ndarray] = None
+
+    def target(self, position: Any) -> None:
+        """Record the live point to follow.
+
+        Always updates the live target; while holding, :meth:`apply` simply
+        ignores it, so on :meth:`release` the camera snaps to the most recent
+        live target rather than a stale one.
+        """
+        self._target = np.asarray(position, dtype='d')[:3]
+
+    def hold(self) -> None:
+        """Freeze the camera on the current target until :meth:`release`."""
+        if self._held_target is None:
+            self._held_target = self._target.copy()
+
+    def release(self) -> None:
+        """Resume following live targets."""
+        self._held_target = None
+
+    @property
+    def is_holding(self) -> bool:
+        return self._held_target is not None
+
+    @property
+    def active_target(self) -> np.ndarray:
+        return self._held_target if self._held_target is not None else self._target
+
+    def apply(self) -> None:
+        """Write the camera pose onto the platform for this frame."""
+        target = self.active_target
+        eye = target + self.offset
+        self.platform.setPosition(tuple(eye))
+        self.platform.setOrientation(look_at_orientation(eye, target, self.up))