Plug-in helper class for receiving events from the vision system. More...

#include <mvtec/plugin-support/v1/Defines.h>
#include <mvtec/plugin-support/v1/Logger.h>
#include <mvtec/plugin-support/v1/Result.h>
#include <mvtec/plugin-support/v1/detail/CRTP.h>
#include <mvtec/plugin/mv_plugin_api_v2.h>
#include <thread>
#include <mvtec/plugin-support/v1/EventDriven/EventMonitorImpl.h>

Data Structures
class	EventMonitor< Plugin >

Detailed Description

Plug-in helper class for receiving events from the vision system.

The communication between plug-ins inside the Communicator and the vision system (i.e. MERLIC) mainly utilizes two FIFO queues, one for either direction:

Actions (-> IActionController.h)
Events notify the plug-ins of any changes of the active state of the vision state machine, available results, or alert the plug-in that an action could not be processed because it was invalid or is not applicable to the current state of the vision system. Most events are caused by an action, in which case they carry its actionId. The communicator holds a separate event queue for each plug-in. Every event is put into each plug-in's event queue, regardless which plug-in issued the associated action. Plug-ins can then get events from their respective queues.

By deriving from MVPlugin::EventMonitor<Plugin>, the Plugin class can effectively subscribe to certain events from the vision system by defining suitable event callbacks. EventMonitor employs the "Curiously recurring template pattern" to mix this functionality into the Plugin class and will only extract parameters from an event and convert them into their support library counterparts if the Plugin class defines a suitable member function to handle it. Hence, the runtime penalty incurred due to uninteresting events is minimized. Note that the signature of these member functions must match exactly, otherwise the callback is not recognized and the corresponding events are silently ignored.

To receive events from the communicator queue, the EventMonitor must be started (via StartEventLoop()) during the plugin startup (Plugin::Start()) and stopped (StopEventLoop()) if the plugin is stopped (Plugin::Stop()).

The following event callbacks are available:

void StateChanged(EventTrigger trigger, ActionType cause, MVPlugin::State fromState, MVPlugin::State toState) noexcept;

This event notifies the plug-in about a change of the vision system state. It gives information about the previous state and the new state.

Parameters

trigger	This parameter contains the ID of the action and optionally that of the plug-in which triggered this event.
cause	This parameter represents the type of action which caused the state transition.
fromState	This parameter represents the value corresponding to the state vision system has transitioned from.
toState	This parameter represents the value corresponding to the state vision system has transitioned to.

void Error(EventTrigger trigger, MVPlugin::Error const& error) noexcept;

This event is sent if an error occurred. It gives information about the error code and an error message. Depending upon the severity of the error, this event may be accompanied by a state change to the "Error" state if the error condition is deemed irrecoverable or if the internal state of the vision system or that of any of the prepared recipes became corrupted.

Parameters

trigger	This parameter contains the ID of the action and optionally that of the plug-in which triggered this event.
error	this parameter represents the error information.

void RecipePrepared(EventTrigger trigger, MVPlugin::RecipeId const& recipeId) noexcept;

This event is sent if the PrepareRecipe action has been processed. It notifies the plug-in that the specified recipe has been loaded.

Parameters

trigger	This parameter contains the ID of the action and optionally that of the plug-in which triggered this event.
recipeId	This parameter represents the recipe ID of the recipe that has been prepared.

void RecipeUnprepared(EventTrigger trigger, MVPlugin::RecipeId const& recipeId) noexcept;

This event notifies the plug-in that the recipe has been unloaded and the respective vision app has been closed, i.e., due to either an UnprepareRecipe action or due to a PrepareRecipe action while another recipe was still loaded. The RecipeUnprepared event only indicates that the unloading commenced and the formerly prepared recipe is no longer available for execution.

Parameters

trigger	This parameter contains the ID of the action and optionally that of the plug-in which triggered this event.
recipeId	This parameter represents the recipe ID of the recipe that is no longer prepared.

void JobStarted(EventTrigger trigger, MVPlugin::JobId jobId) noexcept;

This event notifies the plug-in that a new execution has started and carries its associated job ID. Thus, this event may be waited for by the caller of StartSingleJob to retrieve the job ID of the job they just started such that they know which job ID to look for in forthcoming ResultReady events.

Parameters

trigger	This parameter contains the ID of the action and optionally that of the plug-in which triggered this event.
jobId	This parameter represents the ID of the job that has been started by the action which caused this event.

void JobStarted(EventTrigger trigger, MVPlugin::JobId jobId, MVPlugin::RecipeId const& recipeId, MVPlugin::JobType

jobType, std::vector<MVPlugin::Value> const& parameters) noexcept;

This is an extended form of the basic JobStarted callback above. It is available since API v2.2.1 and adds information on the recipe ID, the type of job (single vs. continuous job), and the start parameters of the job.

An even further extended overload for JobStarted is available and should be preferred to this one.

When this extended overload of JobStarted is defined and the Communicator running the plug-in supports the API features (v2.2.1 or later), it will be invoked instead of the basic overload. It is possible to define both overloads in the Plugin class where the basic overload serves as a compatibility fallback in case the Communicator does not yet support the extended form (API v2.2.0). When the additional information is not required, the basic overload should be used to maximize compatibility and avoid unnecessary overhead.

Parameters

trigger	This parameter contains the ID of the action and optionally that of the plug-in which triggered this event.
jobId	This parameter represents the ID of the job that has been started by the action which caused this event.
recipeId	This parameter represents the ID of the recipe for which the job that has been started is being executed.
jobType	This parameter is an enum indicating whether the started job is a single job or a continuous job.
parameters	This is the set of job parameters that are used to execute the job. An empty vector indicates that the recipe's default input parameters are being used. Note that it is possible that the values differ from those that have been passed through IActionController::StartSingleJob() or IActionController::StartContinuous() in case the vision system did not accept the requested job parameters.

void JobStarted(EventTrigger trigger, MVPlugin::JobInfo jobInfo) noexcept;

This is a further extended form of the JobStarted callback. It is available since API v2.2.2 and adds information on the measurement and part IDs. Since these additional fields are optional, this overload is also usable when the Communicator running the plug-in only supports API v2.2.1.

This overload and the one above are mutually exclusive. It is recommended to update to this overload if information on recipe ID, job type, or parameters, are needed; otherwise, the basic overload only providing the job ID can be used to maximize compatibility with older Communicators (API v2.2.0).

Parameters

trigger	This parameter contains the ID of the action and optionally that of the plug-in which triggered this event.
jobInfo	This parameter contains the ID of the job itself, as well as the IDs of the recipe, measurement, and part associated with the job, its type, and the parameters the job was started with. It may be extended in future API versions.

void AcquisitionDone(MVPlugin::JobId jobId) noexcept;

This event is emitted whenever the image acquisition from all image sources is finished. The image processing job may still be in progress at that time. AcquisitionDone should be expected once for a SingleExecution job and multiple times for a ContinuousExecution job. The corresponding job ID can be retrieved from the event.

Parameters

jobId This parameter represents the ID of the job during which acquisition finished.

void AcquisitionDone(MVPlugin::AcquisitionInfo acquisitionInfo) noexcept;

This is an extended form of the basic AcquisitionDone callback above. It is available since API v2.2.2 and adds information on the acquisition duration. Since this additional information is optional, this overload is also usable when the Communicator running the plug-in only supports API v2.2.0.

This overload and the basic one above are mutually exclusive.

Parameters

acquisitionInfo This parameter contains the ID of the job for which the acquisition took place, as well as additional information on the acquisition such as the total time that it has taken. It may be extended in future API versions.

void Ready(EventTrigger trigger, MVPlugin::JobId jobId) noexcept;

This event notifies the plug-in that the vision system returned to the "Ready" state after an execution finished and carries the job ID of said execution. It is neither emitted when the vision system initially enters "Ready" after preparing a new recipe nor when an execution finishes due to a call to Halt or Reset.

Parameters

trigger	This parameter contains the ID of the action and optionally that of the plug-in which triggered this event.
jobId	This parameter represents the ID of the job which was completed prior to becoming "Ready" again.

void ResultReady(MVPlugin::Result const& result) noexcept;

This event is sent when the result of an execution has been made available by the vision system. It is emitted independently from the MERLIC RTE state machine and you should not rely on any particular order relative to other events. Use the JobStarted, Ready, or StateChanged events to synchronize with the state machine instead.

Parameters

result This parameter represents the actual result data.

void VisionSystemAvailable(MVPlugin::SystemStatus const& systemStatus,

std::future<std::vector<MVPlugin::RecipeData>> recipeData) noexcept;

This event is sent when the vision system is available (again).

Parameters

systemStatus	This parameter represents the actual systemStatus. Be careful with this parameter, it is not synchronized with the EventQueue. It is possible that a subsequent StateChange event does not match the systemStatus.
recipeData	This parameter represents the actual available Recipes. This parameter represents a future parameter due to its high processing effort.

Data Structures

Detailed Description