Managing Projects with Project Explorer
Project Explorer is a window displaying elements which are contained in the currently opened project:
- Macrofilters (definitions)
- Global Parameters
- User Types
- User Filter libraries
Its main goal is to provide a single place to browse, add, remove, rename or open the items, which are grouped into categories in the same way as the filters in the Filter Catalog. A category may correspond to a standard module or to a module of a User Filter library. There is also one special category, Attachments, which appears when the user adds an external file to the project (it might be for example a text document with a piece of documentation).
As described in Running and Analysing Programs, there are two ways of navigating through the existing macrofilters. One of them is with the Project Explorer window, which displays definitions of macrofilters, not the instances. After double-clicking on a macrofilter in the Project Explorer, however, a macrofilter instance is opened in the Program Editor. As one macrofilter definition can have zero, one or many instances. Some special rules apply to which of the instances it is:
- If possible, the most recently executed instance is opened.
- If no instance has been executed yet, the most recently created one is opened.
- If there are no instances at all the "ghost instance" is presented, which allows editing the macrofilter, but will never have any data on the output ports.
Macrofilter counter shows how many times a given macrofilter is used in the program.
ADVANCED NOTE: If a macrofilter X is used in a macrofilter Y and there are multiple instances of the macrofilter Y, we still consider macrofilter X being used once. Number of uses is not the same as number of instances.
If some value is used many times in several different places of a program then it should be turned into a global parameter. Otherwise, consecutive changes to the value will require the error-prone manual process of finding and changing all the occurrences. It is also advisable to use global parameters to clearly distinguish the most important values from the project specification – for example the expected dimensions and tolerances. This will make a program much easier to maintain in future.
In Adaptive Vision Studio global parameters belong to specific modules and are managed in the Project Explorer. To create one, click the Create New Global Parameter... button and then a dialog box will appear where you will provide the name, the type and the value of the new item. After a global parameter is created it can be dragged-and-dropped on filter inputs and appropriate connections will be created with a visual label displaying the name of the parameter.
Global parameters contained in a project can also be edited in the Properties window after being selected in the Project Explorer or in the Program Editor.
Since version 4.11 it is possible to create and manage global parameters with dedicated filters: WriteParameter and ReadParameter. They are available in the Program Structure category of the Toolbox.
While adding a new input, "Select Global Parameter" window is displayed:
Thanks to these filters you can easily read or write the values of global parameters anywhere in your algorithm. In order to facilitate development the icon of the global parameter has different appearance depending on whether it is overwritten somewhere in the program. The color of the icon will be red then so that you will know that this value may change during the execution of your application.
To see how Global Parameters work in practice, check out our official example: HMI Handling Events.Remarks:
- Connected filters are not re-executed after the global parameter is changed. This is due to the fact, that many filters in different parts of the program can be connected to one global parameters. Re-executing all of them could cause unexpected non-local program state changes and thus is forbidden.
- Do NOT use writable global parameters unless you really must. In most cases data should be passed between filters with explicit connections, even if there are a lot of them. Writable global parameters should be used only for some very specific tasks, most notably for configuration parameters that may be dynamically loaded during program execution and for high level program statistics that may be manipulated through the HMI (like the last defect time).
When a project grows above 10-20 macrofilters it might be appropriate to divide it into several separate modules, each of which would correspond to some logical part. It is advisable to create separate modules for things like i/o communication, configuration management or for automated unit testing. Macrofilters and global variables will be then grouped in a logical way and it will be easier to browse them.
Modules are also sometimes called "libraries of macrofilters". This is because they provide a means to develop sets of common user's tools that can be used in many different projects. This might be very handy for users who specialize in specific market areas and who find some standard tasks appearing again and again.
To create a module, click the Create New module... button and then a dialog box will appear. In there you specify the location and name of the module. The path may be absolute or relative. Modules are saved with extension .avlib. Saving and updating the module files happens when the containing program is saved.
After creating a module you may move already existing macrofilters into the module by dragging them onto the module in Project Explorer. Clicking the Create New Macrofilter... button allows you to create a new macrofilter with the given name. During that you can access Advanced options by clicking the appropriate button. There you can specify the parent module and access to the macrofilter. Access can be either private or public. Private macrofilters cannot be directly used outside its module. You can also provide a tooltip (description) for the macrofilter. This will show up in the properties section of an instance and when hovered over in the Project Explorer. Tooltip should describe the macrofilter's purpose and be concise. They are especially important when creating an
Right clicking a macrofilter and selecting Edit properties... allows to modify their properties, including access, after their creation.
The image below shows a structure of an example program. The macrofilters have been grouped into two Modules. Module FindDefects has macrofilters related to defect detection and a global parameter used by the macrofilters. Notice how the ProcessImage macrofilter is grayed out. It indicates it is a private macrofilter (here it is used by FindShapeDefects). ProcessImage cannot be used outside its module.
The other module has macrofilters related to showing and storing the results of the inspection.
Here are some guidelines on how to use modules in such situations:
- Create a separate module for each set of related, standard macrofilters.
- Give each module a unique and clear name.
- Use the English language and follow the same naming conventions as in the native filters.
- Create the common macrofilters in such a way, that they do not have to be modified between different projects and only the values of their parameters have to be adapted.
- If some of the macrofilters are intended as implementation only (not to be used from other modules), mark them as private.
It is important to note that modules containing filters interfacing with the HMI should not be shared between programs. Every filter port connected to the HMI has a unique identifier. Those identifiers vary between programs - ports of the same filter in different programs will have different identifiers.
Generally it is a good practice to create a separate module for all things related to the HMI. That way every other module can be shared between programs without any problems.
If you want to use a module which had been created before click the Import Existing Module... . This will open a window in which you can select modules to add. Now the path to the module will be linked to the project. Similarly to creating a new module you can choose whether the path to it will be relative or absolute.
Remember that modules are separate files and as such can be modified externally. This is especially important with modules which are shared between multiple projects at the same time.
Sometimes users would like to hide the contents of some of their macrofilter to protect them against unauthorized access. They can do this by placing them inside a module and locking it. To do this it is necessary to right click on the module in the Project Explorer and select Lock Module option. User will be then prompted to provide a password for this specific module.
After creating password user should see an open lock icon next to the module name in the Project Explorer. You can work with this module exactly the same way as with any other module. What distinguishes it from other modules is that it can be locked, which will make checking implementation of macrofilters included inside not possible. Such modules will be similar to filters in this matter. This operation will also encrypt the avlib file. It is important to lock the module every time you finish working on it.
In order to unlock a module you need to select the Unlock Module option in the ProjectExplorer and enter the correct password. To completely remove module locking feature from a selected module, use the Remove Module Lock option.
|Previous: Performing General Calculations||Next: Keyboard Shortcuts|