Support for Princeton Instruments’ PICam Library - picam

Python wrapper around Princeton Instruments’ PICam camera SDK using ctypes. This version has been partly inspired by Joe Lowney’s GitHub project (https://github.com/joelowney/PythonForPicam).

In order to run this module, you have to have the PICam library, provided by Princeton Instruments at ftp://ftp.princetoninstruments.com/Public/Software/Official/PICam, installed on your computer. The module looks for Picam.dll either at a path provided by the user or at the path provided in the environment variable PicamRoot, which is created by the PICam installer.

Note

This version of picam was developed under Python 2.7 and does not yet run under Python 3 mainly due to the changed print syntax.

Basic interface to Princeton Instrument’s PICam library. It supports most of the standard features that are provided by PICam. I have decided not to implement a non-blocking version of the image acquisition in order to keep things clear and simple.

Here is some example code showing the necessary parameters to get 1 kHz readout rates on a PIXIS100:

from picam import *

# initialize camera class and connect to library, look for available camera and connect to first one
cam = picam()
cam.loadLibrary()
cam.getAvailableCameras()
cam.connect()

# this will cool down CCD
cam.setParameter("SensorTemperatureSetPoint", -75)

# shortest expoure
cam.setParameter("ExposureTime", 0)

# readout mode
cam.setParameter("ReadoutControlMode", PicamReadoutControlMode["FullFrame"])

# custom chip settings
cam.setROI(0, 1339, 1, 0, 99, 100)
cam.setParameter("ActiveWidth", 1340)
cam.setParameter("ActiveHeight", 100)
cam.setParameter("ActiveLeftMargin", 0)
cam.setParameter("ActiveRightMargin", 0)
cam.setParameter("ActiveTopMargin", 8)
cam.setParameter("ActiveBottomMargin", 8)
cam.setParameter("VerticalShiftRate", 3.2)    # select fastest

# set logic out to not ready
cam.setParameter("OutputSignal", PicamOutputSignal["Busy"])

# shutter delays; open before trigger corresponds to shutter opening pre delay
cam.setParameter("ShutterTimingMode", PicamShutterTimingMode["Normal"])
cam.setParameter("ShutterClosingDelay", 0)

# sensor cleaning
cam.setParameter("CleanSectionFinalHeightCount", 1)
cam.setParameter("CleanSectionFinalHeight", 100)
cam.setParameter("CleanSerialRegister", False)
cam.setParameter("CleanCycleCount", 1)
cam.setParameter("CleanCycleHeight", 100)
cam.setParameter("CleanUntilTrigger", True)

# sensor gain settings
# according to manual, Pixis supports 100kHz and 2MHz; select fastest
cam.setParameter("AdcSpeed", 2.0)
cam.setParameter("AdcAnalogGain", PicamAdcAnalogGain["Low"])
cam.setParameter("AdcQuality", PicamAdcQuality["HighCapacity"])

# trigger and timing settings
cam.setParameter("TriggerDetermination", PicamTriggerDetermination["PositivePolarity"])
cam.setParameter("TriggerResponse", PicamTriggerResponse["ReadoutPerTrigger"])

# send configuration
cam.sendConfiguration()

# get readout speed
print "Estimated readout time = %f ms" % cam.getParameter("ReadoutTimeCalculation")

cam.disconnect()
cam.unloadLibrary()
class picam.picam

Main class that handles all connectivity with library and cameras.

addROI(x0, w, xbin, y0, h, ybin)

Add a region-of-interest to the existing list of ROIs.

Important

The ROIs should not overlap! However, this function does not check for overlapping ROIs!

Parameters:
  • x0 (int) – X-coordinate of upper left corner of ROI.
  • w (int) – Width of ROI.
  • xbin (int) – X-Binning, i.e. number of columns that are combined into one larger column (1 to w).
  • y0 (int) – Y-coordinate of upper left corner of ROI.
  • h (int) – Height of ROI.
  • ybin (int) – Y-Binning, i.e. number of rows that are combined into one larger row (1 to h).
connect(camID=None)

Connect to camera.

Parameters:camID (int) – Number / index of camera to connect to (optional). It is an integer index into a list of valid camera IDs that has been retrieved by getAvailableCameras(). If camID is None, this functions connects to the first available camera (default).
disconnect()

Disconnect current camera.

getAvailableCameras()

Queries a list of IDs of cameras that are connected to the computer and prints some sensor information for each camera to stdout.

If no physical camera is found, a demo camera is initialized - for debug only.

getBuffer(address, size)

This is an internally used function to convert the readout buffer into a sequence of numpy arrays. It reads all available data at once into a numpy buffer and reformats data to a usable format.

Parameters:
  • address (long) – Memory address where the readout buffer is stored.
  • size (int) – Number of readouts available in the readout buffer.
Returns:

List of ROIS; for each ROI, array of readouts; each readout is a NxM array.

getCurrentCameraID()

Returns the current camera ID (PicamCameraID).

getLastError()

Returns the identifier associated with the last error (str).

getLibraryVersion()

Returns the PICam library version string.

getParameter(name)

Reads and returns the value of the parameter with given name. If there is no parameter of this name, the function returns None and prints a warning.

Parameters:name (str) – Name of the parameter exactly as stated in the PICam SDK manual.
Returns:Value of this parameter with data type corresponding to the type of parameter.
loadLibrary(pathToLib='')

Loads the picam library (‘Picam.dll’) and initializes it.

Parameters:pathToLib (str) – Path to the dynamic link library (optional). If empty, the library is loaded using the path given by the environment variabel PicamRoot, which is normally created by the PICam SDK installer.
Returns:Prints the library version to stdout.
printAvailableParameters()

Prints an overview over the parameters to stdout that are available for the current camera and their limits.

readNFrames(N=1, timeout=100)

This function acquires N frames using Picam_Acquire. It waits till all frames have been collected before it returns.

Parameters:
  • N (int) – Number of frames to collect (>= 1, default=1). This number is essentially limited by the available memory.
  • timeout (float) – Maximum wait time between frames in milliseconds (default=100). This parameter is important when using external triggering.
Returns:

List of acquired frames.

sendConfiguration()

This function has to be called once all configurations are done to apply settings to the camera.

setParameter(name, value)

Set parameter. The value is automatically typecast to the correct data type corresponding to the type of parameter.

Note

Setting a parameter with this function does not automatically change the configuration in the camera. In order to apply all changes, sendConfiguration() has to be called.

Parameters:
  • name (str) – Name of the parameter exactly as stated in the PICam SDK manual.
  • value (mixed) – New parameter value. If the parameter value cannot be changed, a warning is printed to stdout.
setROI(x0, w, xbin, y0, h, ybin)

Create a single region of interest (ROI).

Parameters:
  • x0 (int) – X-coordinate of upper left corner of ROI.
  • w (int) – Width of ROI.
  • xbin (int) – X-Binning, i.e. number of columns that are combined into one larger column (1 to w).
  • y0 (int) – Y-coordinate of upper left corner of ROI.
  • h (int) – Height of ROI.
  • ybin (int) – Y-Binning, i.e. number of rows that are combined into one larger row (1 to h).
status(err)

Checks the return value of a picam function for any error code. If an error occurred, it prints the error message to stdout.

Parameters:err (int) – Error code returned by any picam function call.
Returns:Error code (int) and if an error occurred, prints error message.
unloadLibrary()

Call this function to release any resources and free the library.

updateROIS()

Internally used utility function to extract a list of pixel sizes of ROIs.

picam.ptr(x)

Shortcut to return a ctypes.pointer to object x.