Node API

class gpi.nodeAPI.NodeAPI(node)[source]

Base class for all external nodes.

External nodes implement the extensible methods of this class: i.e. compute(), validate(), execType(), etc... to create a unique Node module.

Core Functions

NodeAPI.initUI()[source]

Initialize the node UI (Node Menu).

This method is intended to be reimplemented by the external node developer. This is where Port and Widget objects are added and initialized. This method is called whenever a node is added to the canvas.

See Adding Widgets and Adding Ports for more detail.

NodeAPI.validate()[source]

The pre-compute validation step.

This function is intended to be reimplemented by the external node developer. Here the developer can access widget and port data (see Accessing Widget Data and Accessing Port Data) to perform validation checks before compute() is called.

Returns:0: The node successfully passed validation

1: The node failed validation, compute will not be called and the canvas will be paused

Return type:An integer corresponding to the result of the validation
NodeAPI.compute()[source]

The module compute routine.

This function is intended to be reimplemented by the external node developer. This is where the main computation of the node is performed. The developer has full access to the widget and port data (see Accessing Widget Data and Accessing Port Data).

Returns:0: Compute completed successfully

1: Compute failed in some way, the canvas will be paused

Return type:An integer corresponding to the result of the computation

Widget Functions

Adding Widgets

NodeAPI.addWidget(wdg=None, title=None, **kwargs)[source]

Add a widget to the node UI.

Parameters:
  • wdg (str) – The widget class name (see Widgets for a list of built-in widget classes)
  • title (str) – A unique name for the widget, and title shown in the Node Menu
  • kwargs – Additional arguments passed to the set_<arg> methods specific to the chosen widget class

Accessing Widget Data

NodeAPI.getVal(title)[source]

Returns the widget value.

Each widget class has a corresponding “main” value. This method will return the value of the widget, by passing along the return from its get_val() method.

Returns:The widget value. The type of the widget value is defined by the widget class. See Widgets for value types for the built-in widget classes.
NodeAPI.setAttr(title, **kwargs)[source]

Set specific attributes of a given widget.

This method may be used to set attributes of any widget during any of the core node functions: initUI(), validate(), or compute().

Parameters:
  • title (str) – the widget name (unique identifier)
  • kwargs – args corresponding to the get_<arg> methods of the widget class. See Widgets for the list of built-in widgets and associated attributes.
NodeAPI.getAttr(title, attr)[source]

Get a specific attribute value from a widget.

This returns the value of a specific attribute of a widget. Widget attributes may be modified by the user manipulating the Node Menu, during widget creation using the kwargs in addWidget(), or programmatically by setAttr().

Parameters:
  • title (str) – The widget name (unique identifier)
  • attr (str) – The desired attribute
Returns:

The desired widget attribute. This value is retrieved by calling get_<attr> on the indicated widget. See Widgets for a list of attributes for the buil-in widget classes.

Port Functions

Adding Ports

NodeAPI.addInPort(title=None, type=None, obligation=100, menuWidget=None, cyclic=False, **kwargs)[source]

Add an input port to the node.

Input ports collect data from other nodes for use/processing within a node compute function. Ports may only be added in the initUI() routine. Data at an input node can be accessed using getData(), but is typically read-only.

Parameters:
  • title (str) – port title (shown in tooltips) and unique identifier
  • type (str) – class name of extended type (e.g. np.complex64)
  • obligationgpi.REQUIRED (default) or gpi.OPTIONAL
  • menuWidgetfor internal use, devs should leave as default None
  • cyclic (bool) – whether the port should allow reverse-flow from downstream nodes (default is False)
  • kwargs – any set_<arg> method belonging to the GPIDefaultType derived class
NodeAPI.addOutPort(title=None, type=None, obligation=100, menuWidget=None, **kwargs)[source]

Add an output port to the node.

Output nodes provide a conduit for passing data to downstream nodes. Ports may only be added in the initUI() routine. Data at an output port can be accessed using setData() and getData() from within validate() and compute().

Parameters:
  • title (str) – port title (shown in tooltips) and unique identifier
  • type (str) – class name of extended type (e.g. np.float32)
  • obligationgpi.REQUIRED (default) or gpi.OPTIONAL
  • menuWidgetfor internal use, debs should leave as default None
  • kwargs – any set_<arg> method belonging to the GPIDefaultType derived class

Accessing Port Data

NodeAPI.setData(title, data)[source]

Set the data at an OutPort.

This is typically called in compute() to set data at an output port, making the data available to downstream nodes. InPort ports are read-only, so this method should only be used with OutPort ports.

Parameters:
  • title (str) – name of the port to send the object reference
  • data – any object corresponding to a GPIType class allowed by this port
NodeAPI.getData(title)[source]

Get the data from a Port for this node.

Usually this is used to get input data from a InPort, though in some circumstances (e.g. in the Glue node) it may be used to get data from an OutPort. This method is available for devs to use in validate() and compute().

Parameters:title (str) – the name of the GPI Port object
Returns:Data from the Port object. The return will have a type corresponding to a GPIType class allowed by this port.

Port Data Types

NumPy Types

class gpi.types.numpy_GPITYPE.NPYarray[source]

The NPYarray type provides port enforcement for numpy multidimensional arrays (ndarray). The enforcement parms are type (ndarray), dtype, ndim, dimension range (drange), shape, and vec (the len of the last dim). Enforcement priority for aliased parms goes ndim->drange->shape. Although shape and vec can overlap, they are enforced independently.

set_drange(val)[source]

tuple(int,int) | Requires a dimension range tuple (min, max).

set_dtype(val)[source]

numpy dtype | Requires an NPY type (i.e. float32, complex64, etc...)

set_ndim(val)[source]

int | Set enforcement for the number of dimensions. Requires (int).

set_shape(val)[source]

tuple(int,int,...) | Requires the dimension lengths in an integer tuple.

set_vec(val)[source]

int | Requires an integer representing the length of the last (most varying) dimension (or shape[-1]).

Python Types

class gpi.types.python_GPITYPE.COMPLEX[source]

Enforcement for the standard python-complex.

class gpi.types.python_GPITYPE.DICT[source]

Enforcement for the standard python-dict.

class gpi.types.python_GPITYPE.FLOAT[source]

Enforcement for the standard python-float.

set_range(val)[source]

float | Specify a float range using a tuple (min, max).

class gpi.types.python_GPITYPE.INT[source]

Enforcement for the standard python-int.

set_range(val)[source]

int | Specify an integer range using a tuple (min, max).

class gpi.types.python_GPITYPE.LIST[source]

Enforcement for the standard python-list.

class gpi.types.python_GPITYPE.LONG[source]

Enforcement for the standard python-long.

set_range(val)[source]

tuple(int,int) | Specify an integer range using a tuple (min, max).

class gpi.types.python_GPITYPE.STRING[source]

Enforcement for the standard python-str.

class gpi.types.python_GPITYPE.TUPLE[source]

Enforcement for the standard python-tuple.

OpenGL Types

class gpi.types.globjectlist_GPITYPE.GLOList[source]

Allows passing GPI-GL object definitions to be passed in lists.

Event Functions

NodeAPI.getEvents()[source]

Get information about events that caused the node to run.

Returns a dictionary containing names of widgets and ports that have changed values since the last time the node ran. Additionally contains information regarding init or requeue events trigered by GPI’s node-evaluation routines.

Note: events from widget-ports count as both widget and port events.

Returns:all events accumulated since the node was last run
The event dictionary contains four key:value pairs:
  • GPI_WIDGET_EVENT : set(widget_titles (string))
  • GPI_PORT_EVENT : set(port_titles (string))
  • GPI_INIT_EVENT : True or False
  • GPI_REQUEUE_EVENT : True or False
Return type:dict
NodeAPI.portEvents()[source]

Specifically check for port events.

Get the names (unique identifier strings) of any ports that have changed data since the last run.

Note: events from widget-ports count as both widget and port events.

Returns:names (strings) of all ports modified since the node last ran
Return type:set
NodeAPI.widgetEvents()[source]

Specifically check for a widget events.

Get the names (unique identifier strings) of any widgets that have changed data since the last run.

Note: events from widget-ports count as both widget and port events.

Returns:names (strings) of all widgets modified since the node last ran
Return type:set

Additional Functions

NodeAPI.setDetailLabel(newDetailLabel='', elideMode='middle')[source]

Set an additional label for the node.

This offers a way to programmatically set an additional label for a node (referred to as the detail label), which shows up underneath the normal node tile and label (as set wihtin the node menu). This is used by the core library to show file paths for the file reader/writer nodes, for example.

Parameters:
  • newDetailLabel (string) – The detail label for the node (e.g. file path, operator, ...)
  • elideMode ({'middle', 'left', 'right', 'none'}, optional) – Method to use when truncating the detail label with an ellipsis.
NodeAPI.getDetailLabel()[source]

Get the current node detail label.

Returns:The node detail label, as set by setDetailLabel()
Return type:string
NodeAPI.starttime()[source]

Begin the timer for the node Wall Time calculation.

Nodes store their own runtime, which is displayed in a tooltip when hovering over the node on the canvas (see User Interface). Normally, each node reports the complete time it takes to run its compute() function. However, a dev can use this method along with endtime() to set the portion of compute() to be used to calculate the Wall Time.

NodeAPI.endtime(msg='')[source]

Begin the timer for the node Wall Time calculation.

Nodes store their own runtime, which is displayed in a tooltip when hovering over the node on the canvas (see User Interface). Normally, each node reports the complete time it takes to run its compute() function. However, a dev can use this method along with starttime() to set the portion of compute() to be used to calculate the Wall Time. This method also prints the Wall Time to stdout, along with an optional additional message, using gpi.logger.PrintLogger.node()).

Parameters:msg (string) – a message to be sent to stdout (using gpi.logger.PrintLogger.node()) along with the Wall Time
gpi.node_profiler.profiler(func)[source]

A decorator for profiling Python performance

Just import the profiler and decorate the function you want to profile (e.g. compute()):

from gpi.node_profiler import profiler
import np as np

...

@profiler
def compute(self):
    print([n**2 for n in np.range(1000)])
    return 0

GPI must be started from the terminal, as profiler output is written to stdout.

Logging (through NodeAPI.log)

PrintLogger.debug(msg)[source]
PrintLogger.info(msg)[source]
PrintLogger.node(msg)[source]
PrintLogger.warn(msg)[source]
PrintLogger.error(msg)[source]
PrintLogger.critical(msg)[source]