PCO MATLAB TE Cooled 26MPix sCMOS Camera User Manual

PCO MATLAB TE Cooled 26MPix sCMOS Camera

PCO asks you to carefully read and follow the instructions in this manual before using the pco.labview SDK.
For any questions or comments, contact us at PCO.

• telephone + 49 (0) 9441 2005 50
• fax 49 (0) 9441 2005 20
• email info@pco.de 
• postal address Excelitas PCO GmbH Donaupark 11 93309 Kelheim, Germany

The cover photo shows a real-world use of a PCO camera system. The lens is sold separately.

Released: November 2022 © Excelitas PCO GmbH
pco.matlab User Manual V1.17.0 © Excelitas PCO GmbH, Germany
This work is licensed under the Creative Commons Attribution-NoDerivatives 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nd/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.

INTRODUCTION

By using pco.matlab for PCO cameras, you cover three components in one package:
The pco.matlab adaptor (chapter 2) integrates your PCO camera(s) into the MATLAB image acquisition toolbox. This makes it very simple for you to conveniently control your camera system and acquire images in MATLAB without limitations.
With the pco.matlab flim package (chapter 3) you get a basic set of MATLAB functions. It helps you to compute phase and modulation depth images as well as lifetime images out of the camera’s raw data. Furthermore, the pco.flim white paper supports you with detailed explanations and mathematical descriptions.
The pco.matlab scripts (chapter 4) provide you a collection of example m-files. They support you to call functions from pco.sdk and pco.recorder directly from the MATLAB scripting language. The examples show how you initialize the camera and change camera settings, grab images from an operating camera or the camera’s internal memory. Grabbed images are displayed directly in a MATLAB figure window or collected in an image stack. Use MATLAB algorithm to further process the images from the image stack.

ADAPTOR FOR MATLAB

This chapter describes the use and the features of the pco.matlab adaptor for the MATLAB image acquisition toolbox.
The PCOCameraAdaptor.dll represents the actual adaptor which is used. Additionally a readme.txt is provided giving installation instructions. Several example script files show how to set up the camera and acquire images for different use cases, using the adaptor functions. The pco_imaqregister.m function provides the registration of the adaptor.
After having installed the adaptor according to the readme file it is possible to acquire images from pco cameras in two ways:

• You can completely work with commands either in the command window or by creating m- files for the image acquisition toolbox.
• The second possibility is to use the image acquisition GUI provided by MATLAB with graphical elements for properties and acquisition commands.

The adaptor supports all camera types.
Due to the toolbox structure only streaming is supported, it isn’t possible to read out camera RAM.
If reading camera RAM is required, script files for MATLAB have to be used (see chapter 4).
This adaptor is supported for MATLAB R2013b and later versions.

MATLAB IMAGE ACQUISITION GUI

The Image Acquisition GUI provided by MATLAB is an easy way to acquire images. The available cameras and their attributes are clearly arranged. The previewing and recording can be controlled by several buttons.
If you use the adaptor with this GUI there are a few restrictions:
Before changing the camera in the hardware browser, both preview and acquisition has to be stopped.
When having connected a camera with a high data transfer rate using MATLAB R2015b, previewing and recording should be performed in the MATLAB command window, because the GUI buttons will react with a certain delay, related to a bug in this specific MATLAB version. A practical way would be to adapt the camera settings in the GUI and after that create a video input and a video source object in the command window and copy the session log from the GUI to the command window.

RELATED MANUALS

To get more information on working with the image acquisition toolbox, have a look at the MATLAB Image Acquisition Toolbox User’s Guide.
For further information on the camera properties, read the latest pco.sdk manual.

GENERAL PROPERTIES

Every adaptor provides two general properties. Those are independent from adaptor type.

FramesPerTrigger
Set the number of images that should be acquired when starting the acquisition. (This value can also be set to infinite, and then an acquisition can only be stopped by calling stop.)

ReturnedColorspace
Set the color of the returned image. (The values that can be set here depend on the image type delivered by the camera. Using b/w cameras this property is not useful because it is not possible to get color information out of a grayscale image. For color cameras it is possible to switch between grayscale, RGB color and YCbCr representation.)

DEVICE SPECIFIC PROPERTIES

Most of the camera settings available in pco.camware are also available in the adaptor. Due to the structure of adaptor properties they are arranged in a different way. The device properties don’t belong to a video input object but to a video source object. Besides delay time, exposure time and frame rate, acquisition or preview is automatically stopped when changing a property, afterwards it will be restarted.

OVERVIEW

The following table shows an overview of all described device properties in alphabetical order and indicates if they are read-only and available for all cameras. Properties where the availability is specific are only visible if the camera supports them.

auto, extern or sequence triggered

| No| Specific

AMImageNumber

| Images to acquire for one acquisition pulse Will be ignored if acquire mode is auto or

extern.

|

No

|

Specific

B1BinningHorizontal

| Horizontal binning of the camera

The binning will reduce the resolution of the camera by the binning factor.

This also effects the hardware ROI Binning may change the pattern of color

cameras

|

No

|

Always

B2BinningVertical

| Vertical binning of the camera

The binning will reduce the resolution of the camera by the binning factor

This also effects the hardware ROI Binning may change the pattern of color

cameras

|

No

|

Always

CFConversionFactor_e_cou nt| Conversion factor of the camera| No| Always
D1DelayTime_unit| Time base of delay time (ns, us, ms)| No| Always

D2DelayTime

| Delay time of the camera. Value is in the selected unit

Can only be set for some cameras

Will be ignored if FMFpsBased is set to on

| No If

selectable

|

Always

D3DelayMin_time_ns| Min delay time in nanoseconds| Yes| Always
D4DelayMax_time_ms| Max delay time in milliseconds| Yes| Always
D5DelayMin_step_ns| Min delay step in nanoseconds| Yes| Always

DPCorePreparation

| Switches DPCore preparation on/off. Will appear if Jetraw is installed or if the

DPCore DLLs reside in the adaptor folder. The property is active if the camera is deposited in the DPCore, otherwise grayed

out.

|

No

|

Specific

E1ExposureTime_unit| Time base of exposure time (ns ,us, ms)| No| Always
E2ExposureTime| Exposure time of the camera Value is in the selected unit| No| Always
E3ExposureMin_time_ns| Min exposure time in nanoseconds| Yes| Always
E4ExposureMax_time_ms| Max exposure time in milliseconds| Yes| Always
E5ExposureMin_step_ns| Min exposure step in nanoseconds| Yes| Always
FlimIPAsymCorrection| Switch asymmetry correction on/off| No| Specific
FlimMPMasterFrequency_Hz| Master modulation frequency in Hz| No| Specific
FlimMPModulationSource| Select the modulation source intern/extern| No| Specific
FlimMPOutputWaveform| Select the output waveform none/sine/square| No| Specific
FlimMPRelativePhase_mdeg| Relative phase in millidegree| No| Specific
FlimPSAddPhaseSampling| Switch additional phase sampling (phase symmetry) yes/no| No| Specific
FlimPSPhaseNumber| Phase number| No| Specific
FlimPSPhaseOrder| Phase order (ascending/opposite)| No| Specific
FlimPSTapSelection| Selected tap(s) Tap A/Tap B/Tap A+B| No| Specific
Property| Description| Read-only| Availability
---|---|---|---

FMFpsBased

| Select if exposure time is set together with delay time (off) or frame rate (on)

Can only be set to on if trigger mode is not hardware triggered

|

No

|

Specific

FRFrameRate| Frame rate of the camera in mHz Will be ignored if FMFpsBased is off| No| Specific

H1HardwareROI_X_Offset

| Horizontal offset for HW ROI

Can only be set for some cameras

Changing Hardware ROI may change the pattern of color cameras

| No if

selectable

|

Always

H2HardwareROI_Width

| Width for HW ROI

Can only be set for some cameras

Changing Hardware ROI may change the pattern of color cameras

If horizontal ROI has to be symmetric, changes in width will be reset and horizontal ROI can only be

changed by the x offset

|

No if

selectable

|

Always

H3HardwareROI_Hor_Sym| Indicator if horizontal hardware ROI has to be symmetric| Yes| Always

H4HardwareROI_Y_Offset

| Vertical offset for HW ROI

Can only be set for some cameras

Changing Hardware ROI may change the pattern of color cameras

| No if

selectable

|

Always

H5HardwareROI_Height

| Height for HW ROI

Can only be set for some cameras

Changing Hardware ROI may change the pattern of color cameras

If vertical ROI has to be symmetric, changes in

height will be reset and vertical ROI can only be changed by the y offset

|

No if

selectable

|

Always

H6HardwareROI_Vert_Sym| Indicator if vertical hardware ROI has to be symmetric| Yes| Always
IO_x_SignalEnableDisabel| Enable/disable IO signal at port x| No| Specific
IO_x_SignalName| Select name of signal that should be connected with IO port x| No| Specific
IO_x_SignalPolarity| Polarity of IO signal at port x| No| Specific
IO_x_SignalType| Type of IO signal at port x| No| Specific
IRMode| Switch IR sensitivity on/off| No| Specific
NFNoiseFilter| Switch noise filter on/off| No| Specific
PCPixelclock_Hz| Pixel rate

Will set the FMFpsBased to off if available

| No| Always
RDIDoubleImageMode| Switch double image mode on/off

See Annotations for property description

| No| Specific
SCMOSReadoutMode| Readout mode setting for pco.edge cameras This parameter is only available for pco.edge

cameras in Rolling Shutter

| No| Specific

SFSensorFormat

| Sensor format of the camera.

In the format [standard], only affective pixels are read out from the sensor. The readout in the format [extended] is camera dependent. This also affects the hardware ROI. The sensor format may

change the pattern of color cameras.

|

No

|

Always

SMShutterMode

| Shutter mode

If shutter mode is changed, the adaptor has to be refreshed/reset

|

No

|

Specific

TMTimestampMode| Timestamp mode

No Stamp, Binary, BinaryAndAscii, Ascii

| No| Specific

Table 1 – properties overview

ANNOTATIONS

AMAcquireMode
If acquire mode is set to extern or sequence triggered, the acquisition is controlled by an external source. If high or low state is effective depends on the settings of the IO signal properties for the acquire enable port. AMImageNumber property will only be created, if sequence trigger mode is available.

FMFpsBased
If frame rate and exposure time are set, it can occur that the values are trimmed by the camera. If the selected exposure time is too high for the current frame rate, the frame rate will be trimmed and updated. If the selected frame rate is too high, the exposure time will be trimmed and updated.

IRMode
Since there are different minimal and maximal exposure times for IR sensitivity on and off, changing IR mode will change min and max exposure time and perhaps (if current exposure time exceeds the new range) also the current exposure time.

RDIDoubleImageMode
If double image mode is set to “on”, the camera will record two images directly after each other instead of just one image. In the adaptor the two images are treated as one with doubled height (first image on top, second on bottom). Setting some hardware ROI (if possible for the specific camera) will affect each of the two images individually (as expected). Setting the soft ROI of the pco.matlab adaptor will affect the two images as one, i.e. setting a y-offset of 10 means cutting off the first 10 lines of the upper image, while the second image will not be affected. If the images should be saved in separated files, the separation has to be done programmatically.

LOGGING ACQUIRED IMAGES

For saving acquired images the toolbox provides three options:

• Memory: Log the images to memory. They can be exported after acquisition.
• Disk: Log the data directly to disk. Therefore a file has to be selected / created where the images will be saved.
• Disk &Memory: Log to memory and to disk.

TRIGGERING

For triggering two parameters can be changed.

Number of triggers
This parameter sets the number of triggers you want to wait for. Using as a command you have to set the TriggerRepeat property, which is always one less than the number of triggers.

Trigger type
This parameter sets the trigger type. Here three options are available:

• Immediate: Acquisition is started directly by calling start
• Manual: Calling start enables acquisition. Acquisition starts by calling the trigger command
• Hardware: Acquisition is controlled by an external source. The availability of trigger sources depend on the camera type
  • ExternExposureStart: An image is taken when an external signal rises or falls (depends on the IO settings)
  • ExternExposureCtrl: An image is taken when an external signal rises or falls (depends on the IO settings). The exposure time is controlled by the length of the external pulse.

REGION OF INTEREST

In addition to the hardware ROI property provided by the camera, MATLAB is also able to perform software ROI. You can select the horizontal and vertical offset and also the image width and height you want to have.
According to these settings the toolbox cuts the delivered image. The range of the four values is limited by the camera resolution, the selected hardware ROI and binning.

TROUBLESHOOTING

The camera adaptor also supports a troubleshooting. If there are problems, you can force the adaptor to write the workflow into a log file by creating a file called sc2_imaq_adaptor.log in the following directory (CSIDL_COMMON_APPDATA\pco):
On Windows 7/10 (or Vista): :\ProgramData\pco\

FLIM PACKAGE

INTRODUCTION

The pco.matlab flim package contains a complete set of MATLAB functions to cover a pco.flim workflow. A function to rearrange the raw data recorded with the pco.flim in a general linear phase sequence is also provided. Please refer to the pco.flim white paper for detailed explanations and mathematical descriptions.
The functions in section 3.2.1 were designed to be independent from the used MATLAB version. Nevertheless, the MATLAB version 2017a or higher in conjunction with the Image Processing Toolbox and the Image Acquisition Toolbox is recommended to benefit from the correct display of the color bars in the lifetime figures when using the example functions in sections 3.2.2 and 3.2.3.

FILE ORGANIZATION

Each MATLAB function is encapsulated into one file whose filename equals the function name. The directory flim_functions provides general FLIM functions. The directories flim_example_file and flim_example_memory provide examples incorporating these general functions.

FLIM FUNCTIONS

The following functions were designed to be used as independent modules which represent the separate steps in the computation of FLIM images. Such steps are the rearrangement of phase images recorded with the pco.flim in a linear phase image stack, the computation of modulation depth and phase images, the referencing procedure to cancel influences induced by the measurement setup, and the computation of lifetime images.
If applicable, all functions offer either distinct modulation depth and phase images or their combination in the form of complex phasors as intermediate or final results.

flim_rearrange_stack

• Description:
  When recording phase image stacks using the pco.flim the sorting of the taps and phases is dependent on several camera configuration parameters. In order to rearrange these phase images in a linearly ascending sequence for further interpretation and calculations the following function can be used.
  A more detailed description of these parameters can be found in the pco.flim manual (subsection FLIM setup in chapter pco.camware 4 software).

• Prototype:

• Supported camera type:
  **** pco.flim

• Parameter:

Return value:

flim_numeric_harmonic_analysis

• Description:
  With a given sequence of linearly ascending phase images, the following function can be used to compute the parameters of a specified harmonic for each pixel. Such are the modulation index (i.e. modulation depth), the phase and the normalized intensity (i.e. constant value). In most cases the fundamental, i.e. the first harmonic, is computed.

• Prototype:

Supported camera type:
pco.flim

Parameter:

Return value:

flim_numeric_harmonic_analysis_phasor

Description:
This function equals the function in section 3.2.1.2 except that the computed modulation index image and the phase image are combined into an image of complex values called ‘phasors’. The mathematical relationship is given by
pxy = mxye∅xy ,
with the phasor xy, the modulation index xy and the phase φxy for each pixel with the coordinates (x, y).
The advantage of complex notation is the simplification of the algebra needed for the description of transfer functions, since MATLAB is capable of handling complex numbers.

Prototype:

Supported camera type:
pco.flim

Parameter:

Return value:

flim_referencing

• Description:
  Since each single FLIM measurement is influenced by the response of the overall setup (pco.flim camera, light source, optical pathways, cables) a reference measurement is needed to correct for this. In most cases a photoluminescent sample with a known luminescence lifetime is used as a reference.
  The following function computes referenced modulation index and phase images using the single results of the reference and sample measurements.

• Prototype:

• Supported camera type:
  pco.flim

• Parameter:

Return value:

flim_referencing_phasor

• Description:
  This function equals the function in section 3.2.1.4 except that phasor images are used as input parameters and return value.

• Prototype:

• Supported camera type:
  pco.flim

• Parameter:

Return value:

flim_get_lifetimes

• Description:
  Assuming that the measured samples can be characterized by first-order low- pass systems (monoexponential behavior) their single time constants (lifetimes) can be computed by means of the (referenced) modulation indices and phases using the following function.

• Prototype:
  

• Supported camera type:
  pco.flim
  

• Parameter:

Return value:

flim_get_lifetimes_phasor

• Description:
  This function equals the function in section 3.2.1.6 except that a phasor image is used as input parameter.

• Prototype:

• Supported camera type:
  pco.flim

• Parameter:

Return value:

EXAMPLE USING MULTI-TIFF FILES

• Description:
  The following function incorporates the functions mentioned in section 3.2.1 to demonstrate a complete FLIM workflow using multi-TIFF files as raw input. In addition to the input parameters described in that section there are parameters to specify the reference and sample files containing the raw data as well as displaying options for the results. After the completion of the FLIM computation a normalized intensity image and two lifetime images based on the modulation index and phase are displayed.

• Prototype:

• Supported camera type:
  pco.flim

• Parameter (excerpt):

A script which calls the above function with predefined parameters and input filenames is provided by the following file:
flim_example_file_script.m

EXAMPLE USING MATLAB MEMORY DATA

• Description:
  In case the raw image stacks containing the phase images are already available in the MATLAB memory, e.g. recorded by means of the Image Acquisition Toolbox in conjunction with the pco.matlab adaptor, the following function can be used to compute and display the FLIM results in a simple way. The computation workflow is the same as in section 3.2.2.

• Prototype:

• Supported camera type:
  pco.flim

• Parameter (excerpt):

A typical call in the MATLAB console using the data recorded with the Image Acquisition Toolbox could look like this:

As all input stacks must be three-dimensional the four-dimensional access is based on how the toolbox stores gray value images in a sequence.

SDK EXAMPLE SCRIPTS

The pco.matlab scripts provide a collection of example m-files. The necessary dll-files and additional header files are included.

The script files contain examples for camera setup, grabbing images to a MATLAB image stack and displaying them in a figure window. There are also examples, which show how to work with the pco.recorder from script file.
Only a subset of all possible camera settings is covered by the examples. For further setup see the pco.sdk description.
When working on a 64 bit Windows system a C-compiler must be installed to enable MATLAB to use external dll’s. See also http://de.mathworks.com/support/compilers/current_release/
To run the example code open MATLAB and select the install directory.
Call the script setup_files (which does the following steps)
Or manually:

• Depending on your environment copy the dll files either from the runtime\bin (32 bit) or the runtime\bin64 (64 bit) directory to the install directory.
• Copy the header files from the runtime\include directory to the install directory.
• Depending on the installed MATLAB version copy the pco_uint.m and pco_uinterr.m from the ver_7 or ver_8 directory.
• Call pco_camera_create_deffile.m, which will create a pco_camera_def.txt file with header definitions.

All m-files whose names start with pco_camera have subfunctions included, which can be used in other files or also standalone.
All m-files whose names start with pco_sdk_example are examples with different functionality. All files include helptext which can be shown with the MATLAB command help.
i.E. help pco_sdk_example_stack
All scripts output some text to the command window using MATLAB disp() function to show processing steps and give some information. This helps to evaluate the correct behavior of
camera and script code.
A short description of the example files follows.

GENERAL

All m-files use a common structure glvar.
Setting variables of this structure different behaviour of loading/unloading SDK library and open/close of the camera could be accomplished.
All example code was tested with different MATLAB versions in 64 bit.
When writing your own m-files it might happen that MATLAB does stop due to syntax or other error. Therefore all examples are built with MATLAB exception handling, which on error does close the camera, unload the sc2_cam library and if necessary the pco_recorder library and does show the error source.
With pco_reset_camlib and/or pco_reset_recorder the libraries can be set to an init state again.

SDK EXAMPLES

The pco_sdk examples show how to setup and use the pco.sdk API within MATLAB. For a simple test call pco_camera_info.m m-file
pco_camera_info();
This should output some messages about camera type and camera revisions

PCO_sdk_example_single

• Description:
  Grab and display a single image with selectable trigger mode and exposure time.
  pco_sdk_example_single() does use subfunctions from pcocamera() and draw_image().

• Supported camera type:
  All cameras

• Prototype:

Parameter:

Return value:

PCO_sdk_example_swtrig

• Description:
  Grab and display a single software triggered image with selectable exposure time. pco_sdk_example_swtrig() does use direct SDK calls and imshow().

• Supported camera type:
  All cameras

• Prototype:

Parameter:

Return value:

PCO_sdk_example_live_getima

• Description:
  Start camera, grab and display images in a loop.
  pco_sdk_example_live_getima does use subfunctions from pcocamera() and draw_image() and grab with SDK-function PCO_GetImageEx with a single buffer.

• Supported camera type:
  All cameras

• Prototype:

• Parameter:****

Return value:

PCO_sdk_example_live_add

• Description:
  Start camera, grab and display images in a loop.
  pco_sdk_example_live_add() uses subfunctions from pcocamera() and draw_image() and grab images with SDK-functions PCO_AddBuffer and PCO_WaitforBuffer with four buffers.

• Supported camera type:
  All cameras

• Prototype:

• Parameter:

Return value:

PCO_sdk_example_stack

• Description:
  Grab images from a streaming camera directly to an image stack.
  The image_stack is transposed before returned to workspace.
  The returned image_stack can be displayed with one of the draw_images functions.

• Supported camera type:
  All cameras

• Prototype:

• Parameter:

Return value:

PCO_sdk_example_read

• Description:
  Grab images into camera internal memory and readout afterwards.
  The pco_sdk_example_read() does use subfunctions from pcocamera().
  Read is done with SDK-functions PCO_AddBuffer and PCO_WaitforBuffer with four buffers.

• Supported camera type:
  All cameras with internal memory

• Prototype:

• Parameter:

Return value:

metadata are available and enabled

RECORDER EXAMPLES

The pco.recorder is built on top of the SDK and forms an API with reduced amount of functions to simplify acquiring and retrieving images compared to the raw pco_sdk functions. The pco_sdk_recorder examples show how to setup and use the pco.recorder API within MATLAB.

PCO_sdk_example_recorder

• Description:
  Set variables and grab images with the pco.recorder from a single pco.camera. The camera is opened within pco.sdk before the recorder functions are called. When recording has been done, imagedata is copied from recorder memory to a MATLAB array.

• Supported camera type:
  All cameras

• Prototype:

• Parameter:

Return value:

References

• CC BY-ND 4.0 Deed | Attribution-NoDerivs 4.0 International | Creative Commons
• Compilers - MATLAB & Simulink

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>