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

psychopy/hardware/{photodiode.py → lightsensor.py}

@@ -1,24 +1,25 @@
-import json
 from psychopy import core, layout, logging
 from psychopy.hardware import base, DeviceManager
 from psychopy.localization import _translate
 from psychopy.hardware import keyboard
+# for legacy compatability, import VisualValidator and VisualValidationError here
+from psychopy.validation.visual import VisualValidator, VisualValidationError
 
 
-class PhotodiodeResponse(base.BaseResponse):
+class LightSensorResponse(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, threshold=None):
+    def __init__(self, t, value, channel, device=None, threshold=None):
         # initialise base response class
-        base.BaseResponse.__init__(self, t=t, value=value)
+        base.BaseResponse.__init__(self, t=t, value=value, device=device)
         # store channel and threshold
         self.channel = channel
         self.threshold = threshold
 
 
-class BasePhotodiodeGroup(base.BaseResponseDevice):
-    responseClass = PhotodiodeResponse
+class BaseLightSensorGroup(base.BaseResponseDevice):
+    responseClass = LightSensorResponse
 
     def __init__(self, channels=1, threshold=None, pos=None, size=None, units=None):
         base.BaseResponseDevice.__init__(self)
@@ -28,6 +29,8 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
         self.state = [False] * channels
         # set initial threshold
         self.threshold = [None] * channels
+        if threshold is None:
+            threshold = 0.5
         self.setThreshold(threshold, channel=list(range(channels)))
         # store position params
         self.units = units
@@ -60,8 +63,8 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
         for cls in DeviceManager.deviceClasses:
             # get class from class str
             cls = DeviceManager._resolveClassString(cls)
-            # if class is a photodiode, add its available devices
-            if issubclass(cls, BasePhotodiodeGroup) and cls is not BasePhotodiodeGroup:
+            # if class is a light sensor, add its available devices
+            if issubclass(cls, BaseLightSensorGroup) and cls is not BaseLightSensorGroup:
                 devices += cls.getAvailableDevices()
 
         return devices
@@ -73,15 +76,15 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
         Parameters
         ----------
         state : bool or None
-            True to get photodiode "on" responses, False to get photodiode "off" responses, None to get all responses.
+            True to get light sensor "on" responses, False to get light sensor "off" responses, None to get all responses.
         channel : int
-            Which photodiode to get responses from?
+            Which light sensor to get responses from?
         clear : bool
             Whether or not to remove responses matching `state` after retrieval.
 
         Returns
         -------
-        list[PhotodiodeResponse]
+        list[LightSensorResponse]
             List of matching responses.
         """
         # make sure parent dispatches messages
@@ -125,7 +128,7 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
         rect.fillColor = "black"
         rect.draw()
         win.flip()
-        # wait 250ms for flip to happen and photodiode to catch it
+        # wait 250ms for flip to happen and light sensor to catch it
         timeoutClock.reset()
         while timeoutClock.getTime() < 0.25:
             self.dispatchMessages()
@@ -138,7 +141,7 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
         rect.fillColor = "white"
         rect.draw()
         win.flip()
-        # wait 250ms for flip to happen and photodiode to catch it
+        # wait 250ms for flip to happen and light sensor to catch it
         timeoutClock.reset()
         while timeoutClock.getTime() < 0.25:
             self.dispatchMessages()
@@ -146,32 +149,58 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
         while self.hasUnfinishedMessage():
             self.dispatchMessages()
         # start off with no channels
-        channels = []
+        channelsOn = set()
         # iterate through potential channels
         for i, state in enumerate(self.state):
-            # if any detected the flash, append it
+            # skip if we got more than 1 message
+            if len(self.getResponses(channel=i, clear=False)) > 1:
+                continue
+            # if any detected the flash, append it (test for false negative)
             if state:
-                channels.append(i)
+                channelsOn.add(i)
+        # clear caught messages so we're starting afresh
+        self.clearResponses()
+        # show black
+        rect.fillColor = "black"
+        rect.draw()
+        win.flip()
+        # wait 250ms for flip to happen and sensor to catch it
+        timeoutClock.reset()
+        while timeoutClock.getTime() < 0.25:
+            self.dispatchMessages()
+        # finish dispatching any messages which are only partially received               
+        while self.hasUnfinishedMessage():
+            self.dispatchMessages()
+        # start off with no channels
+        channelsOff = set()
+        # iterate through potential channels
+        for i, state in enumerate(self.state):
+            # skip if we got more than 1 message
+            if len(self.getResponses(channel=i, clear=False)) > 1:
+                continue
+            # if any detected the lack of flash, append it (test for false positive)
+            if not state:
+                channelsOff.add(i)
         
-        return channels
+        return tuple(channelsOn & channelsOff)
     
-    def findPhotodiode(self, win, channel=None, retryLimit=5):
+    def findSensor(self, win, channel=None, retryLimit=5):
         """
-        Draws rectangles on the screen and records photodiode responses to recursively find the location of the diode.
+        Draws rectangles on the screen and records light sensor responses to recursively find the location of the diode.
 
         Returns
         -------
         psychopy.layout.Position
-            Position of the diode on the window. Essentially, the center of the last rectangle which the photodiode
+            Position of the diode on the window. Essentially, the center of the last rectangle which the light sensor
             was able to detect.
         psychopy.layout.Size
-            Size of the area of certainty. Essentially, the size of the last (smallest) rectangle which the photodiode
+            Size of the area of certainty. Essentially, the size of the last (smallest) rectangle which the light sensor
             was able to detect.
         """
         # timeout clock
         timeoutClock = core.Clock()
         # keyboard to check for escape
-        kb = keyboard.Keyboard(deviceName="photodiodeValidatorKeyboard")
+        kb = keyboard.Keyboard(deviceName="visualValidatorKeyboard")
         # stash autodraw
         win.stashAutoDraw()
         # import visual here - if they're using this function, it's already in the stack
@@ -186,7 +215,7 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
         # add low opacity label
         label = visual.TextBox2(
             win,
-            text=f"Finding photodiode...",
+            text=f"Finding light sensor...",
             fillColor=(0, 0, 0), color=(80, 80, 80), colorSpace="rgb255",
             pos=(0, 0), size=(2, 2), units="norm",
             alignment="center",
@@ -211,18 +240,18 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
                 # if no channels are responsive, use 0th channel and let scanQuadrants fail cleanly
                 channel = 0
         # update label text once we have a channel
-        label.text = f"Finding photodiode {channel}..."
+        label.text = f"Finding light sensor {channel}..."
 
         def scanQuadrants(responsive=False):
             """
-            Recursively shrink the rectangle around the position of the photodiode until it's too 
+            Recursively shrink the rectangle around the position of the light sensor until it's too 
             small to detect.
 
             Parameters
             ----------
             responsive : bool
                 When calling manually, this should always be left as False! Will be set to True if 
-                any response was received from the photodiode.
+                any response was received from the light sensor.
             """
             # work out width and height of area
             w, h = rect.size
@@ -251,7 +280,7 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
                 label.draw()
                 rect.draw()
                 win.flip()
-                # wait for flip to happen and photodiode to catch it (max 250ms)
+                # wait for flip to happen and light sensor to catch it (max 250ms)
                 timeoutClock.reset()
                 self.clearResponses()
                 while not self.responses and timeoutClock.getTime() < 0.25:
@@ -262,16 +291,18 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
                 # check for escape before entering recursion
                 if kb.getKeys(['escape']):
                     return None
-                # poll photodiode
+                # poll light sensor
                 if self.getState(channel):
                     # mark that we've got a response
                     responsive = True
                     # if it detected this rectangle, recur
                     return scanQuadrants(responsive=responsive)
-            # if none of these have returned, rect is too small to cover the whole photodiode, so return
+            # if none of these have returned, rect is too small to cover the whole light sensor, so return
             return responsive
 
         def handleNonResponse(label, rect, timeout=5):
+            # log error
+            logging.error("Failed to find light sensor")
             # skip if retry limit hit
             if retryLimit <= 0:
                 return None
@@ -279,10 +310,10 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
             timer = core.CountdownTimer(start=timeout)
             # set label text to alert user
             msg = (
-                "Received no responses from photodiode during `findPhotodiode`. Photodiode may not "
+                "Received no responses from light sensor during `findSensor`. Light sensor may not "
                 "be connected or may be configured incorrectly.\n"
                 "\n"
-                "To manually specify the photodiode's position, press ENTER. To quit, press "
+                "To manually specify the light sensor's position, press ENTER. To quit, press "
                 "ESCAPE. Otherwise, will retry in {:.0f}s\n"
             )
             label.foreColor = "red"
@@ -303,13 +334,17 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
                 label.draw()
                 # flip
                 win.flip()
-            # if we timed out, retry whole find procedure
-            return self.findPhotodiode(win, channel=channel, retryLimit=retryLimit-1)
+            # if we timed out...
+            logging.error("Trying to find light sensor again after failing")
+            # re-detect threshold
+            self.findThreshold(win, channel=channel)
+            # re-find light sensor
+            return self.findSensor(win, channel=channel, retryLimit=retryLimit-1)
         
         def specifyManually(label, rect):
             # set label text to alert user
             label.text = (
-                "Use the arrow keys to move the photodiode patch and use the plus/minus keys to "
+                "Use the arrow keys to move the light sensor patch and use the plus/minus keys to "
                 "resize it. Press ENTER when finished, or press ESCAPE to quit.\n"
             )
             label.foreColor = "red"
@@ -360,12 +395,12 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
         self.state = [None] * self.channels
         self.dispatchMessages()
         self.clearResponses()
-        # recursively shrink rect around the photodiode
+        # recursively shrink rect around the light sensor
         responsive = scanQuadrants()
         # if cancelled, warn and continue
         if responsive is None:
             logging.warn(
-                "`findPhotodiode` procedure cancelled by user."
+                "`findSensor` procedure cancelled by user."
             )
             return (
                 layout.Position(self.pos, units="norm", win=win),
@@ -373,7 +408,7 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
             )
         # if we didn't get any responses at all, prompt to try again
         if not responsive:
-            handleNonResponse(label=label, rect=rect)
+            return handleNonResponse(label=label, rect=rect)
         # clear all the events created by this process
         self.state = [None] * self.channels
         self.dispatchMessages()
@@ -386,7 +421,7 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
         # set size/pos/units
         self.units = "norm"
         self.size = rect.size * 2
-        self.pos = rect.pos + rect.size / (-2, 2)
+        self.pos = rect.pos
 
         return (
             layout.Position(self.pos, units="norm", win=win),
@@ -405,7 +440,7 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
             # return array of thresholds
             return thresholds
         # keyboard to check for escape/continue
-        kb = keyboard.Keyboard(deviceName="photodiodeValidatorKeyboard")
+        kb = keyboard.Keyboard(deviceName="defaultKeyboard")
         # stash autodraw
         win.stashAutoDraw()
         # import visual here - if they're using this function, it's already in the stack
@@ -419,7 +454,7 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
         # add low opacity label
         label = visual.TextBox2(
             win,
-            text=f"Finding best threshold for photodiode {channel}...",
+            text=f"Finding best threshold for light sensor {channel}...",
             fillColor=None, color=(0, 0, 0), colorSpace="rgb",
             pos=(0, 0), size=(2, 2), units="norm",
             alignment="center",
@@ -435,11 +470,9 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
                 f"Trying threshold range: {threshRange}"
             )
             # work out current
-            current = int(
-                sum(threshRange) / 2
-            )
+            current = sum(threshRange) / 2
             # set threshold and get value
-            value = self._setThreshold(int(current), channel=channel)
+            value = self._setThreshold(current, channel=channel)
 
             if value:
                 # if expecting light and got light, we have an upper bound
@@ -454,7 +487,7 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
             if recursionLimit <= 0:
                 return current
             # return if threshold is small enough
-            if abs(threshRange[1] - threshRange[0]) < 4:
+            if abs(threshRange[1] - threshRange[0]) < 0.01:
                 return current
             # recur with new range
             return _bisectThreshold(threshRange, recursionLimit=recursionLimit-1)
@@ -477,7 +510,18 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
             label.draw()
             win.flip()
             # get threshold
-            thresholds[col] = _bisectThreshold([0, 255], recursionLimit=16)
+            thresholds[col] = _bisectThreshold([0, 1], recursionLimit=16)
+        # report thresholds
+        logging.debug(f"Channel {channel} responded 'on' for a black screen at threshold {thresholds['black']}")
+        logging.debug(f"Channel {channel} responded 'on' for a white screen at threshold {thresholds['white']}")
+        # if black is detected at the same or lower threshold as white, the sensor isn't working
+        if thresholds['black'] <= thresholds['white']:
+            logging.debug(
+                f"Could not detect a reasonable threshold for channel {channel}, sensor may be "
+                f"unplugged."
+            )
+            self._setThreshold(0, channel=channel)
+            return None
         # pick a threshold between white and black (i.e. one that's safe)
         threshold = (thresholds['white'] + thresholds['black']) / 2
         # clear bg rect
@@ -495,6 +539,46 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
 
         return int(threshold)
 
+    def checkSensor(self, win, channels=None, reps=1):
+        """
+        Check that the sensor is responsive on a given channel by alternating the full window 
+        between white and black, then checking that the channel state is True when white and False 
+        when black.
+
+        Parameters
+        ----------
+        win : psychopy.visual.Window
+            Window to use for checking.
+        channels : list[int] or tuple[int] or int or None, optional
+            Channel or channels to check, use None (default) to check all channels.
+        reps : int, optional
+            How many times to repeat the test - if the sensor has a habit of randomly 
+            flickering, there's a chance of it passing tests by random chance, so you may wish to 
+            repeat it several times. Default is 1 (aka do not repeat)
+
+        Returns
+        -------
+        bool
+            True
+        """
+        # if given just one channel, wrap it in a list
+        if isinstance(channels, int):
+            channels = [channels]
+        # if None, check all channels
+        if channels is None:
+            channels = list(range(self.channels))
+        # for each specified channel...
+        for channel in channels:
+            # the following is repeated for good measure, as many times as specified
+            for rep in range(reps):
+                # run findChannels
+                found = self.findChannels(win)
+                # if the given channel isn't found, test fails
+                if channel not in found:
+                    return False
+        
+        return True
+
     def setThreshold(self, threshold, channel):
         if isinstance(channel, (list, tuple)):
             # if given a list of channels, iterate
@@ -530,18 +614,14 @@ class BasePhotodiodeGroup(base.BaseResponseDevice):
         return self.state[channel]
 
 
-class PhotodiodeValidationError(BaseException):
-    pass
-
-
-class ScreenBufferSampler(BasePhotodiodeGroup):
-    def __init__(self, win, threshold=125, pos=None, size=None, units=None):
+class ScreenBufferSampler(BaseLightSensorGroup):
+    def __init__(self, win, threshold=0.5, pos=None, size=None, units=None):
         # store win
         self.win = win
         # default rect
         self.rect = None
         # initialise base class
-        BasePhotodiodeGroup.__init__(
+        BaseLightSensorGroup.__init__(
             self, channels=1, threshold=threshold, pos=pos, size=size, units=units
         )
         # make clock
@@ -558,8 +638,9 @@ class ScreenBufferSampler(BasePhotodiodeGroup):
         """
         Check the screen for changes and dispatch events as appropriate
         """
+        from psychopy.visual import Window
         # if there's no window, skip
-        if self.win is None:
+        if not isinstance(self.win, Window):
             return
         # get rect
         left, bottom = self._pos.pix + self.win.size / 2
@@ -575,24 +656,25 @@ class ScreenBufferSampler(BasePhotodiodeGroup):
             makeLum=True
         )
         # work out whether it's brighter than threshold
-        state = pixels.mean() > (255 - self.getThreshold())
+        state = pixels.mean() > (255 - self.getThreshold() * 255)
         # if state has changed, make an event
         if state != self.state[0]:
             if self.win._frameTimes:
                 frameT = logging.defaultClock.getTime() - self.win._frameTimes[-1]
             else:
                 frameT = 0
-            resp = PhotodiodeResponse(
+            resp = LightSensorResponse(
                 t=self.clock.getTime() - frameT,
                 value=state,
                 channel=0,
-                threshold=self._threshold
+                threshold=self._threshold,
+                device=self
             )
             self.receiveMessage(resp)
 
     def parseMessage(self, message):
         """
-        Events are created as PhotodiodeResponses, so parseMessage is not needed for
+        Events are created as LightSensorResponses, so parseMessage is not needed for
         ScreenBufferValidator. Will return message unchanged.
         """
         return message
@@ -615,8 +697,8 @@ class ScreenBufferSampler(BasePhotodiodeGroup):
     @staticmethod
     def getAvailableDevices():
         return [{
-            'deviceName': "Photodiode Emulator (Screen Buffer)",
-            'deviceClass': "psychopy.hardware.photodiode.ScreenBufferSampler",
+            'deviceName': "Light Sensor Emulator (Screen Buffer)",
+            'deviceClass': "psychopy.hardware.lightsensor.ScreenBufferSampler",
             'win': "session.win"
         }]
 
@@ -678,7 +760,7 @@ class ScreenBufferSampler(BasePhotodiodeGroup):
     def units(self, value):
         self._units = value
 
-    def findPhotodiode(self, win=None, channel=0):
+    def findSensor(self, win=None, channel=0):
         if win is None:
             win = self.win
         else:
@@ -686,7 +768,7 @@ class ScreenBufferSampler(BasePhotodiodeGroup):
         # handle None
         if channel is None:
             channel = 0
-        # there's no physical photodiode, so just pick a reasonable place for it
+        # there's no physical light sensor, so just pick a reasonable place for it
         self._pos = layout.Position((0.95, -0.95), units="norm", win=win)
         self._size = layout.Size((0.05, 0.05), units="norm", win=win)
         self.units = "norm"
@@ -701,146 +783,7 @@ class ScreenBufferSampler(BasePhotodiodeGroup):
         # handle None
         if channel is None:
             channel = 0
-        # there's no physical photodiode, so just pick a reasonable threshold
-        self.setThreshold(127, channel=channel)
+        # there's no physical light sensor, so just pick a reasonable threshold
+        self.setThreshold(0.5, channel=channel)
 
         return self.getThreshold(channel=channel)
-
-
-class PhotodiodeValidator:
-
-    def __init__(
-            self, win, diode, channel=None,
-            variability=1/60,
-            report="log",
-            autoLog=False):
-        # set autolog
-        self.autoLog = autoLog
-        # store window handle
-        self.win = win
-        # store diode handle
-        self.diode = diode
-        self.channel = channel
-        # store method of reporting
-        self.report = report
-        # set acceptable variability
-        self.variability = variability
-
-        from psychopy import visual
-        # black rect which is always drawn on win flip
-        self.offRect = visual.Rect(
-            win,
-            fillColor="black",
-            depth=1, autoDraw=True,
-            autoLog=False
-        )
-        # white rect which is only drawn when target stim is, and covers black rect
-        self.onRect = visual.Rect(
-            win,
-            fillColor="white",
-            depth=0, autoDraw=False,
-            autoLog=False
-        )
-        # update rects to match diode
-        self.updateRects()
-
-    def connectStimulus(self, stim):
-        # store mapping of stimulus to self in window
-        self.win.validators[stim] = self
-        stim.validator = self
-
-    def draw(self):
-        self.onRect.draw()
-
-    def updateRects(self):
-        """
-        Update the size and position of this validator's rectangles to match the size and position of the associated
-        diode.
-        """
-        for rect in (self.onRect, self.offRect):
-            # set units from diode
-            rect.units = self.diode.units
-            # set pos from diode, or choose default if None
-            if self.diode.pos is not None:
-                rect.pos = self.diode.pos
-            else:
-                rect.pos = layout.Position((0.95, -0.95), units="norm", win=self.win)
-            # set size from diode, or choose default if None
-            if self.diode.size is not None:
-                rect.size = self.diode.size
-            else:
-                rect.size = layout.Size((0.05, 0.05), units="norm", win=self.win)
-
-    def validate(self, state, t=None):
-        """
-        Confirm that stimulus was shown/hidden at the correct time, to within an acceptable margin of variability.
-
-        Parameters
-        ----------
-        state : bool
-            State which the photodiode is expected to have been in
-        t : clock.Timestamp, visual.Window or None
-            Time at which the photodiode should have read the given state.
-
-        Returns
-        -------
-        bool
-            True if photodiode state matched requested state, False otherwise.
-        """
-        # get and clear responses
-        messages = self.diode.getResponses(state=state, channel=self.channel, clear=True)
-        # if there have been no responses yet, return empty handed
-        if not messages:
-            return None, None
-
-        # if there are responses, get most recent timestamp
-        lastTime = messages[-1].t
-        # validate
-        valid = abs(lastTime - t) < self.variability
-
-        # construct message to report
-        validStr = "within acceptable variability"
-        if not valid:
-            validStr = "not " + validStr
-        logMsg = (
-            "Photodiode expected to receive {state} within {variability}s of {t}s. Actually received {state} at "
-            "{lastTime}. This is {validStr}."
-        ).format(
-            state=state, variability=self.variability, t=t, lastTime=lastTime, validStr=validStr
-        )
-
-        # report as requested
-        if self.report in ("log",):
-            # if report mode is log or error, log result
-            logging.debug(logMsg)
-        if self.report in ("err", "error") and not valid:
-            # if report mode is error, raise error for invalid
-            err = PhotodiodeValidationError(logMsg)
-            logging.error(err)
-            raise err
-        if callable(self.report):
-            # if self.report is a method, call it with args state, t, valid and logMsg
-            self.report(state, t, valid, logMsg)
-
-        # return timestamp and validity
-        return lastTime, valid
-
-    def resetTimer(self, clock=logging.defaultClock):
-        self.diode.resetTimer(clock=clock)
-
-    def getDiodeState(self):
-        return self.diode.getState()
-
-    @staticmethod
-    def onValid(isWhite):
-        pass
-
-    @staticmethod
-    def onInvalid(isWhite):
-        msg = "Stimulus validation failed. "
-        if isWhite:
-            msg += "Stimulus drawn when not expected."
-        else:
-            msg += "Stimulus not drawn when expected."
-
-        raise AssertionError(msg)