Writing Python Nodes

Development Environment

We strongly recommend the use of VSCode as an editor for creating and modifying python node scripts. Then follow these steps to set up the editor.

1. Ensure the Python extension pack is installed.

2. Select the python interpreter built into Connect

   `Ctrl-Shift-P` > "Python: Select Interpreter" > "Enter Interpreter Path" > `[Connect Install Dir]\bin\python.exe`

3. Set the python search paths to include our prepackaged modules

   Settings > Python: Analysis: Extra Paths > Add `[Connect Install Dir]\bin\Lib\site-packages`

PythonNodeBase allows python node developers to interact only with numpy objects while creating an algorithm. This interface currently only supports table data, but greatly simplifies interaction with vtk.

Creating a Node Script

All python node scripts must contain a class named PythonNode which derives (directly or transitively) from VTKPythonAlgorithmBase. Provided base node types in the ema3d.pynode package meet this requirement.

PythonNodeBase

All python nodes are recommended to inherit from PythonNodeBase. This base class provides convenient methods for interacting with time steps and data and handles port naming and types.

For an example of how to use this base class, see ugrid_processing_example.py in the ema3d.templates python package.

TableNodeBase

This base class simplifies the creation of nodes which produce tabular output, but does not impose limitations on the type of input they take. Nodes which also take tabular input may benefit from the use of TableToTableNode.

Implementation of data processing logic should be in an override of the ProcessData method of the PythonNode class. Processing on the input data objects should result in a numpy array which can then be passed into the returnProcessedData method with matching metadata to put the numpy array and associated metadata into the output information object in the proper format.

TableToTableNode

This base class simplifies the creation of nodes which take tabular inputs and produce a tabular output. Types are converted automatically between vtk and numpy representations and convenience methods are available to deal with input data and propagate names and type information.

Start by creating a script with a class called PythonNode which subclasses from TableToTableNode. All implementation code for custom nodes based on TableToTableNode should go in an override of the process method, which is called whenever data is requested. Data from the node's ports is provided to the process method in the form of two arguments, data: list[ndarray] and metadata: list[TableMetadata]. Each is a list with a single entry for each port. Each port's data array is a numpy array with data columns provided to that port accessible along axis 0, and column name and type available in the metadata array at the corresponding index in the "names" and "types" property lists.

For additional support, consult table_node_example.py in the ema3d.templates package which provides an example of a node which does an FFT on input voltage data.

If you need direct control over VTK data types, want to work with data types unsupported by convenience base classes, or simply like doing things the hard way, you can inherit directly from VTKPythonAlgorithmBase. Implement logic in RequestData and possibly RequestInformation, RequestUpdateExtent, and RequestDataObject.

Resources

• Official VTKPythonAlgorithmBase Docs

• Official VTK Documentation

• VTK Python Examples

• Minimal python example in ema3d.templates.vtk_base_example

Note that while some online examples may use the legacy import vtk import for VTK types, this is unsupported when writing python nodes. Instead, directly import the appropriate module with from vtkmodules.submodule... import ModuleName . All modules imported by the legacy import can be imported in the new style.

Generating .pyi Files

If you're working directly with VTK data types and functions, it's useful to have automatic completion and some type hints available. These aren't perfect - VTK's python bindings are not fully typed - but they do help.

1. Generate python information files

   1. In an administrative terminal, navigate to (Connect Install Dir)\bin\Lib\site-packages\vtkmodules

   2. Run ..\..\..\python.exe generate_pyi.py. It will likely take a few seconds to run and some error messages are normal.

2. Configure VSCode to index to the full depth of the package

   1. Settings > Python: Analysis: Package Index Depths > Edit in settings.json (or open your VSCode settings.json)

   2. Add the following to the python.analysis.packageIndexDepths list:

      json

      Copy

      {
      "name": "vtkmodules",
      "depth": 4,
      "includeAllSymbols": true
      }