25 Nov 2021

How to Customize Amira-Avizo with moduleExtender

Are there module settings you always need to change during your daily work? This Xtra describes how you can permanently change default settings of modules in Amira-Avizo.

Xtra_Customize_with_moduleExtender_title

Using this Xtra file, modified_module_behaviour.rc2, the settings of a number of modules are changed by executing the Tcl-code inside the "proc" section on instantiation of the module.

The changes affect the following modules in the described ways:

Generate Surface: Normally, if you try to create a surface from a not very small label data-set, a warning window pops up. By setting the "setInteractive" port to 0, that window is no longer shown.
Volren:
1. In Amira-Avizo, the default colormap for Volren is "volrenRed". That default is changed to "volrenWhite".
2. With version 2021.1, the "Auto adjust range" option of the colormap has been activated by default. This results in a re-adjustment of the range-values of colormap whenever Volren is re-connected to another data-object. After running the Tcl code, that behavior is changed such that "Auto adjust range" is only activated on right-click instantiation on a data-object, and immediately deactivated afterwards.
Volume Rendering:
1. In Amira-Avizo, the default colormap for Volume Rendering is "volrenWhite". That default is changed to "grayScale".
2. With version 2021.1, the option "Auto adjust range" of the colormap has been activated by default. This results in a re-adjustment of the range-values of colormap whenever Volume Rendering is re-connected to another data-object. After running the Tcl code, that behavior is changed such that "Auto adjust range" is only activated on right-click instantiation on a data-object, and immediately deactivated afterwards.
3. The default for the "Sampling Quality" setting is 0.5, which becomes too slow for interactive use for larger data-sets on medium-sized GPUs. That setting is changed to 0.2.
Surface Cross Contour: The default setting of "epsilon" might cause doubled contour-lines in certain circumstances. By reducing that value to 1e-10, that no longer occurs.
Ortho Slice: With version 2021.1, the option "Auto adjust range" of the colormap has been activated by default. This results in a re-adjustment of the range-values of colormap whenever Ortho Slice is re-connected to another data-object. After running the Tcl code, that behavior is changed such that "Auto adjust range" is only activated on right-click instantiation on a data-object, and immediately deactivated afterwards.

You can modify the modified_module_behaviour.rc2 file. Here are a few hints:

Putting a "#" as first character in a line marks that line as a comment, and it is not interpreted.
Be careful that you have the backslash ("\") at the end of each line within one call of moduleExtender, because those calls are in principle one-line commands, but for readability they have been split into multiple lines. The backslash is telling the interpreter that the command is continued in the next line.
You have to use the semicolons (";"), which are, in Tcl, separators of commands within one line.
The "$this fire;" command forces a refresh of the module using the parameters set earlier. In some cases this is necessary before you can set other parameters.
If you want to use the modified file, you have to restart Amira-Avizo, because resource-files are only sourced on start-up.

Background information

moduleExtender

In Amira-Avizo it is possible to customize the behavior of modules by using the "moduleExtender" internal Tcl-command.
With "moduleExtender", an already registered module is replaced by a modified version.
The changes demonstrated here are done by executing the Tcl-code inside the "-proc { ... }" block whenever the module is instantiated.
Some of the changes are after "if"-blocks like this:

  if { [exists $PRIMARY] } { \
    $this data connect $PRIMARY \
  }; \
  $this fire; \

That "if"-block forces the connection of the data-object before the modified settings defined afterwards are applied.

Resource files

Resource-files in Amira-Avizo are special files containing code in the Tcl scripting-language. They are used, for example, to register modules and data-types.

Resource files are sourced (read and interpreted) at start-up of Amira-Avizo. They have to be located in one of the specific sub-directories:

share\resources
share\script-objects
share\python_script_objects

of either the installation directory (i.e. AVIZO_ROOT or AMIRA_ROOT) or the user-defined "local" directory (AVIZO_LOCAL or AMIRA_LOCAL, see here for instructions).

Resource files must have either an ".rc" or ".rc2" file extension. Depending on the extension, they are sourced at different stages of the start-up procedure. Resource files in AVIZO_LOCAL are sourced after those in AVIZO_ROOT, and ".rc2"-files are sourced after all the ".rc"-files.