Python_CallFunction

void fil::Python_CallFunction
(
	const ftl::File& inModulePath,
	const ftl::String& inFunctionName,
	ftl::Optional<const fil::PythonObject&> inArg1,
	ftl::Optional<const fil::PythonObject&> inArg2,
	ftl::Optional<const fil::PythonObject&> inArg3,
	ftl::Optional<const fil::PythonObject&> inArg4,
	ftl::Optional<const fil::PythonObject&> inArg5,
	ftl::Optional<const fil::PythonObject&> inArg6,
	ftl::Optional<fil::PythonObject&> outResult1,
	ftl::Optional<fil::PythonObject&> outResult2,
	ftl::Optional<fil::PythonObject&> outResult3,
	ftl::Optional<fil::PythonObject&> outResult4
)

This filter allows to utilize/interface with Python scripts and libraries by calling a function in a Python module while passing its arguments and retrieving its results through filter input and output ports.

For this filter to work it is required to separately install the Python runtime version 3.12 in the system with installation path added to the system environment variables. Currently the filter is only supported on the Windows operating system.

inModulePath input specifies a path to a Python module/script file to be loaded (the path must point to a file with .py extension). This module will be loaded into the Python environment created in the background only once over a vision program execution. Upon load the top level part of the script will be executed allowing to initialize the scripts global state and prepare any custom environment. The module will stay loaded and the global state of the module will be preserved (even after exiting a Task macrofilter) up until the vision program stops. Subsequent calls to the same filter instance or other instances of the Python_CallFunction filters pointing to the same python script file will invoke the already loaded module. Thus it is possible to contain additional work state in Pythons global variables and refer to it from various Python functions from various Python_CallFunction filter instances.

After the vision program stops and starts again all modules are unloaded and the global Python state is reset. Note that to reset the Python environment state when working from FabImage Library programmers interface the fil::Python_Cleanup() function can be used.

inFunctionName specifies the name of the function to be invoked. This name must point to a Python function existing in the top level namespace of the specified Python script module.

inArg1 to inArg6 inputs provide input arguments for the function call. Objects from those inputs are passed to the function in order as positional arguments. Leaving the input on its default (Auto) value means that the argument is not used. The inputs must be set in consecutive order starting from inArg1. Setting the inputs in non-consecutive order (e.g. leaving inArg2 but setting the inArg3 input) will result in a DomainError.

outResult1 to outResult4 outputs are retrieving the object returned by the Python code from the function. When the function returns a Tuple it is unpacked and its items are assigned in order to the outResult1 to outResult4 outputs. When the returned tuple contains less than 4 items the remaining filter outputs are set to None. Attempt to return more than 4 items in a tuple will result in a RuntimeError. When the function returns an object different than Tuple it is assigned to the outResult1 output and the remaining outputs are set to None.

Data conversion

All data inputs and outputs caring function call arguments and results are of special built-in type PythonObject. This type can hold some of the Pythons built-in types and provides implicit conversion to and from vision program types. As a result it is possible to simply connect data of arbitrary supported types to the Python_CallFunction argument inputs to pass such data to the Python environment and to connect a result object from the arguments output to an input of anticipated type to convert the Python objects back to the vision program types.

The following Python built-in types and their convertible vision program equivalents are supported:

Python type	Program type(s)
Boolean (bool)	Bool
Integer (int)	Integer, Long
Real (float)	Real, Double
String (text)	String
List of Boolean objects	BoolArray
List of Integer objects	IntegerArray, LongArray
List of Real objects1	RealArray, DoubleArray
List of String objects	StringArray
None	See Conditional Data

Connecting data of one of the above program types to the argument input will create an object of equivalent Python type that will be passed as the function argument.

When connecting data from the results output the type returned by the Python code must be anticipated and a connection must be made to an input of equivalent program type. Returning a type not listed in the above table from the Python function will result in a DomainError. When the object returned by the Python function is not compatible with the connected program type a DomainError will be raised at the connected inputs filter at program runtime. Similar conversion DomainError will be raised when a numeric value returned from the Python code is out of the supported range of the destination program type.

Special care must be taken when returning list objects from the function call. Python allows to mix object types in the list items, but in order to convert such list to a program array all its items must be of the same type. Attempt to return a list with items of mixed types will result in a DomainError.

¹) When returning a list with mixed Real and Integer objects from a python function the entire list is considered to be a list of Reals and implicitly converted to real arrays for the vision application.

Conditional Data

By default the argument inputs and result outputs do not support conditional data. Connecting conditional types on argument inputs will result in a conditional execution of the filter and returning empty data from the result outputs will fail to convert to program data.

To pass a conditional data into the Python function the ConditionalToPythonObject filter must be used first on a connection to the argument input. Non-Nil data will be converted without change, as described above. Nil value from the program will be passed to the Python function argument as a None object and must be handled by the Python code accordingly.

To retrieve a conditional data from the function the PythonObjectToConditional filter must be used on a connection from the result output. When the Python function return a None object (or passes a None object as a returned tuple item) it will be converted to Nil on a conditional output of the PythonObjectToConditional. Other than None objects will be converted without change, as described above and returned as non-Nil conditional data.

Logging

This filter, on initialization, will install a handler to the standard Python logging facilities that will redirect the logging messages from the Python code to the FabImage Studio console and log file. For example, calling below function using the filter:

import logging

def myTestFunction():
    logging.getLogger().warning("This is a warning log!")

will result in the following log record in the console:

10:30:00 | Warning | [Python] This is a warning log!

The "[Python]" prefix is added by default by the handlers formatter, which can be customized from the Python script (e.g. at the script initialization) by modifying the properties of a handler identified by the name "FISLogHandler". For example:

logging.getHandlerByName("FISLogHandler").setFormatter(logging.Formatter('This is a %(levelname)s log from a Python script: "%(message)s"'))

Logging level is left on the default settings and can also be modified from the Python script during the initialization. For example, to see the log messages at info level:

logging.getLogger().setLevel(logging.INFO)

Logging messages are redirected to the console only from the thread that performs the function call from the filter and only during the filter execution. Log messages sent from the threads started separately in the python scripts will not be redirected.

Exception handling

All not handled exceptions thrown by the Python code during the function call will result in the filter causing a RuntimeError with the description formatted from the Python exception.

Failure to load the Python script file (module) on filters first execution, even as a result of a not handled exception in the top-level initialization code, will result in the filter causing an IOError.

List of possible exceptions:

Error type	Description
DomainError	Empty Python function name specified.
DomainError	Empty Python module file path specified.
DomainError	Python function call arguments provided in a non-consecutive way.
RuntimeError	Too many result arguments returned by the Python function call.