Image Acquisition

Image Acquisition

The SDK supports the following 2 image acquisition methods: callback and polling. Select one as needed.

• Callback: Acquire image via callback.
• Polling: Acquire image via polling.

Attention

These two methods cannot be used at the same time. Select one at one time.

Acquire Images via Callback

The SDK provides an API to register callback function. You can call MV_CC_RegisterImageCallBackEx() and register callback API for image acquisition in SDK. After getting image, SDK will call custom callback function.

Attention

• Time-consuming operation and thread lock are not recommended, as adding them may block callback.
• pUser is invalid and cannot be used again after callback ends.

The API calling flow is as follows:

1. Call MV_CC_SetImageNodeNum() to set the appropriate number of buffer nodes.

   Note

   Set the appropriate number of buffer nodes as needed. Major factors include: camera frame rate, image solution, computer disposition such as main board performance and memory.

2. Call MV_CC_RegisterImageCallBackEx() to register image processing function.
3. Call::MV_CC_StartGrabbing() to start grabbing image.
4. It will be executed and handle images in custom image processing function after SDK receives image.

The following sample code shows how to acquire image through callback function:

• Method of customizing image callback:

  void __stdcall ImageCallBackEx(unsigned char * pData, MV_FRAME_OUT_INFO_EX* pFrameInfo, void* pUser)
  {
      if (pFrameInfo)
      {
          printf("Get One Frame: Width[%d], Height[%d], FrameLen[%I64d] nFrameNum[%d]\n", 
          pFrameInfo->nExtendWidth, pFrameInfo->nExtendHeight, pFrameInfo->nFrameLenEx,pFrameInfo->nFrameNum);
          // pData: an image pointer; pFrameInfo->nFrameLenEx: image length that can process image
      }
  }

• Register a callback for image grabbing, and start acquiring images.

  // Register image capture and callback
  nRet = MV_CC_RegisterImageCallBackEx(handle, ImageCallBackEx, handle);
  Check(nRet);
  
  // Set the number of output buffer
  nRet = MV_CC_SetImageNodeNum(handle, 5);
  Check(nRet);
  
  // Start grabbing images
  nRet = MV_CC_StartGrabbing(handle);
  Check(nRet);

Acquire Images via Polling

SDK offers API for active image acquisition. You can manually create a thread, and repeatedly call this API in the thread to get image information.

Basic steps of acquiring image via polling are as follows:

1. Call MV_CC_SetImageNodeNum() to set the appropriate number of buffer nodes in SDK.

   Note

   • Image data of camera received by SDK is cached in SDK for calling from users. Call :: MV_CC_SetImageNodeNum() to configure number of buffer nodes in SDK. Due to slow calling of the upper layer, and limited buffer nodes, SDK memory is inadequate for storage of images sent from the camera, leading to frame loss.
   • The actual number of buffer nodes depends on the actual situation (main factors including camera frame rate, image solution, computer disposition such as main board performance and memory).

2. Call MV_CC_StartGrabbing() to start grabbing image.

3. Call MV_CC_GetImageBuffer() in the application layer to get frame data in the specified pixel format.

   Note

   • You can set the timeout of this API. SDK waits for returned data before timeout.
   • When getting image data, you can configure API calling frequency in the upper application layer according to the camera frame rate.

4. Process image through buffer operation.

5. Call MV_CC_FreeImageBuffer() to release buffer.

   Note

   Buffer will be returned to SDK when calling MV_CC_FreeImageBuffer(). Buffer will be invalid after being returned.

The following sample code shows the process of acquiring images via polling:

1. Customize the thread function, and receive and process images.

   static  unsigned int __stdcall WorkThread(void* handle)
   {
       int nRet = MV_OK;
       MV_FRAME_OUT stOutFrame = {0};
       while(true)
       {
           nRet = MV_CC_GetImageBuffer(handle, &stOutFrame, 1000);
           if (nRet == MV_OK)
           {
               printf("Get Image Buffer: Width[%d], Height[%d], FrameNum[%d]\n",
               stOutFrame.stFrameInfo.nWidth, stOutFrame.stFrameInfo.nHeight, stOutFrame.stFrameInfo.nFrameNum);
               nRet = MV_CC_FreeImageBuffer(handle, &stOutFrame);
               Check(nRet);
   
           }
           if(g_bExit)
           {
               break;
           }
       }
       return 0;
   }

2. Start to collect

   // Set number of buffer nodes
   nRet = MV_CC_SetImageNodeNum(handle, 5);
   Check(nRet);
   
   // Start grabbing images
   nRet = MV_CC_StartGrabbing(handle);
   Check(nRet);
   
   unsigned int nThreadID = 0;
   void* hThreadHandle = (void*) _beginthreadex(NULL , 0 , WorkThread , handle, 0 , &nThreadID );
   if (NULL == hThreadHandle)
   {
       break;
   }

Previous: Event and Exception

Next: Image Processing