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

psychopy/hardware/soundsensor.py

@@ -0,0 +1,473 @@
+import json
+from psychopy import constants, core, sound, logging
+from psychopy.hardware import base, DeviceManager
+from psychopy.localization import _translate
+from psychopy.hardware import keyboard
+
+
+class SoundSensorResponse(base.BaseResponse):
+    # list of fields known to be a part of this response type
+    fields = ["t", "value", "channel", "threshold"]
+
+    def __init__(self, t, value, channel, device=None, threshold=None):
+        # initialise base response class
+        base.BaseResponse.__init__(self, t=t, value=value, device=device)
+        # store channel and threshold
+        self.channel = channel
+        self.threshold = threshold
+
+
+class BaseSoundSensorGroup(base.BaseResponseDevice):
+
+    def __init__(self, channels=1, threshold=None):
+        base.BaseResponseDevice.__init__(self)
+        # store number of channels
+        self.channels = channels
+        # attribute in which to store current state
+        self.state = [False] * channels
+        # set initial threshold
+        self.threshold = [None] * channels
+        self.setThreshold(threshold, channel=list(range(channels)))
+    
+    def findThreshold(self, speaker, channel=None, samplingWindow=0.5):
+        """
+        Find the best threshold for this device with a given speaker.
+
+        Parameters
+        ----------
+        speaker : psychopy.hardware.speaker.SpeakerDevice
+            Speaker to find best threshold for.
+        channel : int or list[int]
+            Channel to look for responses in, or a list of channels
+        samplingWindow : float
+            How long (s) to wait for a response after playing the test noise
+        """
+        # if not given any channels, use all
+        if channel is None:
+            channel = list(range(self.channels))
+        # is given many channels, find for each
+        if isinstance(channel, (list, tuple)):
+            thresholds = []
+            # iterate through channels
+            for thisChannel in channel:
+                thresholds.append(
+                    self.findThreshold(speaker, channel=thisChannel)
+                )
+            
+            return thresholds
+        
+        # sound to play
+        snd = sound.Sound("voicekeyThresholdStim.wav", speaker=speaker, secs=5, loops=-1)
+        # keyboard to check for escape/continue
+        kb = keyboard.Keyboard(deviceName="defaultKeyboard")
+        
+        def _bisectThreshold(threshRange, recursionLimit=16):
+            """
+            Recursively narrow thresholds to approach an acceptable threshold
+            """
+            # work out current
+            current = sum(threshRange) / 2
+            # set threshold
+            self._setThreshold(current, channel=channel)
+            # reset current state and clear responses
+            self.state[channel] = None
+            self.responses = []
+            # start a countdown for beep duration
+            countdown = core.CountdownTimer(samplingWindow)
+            # wait for a response
+            gotResp = False
+            while countdown.getTime() > 0:
+                gotResp = gotResp or self.getState(channel=channel)
+            # get state
+            value = self.getState(channel=channel)
+            # log
+            logging.debug(
+                f"Trying threshold range: {threshRange}, detected sound: {value}"
+            )
+            # set either upper or lower bound according to whether we got sound
+            if value:
+                threshRange[1] = current
+            else:
+                threshRange[0] = current
+            # check for escape before entering recursion
+            if kb.getKeys(['escape']):
+                return current
+            # check for recursion limit before reentering recursion
+            if recursionLimit <= 0:
+                return current
+            # return if threshold is small enough
+            if abs(threshRange[1] - threshRange[0]) < 4:
+                return current
+            # recur with new range
+            return _bisectThreshold(threshRange, recursionLimit=recursionLimit-1)
+        
+        # reset state
+        self.dispatchMessages()
+        self.clearResponses()
+        # make sure sound isn't playing
+        snd.stop()
+        # get threshold with no sound
+        offThreshold = _bisectThreshold([0, 1], recursionLimit=16)
+        # play sound
+        snd.play()
+        # get threshold with sound
+        onThreshold = _bisectThreshold([0, 1], recursionLimit=16)
+        # stop sound once done
+        snd.stop()
+        # pick a threshold between white and black (i.e. one that's safe)
+        threshold = (offThreshold + onThreshold) / 2
+        # clear all the events created by this process
+        self.state = [None] * self.channels
+        self.dispatchMessages()
+        self.clearResponses()
+        # set to found threshold
+        self._setThreshold(int(threshold), channel=channel)
+
+        return int(threshold)
+
+    def getThreshold(self, channel):
+        return self.threshold[channel]
+    
+    def setThreshold(self, threshold, channel=None):
+        # if not given a channel, set for all channels
+        if channel is None:
+            channel = list(range(self.channels))
+        # if given multiple channels, set for each
+        if isinstance(channel, (list, tuple)):
+            state = []
+            for thisChannel in channel:
+                state.append(
+                    self.setThreshold(threshold, channel=thisChannel)
+                )
+            return state
+
+        # store threshold value
+        self.threshold[channel] = threshold
+        # do device-specific threshold setting
+        state = self._setThreshold(threshold, channel=channel)
+
+        return state
+
+    def _setThreshold(self, threshold, channel=None):
+        """
+        Device-specific threshold setting method. This will be called by `setThreshold` and should 
+        be overloaded by child classes of BaseSoundSensor.
+
+        Parameters
+        ----------
+        threshold : int
+            Threshold at which to register a SoundSensor response, with 0 being the lowest possible 
+            volume and 255 being the highest.
+        channel : int
+            Channel to set the threshold for (if applicable to device)
+
+        Returns
+        ------
+        bool
+            True if current decibel level is above the threshold.
+        """
+        raise NotImplementedError()
+    
+    def getResponses(self, state=None, channel=None, clear=True):
+        """
+        Get responses which match a given on/off state.
+
+        Parameters
+        ----------
+        state : bool or None
+            True to get voicekey "on" responses, False to get voicekey "off" responses, None to 
+            get all responses.
+        channel : int
+            Which voicekey to get responses from?
+        clear : bool
+            Whether or not to remove responses matching `state` after retrieval.
+
+        Returns
+        -------
+        list[SoundSensorResponse]
+            List of matching responses.
+        """
+        # make sure parent dispatches messages
+        self.dispatchMessages()
+        # array to store matching responses
+        matches = []
+        # check messages in chronological order
+        for resp in self.responses.copy():
+            # does this message meet the criterion?
+            if (state is None or resp.value == state) and (channel is None or resp.channel == channel):
+                # if clear, remove the response
+                if clear:
+                    i = self.responses.index(resp)
+                    resp = self.responses.pop(i)
+                # append the response to responses array
+                matches.append(resp)
+
+        return matches
+    
+    def receiveMessage(self, message):
+        # do base receiving
+        base.BaseResponseDevice.receiveMessage(self, message)
+        # update state
+        self.state[message.channel] = message.value
+
+    def resetTimer(self, clock=logging.defaultClock):
+        raise NotImplementedError()
+
+    def getState(self, channel):
+        # dispatch messages from parent
+        self.dispatchMessages()
+        # return state after update
+        return self.state[channel]
+    
+    def findSpeakers(self, channel, allowedSpeakers=None, beepDur=1):
+        """
+        Play a sound on different speakers and return a list of all those which this SoundSensor was 
+        able to detect.
+
+        Parameters
+        ----------
+        channel : int
+            Channel to listen for responses on.
+        allowedSpeakers : list[SpeakerDevice or dict] or None
+            List of speakers to test, or leave as None to test all speakers. If speakers are given 
+            as a dict, SpeakerDevice objects will be created via DeviceManager. 
+        beepDur : float
+            How long (s) to play a beep for on each speaker?
+        """
+        # if no allowed speakers given, use all
+        if allowedSpeakers is None:
+            allowedSpeakers = DeviceManager.getAvailableDevices(
+                "psychopy.hardware.speaker.SpeakerDevice"
+            )
+        # list of found speakers
+        foundSpeakers = []
+        # iterate through allowed speakers
+        for speaker in allowedSpeakers:
+            # if given a dict, actualise it
+            if isinstance(speaker, dict):
+                speakerProfile = speaker
+                speaker = DeviceManager.getDevice(speakerProfile['deviceName'])
+                if speaker is None:
+                    speaker = DeviceManager.addDevice(**speakerProfile)
+            # generate a sound for this speaker
+            try:
+                snd = sound.Sound("A", speaker=speaker)
+            except Exception as err:
+                # silently skip on error
+                logging.warn(f"Failed to play audio on speaker {speaker}, reason: {err}")
+                continue
+            # reset current state and clear responses
+            self.state[channel] = False
+            self.responses = []
+            # start a countdown for beep duration
+            countdown = core.CountdownTimer(beepDur)
+            # start playing sound
+            snd.play()
+            # wait for a response
+            while countdown.getTime() > 0:
+                self.dispatchMessages()
+            # stop playing sound
+            snd.stop()
+            # wait again for the off message, to a max of the beep duration
+            countdown.reset(beepDur)
+            while countdown.getTime() > 0 and len(self.responses) <= 1:
+                self.dispatchMessages()
+            # if we got messages, the speaker is good
+            if len(self.responses) == 2:
+                foundSpeakers.append(speaker)
+        
+        return foundSpeakers
+
+
+
+class MicrophoneSoundSensor(BaseSoundSensorGroup):
+    """
+    Use a MicrophoneDevice to emulate a SoundSensor, by continuously querying its volume.
+
+    Parameters
+    ----------
+    device : psychopy.hardware.MicrophoneDevice
+        Microphone to sample from
+    threshold : int, optional
+        Threshold (0-1) at which to register a response, by default 0.5
+    dbRange : tuple, optional
+        Range of possible decibels to expect mic responses to be in, by default (0, 1)
+    samplingWindow : float
+        How long (s) to average samples from the microphone across? Larger sampling windows reduce 
+        the chance of random spikes, but also reduce sensitivity.
+    """
+    def __init__(self, device, threshold=0.5, dbRange=(0, 1), samplingWindow=0.03):
+        # if device is given by name, get it from DeviceManager
+        if isinstance(device, str):
+            deviceName = device
+            device = DeviceManager.getDevice(deviceName)
+            # if none by that name, try by that index
+            if device is None:
+                device = DeviceManager.getDeviceBy("index", deviceName)
+            # if none by that index, do any profiles match?
+            if device is None:
+                for profile in DeviceManager.getAvailableDevices(
+                    "psychopy.hardware.microphone.MicrophoneDevice"
+                ):
+                    # if any match the index, make a device from that profile
+                    if deviceName in (profile['index'], profile['deviceName']):
+                        device = DeviceManager.addDevice(**profile)
+            # if none found, fallback to default and print warning
+            if device is None:
+                logging.warn(
+                    f"No Microphonen named {deviceName}, falling back to default device."
+                )
+        # if no device given, get default
+        if device is None:
+            device = DeviceManager.getDeviceBy("index", None)
+        # store device
+        self.device = device
+        # store decibel range
+        self.dbRange = dbRange
+        # store sampling window
+        self.samplingWindow = samplingWindow
+        # make clock
+        from psychopy.core import Clock
+        self.clock = Clock()
+        # initialise base class
+        BaseSoundSensorGroup.__init__(
+            self, channels=1, threshold=threshold
+        )
+    
+    def getThreshold(self, channel=None):
+        return BaseSoundSensorGroup.getThreshold(self, channel=channel or 0)
+    
+    def getThresholdDb(self, channel=None):
+        """
+        Get the volume threshold in dB rather than arbitrary units.
+        """
+        return (
+            min(self.dbRange) + 
+            self.getThreshold(channel=channel) * (max(self.dbRange) - min(self.dbRange))
+        )
+    
+    def _setThreshold(self, threshold, channel=None):
+        """
+        No additional setup is needed for emulator as thresholding is emulated outside of the 
+        device.
+        """
+        return self.getState(channel=channel)
+
+    def dispatchMessages(self):
+        """
+        Check the Microphone volume and deliver appropriate response.
+        """
+        # make sure mic is recording
+        if not self.device.isStarted:
+            self.device.start()
+        # get current volume
+        vol = self.device.getCurrentVolume(timeframe=self.samplingWindow)
+        # if device is multi-channel, take max
+        if not isinstance(vol, (int, float)):
+            vol = max(vol)
+        # transform volume to arbitrary units
+        adjVol = int(
+            (vol - min(self.dbRange)) / (max(self.dbRange) - min(self.dbRange)) * 255
+        )
+        # iterate through channels
+        for channel in range(self.channels):
+            # work out state from adjusted volume
+            state = adjVol > self.getThreshold(channel=channel)
+            # if state has changed, make an event
+            if state != self.state[channel]:
+                resp = SoundSensorResponse(
+                    t=self.clock.getTime(),
+                    value=state,
+                    channel=channel,
+                    threshold=self.getThreshold(channel=channel),
+                    device=self
+                )
+                self.receiveMessage(resp)
+
+    def parseMessage(self, message):
+        """
+        Events are created as SoundSensorResponse, so parseMessage is not needed. Will return message 
+        unchanged.
+        """
+        return message
+
+    def isSameDevice(self, other):
+        if isinstance(other, type(self)):
+            # if both objects are this class, then compare mics
+            return other.device is self.device
+        else:
+            # if types don't match up, it's not the same device
+            return False
+
+    @staticmethod
+    def getAvailableDevices():
+        profiles = []
+        # iterate through available microphones
+        for micProfile in DeviceManager.getAvailableDevices("psychopy.hardware.microphone.MicrophoneDevice"):
+            profiles.append({
+                'deviceName': "SoundSensor Emulator (%(deviceName)s)" % micProfile,
+                'deviceClass': "psychopy.hardware.soundsensor.MicrophoneSoundSensor",
+                'device': micProfile['index'],
+
+            })
+        
+        return profiles
+    
+    def resetTimer(self, clock=logging.defaultClock):
+        self.clock._timeAtLastReset = clock._timeAtLastReset
+        self.clock._epochTimeAtLastReset = clock._epochTimeAtLastReset
+
+
+class SoundSensor:
+    """
+    Object to represent a SoundSensor in Builder experiments. Largely exists as a wrapper around 
+    BaseSoundSensorGroup, with the ability to inherit a device defined by a backend.
+    """
+    def __init__(self, device):
+        if isinstance(device, BaseSoundSensorGroup):
+            # if given a button group, use it
+            self.device = device
+        # if given a string, get via DeviceManager
+        if isinstance(device, str):
+            if device in DeviceManager.devices:
+                self.device = DeviceManager.getDevice(device)
+            else:
+                # don't use formatted string literals in _translate()
+                raise ValueError(_translate(
+                    "Could not find device named '{device}', make sure it has been set up "
+                    "in DeviceManager."
+                ).format(device))
+
+        # starting value for status (Builder)
+        self.status = constants.NOT_STARTED
+        # arrays to store info (Builder)
+        self.buttons = []
+        self.times = []
+        self.corr = []
+
+    def getAvailableDevices(self):
+        return self.device.getAvailableDevices()
+
+    def getResponses(self, state=None, channel=None, clear=True):
+        return self.device.getResponses(state=state, channel=channel, clear=clear)
+
+    def resetTimer(self, clock=logging.defaultClock):
+        return self.device.resetTimer(clock=clock)
+
+    def getState(self, channel):
+        return self.device.getState(channel=channel)
+
+    def clearResponses(self):
+        return self.device.clearResponses()
+    
+    def findSpeakers(self, channel, allowedSpeakers=None, beepDur=1):
+        return self.device.findSpeakers(channel, allowedSpeakers=allowedSpeakers, beepDur=beepDur)
+    
+    def findThreshold(self, speaker, channel=None, samplingWindow=0.5):
+        self.device.findThreshold(speaker, channel=channel, samplingWindow=samplingWindow)
+    
+    def getThreshold(self, channel):
+        self.device.getThreshold(channel=channel)
+    
+    def setThreshold(self, threshold, channel=None):
+        self.device.setThreshold(threshold=threshold, channel=channel)

psychopy/hardware/spatial/__init__.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""Classes and functions for spatial tracking devices in PsychoPy.
+"""
+
+# Part of the PsychoPy library
+# 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 psychopy.tools.mathtools as mt
+import numpy as np
+
+
+class TrackerData:
+    """Class for storing motion tracking data.
+
+    This class is used to store data from a motion tracking device. The data
+    includes the position and orientation of the tracker, as well as the
+    angular and linear velocity and acceleration values reported by the device.
+
+    Parameters
+    ----------
+    absSampleTime : float
+        The absolute sample time of the tracker data in seconds.
+    pos : tuple
+        The position of the tracker in [x, y, z] coordinates.
+    ori : tuple
+        The orientation of the tracker in [x, y, z, w] quaternion.
+    linearVelocity : tuple
+        The linear velocity of the tracker in [vx, vy, vz] coordinates.
+    angularVelocity : tuple
+        The angular velocity of the tracker in [vx, vy, vz] coordinates.
+    linearAcceleration : tuple
+        The linear acceleration of the tracker in [ax, ay, az] coordinates.
+    angularAcceleration : tuple
+        The angular acceleration of the tracker in [ax, ay, az] coordinates.
+    compassHeading : float
+        The compass heading of the tracker in degrees.
+
+    """
+    def __init__(
+            self, 
+            absSampleTime,
+            pos=(0., 0., 0.),
+            ori=(0., 0., 0., 1.),
+            linearVelocity=(0., 0., 0.),
+            angularVelocity=(0., 0., 0.),
+            linearAcceleration=(0., 0., 0.),
+            angularAcceleration=(0., 0., 0.),
+            compassHeading=0.0):
+        
+        # time the data was sampled from the device
+        self._absSampleTime = float(absSampleTime)
+
+        # tracker pose
+        self._thePose = mt.RigidBodyPose(pos, ori, dtype=float)
+
+        # IMU data
+        self._angularVelocity = np.asarray(angularVelocity, dtype=float)
+        self._linearVelocity = np.asarray(linearVelocity, dtype=float)
+        self._angularAcceleration = np.asarray(linearAcceleration, dtype=float)
+        self._linearAcceleration = np.asarray(angularAcceleration, dtype=float)
+        self._compassHeading = float(compassHeading)
+
+    @property
+    def thePose(self):
+        """The pose of the tracker in 3D space.
+
+        Returns
+        -------
+        RigidBodyPose
+            The pose of the tracker.
+
+        """
+        return self._thePose 
+    
+    @thePose.setter
+    def thePose(self, value):
+        if not isinstance(value, mt.RigidBodyPose):
+            raise TypeError("Expected a `RigidBodyPose` object.")
+        
+        self._thePose = value
+
+    @property
+    def pos(self):
+        """Return the position of the tracker.
+
+        Returns
+        -------
+        numpy.ndarray
+            The position of the tracker.
+
+        """
+        return self._trackerPose.getPos()
+    
+    @pos.setter
+    def pos(self, value):
+        self._trackerPose.setPos(value)
+
+    @property
+    def ori(self):
+        """Return the orientation of the tracker.
+
+        Returns
+        -------
+        numpy.ndarray
+            The orientation of the tracker.
+
+        """
+        return self._trackerPose.getOri()
+
+    @ori.setter
+    def ori(self, value):
+        self._trackerPose.setOri(value)
+
+    @property
+    def posOri(self):
+        """Return the position and orientation of the tracker.
+
+        Returns
+        -------
+        tuple
+            The position and orientation of the tracker.
+
+        """
+        return self._trackerPose.getPosOri()
+
+    @posOri.setter
+    def posOri(self, value):
+        self._trackerPose.setPosOri(value)
+
+    @property
+    def absSampleTime(self):
+        """Return the absolute sample time of the tracker data.
+
+        Returns
+        -------
+        float
+            The absolute sample time of the tracker data.
+
+        """
+        return self._absSampleTime
+    
+    @absSampleTime.setter
+    def absSampleTime(self, value):
+        self._absSampleTime = float(value)
+
+    @property
+    def angularVelocity(self):
+        """Return the angular velocity of the tracker.
+
+        Returns
+        -------
+        numpy.ndarray
+            The angular velocity of the tracker.
+
+        """
+        return self._angularVelocity
+    
+    @angularVelocity.setter
+    def angularVelocity(self, value):
+        self._angularVelocity[:] = value
+    
+    @property
+    def linearVelocity(self):
+        """Return the linear velocity of the tracker.
+
+        Returns
+        -------
+        numpy.ndarray
+            The linear velocity of the tracker.
+
+        """
+        return self._linearVelocity
+    
+    @linearVelocity.setter
+    def linearVelocity(self, value):
+        self._linearVelocity[:] = value
+
+    @property
+    def angularAcceleration(self):
+        """Return the angular acceleration of the tracker.
+
+        Returns
+        -------
+        numpy.ndarray
+            The angular acceleration of the tracker.
+
+        """
+        return self._angularAcceleration
+    
+    @angularAcceleration.setter
+    def angularAcceleration(self, value):
+        self._angularAcceleration[:] = value
+    
+    @property
+    def linearAcceleration(self):
+        """Return the linear acceleration of the tracker.
+
+        Returns
+        -------
+        numpy.ndarray
+            The linear acceleration of the tracker.
+
+        """
+        return self._linearAcceleration
+    
+    @linearAcceleration.setter
+    def linearAcceleration(self, value):
+        self._linearAcceleration[:] = value
+
+    @property
+    def compassHeading(self):
+        """Return the compass heading of the tracker.
+
+        Returns
+        -------
+        float
+            The compass heading of the tracker.
+
+        """
+        return self._compassHeading
+    
+    @compassHeading.setter
+    def compassHeading(self, value):
+        self._compassHeading = value
+
+
+if __name__ == "__main__":
+    pass
+