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...
-
copyVal
(dataObject) → 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: dataObject : {
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
-
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
execFuncsInfo
-
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
-
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]) → 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
- cameras, grabber: the buffer must be a
-
hideToolbox
() → hides toolbox of the plugin¶ Raises: RuntimeError :
if plugin does not provide a toolbox
See also
-
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
-
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 returnedReturns: counts : {None or int}
If count == -1 the number of required counts to finally stop the device is returned. Else: None
See also
-