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.java 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:

import mvIMPACT.acquire.*;
 
//-----------------------------------------------------------------------------
class EventCallback extends ComponentCallback
//-----------------------------------------------------------------------------
{
  //=============================================================================
  //=== Private member variables ================================================
  //=============================================================================
  private Object pUserData_;
 
  //=============================================================================
  //=== Public constructors =====================================================
  //=============================================================================
  public EventCallback( Object pUserData )
  {
    super();
    pUserData_ = pUserData;
  }
 
  //=============================================================================
  //=== Public member functions =================================================
  //=============================================================================
  @Override
  public void execute( Component c, SWIGTYPE_p_void pUserData )
  {
    EventControl ec = (EventControl)getUserData();
    if ( c.isProp() )
    {
      Property p = new Property( c.hObj() );
      System.out.println("Component " + c.name() + " has changed. Its current value: " + p.readS() + "us. FrameID is: " + ec.getEventExposureEndFrameID().readS());
    }
  }
  
  public Object getUserData()
  {
    return pUserData_;
  }
}

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.

EventControl ec = new EventControl( pDev_ );
ec.getEventSelector().writeS( "ExposureEnd" );
ec.getEventNotification().writeS( "On" );

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

EventCallback eventCallback = new EventCallback( "", ec );
// register a callback to eventExposureEndTimestamp
eventCallback.registerComponent( ec.getEventExposureEndTimestamp() );

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

// clean up
eventCallback.unregisterComponent( ec.getEventExposureEndTimestamp() );

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