dataIO

class itom.dataIO

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 or copyVal 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 empty dataObject or a dataObject 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

getVal

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 or copyVal is called by the script. The live image timer is disabled.

This method disables the auto grabbing flag.

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 or copyVal is called by the script. The live image timer is disabled.

This method enables the auto grabbing flag.

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 or copyVal is called by the script. The live image timer is disabled.

Returns:

auto grabbing flag : {bool}

  • False = auto grabbing off
  • True = auto grabbing on.
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 [default: 0].

Returns:

out : {None or dict}

depending on the value of detailLevel.

See also

exec

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

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

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.

Parameters:

detailLevel : {dict}, optional

if detailLevel == 1, function returns a dictionary with parameters, else None is returned [default]

Returns:

out : {None, dict}

If detailLevel == 1, a dictionary containing all printed information is returned

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 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 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 method copyVal.
  • other IO-devices (AD-converters): The buffer must be an object of type 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

copyVal

hideToolbox() → hides toolbox of the plugin
Raises:

RuntimeError :

if plugin does not provide a toolbox

See also

showToolbox

name() → returns the plugin name
Returns:

name : {str}

name of the plugin, which corresponds to getParam(‘name’)

See also

getParam

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 or copyVal is called by the script. The live image timer is disabled.

This method allows setting this flag.

Parameters:

on : {bool}

  • TRUE = on
  • FALSE = off
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).

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 is 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

hideToolbox

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 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:

count : {int}, optional

Number of increments to the internal start-counter [default:1]

See also

stopDevice

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 and stopDevice 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, then stopDevice 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

startDevice

Previous topic

itom.plot

Next topic

actuator

This Page