Callbacks Triggered By GenICam™ Events

Note

This use case applies only to devices operating in GenICam™ interface layout. More details at chapter General and Which Interface Is Supported By Which Device?.

In some cases it is interesting to get notified about the occurrence of a certain event (e.g. a trigger signal or the end of an image being exposed) on the camera side as soon as possible. This can be achieved by using the events specified by the GenICam™ standard in combination with callbacks.

Depending on the firmware version the following events are currently supported:

• General events:
  • EventExposureEnd
  • EventFrameEnd
• Digital I/O related events:
  • EventLine4RisingEdge
  • EventLine4FallingEdge
  • EventLine4AnyEdge
  • EventLine5RisingEdge
  • EventLine5FallingEdge
  • EventLine5AnyEdge

The following example will illustrate how the events can be used to get notified about an image which has been exposed by the sensor, so the image has not been read out yet. This means the information about the finished image is available much earlier than the image itself. Depending on the resolution of the used device and the bandwidth of the used interface the saved time might be significant.

Note

This use case assumes that the image acquisition is already working and the used device supports the GenICam™ interface layout (see Preface for details), similar to the ContinuousCapture.py sample.

How it works

1. The device is opened by calling

   pDev.open() 

1. An instance of the EventControl class is created.
2. The desired GenICam™ event of the device is enabled.
3. A callback is created.
4. The callback is registered to the property which should execute the callback once its value or features change.
5. As soon as the image acquisition starts, the callback will be invoked.

Any application that wants to get notified when a certain feature in the Impact Acquire property tree did change needs to derive a class from mvIMPACT::acquire::ComponentCallback and override the mvIMPACT::acquire::ComponentCallback::execute() method:

#------------------------------------------------------------------
# Event Callback implementation
#------------------------------------------------------------------
class EventCallback(acquire.ComponentCallback):
  def __init__(self, pUserData):
    acquire.ComponentCallback.__init__(self)
    self.pUserData_ = pUserData
 
  def execute(self, c, pUserData):
    try:
      # re-generating the object/data previously attached to the callback object. This could now be used to call a certain member function e.g. to update a class instance about this vent!
      ec = self.pUserData_
      if( c.isProp ):
        p = acquire.Property(c.hObj())
        print("Component " + c.name() + " has changed. Its current value: " + p.readS() + "us. FrameID is: " + ec.eventExposureEndFrameID.readS())
    except Exception as e:
      print("An exception has been raised by code that is not supposed to raise one: '" + str(e) + "'! If this is NOT handled here the application will crash as this Python exception instance will be returned back into the native code that fired the callback!")

In order to be able to do something useful each callback can carry a pointer to arbitrary user data that can be used to get access to any part of the application code within the callback context. This example attaches an instance of the class EventControl to get access to the events properties, when creating the callback handler later.

The event control class needs to be instantiated to get access to switch on the devices GenICam™ events. In this case the "ExposureEndEvent" is enabled and will be sent by the device once the exposure of an image has finished.

ec = acquire.EventControl(pDev);
ec.eventSelector.writeS("ExposureEnd")
ec.eventNotification.writeS("On")

Now the actual callback handler will be created and a property will be registered to it:

eventCallback = EventCallback(ec)
eventCallback.registerComponent(ec.eventExposureEndTimestamp)

Once the callback is not needed anymore, it should be unregistered:

eventCallback.unregisterComponent(ec.eventExposureEndTimestamp)

The code used for this use case can be found at: GenICamCallbackOnEvent.py