Actions

Actions are custom operations that appear on the context menu when you right-click selected cases in a Tecplot Chorus project. Two sample actions are included with Tecplot Chorus:

Extract Data with Tecplot 360: Executes a macro that extracts a slice from a data file associated with each case and writes the slice data to its own file. A link to this file is then added to your Tecplot Chorus project. This action may be modified to invoke other macro files for other purposes.

After extraction has finished, click Manage Jobs at the bottom of the Tecplot Chorus window, select the job, and click Deposit.
Open with Paraview: Opens a data file associated with the first selected case using the third-party Paraview data visualization tool.

The example actions run Python scripts.

Enabling the Example Actions

The example actions are stored in the folder interop/actions, which is in the Tecplot Chorus installation folder. This folder also contains a registration file, a simple XML file that tells Tecplot Chorus how each action should appear in the context menu and the command line necessary to invoke it.

Tecplot Chorus supports multiple registration files; all .xml files in the interop/actions folder are scanned for action definitions. The file examples.xml is the registration file for the example actions. You will need to modify this file to enable the example actions, as they are turned off initially.

Tecplot Chorus will also scan a folder in your home directory for action registration files. This may be useful if you don’t have write access in the program installation directory, or if you want certain actions to be available only to certain users. On Windows, this folder is Tecplot/Chorus/interop/actions in your My Documents folder. On Linux, this folder is ~/.tecplot/chorus/interop/actions. You’ll need to create this folder if it does not exist.

You may want to copy examples.xml (and other action registration files) to this folder and modify it there so it will be used by future versions of Tecplot Chorus you install without needing to copy it to the new version’s interop/actions directory.

Open examples.xml in a text editor and find the <action> tags, which initially read <action enabled="false">. Change one or both of these to read <action enabled="true">. The line immediately following the <action> tag includes a <name> tag that identifies the action you’re editing.

The <exec> tag for each action includes placeholder text that must be edited before the actions will work on your computer. In particular:

Replace /path/to/python with the path of your Python interpreter. On Linux systems, this is usually /usr/bin/python. If an appropriate Python interpreter is in your system’s PATH, you may simply use python.
Replace /path/to/ExtractDataWithTecplot360.py or /path/to/OpenWithParaview.py with the full paths to these scripts. On Windows, these files are usually in C:/Program Files/Tecplot/Tecplot Chorus 2023 R2/interop/actions.

Windows users should use forward slashes (/) in pathnames rather than backslashes (\).

The text %INSTRUCTION_FILE% will be used by Tecplot Chorus when the action is invoked. Do not change it.

After enabling one or both of the custom actions, close Tecplot Chorus if it is open, then restart it and open a project. When you right-click selected cases in any data view or plot, the enabled actions will be shown in the context menu, as seen here. However, the actions won’t run until you make the changes described in the next section.

Configuring the Example Actions

The example Python scripts must be modified before they will run on your computer. Open them in a text editor and make the indicated changes.

ExtractDataWithTecplot360.py

Search for the following placeholders and replace them as noted.

/path/to/resulting/data/datafile.plt: Replace with the path where the generated Tecplot 360 data file (.plt file) will be temporarily stored before being added to the project.
/path/to/tecplot360/bin/tec360: Replace with the path to the Tecplot 360 executable. On Windows systems, this is usually C:/Program Files/Tecplot/Tecplot 360 EX 2024 R1/bin/tec360.exe.
/path/to/extract_slice.mcr: Replace with the path to the Tecplot 360 macro to be run, i.e., extract_slice.mcr.

Windows users should use forward slashes (/) in pathnames rather than backslashes (\).

OpenWithParaview.py

Search for the placeholder /path/to/paraview and replace it with the complete path of the Paraview executable on your system.

Windows users should use forward slashes (/) in pathnames rather than backslashes (\).

Creating Your Own Actions

As this feature is new, there may be changes to how actions work in future releases of Tecplot Chorus.

If you can program in Python, the example Python scripts and Tecplot macros can be used as starting points for developing your own actions.

Tecplot Chorus actions can, however, be written in virtually any language. While we used Python for the examples, you could use Perl, Ruby, Java, C#, C++ or C. If you can use it to write programs that can be run from the command line, you can use it to write a Tecplot Chorus action. (An XML library is handy, too.)

Actions work according to the following process:

The user invokes the action by selecting one or more cases, right-clicking, and choosing the action from the context menu.
Tecplot Chorus writes an instruction XML file. The instruction file contains information about the project, the job, and the selected cases.
Your action is launched, passing the path to the instruction file as an argument to your action according to the command line template given in the <exec> tag in the action registration file.
Your action reads and parses the instruction file.

The instruction file contains XML data. Its schema is subject to change and is currently not documented; the best way to see what’s in an instruction file is to write a custom action that displays it or copies it to a safe location for later review.

Using information gleaned from the instruction file, your action script performs its work.
If your action needs to add any variables or file links to the project, it must perform the following steps:
- Write its results to a CSV file in the pending jobs folder specified by the instruction XML file. The name of the results must be job#.csv where # is replaced with the job ID from the instruction XML. The first column must be the Case ID for the affected cases. Additional columns may be used to overwrite variables already in the project for the indicated cases or to add new variables.
  
  Only one or more successfully processed cases should be written to this CSV file. The number of successfully processed cases may be less than the number of cases passed to the action. If no cases were successfully processed, do not create the CSV file. Tecplot Chorus uses the presence or absence of this file to determine the status displayed in the Manage Jobs dialog.
- Write a status message to job#.runstatus in the pending jobs folder (again, # is replaced with the job ID). This text is displayed when the user clicks the Job Details button in the Manage Jobs dialog.
- Finally, create job#.done (where # is once more replaced with the job ID) in the pending jobs folder to signal to Tecplot Chorus that it has finished its work.
- The user then deposits the action’s results into their project using the Manage Jobs window.
If the action does not need to add any data to the project, for example for a viewer action such as the Paraview example action, it should simply delete the instruction file to signal to Tecplot Chorus that the action has been completed.

The provided Python utility library, JobInfo.py, helps you manage this flow if you are writing your action in Python. Make sure a copy is in the same folder as your action, or in some other folder that Python will look in for modules, such as your Python installation’s site-packages directory.

After writing your script, tell Tecplot Chorus how to invoke your action by creating a registration file for it. We suggest copying examples.xml to a different name and modifying it as appropriate. A single registration file may contain definitions of multiple custom actions; simply include as many <action>… </action> sections as required.

Your action’s registration file should be placed in the interop/actions directory in your Tecplot Chorus installation folder, or in the user-specific action folders appropriate to your operating system:

Windows: Tecplot/Chorus/interop/actions in My Documents.
Linux: ~/.tecplot/chorus/interop/actions.