7 ObjectTypes for the Vision System in General

7.1 VisionSystemType

This ObjectType defines the representation of a machine vision system. Figure 8 shows the hierarchical structure and details of the composition. It is formally defined in Table 10.

Instances of this ObjectType provide a general communication interface for a machine vision system. This interface makes it possible to interact with this system independent of the knowledge of the internal structure and the underlying processes of the machine vision system.

System behavior is modeled with a mandatory hierarchical finite state machine.

VisionSystemType contains four optional management objects, RecipeManagement, ConfigurationManagement, ResultManagement, and SafetyStateManagement. All of these provide access to the exposed functionality of the machine vision system.

ConfigurationManagement providesConfigurationManagement provides methods and properties required for Section 7.2.

RecipeManagement provides functionality to add, remove, prepare, and retrieve vision system recipes. RecipeManagementType is described in Section 7.5.

ResultManagement provides methods and properties necessary for managing the results. ResultManagementType is described in Section 7.10.

SafetyStateManagement provides functionality to inform the vision system about the change of an external safety state. SafetyStateManagementType is described in Section 7.13.

StateMachine provides information about the current state of the vision system and methods for controlling it. VisionStateMachineType is defined in Section 8.2.

DiagnosticLevel specifies the threshold for the severity of diagnostic messages to be generated by the server. More information can be found in Section 11.3.

SystemState represents the system state in terms of the SEMI E10 standard. More information can be found in Section11.6.

7.2 ConfigurationManagementType

7.2.1 Overview

This ObjectType defines the representation of the machine vision system configuration management. Figure 9 shows the hierarchical structure and details of the composition. It is formally defined in Table 11.

Even supposedly identical vision systems will differ in some details. In order to produce the same results the vision systems have to be adjusted individually e.g. calibrated. Within this document, the set of all parameters that are needed to get the system working is called a configuration. Configurations can be used to align different vision systems that have the same capabilities, so that these systems produce the same results for the same recipes.

Instances of this ObjectType handle all configurations that are exposed by the system. Only one configuration can be active at a time. This active configuration affects all recipes used in the machine vision system. The configurations can optionally also be exposed in a folder, in order to provide access to the client.

Configurations are handled as files, meta data of configurations can be directly viewed but not changed by the client. The interpretation of the configuration’s content is not part of this specification.

ConfigurationTransfer is an instance of the ConfigurationTransferType defined in Section 7.4 and it is used to transfer the contents of a configuration by the temporary file transfer method defined in OPC 10000-5, Annex C.4.

Configurations is an instance of the ConfigurationFolderType and it is used to organize variables of DataType ConfigurationDataType which is defined in Section 12.9. If the server chooses to expose configuration information in the Address Space, the Object may contain the set of all configurations available on the system. This is implementation-defined. If a server does not expose configuration information in the Address Space, this Object is expected to be non-existent.

The DataTypes used in the ConfigurationManagementType are defined in OPC 10000-5 and in Section 11.6 of this specification.

7.2.2 ConfigurationManagementType methods

7.2.2.1 AddConfiguration

7.2.2.1.1 Overview

This method is used to add a configuration to the configuration management of the vision system. It concerns itself only with the metadata of the configuration, the actual content is transferred by an object of ConfigurationTransferType which is defined in Section 7.4.

The intended behavior of this method for different input arguments is described in the following subsections.

Signature

	AddConfiguration ([in]	ConfigurationIdDataType	externalId[out]	ConfigurationIdDataType	internalId[out]	NodeId	configuration[out]	Boolean	transferRequired[out]	Int32	error);

7.2.2.1.2 New ExternalId

If AddConfiguration is called with an ExternalId not yet existing in the configuration management of the vision system, it is expected that the vision system creates an appropriate management structure with an InternalId which is unique on the system. The server then returns this InternalId.

If the server chooses to represent all or selected configurations in the Address Space and if the new configuration matches the current selection criteria, the server shall create a new entry in the Configurations folder in the Address Space.

The method will return TRUE in the TransferRequired argument. Since the ExternalId does not yet exist in the configuration management of the vision system, it is expected the configuration does not yet exist either in the local configuration storage of the vision system, and therefore needs to be transferred.

7.2.2.1.3 Identically Existing ExternalId with identical configuration

If AddConfiguration is called with an ExternalId already existing in the configuration management of the vision system, it is expected that the vision system checks whether an identical version of the configuration already exists, provided that the content of the ExternalId allows for such a check. (A way to perform this comparison without having to download the binary content first is offered by the optional hash value in the ExternalId. The idea is that the client computes a hash for the contents of the recipe and passes that hash in the ExternalId. The server can then check this hash against a hash transmitted earlier, or it can compute a hash by itself over the contents of the recipe currently stored on the vision system side. For this procedure, the server needs to know the hash algorithm used by the client which can be transmitted in the hashAlgorithm member of the ExternalId).

Note that the method has no way of checking this with the actual configuration content which is not yet known to the vision system.

The method will return FALSE in the TransferRequired argument if the method comes to the conclusion that the configuration already exists with identical content on the vision system. Note that the result is not binding for the client who may decide to transfer the configuration content anyway.

If the server represents configurations in the Address Space, no new entry shall be created in the configurations folder.

7.2.2.1.4 Identically Existing ExternalId with different configuration

If AddConfiguration comes to the conclusion that the content of the configuration to be transferred is different from the content already existing for this ExternalId, it shall return TRUE in the TransferRequired argument.

The behavior with respect to the management of the configuration metadata and configuration content is entirely application-defined. The vision system may decide to create a new management structure and add the configuration content to the local configuration store, or it may decide to re-use the existing ExternalId and overwrite the configuration content. In any case, the vision system shall create a new, system-wide unique InternalId for this configuration.

If the server chooses to represent configurations in the Address Space, the behavior with respect to these objects should mirror the behavior of the vision system in its internal configuration management.

7.2.2.1.5 Local creation or editing of configurations

This is not, strictly speaking, a use case of the method AddConfiguration, but results are comparable, and therefore the use case is described here.

If a configuration is created locally on the vision system or is loaded onto the vision system by a different interface than the OPC Machine Vision interface, i.e. the configuration is added without using method AddConfiguration, then this configuration shall have a system-wide unique InternalId, just like a configuration added through the method.

If an existing configuration which was uploaded to the vision system through the method AddConfiguration, is locally changed, the ExternalId shall be removed from the changed version and it shall receive a new system-wide unique InternalId so that the two configurations cannot be confused. The vision system may record the history from which configuration it was derived.

If the server exposes configurations in the Address Space and if the locally created or edited configurations match the current filter criteria, then they shall be represented as nodes in the Configurations folder, with their system-wide unique InternalIds, but without ExternalIds.

7.2.2.2 GetConfigurationById

This method is used to get the metadata for one configuration from a number of configurations.

Signature

	GetConfigurationById ([in]	ConfigurationIdDataType	internalId[in]	Int32	timeout[out]	Handle	configurationHandle[out]	ConfigurationDataType	configuration[out]	Int32	error);
	

7.2.2.3 GetConfigurationList

This method is used to get a list of all configurations. It concerns itself only with the metadata of the configuration, the actual content is transferred by a ConfigurationTransferType object.

Signature

	GetConfigurationList ([in]	UInt32	maxResults[in]	UInt32	startIndex[in]	Int32	timeout[out]	Boolean	isComplete[out]	UInt32	resultCount[out]	Handle	configurationHandle[out]	ConfigurationDataType[]	configurationList[out]	Int32	error);
	

The following cases must be considered with the respect to the number of available configurations:

The number of configurations to be returned is less or equal to maxResults; the first call, with startIndex=0, returns isComplete=TRUE, so the client knows that no further calls are necessary. resultCount gives the number of valid elements in the configurationList array.

The number of configurations to be returned is larger than maxResults; the first N calls (N > 0 with N ≤ (number of configurations) divisor MaxResults), with startIndex=(N-1)*maxResults, return isComplete=FALSE, so the client knows that further calls are necessary. The following call returns isComplete=TRUE, so the client knows, no further calls are necessary. resultCount gives the number of valid elements in the configurationList array (on each call, so on the first N calls, this should be maxResults).

7.2.2.4 ReleaseConfigurationHandle

This method is used to inform the server that the client has finished processing a given configuration set allowing the server to free resources managing this configuration set.

The server should keep the data of the configuration set available for the client until the ReleaseConfigurationHandle method is called or until a timeout given by the client has expired. However, the server is free to release the data at any time, depending on its internal resource management, so the client cannot rely on the data being available. ReleaseConfigurationHandle is merely a hint allowing the server to optimize its internal resource management. For timeout usage, see the description in Section 7.2.2.2.

Signature

	ReleaseConfigurationHandle ([in]	Handle	configurationHandle[out]	Int32		error);
	

7.2.2.5 RemoveConfiguration

This method is used to remove a configuration from the configuration management of the vision system.

Application Note:

It may be required from a vision system – e.g. in pharmaceutical or other safety-critical applications – to keep a record of the prior existence of a removed configuration. This may be important in such systems for the meta information of results that were generated while the removed configuration was active. It serves to keep it comprehensible which configurations were available on the vision system

Signature

	RemoveConfiguration ([in]	ConfigurationIdDataType	internalId[out]	Int32	error);
	

7.2.2.6 ActivateConfiguration

This method is used to activate a configuration from the configuration management of the vision system.

Since only a single configuration can be active at any time, this method shall deactivate any other configuration which may currently be active. From that point on until the next call to this method the vision system will conduct its operation according to the settings of the activated configuration.

Note that there is no way to deactivate a configuration except by activating another one to avoid having no active configuration on the system.

Signature

	ActivateConfiguration ([in]	ConfigurationIdDataType	internalId[out]	Int32	error);

7.3 ConfigurationFolderType

This ObjectType is a subtype of the FolderType and is used to organize the configurations of a vision system. Figure 10 shows the hierarchical structure and details of the composition. It is formally defined in Table 24.

Instances of this ObjectType organize all available configurations of the vision system, which the server decides to expose in the Address Space. It may contain no configuration if no configuration is available, if the server does not expose configurations in the Address Space at all, or if no configuration matches the criteria of the server for exposure in the Address Space.

Note that the folder contains only metadata of the configurations, not the actual configuration data of the vision system.

The ConfigurationDataType used in the ConfigurationFolderType is defined in Section 12.12.

7.4 ConfigurationTransferType

7.4.1 Overview

This ObjectType is a subtype of the TemporaryFileTransferType defined in OPC 10000-5 and is used to transfer configuration data as a file.

The ConfigurationTransferType overwrites the Methods GenerateFileForRead and GenerateFileForWrite to specify the concrete type of the generateOptions Parameter of the Methods.

Figure 11 shows the hierarchical structure and details of the composition. It is formally defined in Table 25.

7.4.2 ConfigurationTransferType methods

7.4.2.1 GenerateFileForRead

This method is used to start the read file transaction. A successful call of this method creates a temporary FileType Object with the file content and returns the NodeId of this Object and the file handle to access the Object.

Signature

	GenerateFileForRead ([in]	ConfigurationTransferOptions	generateOptions[out]	NodeId	fileNodeId[out]	UInt32	fileHandle[out]	NodeId	completionStateMachine);
	

7.4.2.2 GenerateFileForWrite

This method is used to start the write file transaction. A successful call of this method creates a temporary FileType Object with the file content and returns the NodeId of this Object and the file handle to access the Object.

Signature

	GenerateFileForWrite ([in]	ConfigurationTransferOptions	generateOptions[out]	NodeId	fileNodeId[out]	UInt32	fileHandle);

7.5 RecipeManagementType

7.5.1 Overview

This ObjectType defines the representation of the machine vision system recipe management (for a conceptual overview of recipe management see Section B.1, for a definition of recipes itself, see Section B.1.2.1). Figure 12 shows the hierarchical structure and details of the composition. It is formally defined in Table 30.

For the actual data transfer, RecipeManagementType makes use of the RecipeTransferType, derived from the TemporaryFileTransferType defined in OPC 10000-5, beginning with version 1.04.

If the server chooses to expose recipe data in the Address Space (see Section B.1.3.3) using the Recipes folder of this type, the FileType object component of the RecipeType objects in this folder can also be used directly for the data transfer.

RecipeTransfer is an instance of the RecipeTransferType defined in Section 7.6 and it is used to transfer the contents of a recipe by the temporary file transfer method defined in OPC 10000-5, Annex C.4.

Recipes is an instance of the RecipeFolderType that organizes RecipeType objects, if the server chooses to expose recipe information in the Address Space. In this case, it may contain the set of all recipes available on the system or a filtered subset, e.g. the set of all currently prepared recipes. This is implementation-defined. If a server does not expose recipe information in the Address Space, this folder is expected to be non-existent.

Products is an instance of the ProductFolderType that organizes ProductDataType variables, if the server chooses to expose product information in the Address Space. In this case, it may contain the set of all products available on the system or a filtered subset, e.g. the set of all products for which recipes are currently prepared. This is implementation-defined. If a server does not expose product information in the Address Space, this folder is expected to be non-existent.

7.5.2 RecipeManagementType Methods

7.5.2.1 AddRecipe

7.5.2.1.1 Overview

This method is used to add a recipe to the recipe management of the vision system. It concerns itself only with the metadata of the recipe, the actual content is transferred by a RecipeTransferType object.

The intended behavior of this method for different input arguments is described in the following subsections.

Signature

	AddRecipe ([in]	RecipeIdExternalDataType	externalId[in]	ProductIdDataType	productId[out]	RecipeIdInternalDataType	internalId[out]	NodeId	recipe[out]	NodeId	product[out]	Boolean	transferRequired[out]	Int32	error);

7.5.2.1.2 New ExternalId

If AddRecipe is called with an ExternalId not yet existing in the recipe management of the vision system, it is expected that the vision system creates an appropriate management structure with an InternalId which is system-wide unique. The server may then return this InternalId, however the client cannot rely on this.

If the server chooses to represent all or selected recipes in the Address Space and if the new recipe matches the current selection critieria, the server shall create a new entry in the Recipes folder in the Address Space.

The method will return TRUE in the TransferRequired argument. Since the ExternalId does not yet exist in the recipe management of the vision system, it is expected that the recipe content does not yet exist either in the local recipe storage of the vision system, and therefore needs to be transferred.

If the ProductId argument is non-empty, it is expected that the vision system creates an appropriate management structure linking the newly created recipe for use with this ProductId. If the ProductId does not yet exist on the vision system, it is expected that it is created.

If the ProductId argument is empty, no such linking takes place. Note that it will not be possible to start a job based on a ProductId not linked to a recipe.

If the server chooses to represent all or selected products in the Address Space and if the ProductId matches the selection criteria, the server shall create a new entry in the Products folder in the Address Space.

If the server chooses to represent all or selected recipes in the Address Space and if the given recipe matches the selection criteria, the ProductId shall be added to the list of products within the appropriate Recipe node.

7.5.2.1.3 Identically Existing ExternalId with identical recipe

If AddRecipe is called with an ExternalId already existing in the recipe management of the vision system, it is expected that the vision system checks whether an identical version of the recipe already exists, provided that the content of the ExternalId allows for such a check (most likely using the hash value).

Note that the method has no way of checking this with the actual recipe content which is not yet known to the vision system.

The method will return FALSE in the TransferRequired argument if the system comes to the conclusion that the recipe already exists with identical content on the vision system. Note that the result is not binding for the client who may decide to transfer the recipe content anyway.

If the server represents recipes in the Address Space, no new entry shall be created in the recipes folder.

The behavior with regard to the ProductId argument is as described above for a new ExternalId. This way of calling AddRecipe can be used to link an existing recipe with another product.

7.5.2.1.4 Identically Existing ExternalId with different recipe

If AddRecipe comes to the conclusion that the content of the recipe to be transferred is different from the content already existing for this ExternalId, it shall return TRUE in the TransferRequired argument.

The behavior with respect to the management of the recipe metadata and recipe content is entirely application-defined. The vision system may decide to create a new management structure with a new InternalId and add the recipe content to the local recipe store, or it may decide to re-use the existing ExternalId and overwrite the recipe content.

If the server chooses to represent recipes in the Address Space, the behavior with respect to these recipe objects should mirror the behavior of the vision system in its internal recipe management

The behavior with regard to the ProductId argument is as described above for a new ExternalId. If the vision system stores both recipe versions, it is implementation-defined whether both are linked to the ProductId or not.

Note that overwriting a recipe shall result in a change to the internalId of the recipe. The change may effect only the hash value, the identifier may remain the same. Historical storage is not required.

7.5.2.1.5 Local creation or editing of recipes

This is not, strictly speaking, a use-case of the method AddRecipe, but results are comparable, therefore, the use-case is described here.

If a recipe is created locally on the vision system or is loaded onto the vision system by a different interface than the OPC Machine Vision interface, i.e. the recipe is added without using the AddRecipe method, then this recipe shall have a system-wide unique InternalId, just like a recipe added through the method.

If an existing recipe which was uploaded to the vision system through AddRecipe is locally changed, the ExternalId shall be removed from the changed version and it shall receive a new system-wide unique InternalId so that the two recipes cannot be confused. Of course the vision system may record the history from which recipe it was derived.

If the server represents recipes in the Address Space and if the locally created or edited recipes match the current filter criteria, then they shall be represented as nodes in the Recipes folder, with their system-wide unique InternalIds, but without ExternalIds.

An important special case is the local editing of an already prepared recipe, described in Section B.1.2.3. Since after local editing, the already prepared recipe is different from before, effectively a new recipe has been prepared by the local editing. Therefore, a new RecipePrepared event shall be generated (see also Section 8.3.8.1).

7.5.2.2 PrepareRecipe

This method is used to prepare a recipe so that it can be used for starting a job on the vision system.

Signature

	PrepareRecipe ([in]	RecipeIdExternalDataType	externalId[in]	RecipeIdInternalDataType	internalIdIn[out]	RecipeIdInternalDataType	internalIdOut[out]	Boolean	isCompleted[out]	Int32	error);

If the vision system is in state Initialized, it is expected to change into state Ready after successful preparation of the recipe and be able to execute jobs called by a Start method with the given ExternalId.

If the vision system is already in state Ready when PrepareRecipe is called, it is expected to be in state Ready again after successful preparation of the recipe and be able to execute jobs called by a Start method with the given ExternalId. Depending on the capabilities of the vision system, it may temporarily leave state Ready for state Initialized, then return to Ready, or, if the system is capable of preparing recipes in the background, it may stay in state Ready and react instantaneously to Start jobs for other, already prepared, recipes. Also depending on the capabilities of the vision system, preparing an additional recipe may unprepare others if the number of recipes being prepared at the same time is limited.

The preparation of a recipe may be a time-consuming operation. The client cannot necessarily assume that the recipe is completely prepared when the method returns. The client should therefore check the preparedness of the recipe after a reasonable amount of time or wait for a RecipePrepared event with the correct ExternalId to be fired. During the time required for preparing a recipe, the system may or may not be capable of reacting to a start method. However, the server is free to handle PrepareRecipe as a synchronous method, returning only after the recipe is completely prepared unless an error has occurred.

Not that the local editing of an already prepared recipe, as described in Sections 7.5.2.1.5 and B.1.2.3 is considered to be the same as the preparation of a new recipe, because after local editing, the already prepared recipe is different from before, so effectively a new recipe has been prepared by the local editing. Therefore, a new RecipePrepared event shall be generated (see also Section 8.3.8.1).

Some recipes may exclude each other from being in prepared state at the same time, for example, when there are mechanical movements involved. Having two such recipes prepared at the same time would mean that an instantaneous reaction to calling the Start method for a prepared recipe would not be possible. However, this is at the discretion of the vision system. The client may merely notice an unusually long reaction time between calling the Start method and the actual state change, or the vision system may prevent the simultaneous preparation by returning an error.

If there is more than one recipe with the identical ExternalId – e.g. due to local copying and modifying of recipes on the vision system – it is implementation-defined how this ambiguity will be handled. The vision system will prepare only a single one of these recipes, which may be the latest one or the latest externally defined one.

7.5.2.3 UnprepareRecipe

This method is used to revert the preparation of a recipe so that it can no longer be used for starting a job on the vision system.

Signature

	UnprepareRecipe ([in]	RecipeIdExternalDataType	externalId[in]	RecipeIdInternalDataType	internalIdIn[out]	RecipeIdInternalDataType	internalIdOut[out]	Int32	error);
	

If the vision system is in Ready state when UnprepareRecipe is called, and the recipe to be unprepared is the only recipe currently prepared, the vision system is expected to change into state Initialized after successful reversion of the preparation of the recipe.

If there are additional recipes in prepared state, the vision system is expected to remain in state Ready and be able to be called by a Start method with one of the remaining prepared recipes. Depending on the capabilities of the vision system, it may temporarily leave state Ready for state Initialized, then return to Ready.

If there is more than one recipe with the identical ExternalId – e.g. due to local copying and modifying of recipes on the vision system – it is implementation-defined how this ambiguity will be handled. However, it is expected that the vision system will handle the ambiguity in the same way as for method PrepareRecipe so that UnprepareRecipe is exactly reciprocal to PrepareRecipe.

7.5.2.4 GetRecipeListFiltered

This method is used to get a list of recipes matching certain filter criteria. It concerns itself only with the metadata of the recipe, the actual content is transferred by a RecipeTransferType object.

Signature

	GetRecipeListFiltered ([in]	RecipeIdExternalDataType	externalId[in]	ProductIdDataType	productId[in]	TriStateBooleanDataType	isPrepared[in]	UInt32	maxResults[in]	UInt32	startIndex[in]	Int32	timeout[out]	Boolean	isComplete[out]	UInt32	resultCount[out]	Handle	recipeHandle[out]	RecipeIdInternalDataType[]	recipeList[out]	Int32	error);

The input arguments are used as filters. Strings or TrimmedStrings as arguments or structure components of arguments can contain * and ? to be used as wildcards. Empty elements are considered to match everything, or in other words are not taken into account for filtering at all. The notion of emptiness is defined together with the respective DataTypes.

In RecipeList, the method returns a list of all recipes whose ExternalIds or ProductIds match the filters.

For RecipleList method there are the following cases with the respect to the number of results:

The number of recipes to be returned according to the filter is less or equal to maxResults; the first call, with nstartIndex=0, returns isComplete=TRUE, so the client knows that no further calls are necessary. resultCount gives the number of valid elements in the recipeList array.

The number of recipes to be returned is larger than maxResults; the first N calls (N > 0 with N ≤ (number of recipes) divisor MaxResults), with startIndex=(N-1)*maxResults, return isComplete=FALSE, so the client knows that further calls are necessary. The following call returns isComplete=TRUE, so the client knows, no further calls are necessary. resultCount gives the number of valid elements in the recipeList array (on each call, so on the first N calls, this should be maxResults).

7.5.2.5 ReleaseRecipeHandle

This method is used to inform the server that the client has finished processing a given recipe set allowing the server to free resources managing this recipe set.

The server should keep the data of the recipe set available for the client until the ReleaseRecipeHandle method is called or until a timeout given by the client has expired. However, the server is free to release the data at any time, depending on its internal resource management, so the client cannot rely on the data being available. ReleaseRecipeHandle is merely a hint allowing the server to optimize its internal resource management. For timeout usage see the description in Section 7.5.2.4.

Signature

	ReleaseRecipeHandle ([in]	Handle	recipeHandle[out]	Int32	error);
	

7.5.2.6 RemoveRecipe

This method is used to remove a recipe from the recipe management of the vision system.

Signature

	RemoveRecipe [([in]	RecipeIdExternalDataType	externalId[out]	Int32	error);

It is expected that the vision system removes the recipe matching the given ExternalId from its management structures. Whether the vision system also removes the actual recipe content is implementation-defined.

Application Note:

The removed recipe may still be referenced by stored results from the vision system. Therefore, it is strongly recommended that the InternalId of a removed recipe is not re-used by the vision system. Otherwise, traceability of results to recipes will be impaired and the vision system may no be able to fulfil certain external requirements, e.g.the FDA Part 11 requirements for pharmaceutical equipment.

However, this standard makes no requirements on the way the vision system creates and maintains its internal management data.

If there is more than one recipe with the identical ExternalId – e.g. due to local copying and modifying of recipes on the vision system – it is implementation-defined how this ambiguity will be handled. For example, the vision system may remove all these recipes or only the externally defined ones or any number of other possibilities.

If the server chooses to represent recipes in the Address Space, the server shall remove the recipe node in the same way as the vision system cleans up its management structures.

7.5.2.7 PrepareProduct

This method is used to prepare a product so that it can be used for starting a job on the vision system.

Signature

	PrepareProduct ([in]	ProductIdDataType	productId[out]	RecipeIdInternalDataType	internalId[out]	Int32	error);
	

In effect, the vision system will use a recipe to work on the product. Therefore, the vision system is expected to select a recipe linked to the given ProductId. If more than one recipe is linked to the product, the resolution of this ambiguity is implementation defined.

The vision system shall return the internal identification of the recipe selected. If there is more than one recipe linked to the given ProductId, it is implementation-defined how this ambiguity will be handled. It is expected that the resolution of the ambiguity will be implemented in a systematic manner throughout the vision system.

Since preparing a product is in effect the same as preparing a recipe which has been selected by the vision system on the basis of the ProductId, state handling is identical to the PrepareRecipe method.

7.5.2.8 UnprepareProduct

This method is used to revert the preparation of a product so that it can no longer be used for starting a job on the vision system.

Signature

	UnprepareProduct ([in]	ProductIdDataType	productId[out]	RecipeIdInternalDataType	internalId[out]	Int32	error);

It is expected that the vision system will select a recipe based on the ProductId in the same way as in method PrepareProduct and then unprepare that recipe so that UnprepareProduct is exactly reciprocal to PrepareProduct.

Therefore, state handling is identical to UnprepareRecipe method.

7.5.2.9 UnlinkProduct

This method is used to remove the link between a recipe and a product in the vision system

Signature

	UnlinkProduct ([in]	RecipeIdInternalDataType	internalId[in]	ProductIdDataType	productId[out]	Int32	error);
	

It is expected that the vision system removes a link between recipes with the given InternalId and products with the given ProductId from its internal management structures.

UnlinkProduct uses the InternalId to ensure that it is unambiguous which recipe the link is removed from. If need be, the client can get the InternalIds for given ExternalIds using the GetRecipeListFiltered method (7.5.2.4).

Starting jobs based on this ProductId will no longer lead to this recipe being used. If there is no link left between this ProductId and any recipe, it will no longer be possible to start a job based on that ProductId.

If the server chooses to represent recipes in the Address Space, the server shall remove the given ProductId from the appropriate recipe node.

If the server chooses to represent products in the Address Space, and there are no recipes linked to a product anymore, it is expected that the server removes the corresponding product node.

7.6 RecipeTransferType

7.6.1 Overview

This ObjectType is a subtype of TemporaryFileTransferType defined in OPC 10000-5 and is used for transferring a recipe.

The RecipeTransferType overwrites the Methods GenerateFileForRead and GenerateFileForWrite to specify the concrete type of the generateOptions Parameter of the Methods.

Figure 13 shows the hierarchical structure and details of the composition. It is formally defined in Table 49.

7.6.2 RecipeTransferType Methods

7.6.2.1 GenerateFileForRead

This method is used to start the read file transaction. A successful call of this method creates a temporary FileType Object with the file content and returns the NodeId of this Object and the file handle to access the Object.

Signature

	GenerateFileForRead ([in]	RecipeTransferOptions	generateOptions[out]	NodeId	fileNodeId[out]	UInt32	fileHandle[out]	NodeId	completionStateMachine);

7.6.2.2 GenerateFileForWrite

This method is used to start the write file transaction. A successful call of this method creates a temporary FileType Object with the file content and returns the NodeId of this Object and the file handle to access the Object.

Signature

	GenerateFileForWrite ([in]	RecipeTransferOptions	generateOptions[out]	NodeId	fileNodeId[out]	UInt32	fileHandle);

7.7 RecipeType

7.7.1 Overview

This ObjectType defines the metadata for a recipe and methods for handling individual recipes.

ExternalId

RecipeId for identifying the recipe outside the vision system. The ExternalId is only managed by the environment.

InternalId

System-wide unique ID for identifying a recipe. This ID is assigned by the vision system.

LastModified

The time, when this recipe was last modified in the recipe store of the vision system. It is assumed that this value is consistent between recipes on the system so that it can be used to order recipes on the system by modification time. As it is possible that the vision system may not be synchronized with a time server, this value may not be valid for comparisons between systems.

LinkedProducts

Array of ProductIds which this recipe is linked to. May be empty.

Handle

FileType object for handling transfer of recipe data between client and server. The data is treated as a binary blob by the server. This method is optional for clients not supporting transfer of the actual recipe contents.

7.7.2 RecipeType Methods

7.7.2.1 Overview

If recipes are exposed in the Address Space, the corresponding entries in the Recipes folder of the RecipeManagement object have to be created using the AddRecipe method of the RecipeManagement object. The recipe object cannot destroy itself as this would affect the data structures of the RecipeManagement object; therefore, removal has to take place using the Remove method of that object.

Operations other than AddRecipe can be carried out directly on the the RecipeType object as well as on he RecipeManagement object.

For data transfer, the FileType object contained in the RecipeType object can be used directly. Therefore, there is no need for a specific Get method.

7.7.2.2 LinkProduct

This method is used to create a link between the recipe and a product in the vision system

Signature

	LinkProduct ([in]	ProductIdDataType	productId[out]	Int32	error);
	

It is assumed that the given ProductId already exists in the vision system management structures, e.g. having been created with the AddProduct method of the RecipeManagementType. It is recommended that it also exists in the Products folder of the RecipeManagementType object to expose a consistent set of data in the Address Space.

In the case of a successful link, the server shall add the given ProductId to the LinkedProducts list of this RecipeType object.

The method shall fail if the product does not exist in the vision system management structures.

7.7.2.3 UnlinkProduct

This method is used to remove the link between the recipe and a product in the vision system

Signature

	UnlinkProduct ([in]	ProductIdDataType	productId[out]	Int32	error);
	

The server shall remove the given ProductId from the LinkedProducts list of this RecipeType object.

It is expected that the vision system removes a link between the recipe represented by this object and products with the given ProductId from its internal management structures.

Starting jobs based on this ProductId will no longer lead to this recipe being used. If there is no link left between this ProductId and any recipe, it will no longer be possible to start a job based on that ProductId.

7.7.2.4 Prepare

This method is used to prepare the recipe so that it can be used for starting a job on the vision system.

Signature

	Prepare ([out]	Boolean	isCompleted[out]	Int32	error);

The effects of the Prepare method of a RecipeType object on the VisionSystem shall be identical to those of the PrepareRecipe method of the RecipeManagementType object.

7.7.2.5 Unprepare

This method is used to revert the preparation of the recipe so that it can no longer be used for starting a job on the vision system.

Signature

	Unprepare ([out]	Int32	error);

The effects of the Unprepare method of a RecipeType object on the VisionSystemAutomaticModeStateMachine shall be identical to those of the UnprepareRecipe method of the RecipeManagementType object.

7.7.2.6 Recipe transfer

There are no dedicated transfer methods on the RecipeType because it already contains a FileType object representing the content of the actual recipe in the vision system. Thus, transfer can be carried out using the standard Open, Read, Write, Close methods of the FileType object.

7.8 RecipeFolderType

This ObjectType is a subtype of the FolderType and is used to organize the recipes of a vision system. Figure 15 shows the hierarchical structure and details of the composition. It is formally defined in Table 63.

Instances of this ObjectType organize all available recipes of the vision system, which the server decides to expose in the Address Space. It may contain no recipe if no recipe is available, if the server does not expose recipes in the Address Space at all, or if no recipe matches the criteria of the server for exposure in the Address Space.

Note that the folder contains only metadata of the recipes, not the actual configuration data of the vision system.

The RecipeType used in the RecipeFolderType is defined in Section 7.7.

7.9 ProductFolderType

This ObjectType is a subtype of the FolderType and is used to organize the products of a vision system. Figure 16 shows the hierarchical structure and details of the composition. It is formally defined in Table 64.

Instances of this ObjectType organize all available products of the vision system, which the server decides to expose in the Address Space. It may contain no product if no product is available, if the server does not expose products in the Address Space at all, or if no product matches the criteria of the server for exposure in the Address Space.

Note that the folder contains only metadata of the products, not the actual product data of the vision system.

The ProductDataType used in the ProductFolderType is defined in Section 12.15.

7.10 ResultManagementType

7.10.1 Overview

This ObjectType defines the representation of the machine vision system result management. Figure 17 shows the hierarchical structure and details of the composition. It is formally defined in Table 65.

ResultManagementType provides methods to query the results generated by the underlying vision system. Results can be stored in a local result store. An event of ResultReadyEventType, which is defined in Section 8.3.8.4, shall be triggered when the system generates a new result.

ResultTransfer is an instance of the ResultTransferType defined in Section 7.12 and it is used to transfer the contents of a result by the temporary file transfer method defined in OPC 10000-5, Annex C.4.

Results is an Object of the ResultFolderType that organizes variables of the DataType ResultDataType which is defined in Section 12.17. If the server chooses to expose result information in the Address Space, it may contain the set of all results available on the system or a filtered subset, e.g. the set of all currently finished results. This is implementation-defined. If a server does not expose result information in the Address Space, this variable is expected to be non-existent.

7.10.2 ResultManagementType methods

7.10.2.1 GetResultById

This method is used to retrieve a result from the vision system. Depending on the design of the vision system, the client may be informed by events of ResultReadyEventType that a new result is available. Then, the client might fetch this result using the information provided by events of ResultReadyEventType which is defined in Section 8.3.8.4.

Since the resultId is supposed to be system-wide unique, this method shall return only a single result. Since there may be additional result content to be retrieved by temporary file transfer, the server should keep result data available, resources permitting, until the client releases the handle ReleaseResult. However, the client cannot rely on the data to remain available until then.

Signature

	GetResultById ([in]	ResultIdDataType	resultId[in]	Int32	timeout[out]	Handle	resultHandle[out]	ResultDataType	result[out]	Int32	error);
	

7.10.2.2 GetResultComponentsById

This method is used to retrieve a result from the vision system. It is basically identical to the GetResultById method described in Section 7.10.2.1, but it returns the result not in a single output argument of ResultDataType but in individual output arguments corresponding to the elements of the ResultDataType structure.

The reason for providing this method is to facilitate the use of subtypes to the structures nested inside of ResultDataType. Since the NodeIds of structured DataTypes nested within a structured DataType are not transferred together with the DataType, subtyping these nested structures would then also necessitate subtyping ResultDataType. This is of course possible, but in the absence of such a subtype, the individual components can still be requested by this method.

Signature

	GetResultComponentsById ([in]	ResultIdDataType	resultId[in]	Int32	timeout[out]	Boolean	hasTransferableDataOnFile[out]	Handle	resultHandle[out]	Boolean	isPartial[out]	Boolean	isSimulated[out]	ResultStateDataType	resultState[out]	MeasIdDataType	measId[out]	PartIdDataType	partId[out]	RecipeIdExternalDataType	externalRecipeId[out]	RecipeIdInternalDataType	internalRecipeId[out]	ProductIdDataType	productId[out]	ConfigurationIdDataType	externalConfigurationId[out]	ConfigurationIdDataType	internalConfigurationId[out]	JobIdDataType	jobId[out]	UtcTime	creationTime[out]	ProcessingTimesDataType	processingTimes[out]	BaseDataType[]	resultContent[out]	Int32	error);
	

7.10.2.3 GetResultListFiltered