You are here: Start » User Interface » Creating Macrofilters

Creating Macrofilters

Introduction

Macrofilters play an important role in developing bigger programs. They are subprograms providing a means to isolate sequences of filters and re-use them in other places of the program. After creating a macrofilter you can create its instances. From outside an instance looks like a regular filter, but by double-clicking on it you navigate inside and you can see its internal structure.

When you create a new project, it contains exactly one macrofilter, named "Main". This is the top level macrofilter from which the program execution will start. Further macrofilters can be added by extracting them from existing filters or by creating them in the Project Explorer window.

Extracting Macrofilters (The Quick Way)

The most straightforward way of creating a macrofilter is by extracting it from several filters contained in an existing macrofilter. This is done by selecting several filters in the Program Editor and choosing the Extract Step... command from the context menu, as depicted in the picture below:

Extracting a macrofilter from three existing filters.

After completing this operation, a new macrofilter definition is created and the previously selected filters are replaced with an instance of this macrofilter. Now, additional inputs and outputs of the new macrofilter can be created by dragging and dropping connections over the new macrofilter instance.

Remark: The "Extract Task (loop)..." command creates a new Task macrofilter which should be used only in special cases. Execution of the Task macrofilter is more complex than execution of the Step macrofilter. Usage of the Task macrofilter for reducing macrofilter complexity may be inappropriate. For more details please read section about Task macrofilters.

Defining the Interface

Being inside of a macrofilter other than "Main" you can see two special blocks: the Macrofilter Inputs and the Macrofilter Outputs. The context menus of these blocks allow to add new inputs or outputs. Another method of adding them is by dragging connections and dropping them over these blocks.

Adding a new output using the context menu of the Macrofilter Outputs block.

Adding a new output by dragging and dropping a connection.

Before the new port is created you need to provide at least its name and type:

Defining a port of a macrofilter.

NOTE: Names of macrofilter inputs and outputs should be clear and meaningful. Names of inputs always start with "in", while names of outputs always start with "out".

Adding Registers

The context menus of macrofilter input and output blocks also contain a command for adding macrofilter registers, Add Macrofilter Register.... This is an advanced feature.

Creating Macrofilters in the Project Explorer

All macrofilter definitions that are contained in the current project can be displayed in the Project Explorer window (by default it is behind the Toolbox on a tab page). Using this control, the user can create or edit macrofilters, but it also acts as a filter catalog from which instances can be created by dragging and dropping the items into the Program Editor.

To create a new macrofilter in the Project Explorer click the Create New Macrofilter... button. A new window will appear allowing you to select the name and structure of the new macrofilter.

Please note, that due to their special use Worker Tasks can only be created in the Project Explorer. For more information on Worker Tasks please refer to Macrofilters article.

Adding Macrofilters in the Project Explorer.

Selecting the name and the structure of a new macrofilter.

Copying Macrofilters

When copying macrofilters in the Program Editor window, you can only create their new instances: modifying one instance will inevitably affect all the others. In order to duplicate the definitions (create brand-new copies) of old macrofilters as independent entities that you will be able to modify separately, you need to do it inside the Project Explorer window.

Copying macrofilters in the Project Explorer - creating new definitions.

Copying macrofilters in the Program Editor - creating new instances.

Please keep in mind, that regardless of whether you copy macrofilters in the Program Editor or the Project Explorer, with other macrofilters nested inside, no new definitions of nested macrofilters will be created.

1. When copying the parent macrofilter (first nest level) in the Program Editor, the number of instances of nested (child) macrofilters will not change.

2. When copying the parent macrofilter (first nest level) in the Project Explorer, new instances of nested (child) macrofilters will be created.

If you want to create a new copy of the whole macrofilter tree (copy of all definitions) you will have to copy each macrofilter separately, starting with the most nested one.

The StartUp Program

It is sometimes useful to have several programs in a single project. The most common scenarios are:

  • When some more complex data, e.g. custom OCR models or calibrated reference images, need to be prepared in a separate program.
  • When it is convenient to have multiple versions of a single program customized for different installations.
  • When the highest reliability is important and sets of automated tests need to be performed on recorded images.

In FabImage Studio a program can be any Worker Task macrofilter. The list of all macrofilters fulfilling this criterion can be seen in the StartUp Macrofilter combo box on the Application Toolbar. This control makes it possible to choose the program that will be run. The related macrofilter will be displayed in the Project Explorer with the bold font.

The StartUp Program Combo Box.

Macrofilter Guidelines

Macrofilters organize big projects, but it is responsibility of the user to make this organization clean and effective. When a project grows, especially under the pressure of time, it is easy to forget this and create programs that are difficult to understand and maintain. To avoid this, please follow the following guidelines:

  1. Macrofilters should not be too big. For program clarity they should typically consist of 3-15 filters. If you macrofilters have more than 20, it is certainly going to be cause trouble.
  2. Each macrofilter should have a clear and single function well reflected in its name. It is recommended to create macrofilters as tools that could possibly be used in many different projects.
  3. Macrofilter names do not affect the program execution, but they are very important for effective maintenance. Choose precise and unambiguous English names. Follow the verb + noun naming convention whenever possible and avoid abbreviations (this applies also to names of macrofilter ports).
  4. Do not mix data analysis with things like communication or visualization in a single macrofilter. These should be separated. If data visualization is needed for HMI, compute results in one macrofilter and then prepare the visualization in another. This will make the data flow more clear.
  5. During project development it is very common that the initial program structure becomes inappropriate for what has been added during development, or that it becomes too complicated and unclear. This is when you should consider REFACTORING, i.e. redesigning the program structure, boundaries of macrofilters and revising any complicated sequences of filters. We strongly recommend considering refactoring as a routine part of the job.
Previous: Connecting and Configuring Filters Next: Creating Models for Template Matching