10.5. dataIO#

This section contains the script reference to the class dataIO, used to access any dataIO hardware in itom (e.g. cameras, AD-converters or further data communication plugins). Read the overview document for more details about the Python interface of the class dataIO.

class itom.dataIO(name, *args, **kwds)#

Creates a new instance of the dataIO plugin name.

This is the constructor for an dataIO plugin. It initialises an new instance of the plugin with the given name. The initialisation parameters are parsed and unnamed parameters are used in their incoming order to fill first mandatory parameters and afterwards optional parameters. Parameters may be passed with their name as keyword, too. However, as usual, no positional parameters are allowed after a keyword-based one.

See pluginHelp() for detailed information about the specific initialisation parameters.

Parameters:
namestr

is the fullname (case sensitive) of an dataIO-plugin.

*argsAny

Every actuator plugin defines a list of mandatory and optional initialization parameters. Pass these arguments either as positional (*args) or keyword based (**kwds) arguments, where the mandatory parameters must be given first, followed by the optional ones. Not every optional initialization argument must be given, else its default value is used.

**kwdsAny

Further keyword based parameters. See also *args.

Returns:
actuator

new instance of the desired dataIO plugin.

acquire(trigger=dataIO.TRIGGER_SOFTWARE)#

Triggers a new camera acquisition.

This method triggers a new data acquisition. This method immediately returns even if the acquisition is not finished yet. Use getVal() or copyVal() to get the acquired data. Both methods will then block until the data is available or a timeout occurred.

Before calling acquire(), the device must have been started using startDevice().

Parameters:
triggerint, optional

Type of the trigger:

  • dataIO.TRIGGER_SOFTWARE = 0 : a software trigger is started, hence, the acquisition is immediately started when calling this method.

  • others : depending on your camera, this parameter can be used to set other triggers, like hardware trigger with raising or falling edges… Please consider the documentation of the specific device for possible values.

connect(signalSignature, callableMethod, minRepeatInterval=0)#

Connects a signal of this dataIO device with the given callable Python method.

Every dataIO object can emit different signals whenever a certain event occurs. Use the method info() to get a print-out of a list of possible signals of the dataIO device. This method is used to connect a certain callable Python callback method or function to a specific signal. The callable function can be bounded as well as unbounded.

The connection is described by the string signature of the signal (hence the source of the connection). Such a signature is the name of the signal, followed by the types of its arguments (the original C++ types). An example is destroyed(), emitted if this device is internally deleted. This signal can be connected to a callback function with no arguments, since the signal has no arguments, too. In case of a bounded method, the self argument must be given in any case.

If the signal should have further arguments with specific datatypes, they are transformed into corresponding Python data types. A table of supported conversions is given in section Supported data types. In general, a callableMethod must be a method or function with the same number of parameters than the signal has (besides the self argument).

If a signal is emitted very often, it can be necessary to limit the call of the callback function to a certain minimum time interval. This can be given by the minRepeatInterval parameter.

Parameters:
signalSignaturestr

This must be the valid signature, known from the Qt-method connect (e.g. targetChanged(QVector<double>))

callableMethodcallable()

valid method or function that is called if the signal is emitted.

minRepeatIntervalint, optional

If > 0, the same signal only invokes a slot once within the given interval (in ms). Default: 0 (all signals will invoke the callable python method.

See also

disconnect, info
copyVal(destObject)#

Gets deep copy of data of this plugin, stored in the given data object.

Returns a deep copy of the recently acquired data (for grabber and ADDA only) of the camera or AD-converter device. The deep copy sometimes requires one copy operation more than the similar command getVal(). However, getVal() only returns a reference to the plugin internal data structure whose values might be changed if another data acquisition is started.

If no acquisition has been triggered, this method raises a RuntimeError. If the acquisition is not finished yet, this method blocks and waits until the end of the acquisition.

Parameters:
destObjectdataObject

dataObject where the plugin data is copied to. Either provide an empty dataObject or a dataObject whose shape exactly fits to the shape of the available data of the plugin. Therefore you can allocate a 3D data object, set a region of interest to one plane such that the data from the plugin is copied into this plane.

Raises:
RuntimeError

if the dataIO plugin is anything else than ADDA or grabber or if no acquisition has been triggered

See also

getVal
disableAutoGrabbing()#

Disables auto grabbing for this grabber (camera…).

If the auto grabbing flag is set, the camera acquisition is continuously triggered if at least one live image is connected to the camera. The default and minimum interval between two grabs is 20 ms. It can be changed via setAutoGrabbingInterval(). If the grabbing process is slower, the camera tries to acquire new images as fast as possible.

Enabling this auto grabbing mechanism can be undesired behaviour for instance if a measurement is started where the acquisition should be controlled by a specific script or something similar. In this case, disable the auto grabbing property. All connected live images will then get new images only if getVal() or copyVal() is called.

This method disables the auto grabbing timer.

See also

setAutoGrabbing, enableAutoGrabbing, getAutoGrabbing, setAutoGrabbingInterval
disconnect(signalSignature, callableMethod)#

Disconnects a connection which must have been established before with exactly the same parameters.

Parameters:
signalSignaturestr

This must be the valid signature, known from the Qt-method connect (e.g. clicked(bool))

callableMethodcallable()

valid method or function, that should not be called any more if the given signal is emitted.

See also

connect, info
enableAutoGrabbing()#

Enables auto grabbing for the grabber (camera…).

If the auto grabbing flag is set, the camera acquisition is continuously triggered if at least one live image is connected to the camera. The default and minimum interval between two grabs is 20 ms. It can be changed via setAutoGrabbingInterval(). If the grabbing process is slower, the camera tries to acquire new images as fast as possible.

Enabling this auto grabbing mechanism can be undesired behaviour for instance if a measurement is started where the acquisition should be controlled by a specific script or something similar. In this case, disable the auto grabbing property. All connected live images will then get new images only if getVal() or copyVal() is called.

This method enables the auto grabbing timer.

See also

setAutoGrabbing, disableAutoGrabbing, getAutoGrabbing, setAutoGrabbingInterval
exec(funcName, *args, **kwds) → Any | Tuple[Any]#

Calls the additional function funcName of this plugin.

Every plugin can define special, additional functions (denoted as exec functions) that can for instance be used in order to call specific calibration routines of cameras or actuators. This generic method is used to call one of these specific functions, that has to be registered in the plugin under the name funcName.

Every function can define a set of mandatory and / or optional parameters. See getExecFuncsInfo() or the plugin help viewer of itom for more information. Pass the mandatory and optional parameters as arguments param1, param2 … to this method.

Additionally, every function can return one or multiple values. Either the single value or a tuple of all returned values is returned by this method.

Parameters:
funcNamestr

The name of the additional function.

*argsAny

Further positional arguments, that are assigned first to all mandatory parameters, followed by the optional ones. The mandatory or optional parameters of the called function can also given as keyword arguments (see **kwds).

**kwdsAny, optional

Keyword-based arguments, see *args above.

Returns:
any or tuple of any

The returned values depend on the function itself.

See also

getExecFuncsInfo
getAutoGrabbing() → bool#

Returns if the auto grabbing property of this grabber device is enabled or disabled.

If the auto grabbing flag is set, the camera acquisition is continuously triggered if at least one live image is connected to the camera.

Enabling this auto grabbing mechanism can be undesired behaviour for instance if a measurement is started where the acquisition should be controlled by a specific script or something similar. In this case, disable the auto grabbing property. All connected live images will then get new images only if getVal() or copyVal() is called.

Returns:
bool

True if the auto grabbing timer is currently active, otherwise False.

See also

enableAutoGrabbing, disableAutoGrabbing, setAutoGrabbing
getAutoGrabbingInterval() → int#

Returns the current auto grabbing interval (in ms), even if auto grabbing is disabled.

If auto grabbing is enabled for a grabber device, a timer is set that continuously acquires data or images from the devices and sends it to all connected plots or other listeners. The timer event will occur with a certain interval (in ms). However, if the image acquisition requires more time than the interval, several timer events will be automatically omitted, such that the next image is only acquired if the grabber device is in an idle state again. Hence, the interval is considered to be a minimum value.

The default interval of newly started grabber devices in 20 ms.

Returns:
int

the current auto grabbing timer interval in ms.

See also

enableAutoGrabbing, disableAutoGrabbing, getAutoGrabbing, setAutoGrabbing, setAutoGrabbingInterval
getExecFuncsInfo(funcName='', detailLevel=0) → dict | None#

Lists all available additional functions of this plugin or gives a detailed description of one specific funcName.

Every plugin can define further functions, that are called by the method exec(). This can for instance be used in order to call specific calibration routines of cameras or actuators.

This method either prints requested information in a readable form to the command line or returns this information as nested dictionary.

Parameters:
funcNamestr, optional

is the fullname or a part of any name of such an additional plugin function. If funcName is an empty string or does not match any plugin function (case sensitive), a list of all suitable additional plugin function names is given. Else, detailed information about the desired funcName is given, like its description or (optional) arguments that are needed to execute this function.

detailLeveldict, optional

if detailLevel == 1, this returns a nested dictionary with detailed information, else it is printed to the command line in a readable form (default).

Returns:
None or dict

The return value depends on the argument detailLevel.

See also

exec
getExecFuncsList() → List[str]#

Gets a list of the names of additional callable functions of this plugin.

Each plugin may define a set of functions, extending the standard interface. These functions are not common to plugins of the same type. They are executed using:

instance.exec("funcname", arg1, arg2, ...)

To get more information about one specific function, call getExecFuncsInfo().

Returns:
list of str

is a list of additional, callable function names of this plugin object.

getParam(name) → int | float | str | Tuple[int] | Tuple[float] | dataObject | polygonMesh | pointCloud | dataIO | actuator#

Returns the current value of the plugin parameter name.

The type of the returned value depends on the real type of the internal plugin, which can be:

The name of the parameter must have the following form:

  • name

  • name:additionalTag (additionalTag can be a special feature of some plugins)

  • name[index] (only possible if parameter is an array type and you only want to get one single value, specified by the integer index [0, len(array) - 1])

  • name[index]:additionalTag (a combination of the two possibilities above)

Parameters:
namestr

Name of the requested parameter.

Returns:
int or float or str or tuple of int or tuple of float or dataObject or polygonMesh or pointCloud or dataIO or actuator

Current value of the parameter name.

Raises:
ValueError

if parameter does not exist

See also

setParam, getParamList, getParamListInfo
getParamInfo(name) → dict#

Returns a nested dictionary with meta information of the desired parameter.

Plugin parameters in itom not only hold a value, but they can also be equipped with further meta information, like the minimum or maximum value range, a certain step size, allowed string values etc.

These values are returned as nested dictionary (if available, else the dict is more or less empty).

Parameters:
namestr

Name of the plugin parameter.

Returns:
dict

nested dictionary with meta information assigned to the plugin parameter name.

getParamList() → List[str]#

Returns a list of the names of all available parameters of this plugin object.

Each plugin defines a set of parameters. Each of these parameters maps its name to a certain value. The value is represented by the C++ class ito::ParamBase and can have one of the following types (Python equivalent in brackets):

  • String (str)

  • Char (int, [-127, 128])

  • Integer, (int)

  • Double (float)

  • CharArray (sequence of int)

  • IntegerArray (sequence of int)

  • DoubleArray (sequence of float)

  • DataObject (dataObject)

  • PolygonMesh (polygonMesh)

  • PointCloud (pointCloud)

  • Another plugin instance (dataIO or actuator)

Using one of the parameter names, its current value can be obtained by getParam("name") and can be set by setParam("name", newValue) (if not read-only).

Usually, every plugin object can define its own set of parameters. However, there are conventions about certain parameters, that must be available and have a specific meaning for a type of plugin object.

Returns:
list of str

list of available parameter names in this plugin.

See also

getParam, setParam, getParamListInfo
getParamListInfo(detailLevel=1) → dict | None#

Prints or returns detailed information about all parameters of this plugin object.

Each plugin defines a set of parameters. Each of these parameters maps its name to a certain value. The value is represented by the C++ class ito::ParamBase and can have one of the following types (Python equivalent in brackets):

  • String (str)

  • Char (int, [-127, 128])

  • Integer, (int)

  • Double (float)

  • CharArray (sequence of int)

  • IntegerArray (sequence of int)

  • DoubleArray (sequence of float)

  • DataObject (dataObject)

  • PolygonMesh (polygonMesh)

  • PointCloud (pointCloud)

  • Another plugin instance (dataIO or actuator)

Using one of the parameter names, its current value can be obtained by getParam("name") and can be set by setParam("name", newValue) (if not read-only).

This method prints a detailed listing with the name, current value, description string and further meta information of every plugin parameter. Additionally, the column R/W indicates if this parameter is writable or read-only.

Dependin`g on detailLevel, this method will not print the listing to the command line but returns it using a nested dict.

Parameters:
detailLeveldict, optional

if detailLevel is set to 1, this method returns a nested dictionary with all information about all parameters of this plugin. Otherwise None is returned and the listing is printed in a readable form to the command line (default).

Returns:
None or dict

See the parameter detailLevel for the difference in returned values.

See also

getParam, setParam, getParamInfo, getParamList, getParamInfo
getType() → int#

Returns the type value of this specific dataIO plugin.

Possible values are:

  • 0x081: a camera or general grabber device

  • 0x101: a analog-digital converter device

  • 0x201: any other kind of device (e.g. data transfer, like serial ports, USB ports, … but also other devices like a power supply…).

Returns:
int

dataIO type identifier.

getVal(dataObj) → None#
getVal(buffer, length=INT_MAX) → int

Gets shallow copy of internal camera image if dataObj is provided. Else values from the plugins are copied to given buffer.

Returns a reference (shallow copy) of the recently acquired image (located in the internal memory if the plugin) if the plugin is a grabber or camera and the buffer is a dataObject. Please consider that the values of the dataObject might change if a new image is acquired since it is only a reference. Therefore consider copying the dataObject or directly use copyVal().

If no acquisition has been triggered, this method raises a :obj`RuntimeError`. If the acquisition is not finished yet, this method blocks and waits until the end of the acquisition.

If the plugin is another type than a grabber or camera (e.g. serialIO), this method requires any buffer object that is preallocated with a reasonable size (e.g. bytearray, bytes or unicode str. Then, the currently available data is copied into this buffer object and the size of the copied data is returned. If the buffer is too small, only the data that fits into the buffer is copied. Another call to getVal() will copy the rest.

Parameters:
dataObjdataObject

Usually for cameras and grabber: A reference (shallow copy) to the internal memory of the camera plugin is set to the given data object. Therefore its content may change if a new image is being acquired by the camera. Consider taking a deep copy if the image (dataObject.copy()) or use the method copyVal().

bufferbytearray or bytes or str

Usually for all other IO devices or AD-converters: The buffer must be an object of type bytearray, bytes or unicode str. The length parameter is then set to the size of the allocated buffer. This buffer is then filled with data and the filled size is returned (max: length).

lengthint, optional

Size of the given buffer. This value is usually automatically determined and must not be given.

Returns:
None or int

None if dataObj is given, else the size of the values filled into the given buffer.

See also

copyVal
hideToolbox()#

Hides the visible toolbox of this plugin object.

Raises:
RuntimeError

if this plugin does not provide a toolbox.

See also

showToolbox
info(verbose=0)#

Prints out information about signal and callable slots of this actuator.

Parameters:
verboseint

0: only slots and signals from the plugin class are printed (default) 1: all slots and signals from all inherited classes are printed

See also

connect, disconnect
name() → str#

Returns the name of this plugin object.

Returns:
namestr

name of the plugin, which corresponds to getParam("name")

See also

getParam
setAutoGrabbing(enable)#

Enables or disables the auto grabbing property of this grabber device.

If the auto grabbing flag is set, the camera acquisition is continuously triggered if at least one live image is connected to the camera.

Enabling this auto grabbing mechanism can be undesired behaviour for instance if a measurement is started where the acquisition should be controlled by a specific script or something similar. In this case, disable the auto grabbing property. All connected live images will then get new images only if getVal() or copyVal() is called.

Parameters:
enablebool

True will enable the auto grabbing timer, False disables it.

See also

enableAutoGrabbing, disableAutoGrabbing, getAutoGrabbing
setAutoGrabbingInterval()#

Changes the minimum auto grabbing interval (in ms) between two auto-grabbed datasets.

If auto grabbing is enabled for a grabber device, a timer is set that continuously acquires data or images from the devices and sends it to all connected plots or other listeners. The timer event will occur with a certain interval (in ms). However, if the image acquisition requires more time than the interval, several timer events will be automatically omitted, such that the next image is only acquired if the grabber device is in an idle state again. Hence, the interval is considered to be a minimum value.

The default interval of newly started grabber devices in 20 ms. It is possible to change this interval even if auto grabbing is currently disabled. The new interval will be considered from the next activation on.

Parameters:
intervalint

New minimum auto grabbing timer interval in ms.

See also

enableAutoGrabbing, disableAutoGrabbing, getAutoGrabbing, setAutoGrabbing, getAutoGrabbingInterval
setParam(name, value)#

Sets a writeable parameter name of this plugin object to value.

Sets the internal plugin parameter with ‘name’ to a new value. The plugin itself can decide whether the given value is accepted as new value. This may depend on the type of the given value, but also on the allowed value range indicated by further meta information of the internal parameter. Parameters that are (currently) set to read-only cannot be set.

The name of the parameter must have the following form:

  • name

  • name:additionalTag (additionalTag can be a special feature of some plugins)

  • name[index] (only possible if parameter is an array type and you only want to get one single value, specified by the integer index [0,nrOfArrayItems-1])

  • name[index]:additionalTag (a combination of the two possibilities above)

Parameters:
namestr

Name of the parameter.

valueint or float or str or tuple of int or tuple of float or dataObject or polygonMesh or pointCloud or dataIO or actuator

The value that will be set. The plugin will check if this value fits to possible constraints, given by the parameters’s meta information or further limitations.

Raises:
RuntimeError

if the new value is (currently) not accepted.

See also

getParam, getParamList, getParamListInfo
setVal(dataObj) → None#
setVal(buffer, length=1) → None

Transfers a dataObject to an ADDA plugin for write, or a bytearray to other dataIO plugins for general purposes.

If the dataIO plugin has the subtype ADDA (analog-digital converter), this method is used to send data to one or more analog outputs of the device. In this case a dataObject must be given as first and only argument. and the second argument length must be 1.

For other dataIO plugins, the first argument must be any buffer object, like a bytearray, bytes or unicode str. The length is then extracted from this value. However it is also possible to define a user-defined size using the length argument.

Parameters:
dataObjdataObject

The array, that should be transmitted to the output of an analog-digital converter. Usually, the shape of this array is M x N, where M channels will obtain up to N new values. This argument is used for ADDA dataIO devices.

bufferbytearray or bytes or str

Other dataIO devices than ADDA need to pass a buffer object, like a bytearray, bytes or unicode str.

lengthint, optional

Usually, this value is not required, since the length of the buffer is automatically extracted from the given object.

showConfiguration()#

Shows the (optional) configuration dialog of this plugin as modal dialog.

Raises:
RuntimeError

if this plugin does not provide a configuration dialog.

showToolbox()#

Opens the (optional) toolbox of this plugin object in the itom main window.

Raises:
RuntimeError

if this plugin does not provide a toolbox.

See also

hideToolbox
startDevice(count=1)#

Starts the given dataIO plugin object.

This command starts the dataIO plugin such that it is ready for data acquisition. Call this method before you start using commands like acquire(), getVal() or copyVal(). If the device already is started, an internal start-counter is incremented by the parameter count. The corresponding stopDevice() method then decrements this counter and finally stops the device once the counter drops to zero again.

The counter is necessary, since every connected live image needs to start the device without knownledge about any previous start. No acquisition is possible, if the device has not been started, hence the counter is 0.

Parameters:
countint, optional

Number of increments to the internal start-counter (default: 1).

See also

stopDevice
stop()#

Stops a started, continuous acquisition.

This method stops a previously started, continuous data acquisition. This method is not implemented in every plugin. A common example for its implementation is to stop an infinite, continuous acquisition job of an AD-converter plugin.

See also

acquire
stopDevice(count=1) → int | None#

Stops the given dataIO plugin object.

If this method is called as many times as he corresponding startDevice() method (or if the counts are equal), the dataIO device is stopped (not deleted) and it is not possible to acquire further data.

Once a live image is connected to a camera, startDevice() is automatically called at start of the live acquisition and stopDevice() at shutdown.

Parameters:
countint, optional

if count > 1, stopDevice() is executed count times, in order to decrement the grabber internal start counter. You can also set count = -1, then stopDevice() is called in a loop until the internal start counter drops to 0. The number of effective counts is then returned.

Returns:
countsNone or int

If count = -1 the number of required calls to stopDevice to finally stop the device is returned. For count >= 0, None is returned.

See also

startDevice
userMutexTryLock()#

tryLock(timeout = 3000) -> bool

Tries to lock the user mutex of this plugin.

Every plugin contains a user mutex, that can be used for arbitrary purposes. It is not used for any official purposes. You can for instance use this mutex both from Python and other C++ threads to protect a series of calls to this plugin to not to be interrupted by other participants. However, it is the full responsibility of the programmer to carefully use this mutex.

Please be careful, that this method can lead to a deadlock if timeout is set to a negative value (infinite wait) and if the mutex is not released by any other thread. Hint: A Python thread is no real thread, it must be a real C++ thread. If you want to use the mutex within two or more Python threads, it is recommended, to call this method with a defined timeout within a loop and wait for this method to return True. This allows unlocking the mutex by another thread.

This method is new for plugins that implement the AddInInterface >= 4.2.

Parameters:
timeoutint

This method will wait for at most timeout milliseconds for the mutex to become available. If this value is negative, it will wait forever until the mutex become available.

Returns:
bool

True if the user defined mutex could be locked, else False.

See also

unlock
userMutexUnlock()#

Tries to unlock the user mutex of this plugin.

Every plugin contains a user mutex, that can be used for arbitrary purposes. It is not used for any official purposes. You can for instance use this mutex both from Python and other C++ threads to protect a series of calls to this plugin to not to be interrupted by other participants. However, it is the full responsibility of the programmer to carefully use this mutex. fu This method is new for plugins that implement the AddInInterface >= 4.2.

See also

lock
TRIGGER_SOFTWARE = 0#
On this page
Show Source