nexxT.interface.Filters module

This module defines the FilterState and Filter classes of the nexxT interface.

class nexxT.interface.Filters.Filter(dynInPortsSupported, dynOutPortsSupported, environment)

Bases: QObject

Note

Import this class with from nexxT.interface import Filter.

This class is the base class for defining a nexxT filter. A minimal nexxT filter class looks like this:

class SimpleStaticFilter(Filter):

    def __init__(self, environment):
        super().__init__(False, False, environment)
        pc = self.propertyCollection()
        self.sample_property = pc.getProperty("sample_property", 0.1, "a property for demonstration purpose")
        self.inPort = self.addStaticInputPort("inPort")
        self.outPort = self.addStaticOutputPort("outPort")

    def onPortDataChanged(self, inputPort):
        dataSample = inputPort.getData()
        newSample = DataSample.copy(dataSample)
        self.outPort.transmit(dataSample)

The constructor of classes derived from nexxT.interface.Filter must have a single argument environment which is passed through to this base class. It configures dynamic port usage with the two boolean flags. In the constructor, the filter can define and query properties and create static ports.

The onPortDataChanged is called whenever new data arrives on an input port. In the example above, a copy of the original data sample is returned.

Note

Usually, nexxT is using the wrapped C++ class instead of the python version. In python there are no differences between the wrapped C++ class and this python class. The C++ interface is defined in nexxT::Filter

__init__(dynInPortsSupported, dynOutPortsSupported, environment)

Filter Constructor.

Parameters:

• dynInPortsSupported – Flag whether this filter supports dynamic input ports

• dynOutPortsSupported – Flag whether this filter supports dynamic output ports

• environment – FilterEnvironment instance which shall be passed through from the filter constructor.

addStaticInputPort(name, queueSizeSamples=1, queueSizeSeconds=None)

Shortcut for generating a static input port and adding it to the filter. See also nexxT.interface.Ports.InputPort()

Parameters:

• name – The name of the input port

• queueSizeSamples – The size of the input queue in samples

• queueSizeSeconds – The size of the input queue in seconds

Returns:

the new port instance

addStaticOutputPort(name)

Shortcut for generating a static output port and adding it to the filter. See also nexxT.interface.Ports.OutputPort()

Parameters:

name – The name of the output port

Returns:

the new port instance

addStaticPort(port)

Register a static port for this filter. Only possible in CONSTRUCTING state.

Parameters:

port – InputPort or OutputPort instance

Returns:

None

environment()

Returns the environment associated with this filter.

Returns:

a FilterEnvironment instance

getDynamicInputPorts()

Get dynamic input ports of this filter. Only possible in and after INITIALIZING state.

Returns:

list of dynamic input ports

getDynamicOutputPorts()

Get dynamic output ports of this filter. Only possible in and after INITIALIZING state.

Returns:

list of dynamic output ports

guiState()

Return the gui state associated with this filter. Note: the gui state shall not be used for properties which are important for data transport, for these cases the propertyCollection() shall be used. Typical gui state variables are: the geometry of a user-managed window, the last directory path used in a file dialog, etc. The gui state might not be initialized during mockup-phase.

Returns:

PropertyCollection instance

onClose()

This function can be overwritten for general de-initialization tasks (e.g. release resources needed to run the filter, close files, etc.). It is the opoosite to onOpen(…).

Returns:

None

onDeinit()

This function can be overwritten for performing de-initialization tasks related to dynamic ports. It is the opposite to onInit(…)

Returns:

None

onInit()

This function can be overwritten for performing initialization tasks related to dynamic ports.

Returns:

None

onOpen()

This function can be overwritten for general initialization tasks (e.g. acquire resources needed to run the filter, open files, connecting to services etc.).

Returns:

onPortDataChanged(inputPort)

This function can be overwritten to be notified when new data samples arrive at input ports. For each data sample arrived this function will be called exactly once.

Parameters:

inputPort – the port where the data arrived

Returns:

None

onStart()

This function can be overwritten to reset internal filter state. It is called before loading a new sequence.

Returns:

None

onStop()

Opposite of onStart.

Returns:

None

onSuggestDynamicPorts()

Shall return the suggested dynamic ports of this filter. Prominent example is to return the streams contained in a HDF5 file. Note that it is safe to assume that the instance lives in the GUI thread, when this function is called from the nexxT framework.

Returns:

listOfInputPortNames, listOfOutputPortNames

propertyCollection()

Return the property collection associated with this filter.

Returns:

PropertyCollection instance

removeStaticPort(port)

Remove a static port of this filter. Only possible in CONSTRUCTING state.

Parameters:

port – InputPort or OutputPort instance

Returns:

None

staticMetaObject = PySide6.QtCore.QMetaObject("Filter" inherits "QObject": )

class nexxT.interface.Filters.FilterState

Bases: object

Note

Import this class with from nexxT.interface import FilterState.

This class defines an enum for the filter states. For reference, the filter’s lifecycle state diagram is shown here:

static state2str(state)

converts a state integer to the corresponding string

Parameters:

state – the state integer

Returns:

string

class nexxT.interface.Filters.FilterSurrogate(dllUrls, name)

Bases: object

Note

Import this class with from nexxT.interface import FilterSurrogate.

This class acts as a surrogate to reference a filter from a DLL/shared object plugin from within python. It’s main purpose is the ability to announce these filters using python entry points. For this, create an instance of this class in one of your modules and refer to it by a ‘nexxT.filters’ entry point. Example:

from distutils.core import setup
setup( # ...
    'nexxT.filters' : [
         'examples.framework.CameraGrabber = nexxT.examples:CameraGrabber',
    ])

The surrogate creation of CameraGrabber is performed in nexxT.examples:

# SPDX-License-Identifier: Apache-2.0
# Copyright (C) 2020 ifm electronic gmbh
#
# THE PROGRAM IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
#

"""
define FilterSurrogates for binary filters.
"""

from pathlib import Path
import os
from nexxT.interface import FilterSurrogate
if os.environ.get("READTHEDOCS", None) is None:
    from nexxT.Qt import QtMultimedia # needed to load corresponding DLL before loading the nexxT plugin

AviReader = FilterSurrogate(
    "binary://" + str((Path(__file__).parent.parent / "tests" /
                       "binary" / "${NEXXT_PLATFORM}" / "${NEXXT_VARIANT}" / "test_plugins").absolute()),
    "VideoPlaybackDevice"
)
"""
Filter surrogate for the VideoPlaybackDevice class which is defined in a packaged shared object "test_plugins".
"""

CameraGrabber = FilterSurrogate(
    "binary://" + str((Path(__file__).parent.parent / "tests" /
                       "binary" / "${NEXXT_PLATFORM}" / "${NEXXT_VARIANT}" / "test_plugins").absolute()),
    "CameraGrabber"
)
"""
Filter surrogate for the CameraGrabber class which is defined in a packaged shared object "test_plugins".
"""

__init__(dllUrls, name)

Create a FilterSurrogate instance.

Parameters:

• dllUrls – might be (1) a dictionary mapping variant names to URLs, variant names are usually “nonopt” and “release” or (2) a url string which will be mapped to the release variant Note that URLs for binary libraries (DLL’s or shared objects) are of the form “binary://<absolute-path-to-dll>”. The absolute path might contain variables like ${NEXXT_PLATFORM} or ${NEXXT_VARIANT}.

• name – the name of the filter class or factory function

dllUrl(variant)

returns the absolute path of the optimzed dll/shared object

Parameters:

variant – the variant for which the filter is needed, given as a string.

name()

returns the name of the filter class