9.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) → actuator

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) → Union[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) → Optional[dict]

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) → Union[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 possibilies 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) → Optional[dict]

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
getPos(axisIndex1, *args) → Union[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) → Union[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 : timout 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 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 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 possibilies 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).

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 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 (inifinite 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
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).