[Avizo/Amira]
Context
Amira-Avizo does not support direct customization of module ports. All modules that can be associated with a data object are available through the object’s pop-up menu, which can be accessed by right-clicking the object’s icon:
The default values of each port are either predefined or automatically computed based on the input data. For certain use cases, it may be desirable to further customize newly created modules using scripting. Additionally, extending an object’s pop-up menu with new entries to invoke specific scripts can be useful when only the default values need to be modified.
This article describes how to achieve these objectives by modifying existing Amira-Avizo resource files or by creating new ones.
Prerequisites
You must have permission to create files and write to the following directory:
<Installation Directory>/share/resources
where <Installation Directory> is the location where the Amira-Avizo software is installed. By default:
- Windows:
C:\Program Files\Thermo Scientific Amira-Avizo3D <version>\
- Linux:
/usr/local/AmiraAvizo3D/<version>/
Process
To customize modules, create a resource file (.rc) and place it in the <Installation Directory>/share/resources folder. Resource files are plain text files that define scripting-based customizations.
For more details, refer to Developer Tools > Tcl Scripting > Configuring Popup Menus in the User's Guide.
In this article, the Axes module is used as an example. The same approach can be applied to other modules.
The Axes module can be accessed from:
- View > Axes in the top menu, or
- The dataset context menu: Annotate > Axes.
The goal is to apply the following customizations:
- Create a new module name AxesCustom1 in the Custom Modules category
- Set the Axes font to Arial with a pink color
- Set the axes colors to yellow, violet, and gray
- Enable the grid.
To apply these characteristics, the following steps must be applied:
1. Retrieve the class name and the scripting commands
1.1. Start the application
Start the application and load a dataset.
1.2. Retrieve the module's class name
For more information, refer to Developer Tools > Tcl Scripting > Script Interface in the User's Guide.
Select the dataset icon and create the Axes object from the Annotate category of the pop-up menu. Hover over the Axes icon until the tooltip appears. The tooltip displays the module's class name (highlighted by the red square in the image below).
The class name is HxAxis.
1.3. Retrieve the port name
Next, identify the port names. In most cases, a port name matches the text label shown in the graphical user interface, with whitespace removed and the first letter in lowercase.
To list all ports for a specific module, open the Tcl Console (Ctrl+A) and type the command <object-name> allPorts.
Example output:
>"Axes" allPorts
data axis options thickness color axisNames textOnOff font showAxisGraduationOnOff textAlignementX textAlignementY textAlignementZ
In this example, the Font port corresponds to "font", and the Colors port corresponds to "color".
Most ports support either setValue/getValue or setState/getState commands:
- setValue/getValue operate on a specific port value
- setState/getState affect the entire port configuration.
The number of parameters and their syntax depend on the port type. Commands of the form <object-name> <port-name> setValue ... represent over 90% of typical scripts.
For detailed information about ports, refer to Guide > Ports Index > Port: Base Class in the Reference documentation.
Example commands:
>"Axes" font getState
name: "Arial Unicode MS" size: 10 buttonText: Select bold: 0 italic: 0 color: 0.8 0.8 0.8
>"Axes" color getState
rgba 4 1 0 0 1 0 1 0 1 0 0 1 1 1 0.8 0.5 1
> "Axes" options getValue 1
0
1.4. Retrieve new port values
The values returned in the console reflect the current settings, which in this case are the application default.
To obtain new values, either consult the module documentation or manually adjust the port to the desired settings. Then re-run the same commands in the console:
>"Axes" font getState
name: "Arial" size: 20 buttonText: Select bold: 0 italic: 0 color: 1 0.8 0.8
>"Axes" color getState
rgba 4 0.922 0.898 0.475 1 0.498 0.498 1 1 0.667 0.667 0.667 1 1 0.8 0.5 1
> "Axes" options getValue 1
1
2. Instantiate the Custom Modules
2.1. Write the file
According to User's Guide Tools > Tcl Scripting > Configuring Popup Menus, the following script implements the required customizations:
module -name "AxesCustom1" \
-primary "HxSpatialData" \
-class "HxAxis" \
-category "CustomModules" \
-package hxcoremodules \
-icon "TVDefAxis" \
-package "hxcoremodules" \
-proc { $this font setState {name: "Arial" size: 20 buttonText: Select color: 1 0.8 0.8};
$this fire;
$this options setValue 1 1;
$this fire;
$this color setState {rgba 4 0.922 0.898 0.475 1 0.498 0.498 1 1 0.667 0.667 0.667 1 1 0.8 0.5 1};
$this fire;}
In this script, "$this" refers to the resource object (AxesCustom1 here), and the "$this fire" command may be required for certain ports to apply their changes. The fire command can be added after each line, with the only side effect being a slight time delay.
Create a new resource file named MyResourceFile.rc, past the above scripting into it, and save it to the folder <Installation Directory>/share/resource.
2.2. Instantiate the modules
- Restart the application and load the dataset.
- Open the dataset context menu and select the Custom Modules category. The new module is now available.
Notes & Related Information
- To view a module's default resource definition, search for its class name in the .rc files located in <Installation Directory>/share/resources.
- Modifying pre-installed resource files is possible but not recommended, as these files are part of the application installation. Always backed up installation files before making changes.
- Creating a separate resource file is strongly recommended to avoid potential conflicts with standard modules.
- To preserve customizations across software upgrades, copy the custom .rc file to newer installations.