10.1. itom methods#

This section shows the spezial itom methods.

10.1.1. Plotting and camera#

Camera plugins have the special method liveImage.

itom.close(handle) → None#

itom.close(all='all') → None

Closes a specific or all opened figures.

This method closes and deletes either one specific figure (if handle is given and valid), or all opened figures (if the string argument "all" is given). All figure can only be closed, if no other figure references this figure (e.g. line cut of an image plot (2D).

This method is a redirect of the staticmethod figure.close().

Parameters:

handleint: a valid figure handle, whose reference figure should be closed. This figure handle is for instance obtained by the first value of the returned tuple of plot(), plot1(), plot2() among others.
all{“all”}: Pass the string "all" if all closeable opened figures should be closed.

See also

figure.close

Notes

If a figure instance still keeps a reference to any figure, it is only closed and will be deleted after that the last referencing instance has been deleted.

itom.liveImage(cam, className='', properties={}) → Tuple[int, plotItem]#

Shows a camera live image in a new figure window.

This method creates a plot-image (2D) and automatically grabs images into this window.

If no className is given, the type of the plot is chosen depending on the type and the size of the object. The defaults for several plot classes can be adjusted in the property dialog of itom.

You can also set a class name of your preferred plot plugin (see also property dialog of itom). If your preferred plot is not able to display the given object, a warning is returned and the default plot type is used again. For dataObjects, it is also possible to simply set className to 1D or 2D in order to choose the default plot type depending on these aliases.

Every plot has several properties that can be configured in the Qt Designer (if the plot is embedded in a GUI), or by the property toolbox in the plot itself or by using the info() method of the corresponding itom.uiItem instance.

Use the properties argument to pass a dictionary with properties you want to set to certain values.

Parameters:

camdataIO: Camera grabber device from which images are acquired.
classNamestr, 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)
propertiesdict, optional: optional dictionary of properties that will be directly applied to the plot widget.

Returns:

indexint: This index is the figure index of the plot figure that is opened by this command. Use figure(index) to get a reference to the figure window of this plot. The plot can be closed by close(index).
plotHandleplotItem: Handle of the plot. This handle is used to control the properties of the plot, connect signals to it or call slots of the plot.

See also

plot, plotItem, plot1, plot2, plot25

itom.plot(data, className='', properties={}) → Tuple[int, plotItem]#

Plots a dataObject, pointCloud or polygonMesh in a new figure window

Plots an existing dataObject, pointCloud or polygonMesh in a dockable, not blocking window. The style of the plot depends on the object dimensions.

If no className is given, the type of the plot is chosen depending on the type and the size of the object. The defaults for several plot classes can be adjusted in the property dialog of itom.

You can also set a class name of your preferred plot plugin (see also property dialog of itom). If your preferred plot is not able to display the given object, a warning is returned and the default plot type is used again. For dataObject, it is also possible to simply set className to 1D, 2D or 2.5D in order to choose the default plot type depending on these aliases. For pointCloud and polygonMesh only the alias 2.5D is valid.

Every plot has several properties that can be configured in the Qt Designer (if the plot is embedded in a GUI), or by the property toolbox in the plot itself or by using the info() method of the corresponding uiItem instance.

Use the properties argument to pass a dict with properties you want to set.

Parameters:

datadataObject or pointCloud or polygonMesh: Is the data object, point cloud or polygonal mesh, that will be plotted.
classNamestr, 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)). Depending on the object, you can also set className to 1D, 2D or 2.5D for displaying the object in the default plot of the indicated categories. If nothing is given, the plot category is guessed from data.
propertiesdict, optional: optional dictionary of properties that will be directly applied to the plot widget.

Returns:

indexint: This index is the figure index of the plot figure that is opened by this command. Use figure(index) to get a reference to the figure window of this plot. The plot can be closed by close(index).
plotHandleplotItem: Handle of the plot. This handle is used to control the properties of the plot, connect to its signals or call slots of the plot.

See also

liveImage, plotItem, plot1, plot2, plot25

itom.plot1(data, xData=None, className='', properties={}) → Tuple[int, plotItem]#

Plots a dataObject as an 1d plot in a new figure window.

This method plots an existing dataObject data in a dockable, not blocking window.

If xData is given, the plot uses this vector for the values of the x axis of the plot.

The plot type of this function is 1D (see method plot()).

Use the properties argument to pass a dictionary with properties you want to set.

Parameters:

datadataObject: Is the dataObject whose region of interest will be plotted.
xDatadataObject, optional: Is the dataObject whose values are used for the axis.
classNamestr, optional: class name of the desired 1D plot (if not indicated, the default 1D plot will be used, see application settings)
propertiesdict, optional: optional dictionary of properties that will be directly applied to the plot widget.

Returns:

indexint: This index is the figure index of the plot figure that is opened by this command. Use figure(index) to get a reference to the figure window of this plot. The plot can be closed by close(index).
plotHandleplotItem: Handle of the plot. This handle is used to control the properties of the plot, connect signals to it or call slots of the plot.

See also

liveImage, plotItem, plot, plot2, plot25

itom.plot2(data, properties={}) → Tuple[int, plotItem]#

Plots a dataObject in a new figure window.

This method plots an existing dataObject in a dockable, not blocking window. The style of the plot depends on the object dimensions. The plot type of this function is 2D.

Use the properties argument to pass a dictionary with properties you want to set to certain values.

Parameters:

datadataObject: Is the dataObject whose region of interest will be plotted.
classNamestr, optional: class name of the desired 2D plot (if not indicated default plot will be used, see application settings)
propertiesdict, optional: optional dictionary of properties that will be directly applied to the plot widget.

Returns:

indexint: This index is the figure index of the plot figure that is opened by this command. Use figure(index) to get a reference to the figure window of this plot. The plot can be closed by close(index).
plotHandleplotItem: Handle of the plot. This handle is used to control the properties of the plot, connect signals to it or call slots of the plot.

See also

liveImage, plotItem, plot, plot1, plot25

itom.plot25(data, className='', properties={}) → Tuple[int, plotItem]#

Plots a dataObject, pointCloud or polygonMesh in a new figure window.

This method plots the data object in a dockable, not blocking window. The style of the plot depends on the object dimensions, its plot type is 2.5D.

Use the properties argument to pass a dictionary with properties you want to set to desired values.

Parameters:

datadataObject or pointCloud or polygonMesh: is the object, that is plotted.
classNamestr, optional: class name of the desired 2.5D plot (if not indicated default plot will be used, see application settings)
propertiesdict, optional: optional dictionary of properties that will be directly applied to the plot widget.

Returns:

indexint: This index is the figure index of the plot figure that is opened by this command. Use figure(index) to get a reference to the figure window of this plot. The plot can be closed by close(index).
plotHandleplotItem: Handle of the plot. This handle is used to control the properties of the plot, connect signals to it or call slots of the plot.

See also

liveImage, plotItem, plot, plot1, plot2

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

You can get the help string in the itom command line for plugins, widgets, filters, …

itom.filterHelp(filterName='', dictionary=0, furtherInfos=0) → dict | None#

Print outs an online help for the given filter(s) or return help information as dictionary.

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 or returned. Else, a list of filters is printed whose name contains the given filterName.

Parameters:

filterNamestr, 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.
dictionaryint, optional: if 1, a dictionary with all relevant information about the documentation of this filter is returned as dictionary and nothing is printed to the command line (default: 0).
furtherInfosint, 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:

infodict: This dictionary is only returned, if dictionary is set to 1. Else None is returned. The dictionary contains relevant information about the desired filterName.

itom.pluginHelp(pluginName, dictionary=False) → dict | None#

Generates an online help for the specific plugin.

Information about an itom plugin library (actuator, dataIO or algorithm), gathered by this method, are the name of the plugin, its version, its type, contained filters (in case of an algorithm) or the description and initialization parameters (otherwise).

Parameters:

pluginNamestr: is the fullname of a plugin library as specified in the plugin toolbox.
dictionarybool, optional: if True, this method returns a dict with all gathered information about the plugin. Else (default), this information is printed to the command line.

Returns:

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

itom.pluginLoaded(pluginName) → bool#

Checks if a certain plugin could be successfully loaded.

This method checks if a specified plugin is loaded and returns True if this is the case, otherwise False.

Parameters:

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

Returns:

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

itom.version(dictionary=False, addPluginInfo=False) → dict | None#

Retrieves, prints out or returns complete version information of itom (and optionally plugins).

Parameters:

dictionarybool, optional: If True, all information is returned as nested dict. Otherwise (default), this information is printed to the command line.
addPluginInfobool, optional: If True, version information about all loaded plugins are added, too. Default: False.

Returns:

None or dict: version information as nested dict, if dictionary is True.

itom.widgetHelp(widgetName='', dictionary=0, furtherInfos=0) → dict | None#

Print outs an online help for the given widget(s) or return help information as dictionary.

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

Parameters:

widgetNamestr, 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.
dictionaryint, optional: if 1, a dictionary with all relevant information about the documentation of this widget is returned as dictionary and nothing is printed to the command line (default: 0).
furtherInfosint, 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:

infodict: This dictionary is only returned, if dictionary is set to 1. Else None is returned. The dictionary contains relevant information about the desired widgetName.

10.1.3. Adding elements to the GUI#

You can add buttons and menus to the itom GUI.

itom.addButton(toolbarName, buttonName, code, icon='', argtuple=[]) → int#

Adds a button to a toolbar in the main window of itom.

This function adds a button to a toolbar in the main window of itom. 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 display an optional icon, or - if not given / not loadable - the 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 >> icon browser of any script window. Furthermore you can give a relative or absolute path to any allowed icon file (the preferred file format is png).

For more information see also the section Add toolbars and buttons of the documentation.

New in itom 4.1: The code argument accepts all kind of callable objects, not only Python methods and functions.

Parameters:

toolbarNamestr: The name of the toolbar.
buttonNamestr: The name and identifier of the button to create.
codestr or callable(): The code or callable to be executed if the button is pressed. If the code is a callable method, it can either be an unbounded function (including lambda functions) or a bounded member method of a class instance. In the latter case, the button does not keep a reference to the class instance, such that a RuntimeError is raised if the instance is not available any more if the button is triggered.
iconstr, optional: The filename of an icon file. This can also be relative to the application directory of itom.
argtupletuple, optional: Arguments, which will be passed to the method (in order to avoid cyclic references try to only use basic element types).

Returns:

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

Raises:

RuntimeError: if the main window is not available

See also

removeButton

itom.addMenu(type, key, name='', code='', icon='', argtuple=[]) → int#

This function adds an element to the main window menu bar.

The root element of every menu list must be of type MENU. Such a MENU element can contain sub-elements. These 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 as key argument. Every component of this string then represents the menu element in its specific level. Only the element in the last can be something else than of type MENU.

For more information see also the section Create menus of the documentation.

Parameters:

typeint: The type of the menu-element (BUTTON : 0 [default], SEPARATOR : 1, MENU : 2). Use the corresponding constant in module itom.
keystr: A slash-separated string where every sub-element is the key-name for the menu-element in the specific level.
namestr, optional: The text of the menu-element. If it is an empty string, the last component of the slash separated key is used as name. For instance if key is equal to item1/item2 the name will be item2.
codestr or callable(), optional: The code to be executed if menu element is pressed.
iconstr, optional: The filename of an icon-file. This can also be relative to the application directory of itom.
argtupletuple, optional: Arguments, which will be passed to method (in order to avoid cyclic references try to only use basic element types).

Returns:

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

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

See also

removeMenu

itom.dumpButtonsAndMenus() → dict#

Gets all user-defined toolbars, menus and its buttons.

Returns:

dict

Dictionary with two top-level entries:

{'toolbars': {}, 'menus': []}

toolbars contains a dict of all customized toolbars, where each item contains all buttons (actions) of this toolbar. menus contains a list of nested dictionaries for each top level menu.

itom.removeButton(handle) → None#

itom.removeButton(toolbarName, buttonName='') → None

Removes one or all buttons from a given toolbar in the itom main window.

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

A button can be identified by two different ways:

Either pass the handle of the button, as returned by addButton(). This can also be used, if multiple buttons should have the same name.
Identify the button by its toolbarName and buttonName. If more than one button is available in the toolbar with the given buttonName, all matched buttons are removed. If buttonName is an empty string (default) all buttons that are contained in the toolbar are removed (including the toolbar).

For more information see also the section Add toolbars and buttons of the documentation.

Parameters:

handleint: The handle returned by addButton().
toolbarNamestr: The name of the toolbar.
buttonNamestr: The name (str, identifier) of the button to remove (only necessary, if toolbarName is given instead of handle). If an empty string all buttons of the given toolbar are removed (including the toolbar itself).

Raises:

RuntimeError: if the main window is not available or the addressed button could not be found.

See also

addButton

itom.removeMenu(key) → None#

itom.removeMenu(menuHandle) → None

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 from addMenu().

For more information see also the section Create menus of the documentation.

Parameters:

keystr: The key (can be a slash-separated list) of the menu entry to remove. If it is a slash-separated list, the menu entry is searched down the path, indicated by the components of the list respectively. If the desired menu item has further child items, they are removed, too.
menuHandleint: The handle of the menu entry that should be removed (including its possible child items). This handle is usually returned by addMenu().

Raises:

RuntimeError: 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 bar and toolbars of itom.

10.1.4. Save and load dataObjects to or from file#

Dataobject can be save as IDC files.

itom.loadDataObject(filename, dataObject, doNotAppendIDO=False)#

Loads a dataObject from an IDO file.

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:

filenamestr: absolute or relative ido file path to the target file
dataObjectdataObject: an allocated, e.g. empty dataObject, that is filled with the loaded object afterwards.
doNotAppendIDObool, optional: If True (default: False), the file suffix ido is appended to filename.

Notes

The value of string tags must be encoded to avoid XML-conflics. Tag names which contains special characters might lead to XML-conflics.

itom.loadIDC(filename) → dict#

loads a pickled idc-file and returns 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:

filenamestr: Filename to the idc-file, that should be loaded. Can be an absolute path, or relative with respect to the current working directory.

Returns:

contentdict: dictionary with loaded content.

See also

pickle.load, saveIDC

itom.loadMatlabMat(filename) → dict#

Loads Matlab mat-file by using scipy methods and returns the loaded dictionary.

Parameters:

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

Returns:

matdict: dictionary with content of file

Raises:

ImportError: if scipy and its module scipy.io could not be imported.

See also

saveMatlabMat

Notes

This method requires the package scipy and its module scipy.io.

itom.saveDataObject(filename, dataObject, tagsAsBinary=False)#

Saves a dataObject to the hard drive in a xml-based file format (ido).

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 either converted to strings with 15 significant digits (>32bit) or stored as base64 encoded values.

Parameters:

filenamestr: absolute or relative file path to the destination file (.ido will be added if no valid suffix is given)
dataObjectdataObject: The n-dimensional dataObject to be serialized to the file.
tagsAsBinarybool, optional: If True all number tags are stored as base64 encoded number values in the ido file. Else (default), they are stored as readable strings.

See also

loadDataObject

Notes

Tagnames which contains special characters might lead to XML-conflicts.

itom.saveIDC(filename, dict, overwriteIfExists=True)#

Saves the given dictionary as pickled idc-file.

This method saves the given dictionary dict as pickled idc-file using the method pickle.dump() from the builtin module pickle. The file will be saved with the pickle protocol version 3 (default for Python 3).

Parameters:

filenamestr: Filename of the destination idc file. Can be an absolute filename or relative with respect to the current working directory.
dictdict: dictionary which should be pickled. All values in the dictionary must be able to be pickled (e.g. all Python base types, dataObjects, numpy.ndarrays…).
overwriteIfExistsbool, optional: If True, an existing file will be overwritten.

Raises:

RuntimeError: if the file cannot be overwritten or if it exists, but overwriteIfExists is False.

See also

pickle.dump, loadIDC

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…) to a Matlab mat file. There are the following possibilities for saving, depending on the type of values:

values is a dict: All values in the dictionary are stored under their corresponding key.
If values contains one item only, it is saved under the given matrixName.
If value is a list or tuple of objects, matrixName must either be a sequence with the same length than value. Then, each item in values is stored with the respective name in matrixName. Or matrixName can be omitted. Then, the items are stored under the self-incremented keys matrix1, matrix2, …

Parameters:

filenamestr: Filename under which the file should be saved (.mat will be appended if not available)
valuesdict or list or tuple or Any: The value(s) to be stored. Can be either a single object (number, string, dataObject, numpy.ndarray among others, or a list, tuple or dict of these single objects.
matrixNamestr or list or tuple, optional: If values is a single value, this parameter must be one single str. Else if values is a sequence it must be a sequence of strings with the same length or it can be omitted. If values is a dictionary, this argument is ignored.

Raises:

ImportError: if scipy and its module scipy.io could not be imported.

See also

loadMatlabMat

Notes

This method requires the package scipy and its module scipy.io.

10.1.5. Debug-Tools#

These are some debug tools.

itom.gcEndTracking()#

Finishes a monitoring session for objects in the garbage collector.

This method makes a snapshot of all objects currently guarded by the garbage collector (gc) and compares the list of objects with the one collected during the last call of gcStartTracking().

The difference of both lists of printed to the command line.

This methods are usually available for development purposes.

Raises:

RuntimeError: if gcStartTracking() was not called before.

See also

gcStartTracking

itom.gcStartTracking()#

Starts a monitoring session for objects in the garbage collector.

This method makes a snapshot of all objects currently guarded by the garbage collector (gc). Before this, gc.collect() was called to clear all unnecessary objects.

Later, call gcEndTracking() to get a print out of the differences between the snapshot at the end and the beginning of the tracking.

This methods are usually available for development purposes.

See also

gcEndTracking

itom.getDebugger() → itoDebugger.itoDebugger#

Returns the itoDebugger object of this itom session.

It is usually not recommended and necessary to use this method or the returned debugger. This method is available for development and debugging purposes.

Returns:

debuggeritoDebugger.itoDebugger: is the debugger instance of this itom session.

10.1.6. Request user rights#

These are some methods to get user information.

itom.userGetInfo() → Dict[str, str]#

Returns a dictionary with relevant information about the current user.

Returns:

dict

dictionary with the following content is returned:

Name: The name of the current user
Type: The user right type of the current user [user, administrator, developer]
ID: The user ID
File: The location and name of the corresponding setting file (ini).

itom.userIsAdmin() → bool#

Returns True if the current user has administrator rights.

For more information about the user management of itom, see User Management.

Returns:

bool: True if current user has administrator rights, otherwise False.

See also

userIsUser, userIsDeveloper, userGetInfo

itom.userIsDeveloper() → bool#

Returns True if the current user has developer rights.

This method only returns True, if the current user has developer rights, not if he has higher rights, like administrator. For more information about the user management of itom, see User Management.

Returns:

bool: True if current user has developer rights, otherwise False.

See also

userIsUser, userIsAdministrator, userGetInfo

itom.userIsUser() → bool#

Returns True if the current user has user rights.

This method only returns True, if the current user has user rights, not if he has higher rights, like developer or administrator. For more information about the user management of itom, see User Management.

Returns:

bool: True if current user has user rights, otherwise False.

See also

userIsDeveloper, userIsAdministrator, userGetInfo

10.1.7. Further commands#

Some further commands.

itom.autoReloader(enabled, checkFileExec=True, checkCmdExec=True, checkFctExec=False)#

dis-/enables the module to automatically reload changed modules.

Use this method to enable or disable (and configure) a tool that automatically tries to reload imported modules and their submodules if they have changed since the last run.

Parameters:

enablebool: The auto-reload tool is loaded if it is enabled for the first time. If it is disabled, it does not check changes of any imported modules.
checkFileExecbool: If True (default) and auto-reload enabled, a check for modifications is executed whenever a script is executed
checkCmdExecbool: If True (default) and auto-reload enabled, a check for modifications is executed whenever a command in the command line is executed
checkFctExecbool: If True and auto-reload enabled, a check for modifications is executed whenever a function or method is run (e.g. by an event or button click) (default: False)

Notes

This tool is inspired by and based on the IPython extension autoreload.

Reloading Python modules in a reliable way is in general difficult, and unexpected things may occur. autoReloader tries to work around common pitfalls by replacing function code objects and parts of classes previously in the module with new versions. This makes the following things to work:

Functions and classes imported via ‘from xxx import foo’ are upgraded to new versions when ‘xxx’ is reloaded.
Methods and properties of classes are upgraded on reload, so that calling ‘c.foo()’ on an object ‘c’ created before the reload causes the new code for ‘foo’ to be executed.

Some of the known remaining caveats are:

Replacing code objects does not always succeed: changing a @property in a class to an ordinary method or a method to a member variable can cause problems (but in old objects only).
Functions that are removed (eg. via monkey-patching) from a module before it is reloaded are not upgraded.
C extension modules cannot be reloaded, and so cannot be autoreloaded.

itom.checkSignals() → int#

Verifies if a Python interrupt request is currently queued.

Returns:

int: Returns 1 if an interrupt is currently queued, else 0.

itom.clc()#: Clears the itom command line (if available).

itom.clearAll()#

Clears all variables in the global workspace.

This method clears all variables in the global workspace, that have been added after the startup process of itom. This only affects variables, that are also displayed in the workspace toolbox. Variables, like methods, functions, classes etc. are filtered out, and will therefore not be deleted.

Variables, that have been created by any startup script will also not be deleted.

itom.copyStringToClipboard(text)#

Copies the given text to the clipboard of your operating system.

Parameters:

textstr: This text is copied to the clipboard.

itom.getAppPath() → str#

Returns the absolute path of the base directory of this application.

The returned value is independent of the current working directory.

Returns:

pathstr: absolute path of this application’s base directory

itom.getCurrentPath() → str#

Returns the absolute path of the current working directory.

The current working directory is also displayed on the right side of the status bar of the main window of itom.

Returns:

str: the absolute path of the current working directory

See also

setCurrentPath

itom.getDefaultScaleableUnits() → List[str]#

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

unitslist of str: List with strings containing all scalable units

See also

scaleValueAndUnit

itom.getPalette(name) → dict#

Returns all relevant data of an existing color palette.

If a color palette with this name exists, its relevant data is returned as dictionary. The values in this dictionary can also be used to call the method setPalette().

Parameters:

namestr: name of the new palette.

Returns:

palettedict

Dictionary with the following entries:

namestr: name of the color palette.
colorStopstuple: tuple with all color stops, each element is another tuple whose first value is the float position of the stop in the range [0.0, 1.0]. The 2nd value is the corresponding rgba color. The first color stop is always at position 0.0, the last one at position 1.0.
inverseColor1rgba: first inverse color.
inverseColor2rgba: 2nd inverse color.
invalidColorrgba: color used for NaN or Inf values.

Raises:

RuntimeError: if no color palette with the given name is available.

See also

setPalette, getPaletteList

itom.getPaletteList(type=0) → Tuple[str]#

Returns a tuple with the names of all currently available color palettes.

Parameters:

typeint, optional: Unused parameter.

Returns:

tuple of str: Tuple with the names of all available color palettes.

See also

setPalette, getPalette

itom.getQtToolPath(toolname) → str#

Gets the absolute path of the given Qt tool

Parameters:

toolnamestr: The filename of the tool that should be searched (e.g. qcollectiongenerator; suffix is not required)

Returns:

pathstr: Absolute path to the given Qt tool.

Raises:

FileExistsError: if the given toolname could not be found

itom.getScreenInfo() → Dict[str, Any]#

Returns dictionary with information about all available screens.

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

Returns:

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.newScript()#

Opens an empty, new script in the current script window.

Raises:

RuntimeError: if the current user has no permission to open a new script.

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:

filenamestr or Any: 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.

Raises:

RuntimeError: if the current user has no permission to open a script.

itom.processEvents()#

This method processes posted events for the Python thread.

Please use this method with care.

itom.registerResource(rccFileName, mapRoot='') → bool#

Registers a resource file with the given rccFileName.

This method opens a given Qt rcc resource file and registers its content at the location in the resource tree specified by mapRoot. This mapRoot must usually be a slash separated path, starting with a slash. n To generate a rcc file, create an index of all files, that should be added to the resource file, in a qrc file and uses the rcc binary from Qt to compile the rcc file.

This method is new in itom > 4.0.0.

Parameters:

rccFileNamestr: filepath to the rcc resource file
mapRootstr, optional: root key, where the resources should be registered below (default: empty string)

Returns:

bool: True if the file could be successfully opened, else False.

See also

unregisterResource

itom.scaleValueAndUnit(scaleableUnits, value, valueUnit) → Tuple[float, str]#

Rescales a value and its unit to the next matching SI unit.

At first, it is checked if the given ‘’valueUnit’’ is contained in the list of the base units scaleableUnits. If this is the case, the given value is scaled such that the returned value is greater or equal than 1. The scaled value and the new unit is returned then.

Use the method getDefaultScaleableUnits() to obtain a suitable list of SI nbase units.

Parameters:

scaleableUnitslist of str: A list of str with all base units that should be considered for scaling. If the given ‘’valueUnit’’ is not contained in this list of base units, no scaling is done and the returned values are equal to [value, valueUnit].
valuefloat: The value to be scaled
valueUnitstr: The value unit to be scaled

Returns:

tuple: The returned tuple has the format [newValue, newUnit], where newValue is a float and newUnit is a string.

Examples

>>> baseUnits = getDefaultScaleableUnits()
>>> print(scaleValueAndUnit(baseUnits, 0.001, 'm'))
[1, 'mm']

itom.scriptEditor()#

Opens new, empty script editor window (undocked).

Raises:

RuntimeError: if the current user has no permission to open a new script.

itom.setApplicationCursor(cursorIndex=-1)#

Changes the itom cursor or restores the previously set cursor if -1.

This methods changes the overall cursor icon of itom where cursorIndex corresponds to the Qt enumeration Qt::CursorShape. e.g.:

0: Arrow

2: Cross Cursor

3: Wait Curson

13: Pointing Hand Cursor

14: Forbidden Cursor

16: Busy Cursor

Every change of the cursor is put on a stack. The previous cursor type is restored, if cursorIndex is set to -1.

Parameters:

cursorIndexint, optional: The cursor enumeration value of the desired cursor shape (Qt::CursorShape) or -1 if the previous cursor should be restored (default)

itom.setCurrentPath(newPath) → bool#

Set current working directory to a new absolute path.

sets the absolute path of the current working directory to ‘newPath’. The current working directory is the base directory for all subsequent relative paths 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:

newPathstr: The new path for the current working directory. If a file path is given, its base path is used.

Returns:

successbool: True in case of success else False.

See also

getCurrentPath

itom.setPalette(name, colorStops, inverseColor1=None, inverseColor2=None, invalidColor=None)#

Changes a given color palette or creates a new one with the given arguments.

This methods modifies an existing color palette (if a palette with name already exists) or creates a new color palette with the given name. An existing color palette can only be modified, if it has no write protection, which is the case for all pre-defined color palettes of itom (see color palette editor in itom property editor). If any of the optional values are not given, default values (from the gray color palette) are used, or, if the color palette name already exists, these values are left unchanged

To obtain the parameters of an existing color palette, that can be used as arguments of this method, unpack the returned dictionary of getPalette().

It is also possible to modify or create color palettes in the color palette editor of the itom property dialog. For more information see Palette Settings.

Parameters:

namestr

Name of the color palette.

colorStopstuple

Tuple with all color stops of this color palette. Each item of this tuple is another tuple with two values. The first value is the float position of the color stop in the range [0.0, 1.0]. The 2nd value is the rgba32 color at this position. Colors between two adjacent color stops are linearly interpolated.

The position of the first color stop has to be 0.0, the one of the last stop 1.0. There must be at least two colorStops.

inverseColor1rgba, optional

First inverse color, used for instance for line cuts, markers etc. of a 2D plot.

inverseColor2rgba, optional

second inverse color, used for instance for line cuts, markers etc. of a 2D plot.

invalidColorrgba, optional

color used for NaN or Inf values in plots. If the invalid color is not given and an existing color palette also has no invalid color, the color of the first color stop is taken.

See also

getPalette, getPaletteList

itom.showHelpViewer(collectionFile='', showUrl='')#

Opens the itom help viewer and displays the itom user documentation or another desired documentation.

The user documentation is shown in the help viewer window. If collectionFile is given, this user-defined collection file is displayed in this help viewer.

Parameters:

collectionFilestr, optional: If given, the indicated Qt collection file (.qch) will be loaded in the help viewer. Per default, the user documentation is loaded (pass an empty string or nothing).
showUrlstr, optional: Shows the document with the given URL inside the collection file (e.g. qthelp://org.sphinx.itomdocumentation.4.2.0/doc/02_installation/install_get_this_help.html). Per default, the index is shown (pass an empty string or nothing).

itom.unregisterResource(rccFileName, mapRoot='') → bool#

Unregisters the resource with the given rccFileName.

This method tries to unload all resources in the given rcc resource file from the location in the resource tree specified by mapRoot. The mapRoot must usually be a slash separated path, starting with a slash.

This method is new in itom > 4.0.0.

Parameters:

rccFileNamestr: filepath to the rcc resource file
mapRootstr, optional: root key, where the resources should be unloaded from (default: empty string).

Returns:

bool: True if the file could be successfully opened, else False.

See also

registerResource