You are here: Start » Extensibility » Creating User Types

Creating User Types

Adaptive Vision Studio allows for defining user's own types. This can be especially useful when it is needed to pass multiple parameters conveniently throughout your application or when creating User Filters.

The user can define a structure with named fields of specified type as well as his own enumeration types (depicting several fixed options).

For example, the user can define a structure which contains such parameters as: width, height, value and position in a single place. Also, the user can define named program states by defining an enumeration type with options: Start, Stop, Error, Pause, etc.

Usage

In an example project information such as: part name, part width, part height and its tolerance is needed for checking product quality. All this data must be accessed during image analysis.

This problem can be solved without user defined types, but creating a lot of connections can make the program structure too complex. Images below show a comparison between working with a user's structure and passing multiple values as separate parameters.

A solution without user types – more connections, less readable.

A solution with user types – fewer connections, more readable.

Creating User Types in Program

To create your own type, save your project, open the main AVCODE file (e.g. with Notepad) and at the beginning of the file enter a type declaration:

struct Part
{
	String 	Name
	Real	Width
	Real	Height
	Real	Tolerance
}

Save your file and reload the project. Now the newly created type can be used as any other type in Adaptive Vision Studio.

After reloading the project the custom made type is available in Adaptive Vision Studio.

Also custom enumeration types can be added. Such types can represent a list of predefined options. To create a custom enumeration type add the code below to the top of your AVCODE file.

enum PartType
{
	Nut
	Bolt
	Screw
	Hook
	Fastener
}

Custom enumeration types can be used like other types.

Creating User Types in User Filters

When creating a User Filter add to the project an AVTYPE file with a user types description. The file should contain type descriptions in a format the same like the one used for creating User Types in a program (see the section above).

In your C++ code declare structures/enums with the same field types, names and order. If you create an enum then you can start using this type in your project instantly. For structures you must provide ReadData and WriteData functions overrides for serialization and deserialization.

In these functions you should serialize/deserialize all fields of your structure in the same order you declared them in the type definition file.

To support structure Part from the previous example in your source code you should add:

Structure declaration:

struct Part
{
	atl::String 	Name;
	float			Width;
	float			Height;
	float			Tolerance;
};

Structure deserialization function:

void ReadData(atl::BinaryReader& reader, Part& outPart)
{
	ReadData(reader, outPart.Name);
	ReadData(reader, outPart.Width);
	ReadData(reader, outPart.Height);
	ReadData(reader, outPart.Tolerance);
}

Structure serialization function:

void WriteData(atl::BinaryWriter& writer, const Part& inValue)
{
	WriteData(writer, inValue.Name);
	WriteData(writer, inValue.Width);
	WriteData(writer, inValue.Height);
	WriteData(writer, inValue.Tolerance);
}

Enum declaration:

enum PartType
{
	Nut,
	Bolt,
	Screw,
	Hook,
	Fastener
};

It is not required for custom serialization / deserialization of enum types.

The file with user type definitions has to be registered. This is done in the RegisterUserObjects class constructor which is defined at the bottom of the user filter code. You need to add there a registration of your file as RegisterTypeDefinitionFile("fileName.avtype"). The file name is a path to your type definitions file. The path should be absolute or relative to the User Filter dll file.

You can use types defined in a User Filter library in this User Filters library as well as in all other modules of the project. If you want to use the same type in multiple User Filters libraries then you should declare these types in each User Filters library.

The following Example Program: "User Filter With User Defined Types" demonstrates usage of User Types in User Filters.

Accessing Structure Fields

To access information contained in a user structure its fields must be expanded. The picture below shows how to expand a type on an input of a macrofilter.

User type fields expanded on a macrofilter's inputs.

User type objects can be created with the CopyObject filter.

User type fields expanded on the CopyObject input.

User defined types can also be accessed with formulas.

Computation using the user defined type.

Saving User Types

User defined types work in Adaptive Vision Studio, so filters such SaveObject, WriteToString, WriteToXmlNode or TcpIp_WriteObject can be used to store and transfer user data.

Related Program Examples

User defined types can be studied in the following Program Examples: Brick Destroy, User Defined Types, User Filter With User Defined Types.

Previous: Debugging User Filters

Next: Designing HMI