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
andWidget
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¶
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()
, orcompute()
.Parameters:
-
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 bysetAttr()
.Parameters: 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 usinggetData()
, 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
) - obligation –
gpi.REQUIRED
(default) orgpi.OPTIONAL
- menuWidget – for 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 usingsetData()
andgetData()
from withinvalidate()
andcompute()
.Parameters: - title (str) – port title (shown in tooltips) and unique identifier
- type (str) – class name of extended type (e.g.
np.float32
) - obligation –
gpi.REQUIRED
(default) orgpi.OPTIONAL
- menuWidget – for 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 withOutPort
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 anOutPort
. This method is available for devs to use invalidate()
andcompute()
.Parameters: title (str) – the name of the GPI Port
objectReturns: Data from the Port
object. The return will have a type corresponding to aGPIType
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.
-
matchesData
(data)[source]¶ Returns True if self matches input data. By default all data matches. Fail-usable in case the porttype can’t be found.
-
matchesType
(type_cls)[source]¶ Returns True if self matches type_cls. By default all types match. Fail-usable in case the porttype can’t be found. type_cls is of the upstream port since the inPort is the limiting factor.
-
setDataAttr
(data)[source]¶ Set any attributes on the data object (e.g. numpy arrays need to be readonly). the data object can be modified and returned in this hook. Passthrough by default.
-
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.
-
matchesData
(data)[source]¶ Returns True if self matches input data. By default all data matches. Fail-usable in case the porttype can’t be found.
-
matchesType
(type_cls)[source]¶ Returns True if self matches type_cls. By default all types match. Fail-usable in case the porttype can’t be found. type_cls is of the upstream port since the inPort is the limiting factor.
-
setDataAttr
(data)[source]¶ Set any attributes on the data object (e.g. numpy arrays need to be readonly). the data object can be modified and returned in this hook. Passthrough by default.
-
-
class
gpi.types.python_GPITYPE.
DICT
[source]¶ Enforcement for the standard python-dict.
-
matchesData
(data)[source]¶ Returns True if self matches input data. By default all data matches. Fail-usable in case the porttype can’t be found.
-
matchesType
(type_cls)[source]¶ Returns True if self matches type_cls. By default all types match. Fail-usable in case the porttype can’t be found. type_cls is of the upstream port since the inPort is the limiting factor.
-
setDataAttr
(data)[source]¶ Set any attributes on the data object (e.g. numpy arrays need to be readonly). the data object can be modified and returned in this hook. Passthrough by default.
-
-
class
gpi.types.python_GPITYPE.
FLOAT
[source]¶ Enforcement for the standard python-float.
-
matchesData
(data)[source]¶ Returns True if self matches input data. By default all data matches. Fail-usable in case the porttype can’t be found.
-
matchesType
(type_cls)[source]¶ Returns True if self matches type_cls. By default all types match. Fail-usable in case the porttype can’t be found. type_cls is of the upstream port since the inPort is the limiting factor.
-
setDataAttr
(data)[source]¶ Set any attributes on the data object (e.g. numpy arrays need to be readonly). the data object can be modified and returned in this hook. Passthrough by default.
-
-
class
gpi.types.python_GPITYPE.
INT
[source]¶ Enforcement for the standard python-int.
-
matchesData
(data)[source]¶ Returns True if self matches input data. By default all data matches. Fail-usable in case the porttype can’t be found.
-
matchesType
(type_cls)[source]¶ Returns True if self matches type_cls. By default all types match. Fail-usable in case the porttype can’t be found. type_cls is of the upstream port since the inPort is the limiting factor.
-
setDataAttr
(data)[source]¶ Set any attributes on the data object (e.g. numpy arrays need to be readonly). the data object can be modified and returned in this hook. Passthrough by default.
-
-
class
gpi.types.python_GPITYPE.
LIST
[source]¶ Enforcement for the standard python-list.
-
matchesData
(data)[source]¶ Returns True if self matches input data. By default all data matches. Fail-usable in case the porttype can’t be found.
-
matchesType
(type_cls)[source]¶ Returns True if self matches type_cls. By default all types match. Fail-usable in case the porttype can’t be found. type_cls is of the upstream port since the inPort is the limiting factor.
-
setDataAttr
(data)[source]¶ Set any attributes on the data object (e.g. numpy arrays need to be readonly). the data object can be modified and returned in this hook. Passthrough by default.
-
-
class
gpi.types.python_GPITYPE.
LONG
[source]¶ Enforcement for the standard python-long.
-
matchesData
(data)[source]¶ Returns True if self matches input data. By default all data matches. Fail-usable in case the porttype can’t be found.
-
matchesType
(type_cls)[source]¶ Returns True if self matches type_cls. By default all types match. Fail-usable in case the porttype can’t be found. type_cls is of the upstream port since the inPort is the limiting factor.
-
setDataAttr
(data)[source]¶ Set any attributes on the data object (e.g. numpy arrays need to be readonly). the data object can be modified and returned in this hook. Passthrough by default.
-
-
class
gpi.types.python_GPITYPE.
STRING
[source]¶ Enforcement for the standard python-str.
-
matchesData
(data)[source]¶ Returns True if self matches input data. By default all data matches. Fail-usable in case the porttype can’t be found.
-
matchesType
(type_cls)[source]¶ Returns True if self matches type_cls. By default all types match. Fail-usable in case the porttype can’t be found. type_cls is of the upstream port since the inPort is the limiting factor.
-
setDataAttr
(data)[source]¶ Set any attributes on the data object (e.g. numpy arrays need to be readonly). the data object can be modified and returned in this hook. Passthrough by default.
-
-
class
gpi.types.python_GPITYPE.
TUPLE
[source]¶ Enforcement for the standard python-tuple.
-
matchesData
(data)[source]¶ Returns True if self matches input data. By default all data matches. Fail-usable in case the porttype can’t be found.
-
matchesType
(type_cls)[source]¶ Returns True if self matches type_cls. By default all types match. Fail-usable in case the porttype can’t be found. type_cls is of the upstream port since the inPort is the limiting factor.
-
setDataAttr
(data)[source]¶ Set any attributes on the data object (e.g. numpy arrays need to be readonly). the data object can be modified and returned in this hook. Passthrough by default.
-
OpenGL Types¶
-
class
gpi.types.globjectlist_GPITYPE.
GLOList
[source]¶ Allows passing GPI-GL object definitions to be passed in lists.
-
matchesData
(data)[source]¶ Returns True if self matches input data. By default all data matches. Fail-usable in case the porttype can’t be found.
-
matchesType
(type_cls)[source]¶ Returns True if self matches type_cls. By default all types match. Fail-usable in case the porttype can’t be found. type_cls is of the upstream port since the inPort is the limiting factor.
-
setDataAttr
(data)[source]¶ Set any attributes on the data object (e.g. numpy arrays need to be readonly). the data object can be modified and returned in this hook. Passthrough by default.
-
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
orrequeue
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
orFalse
GPI_REQUEUE_EVENT
:True
orFalse
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 withendtime()
to set the portion ofcompute()
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 withstarttime()
to set the portion ofcompute()
to be used to calculate the Wall Time. This method also prints the Wall Time to stdout, along with an optional additional message, usinggpi.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
.