EXCELITAS TECHNOLOGIES Python Software Development Kit User Manual

: June 9, 2024
: EXCELITAS TECHNOLOGIES

Table of Contents

Python Software Development Kit
General
API Documentation
References
Read User Manual Online (PDF format)
Download This Manual (PDF format)

Python Software Development Kit
User Manual

Python Software Development Kit

PCO asks you to carefully read and follow the instructions in this document.
For any questions or comments, please feel free to contact us at any time.
telephone: +49 (0) 9441 2005 50
fax: +49 (0) 9441 2005 20
postal address: Excelitas PCO GmbH Donaupark 11 93309 Kelheim, Germany
email: info@pco.de
web: www.pco.de
pco.python user manual 0.1.7
Released December 2021
©Copyright Excelitas PCO GmbH
This work is licensed under the Creative Commons Attribution-No Derivatives 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.

General

The Python package pco offers all functions for working with pco cameras that are based on the current pco.sdk. All shared libraries for the communication with the camera and subsequent image processing are included.

Easy to use camera class
Powerful API to pco.sdk
Image recording and processing with pco.recorder

1.1 Installation
Install from pypi (recommended):
$ pip install pco
1.2 Basic Usage
import matplotlib.pyplot as plt
import pco
with pco.Camera() as cam:
cam.record()
image, meta = cam.image()
plt.imshow(image, cmap=’gray’)
plt.show() EXCELITAS TECHNOLOGIES Python Software Development Kit - Basic
Usage 1.3 Event and Error Logging
To activate the logging output, create the Camera object with the debuglevel= parameter.
The debug level can be set to one of the following values:

‘off’ Disables all output.
‘error’ Shows only error messages.
‘verbose’ Shows all messages.
‘extra verbose’ Shows all messages and values.

The default debuglevel is ‘off’.
pco.Camera(debuglevel=’verbose’)
…
[][sdk] get_camera_type: OK.
The optional timestamp= parameter activates a tag in the printed output. Possible values are: ‘on’ and ‘off’. The default value is ‘off’.
pco.Camera(debuglevel=’verbose’, timestamp=’on’)
…
[2019-11-25 15:54:15.317855 / 0.016 s] [][sdk] get_camera_type: OK.

API Documentation

The pco.Camera class offers the following methods:

record() generates, configures, and starts a new recorder instance.
stop() stops the current recording.
close() closes the current active camera and releases the occupied ressources.
image() returns an image from the recorder as numpy array.
images() returns all recorded images from the recorder as a list of numpy arrays.
image_average() returns the averaged image. This image is calculated from all recorded images in the buffer.
set_exposure_time() sets the exposure time for the camera.
wait_for_first_image() waits for the first available image in the recorder memory.

The pco.Camera class has the following variable:

configuration

The pco.Camera class has the following objects:

sdk offers direct access to all underlying functions of the pco.sdk.
recorder offers direct access to all underlying functions of the pco.recorder.

2.1 Methods
This section describes all methods offered by the pco.Camera class.
2.1.1 Record
Description Creates, configures, and starts a new recorder instance. The entire camera configuration must be set before calling record(). The set_exposure_time() command is the only exception. This function has no effect on the recorder object and can be called up during the recording.
Prototype def record(self, number_of_images=1, mode=’sequence’):
Parameter

Name	Description
number_of_images	Sets the number of images allocated in the driver. The RAM

of the PC limits the maximum value.
mode| In ‘sequence’ mode, this function is blocking during record. The recorder stops automatically when the number_of_images is reached. In ‘sequence non blocking’ mode, this function is non-blocking. The status must be checked before reading an image. This mode is used to read images while recording, e.g. thumbnail.
In ‘ring buffer’ mode this function is non blocking. The status must be checked before reading an image. Recorder does not stop the recording when the number_of_images is reached. Once this happens, the oldest images are overwritten.
In ‘fifo’ mode, this function is non-blocking. The status must be checked before reading an image. When the number_of_images in the fifo is reached, the following images are dropped until images are read from the fifo.

2.1.2 Stop
Description Stops the current recording. In ‘ring buffer’ and ‘fifo’ mode, this function must be called by the user. In ‘sequence’ and ‘sequence non blocking’ mode, this function is automatically called up when the number_of_images is reached.
Prototype def stop(self):
2.1.3 Close
Description Closes the activated camera and releases the blocked ressources. This function must be called before the application is terminated. Otherwise, the resources remain occupied.
Prototype def close(self):
This function is called automatically if the camera object is created by the with statement. An explicit call to close() is no longer necessary.
with pco.Camera() as cam: # do some stuff
2.1.4 Image
Description Returns an image from the recorder. The type of the image is a numpy.ndarray. This array is shaped depending on the resolution and ROI of the image.
Prototype def image(self, image_number=0, roi=None):
Parameter

Name	Description
image_number	Specifies the number of the image to be read. In ‘sequence’ or

‘sequence non blocking’ mode, the recorder index matches the image_number. If image_number is set to 0xFFFFFFFF, the last recorded image is copied. This allows to create a live preview while recording.
roi| Sets the region of interest. Only this region of the image is copied to the return value.

Example >>> cam.record(number_of_images=1, mode=’sequence’)

image, meta = cam.image()
type(image) numpy.ndarray
image.shape (2160, 2560)
image, metadata = cam.image(roi=(1, 1, 300, 300))
image.shape (300, 300)
2.1.5 Images
Description Returns all recorded images from the recorder as a list of numpy arrays.
Prototype def images(self, roi=None, blocksize=None):
Parameter

Name	Description
roi	Sets the region of interest. Only this region of the image is copied to

the return value.
blocksize| Defines the maximum number of images that are returned. This parameter is only useful in ‘fifo’ mode and under special conditions.

Example >>> cam.record(number_of_images=20, mode=’sequence’)

images, metadatas = cam.images()
len(images) 20
for image in images:
…
print(‘Mean: {:7.2f} DN’.format(image.mean()))
…
Mean: 2147.64 DN
Mean: 2144.61 DN
…
images = cam.images(roi=(1, 1, 300, 300))
images[0].shape (300, 300)
2.1.6 Image_average
Description Returns the averaged image. This image is calculated from all recorded images in the buffer.
Prototype def image_average(self, roi=None):
Parameter

Name	Description
roi	Defines the region of interest. Only this region of the image is copied

to the return value.

Example >>> cam.record(number_of_images=100, mode=’sequence’)

avg = cam.image_average()
avg = cam.image_average(roi=(1, 1, 300, 300))
2.1.7 Set_exposure_time
Description Sets the exposure time of the camera.
Prototype def set_exposure_time(self, exposure_time):
Parameter

Name	Description
exposure_time	Must be given as float or integer value in the unit ‘second’.

The underlying values for the function sdk.set_delay_exposure_time(0, ‘ms’, time, timebase) will be calculated automatically. The delay time is set to 0.

Example >>> cam.set_exposure_time(0.001)

cam.set_exposure_time(1e-3)
2.1.8 Wait_for_first_image
Description Waits for the first available image in the recorder memory. In recorder mode ‘sequence non blocking’, ‘ring buffer’. and ‘fifo’, the function record() returns immediately. Therefore, this function can be used to wait for images from the camera before calling image(), images(), or image_average().
Prototype def wait_for_first_image(self):
2.2 Variable Configuration
The camera parameters are updated by changing the configuration variable.
cam.configuration = {‘exposure time’: 10e-3,
‘roi’: (1, 1, 512, 512),
‘timestamp’: ‘ascii’,
‘pixel rate’: 100_000_000,
‘trigger’: ‘auto sequence’,
‘acquire’: ‘auto’,
‘metadata’: ‘on’,
‘binning’: (1, 1)}
The variable can only be changed before the record() function is called. It is a dictionary with a certain number of entries. Not all possible elements need to be specified. The following sample code only changes the ‘pixel rate’ and does not affect any other elements of the configuration.
with pco.Camera() as cam:
cam.configuration = {‘pixel rate’: 286_000_000}
cam.record()
…
2.3 Objects
This section describes all objects offered by the pco.Camera class.
2.3.1 SDK
The object sdk allows direct access to all underlying functions of the pco.sdk.
cam.sdk.get_temperature()
{‘sensor temperature’: 7.0, ‘camera temperature’: 38.2, ‘power temperature’: 36.7}
All return values from sdk functions are dictionaries. Not all camera settings are currently covered by the Camera class. Special settings have to be set directly by calling the respective sdk function.
2.3.2 Recorder
The object rec offers direct access to all underlying functions of the pco.recorder. It is not necessary to call a recorder class method directly. All functions are fully covered by the methods of the Camera class.