10.2. actuator#

This section contains the script reference to the class actuator, used to access any actuator or motor hardware in itom. Read the overview document for more details about the Python interface of the class actuator.

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

Creates a new instance of the actuator plugin name.

This is the constructor for an actuator 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 actuator-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 actuator plugin.

calib(axisIndex1, *args)#

Starts a calibration or homing routine of one or multiple axes.

Most actuators have the possibility to calibrate or home certain axes. Use this command to start the calibration.

Parameters:

axisIndex1int: Index of the first axis to be calibrated or homed (e.g. 0 for first axis).
*argsint: Pass further axis indices as 2nd, 3rd, etc. parameter to this function if more than one axis should be calibrated or homed.

Raises:

NotImplemented: if calibration routine not available in this plugin.

connect(signalSignature, callableMethod, minRepeatInterval=0)#

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

Every actuator 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 actuator. 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 targetChanged(QVector<double>), emitted whenever the target position of one or multiple axes changed. This signal can be connected to a callback function, that accepts one argument (in case of a bounded method, the self argument must be an additional first parameter.

The C++ datatype QVector<double> will be transformed to tuple of float, for more type conversions see the table 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). The types are converted based on the itom C++ <-> Python conversion table (Supported data types).

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

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

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

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.

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:

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, 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.

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

getPos(axisIndex1, *args) → float | Tuple[float]#

Returns the current position(s) of the given axis or axes (in mm or degree).

This method requests the current position(s) of the given axes and returns it or them.

Parameters:

axisIndex1int: index of the first axis (e.g. 0 for first axis)
*argsint: Pass further indices of more axes as additional parameters.

Returns:

positionsfloat or tuple of float: Current position as float value if only one axis is given or a tuple of floats if multiple axis indices are given. The unit is mm or degree.

See also

setPosRel, setPosAbs

getStatus(axis=-1) → int | List[int]#

Returns the status for one single axis or all axes of the actuator object.

Each axis of an actuator plugin has got a status value that is used for informing about the current status of the axis.

The status value is a bitmask (flag), that might contain a combination of the following values:

Moving flags:

actuatorUnknown = 0x0001 : unknown current moving status
actuatorInterrupted = 0x0002 : movement has been interrupted by the user or another error during the movement occurred
actuatorMoving = 0x0004 : axis is currently moving
actuatorAtTarget = 0x0008 : axis reached the target position
actuatorTimeout = 0x0010 : timeout during movement. Unknown status of the movement

Switches flags:

actuatorEndSwitch = 0x0100 : axis reached any end switch (e.g. if only one end switch is available)
actuatorEndSwitch1 = 0x0200 : axis reached the specified left end switch (if set, also set actuatorEndSwitch)
actuatorEndSwitch2 = 0x0400 : axis reached the specified left end switch (if set, also set actuatorEndSwitch)
actuatorRefSwitch = 0x0800 : axis reached any reference switch (e.g. for calibration…)
actuatorRefSwitch1 = 0x1000 : axis reached the specified right reference switch (if set, also set actuatorRefSwitch)
actuatorRefSwitch2 = 0x2000 : axis reached the specified right reference switch (if set, also set actuatorRefSwitch)

Status flags:

actuatorAvailable = 0x4000 : the axis is available
actuatorEnabled = 0x8000 : the axis is currently enabled and can be moved
actuatorError = 0x10000 : axis has encountered error/reports error

Parameters:

axisint, optional: If an index >= 0 is passed, the status of this specific axis is returned. Else, a list of status values for all axes is returned (default).

Returns:

int or list of int: Single status value or a list of status values as combination of the possible flag values, given above.

getType() → int#

Returns the type value of this actuator plugin (always: 0x2).

Returns:

int: actuator type value (0x2).

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

setInterrupt()#

Request the interruption of the movement of this actuator.

Sets the interrupt flag of the actuator. The actuator interrupts the movement of all running axes as soon as this flag is checked and handled again.

setOrigin(axisIndex1, *args)#

Defines the current position of the given axes to have the value 0.

The current positions of all indicated axes (axisIndex1, *args) are considered to be 0 such that future positioning commands are relative with respect to this current position.

Parameters:

axisIndex1int: index of the first axis (e.g. 0 for first axis)
*argsint: Pass further axis indices as 2nd, 3rd, etc. parameter to this function if more than one axis should be origined.

Raises:

NotImplemented: if actuator does not support this feature

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

setPosAbs(axisIndex1, pos1, *args)#

Moves the given axis or axes to the indicated absolute position(s) (in mm or degree).

The parameters of this function are always alternating between the index of one axis and its new absolute target position as following parameter. As an example, moving the first three axes would look like:

myMotor.setPosAbs(0, 10.0, 1, -5.2, 2, 0.7)  # axes 0, 1 and 2 are absolutely moved 

This method starts the absolute positioning of all given axes. If the async parameter (see getParam() and setParam()) of the plugin is 0 (usually default), a synchronous positioning is started, hence, this method returns after that all axes reached their target positions or a timeout occurred. Else, (async = 1) this method immediately returns and the actuator continuous its movement.

Parameters:

axisIndex1int: index of the first axis, that should be moved.
pos1float: absolute target position for this first axis axisIndex1 (in mm or degree)
*args: Pass more arguments of the form axisIndexX, posX to move more than one axis.

See also

getPos, setPosRel

setPosRel(axisIndex1, offset1, *args)#

Moves the given axis or axes to the indicated relative position(s) (in mm or degree).

myMotor.setPosAbs(0, 10.0, 1, -5.2, 2, 0.7)  # axes 0, 1 and 2 are absolutely moved 

This method starts the relative positioning of all given axes. If the async parameter (see getParam() and setParam()) of the plugin is 0 (usually default), a synchronous positioning is started, hence, this method returns after that all axes reached their target positions or a timeout occurred. Else, (async = 1) this method immediately returns and the actuator continuous its movement.

Parameters:

axisIndex1int: index of the first axis, that should be moved.
offset1float: The new target position for the first axis axisIndex1 is given by the current position of this axis plus this offset1 value (in mm or degree)
*args: Pass more arguments of the form axisIndexX, offsetX to move more than one axis.

See also

getPos, setPosAbs

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

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.

See also

lock

actuatorAtTarget = 8#

actuatorAvailable = 16384#

actuatorEnabled = 32768#

actuatorEndSwitch = 256#

actuatorEndSwitch1 = 512#

actuatorEndSwitch2 = 1024#

actuatorError = 65536#

actuatorInterrupted = 2#

actuatorMoving = 4#

actuatorRefSwitch = 2048#

actuatorRefSwitch1 = 4096#

actuatorRefSwitch2 = 8192#

actuatorTimeout = 16#

actuatorUnknown = 1#

currentPositions#

tuple of float : Gets the current positions (in mm or degree) of all axes.

This property returns a tuple whose size corresponds to the number of axes of this actuator. The returned tuple contains the current positions of all axes (in mm or degree). This property is always updated if the plugin signals a change of any current position via the signal actuatorStatusChanged. Instead of reading this property, you can also connect to this signal in order to get instantly informed about new current positions.

This property always returns immediately, however it only contains the last reported values which can slightly differ from the real current positions (if the plugin rarely emits its current states for instance due to performance reasons).

currentStatus#

tuple of int : Gets the current status (flag mask, see getStatus()) of all axes

This property returns a tuple whose size corresponds to the number of axes of this actuator. The returned tuple contains the current positions of all axes (in mm or degree). This property is always updated if the plugin signals a change of any current position via the signal ‘actuatorStatusChanged’. Instead of reading this property, you can also connect to this signal in order to get instantly informed about new current positions.

The difference between this property and the method getStatus() is that getStatus will only return if the actuator plugin is currently idle. This property always returns immediately, however it only contains the last reported values which can slightly differ from the real current positions (if the plugin rarely emits its current states for instance due to performance reasons).

targetPositions#

tuple of float : Gets the target positions (in mm or degree) of all axes.

This property returns a tuple whose size corresponds to the number of axes of this actuator. The returned tuple contains the current target positions of all axes (in mm or degree). This property is always updated if the plugin signals a change of any target position via the signal targetChanged. Instead of reading this property, you can also connect to this signal in order to get instantly informed about new target positions.

This property always returns immediately, however it only contains the last reported values which can slightly differ from the real target positions (if the plugin rarely emits its current states for instance due to performance reasons).