You are here: Start » Getting Started » Running and Analysing Programs
Running and Analysing Programs
One of the best ways to learn FabImage Studio quickly is to study the example projects that come with the application. The File » Open Example... command is a shortcut to the location they are stored in. The list of available projects is also available in the Program Examples section.
When a project is loaded you can run it simply by clicking the Run button on the Application Toolbar or by pressing F5. This will start continuous program execution; results will be visible in the Data Preview panels. You can also run the program iteration by iteration by clicking Iterate or pressing F6.
When a project is loaded from a file or when new filters (tools) are added, the filter instances are displayed subdued. They become highlighted after they are invoked (executed). It is also possible to invoke individual filters one by one by clicking Step Over or Step Into , or by pressing F10 or F11 respectively. The difference between Step Over and Step Into is related to macrofilters – the former invokes entire macrofilters, whereas the latter invokes individual filters inside.
Once the filters (tools) are executed, their output data can be displayed in the Data Previews panels. To display a value of a particular output, just drag and drop from the port of the filter to a Data Preview panel. Remember to press and hold left mouse button during entire movement from the port to the preview. Multiple data can be often displayed in multiple layers of a single preview. This is useful especially for displaying geometrical primitives, paths or regions over images.
In bigger projects you will also find it useful to switch between three different layouts, which can be created to visualize different stages of the algorithm, as well as to the automatic layout mode, which is very useful for interactive analysis of individual filters:
Data displayed in the Data Preview panels can be analyzed interactively. There are different tools for different types of data available in the main window toolbar. These tools depend on currently selected preview which is marked with a yellow border when window is docked.
For the most common Image type the Data Preview window has the following appearance:
Additionally, there are several usability enhancements:
- Mouse Wheel – zooms in or out the image.
- 3rd Mouse Button + Drag – moves the view.
- Right Click – opens a context menu and allows to save the view to an image file.
While analyzing your application, it is useful to switch to the Results control available near the bottom of the screen. If you cannot see it, you need to enable it through View » Results.Upon clicking on a filter or checking a group of filters, a table with appropriate data will be displayed.
Displays the name of the selected filter or filters as well as some of their outputs, including diagnostic ones (if the Diagnostic Mode is enabled).
Displays the type of data returned by the given output.
Displays the type of data returned by the given output in the last iteration.
If the given output can be subject to a Pass/Fail inspection (so any output returning a numerical value but also such types as String or Bool), you may check the box visible in this column in the corresponding row, thus enabling the following few columns. The application must be stopped for it to be allowed.
In this parser you can insert a simple formula describing the criterion for a Pass (hover the cursor over the question mark to see examples). The application must be stopped for it to be allowed.
- Pass/Fail status
A green or red dot will appear signifying whether the criterion described under Limits has been met or not.
- Pass/Fail status statistics
Displays the number of iterations in which this particular output has so far met the criterion described under Limits.
If the given output can be subject to a mathematical analysis, you may check the box visible in this column in the corresponding row in order to enable the following few statistics. The application must be stopped for that to be allowed.
Displays the lowest value so far returned.
Displays the highest value so far returned.
Displays the mean value of those so far returned.
Displays the median value of those so far returned.
- Standard Deviation
Displays the standard deviation value of those so far returned.
Below you can see a modified Fiducial Markers example. Two filters display the application of the Results control.
After performing ten iterations on equally-sized images, we can see that:
- The outImage.Width Integer output returned True on all ten iterations (because the value was the same and the parser allowed it to be either the same or higher).
- The outImage.Height Integer output returned False on all ten iterations (because the value was never lower and the parser only allowed it to be lower).
- The outFileName String output returned True on one out of ten iterations (because the number within the name kept increasing so it did not stay the same).
Note how next to the parsers applied to numerical values there is a blue question mark . If you hover your cursor over it, you will see suggestions of formulas that you can use within the parser. These suggestions are not available with non-numerical types of data. Also note how after executing the program, new out...Status outputs became available in the filter (they are shown in the preview window above the Results control).
Below you can see the file name being verified again, this time as the Bool type output outFileNameIs001png. The Results control shows the identical effect to that of the outFileName String output above—except that this time the Limits parser can only be set either to True or to False.
Except for the most simple applications, programs in FabImage Studio are composed of many so called macrofilters (subprograms). Instances of macrofilters in the Program Editor can be recognized through the icon which depicts several blue bars. Double clicking on an instance opens the macrofilter in the Program Editor.
There are two other ways of browsing macrofilters. One is through the Macrofilter Navigator at the top of the Program Editor, which displays instances of macrofilters (how they are actually used and nested in the program). Another is through the Project Explorer, which displays definitions of macrofilters (a plain list of all macrofilters from which the user can create instances by dragging and dropping them to the Program Editor; double clicking on an item here opens the macrofilter in the Program Editor).
Definitions of macrofilters correspond to definitions of functions in C++, whereas instances of macrofilters correspond to function calls on a call-stack. Unlike the C++, there is no recurrence in FabImage Studio and each macrofilter definition has a constant and finite number of instances. Thus, we actually have a static call-tree instead of a dynamic call-stack. This makes program understanding and debugging much easier.
Analysing Operation of a Single Macrofilter
The Iterate Current Macro command can be very useful when you want to focus on a single macrofilter in a program with many macrofilters. It executes the whole program and pauses each time when it comes to the end of the currently selected macrofilter instance.
The Iterate Current Macro command is very similar to setting a breakpoint at the end of some function in a C++ debugger.
More information about program iteration is available in Testing and Debugging.
Pausing the program execution in any algorithm location is a fundamental technique while debugging program in any programming language. In FabImage Studio such a pausing can be done with breakpoints in the program editor. Breakpoints are visualized with red circle in the left margin of the program editor and a line next to it:
Breakpoints can be activated (toggled) in several ways:
- by clicking appropriate locations within the program editor margin,
- through the context menu of the filter blocks or macrofilter outputs block,
- with F9 shortcut on selected filter block or macrofilter outputs block.
You can read more about Breakpoints in Testing and Debugging.
Knowing Where You Are
At each moment of a program execution you can see on the Application Status Bar which macrofilter instance is currently being executed. This is called a call-stack, because not only the name of the macrofilter is displayed, but also all the names of the parent macrofilters.
The current position of the execution process is also marked with a green line or frame in the Program Editor:
|Previous: Introduction to Data Flow Programming||Next: Acquiring Images|