AxsunOCTCapture 3.8.2
Captures and buffers streamed imaged data from the Axsun Ethernet/PCIe DAQ and displays or retrieves images to a client application on request.

This is cross-platform example source code showing how to use the file loading and exporting functionality of AxsunOCTCapture in a C++ client application. It uses the traditional polling approach to retrieve images from the Main Image Buffer.

// AxsunOCTCapture_example_LoadExport.cpp
// 1. AxsunOCTCapture functions are Standard C and do NOT throw C++ exceptions, but rather
// return an error status of type AxErr. Calls to AxsunOCTCapture functions in this
// example program are typically wrapped in an "if (status != OK) throw AxErr" fashion
// and contained in a try/catch block in order to make the behavior exception-based.
// 2. The intent of this example program is to exemplify the capabilities of the
// AxsunOCTCapture library. Program structure is simplified for readability and is not
// intended for "production" use as-is.
// include for all AxsunOCTCapture functions, structs, enums, typedefs
// STL includes for this example application; NOT related to AxsunOCTCapture functionality
#include <iostream> // for std::cout
#include <filesystem> // for managing save/export paths
#include <algorithm> // for std::for_each_n
#include <vector>
// Define an AxsunOCTCapture class to wrap axStartSession(), axStopSession(), and the session handle in RAII fashion.
// (This will convieniently call axStopSession() automatically in the destructor so that resources are cleaned up.)
class AxsunOCTCapture {
AOChandle session_{ nullptr }; // AOChandle is an opaque struct
AxsunOCTCapture(float size) { if (auto retval = axStartSession(&session_, size); retval != AxErr::NO_AxERROR) throw retval; }
~AxsunOCTCapture() { axStopSession(session_); }
AOChandle operator()() { if (session_) return session_; else throw AxErr::CAPTURE_SESSION_NOT_SETUP; }
// callback function executed for every image exported
void ExportCallback(int32_t image, void* userdata) {
if (!(image % 50)) // report every 50th image by printing to console
std::cout << "Export Callback: Image # " << image << "\n";
int main(int argc, char* argv[]) {
char message[512]{""}; // for getting string output from axGetMessage() and axGetErrorString()
if (argc != 2) {
std::cout << "**** Please pass one argument: the path to a valid data file. ****\n";
return 0;
try {
std::cout << "Welcome to the AxsunOCTCapture Load & Export Example Application.\n";
// create an AxsunOCTCapture session
// (this is the first step in any AxsunOCTCapture application)
auto AOC = AxsunOCTCapture{ 250.0f }; // argument is buffer size in MB
// register callback functions for image export progress
axRegisterExportCallback(AOC(), ExportCallback, nullptr);
// initialize some paths for loaded buffer and exported image files
auto loadfile = std::filesystem::path(argv[1]);
auto parent_dir = loadfile.parent_path();
auto export_dir = parent_dir / "Exported";
std::cout << "Loading file at " << loadfile << "\n";
auto tempnumber = int32_t{ 0 }; // a temp variable for passing by pointer to Load and Export functions
// LOAD a previously-saved image buffer
if (auto retval = axLoadFile(AOC(), loadfile.string().c_str(), &tempnumber); retval != AxErr::NO_AxERROR) throw retval;
std::cout << "Loaded " << tempnumber << " packets from disk.\n";
// declare local variables for axGetStatus()
uint32_t imaging{ 0 }, last_packet{ 0 }, last_frame{ 0 }, last_image{ 0 }, dropped_packets{ 0 }, frames_since_sync{ 0 };
// query the status of the Main Image Buffer after loading
if (auto retval = axGetStatus(AOC(), &imaging, &last_packet, &last_frame, &last_image, &dropped_packets, &frames_since_sync); retval != AxErr::NO_AxERROR) throw retval;
std::cout << "There are now " << last_image << " images in the Main Image Buffer.\n";
// declare local variables for axGetImageInfo() and axRequestImage()
auto prefs = request_prefs_t{
.crop_width_total = 2000 // crop retrieved images to this maximum width
auto info = image_info_t{};
// allocate a large enough user buffer to cover image sizes up to 2048 x 2000 x 4 bytes/pix
// (NOTE: you can resize appropriately depending on your application)
constexpr auto buffer_size = size_t{ 2048 * 2000 * 4 };
auto image_buffer = std::vector<uint8_t>(buffer_size);
// Loop once thru the full Main Image Buffer of loaded images
for (auto i = 1; i <= last_image; ++i) {
if (auto retval = axGetImageInfo(AOC(), i, &info); retval != AxErr::NO_AxERROR) {
// get and then print error details
axGetErrorString(retval, message);
std::cout << "axGetImageInfo() returned " << static_cast<int32_t>(retval) << " " << message << '\n';
else {
// if no errors in axGetImageInfo() then request the image to be copied into client's image_buffer
retval = axRequestImage(AOC(), info.image_number, prefs, buffer_size,, &info);
// here is where you can save, display, analyze, or otherwise //
// do whatever you want with the data now in your image_buffer! //
// print a sample of pixel values (as 8-bit) to the console every 50th image
if (!(i % 50)) {
std::for_each_n(image_buffer.begin(), 10, [](const auto& x) {std::cout << "\t" << +x; });
std::cout << "\n";
// EXPORT individual images using axExportImagesAdv()
// (this is an advanced version which passes two preferences structures for maximum adjustability)
auto request_prefs = request_prefs_t{
.crop_width_total = 700
auto export_prefs = export_prefs_t{
.width = 640,
.height = 480,
.contrast = 1.0,
.brightness = 0.0,
.colormap = AxColormap::SEPIA,
.movie_fps = 60
if (auto retval = axExportImagesAdv(AOC(), export_dir.string().c_str(), &tempnumber, AxFileType::PNG, 1, last_image, request_prefs, export_prefs); retval != AxErr::NO_AxERROR) throw retval;
std::cout << "Exported " << tempnumber << " individual images to " << export_dir << "\n";
catch (const AxErr& e) {
axGetErrorString(e, message);
std::cout << "ERROR: " << message << '\n';
catch (...) {
std::cout << "***** UNKNOWN ERROR. Program terminating.\n";
std::cout << "Done.\n\n";
Error codes returned from AxsunOCTCapture or AxsunOCTControl_LW functions. Use axGetErrorString() in ...
Definition: AxsunCommonEnums.h:40
This header file contains all exported function prototypes, structures, and enums necessary for integ...
AxErr __cdecl axGetImageInfo(AOChandle session, uint32_t requested_image, image_info_t *image_info)
Get information on an image in the Main Image Buffer.
struct CaptureSession * AOChandle
Axsun OCT Capture handle - a pointer to the opaque structure used to manage created capture sessions.
Definition: AxsunOCTCapture.h:170
AxErr __cdecl axStopSession(AOChandle session)
Stop a capture session and deallocate all resources, including Main Image Buffer and interfaces.
AxErr __cdecl axExportImagesAdv(AOChandle session, const char *path_directory, int32_t *images_exported, AxFileType file_type, uint32_t start_image, uint32_t end_image, request_prefs_t request_prefs, export_prefs_t export_prefs)
Export images from the Main Image Buffer into individual graphics and movie files,...
AxErr __cdecl axRegisterExportCallback(AOChandle session, AxCallbackFunction_t callback_function, void *user_data)
Registers a callback function to be executed each time an image is exported using axExportImages(),...
AxErr __cdecl axStartSession(AOChandle *session, float capacity_MB)
Start an Axsun DAQ imaging session by allocating memory for the Main Image Buffer.
AxErr __cdecl axLoadFile(AOChandle session, const char *path_file, int32_t *packets_read)
Load contents from file on disk into Main Image Buffer.
AxErr __cdecl axRequestImage(AOChandle session, uint32_t requested_image, request_prefs_t prefs, uint32_t output_buf_len, uint8_t *image_data_out, image_info_t *image_info)
Retrieve and/or display an image from the Main Image Buffer.
Definition: AxsunOCTCapture.h:225
AxErr __cdecl axGetStatus(AOChandle session, uint32_t *imaging, uint32_t *last_packet_in, uint32_t *last_frame_in, uint32_t *last_image_in, uint32_t *dropped_packets, uint32_t *frames_since_sync)
Get imaging mode status and Main Image Buffer statistics.
void __cdecl axGetErrorString(AxErr errorcode, char *message_out)
Get a description of a specific AxErr error code.
Definition: AxsunOCTCapture.h:211
Structure for image export preferences (movie functionality requires installation of OpenCV).
Definition: AxsunOCTCapture.h:419
uint32_t width
Definition: AxsunOCTCapture.h:421
Structure for conveying metadata information about an image.
Definition: AxsunOCTCapture.h:452
Structure for image request preferences.
Definition: AxsunOCTCapture.h:386
uint32_t average_number
Definition: AxsunOCTCapture.h:393
AxRequestMode request_mode
Definition: AxsunOCTCapture.h:389