itom methods

Plotting and camera

itom.liveImage(cam[, className, properties]) → show a camera live image in a newly created figure

Creates a plot-image (2D) and automatically grabs images into this window. This function is not blocking.

Parameters:

cam : {dataIO-Instance}

Camera grabber device from which images are acquired.

className : {str}, optional

class name of desired plot (if not indicated or if the className can not be found, the default plot will be used (see application settings)

properties : {dict}, optional

optional dictionary of properties that will be directly applied to the plot widget.

itom.plot(data[, className, properties]) → plots a dataObject in a newly created figure

Plot an existing dataObject in dockable, not blocking window. The style of the plot depends on the object dimensions. If x-dim or y-dim are equal to 1, plot will be a line-plot, else a 2D-plot.

Parameters:

data : {DataObject}

Is the data object whose region of interest will be plotted.

className : {str}, optional

class name of desired plot (if not indicated or if the className can not be found, the default plot will be used (see application settings)

properties : {dict}, optional

optional dictionary of properties that will be directly applied to the plot widget.

Using algorithms and filters

itom.filter(name[, furtherParameters, ...]) → invoke a filter (or algorithm) function from an algorithm-plugin.

This function is used to invoke itom filter-functions or algorithms, declared within itom-algorithm plugins. The parameters (arguments) depends on the specific filter function (see filterHelp(name)), By filterHelp() a list of available filter functions is retrieved.

Parameters:

name : {str}

The name of the filter

furtherParameters : {variant}

Further parameters depend on the filter-methods itself (give the mandatory and then optional parameters in their defined order).

Returns:

out : {variant}

The returned values depend on the definition of each filter. In general it is a tuple of all output parameters that are defined by the filter function.

See also

filterHelp

Methods for getting help and information about filters, plugins, ui-elements, ...

itom.pluginHelp(pluginName[, dictionary = False]) → generates an online help for the specified plugin.

Gets (also print to console) the initialisation parameters of the plugin specified pluginName (str, as specified in the plugin window). If dictionary == True, a dict with all plugin parameters is returned and nothing is printed to the console.

Parameters:

pluginName : {str}

is the fullname of a plugin as specified in the plugin window.

dictionary : {bool}, optional

if dictionary == True, function returns a dict with plugin parameters and does not print anything to the console (default: False)

Returns:

out : {None or dict}

Returns None or a dict depending on the value of parameter dictionary.

itom.widgetHelp([widgetName, dictionary = 0, furtherInfos = 0]) → generates an online help for the given widget(s).

This method prints information about one specific widget or a list of widgets to the console output. If one specific widget, defined in an algorithm plugin can be found that case-sensitively fits the given widgetName its full documentation is printed. Else, a list of widgets is printed whose name contains the given widgetName.

Parameters:

widgetName : {str}, optional

is the fullname or a part of any widget-name which should be displayed. If widgetName is empty or no widget matches widgetName (case sensitive) a list with all suitable widgets is given.

dictionary : {dict}, optional

if dictionary == 1, a dictionary with all relevant components of the widget’s documentation is returned and nothing is printed to the command line [default: 0]

furtherInfos : {int}, optional

Usually, widgets whose name only contains the given widgetName are only listed at the end of the information text. If this parameter is set to 1 [default: 0], the full information for all these widgets is printed as well.

Returns:

out : {None or dict}

In its default parameterization this method returns None. Depending on the parameter dictionary it is also possible that this method returns a dictionary with the single components of the information text.

itom.filterHelp([filterName, dictionary = 0, furtherInfos = 0]) → generates an online help for the given filter(s).

This method prints information about one specific filter (algorithm) or a list of filters to the console output. If one specific filter, defined in an algorithm plugin can be found that case-sensitively fits the given filterName its full documentation is printed. Else, a list of filters is printed whose name contains the given filterName.

Parameters:

filterName : {str}, optional

is the fullname or a part of any filter-name which should be displayed. If filterName is empty or no filter matches filterName (case sensitive) a list with all suitable filters is given.

dictionary : {dict}, optional

if dictionary == 1, a dictionary with all relevant components of the filter’s documentation is returned and nothing is printed to the command line [default: 0]

furtherInfos : {int}, optional

Usually, filters or algorithms whose name only contains the given filterName are only listed at the end of the information text. If this parameter is set to 1 [default: 0], the full information for all these filters is printed as well.

Returns:

out : {None or dict}

In its default parameterization this method returns None. Depending on the parameter dictionary it is also possible that this method returns a dictionary with the single components of the information text.

itom.pluginLoaded(pluginName) → check if a certain plugin could be successfully loaded.

Checks if a specified plugin is loaded and returns the result as a boolean expression.

Parameters:

pluginName : {str}

The name of a specified plugin as usually displayed in the plugin window.

Returns:

result : {bool}

True, if the plugin has been loaded and can be used, else False.

itom.version([toggle-output [, include-plugins]])) → retrieve complete information about itom version numbers

Parameters:

toggle-output : {bool}, optional

default = false if true, output will be written to a dictionary else to console.

dictionary : {bool}, optional

default = false if true, add informations about plugIn versions.

Returns:

None (display outPut) or PyDictionary with version information. :

Notes

Retrieve complete version information of itom and if specified version information of loaded plugins and print it either to the console or to a PyDictionary.

Adding elements to the GUI

itom.addButton(toolbarName, buttonName, code[, icon, argtuple]) → adds a button to a toolbar in the main window

This function adds a button to a toolbar in the main window. If the button is pressed the given code, function or method is executed. If the toolbar specified by ‘toolbarName’ does not exist, it is created. The button will show the optional icon, or if not given or not loadable, ‘buttonName’ is displayed as text.

itom comes with basic icons addressable by ‘:/../iconname.png’, e.g. ‘:/gui/icons/close.png’. These natively available icons are listed in the icon-browser in the menu ‘edit >> iconbrowser’ of any script window. Furthermore you can give a relative or absolute path to any allowed icon file (the preferred file format is png).

Parameters:

toolbarName : {str}

The name of the toolbar.

buttonName : {str}

The name and identifier of the button to create.

code : {str, method, function}

The code to be executed if the button is pressed.

icon : {str}, optional

The filename of an icon-file. This can also be relative to the application directory of ‘itom’.

argtuple : {tuple}, optional

Arguments, which will be passed to the method (in order to avoid cyclic references try to only use basic element types).

Returns:

handle : {int}

handle to the newly created button (pass it to removeButton to delete exactly this button)

Raises:

Runtime error : :

if the main window is not available

See also

removeButton

itom.removeButton(handle | toolbarName[, buttonName]) → removes a button from a given toolbar.

This method removes an existing button from a toolbar in the main window of ‘itom’. This button must have been created using addButton. If the toolbar is empty after the removal, it is finally deleted.

Pass either the ‘handle’ parameter of both ‘toolbarName’ and ‘buttonName’. It is more precise to use the handle in order to exactly delete the button that has been created by a call to addButton. Using the names of the toolbar and the button always delete any button that has been created using this data.

Parameters:

handle : {int}

The handle returned by addButton().

toolbarName : {str}

The name of the toolbar.

buttonName : {str}

The name (str, identifier) of the button to remove.

Raises:

Runtime error : :

if the main window is not available or the given button could not be found.

See also

addButton

itom.addMenu(type, key[, name, code, icon, argtuple]) → adds an element to the menu bar of itom.

This function adds an element to the main window menu bar. The root element of every menu-list must be a MENU-element. Such a MENU-element can contain sub-elements. The following sub-elements can be either another MENU, a SEPARATOR or a BUTTON. Only the BUTTON itself triggers a signal, which then executes the code, given by a string or a reference to a callable python method or function. Remember, that this reference is only stored as a weak pointer. If you want to directly add a sub-element, you can give a slash-separated string in the key-parameter. Every sub-component of this string then represents the menu-element in its specific level. Only the element in the last can be something else than MENU.

itom comes with basic icons addressable by ‘:/../iconname.png’, e.g. ‘:/gui/icons/close.png’. These natively available icons are listed in the icon-browser in the menu ‘edit >> iconbrowser’ of any script window. Furthermore you can give a relative or absolute path to any allowed icon file (the preferred file format is png).

Parameters:

type : {Int}

The type of the menu-element (BUTTON:0 [default], SEPARATOR:1, MENU:2). Use the corresponding constans in module ‘itom’.

key : {str}

A slash-separated string where every sub-element is the key-name for the menu-element in the specific level.

name : {str}, optional

The text of the menu-element. If not indicated, the last sub-element of key is taken.

code : {str, Method, Function}, optional

The code to be executed if menu element is pressed.

icon : {str}, optional

The filename of an icon-file. This can also be relative to the application directory of ‘itom’.

argtuple : {tuple}, optional

Arguments, which will be passed to method (in order to avoid cyclic references try to only use basic element types).

Returns:

handle : {int}

Handle to the recently added leaf node (action, separator or menu item). Use this handle to delete the item including its child items (for type ‘menu’).

Raises:

Runtime error : :

if the main window is not available or the given button could not be found.

See also

removeMenu

itom.removeMenu(key | menuHandle) → remove a menu element with the given key or handle.

This function remove a menu element with the given key or menuHandle. key is a slash separated list. The sub-components then lead the way to the final element, which should be removed.

Alternatively, it is possible to pass the handle obtained by addMenu.

Parameters:

key : {str}, optional

The name (str, identifier) of the menu entry to remove.

handle : {int}, optional

The handle of the menu entry that should be removed (including its possible child items).

Raises:

Runtime error : :

if the main window is not available or the given button could not be found.

See also

addMenu

For more information about using these methods, see Customize the menu and toolbars of itom.

Disk-IO

itom.loadDataObject(filename, dataObject[, doNotAppendIDO]) → load a dataObject from the harddrive.

This function reads a dataObject from the file specified by filename. MetaData saveType (string, binary) are extracted from the file and restored within the object.

Parameters:

filename : {str}

Filename and Path of the destination (.ido will be added if not available)

dataObject : {dataObject}

A pre-allocated dataObject (empty dataObject is allowed).

doNotAppendIDO : {bool}, optional

False[default]: file suffix .ido will not be appended to filename, True: it will be added.

Notes

The value of string-Tags must be encoded to avoid XML-conflics. Tagnames which contains special characters leads to XML-conflics.

itom.saveDataObject(filename, dataObject[, tagsAsBinary = False]) → save a dataObject to harddrive in a xml-based file format.

This method writes a dataObject into the file specified by ‘filename’. The data is stored in a binary format within a xml-based structure. All string-tags of the dataObject are encoded in order to avoid xml-errors, the value of numerical tags are converted to string with 15 significant digits (>32bit, tagsAsBinary = False [default]) or in a binary format (tagsAsBinary = True).

Parameters:

filename : {str}

Filename and Path of the destination (.ido will be added if no .*-ending is available)

dataObject : {DataObject}

An allocated dataObject of n-Dimensions.

tagsAsBinary : {bool}, optional

Optional tag to toggle if numeric-tags should be saved (metaData) as binary or by default as string.

See also

loadDataObject

Notes

Tagnames which contains special characters leads to XML-conflics.

itom.loadMatlabMat(filename) → loads Matlab mat-file by using scipy methods and returns the loaded dictionary.

This function loads matlab mat-file by using scipy methods and returns the loaded dictionary.

Parameters:

filename : {str}

Filename from which the data will be imported (.mat will be added if not available)

Returns:

mat : {dict}

dictionary with content of file

See also

saveMatlabMat

itom.saveMatlabMat(filename, values[, matrixName = 'matrix']) → save strings, numbers, arrays or combinations into a Matlab mat file.

Save one or multiple objects (strings, numbers, arrays, dataObject, numpy.ndarray, npDataObject...) to a Matlab mat file. There are the following possibilites for saving:

• One given value is saved under one given ‘matrixName’ or ‘matrix’ if ‘matrixName’ is not given.
• A list or tuple of objects is given. If no ‘matrixName’ is given, the items get the names ‘matrix1’, ‘matrix2’... Else, ‘matrixName’ must be a sequence of value names with the same length than ‘values’.
• A dictionary is given, such that each value is stored under its corresponding key.

Parameters:

filename : {str}

Filename under which the file should be saved (.mat will be appended if not available)

values : {dictionary, list, tuple, variant}

single value, dictionary, list or tuple with elements of type number, string, array (dataObject, numpy.ndarray, npDataObject...)

matrix-name : {str, list, tuple}, optional

if ‘values’ is a single value, this parameter must be one single str, if ‘values’ is a sequence it must be a sequence of strings with the same length, if ‘values’ is a dictionary this argument is ignored.

See also

loadMatlabMat

itom.loadIDC(filename) → load a pickled idc-file and return the content as dictionary

This methods loads the given idc-file using the method pickle.load from the python-buildin module pickle and returns the loaded dictionary.

Parameters:

filename : {String}

absolute filename or filename relative to the current directory.

Returns:

content : {dict}

dictionary with loaded content

See also

pickle.load, saveIDC

itom.saveIDC(filename, dict[, overwriteIfExists = True]) → saves the given dictionary as pickled idc-file.

This method saves the given dictionary as pickled idc-file using the method dump from the builtin module pickle.

Parameters:

filename : {string}

absolute filename or filename relative to the current directory.

dict : {dict}

dictionary which should be pickled.

overwriteIfExists : {bool}, default: True

if True, an existing file will be overwritten.

See also

pickle.dump, loadIDC

Debug-Tools

itom.gcEndTracking() → compares the current object list of the garbage collector with the recently saved list.

itom.gcStartTracking() → stores the current object list of the garbage collector.

itom.getDebugger() → returns new reference to debugger instance

Further commands

itom.scriptEditor() -> opens new, empty script editor window (undocked)

itom.openScript(filename) → open the given script in current script window.

Open the python script indicated by filename in a new tab in the current, latest opened editor window. Filename can be either a string with a relative or absolute filename to the script to open or any object with a __file__ attribute. This attribute is then read and used as path.

The relative filename is relative with respect to the current directory.

Parameters:

filename : {str} or {obj}

Relative or absolute filename to a python script that is then opened (in the current editor window). Alternatively an object with a __file__ attribute is allowed.

itom.newScript() → opens an empty, new script in the current script window.

Creates a new itom script in the latest opened editor window.

itom.setCurrentPath(newPath) → set current working directory to given absolute newPath

sets the absolute path of the current working directory to ‘newPath’. The current working directory is the base directory for all subsequent relative pathes of icon-files, script-files, ui-files, relative import statements...

The current directory is always indicated in the right corner of the status bar of the main window.

Parameters:

newPath : {str}

The new working path of this application

Returns:

success : {bool}

True in case of success else False

See also

getCurrentPath

itom.getAppPath() → returns absolute path of application base directory.

This function returns the absolute path of application base directory. The return value is independent of the current working directory.

Returns:

path : {str}

absolute path of this application’s base directory

itom.getCurrentPath() → returns absolute path of current working directory.

Returns:

Path : {str}

absolute path of current working directory

See also

setCurrentPath

itom.getScreenInfo() → returns dictionary with information about all available screens.

This method returns a dictionary with information about the current screen configuration of this computer.

Returns:

screenInfo : {dict}

dictionary with the following content is returned:

• screenCount (int): number of available screens
• primaryScreen (int): index (0-based) of primary screen
• geometry (tuple): tuple with dictionaries for each screen containing data for width (w), height (h) and its top-left-position (x, y)

itom.getDefaultScaleableUnits() → Get a list with the strings of the standard scalable units.

The unit strings returned as a list by this method can be transformed into each other using scaleValueAndUnit.

Returns:

units : {list}

List with strings containing all scaleable units

See also

scaleValueAndUnit

itom.scaleValueAndUnit()

ScaleValueAndUnit(scaleableUnits, value, valueUnit) -> Scale a value and its unit and returns [value, ‘Unit’]

Parameters:

scaleableUnits : {PyList of Strings}

A string list with all scaleable units

value : {double}

The value to be scaled

valueUnit : {str}

The value unit to be scaled

Returns:

PyTuple with scaled value and scaled unit :

Notes

Rescale a value with SI-unit (e.g. 0.01 mm to 10 micrometer). Used together with itom.getDefaultScaleableUnits()

itom.clc() -> clears the itom command line (if available)

Another possibility to add methods to this page is to use the auto-summary function. Since, the default-role property in conf.py is set to ‘autolink’ and the auto-summary module is included, small pages will be automatically created for each method in the following list and a hyperlink to this site is created:

With method signature:

itom.widgetHelp(([widgetName, ...)	This method prints information about one specific widget or a list of widgets to the console output.
itom.pluginHelp((pluginName [, ...)	Gets (also print to console) the initialisation parameters of the plugin specified pluginName (str, as specified in the plugin window).
itom.filterHelp(([filterName, ...)	This method prints information about one specific filter (algorithm) or a list of filters to the console output.

Without method signature:

itom.liveImage	Creates a plot-image (2D) and automatically grabs images into this window.
itom.plot	Plot an existing dataObject in dockable, not blocking window.