class Device¶
- class scTDC.Device(inifilepath='tdc_gpx3.ini', autoinit=True, lib=None)¶
A higher-level interface for TDCs and DLDs for applications that use pre-computed histograms from the scTDC library.
- __init__(inifilepath='tdc_gpx3.ini', autoinit=True, lib=None)¶
Creates a device object.
- Parameters
inifilepath (str, optional) – the name of or full path to the configuration/ini file, defaults to “tdc_gpx3.ini”
autoinit (bool, optional) – if True, initialize the hardware immediately, defaults to True
lib (
scTDClib
, optional) – if not None, reuse the specified scTDClib object, else the Device class creates its own scTDClib object internally, defaults to None
- initialize()¶
Initialize the hardware.
- Returns
a tuple containing an error code and a human-readable error message (zero and empty string in case of success)
- Return type
tuple(int, str)
- deinitialize()¶
Deinitialize the hardware.
- Returns
a tuple containing an error code and a human-readable error message (zero and empty string in case of success)
- Return type
tuple(int, str)
- is_initialized()¶
Query whether the device is initialized
- Returns
True if the device is initialized
- Return type
bool
- do_measurement(time_ms=100, synchronous=False)¶
Start a measurement.
- Parameters
time_ms (int, optional) – the measurement time in milliseconds, defaults to 100
synchronous (bool, optional) – if True, block until the measurement has finished. defaults to False.
- Returns
a tuple (0, “”) in case of success, or a negative error code and a string with the error message
- Return type
tuple(int, str)
- interrupt_measurement()¶
Interrupt a measurement that was started with synchronous=False.
- Returns
a tuple (0, “”) in case of success, or a negative error code and a string with the error message
- Return type
tuple(int, str)
- add_end_of_measurement_callback(cb)¶
Adds a callback function for the end of measurement. The callback function needs to accept one
int
argument which indicates the reason for the callback. Notification via callback is useful if you want to use do_measurement(…) with synchronous=False, for example in GUIs that need to be responsive during measurement.- Parameters
cb (Callable) – the callback function
- Returns
non-negative ID of the callback (for later removal)
- Return type
int
- remove_end_of_measurement_callback(id_of_cb)¶
Removes a previously added callback function for the end of measurement.
- Parameters
id_of_cb (int) – the ID as previously returned by
add_end_of_measurement_callback
.- Returns
0 on success, -1 if the id_of_cb is unknown
- Return type
int
- add_3d_pipe(depth, modulo, binning, roi)¶
Adds a 3D pipe (x, y, time) with static buffer. The 3D buffer retrieved upon reading is organized such that a point (x, y, time_slice) is addressed by x + y * size_x + time_slice * size_x * size_y. When getting a numpy array view/copy of the buffer, the ‘F’ (Fortran) indexing order can be chosen, such that the indices are intuitively ordered as x, y, time.
- Parameters
depth (int) – one of BS8, BS16, BS32, BS64, BS_FLOAT32, BS_FLOAT64
modulo (int) – If 0, no effect. If > 0, a module operation is applied to the time values of events before sorting events into the 3D buffer. The unit of the module value is the time bin divided by 32, i.e. a modulo value of 32 corresponds to one time bin.
binning ((int,int,int)) – a 3-tuple specifying the binning in x, y, and time, where all values need to be a power of 2.
roi (((int, int), (int, int), (int, int))) – a 3-tuple of (offset, size) pairs specifying the ranges along the x, y, and time axes.
- Returns
a tuple containing a non-negative pipe ID and the Pipe object in case of success. A tuple containing the negative error code and the error message in case of failure.
- Return type
tuple(int, Pipe) | tuple(int, str)
- add_xy_pipe(depth, modulo, binning, roi)¶
Adds a 2D pipe (x,y) with static buffer. The 2D buffer retrieved upon reading is organized such that a point (x,y) is addressed by x + y * size_x. When getting a numpy array view/copy of the buffer, the ‘F’ (Fortran) indexing order can be chosen, such that the indices are intuitively ordered x, y. The binning in time has an influence only on the time units in the roi. The time part in the roi specifies the integration range, such that only events inside this time range are inserted into the data buffer.
- Parameters
depth (int) – one of BS8, BS16, BS32, BS64, BS_FLOAT32, BS_FLOAT64
modulo (int) – If 0, no effect. If > 0, a module operation is applied to the time values of events before sorting events into the 2D buffer. The unit of the module value is the time bin divided by 32, i.e. a modulo value of 32 corresponds to one time bin.
binning ((int,int,int)) – a 3-tuple specifying the binning in x, y, and time, where all values need to be a power of 2.
roi (((int, int), (int, int), (int, int))) – a 3-tuple of (offset, size) pairs specifying the ranges along the x, y, and time axes.
- Returns
a tuple containing a non-negative pipe ID and the Pipe object in case of success. A tuple containing the negative error code and the error message in case of failure.
- Return type
tuple(int, Pipe) | tuple(int, str)
- add_xt_pipe(depth, modulo, binning, roi)¶
Adds a 2D pipe (x,t) with static buffer. The 2D buffer retrieved upon reading is organized such that a point (x,time) is addressed by x + time * size_x. When getting a numpy array view/copy of the buffer, the ‘F’ (Fortran) indexing order can be chosen, such that the indices are intuitively ordered x, time. The binning in y has an influence only on the y units in the roi. The y part in the roi specifies the integration range, such that only events inside this y range are inserted into the data buffer.
- Parameters
depth (int) – one of BS8, BS16, BS32, BS64, BS_FLOAT32, BS_FLOAT64
modulo (int) – If 0, no effect. If > 0, a module operation is applied to the time values of events before sorting events into the 2D buffer. The unit of the module value is the time bin divided by 32, i.e. a modulo value of 32 corresponds to one time bin.
binning ((int,int,int)) – a 3-tuple specifying the binning in x, y, and time, where all values need to be a power of 2.
roi (((int, int), (int, int), (int, int))) – a 3-tuple of (offset, size) pairs specifying the ranges along the x, y, and time axes.
- Returns
a tuple containing a non-negative pipe ID and the Pipe object in case of success. A tuple containing the negative error code and the error message in case of failure.
- Return type
tuple(int, Pipe) | tuple(int, str)
- add_yt_pipe(depth, modulo, binning, roi)¶
Adds a 2D pipe (y,t) with static buffer. The 2D buffer retrieved upon reading is organized such that a point (y,time) is addressed by y + time * size_y. When getting a numpy array view/copy of the buffer, the ‘F’ (Fortran) indexing order can be chosen, such that the indices are intuitively ordered y, time. The binning in x has an influence only on the x units in the roi. The x part in the roi specifies the integration range, such that only events inside this x range are inserted into the data buffer.
- Parameters
depth (int) – one of BS8, BS16, BS32, BS64, BS_FLOAT32, BS_FLOAT64
modulo (int) – If 0, no effect. If > 0, a module operation is applied to the time values of events before sorting events into the 2D buffer. The unit of the module value is the time bin divided by 32, i.e. a modulo value of 32 corresponds to one time bin.
binning ((int,int,int)) – a 3-tuple specifying the binning in x, y, and time, where all values need to be a power of 2.
roi (((int, int), (int, int), (int, int))) – a 3-tuple of (offset, size) pairs specifying the ranges along the x, y, and time axes.
- Returns
a tuple containing a non-negative pipe ID and the Pipe object in case of success. A tuple containing the negative error code and the error message in case of failure.
- Return type
tuple(int, Pipe) | tuple(int, str)
- add_t_pipe(depth, modulo, binning, roi)¶
Adds a 1D time histogram pipe, integrated over a rectangular region in the (x,y) plane (for delay-line detectors) with static buffer. The buffer received upon reading is a 1D array of the intensity values for all resolved time bins. The binning in x and y has an influence only on the x and y units in the roi. The x and y parts in the roi specify the integration ranges, such that only events inside the x and y ranges are inserted into the data buffer.
- Parameters
depth (int) – one of BS8, BS16, BS32, BS64, BS_FLOAT32, BS_FLOAT64
modulo (int) – If 0, no effect. If > 0, a module operation is applied to the time values of events before sorting events into the 1D array. The unit of the module value is the time bin divided by 32, i.e. a modulo value of 32 corresponds to one time bin.
binning ((int,int,int)) – a 3-tuple specifying the binning in x, y, and time, where all values need to be a power of 2.
roi (((int, int), (int, int), (int, int))) – a 3-tuple of (offset, size) pairs specifying the ranges along the x, y, and time axes.
- Returns
a tuple containing a non-negative pipe ID and the Pipe object in case of success. A tuple containing the negative error code and the error message in case of failure.
- Return type
tuple(int, Pipe) | tuple(int, str)
- add_statistics_pipe()¶
Adds a pipe for statistics data (sometimes referred to as rate meters). The statistics data is only updated at the end of each measurement.
- Returns
a tuple containing a non-negative pipe ID and the Pipe object in case of success. A tuple containing the negative error code and the error message in case of failure.
- Return type
tuple(int, Pipe) | tuple(int, str)
- add_tdc_histo_pipe(depth, channel, modulo, binning, offset, size)¶
Adds a pipe for time histograms from a stand-alone TDC. TDC events are filtered by the specified channel, and their time values are transformed first by modulo, then by binning, then by subtraction of the offset, and finally, by clipping to the size value. The resulting value (if not clipped) is the array index of the histogram which is incremented by one.
- Parameters
depth (int) – one of BS8, BS16, BS32, BS64
channel (int) – selects the TDC channel
modulo (int) – If 0, no effect. If > 0, a modulo operation is applied to the time values of TDC events before sorting them into the 1D array. The unit of the module value is the time bin divided by 32, i.e. a modulo value of 32 corresponds to one time bin.
binning (int) – divides the time value by the specified binning before sorting into the 1D array. Must be a power of 2. Binning 1 is equivalent to no binning.
offset (int) – The offset / lower boundary of the accepted range on the time axis.
size (int) – The size / length of the accepted range on the time axis. The size is also directly the number of entries in the array/histogram
- Returns
a tuple containing a non-negative pipe ID and the Pipe object in case of success. A tuple containing the negative error code and the error message in case of failure.
- Return type
tuple(int, Pipe) | tuple(int, str)
- remove_pipe(pipeid)¶
Remove a pipe. Manual removal of pipes may be unnecessary if you are using all created pipes until the deinitialization of the device.
- Parameters
pipeid (int) – the pipe ID as returned in the first element of the tuple by all add_XYZ_pipe functions
- Returns
0 on success, -1 if pipe id unknown or error
- Return type
int
Pixel/Voxel data type constants¶
- scTDC.BS8 = 0¶
pixel data format, unsigned 8-bit integer
- scTDC.BS16 = 1¶
pixel data format, unsigned 16-bit integer
- scTDC.BS32 = 2¶
pixel data format, unsigned 32-bit integer
- scTDC.BS64 = 3¶
pixel data format, unsigned 64-bit integer
- scTDC.BS_FLOAT32 = 4¶
pixel data format, single-precision floating point number
- scTDC.BS_FLOAT64 = 5¶
pixel data format, double-precision floating point number