FocalSpec Sensor API

Introduction

This document specifies the functions and parameters of the FocalSpec Sensor API (SDK).

Requirements

Supported Platforms

• Windows 10 Professional 32-bit or 64-bit
• Linux (tested to work in Ubuntu 64-bit 18.04.1 LTS, although there are not any distribution-specific requirements)

Hardware Requirements

• Gigabit Ethernet for LCI401, LCI1200, LCI1201 and LCI1600 sensors
• 10 Gigabit Ethernet for LCI1220 and LCI1620 sensors

Software Compatibility Chart

Open FW FSSDK Sensor Compatibility Chart.pdf from FocalSpec Software Development Kit folder.

Installation

Windows

Run setup-X.Y.Z.exe from the USB drive or SharePoint to install FSSDK. X.Y.Z is the FSSDK version number.

Linux

Download Intel IPP library from Intel: https://software.intel.com/en-us/ipp. Unpack the downloaded package and install it by running the included install_GUI.sh or install.sh as root. By default, the library will be installed in /opt/intel/ipp.

Download Intel MKL library from Intel: https://software.intel.com/en-us/mkl. Unpack the downloaded package and install it by running the included install_GUI.sh or install.sh as root. By default, the library will be installed in /opt/intel/mkl.

Unpack fssdk-X.Y.Z-linux.tar.gz from the USB drive or SharePoint to the installation folder. X.Y.Z is the FSSDK version number. Default target folder: ./fssdk.

tar xzvf fssdk-X.Y.Z-linux.tar.gz

Installation option 1: installer script.

Run fssdk/install.sh as root. By default, the target installation folder is /opt/fssdk. You can change this by option --target=TARGET. Use option --help for help.

# Installation to /opt/fssdk:
cd fssdk
sudo ./install.sh

This will:

• Copy files to target folder.
• Generate fssdk-env.sh file which will contain the required environment variables.

Either run fssdk-env.sh from profile script (such as ~/.bashrc), or copy-paste its content to the profile script.

Make sure the Intel IPP and MKL library path variables in the fssdk-env.sh are correct.

Installation option 2: manual installation.

Copy the FSSDK files to a desired location.

Set the following environment variables:

• FSSDK_PATH: path to the top folder of FSSDK installation (e.g. /opt/fssdk).
• IPP_PATH: path to Intel IPP library (e.g. /opt/intel/ipp).
• MKL_PATH: path to Intel MKL library (e.g. /opt/intel/mkl).
• LD_LIBRARY_PATH: add the path to FSSDK API folder (FSSDK_PATH/API), and IPP and MKL libraries (IPP_PATH/lib/intel64, MKL_PATH/lib/intel64).

The environment variables can be set by adding the following lines to ~/.bashrc or other profile script. Modify paths as necessary.

# Path to FSSDK
export FSSDK_PATH=/opt/fssdk
# Path to Intel IPP library
export IPP_PATH=/opt/intel/ipp
# Path to Intel MKL library
export MKL_PATH=/opt/intel/mkl
# Library search path
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$FSSDK_PATH/API:$IPP_PATH/lib/intel64:$MKL_PATH/lib/intel64

To apply environment variables immediately, run the following command:

source ~/.bashrc

Folder Structure

• API - The API.
• ConsoleExample - Example cross-platform C/C++ project to start with.
• Drivers - Drivers needed to run the API. Windows-only.
• GuiExample - Example C#/.Net application with graphical user interface (Windows Forms) to start with. Windows-only.
• FocalSpec SDK Demo - Simplified example C#/.Net application with graphical user interface (XAML). Windows-only.
• LabViewExample - Example LabView application.
• Manual - This documentation.

API Files

Windows

Library	Description
Vevo.dll	FSAPI DLL
Vevo.lib	FSAPI library file for DLL linking
FsApiNet.dll	FSAPI .Net wrapper library.
vevo-win32.dll	Communication library used by Win32 Vevo.dll
vevo-x64.dll	Communication library used by x64 Vevo.dll

Linux

Library	Description
libvevo.so	FSAPI shared library
libvevobase.so	Communication library used by libvevo.so

Header Files

Header	Description
CameraDll.h	FSAPI library function signatures
Callback.h	Callback function signatures
CameraStatus.h	Return value listing
PeakStructure.h	Peak format description
VevoParameterDefinitions.h	FSAPI parameters

Creating an Application

In short, the API design follows a common practice:

1. open API
2. initialize a camera
3. start receiving data
4. do something with the data
5. stop receiving data
6. close API

In function level, the flow is usually as follows:

int camera_count = 1; // One camera expected
char **camera_ids = NULL;

// Open API and discover cameras that respond within 2000ms. If expected camera count is not reached an additional 20 seconds timeout is waited.
// As a result, we get number of cameras and their IDs that we need to control them.
_Open(&camera_count, &camera_ids, 2000)

// Connect to a camera of interest. Let it be the first one. Use auto-ip.
_Connect(camera_ids[0], NULL);

int calibrations_in_camera = 0;
_GetIntParameter(camera_ids[0], const_cast<char*>(PARAM_SENSOR_DATA_IN_FLASH), &calibrations_in_camera);

if(!calibrations_in_camera)
{
   // Assign Z calibration file.
   _SetStringParameter(camera_ids[0], PARAM_SENSOR_CALIBRATION_FILE, "C:\\temp\\zcalibration.calib");

   // Assign X calibration file.
   _SetStringParameter(camera_ids[0], PARAM_SENSOR_X_CALIBRATION_FILE, "C:\\temp\\xcalibration.calib");
}

_SetStringParameter(camera_ids[0], PARAM_LOAD_RECIPE, "Recipe"));

// Set sorting order for line callback
_SetLineSortingOrder(camera_ids[0], SurfaceSorting::FROM_TOP_TO_BOTTOM);

// Register a callback function
_SetLineCallback(camera_ids[0], 0, LineCallbackHandler);

// Start data reception, which will automatically fire your corresponding callback
_StartGrabbing(camera_ids[0]);

// Do some application specific operations at the callback.
// ...

// Time to close application. Stop data reception and close the API.
_StopGrabbing(camera_ids[0]);
_Close();

Below is an example of a line callback.

void LineCallbackHandler(char *cameraID, int layerId, float *zValues, float *intensityValues, int line_length, double xStep, HEADER *header)
{
    // Place you application code here.

    // Make this function fast and non-blocking (parameter points_in_queue should not accumulate over time).
    // One approach to achieve this is to push values into a buffer, which is processed by another consumer thread.
}

Example Projects

There are four example projects with source codes included:

1. GuiExample: graphical user interface example, written in C#/.Net, Windows only. To open and run it, please open GuiExample\GuiExample.sln with VisualStudio.
2. FocalSpec SDK Demo: simplified graphical user interface example, written in C#/.Net, Windows only. To open and run it, please open FocalSpec SDK Demo\FocalSpec_SDK_Demo.sln with VisualStudio.
3. ConsoleExample: cross-platform CLI example, written in C/C++.
4. LabViewExample: example GUI application, written in LabView.

It is recommended to start with GuiExample, since they provide visual feedback. More information about GuiExample can be found from manual.pdf.

Building ConsoleExample

Windows

Open ConsoleExample\ConsoleExample.sln and read instructions from ConsoleExample.cpp.

Linux

Install the necessary build tools, such as build-essential and cmake.

Build with CMake:

cd ConsoleExample
mkdir build
cd build
cmake ..
make

Change Log

Change log is provided as a PDF file (Changelog.pdf) contained in the API folder of the SDK installation folder.