Concrete implementation for PCO camera

PCO module (pymanip.video.pco)

This module is a shortcut for the pymanip.video.pco.camera.PCO_Camera class. It also defines utility functions for PCO camera.

pymanip.video.pco.PCO_read_binary_file(f)

This functions reads PCO binary image file.

pymanip.video.pco.print_available_pco_cameras()

This functions queries the Pixelfly library for available cameras, and prints the result.

PixelFly library bindings (pymanip.video.pco.pixelfly)

This module implements bindings to the PCO PixelFly library using ctypes. Please not that these bindings are not official, and that not all PixelFly functions are wrapped. Please refer to the official PCO PixelFly documentation for accurate description of the functions.

class pymanip.video.pco.pixelfly.PCO_Image

This class is a binding to the PCO_Image C Structure.

pymanip.video.pco.pixelfly.PCO_manage_error(ret_code)

This function raises an error exception or a runtime warning if ret_code is non-zero.

Parameters

ret_code (int) – PCO library function return code

pymanip.video.pco.pixelfly.bcd_byte_to_str(input_)

This function converts a one-byte bcd value into two digit string.

Parameters

input (int) – bcd value to convert

Returns

converted bcd value

Return type

str

pymanip.video.pco.pixelfly.bcd_to_int(input_, endianess='little')

This function converts decimal-coded value (bcd) into int.

Parameters

input (byte or bytearray) – input bcd value

Returns

integer value

Return type

int

Decimal-encoded value format is given in this table:

Decimal digit	Bits
0	0000
1	0001
2	0010
3	0011
4	0100
5	0101
6	0110
7	0111
8	1000
9	1001

pymanip.video.pco.pixelfly.PCO_OpenCamera()

This function opens a camera device and attach it to a handle, which will be returned by the parameter ph. This function scans for the next available camera. If you want to access a distinct camera please use PCO_OpenCameraEx. Due to historical reasons the wCamNum parameter is a don’t care.

pymanip.video.pco.pixelfly.PCO_OpenCameraEx(interface_type, camera_number)

This function opens a distinct camera, e.g. a camera which is connected to a specific interface port.

Parameters

• interface_type (int) – Interface type to look for the camera

• camera_number (int) – ID of the camera

The interface_type values are given in this table:

Interface	interface_type
FireWire	1
Camera Link Matrox	2
Camera Link Silicon Software mE III	3
Camera Link National Instruments	4
GigE	5
USB 2.0	6
Camera Link Silicon Software mE IV	7
USB 3.0	8
Reserved for WLAN	9
Camera Link serial port only	10
Camera Link HS	11
all	0xFFFF

pymanip.video.pco.pixelfly.PCO_CloseCamera(handle)

This function closes a camera device.

Parameters

handle (HANDLE) – handle of the camera

pymanip.video.pco.pixelfly.PCO_GetInfoString(handle)

This function reads information about the camera, e.g. firmware versions.

Parameters

handle (HANDLE) – camera handle

pymanip.video.pco.pixelfly.PCO_GetROI(handle: int) → Tuple[int, int, int, int]

This function returns the current ROI (region of interest) setting in pixels. (X0,Y0) is the upper left corner and (X1,Y1) the lower right one.

Parameters

handle (HANDLE) – handle of the camera

Returns

X0, Y0, X1, Y1

Return type

int, int, int, int

pymanip.video.pco.pixelfly.PCO_SetROI(handle: int, RoiX0: ctypes.c_int, RoiY0: ctypes.c_int, RoiX1: ctypes.c_int, RoiY1: ctypes.c_int)

This function does set a ROI (region of interest) area on the sensor of the camera.

Parameters

• handle (HANDLE) – handle of the camera

• RoiX0 (int) – left border

• RoiY0 (int) – upper border

• RoiX1 (int) – right border

• RoiY1 (int) – lower border

pymanip.video.pco.pixelfly.PCO_GetFrameRate(handle)

This function returns the current frame rate and exposure time settings of the camera.Returned values are only valid if last timing command was PCO_SetFrameRate.

pymanip.video.pco.pixelfly.PCO_SetFrameRate(handle: int, FrameRateMode: ctypes.c_int, FrameRate: ctypes.c_long, FrameRateExposure: ctypes.c_long)

This function sets Frame rate (mHz) and exposure time (ns) Frame rate status gives the limiting factors if the condition are not met.

pymanip.video.pco.pixelfly.PCO_GetCameraName(handle)

This function retrieves the name of the camera.

pymanip.video.pco.pixelfly.PCO_GetGeneral(handle)

This function requests all info contained in the following descriptions, especially:

• camera type, hardware/firmware version, serial number, etc.

• Request the current camera and power supply temperatures

pymanip.video.pco.pixelfly.PCO_GetSensorStruct(handle)

Get the complete set of the sensor functions settings

pymanip.video.pco.pixelfly.PCO_GetCameraDescription(handle)

Sensor and camera specific description is queried. In the returned PCO_Description structure margins for all sensor related settings and bitfields for available options of the camera are given.

pymanip.video.pco.pixelfly.PCO_GetCameraHealthStatus(handle)

This function retrieves information about the current camera status.

pymanip.video.pco.pixelfly.PCO_GetRecordingStruct(handle)

Get the complete set of the recording function settings. Please fill in all wSize parameters, even in embedded structures.

pymanip.video.pco.pixelfly.PCO_GetSizes(handle: int) → Tuple[int, int, int, int]

This function returns the current armed image size of the camera.

pymanip.video.pco.pixelfly.PCO_AllocateBuffer(handle: int, bufNr: int, size: int, bufPtr: pyvisa.ctwrapper.types.LP_c_int, hEvent: ctypes.c_void_p = 0) → Tuple[int, pyvisa.ctwrapper.types.LP_c_int, int]

This function sets up a buffer context to receive the transferred images. A buffer index is returned, which must be used for the image transfer functions. There is a maximum of 16 buffers per camera.

Attention: This function cannot be used, if the connection to the camera is established through the serial connection of a Camera Link grabber. In this case, the SDK of the grabber must be used to do any buffer management.

pymanip.video.pco.pixelfly.PCO_FreeBuffer(handle, bufNr)

This function frees a previously allocated buffer context with a given index. If internal memory was allocated for this buffer context, it will be freed. If an internal event handle was created, it will be closed.

pymanip.video.pco.pixelfly.PCO_GetBufferStatus(handle, sBufNr)

This function queries the status of the buffer context with the given index:

• StatusDll describes the state of the buffer context:

  StatusDll	description
  0x80000000	Buffer is allocated
  0x40000000	Buffer event created inside the SDK DLL
  0x20000000	Buffer is allocated externally
  0x00008000	Buffer event is set

• StatusDrv describes the state of the last image transfer into this buffer.

  • PCO_NOERROR: Image transfer succeeded

  • others: See error codes

pymanip.video.pco.pixelfly.PCO_ArmCamera(handle)

Arms, i.e. prepares the camera for a consecutive set recording status = [run] command. All configurations and settings made up to this moment are accepted and the internal settings of the camera is prepared. Thus the camera is able to start immediately when the set recording status = [run] command is performed.

pymanip.video.pco.pixelfly.PCO_GetRecordingState(handle)

Returns the current Recording state of the camera: - 0x0000: camera is stopped, recording state [stop]

• 0x0001: camera is running, recording state [run]

pymanip.video.pco.pixelfly.PCO_SetRecordingState(handle, state)

Sets the current recording status and waits till the status is valid. If the state can’t be set the function will return an error.

Note

• it is necessary to arm camera before every set recording status command in order to ensure that all settings are accepted correctly.

• During the recording session, it is possible to change the timing by calling PCO_SetDelayExposureTime().

pymanip.video.pco.pixelfly.PCO_GetBitAlignment(handle)

This function returns the current bit alignment of the transferred image data. The data can be either MSB (Big Endian) or LSB (Little Endian) aligned. Returns: - 0x0000 [MSB]

• 0x0001 [LSB]

pymanip.video.pco.pixelfly.PCO_SetBitAlignment(handle, littleEndian)

This functions sets the bit alignment of the transferred image data. littleEndian can be 0 or 1.

pymanip.video.pco.pixelfly.PCO_GetImageStruct(handle)

Information about previously recorded images is queried from the camera and the variables of the PCO_Image structure are filled with this information.

pymanip.video.pco.pixelfly.PCO_GetMetaData(handle, bufNr)

Cameras: pco.dimax and pco.edge

Query additionnal image information, which the camera has attached to the transferred image, if Meta Data mode is enabled.

pymanip.video.pco.pixelfly.PCO_SetMetaDataMode(handle, MetaDataMode)

Cameras: pco.dimax and pco.edge

Sets the mode for Meta Data and returns information about size and version of the Meta Data block. When Meta Data mode is set to [on], a Meta Data block with additional information is added at the end of each image. The internal buffers allocated with PCO_AllocateBuffer are adapted automatically.

pymanip.video.pco.pixelfly.PCO_GetMetaDataMode(handle)

Returns the current Meta Data mode of the camera and information about size and version of the Meta Data block.

pymanip.video.pco.pixelfly.PCO_SetTimestampMode(handle, mode)

Sets the timestamp mode of the camera:

mode	short description	long description
0x0000	[off]
0x0001	[binary]	BCD coded timestamp in the first 14 pixels
0x0002	[binary+ASCII]	BCD coded timestamp in the first 14 pixels + ASCII text
0x0003	[ASCII]	ASCII text only (see camera descriptor for availability)

pymanip.video.pco.pixelfly.PCO_AddBufferEx(handle, dw1stImage, dwLastImage, sBufNr, wXRes, wYRes, wBitPerPixel)

This function sets up a request for a single transfer from the camera and returns immediately.

pymanip.video.pco.pixelfly.PCO_CancelImages(handle)

This function does remove all remaining buffers from the internal queue, reset the internal queue and also reset the transfer state machine in the camera. It is mandatory to call PCO_CancelImages after all image transfers are done. This function can be called before or after setting PCO_SetRecordingState to [stop].

pymanip.video.pco.pixelfly.PCO_SetImageParameters(handle, XRes, YRes, flags)

This function sets the image parameters for internal allocated resources. This function must be called before an image transfer is started. If next image will be transfered from a recording camera, flag IMAGEPARAMETERS_READ_WHILE_RECORDING must be set. If next action is to readout images from the camera internal memory, flag IMAGEPARAMETERS_READ_FROM_SEGMENTS must be set.

pymanip.video.pco.pixelfly.PCO_GetImageEx(handle, segment, firstImage, lastImage, bufNr, xRes, yRes, bitsPerPixel)

This function can be used to get a single image from the camera. The function does not return until the image is transferred to the buffer or an error occured. The timeout value for the transfer can be set with function PCO_SetTimeouts, the default value is 6 seconds. On return the image stored in the memory area of the buffer, which is addressed through parameter sBufNr.

pymanip.video.pco.pixelfly.PCO_SetDelayExposureTime(handle, dwDelay, dwExposure, wTimeBaseDelay, wTimeBaseExposure)

This function sets the delay and exposure time and the associated time base values. Restrictions for the parameter values are defined in the PCO_Description structure: - dwMinDelayDESC

• dwMaxDelayDESC

• dwMinDelayStepDESC

• dwMinExposDESC

• dwMaxExposDESC

• dwMinExposStepDESC

Possible values for wTimeBaseDelay and wTimeBaseExposure:

Value	Unit
0x0000	ns
0x0001	µs
0x0002	ms

pymanip.video.pco.pixelfly.PCO_GetDelayExposureTime(handle)

Returns the current setting of delay and exposure time

pymanip.video.pco.pixelfly.PCO_GetTriggerMode(handle)

Returns the current trigger mode setting of the camera

pymanip.video.pco.pixelfly.PCO_SetTriggerMode(handle, mode)

Sets the trigger mode of the camera.

pymanip.video.pco.pixelfly.PCO_SetADCOperation(handle, operation)

Sets the ADC (analog-digital-converter) operating mode. If sensor data is read out using single ADC operation, linearity of image data is enhanced. Using dual ADC, operation readout is faster and allows higher frame rates. If dual ADC operating mode is set, horizontal ROI must be adapted to symmetrical values.

Possible values:

Value	Mode
0x0001	[single ADC]
0x0002	[dual ADC]

pymanip.video.pco.pixelfly.PCO_GetADCOperation(handle)

Returns the ADC operation mode (single / dual)

pymanip.video.pco.pixelfly.PCO_SetPixelRate(handle, rate)

This functions sets the pixel rate for the sensor readout.

pymanip.video.pco.pixelfly.PCO_GetPixelRate(handle)

Returns the current pixel rate of the camera in Hz. The pixel rate determines the sensor readout speed.

pymanip.video.pco.pixelfly.PCO_GetNoiseFilterMode(handle)

This function returns the current operating mode of the image correction in the camera.

The noise filter mode:

Value	Mode
0x0000	[off]
0x0001	[on]
0x0101	[on + hot pixel correction]

pymanip.video.pco.pixelfly.PCO_SetNoiseFilterMode(handle, mode)

This function does set the image correction operating mode of the camera. Image correction can either be switched to totally off, noise filter only mode or noise filter plus hot pixel correction mode. The command will be rejected, if Recording State is [run], see PCO_GetRecordingState.

The noise filter mode:

Value	Mode
0x0000	[off]
0x0001	[on]
0x0101	[on + hot pixel correction]

pymanip.video.pco.pixelfly.PCO_TriggerModeDescription

dictionnary of trigger modes

PCO Camera module (pymanip.video.pco.camera)

This module implement the pymanip.video.pco.PCO_Camera class using bindings to the Pixelfly library from pymanip.video.pco.pixelfly.

class pymanip.video.pco.camera.PCO_Camera(interface='all', camera_num=0, *, metadata_mode=False, timestamp_mode=True)

Concrete pymanip.video.Camera class for PCO camera.

Parameters

• interface (str, optional) – interface where to look for the camera, defaults to “all”

• camera_num (int, optional) – camera number to look for, defaults to 0.

• metadata_mode (bool, optional) – enable PCO Metadata mode, defaults to False.

• timestamp_mode (bool, optional) – enable Timestamp mode (supported by all cameras), defaults to True.

acquisition(num=inf, timeout=None, raw=False, raise_on_timeout=True)

Concrete implementation of pymanip.video.Camera.acquisition() for the PCO camera.

acquisition_async(num=inf, timeout=None, raw=False, initialising_cams=None, raise_on_timeout=True)

Concrete implementation of pymanip.video.Camera.acquisition_async() for the PCO camera.

acquisition_oneshot()

Concrete implementation of pymanip.video.Camera.acquisition_oneshot() for the PCO camera.

property bitdepth

Camera sensor bit depth

close()

This method closes the connection to the camera.

current_adc_operation()

This method returns the current ADC operation mode.

Returns

Current ADC operation mode (0x0001 for “single”, 0x0002 for “dual”)

Return type

int

current_delay_exposure_time()

This method returns current delay and exposure time in seconds.

Returns

delay, exposure

Return type

float, float

current_frame_rate()

This method returns the current frame rate.

Returns

Current frame rate

Return type

int

current_noise_filter_mode()

This methods queries the current noise filter mode.

Returns

the noise filter mode

Return type

int

The noise filter mode:

Value	Mode
0x0000	[off]
0x0001	[on]
0x0101	[on + hot pixel correction]

current_pixel_rate()

This method returns the current pixel rate.

Returns

Current pixel rate (e.g. 10 MHz or 40 MHz for the PCO.1600

Return type

int

current_trigger_mode_description()

This method returns the current trigger mode description.

Returns

description of current trigger mode

Return type

str

health_status()

This method queries the camera for its health status.

Returns

warn, err, status

property name

Camera name

property resolution

Camera maximum resolution

set_adc_operating_mode(mode)

This function selects single or dual ADC operating mode:

Parameters

mode (int or str) – “single” (or 0x0001) or “dual” (or 0x0002)

• Single mode increases linearity;

• Dual mode allows higher frame rates.

set_delay_exposuretime(delay=None, exposuretime=None)

This method sets both the delay and the exposure time.

Parameters

• delay (float) – delay in seconds

• exposuretime (float) – exposure time in seconds

set_frame_rate(Frameratemode, Framerate, Framerateexposure)

This method sets Frame rate (mHz) and exposure time (ns).

Parameters

• Frameratemode (int) – one of the possible framerate modes (0x0000, 0x0001, 0x0002, 0x0003)

• Framerate (int) – framerate in mHz

• Framerateexposure (int) – Exposure time in ns

Returns

message, framerate, exposure time

Return type

int, int, int

The meaning of the framerate mode is given in this table

Framerate mode	Meaning
0x0000	Auto mode (camera decides which parameter will be trimmed)
0x0001	Frame rate has priority, (exposure time will be trimmed)
0x0002	Exposure time has priority, (frame rate will be trimmed)
0x0003	Strict, function shall return with error if values are not possible.

The message value in return gives the limiting factors when the condition are not fulfilled. The meaning is given in this table

Message	Meaning
0x0000	Settings consistent, all conditions met
0x0001	Frame rate trimmed, frame rate was limited by readout time
0x0002	Frame rate trimmed, frame rate was limited by exposure time
0x0004	Exposure time trimmed, exposure time cut to frame time
0x8000	Return values dwFrameRate and dwFrameRateExposure are not yet validated.

In the case where message 0x8000 is returned, the other values returned are simply the parameter values passed to the function.

set_noise_filter_mode(mode)

This method does set the image correction operating mode of the camera. Image correction can either be switched totally off, noise filter only mode or noise filter plus hot pixel correction mode. The command will be rejected, if Recording State is [run], see PCO_GetRecordingState.

Parameters

mode (int) – the noise filter mode

The noise filter mode:

Value	Mode
0x0000	[off]
0x0001	[on]
0x0101	[on + hot pixel correction]

set_pixel_rate(rate)

This function selects the pixel rate for sensor readout.

Parameters

rate (float) – readout rate (in Hz)

For PCO.1600: 10 Mhz or 40 MHz

set_roi(roiX0=0, roiY0=0, roiX1=0, roiY1=0)

This method sets the positions of the upper left corner (X0,Y0) and lower right (X1,Y1) corner of the ROI (region of interest) in pixels.

Parameters

• roiX0 (int) – left border in pixels, must be \(1 + 32n, n \in \mathbb{N}\)

• roiY0 – top border in pixels, must be \(1 + 8n, n \in \mathbb{N}\)

• roiX1 (int) – right border in pixels, must be \(32m, m \in \mathbb{N}\)

• roiY1 – bottom border in pixels, must be \(8m, m \in \mathbb{N}\)

The minimum ROI is \(64\times 16\) pixels, and it is required that \(roiX1 \geq roix0\) and \(roiY1 \geq roiY0\).

set_trigger_mode(mode)

This method sets the trigger mode for the camera.

Parameters

mode (str) – one of PCO_TriggerModeDescription

Possible values are:

mode	description
0x0000	auto sequence
0x0001	software trigger
0x0002	external exposure start & software trigger
0x0003	external exposure control
0x0004	external synchronized
0x0005	fast external exposure control
0x0006	external CDS control
0x0007	slow external exposure control
0x0102	external synchronized HDSDI

pymanip.video.pco.camera.PCO_get_binary_timestamp(image)

This functions reads the BCD coded timestamp in the first 14 pixels of an image from a PCO camera.

Parameters

image (array) – the PCO camera image buffer

Returns

counter, timestamp

Return type

int, datetime

We assume the following format (per PCO documentation):

Pixel	Description	Range
Pixel 1	Image counter (MSB)	00..99
Pixel 2	Image counter	00..99
Pixel 3	Image counter	00..99
Pixel 4	Image counter (LSB)	00..99
Pixel 5	Year (MSB)	20
Pixel 6	Year (LSB)	03..99
Pixel 7	Month	01..12
Pixel 8	Day	01..31
Pixel 9	Hour	00..23
Pixel 10	Minutes	00..59
Pixel 11	Seconds	00..59
Pixel 12	µs * 10000	00..99
Pixel 13	µs * 100	00..99
Pixel 14	µs	00..90

class pymanip.video.pco.camera.PCO_Buffer(cam_handle, XResAct, YResAct)

This class represents an allocated buffer for the PCO camera. It implements context manager, as well as utility function to convert to bytes and numpy array. The buffer is allocated in the constructor method, and freed either by the context manager exit method, or manually calling the free() method.

Parameters

• cam_handle (HANDLE) – camera handle

• XResAct (int) – resolution in x direction

• YResAct (int) – resolution in y direction

as_array()

This methods returns the buffer as a numpy array. No data is copied, the memory is still bound to this buffer. The user must copy the data if necessary.

Returns

image array

Return type

numpy.ndarray

bytes()

This methods returns the data as a bytearray.

Returns

image data

Return type

bytearray

free()

This methods frees the buffer.