Getting A Single Image

At least four steps are necessary to capture a single image from a Balluff device. These steps are explained with the help of source examples from ImpactControlCenter.

Step 1: The Device Needs To Be Initialized

// Get a pointer to the first device found 
mv.impact.acquire.Device pDev = mv.impact.acquire.DeviceManager.getDevice(0);
 
// initialise it(this step is optional as this will be done automatically from
// all other wrapper classes that accept a device pointer):
pDev.open();

Step 2: Request The Acquisition Of An Image

// create an instance of the function interface for this device
// (this would also initialise a device if necessary)
mv.impact.acquire.FunctionInterface fi = new mv.impact.acquire.FunctionInterface(pDev);
// send the request for one image down to the driver
fi.imageRequestSingle();

A live acquisition (running inside a thread function) could be implemented as follows:

Thread thread = new Thread(delegate()
{
  // Send all requests to the capture queue. There can be more than 1 queue for some devices, but for this sample
  // we will work with the default capture queue. If a device supports more than one capture or result
  // queue, this will be stated in the manual. If nothing is mentioned about it, the device supports one
  // queue only. This loop will send all requests currently available to the driver. To modify the number of requests
  // use the property mv.impact.acquire.SystemSettings.requestCount at runtime (note that some devices will
  // only allow to modify this parameter while NOT streaming data!) or the property
  // mv.impact.acquire.Device.defaultRequestCount BEFORE opening the device.
  TDMR_ERROR result = TDMR_ERROR.DMR_NO_ERROR;
  while ((result = (TDMR_ERROR)fi.imageRequestSingle()) == TDMR_ERROR.DMR_NO_ERROR) { };
  if (result != TDMR_ERROR.DEV_NO_FREE_REQUEST_AVAILABLE)
  {
    Console.WriteLine("'FunctionInterface.imageRequestSingle' returned with an unexpected result: {0}({1})", result, ImpactAcquireException.getErrorCodeAsString(result));
  }
  // Start the acquisition manually if this was requested(this is to prepare the driver for data capture and tell the device to start streaming data)
  if (pDev.acquisitionStartStopBehaviour.read() == TAcquisitionStartStopBehaviour.assbUser)
  {
    if ((result = (TDMR_ERROR)fi.acquisitionStart()) != TDMR_ERROR.DMR_NO_ERROR)
    {
      Console.WriteLine("'FunctionInterface.acquisitionStart' returned with an unexpected result: {0}({1})", result, ImpactAcquireException.getErrorCodeAsString(result));
    }
  }
 
  // run thread loop
  Request pRequest = null;
  int timeout_ms = 500;
  int cnt = 0;
  int requestNr = Device.INVALID_ID;
  while (!terminated)
  {
    // wait for results from the default capture queue
    requestNr = fi.imageRequestWaitFor(timeout_ms);
    pRequest = fi.isRequestNrValid(requestNr) ? fi.getRequest(requestNr) : null;
    if (pRequest != null)
    {
      if (pRequest.isOK)
      {
        // display/process/store or do whatever you like with the image here
      }
      else
      {
        Console.WriteLine("Error: {0}", pRequest.requestResult.readS());
      }
      pRequest.unlock();
      // send a new image request into the capture queue
      fi.imageRequestSingle();
    }
    else
    {
      // If the error code is -2119(DEV_WAIT_FOR_REQUEST_FAILED), the documentation will provide 
      // additional information under TDMR_ERROR in the interface reference
      Console.WriteLine("imageRequestWaitFor failed ({0}, {1}), timeout value too small?", requestNr, ImpactAcquireException.getErrorCodeAsString(requestNr));
    }
  }
 
  // Stop the acquisition manually if this was requested
  if (pDev.acquisitionStartStopBehaviour.read() == TAcquisitionStartStopBehaviour.assbUser)
  {
    if ((result = (TDMR_ERROR)fi.acquisitionStop()) != TDMR_ERROR.DMR_NO_ERROR)
    {
      Console.WriteLine("'FunctionInterface.acquisitionStop' returned with an unexpected result: {0}({1})", result, ImpactAcquireException.getErrorCodeAsString(result));
    }
  }
 
  // clear all queues
  fi.imageRequestReset(0, 0);
});

Note

Images supplied to the user are locked for the driver. So if the user does not unlock the images, a permanent acquisition won't be possible as sooner or later all available requests will have been processed by the driver and have been returned to the user.

See also

Step 4.

Step 3: Wait Until The Image Has Been Captured

int requestNr = fi.imageRequestWaitFor( timeout_ms );

Step 4: Unlock The Image Buffer Once The Image Has Been Processed:

if(fi.isRequestNrValid(requestNr))
{
  // processing, displaying whatever
  fi.imageRequestUnlock(requestNr);
}

Note

ImpactControlCenter acquires images with the help of a capture thread. In order to avoid performance losses, the image buffer is locked during either the live or single image acquisition.

So after displaying the image the unlock is necessary!