Source code for

#!/usr/bin/env python
# -*- coding: utf-8 -*-

# Part of the PsychoPy library
# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2022 Open Science Tools Ltd.
# Distributed under the terms of the GNU General Public License (GPL).

# Acknowledgements:
#    This code was mostly written by Jon Peirce.
#    CRS Ltd provided support as needed.

# Acknowledgements
#    This code was written by Jon Peirce

import sys
    import serial
except Exception:
    serial = False
import numpy

__docformat__ = "restructuredtext en"

# try to use psychopy logging but revert to system logging
    from psychopy import logging  # from 1.73 onwards
except ImportError:
    import logging  # use the standard python logging
eol = "\n\r"  # unusual for a serial port?!

[docs]class ColorCAL: """A class to handle the CRS Ltd ColorCAL device """ # PsychoPy uses these two variables for matching classes to photometers longName = "CRS ColorCAL" driverFor = ["colorcal"] def __init__(self, port=None, maxAttempts=2): """Open serial port connection with Colorcal II device :Usage: cc = ColorCAL(port, maxAttempts) If no port is provided then the following defaults will be tried: - /dev/cu.usbmodem0001 (OSX) - /dev/ttyACM0 - COM3 (windows) """ super(ColorCAL, self).__init__() if not serial: raise ImportError('The module serial is needed to connect to ' 'photometers. On most systems this can be ' 'installed with\n\t easy_install pyserial') # try to deduce port if port is None: if sys.platform == 'darwin': port = '/dev/cu.usbmodem0001' elif sys.platform.startswith('linux'): port = '/dev/ttyACM0' elif sys.platform.startswith('win'): port = 3 if type(port) in (int, float): # add one so that port 1=COM1 self.portNumber = port self.portString = 'COM%i' % self.portNumber else: self.portString = port self.portNumber = None self.isOpen = 0 self.lastLum = None self.lastCmd = '' self.type = 'ColorCAL' = False self.OK = True # until we fail self.maxAttempts = maxAttempts self._zeroCalibrated = False # try to open the port try: = serial.Serial(self.portString) except Exception: msg = ("Couldn't connect to port %s. Is it being used by " "another program?") self._error(msg % self.portString) # setup the params for serial port if self.OK: # not sure why this helps but on win32 it does!! try: # actually, any baudrate is fine? except: = 115200 # setBaudrate() remov pyserial v3.0 try: if not except Exception: msg = "Opened serial port %s, but couldn't connect to ColorCAL" self._error(msg % self.portString) else: self.isOpen = 1 # check that we can communicate with it self.ok, self.serialNum, self.firm, self.firmBuild = self.getInfo() self.calibMatrix = self.getCalibMatrix()
[docs] def sendMessage(self, message, timeout=0.1): """Send a command to the photometer and wait an allotted timeout for a response. """ # flush the read buffer first # read as many chars as are in the buffer prevOut ='utf-8') if len(prevOut) and prevOut not in ('>' + eol, eol): # do not use log messages here print('Resp found to prev cmd (%s):%s' % (self.lastCmd, prevOut)) self.lastCmd = message if type(message) is not bytes: message = message.encode('utf-8') if not (message.endswith(b'\n') or message.endswith(b'\n\r')): message += b"\n" # append a newline if necess # send the message # get reply (within timeout limit) = timeout logging.debug('Sent command:%s' % (message[:-1])) # send complete msg # get output lines using self.readline, not # colorcal signals the end of a message by giving a command prompt lines = [] thisLine = '' nEmpty = 0 while (thisLine != '>') and (nEmpty <= self.maxAttempts): # can't handle custom eol thisLine = self.readline(eol=eol).decode('utf-8') if thisLine in (eol, '>', ''): # lines we don't care about nEmpty += 1 continue else: # line without any eol chars lines.append(thisLine.strip(eol)) nEmpty = 0 # got all lines and reached '>' if len(lines) == 1: return lines[0] # return the string else: return lines # a list of lines
[docs] def measure(self): """Conduct a measurement and return the X,Y,Z values Usage:: ok, X, Y, Z = colorCal.measure() Where: ok is True/False X, Y, Z are the CIE coordinates (Y is luminance in cd/m**2) Following a call to measure, the values ColorCAL.lastLum will also be populated with, for compatibility with other devices used by PsychoPy (notably the PR650/PR655) """ # use a long timeout for measurement: val = self.sendMessage('MES', timeout=5) valstrip = val.strip('\n\r>') vals = valstrip.split(',') ok = (vals[0] == 'OK00') # transform raw x,y,z by calibration matrix xyzRaw = numpy.array([vals[1].strip(), vals[2].strip(), vals[3].strip()], dtype=float) X, Y, Z =, xyzRaw) self.ok, self.lastLum = ok, Y return ok, X, Y, Z
[docs] def getLum(self): """Conducts a measurement and returns the measured luminance .. note:: The luminance is always also stored as .lastLum """ self.measure() return self.lastLum
[docs] def getInfo(self): """Queries the device for information usage:: (ok, serialNumber, firmwareVersion, firmwareBuild) = colorCal.getInfo() `ok` will be True/False Other values will be a string or None. """ val = self.sendMessage(b'IDR') valstrip = val.strip('\n\r>') val = valstrip.split(',') ok = (val[0] == 'OK00') if ok: firmware = val[2] serialNum = val[4] firmBuild = val[-1] else: firmware = 0 serialNum = 0 firmBuild = 0 return ok, serialNum, firmware, firmBuild
[docs] def getNeedsCalibrateZero(self): """Check whether the device needs a dark calibration In initial versions of CRS ColorCAL mkII the device stored its zero calibration in volatile memory and needed to be calibrated in darkness each time you connected it to the USB This function will check whether your device requires that (based on firmware build number and whether you've already done it since python connected to the device). :returns: True or False """ if self.firmBuild < '877' and not self._zeroCalibrated: return True else: return False
[docs] def calibrateZero(self): """Perform a calibration to zero light. For early versions of the ColorCAL this had to be called after connecting to the device. For later versions the dark calibration was performed at the factory and stored in non-volatile memory. You can check if you need to run a calibration with:: ColorCAL.getNeedsCalibrateZero() """ val = self.sendMessage(b"UZC", timeout=1.0) val = val.strip('\n\r>') if val == 'OK00': pass elif val == 'ER11': logging.error( "Could not calibrate ColorCAL2. Is it properly covered?") return False else: # unlikely logging.warning( "Received surprising result from ColorCAL2: %s)" % repr(val)) return False # then take a measurement to see if we are close to zero lum (ie is it # covered?) self.ok, x, y, z = self.measure() if y > 3: logging.error('There seems to be some light getting to the ' 'detector. It should be well-covered for zero ' 'calibration') return False self._zeroCalibrated = True self.calibMatrix = self.getCalibMatrix() return True
[docs] def getCalibMatrix(self): """Get the calibration matrix from the device, needed for transforming measurements into real-world values. This is normally retrieved during __init__ and stored as `ColorCal.calibMatrix` so most users don't need to call this function. """ matrix = numpy.zeros((3, 3), dtype=float) # alternatively use 'r99' which gets all rows at once, but then more # parsing? for rowN in range(3): rowName = 'r0%i' % (rowN + 1) val = self.sendMessage(rowName.encode('ascii'), timeout=1.0) valstrip = val.strip('\n\r>') vals = valstrip.split(',') # convert to list of values if vals[0] == 'OK00' and len(vals) > 1: # convert to numpy array rawVals = numpy.array(vals[1:], dtype=int) floats = _minolta2float(rawVals) matrix[rowN, :] = floats else: msg = 'ColorCAL got this from command %s: %s' print(msg % (rowName, repr(val))) return matrix
def _error(self, msg): self.OK = False logging.error(msg)
[docs] def readline(self, size=None, eol='\n\r'): """This should be used in place of the standard serial.Serial.readline() because that doesn't allow us to set the eol character """ # The code here is adapted from # pyserial 2.5: serialutil.FileLike.readline # which is released under the python license. # Copyright (C) 2001-2010 Chris Liechti leneol = len(eol) line = bytearray() while True: # NB timeout is applied here, so to each char read c = if c: line += c if line[-leneol:] == eol: break if size is not None and len(line) >= size: break else: break return bytes(line).strip()
def _minolta2float(inVal): """Takes a number, or numeric array (any shape) and returns the appropriate float. minolta stores; +ve values as val * 10000 -ve values as -val * 10000 + 50000 >>> _minolta2Float(50347) # NB returns a single float -0.034700000000000002 >>> _minolta2Float(10630) 1.0630999999999999 >>> _minolta2Float([10635, 50631]) # NB returns a numpy array array([ 1.0635, -0.0631]) """ # convert to array if needed arr = numpy.asarray(inVal) # handle single vals if arr.shape == (): if inVal < 50000: return inVal/10000.0 else: return (-inVal + 50000.0)/10000.0 # handle arrays negs = (arr > 50000) # find negative values out = arr/10000.0 # these are the positive values out[negs] = (-arr[negs] + 50000.0)/10000.0 return out

Back to top