Using the Capture API

Background

The AxsunOCTCapture API provides users of the Axsun Ethernet/PCIe DAQ with the ability to retrieve digitized data for subsequent display, analysis, archival, or other user process. Refer to the AxsunOCTCapture Function Reference and sample code projects on the Software Downloads page for more information about secondary and advanced functionality provided by the Capture API. Any functionality provided in GUI form by the Image Capture Tool also relies directly on the Capture API, so its documentation provides additional examples of the Capture API's secondary capabilities.

NOTE: Become familiar with the Basic Operation of the Ethernet/PCIe DAQ prior to reading this document.

Installation

Windows OS

Installation of the AxsunOCTCapture library and its dependencies is covered when installing the Image Capture Tool GUI.

Linux OS

Installation of the AxsunOCTCapture library and its dependencies is covered on this page.

Integrating Into Your Application

Basic functionality of the Capture API can be achieved with only several function calls architected as described below. Please refer to source code available in the AxsunOCTCapture Function Reference for several basic API integration example programs that highlight the main functionality in the library.

• The Capture API is a "plain-old" ANSI C interface which can be directly called from applications coded in native C or C++.

• LabVIEW integration can be achieved using the Call Library Function Node.

• C#/.NET Framework integration can be achieved using P/Invoke and the DllImport attribute discussed here.

• Python integration can be achieved using the ctypes library.

Starting a Capture Session

Starting a Capture session allocates library resources, including the Main Image Buffer – the RAM location into which streamed data will be buffered for subsequent retrieval by the user. The Main Image Buffer size should be allocated based on the expected length of a Burst Record operation. It is a circular buffer, so allocating too small will limit the length of a Burst Record operation before overflow, and allocating too large will unnecessarily reserve RAM which could be used by other processes. To start a Capture session, call axStartSession(...) with a capacity_MB argument as the desired number of MB to reserve for the Main Image Buffer.

Selecting a Capture Interface

Once the Capture session is started, select a capture interface (PCIe or Gigabit Ethernet) for acquiring data from an Axsun DAQ using axSelectInterface(...). This step can be skipped if the session involves only loading saved data files from disk rather than capturing new image data from a DAQ.

Querying Buffer Information

At any time following the start of a Capture session and preferably in a loop which executes regularly during image collection, query the current status of the Main Image Buffer using axGetStatus(...). This provides the active state of data streaming (i.e. is the DAQ currently transmitting images or is it idle?), the number of images captured since last reset, and other parameters.

Retrieving Image Info and Image Data

Following the capture of data into the Main Image Buffer and contained in a loop which executes repeatedly during live image display or during playback of previously recorded images, use the axGetImageInfo(...) and axRequestImage(...) functions to copy image data from the Main Image Buffer into user memory for subsequent interaction as desired. Alternatively, an event-driven approach is available to asynchronously respond to new images via a callback rather than the traditional polling approach.

Getting Info and Error Messages

Use axGetMessage(...) to learn additional information about the session status and axGetErrorString(...) to describe the source of potential error codes returned from AxsunOCTCapture function calls.

Stopping a Capture Session

Call axStopSession(...) to release interfaces and free resources that were initially allocated when the Capture session was started.