9.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 communcation plugins). Read the overview document for more details about the Python interface of the class dataIO.
-
class
itom.
dataIO
(name, *mandparams, *optparams) → creates new instance of dataIO plugin ‘name’¶ This is the constructor for a
dataIO
plugin. It initializes an new instance of the plugin specified by ‘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 name as well but after the first named parameter no more unnamed parameters are allowed.See pluginHelp(name) for detail information about the specific initialisation parameters.
- Parameters
name : {str}
is the fullname (case sensitive) of an ‘actuator’-plugin as specified in the plugin-window.
mandparams : {variant(s)}
arguments corresponding the mandatory initialization parameters. The number of arguments and their order must fit the the required mandatory parameters
optparams : {variant(s)}, optional
argument corresponding to the optional initialization parameters. If unnamed arguments are used, their order must correspond to the order of the optional parameters, keyword-based parameters are allowed as well.
- Returns
inst : {dataIO}
new instance of the dataIO-plugin
-
acquire
(trigger=dataIO.TRIGGER_SOFTWARE) → triggers a new the camera acquisition¶ This method triggers a new data acquisition. This method immediately returns even if the acquisition is not finished yet. Use
getVal
orcopyVal
to get the acquired data. Both methods block until the data is available.- Parameters
trigger : {int}, 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…
-
connect
(signalSignature, callableMethod, minRepeatInterval=0) → connects the signal of the actuator with the given callable python method¶ This instance of dataIO wraps a dataIO device (ADDA, grabber or rawIO), that is defined by a C++ - class, that is finally derived from QObject. Every dataIO can send various signals. Use this method to connect any signal to any callable python method(bounded or unbounded).This method must have the same number of arguments than the signal and the types of the signal definition must be convertable into a python object.
- Parameters
signalSignature : {str}
This must be the valid signature, known from the Qt - method connect (e.g. ‘reachedTarget(bool)’)
callableMethod : {python method or function}
valid method or function that is called if the signal is emitted.
minRepeatInterval : {int}, 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
-
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
destObject : {dataObject}
dataObject
where the plugin data is copied to. Either provide an emptydataObject
or adataObject
whose size (or region of interest) exactly has the same size than 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
-
disableAutoGrabbing
() → Disable auto grabbing for the grabber (camera…),¶ If the auto grabbing flag is set, the camera acquisition is automatically and continuously triggered if at least one live image is connected. This is an undesired behaviour if a measurement is started where the acquisition should be controlled by a specific script or something similar. Then disable the auto grabbing property. All connected live images will then get new images when
getVal
orcopyVal
is called by the script. The live image timer is disabled.This method disables the auto grabbing flag.
See also
-
disconnect
(signalSignature, callableMethod) → disconnects a connection which must have been established with exactly the same parameters.¶ - Parameters
signalSignature : {str}
This must be the valid signature, known from the Qt-method connect (e.g. ‘clicked(bool)’)
callableMethod : {python method or function}
valid method or function, that should not be called any more, if the given signal is emitted.
See also
-
enableAutoGrabbing
() → enable auto grabbing for the grabber (camera…),¶ If the auto grabbing flag is set, the camera acquisition is automatically and continuously triggered if at least one live image is connected. This is an undesired behaviour if a measurement is started where the acquisition should be controlled by a specific script or something similar. Then disable the auto grabbing property. All connected live images will then get new images when
getVal
orcopyVal
is called by the script. The live image timer is disabled.This method enables the auto grabbing flag.
See also
-
exec
(funcName[, param1, ...]) → invoke the function ‘funcName’ registered as execFunc within the plugin.¶ Every plugin can define further functions that can for instance be used in order to call specific calibration routines of cameras or actuators. This general method is used to call one of these specific functions registered under funcName.
- Parameters
funcName : {str}
The name of the function
param1 : {variant}, optional
Further parameters depending on the requirements of the specific function.
- Returns
out : {variant, list of variants}.
The return values depend on the function itself.
See also
-
getAutoGrabbing
() → return the status of the auto grabbing flag.¶ If the auto grabbing flag is set, the camera acquisition is automatically and continuously triggered if at least one live image is connected. This is an undesired behaviour if a measurement is started where the acquisition should be controlled by a specific script or something similar. Then disable the auto grabbing property. All connected live images will then get new images when
getVal
orcopyVal
is called by the script. The live image timer is disabled.- Returns
auto grabbing flag : {bool}
False = auto grabbing off
True = auto grabbing on.
See also
-
getAutoGrabbingInterval
() → 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 windows or listeners. The timer event will occur with a certain interval (in ms). However, if the image acquisition requires more time than the interval, several events can be omitted, such that the next image is only acquired if the grabber device is in an idle state. Hence, the interval is considered to be a minimum value.
-
getExecFuncsInfo
([funcName[, detailLevel]]) → plots a list of available execFuncs or a detailed description of the specified execFunc.¶ Every plugin can define further functions, that are called by plugin.exec(‘funcName’ [,param1, param2…]). This can for instance be used in order to call specific calibration routines of cameras or actuators. This method allows printing information about available functions of this type.
- Parameters
funcName : {str}, optional
is the fullname or a part of any execFunc-name which should be displayed. If funcName is none or no execFunc matches funcName casesensitiv a list with all suitable execFuncs is given.
detailLevel : {dict}, optional
if detailLevel == 1, function returns a dictionary with parameters, else information is print to the command line [default: 0].
- Returns
out : {None or dict}
depending on the value of detailLevel.
See also
-
getExecFuncsList
() → returns a list of the names of the additional 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. These functions are executed using instance.exec(“funcname”,params) to check exact function call use instance.getExecFuncsInfo()getExecFuncsInfo
-
getParam
(name) → current value of the plugin parameter ‘name’.¶ Returns the current value of the internal plugin parameter with ‘name’. The type of the returned value depends on the real type of the internal plugin, which may be:
String -> str
Char, Integer -> int
Double -> float
CharArray, IntegerArray -> tuple of int
DoubleArray -> tuple of float
DataObject -> dataObject
PolygonMesh -> polygonMesh
PointCloud -> pointCloud
Another plugin instance -> dataIO or actuator
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
- Parameters
name : {str}
name of the requested parameter
- Returns
out : {variant}
value of the parameter
- Raises
ValueError :
if parameter does not exist
See also
-
getParamInfo
(name) → returns dictionary with meta information of parameter ‘name’.¶
-
getParamList
() → returns a list of the names of the internal parameters of the plugin¶ Each plugin defines a set of parameters, where each parameter has got a name and maps to any value. The value is represented by the C++ class ito::ParamBase and can have one of the following types:
String
Char
Integer
Double
CharArray
IntegerArray
DoubleArray
DataObject
PolygonMesh
PointCloud
Another plugin instance
Using one of the parameter names, its current value can be obtained by getParam(‘name’) and is writable by setParam(‘name’, newValue) (if not read-only)
- Returns
out : {list}
list of parameter names
See also
-
getParamListInfo
(detailLevel=1) → prints detailed information about all plugin parameters.¶ Each plugin defines a set of parameters, where each parameter has got a name and maps to any value. The value is represented by the C++ class ito::ParamBase and can have one of the following types:
String
Char
Integer
Double
CharArray
IntegerArray
DoubleArray
DataObject
PolygonMesh
PointCloud
Another plugin instance
Using one of the parameter names, its current value can be obtained by getParam(‘name’) and is writable by setParam(‘name’, newValue) (if not read-only)
This method prints a detailed table 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.
- Parameters
detailLevel : {dict}, optional
if detailLevel == 1, function returns a dictionary with parameters, else None is returned and the output is printed in a readable form to the console [default]
- Returns
out : {None, dict}
If detailLevel == 1, a dictionary containing all printed information is returned
See also
-
getType
() → returns dataIO type¶
-
getVal
(buffer=`dataObject`|`bytearray`|`bytes`, length = maxlength) → returns shallow copy of internal camera image if `dataObject`-buffer is provided. Else values from plugin are copied to given byte or byte-array 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 thedataObject
might change if a new image is acquired since it is only a reference. Therefore consider copying thedataObject
or directly usecopyVal
.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.
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. 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
buffer : {
dataObject
, bytearray, bytes or str}this parameter depends on the type of dataIO-instance:
cameras, grabber: the buffer must be a
dataObject
(no length parameter): 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 methodcopyVal
.other IO-devices (AD-converters): The buffer must be an object of type
dataObject
, bytearray, bytes or unicode string. The length parameter is then set to the size of the buffers. The effective size of the used memory in buffer is returned.
length : {int}, optional
size of the given buffer. This value is usually automatically determined and must not be given.
- Returns
out : {None or int}
None or size of used buffer if buffer is no
dataObject
See also
-
hideToolbox
() → hides toolbox of the plugin¶ - Raises
RuntimeError :
if plugin does not provide a toolbox
See also
-
info
(verbose=0) → returns information about signal and slots.¶ - Parameters
verbose : {int}
0: only slots and signals from the plugin class are printed (default) 1: all slots and signals from all inherited classes are printed
-
name
() → returns the plugin name¶ - Returns
name : {str}
name of the plugin, which corresponds to getParam(‘name’)
See also
-
setAutoGrabbing
(on) → Set auto grabbing of the grabber device to on or off¶ If the auto grabbing flag is set, the camera acquisition is automatically and continuously triggered if at least one live image is connected. This is an undesired behaviour if a measurement is started where the acquisition should be controlled by a specific script or something similar. Then disable the auto grabbing property. All connected live images will then get new images when
getVal
orcopyVal
is called by the script. The live image timer is disabled.This method allows setting this flag.
- Parameters
on : {bool}
TRUE = on
FALSE = off
See also
-
setAutoGrabbingInterval
() → Sets the current auto grabbing interval (in ms) without dis- or enabling the auto grabber¶ 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 windows or listeners. The timer event will occur with a certain interval (in ms). However, if the image acquisition requires more time than the interval, several events can be omitted, such that the next image is only acquired if the grabber device is in an idle state. Hence, the interval is considered to be a minimum value.
- Parameters
interval : {int}
Interval in ms.
-
setParam
(name, value) → sets parameter ‘name’ to the given value.¶ Sets the internal plugin parameter with ‘name’ to a new value. The plugin itsself 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 have the read-only flag set can not be reset.
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
- Parameters
name : {str}
name of the parameter
value : {str, int, double, …}
value that will be set. Only the name and existance of the parameter is checked before passing the request to the plugin. The plugin itsself is responsible for further validations (including read-only attribute).
See also
-
setVal
(dataObjectOrBuffer[, length=1]) → transfer given `dataObject` to ADDA plugin or further buffer to other dataIO plugin.¶ If the dataIO plugin has the subtype ADDA, 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 argument and the second argument length must be 1.For other dataIO plugins, the first argument must be any buffer object, like bytearray, bytes or unicode string. The length is then extracted from this value. However it is also possible to define a user-defined size using the ‘length’ argument.
- Parameters
dataObjectOrBuffer : {
dataObject
, bytearray, bytes, str}value to send to plugin. For an ADDA plugin, a
dataObject
is required whose content is sent to the analogous outputs of the device. For other dataIO plugins buffer values like bytearray, bytes or unicode string are required.length : {int}, optional
usually this value is not required, since the length of the buffer is automatically extracted from the given objects and 1 for a
dataObject
-
showConfiguration
() → show configuration dialog of the plugin¶ - Raises
RuntimeError :
if plugin does not provide a configuration dialog
-
showToolbox
() → open toolbox of the plugin¶ - Raises
RuntimeError :
if plugin does not provide a toolbox
See also
-
startDevice
(count=1) → starts the given dataIO-plugin.¶ 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
orcopyVal
. If the device already is started, an internal start-counter is incremented by the parameter ‘count’. The correspondingstopDevice
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
count : {int}, optional
Number of increments to the internal start-counter [default:1]
See also
-
stop
() → stops a started, continuous acquisition¶ This method stops a previously started, continuous data acquisition. This method is not always implemented in plugins. A common example for its implementation is to stop an infinite, continuous acquisition job of a AD-converter plugin.
See also
-
stopDevice
(count=1) → stops the given dataIO-plugin.¶ If this method is called as many times as the corresponding
startDevice
(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 andstopDevice
at shutdown.- Parameters
count : {int}, optional
default = 1 if count > 1,
stopDevice
is executed ‘count’ times, in order to decrement the grabber internal start counter. You can also use -1 as count argument, thenstopDevice
is repeated until the internal start counter is 0. The number of effective counts is then returned- Returns
counts : {None or int}
If count == -1 the number of required counts to finally stop the device is returned. Else: None
See also