microscope.cameras.pvcam module

pvcam library wrapper.

This module exposes pvcam C library functions in python.

Todo

Support frame metadata. The following functions are still not implemented:

/*****************************************************************************/
/*****************************************************************************/
/*                                                                           */
/*                         Frame metadata functions                          */
/*                                                                           */
/*****************************************************************************/
/*****************************************************************************/

/**
Decodes all the raw frame buffer metadata into a friendly structure.
@param pDstFrame A pre-allocated helper structure that will be filled with
                 information from the given raw buffer.
@param pSrcBuf A raw frame buffer as retrieved from PVCAM
@param srcBufSize The size of the raw frame buffer
@return #PV_FAIL in case of failure.
*/
rs_bool PV_DECL pl_md_frame_decode (md_frame* pDstFrame, void* pSrcBuf, uns32 srcBufSize);

/**
Optional function that recomposes a multi-ROI frame into a displayable image buffer.
Every ROI will be copied into its appropriate location in the provided buffer.
Please note that the function will subtract the Implied ROI position from each ROI
position which essentially moves the entire Implied ROI to a [0, 0] position.
Use the Offset arguments to shift all ROIs back to desired positions if needed.
If you use the Implied ROI position for offset arguments the frame will be recomposed
as it appears on the full frame.
The caller is responsible for black-filling the input buffer. Usually this function
is called during live/preview mode where the destination buffer is re-used. If the
ROIs do move during acquisition it is essential to black-fill the destination buffer
before calling this function. This is not needed if the ROIs do not move.
If the ROIs move during live mode it is also recommended to use the offset arguments
and recompose the ROI to a full frame - with moving ROIs the implied ROI may change
with each frame and this may cause undesired ROI "twitching" in the displayable image.

@param pDstBuf An output buffer, the buffer must be at least the size of the implied
               ROI that is calculated during the frame decoding process. The buffer
               must be of type uns16. If offset is set the buffer must be large
               enough to allow the entire implied ROI to be shifted.
@param offX    Offset in the destination buffer, in pixels. If 0 the Implied
               ROI will be shifted to position 0 in the target buffer.
               Use (ImpliedRoi.s1 / ImplierRoi.sbin) as offset value to
               disable the shift and keep the ROIs in their absolute positions.
@param offY    Offset in the destination buffer, in pixels. If 0 the Implied
               ROI will be shifted to position 0 in the target buffer.
               Use (ImpliedRoi.p1 / ImplierRoi.pbin) as offset value to
               disable the shift and keep the ROIs in their absolute positions.
@param dstWidth  Width, in pixels of the destination image buffer. The buffer
                 must be large enough to hold the entire Implied ROI, including
                 the offsets (if used).
@param dstHeight Height, in pixels of the destination image buffer.
@param pSrcFrame A helper structure, previously decoded using the frame
                 decoding function.
@return #PV_FAIL in case of failure.
*/
rs_bool PV_DECL pl_md_frame_recompose (void* pDstBuf, uns16 offX, uns16 offY,
                                       uns16 dstWidth, uns16 dstHeight,
                                       md_frame* pSrcFrame);

/**
This method creates an empty md_frame structure for known number of ROIs.
Use this method to prepare and pre-allocate one structure before starting
continous acquisition. Once callback arrives fill the structure with
pl_md_frame_decode() and display the metadata.
Release the structure when not needed.
@param pFrame a pointer to frame helper structure address where the structure
              will be allocated.
@param roiCount Number of ROIs the structure should be prepared for.
@return #PV_FAIL in case of failure.
*/
rs_bool PV_DECL pl_md_create_frame_struct_cont (md_frame** pFrame, uns16 roiCount);

/**
This method creates an empty md_frame structure from an existing buffer.
Use this method when loading buffers from disk or when performance is not
critical. Do not forget to release the structure when not needed.
For continous acquisition where the number or ROIs is known it is recommended
to use the other provided method to avoid frequent memory allocation.
@param pFrame A pointer address where the newly created structure will be stored.
@param pSrcBuf A raw frame data pointer as returned from the camera
@param srcBufSize Size of the raw frame data buffer
@return #PV_FAIL in case of failure
*/
rs_bool PV_DECL pl_md_create_frame_struct (md_frame** pFrame, void* pSrcBuf,
                                           uns32 srcBufSize);

/**
Releases the md_frame struct
@param pFrame a pointer to the previously allocated structure
*/
rs_bool PV_DECL pl_md_release_frame_struct (md_frame* pFrame);

/**
Reads all the extended metadata from the given ext. metadata buffer.
@param pOutput A pre-allocated structure that will be filled with metadata
@param pExtMdPtr A pointer to the ext. MD buffer, this can be obtained from
                the md_frame and md_frame_roi structures.
@param extMdSize Size of the ext. MD buffer, also retrievable from the helper
                 structures.
@return #PV_FAIL in case the metadata cannot be decoded.
*/
rs_bool PV_DECL pl_md_read_extended (md_ext_item_collection* pOutput, void* pExtMdPtr,
                                     uns32 extMdSize);
class microscope.cameras.pvcam.FRAME_INFO[source]

Bases: _ctypes.Structure

FrameInfoGUID

Structure/Union member

FrameNr

Structure/Union member

ReadoutTime

Structure/Union member

TimeStamp

Structure/Union member

TimeStampBOF

Structure/Union member

hCam

Structure/Union member

class microscope.cameras.pvcam.OUTPUT(val)[source]

Bases: microscope.cameras.pvcam._meta

get_var(buf_len=0)[source]
class microscope.cameras.pvcam.PVCAM_FRAME_INFO_GUID[source]

Bases: _ctypes.Structure

f1

Structure/Union member

f2

Structure/Union member

f3

Structure/Union member

f4

Structure/Union member

class microscope.cameras.pvcam.PVCamera(index=0, **kwargs)[source]

Bases: microscope.devices.FloatingDeviceMixin, microscope.devices.CameraDevice

Implements the CameraDevice interface for the pvcam library.

_fetch_data()[source]

Fetch data - for use in fetch_loop.

_get_binning()[source]

Return the current binning (horizontal, vertical).

_get_roi()[source]

Return the current ROI (left, top, width, height).

_get_sensor_shape()[source]

Return the sensor shape (width, height).

_on_disable()[source]

Disable the hardware for a short period of inactivity.

_on_enable()[source]

Enable the camera hardware and make ready to respond to triggers.

Return True if successful, False if not.

_on_shutdown()[source]

Disable the hardware for a prolonged period of inactivity.

abort()[source]

Abort acquisition.

This should put the camera into a state in which settings can be modified.

get_cycle_time()[source]

Return the cycle time.

Just return self.cycle_time, which is updated with the real value during _on_enable.

get_exposure_time()[source]

Return the current exposure time.

Just return self.exposure_time, which is updated with the real value during _on_enable.

get_id()[source]

Get hardware’s unique identifier.

get_trigger_type()[source]

Return the current trigger type.

initialize()[source]

Initialise the camera.

make_safe()[source]

Put the camera into a safe state.

Safe means (at least):
  • it won’t sustain damage if light falls on the sensor.
open_cameras = []
set_exposure_time(*args, **kwargs)
set_readout_mode(*args, **kwargs)
soft_trigger()[source]

Expose software triggering to a client.

Trigger an exposure in TRIG_SOFT mode. Log some debugging stats in other trigger modes.

class microscope.cameras.pvcam.PVEnumParam(camera, param_id)[source]

Bases: microscope.cameras.pvcam.PVParam

PVParam subclass for enums

current

Return the current (or cached) enum parameter value.

set_value(new_value)[source]

Set an enum parameter value.

values

Get allowable enum values

class microscope.cameras.pvcam.PVParam(camera, param_id)[source]

Bases: object

A wrapper around PVCAM parameters.

_query(what=0, force_query=False)[source]

Query the DLL for an attribute for this parameter.

This returns pythonic types, not ctypes.

access

Return parameter access attribute.

available

Return whether or not parameter is available on hardware.

count

Return count of parameter enum entries.

current

Return the current (or cached) parameter value.

Subclasses should override this for more complex data types.

static factory(camera, param_id)[source]

Create a PVParam or appropriate subclass

set_value(new_value)[source]

Set a parameter value.

Subclasses should do whatever processing they need on new_value, then call super().set_value(new_value)

values

Get parameter min and max values.

Subclasses for strings and enum override this.

class microscope.cameras.pvcam.PVStringParam(camera, param_id)[source]

Bases: microscope.cameras.pvcam.PVParam

PVParam subclass for strings

current

Return the current (or cached) string parameter value.

set_value(new_value)[source]

Set a string parameter value

values

Get allowable string length.

class microscope.cameras.pvcam.TriggerMode(id, label, pv_mode, microscope_mode)[source]

Bases: object

A microscope trigger mode using PVCAM PMODES.

microscope.cameras.pvcam._status()[source]

Fetch the PVCAM DLL status.

class microscope.cameras.pvcam.active_camera_type[source]

Bases: _ctypes.Structure

alt_mode

Structure/Union member

clear_count

Structure/Union member

cols

Structure/Union member

do_clear

Structure/Union member

exp_res

Structure/Union member

frame_selectable

Structure/Union member

frame_transfer

Structure/Union member

io_hdr

Structure/Union member

mpp_mode

Structure/Union member

mpp_selectable

Structure/Union member

open_shutter

Structure/Union member

postmask

Structure/Union member

postscan

Structure/Union member

preamp_delay

Structure/Union member

preflash

Structure/Union member

premask

Structure/Union member

prescan

Structure/Union member

rows

Structure/Union member

shutter_close_delay

Structure/Union member

shutter_open_delay

Structure/Union member

microscope.cameras.pvcam.dllFunc(name, args=[], argnames=[], buf_len=0)[source]

Register a function using dllFunction.

class microscope.cameras.pvcam.dllFunction(name, args=[], argnames=[], buf_len=-1, lib=<MagicMock id='139821597995192'>)[source]

Bases: object

Expose a DLL function to python.

(Again, largely nicked from PYME.)

microscope.cameras.pvcam.get_param_dtype(param_id)[source]

Return parameter dtype (for microscope settings) for param_id.

microscope.cameras.pvcam.get_param_type(param_id)[source]

Return parameter type code (for C/DLL) for param_id.

class microscope.cameras.pvcam.io_list[source]

Bases: _ctypes.Structure

post_close

Structure/Union member

post_flash

Structure/Union member

post_integrate

Structure/Union member

post_open

Structure/Union member

post_readout

Structure/Union member

pre_close

Structure/Union member

pre_flash

Structure/Union member

pre_integrate

Structure/Union member

pre_open

Structure/Union member

pre_readout

Structure/Union member

class microscope.cameras.pvcam.io_struct[source]

Bases: _ctypes.Structure

io_port

Structure/Union member

io_type

Structure/Union member

next

Structure/Union member

state

Structure/Union member

class microscope.cameras.pvcam.md_ext_item[source]

Bases: _ctypes.Structure

tagInfo

Structure/Union member

value

Structure/Union member

class microscope.cameras.pvcam.md_ext_item_collection[source]

Bases: _ctypes.Structure

count

Structure/Union member

list

Structure/Union member

map

Structure/Union member

class microscope.cameras.pvcam.md_ext_item_info[source]

Bases: _ctypes.Structure

name

Structure/Union member

size

Structure/Union member

tag

Structure/Union member

class microscope.cameras.pvcam.md_frame[source]

Bases: _ctypes.Structure

extMdData

Structure/Union member

extMdDataSize

Structure/Union member

header

Structure/Union member

impliedRoi

Structure/Union member

roiArray

Structure/Union member

roiCapacity

Structure/Union member

roiCount

Structure/Union member

class microscope.cameras.pvcam.md_frame_header[source]

Bases: _ctypes.Structure

bitDepth

Structure/Union member

colorMask

Structure/Union member

exposureTime

Structure/Union member

exposureTimeResN

Structure/Union member

extendedMdSize

Structure/Union member

flags

Structure/Union member

frameNr

Structure/Union member

roiCount

Structure/Union member

roiTimestampResN

Structure/Union member

signature

Structure/Union member

timestampBOF

Structure/Union member

timestampEOF

Structure/Union member

timestampResNs

Structure/Union member

version

Structure/Union member

class microscope.cameras.pvcam.md_frame_roi[source]

Bases: _ctypes.Structure

data

Structure/Union member

dataSize

Structure/Union member

extMdData

Structure/Union member

extMdDataSize

Structure/Union member

header

Structure/Union member

class microscope.cameras.pvcam.md_frame_roi_header[source]

Bases: _ctypes.Structure

extendedMdSize

Structure/Union member

flags

Structure/Union member

roi

Structure/Union member

roiNr

Structure/Union member

timestampBOR

Structure/Union member

timestampEOR

Structure/Union member

class microscope.cameras.pvcam.rgn_type[source]

Bases: _ctypes.Structure

p1

Structure/Union member

p2

Structure/Union member

pbin

Structure/Union member

s1

Structure/Union member

s2

Structure/Union member

sbin

Structure/Union member

class microscope.cameras.pvcam.smart_stream_type[source]

Bases: _ctypes.Structure

entries

Structure/Union member

params

Structure/Union member

microscope.cameras.pvcam.stripMeta(val)[source]

Strip meta info from OUTPUT and OUTSTRING instances.