class scTDClib

class scTDC.scTDClib(libfilepath=None)

low-level wrapper of the C interface in the dynamically loaded library scTDC

__init__(libfilepath=None)

loads the library scTDC (scTDC1.dll or libscTDC.so) from hard disk and adds the correct signatures to the library functions so they can be used from Python.

Parameters

libfilepath (str) – optionally specify the full path including file name to the shared library file, defaults to None

sc_tdc_init_inifile(inifile_path='tdc_gpx3.ini')

Initializes the hardware and loads the initial settings from the specified ini file.

Parameters

inifile_path (str) – the name of or full path to the configuration file, defaults to “tdc_gpx3.ini”

Returns

Returns a non-negative device descriptor on success or a negative error code in case of failure. The device descriptor is needed for all functions that involve the initialized device

Return type

int

sc_tdc_init_inifile_overrides(inifile_path='tdc_gpx3.ini', overrides=None)

Initializes the hardware and loads the initial settings from the specified ini file. Enables overriding of parameters from the ini file without modification of the ini file on hard disk (the override entries reside in memory and are evaluated by the scTDC library).

Parameters
  • inifile_path (str) – the name of or full path to the configuration file, defaults to “tdc_gpx3.ini”

  • overrides (list) – a list of 3-tuples (section_name, parameter_name, parameter_value), where the section_name is specified without square brackets ([]). Spelling of names is case sensitive. defaults to [] (empty list)

Returns

a non-negative device descriptor on success, or, a negative error code in case of failure. The device descriptor is needed for all functions that involve the initialized device

Return type

int

sc_get_err_msg(errcode)

Returns an error message to the given error code.

Parameters

errcode (int) – a negative error code returned by one of the library functions

Returns

the error message describing the reason of the error code

Return type

str

sc_tdc_config_get_library_version()

Query the version of the scTDC library.

Returns

a 3-tuple containing the version separated into major, minor and patch parts, e.g. version 1.3017.5 becomes (1, 3017, 5)

Return type

tuple

sc_tdc_deinit2(dev_desc)

Deinitialize the hardware.

Parameters

dev_desc (int) – device descriptor as retrieved from sc_tdc_init_inifile or sc_tdc_init_inifile_overrides

Returns

0 on success or negative error code

Return type

int

sc_tdc_start_measure2(dev_desc, exposure_ms)

Start a measurement (asynchronously/non-blocking)

Parameters
  • dev_desc (int) – device descriptor as returned by one of the initialization functions

  • exposure_ms (int) – The exposure time in milliseconds

Returns

0 on success or negative error code

Return type

int

sc_tdc_interrupt2(dev_desc)

Interrupts a measurement asynchronously (non-blocking). Asynchronously means, the function may return before the device actually reaches idle state. sc_tdc_set_complete_callback2 may be used to be notified when the device has stopped the measurement.

Parameters

dev_desc (int) – device descriptor

Returns

0 on success or negative error code

Return type

int

sc_pipe_open2(dev_desc, pipe_type, pipe_params)

Open a pipe for reading data from the device. The available pipe types with their corresponding pipe_params types are

Parameters
  • dev_desc (int) – device descriptor

  • pipe_type (int) – one of the pipe type constants

  • pipe_params (Any) – various types of structures depending on pipe_type. If a structure is needed, it should be passed by value, not by pointer.

Returns

a non-negative pipe handle on success or a negative error code

Return type

int

sc_pipe_close2(dev_desc, pipe_handle)

Close a pipe.

Parameters
  • dev_desc (int) – device descriptor

  • pipe_handle (int) – the pipe handle as returned by sc_pipe_open2

Returns

0 on success or negative error code

Return type

int

sc_pipe_read2(dev_desc, pipe_handle, timeout)

Read from a pipe. The functions waits until either data is available or the timeout is reached.

Parameters
  • dev_desc (int) – device descriptor

  • pipe_handle (int) – pipe handle as returned by sc_pipe_open2

  • timeout (int) – the timeout in milliseconds

Returns

a tuple containing the return code and a ctypes.POINTER to the data buffer

Return type

tuple

sc_tdc_get_status2(dev_desc)

Query whether the device is idle or in measurement.

Parameters

dev_desc (int) – device descriptor

Returns

0 (idle) or 1 (exposure) or negative error code

Return type

int

sc_tdc_get_statistics2(dev_desc)

This function is deprecated. Use the statistics pipe, instead. This function is kept for older scTDC library versions.

sc_tdc_set_complete_callback2(dev_desc, privptr, callback)

Sets a callback to be notified about completed measurements or other events regarding the transition from measurement state to idle state.

Parameters
  • dev_desc (int) – device descriptor

  • privptr (ctypes.POINTER(void)) – a private pointer that is passed back into the callback

  • callback (function) – the function to be called for notifications

Returns

0 on success or negative error code

Return type

int

Pipe type constants

scTDC.TDC_HISTO = 0

pipe type, TDC time histogram for one TDC channel

scTDC.DLD_IMAGE_XY = 1

pipe type, image mapping the detector area

scTDC.DLD_IMAGE_XT = 2

pipe type, image mapping the detector x axis and the TDC time axis

scTDC.DLD_IMAGE_YT = 3

pipe type, image mapping the detector y axis and the TDC time axis

scTDC.DLD_IMAGE_3D = 4

pipe type, 3D matrix mapping the detector area the the TDC time axis

scTDC.DLD_SUM_HISTO = 5

pipe type, 1D histogram for DLDs, counts vs time axis

scTDC.STATISTICS = 6

pipe type, statistics data delivered at the end of measurements

scTDC.USER_CALLBACKS = 10

pipe type, TDC and DLD event data, slow in python

scTDC.BUFFERED_DATA_CALLBACKS = 12

pipe type, TDC and DLD event data, more efficient variant of USER_CALLBACKS

scTDC.PIPE_CAM_FRAMES = 13

pipe type, provides camera frame raw image data and frame meta data

scTDC.PIPE_CAM_BLOBS = 14

pipe type, provides camera blob coordinates

Data types for type parameters:

class scTDC.sc3du_t
class sc3du_t(ctypes.Structure):
 _fields_ = [("x",ctypes.c_uint),
             ("y",ctypes.c_uint),
             ("time", ctypes.c_uint64)]
class scTDC.sc3d_t
class sc3d_t(ctypes.Structure):
 _fields_ = [("x",ctypes.c_int),
             ("y",ctypes.c_int),
             ("time", ctypes.c_int64)]
class scTDC.roi_t
class roi_t(ctypes.Structure):
 _fields_ = [("offset", sc3d_t),
             ("size", sc3du_t)]
class scTDC.sc_pipe_dld_image_xyt_params_t
class sc_pipe_dld_image_xyt_params_t(ctypes.Structure):
 _fields_ = [("depth",    ctypes.c_int),
             ("channel",  ctypes.c_int),
             ("modulo",   ctypes.c_uint64),
             ("binning",  sc3du_t),
             ("roi",      roi_t),
             ("accumulation_ms", ctypes.c_uint),
             ("allocator_owner", ctypes.c_char_p),
             ("allocator_cb",    ALLOCATORFUNC)]
class scTDC.sc_pipe_tdc_histo_params_t
class sc_pipe_tdc_histo_params_t(ctypes.Structure):
 _fields_ = [("depth",     ctypes.c_int),
             ("channel",   ctypes.c_uint),
             ("modulo",    ctypes.c_uint64),
             ("binning",   ctypes.c_uint),
             ("offset",    ctypes.c_uint64),
             ("size",      ctypes.c_uint),
             ("accumulation_ms", ctypes.c_uint),
             ("allocator_owner", ctypes.c_char_p),
             ("allocator_cb", ALLOCATORFUNC)]
class scTDC.sc_pipe_statistics_params_t
class sc_pipe_statistics_params_t(ctypes.Structure):
 _fields_ = [("allocator_owner", ctypes.c_char_p),
             ("allocator_cb", ALLOCATORFUNC)]
class scTDC.sc_pipe_callbacks
class sc_pipe_callbacks(ctypes.Structure):
 _fields_ = [("priv",                ctypes.POINTER(None)),
             ("start_of_measure",    CB_STARTMEAS),
             ("end_of_measure",      CB_ENDMEAS),
             ("millisecond_countup", CB_MILLISEC),
             ("statistics",          CB_STATISTICS),
             ("tdc_event",           CB_TDCEVENT),
             ("dld_event",           CB_DLDEVENT)]

if os.name == 'nt':
    _FUNCTYPE = ctypes.WINFUNCTYPE
else:
    _FUNCTYPE = ctypes.CFUNCTYPE
CB_STARTMEAS  = _FUNCTYPE(None, ctypes.POINTER(None))
CB_ENDMEAS    = CB_STARTMEAS
CB_MILLISEC   = CB_STARTMEAS
CB_STATISTICS = _FUNCTYPE(None, ctypes.POINTER(None),
                          ctypes.POINTER(statistics_t))
CB_TDCEVENT   = _FUNCTYPE(None, ctypes.POINTER(None),
                          ctypes.POINTER(tdc_event_t), ctypes.c_size_t)
CB_DLDEVENT   = _FUNCTYPE(None, ctypes.POINTER(None),
                          ctypes.POINTER(dld_event_t), ctypes.c_size_t)
class scTDC.sc_pipe_callback_params_t
class sc_pipe_callback_params_t(ctypes.Structure):
 _fields_ = [("callbacks", ctypes.POINTER(sc_pipe_callbacks))]
class scTDC.sc_pipe_buf_callbacks_params_t
 class sc_pipe_buf_callbacks_params_t(ctypes.Structure):
_fields_ = [("priv",                  ctypes.POINTER(None)),
            ("data",                  CB_BUFDATA_DATA),
            ("end_of_measurement",    CB_BUFDATA_END_OF_MEAS),
            ("data_field_selection",  ctypes.c_uint),
            ("max_buffered_data_len", ctypes.c_uint),
            ("dld_events",            ctypes.c_int),
            ("version",               ctypes.c_int),
            ("reserved",              ctypes.c_ubyte * 24)]

Types returned when reading pipes (or getting callbacks from pipes):

class scTDC.statistics_t
class statistics_t(ctypes.Structure):
 _fields_ = [("counts_read", ctypes.c_uint * 64),
             ("counts_received", ctypes.c_uint * 64),
             ("events_found", ctypes.c_uint * 4),
             ("events_in_roi", ctypes.c_uint * 4),
             ("events_received", ctypes.c_uint * 4),
             ("counters", ctypes.c_uint * 64),
             ("reserved", ctypes.c_uint * 52)]
class scTDC.tdc_event_t
class tdc_event_t(ctypes.Structure):
 _fields_ = [("subdevice",     ctypes.c_uint),
             ("channel",       ctypes.c_uint),
             ("start_counter", ctypes.c_ulonglong),
             ("time_tag",      ctypes.c_ulonglong),
             ("time_data",     ctypes.c_ulonglong),
             ("sign_counter",  ctypes.c_ulonglong)]
class scTDC.dld_event_t
class dld_event_t(ctypes.Structure):
 _fields_ = [("start_counter",      ctypes.c_ulonglong),
             ("time_tag",           ctypes.c_ulonglong),
             ("subdevice",          ctypes.c_uint),
             ("channel",            ctypes.c_uint),
             ("sum",                ctypes.c_ulonglong),
             ("dif1",               ctypes.c_ushort),
             ("dif2",               ctypes.c_ushort),
             ("master_rst_counter", ctypes.c_uint),
             ("adc",                ctypes.c_ushort),
             ("signal1bit",         ctypes.c_ushort)]
class scTDC.sc_pipe_buf_callback_args
class sc_pipe_buf_callback_args(ctypes.Structure):
 _fields_ = [("event_index",        ctypes.c_ulonglong),
             ("som_indices",        ctypes.POINTER(ctypes.c_ulonglong)),
             ("ms_indices",         ctypes.POINTER(ctypes.c_ulonglong)),
             ("subdevice",          ctypes.POINTER(ctypes.c_uint)),
             ("channel",            ctypes.POINTER(ctypes.c_uint)),
             ("start_counter",      ctypes.POINTER(ctypes.c_ulonglong)),
             ("time_tag",           ctypes.POINTER(ctypes.c_uint)),
             ("dif1",               ctypes.POINTER(ctypes.c_uint)),
             ("dif2",               ctypes.POINTER(ctypes.c_uint)),
             ("time",               ctypes.POINTER(ctypes.c_ulonglong)),
             ("master_rst_counter", ctypes.POINTER(ctypes.c_uint)),
             ("adc",                ctypes.POINTER(ctypes.c_int)),
             ("signal1bit",         ctypes.POINTER(ctypes.c_ushort)),
             ("som_indices_len",    ctypes.c_uint),
             ("ms_indices_len",     ctypes.c_uint),
             ("data_len",           ctypes.c_uint),
             ("reserved",           ctypes.c_char * 12)]