# Using the Capture API

## Background

The **AxsunOCTCapture API** provides users of the Axsun [Ethernet/PCIe DAQ](https://docs.axsun.com/axsun-knowledge-base/ref-manual/gigabit-ethernet-daq-board) with the ability to retrieve digitized data for subsequent display, analysis, archival, or other user process.  Refer to the [AxsunOCTCapture Function Reference](https://downloads.axsun.com/public/software/EthernetDAQ/AxsunOCTCaptureAPI_manual/_axsun_o_c_t_capture_8h.html) and sample code projects on the [Software Downloads](https://docs.axsun.com/axsun-knowledge-base/other/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](https://docs.axsun.com/axsun-knowledge-base/software-tools/image-capture-tool) also relies directly on the Capture API, so [its documentation](https://docs.axsun.com/axsun-knowledge-base/software-tools/image-capture-tool) provides additional examples of the Capture API's secondary capabilities.

{% hint style="info" %}
**NOTE:** Become familiar with the [Basic Operation](https://docs.axsun.com/axsun-knowledge-base/ref-manual/gigabit-ethernet-daq-board/basic-operation#interaction-with-the-axsunoctcapture-library) of the Ethernet/PCIe DAQ prior to reading this document.
{% endhint %}

## Installation

### Windows OS

Installation of the AxsunOCTCapture library and its dependencies is covered [when installing the Image Capture Tool](https://docs.axsun.com/axsun-knowledge-base/guides/integrated-engine/installing-software#image-capture-tool-and-axsunoctcapture) GUI.

### Linux OS

Installation of the AxsunOCTCapture library and its dependencies is [covered on this page](https://docs.axsun.com/axsun-knowledge-base/api-references/axsunoctcapture.dll/linux-installation).

## 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 ](https://downloads.axsun.com/public/software/EthernetDAQ/AxsunOCTCaptureAPI_manual/index.html)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](http://zone.ni.com/reference/en-XX/help/371361R-01/glang/call_library_function/).  
* **C#/.NET Framework** integration can be achieved using P/Invoke and the `DllImport` attribute discussed [here](https://docs.microsoft.com/en-us/cpp/dotnet/using-explicit-pinvoke-in-cpp-dllimport-attribute?view=vs-2017).
* **Python** integration can be achieved using the [ctypes library](https://docs.python.org/3/library/ctypes.html).

### 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](https://docs.axsun.com/axsun-knowledge-base/ref-manual/gigabit-ethernet-daq-board/basic-operation#live-imaging-burst-record).  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.