psychopy 2024.2.5__py3-none-any.whl → 2025.1.0__py3-none-any.whl

psychopy/visual/stim3d.py

@@ -4,7 +4,7 @@
 """Classes for 3D stimuli."""
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 from psychopy import logging
@@ -26,6 +26,10 @@ import numpy as np
 
 import pyglet.gl as GL
 
+# classes moved out of this module
+RigidBodyPose = mt.RigidBodyPose
+BoundingBox = mt.BoundingBox
+
 
 class LightSource:
     """Class for representing a light source in a scene. This is a 
@@ -1160,613 +1164,6 @@ class BlinnPhongMaterial:
         GL.glEnable(GL.GL_COLOR_MATERIAL)
 
 
-class RigidBodyPose:
-    """Class for representing rigid body poses. This is a lazy-imported
-    class, therefore import using full path
-    `from psychopy.visual.stim3d import RigidBodyPose` when inheriting
-    from it.
-
-    This class is an abstract representation of a rigid body pose, where the
-    position of the body in a scene is represented by a vector/coordinate and
-    the orientation with a quaternion. Pose can be manipulated and interacted
-    with using class methods and attributes. Rigid body poses assume a
-    right-handed coordinate system (-Z is forward and +Y is up).
-
-    Poses can be converted to 4x4 transformation matrices with `getModelMatrix`.
-    One can use these matrices when rendering to transform the vertices of a
-    model associated with the pose by passing them to OpenGL. Matrices are
-    cached internally to avoid recomputing them if `pos` and `ori` attributes
-    have not been updated.
-
-    Operators `*` and `~` can be used on `RigidBodyPose` objects to combine and
-    invert poses. For instance, you can multiply (`*`) poses to get a new pose
-    which is the combination of both orientations and translations by::
-
-        newPose = rb1 * rb2
-
-    Likewise, a pose can be inverted by using the `~` operator::
-
-        invPose = ~rb
-
-    Multiplying a pose by its inverse will result in an identity pose with no
-    translation and default orientation where `pos=[0, 0, 0]` and
-    `ori=[0, 0, 0, 1]`::
-
-        identityPose = ~rb * rb
-
-    Warnings
-    --------
-    This class is experimental and may result in undefined behavior.
-
-    """
-    def __init__(self, pos=(0., 0., 0.), ori=(0., 0., 0., 1.)):
-        """
-        Parameters
-        ----------
-        pos : array_like
-            Position vector `[x, y, z]` for the origin of the rigid body.
-        ori : array_like
-            Orientation quaternion `[x, y, z, w]` where `x`, `y`, `z` are
-            imaginary and `w` is real.
-
-        """
-        self._pos = np.ascontiguousarray(pos, dtype=np.float32)
-        self._ori = np.ascontiguousarray(ori, dtype=np.float32)
-
-        self._modelMatrix = mt.posOriToMatrix(
-            self._pos, self._ori, dtype=np.float32)
-
-        # computed only if needed
-        self._normalMatrix = np.zeros((4, 4), dtype=np.float32, order='C')
-        self._invModelMatrix = np.zeros((4, 4), dtype=np.float32, order='C')
-
-        # additional useful vectors
-        self._at = np.zeros((3,), dtype=np.float32, order='C')
-        self._up = np.zeros((3,), dtype=np.float32, order='C')
-
-        # compute matrices only if `pos` and `ori` attributes have been updated
-        self._matrixNeedsUpdate = False
-        self._invMatrixNeedsUpdate = True
-        self._normalMatrixNeedsUpdate = True
-
-        self.pos = pos
-        self.ori = ori
-
-        self._bounds = None
-
-    def __repr__(self):
-        return 'RigidBodyPose({}, {}), %s)'.format(self.pos, self.ori)
-
-    @property
-    def bounds(self):
-        """Bounding box associated with this pose."""
-        return self._bounds
-
-    @bounds.setter
-    def bounds(self, value):
-        self._bounds = value
-
-    @property
-    def pos(self):
-        """Position vector (X, Y, Z)."""
-        return self._pos
-
-    @pos.setter
-    def pos(self, value):
-        self._pos = np.ascontiguousarray(value, dtype=np.float32)
-        self._normalMatrixNeedsUpdate = self._matrixNeedsUpdate = \
-            self._invMatrixNeedsUpdate = True
-
-    @property
-    def ori(self):
-        """Orientation quaternion (X, Y, Z, W)."""
-        return self._ori
-
-    @ori.setter
-    def ori(self, value):
-        self._ori = np.ascontiguousarray(value, dtype=np.float32)
-        self._normalMatrixNeedsUpdate = self._matrixNeedsUpdate = \
-            self._invMatrixNeedsUpdate = True
-
-    @property
-    def posOri(self):
-        """The position (x, y, z) and orientation (x, y, z, w)."""
-        return self._pos, self._ori
-
-    @posOri.setter
-    def posOri(self, value):
-        self._pos = np.ascontiguousarray(value[0], dtype=np.float32)
-        self._ori = np.ascontiguousarray(value[1], dtype=np.float32)
-        self._matrixNeedsUpdate = self._invMatrixNeedsUpdate = \
-            self._normalMatrixNeedsUpdate = True
-
-    @property
-    def at(self):
-        """Vector defining the forward direction (-Z) of this pose."""
-        if self._matrixNeedsUpdate:  # matrix needs update, this need to be too
-            atDir = [0., 0., -1.]
-            self._at = mt.applyQuat(self.ori, atDir, out=self._at)
-
-        return self._at
-
-    @property
-    def up(self):
-        """Vector defining the up direction (+Y) of this pose."""
-        if self._matrixNeedsUpdate:  # matrix needs update, this need to be too
-            upDir = [0., 1., 0.]
-            self._up = mt.applyQuat(self.ori, upDir, out=self._up)
-
-        return self._up
-
-    def __mul__(self, other):
-        """Multiply two poses, combining them to get a new pose."""
-        newOri = mt.multQuat(self._ori, other.ori)
-        return RigidBodyPose(mt.transform(other.pos, newOri, self._pos), newOri)
-
-    def __imul__(self, other):
-        """Inplace multiplication. Transforms this pose by another."""
-        self._ori = mt.multQuat(self._ori, other.ori)
-        self._pos = mt.transform(other.pos, self._ori, self._pos)
-
-    def copy(self):
-        """Get a new `RigidBodyPose` object which copies the position and
-        orientation of this one. Copies are independent and do not reference
-        each others data.
-
-        Returns
-        -------
-        RigidBodyPose
-            Copy of this pose.
-
-        """
-        return RigidBodyPose(self._pos, self._ori)
-
-    def isEqual(self, other):
-        """Check if poses have similar orientation and position.
-
-        Parameters
-        ----------
-        other : `RigidBodyPose`
-            Other pose to compare.
-
-        Returns
-        -------
-        bool
-            Returns `True` is poses are effectively equal.
-
-        """
-        return np.isclose(self._pos, other.pos) and \
-            np.isclose(self._ori, other.ori)
-
-    def setIdentity(self):
-        """Clear rigid body transformations.
-        """
-        self._pos.fill(0.0)
-        self._ori[:3] = 0.0
-        self._ori[3] = 1.0
-        self._matrixNeedsUpdate = self._normalMatrixNeedsUpdate = \
-            self._invMatrixNeedsUpdate = True
-
-    def getOriAxisAngle(self, degrees=True):
-        """Get the axis and angle of rotation for the rigid body. Converts the
-        orientation defined by the `ori` quaternion to and axis-angle
-        representation.
-
-        Parameters
-        ----------
-        degrees : bool, optional
-            Specify ``True`` if `angle` is in degrees, or else it will be
-            treated as radians. Default is ``True``.
-
-        Returns
-        -------
-        tuple
-            Axis [rx, ry, rz] and angle.
-
-        """
-        return mt.quatToAxisAngle(self._ori, degrees)
-
-    def setOriAxisAngle(self, axis, angle, degrees=True):
-        """Set the orientation of the rigid body using an `axis` and
-        `angle`. This sets the quaternion at `ori`.
-
-        Parameters
-        ----------
-        axis : array_like
-            Axis of rotation [rx, ry, rz].
-        angle : float
-            Angle of rotation.
-        degrees : bool, optional
-            Specify ``True`` if `angle` is in degrees, or else it will be
-            treated as radians. Default is ``True``.
-
-        """
-        self.ori = mt.quatFromAxisAngle(axis, angle, degrees)
-
-    def getYawPitchRoll(self, degrees=True):
-        """Get the yaw, pitch and roll angles for this pose relative to the -Z
-        world axis.
-
-        Parameters
-        ----------
-        degrees : bool, optional
-            Specify ``True`` if `angle` is in degrees, or else it will be
-            treated as radians. Default is ``True``.
-
-        """
-        return mt.quatYawPitchRoll(self._ori, degrees)
-
-    @property
-    def modelMatrix(self):
-        """Pose as a 4x4 model matrix (read-only)."""
-        if not self._matrixNeedsUpdate:
-            return self._modelMatrix
-        else:
-            return self.getModelMatrix()
-
-    @property
-    def inverseModelMatrix(self):
-        """Inverse of the pose as a 4x4 model matrix (read-only)."""
-        if not self._invMatrixNeedsUpdate:
-            return self._invModelMatrix
-        else:
-            return self.getModelMatrix(inverse=True)
-
-    @property
-    def normalMatrix(self):
-        """The normal transformation matrix."""
-        if not self._normalMatrixNeedsUpdate:
-            return self._normalMatrix
-        else:
-            return self.getNormalMatrix()
-
-    def getNormalMatrix(self, out=None):
-        """Get the present normal matrix.
-
-        Parameters
-        ----------
-        out : ndarray or None
-            Optional 4x4 array to write values to. Values written are computed
-            using 32-bit float precision regardless of the data type of `out`.
-
-        Returns
-        -------
-        ndarray
-            4x4 normal transformation matrix.
-
-        """
-        if not self._normalMatrixNeedsUpdate:
-            return self._normalMatrix
-
-        self._normalMatrix[:, :] = np.linalg.inv(self.modelMatrix).T
-
-        if out is not None:
-            out[:, :] = self._normalMatrix[:, :]
-
-        self._normalMatrixNeedsUpdate = False
-
-        return self._normalMatrix
-
-    def getModelMatrix(self, inverse=False, out=None):
-        """Get the present rigid body transformation as a 4x4 matrix.
-
-        Matrices are computed only if the `pos` and `ori` attributes have been
-        updated since the last call to `getModelMatrix`. The returned matrix is
-        an `ndarray` and row-major.
-
-        Parameters
-        ----------
-        inverse : bool, optional
-            Return the inverse of the model matrix.
-        out : ndarray or None
-            Optional 4x4 array to write values to. Values written are computed
-            using 32-bit float precision regardless of the data type of `out`.
-
-        Returns
-        -------
-        ndarray
-            4x4 transformation matrix.
-
-        Examples
-        --------
-        Using a rigid body pose to transform something in OpenGL::
-
-            rb = RigidBodyPose((0, 0, -2))  # 2 meters away from origin
-
-            # Use `array2pointer` from `psychopy.tools.arraytools` to convert
-            # array to something OpenGL accepts.
-            mv = array2pointer(rb.modelMatrix)
-
-            # use the matrix to transform the scene
-            glMatrixMode(GL_MODELVIEW)
-            glPushMatrix()
-            glLoadIdentity()
-            glMultTransposeMatrixf(mv)
-
-            # draw the thing here ...
-
-            glPopMatrix()
-
-        """
-        if self._matrixNeedsUpdate:
-            self._modelMatrix = mt.posOriToMatrix(
-                self._pos, self._ori, out=self._modelMatrix)
-
-            self._matrixNeedsUpdate = False
-            self._normalMatrixNeedsUpdate = self._invMatrixNeedsUpdate = True
-
-        # only update and return the inverse matrix if requested
-        if inverse:
-            if self._invMatrixNeedsUpdate:
-                self._invModelMatrix = mt.invertMatrix(
-                    self._modelMatrix, out=self._invModelMatrix)
-                self._invMatrixNeedsUpdate = False
-
-            if out is not None:
-                out[:, :] = self._invModelMatrix[:, :]
-
-            return self._invModelMatrix  # return the inverse
-
-        if out is not None:
-            out[:, :] = self._modelMatrix[:, :]
-
-        return self._modelMatrix
-
-    def getViewMatrix(self, inverse=False):
-        """Convert this pose into a view matrix.
-
-        Creates a view matrix which transforms points into eye space using the
-        current pose as the eye position in the scene. Furthermore, you can use
-        view matrices for rendering shadows if light positions are defined
-        as `RigidBodyPose` objects.
-
-        Parameters
-        ----------
-        inverse : bool
-            Return the inverse of the view matrix. Default is `False`.
-
-        Returns
-        -------
-        ndarray
-            4x4 transformation matrix.
-
-        """
-        axes = np.asarray([[0, 0, -1], [0, 1, 0]], dtype=np.float32)
-
-        rotMatrix = mt.quatToMatrix(self._ori, dtype=np.float32)
-        transformedAxes = mt.applyMatrix(rotMatrix, axes, dtype=np.float32)
-
-        fwdVec = transformedAxes[0, :] + self._pos
-        upVec = transformedAxes[1, :]
-
-        viewMatrix = vt.lookAt(self._pos, fwdVec, upVec, dtype=np.float32)
-
-        if inverse:
-            viewMatrix = mt.invertMatrix(viewMatrix)
-
-        return viewMatrix
-
-    def transform(self, v, out=None):
-        """Transform a vector using this pose.
-
-        Parameters
-        ----------
-        v : array_like
-            Vector to transform [x, y, z].
-        out : ndarray or None, optional
-            Optional array to write values to. Must have the same shape as
-            `v`.
-
-        Returns
-        -------
-        ndarray
-            Transformed points.
-
-        """
-        return mt.transform(self._pos, self._ori, points=v, out=out)
-
-    def transformNormal(self, n):
-        """Rotate a normal vector with respect to this pose.
-
-        Rotates a normal vector `n` using the orientation quaternion at `ori`.
-
-        Parameters
-        ----------
-        n : array_like
-            Normal to rotate (1-D with length 3).
-
-        Returns
-        -------
-        ndarray
-            Rotated normal `n`.
-
-        """
-        pout = np.zeros((3,), dtype=np.float32)
-        pout[:] = n
-        t = np.cross(self._ori[:3], n[:3]) * 2.0
-        u = np.cross(self._ori[:3], t)
-        t *= self._ori[3]
-        pout[:3] += t
-        pout[:3] += u
-
-        return pout
-
-    def __invert__(self):
-        """Operator `~` to invert the pose. Returns a `RigidBodyPose` object."""
-        return RigidBodyPose(
-            -self._pos, mt.invertQuat(self._ori, dtype=np.float32))
-
-    def invert(self):
-        """Invert this pose.
-        """
-        self._ori = mt.invertQuat(self._ori, dtype=np.float32)
-        self._pos *= -1.0
-
-    def inverted(self):
-        """Get a pose which is the inverse of this one.
-
-        Returns
-        -------
-        RigidBodyPose
-            This pose inverted.
-
-        """
-        return RigidBodyPose(
-            -self._pos, mt.invertQuat(self._ori, dtype=np.float32))
-
-    def distanceTo(self, v):
-        """Get the distance to a pose or point in scene units.
-
-        Parameters
-        ----------
-        v : RigidBodyPose or array_like
-            Pose or point [x, y, z] to compute distance to.
-
-        Returns
-        -------
-        float
-            Distance to `v` from this pose's origin.
-
-        """
-        if hasattr(v, 'pos'):  # v is pose-like object
-            targetPos = v.pos
-        else:
-            targetPos = np.asarray(v[:3])
-
-        return np.sqrt(np.sum(np.square(targetPos - self.pos)))
-
-    def interp(self, end, s):
-        """Interpolate between poses.
-
-        Linear interpolation is used on position (Lerp) while the orientation
-        has spherical linear interpolation (Slerp) applied taking the shortest
-        arc on the hypersphere.
-
-        Parameters
-        ----------
-        end : LibOVRPose
-            End pose.
-        s : float
-            Interpolation factor between interval 0.0 and 1.0.
-
-        Returns
-        -------
-        RigidBodyPose
-            Rigid body pose whose position and orientation is at `s` between
-            this pose and `end`.
-
-        """
-        if not (hasattr(end, 'pos') and hasattr(end, 'ori')):
-            raise TypeError("Object for `end` does not have attributes "
-                            "`pos` and `ori`.")
-
-        interpPos = mt.lerp(self._pos, end.pos, s)
-        interpOri = mt.slerp(self._ori, end.ori, s)
-
-        return RigidBodyPose(interpPos, interpOri)
-
-    def alignTo(self, alignTo):
-        """Align this pose to another point or pose.
-
-        This sets the orientation of this pose to one which orients the forward
-        axis towards `alignTo`.
-
-        Parameters
-        ----------
-        alignTo : array_like or LibOVRPose
-            Position vector [x, y, z] or pose to align to.
-
-        """
-        if hasattr(alignTo, 'pos'):  # v is pose-like object
-            targetPos = alignTo.pos
-        else:
-            targetPos = np.asarray(alignTo[:3])
-
-        fwd = np.asarray([0, 0, -1], dtype=np.float32)
-        toTarget = targetPos - self._pos
-        invPos = mt.applyQuat(
-            mt.invertQuat(self._ori, dtype=np.float32),
-            toTarget, dtype=np.float32)
-        invPos = mt.normalize(invPos)
-
-        self.ori = mt.multQuat(
-            self._ori, mt.alignTo(fwd, invPos, dtype=np.float32))
-
-
-class BoundingBox:
-    """Class for representing object bounding boxes. This is a 
-    lazy-imported class, therefore import using full path 
-    `from psychopy.visual.stim3d import BoundingBox` when inheriting from it.
-
-
-    A bounding box is a construct which represents a 3D rectangular volume about
-    some pose, defined by its minimum and maximum extents in the reference frame
-    of the pose. The axes of the bounding box are aligned to the axes of the
-    world or the associated pose.
-
-    Bounding boxes are primarily used for visibility testing; to determine if
-    the extents of an object associated with a pose (eg. the vertices of a
-    model) falls completely outside of the viewing frustum. If so, the model can
-    be culled during rendering to avoid wasting CPU/GPU resources on objects not
-    visible to the viewer.
-
-    """
-    def __init__(self, extents=None):
-        self._extents = np.zeros((2, 3), np.float32)
-        self._posCorners = np.zeros((8, 4), np.float32)
-
-        if extents is not None:
-            self._extents[0, :] = extents[0]
-            self._extents[1, :] = extents[1]
-        else:
-            self.clear()
-
-        self._computeCorners()
-
-    def _computeCorners(self):
-        """Compute the corners of the bounding box.
-
-        These values are cached to speed up computations if extents hasn't been
-        updated.
-
-        """
-        for i in range(8):
-            self._posCorners[i, 0] = \
-                self._extents[1, 0] if (i & 1) else self._extents[0, 0]
-            self._posCorners[i, 1] = \
-                self._extents[1, 1] if (i & 2) else self._extents[0, 1]
-            self._posCorners[i, 2] = \
-                self._extents[1, 2] if (i & 4) else self._extents[0, 2]
-            self._posCorners[i, 3] = 1.0
-
-    @property
-    def isValid(self):
-        """`True` if the bounding box is valid."""
-        return np.all(self._extents[0, :] <= self._extents[1, :])
-
-    @property
-    def extents(self):
-        return self._extents
-
-    @extents.setter
-    def extents(self, value):
-        self._extents[0, :] = value[0]
-        self._extents[1, :] = value[1]
-        self._computeCorners()
-
-    def fit(self, verts):
-        """Fit the bounding box to vertices."""
-        np.amin(verts, axis=0, out=self._extents[0])
-        np.amax(verts, axis=0, out=self._extents[1])
-        self._computeCorners()
-
-    def clear(self):
-        """Clear a bounding box, invalidating it."""
-        self._extents[0, :] = np.finfo(np.float32).max
-        self._extents[1, :] = np.finfo(np.float32).min
-        self._computeCorners()
-
-
 class BaseRigidBodyStim(ColorMixin, WindowMixin):
     """Base class for rigid body 3D stimuli.
 

psychopy/visual/text.py

@@ -5,7 +5,7 @@
 '''
 
 # Part of the PsychoPy library
-# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2025 Open Science Tools Ltd.
 # Distributed under the terms of the GNU General Public License (GPL).
 
 import os
@@ -244,7 +244,18 @@ class TextStim(BaseVisualStim, DraggingMixin, ForeColorMixin, ContainerMixin):
                 GL.glDeleteLists(self._listID, 1)
             except (ImportError, ModuleNotFoundError, TypeError, GL.lib.GLException):
                 pass  # if pyglet no longer exists
-
+    
+    @property
+    def opacity(self):
+        return BaseVisualStim.opacity.fget(self)
+
+    @opacity.setter
+    def opacity(self, value):
+        # do base setting
+        BaseVisualStim.opacity.fset(self, value)
+        # trigger update
+        self._needSetText = True
+    
     @attributeSetter
     def height(self, height):
         """The height of the letters (Float/int or None = set default).
@@ -485,7 +496,6 @@ class TextStim(BaseVisualStim, DraggingMixin, ForeColorMixin, ContainerMixin):
         if self.win.winType in ["pyglet", "glfw"]:
             # unbind the main texture
             GL.glActiveTexture(GL.GL_TEXTURE0)
-#            GL.glActiveTextureARB(GL.GL_TEXTURE0_ARB)
             # the texture is specified by pyglet.font.GlyphString.draw()
             GL.glBindTexture(GL.GL_TEXTURE_2D, 0)
             GL.glEnable(GL.GL_TEXTURE_2D)