i3camera_web_logo

I3Camera C++ library

v1.2.0

Overview
Versions
Library files
I3Camera class description
Data structures
VSourceParams class description
CameraParams class description
Build and connect to your project
Simple example
Test application

Overview

The I3Camera C++ library is a video capture and software controller for THERMAL EXPERT cameras. The I3Camera library supports Q1, Q2, V1, V2, EQ1, EQ2, EV1 and EV2 USB camera models. The library inherits interfaces from VSource and Camera. It depends on libraries: VSource (provides interface and data structures to capture video from cameras, source code included, Apache 2.0 license), Camera (provides interface and data structures to control cameras, source code, Apache 2.0 license), Logger (provides function to print logs, source code included, Apache 2.0 license). The I3Camera library provides simple interface to be integrated in any C++ projects. The library depends on i3camera SDK that provides communication with camera via an USB port. Additionally test application depends on OpenCV. It is developed with C++17 standard and compatible with Linux and Windows.

Versions

Table 1 - Library versions.

Version	Release date	What’s new
1.0.0	17.01.2025	- First version.
1.1.0	03.02.2025	- Init string parameter is changed from camera index to camera id. - New method is added for detection of available cameras ids.
1.2.0	13.02.2025	- Internal thread is removed, reading new frame is done directly in getFrame method.

Library files

The library supplied by source code only. The user would be given a set of files in the form of a CMake project (repository). The repository structure is shown below:

CMakeLists.txt ------------ Main CMake file of the library.
3rdparty ------------------ Folder with third-party libraries.
    CMakeLists.txt -------- CMake file which includes third-party libraries.
    Camera ---------------- Folder with Camera library source code.
    VSource --------------- Folder with VSource library source code.
    Logger ---------------- Folder with Logger library source code.
test ---------------------- Folder with test application.
    CMakeLists.txt -------- CMake file for test application.
    main.cpp -------------- Source code file of test application.
example ------------------- Folder with example application.
    CMakeLists.txt -------- CMake file for example application.
    main.cpp -------------- Source code file of example application.
src ----------------------- Folder with source code of the library.
    CMakeLists.txt -------- CMake file of the library.
    impl ------------------ Folder with library implementation files.
        I3CameraImpl.h ---- Header file which includes I3CameraImpl class declaration.
        I3CameraImpl.Cpp -- Source code file of the library.
    I3Camera.cpp ---------- Source code file of the library.
    I3Camera.h ------------ Header file which includes I3Camera class declaration.
    I3CameraVersion.h ----- Header file which includes version of the library.
    I3CameraVersion.h.in -- CMake service file to generate version file.

I3Camera class description

I3Camera class declaration

I3Camera class declared in I3Camera.h file. The I3Camera class includes VSource and Camera interfaces. So, the I3Camera class includes set of similar methods (for video source and camera control). Class declaration:

namespace cr
{
namespace video
{
class I3Camera : public VSource, public cr::camera::Camera 
{
public:

    /// Class constructor.
    I3Camera();

    /// Class destructor.
    ~I3Camera();

    /// Get version of the library.
    static std::string getVersion();

    /// Detect available cameras.
    static std::vector<std::string> detectAvailableCameras();

    /// Decode and execute command.
    bool decodeAndExecuteCommand(uint8_t *data, int size) override;

    // #######################################
    // VIDEO SOURCE INTERFACE
    // #######################################

    /// Open video source by initialization string.
    bool openVSource(std::string &initString) override;

    /// Init video source by parameters structure.
    bool initVSource(VSourceParams &params) override;

    /// Check if video source is open.
    bool isVSourceOpen() override;

    /// Close video source.
    void closeVSource() override;

    /// Get video source frame.
    bool getFrame(Frame &frame, int32_t timeoutMsec = 0) override;

    /// Set video source parameter.
    bool setParam(VSourceParam id, float value) override;

    /// Get video source parameter.
    float getParam(VSourceParam id) override;

    /// Get video source params.
    void getParams(VSourceParams &params) override;

    /// Execute video source command.
    bool executeCommand(VSourceCommand id) override;

    // #######################################
    // CAMERA CONTROL INTERFACE
    // #######################################

    /// Open camera controller by initialization string.
    bool openCamera(std::string initString) override;

    /// Init camera controller by parameters structure.
    bool initCamera(cr::camera::CameraParams &params) override;

    /// Close camera controller.
    void closeCamera() override;

    /// Check if camera controller is open.
    bool isCameraOpen() override;

    /// Check if camera controller is connected.
    bool isCameraConnected() override;

    /// Set camera parameter.
    bool setParam(cr::camera::CameraParam id, float value) override;

    /// Get camera parameter.
    float getParam(cr::camera::CameraParam id) override;

    /// Get camera params.
    void getParams(cr::camera::CameraParams &params) override;

    /// Execute camera command.
    bool executeCommand(cr::camera::CameraCommand id) override;
};
}
}

getVersion method

The getVersion() returns string of I3Camera class version. Method declaration:

static std::string getVersion();

Method can be used without I3Camera class instance:

std::cout << "I3Camera class version: " << cr::video::I3Camera::getVersion();

Console output:

I3Camera class version: 1.2.0

detectAvailableCameras method

The detectAvailableCameras() method detects available cameras connected to the system. It returns the unique identifiers of the connected cameras. The unique id is required to initialize the camera by openCamera or openVsource methods. Method declaration:

static std::vector<std::string> detectAvailableCameras();

Method can be used without I3Camera class instance:

std::vector<std::string> cameras = cr::video::I3Camera::detectAvailableCameras();
for (const auto &camera : cameras)
{
    std::cout << "Camera: " << camera << std::endl;
}

Console output:

Camera: 1234
Camera: 5678
Camera: 9012

Returns: vector of strings with unique identifiers of the connected cameras. If no cameras connected, the method will return empty vector.

openVSource method

The openVSource(…) opens the connection to I3Camera camera.openCamera(…) or openVSource(…) methods (not matter which) can be used interchangeably. If camera is already initialized by any of initialization methods, the method will return TRUE. Camera and video source parameters will be initialized by default. Method declaration:

bool openVSource(std::string initString) override;

Parameter	Value
initString	Unique camera identifier. In order to detect the id for a camera see detectAvailableCameras method. Remaining default parameters : - Agc mode : on - Gain : 40% - FPS : 30.

Returns: TRUE if the video source initialized or FALSE if not.

openCamera method

The openCamera(…) opens the connection to I3Camera camera. openCamera(…) or openVSource(…) methods (not matter which) can be used interchangeably. If camera is already initialized by any of initialization methods, the method will return TRUE. Camera and video source parameters will be initialized by default. Method declaration:

bool openCamera(std::string initString) override;

Parameter	Value
initString	Unique camera identifier. In order to detect the id for a camera see detectAvailableCameras method. Remaining default parameters : - Agc mode : on - Gain : 40% - FPS : 30.

Returns: TRUE if the camera controller initialized or FALSE if not.

initVSource method

The initVSource(…) initializes video source and sets video source params (VSource interface). The method initializes camera params (Camera interface) as well by default values. Method declaration:

bool initVSource(cr::video::VSourceParams& params) override;

Parameter	Value
params	VSourceParams class object. VSourceParams class includes initString which used in same way as openVSource(…) method.

Returns: TRUE if the video source initialized or FALSE if not.

initCamera method

The initCamera(…) initializes controller and sets camera params (Camera interface). The method initialize video source params (VSource interface) as well by default values. Method declaration:

bool initCamera(CameraParams& params) override;

Parameter	Value
params	CameraParams class object. CameraParams class includes initString which used in same way as openCamera(…) method.

Returns: TRUE if the camera controller initialized or FALSE if not.

getFrame method

The getFrame(…) reads a video frame from I3Camera.

bool getFrame(Frame &frame, int32_t timeoutMsec = 0) override;

Parameter	Value
frame	Refence to Frame instance for new frame.
timeoutMsec	Timeour for reading frame. Value : </br> -1 : Wait until new frame comes. </br> 0 : Return immediately if there is new frame, or return without a frame. </br> timeoutValue : Wait until new frame comes or timeout passes.

Returns: TRUE if new frame read or FALSE if not.

closeVSource method

The closeVSource() closes the connection to camera. The result of the method is equal to closeCamera(…) method (user can use any of them). Method declaration:

void closeVSource() override;

closeCamera method

closeCamera() closes the connection to camera. The result of the method is equal to closeVSource(…) method (user can use any of them). Method declaration:

void closeCamera() override;

isVSourceOpen method

The isVSourceOpen() method returns video source initialization status. Open status shows if the video source initialized but doesn’t show if controller has communication with equipment. This method is equal to isCameraOpen(…) and isCameraConnected methods. Method declaration:

bool isVSourceOpen() override;

Returns: TRUE is the video source initialized or FALSE if not.

isCameraOpen method

The isCameraOpen() method returns controller initialization status. Open status shows if the controller initialized but doesn’t show if controller has communication with equipment. This method is equal to isVSourceOpen(…) and isCameraConnected methods. Method declaration:

bool isCameraOpen() override;

Returns: TRUE is the controller initialized or FALSE if not.

isCameraConnected method

The isCameraConnected() is equal to isCameraOpen(…) and isVSourceOpen methods. Method declaration:

bool isCameraConnected() override;

Returns: TRUE is the controller initialized or FALSE if not.

setParam method

The setParam(…) is an overloaded method. The method intended to set Camera or VSource parameter value. Method declaration:

bool setParam(VSourceParam id, float value) override;
bool setParam(CameraParam id, float value) override;

Parameter	Description
id	Video source parameter ID according to VSourceParam enum or camera parameter ID according to CameraParam enum.
value	Camera or VSource parameter value. Valid values depend on parameter ID.

Returns: TRUE if the parameter is set (accepted by controller) or FALSE if not.

getParam method

The getParam(…) is an overloaded method. The method intended to obtain Camera or VSource parameter value. Method declaration:

float getParam(VSourceParam id) override;
float getParam(CameraParam id) override;

Parameter	Description
id	Video source parameter ID according to VSourceParam enum or camera parameter ID according to CameraParam enum.

Returns: parameter value or -1.0f of the parameters not supported.

getParams method

The getParams(…) is an overloaded method. The method intended to obtain Camera or VSource parameters structure. Method declaration:

void getParams(VSourceParams& params) override;
void getParams(CameraParams& params) override;

Parameter	Description
params	Reference to VSourceParam class object or CameraParams class object.

executeCommand method

The executeCommand(…) is an overloaded method. The method intended to execute Camera or VSource action command. Method declaration:

bool executeCommand(VSourceCommand id) override;
bool executeCommand(CameraCommand id) override;

Parameter	Description
id	Camera command ID according to CameraCommand enum or video source command ID according to VSourceCommand enum.

Returns: TRUE is the command is executed (accepted by controller) or FALSE if not.

decodeAndExecuteCommand method

The decodeAndExecuteCommand(…) method decodes and executes command on controller side. Method will decode commands which encoded by encodeCommand(…) and encodeSetParamCommand(…) methods of VSource and Camera interface classes. If command decoded the method will call setParam(…) or executeCommand(…) methods for VSource or Camera interfaces. Method declaration:

bool decodeAndExecuteCommand(uint8_t* data, int size) override;

Parameter	Description
data	Pointer to input command.
size	Size of the data buffer. Must be 11 bytes for SET_PARAM and COMMAND.

Returns: TRUE if command decoded (SET_PARAM or COMMAND) and executed (action command or set param command).

encodeSetParamCommand method of VSource class

The encodeSetParamCommand(…) static method of VSource interface class designed to encode command to change any remote video source parameter. To control a video source remotely, the developer has to develop his own protocol and according to it encode the command and deliver it over the communication channel. To simplify this, the VSource class contains static methods for encoding the control command. The VSource class provides two types of commands: a parameter change command (SET_PARAM) and an action command (COMMAND). encodeSetParamCommand(…) designed to encode SET_PARAM command. Method declaration:

static void encodeSetParamCommand(uint8_t* data, int& size, VSourceParam id, float value);

Parameter	Description
data	Pointer to data buffer for encoded command. Must have size >= 11.
size	Size of encoded data. Will be 11 bytes.
id	Parameter ID according to VSourceParam enum.
value	Parameter value.

encodeSetParamCommand(…) is static and used without VSource class instance. This method used on client side (control system). Command encoding example:

// Buffer for encoded data.
uint8_t data[11];
// Size of encoded data.
int size = 0;
// Random parameter value.
float outValue = (float)(rand() % 20);
// Encode command.
VSource::encodeSetParamCommand(data, size, VSourceParam::EXPOSURE, outValue);

encodeCommand method of VSource class

The encodeCommand(…) static method of VSource interface class designed to encode video source action command. To control a video source remotely, the developer has to develop his own protocol and according to it encode the command and deliver it over the communication channel. To simplify this, the VSource class contains static methods for encoding the control command. The VSource class provides two types of commands: a parameter change command (SET_PARAM) and an action command (COMMAND). encodeCommand(…) designed to encode COMMAND command (action command). Method declaration:

static void encodeCommand(uint8_t* data, int& size, VSourceCommand id);

Parameter	Description
data	Pointer to data buffer for encoded command. Must have size >= 7 bytes.
size	Size of encoded data. Will be 7 bytes.
id	Command ID according to VSourceCommand enum.

encodeCommand(…) is static and used without VSource class instance. This method used on client side (control system). Command encoding example:

// Buffer for encoded data.
uint8_t data[11];
// Size of encoded data.
int size = 0;
// Encode command.
VSource::encodeCommand(data, size, VSourceCommand::RESTART);

decodeCommand method of VSource class

decodeCommand(…) static method of VSource interface class designed to decode command on video source controller side. To control a video source remotely, the developer has to develop his own protocol and according to it decode the command on video source controller side. To simplify this, the VSource interface class contains static method to decode input command (commands should be encoded by methods encodeSetParamsCommand(…) or encodeCommand(…)). The VSource class provides two types of commands: a parameter change command (SET_PARAM) and an action command (COMMAND). Method declaration:

static int decodeCommand(uint8_t* data, int size, VSourceParam& paramId, VSourceCommand& commandId, float& value);

Parameter	Description
data	Pointer to input command.
size	Size of command. Should be 11 bytes for SET_PARAM and 7 bytes for COMMAND.
paramId	Parameter ID according to VSourceParam enum. After decoding SET_PARAM command the method will return parameter ID.
commandId	Command ID according to VSourceCommand enum. After decoding COMMAND the method will return command ID.
value	Parameter value (after decoding SET_PARAM command).

Returns: 0 - in case decoding COMMAND, 1 - in case decoding SET_PARAM command or -1 in case errors.

encodeSetParamCommand method of Camera class

encodeSetParamCommand(…) static method of Camera interface class encodes command to change any remote camera parameter value. To control a camera remotely, the developer has to design his own protocol and according to it encode the command and deliver it over the communication channel. To simplify this, the Camera class contains static methods for encoding the control command. The Camera class provides two types of commands: a parameter change command (SET_PARAM) and an action command (COMMAND). encodeSetParamCommand(…) designed to encode SET_PARAM command. Method declaration:

static void encodeSetParamCommand(uint8_t* data, int& size, CameraParam id, float value);

Parameter	Description
data	Pointer to data buffer for encoded command. Must have size >= 11.
size	Size of encoded data. Will be 11 bytes.
id	Parameter ID according to CameraParam enum.
value	Parameter value.

encodeSetParamCommand(…) is static and used without Camera class instance. This method used on client side (control system). Command encoding example:

// Buffer for encoded data.
uint8_t data[11];
// Size of encoded data.
int size = 0;
// Encode command.
Camera::encodeSetParamCommand(data, size, CameraParam::EXPOSURE_MODE, 2);

encodeCommand method of Camera class

encodeCommand(…) static method of Camera interface class encodes command for camera remote control. To control a camera remotely, the developer has to design his own protocol and according to it encode the command and deliver it over the communication channel. To simplify this, the Camera class contains static methods for encoding the control command. The Camera class provides two types of commands: a parameter change command (SET_PARAM) and an action command (COMMAND). encodeCommand(…) designed to encode COMMAND command (action command). Method declaration:

static void encodeCommand(uint8_t* data, int& size, CameraCommand id);

Parameter	Description
data	Pointer to data buffer for encoded command. Must have size >= 7.
size	Size of encoded data. Will be 7 bytes.
id	Command ID according to CameraCommand enum.

encodeCommand(…) is static and used without Camera class instance. This method used on client side (control system). Command encoding example:

// Buffer for encoded data.
uint8_t data[7];
// Size of encoded data.
int size = 0;
// Encode command.
Camera::encodeCommand(data, size, CameraCommand::NUC);

decodeCommand method of Camera class

decodeCommand(…) static method of Camera interface class decodes command on camera controller side. Method declaration:

static int decodeCommand(uint8_t* data, int size, CameraParam& paramId, CameraCommand& commandId, float& value);

Parameter	Description
data	Pointer to input command.
size	Size of command. Must be 11 bytes for SET_PARAM and 7 bytes for COMMAND.
paramId	Camera parameter ID according to CameraParam enum. After decoding SET_PARAM command the method will return parameter ID.
commandId	Camera command ID according to CameraCommand enum. After decoding COMMAND the method will return command ID.
value	Camera parameter value (after decoding SET_PARAM command).

Returns: 0 - in case decoding COMMAND, 1 - in case decoding SET_PARAM command or -1 in case errors.

Data structures

VSourceCommand enum

Enum declaration:

enum class VSourceCommand
{
    /// Restart.
    RESTART = 1
};

Table 2 - Video source commands description.

Command	Description
RESTART	Not supported by I3Camera library.

CameraCommand enum

Enum declaration:

namespace cr
{
namespace camera
{
enum class CameraCommand
{
    /// Restart camera controller.
    RESTART = 1,
    /// Do NUC.
    NUC,
    /// Apply settings.
    APPLY_PARAMS,
    /// Save params.
    SAVE_PARAMS,
    /// Menu on.
    MENU_ON,
    /// Menu off.
    MENU_OFF,
    /// Menu set.
    MENU_SET,
    /// Menu up.
    MENU_UP,
    /// Menu down.
    MENU_DOWN,
    /// Menu left.
    MENU_LEFT,
    /// Menu right.
    MENU_RIGHT,
    /// Freeze, Argument: time msec.
    FREEZE,
    /// Disable freeze.
    DEFREEZE
};
}
}

Table 3 - Camera commands description.

Command	Description
RESTART	Not supported by I3Camera library.
NUC	NUC command.
APPLY_PARAMS	Not supported by I3Camera library.
SAVE_PARAMS	Not supported by I3Camera library.
MENU_ON	Not supported by I3Camera library.
MENU_OFF	Not supported by I3Camera library.
MENU_SET	Not supported by I3Camera library.
MENU_UP	Not supported by I3Camera library.
MENU_DOWN	Not supported by I3Camera library.
MENU_LEFT	Not supported by I3Camera library.
MENU_RIGHT	Not supported by I3Camera library.
FREEZE	Not supported by I3Camera library.
DEFREEZE	Not supported by I3Camera library.

VSourceParam enum

Enum declaration:

enum class VSourceParam
{
    /// [read/write] Logging mode. Values: 0 - Disable, 1 - Only file,
    /// 2 - Only terminal, 3 - File and terminal.
    LOG_LEVEL = 1,
    /// [read/write] Frame width. User can set frame width before initialization
    /// or after. Some video source classes may set width automatically.
    WIDTH,
    /// [read/write] Frame height. User can set frame height before
    /// initialization or after. Some video source classes may set height
    /// automatically.
    HEIGHT,
    /// [read/write] Gain mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual control, 1 - Auto.
    GAIN_MODE,
    /// [read/write] Gain value. Value: 0(min for particular video source class)
    /// - 65535(max for particular video source class).
    GAIN,
    /// [read/write] Exposure mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual control, 1 - Auto.
    EXPOSURE_MODE,
    /// [read/write] Exposure value. Value: 0(min for particular video source
    /// class) - 65535(max for particular video source class).
    EXPOSURE,
    /// [read/write] Focus mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual control, 1 - Auto.
    FOCUS_MODE,
    /// [read/write] Focus position. Value: 0(full near) - 65535(full far).
    FOCUS_POS,
    /// [read only] Video capture cycle time. **VSource** class sets this value
    /// automatically. This parameter means time interval between two captured
    /// video frame.
    CYCLE_TIME_MKS,
    /// [read/write] FPS. User can set frame FPS before initialization or after.
    /// Some video source classes may set FPS automatically.
    FPS,
    /// [read only] Open flag. 0 - not open, 1 - open.
    IS_OPEN,
    /// Region of interest upper left corner x coordinate.
    ROI_X,
    /// Region of interest upper left corner y coordinate.
    ROI_Y,
    /// Region of interest width.
    ROI_WIDTH,
    /// Region of interest height.
    ROI_HEIGHT,
    /// [read/write] Custom parameter. Depends on implementation.
    CUSTOM_1,
    /// [read/write] Custom parameter. Depends on implementation.
    CUSTOM_2,
    /// [read/write] Custom parameter. Depends on implementation.
    CUSTOM_3
};

Table 4 - Video source params description. Some params are not supported in VSourceOpenCv implementation.

Parameter	Access	Description
LOG_LEVEL	read / write	Logging mode. Values: 0 - Disable, 1 - Only file, 2 - Only terminal (console), 3 - File and terminal.
WIDTH	read / write	Not supported to set. Read only. Frame size is not adjustable in i3 cameras. Each camera has constant frame resolution.
HEIGHT	read / write	Not supported to set. Read only. Frame size is not adjustable in i3 cameras. Each camera has constant frame resolution.
GAIN_MODE	read / write	Not supported by I3Camera library.
GAIN	read / write	Gain value in percentage. It is internally mapped to pretested camera gain values.
EXPOSURE_MODE	read / write	Not supported by I3Camera library.
EXPOSURE	read / write	Not supported by I3Camera library.
FOCUS_MODE	read / write	Not supported by I3Camera library.
FOCUS_POS	read / write	Not supported by I3Camera library.
CYCLE_TIME_MKS	read only	Video capture cycle time, microseconds. I3Camera class sets this value automatically depending on input FPS. This parameter means time interval in microseconds between two captured video frame.
FPS	read / write	FPS value that is set to i3 camera, the fps value is not supposed to be same as fps camera can provide.
IS_OPEN	read only	Open flag. 0 - not open, 1 - open (Video source is initialized).
ROI_X	read / write	Not supported by I3Camera library.
ROI_Y	read / write	Not supported by I3Camera library.
ROI_WIDTH	read / write	Not supported by I3Camera library.
ROI_HEIGHT	read / write	Not supported by I3Camera library.
CUSTOM_1	read / write	Not supported by I3Camera library.
CUSTOM_2	read / write	Not supported by I3Camera library.
CUSTOM_3	read / write	Not supported by I3Camera library.

CameraParam enum

Enum declaration:

namespace cr
{
namespace camera
{
enum class CameraParam
{
    /// Video frame width. Value from 0 to 16384.
    WIDTH = 1,
    /// Video frame height Value from 0 to 16384.
    HEIGHT,
    /// Display menu mode.
    DISPLAY_MODE,
    /// Video output type.
    VIDEO_OUTPUT,
    /// Logging mode.
    LOG_MODE,
    /// Exposure mode.
    EXPOSURE_MODE,
    /// Exposure time of the camera sensor.
    EXPOSURE_TIME,
    /// White balance mode.
    WHITE_BALANCE_MODE,
    /// White balance area.
    WHITE_BALANCE_AREA,
    /// White dynamic range mode.
    WIDE_DYNAMIC_RANGE_MODE,
    /// Image stabilization mode.
    STABILIZATION_MODE,
    /// ISO sensitivity.
    ISO_SENSITIVITY,
    /// Scene mode.
    SCENE_MODE,
    /// FPS.
    FPS,
    /// Brightness mode.
    BRIGHTNESS_MODE,
    /// Brightness. Value 0 - 100%.
    BRIGHTNESS,
    /// Contrast. Value 1 - 100%.
    CONTRAST,
    /// Gain mode.
    GAIN_MODE,
    /// Gain. Value 1 - 100%.
    GAIN,
    /// Sharpening mode.
    SHARPENING_MODE,
    /// Sharpening. Value 1 - 100%.
    SHARPENING,
    /// Palette.
    PALETTE,
    /// Analog gain control mode.
    AGC_MODE,
    /// Shutter mode.
    SHUTTER_MODE,
    /// Shutter position. 0 (full close) - 65535 (full open).
    SHUTTER_POSITION,
    /// Shutter speed. Value: 0 - 100%.
    SHUTTER_SPEED,
    /// Digital zoom mode.
    DIGITAL_ZOOM_MODE,
    /// Digital zoom. Value 1.0 (x1) - 20.0 (x20).
    DIGITAL_ZOOM,
    /// Exposure compensation mode.
    EXPOSURE_COMPENSATION_MODE,
    /// Exposure compensation position. 
    EXPOSURE_COMPENSATION_POSITION,
    /// Defog mode.
    DEFOG_MODE,
    /// Dehaze mode.
    DEHAZE_MODE,
    /// Noise reduction mode.
    NOISE_REDUCTION_MODE,
    /// Black and white filter mode.
    BLACK_WHITE_FILTER_MODE,
    /// Filter mode.
    FILTER_MODE,
    /// NUC mode for thermal cameras.
    NUC_MODE,
    /// Auto NUC interval for thermal cameras. 
    AUTO_NUC_INTERVAL_MSEC,
    /// Image flip mode.
    IMAGE_FLIP,
    /// DDE mode.
    DDE_MODE,
    /// DDE level.
    DDE_LEVEL,
    /// ROI top-left horizontal position, pixels.
    ROI_X0,
    /// ROI top-left vertical position, pixels.
    ROI_Y0,
    /// ROI bottom-right horizontal position, pixels.
    ROI_X1,
    /// ROI bottom-right vertical position, pixels.
    ROI_Y1,
    /// Camera temperature, degree.
    TEMPERATURE,
    /// ALC gate.
    ALC_GATE,
    /// Sensor sensitivity.
    SENSETIVITY,
    /// Changing mode (day / night).
    CHANGING_MODE,
    /// Changing level (day / night).
    CHANGING_LEVEL,
    /// Chroma level. Values: 0 - 100%.
    CHROMA_LEVEL,
    /// Details, enhancement. Values: 0 - 100%.
    DETAIL,
    /// Camera settings profile.
    PROFILE,
    /// Connection status (read only). Shows if we have respond from camera.
    /// Value: 0 - not connected, 2 - connected.
    IS_CONNECTED,
    /// Open status (read only):
    /// 1 - camera control port open, 0 - not open.
    IS_OPEN,
    /// Camera type.
    TYPE,
    /// Camera custom param.
    CUSTOM_1,
    /// Camera custom param.
    CUSTOM_2,
    /// Camera custom param.
    CUSTOM_3
};
}
}

Table 5 - Camera params description.

Parameter	Access	Description
WIDTH	read / write	Not supported to set. Read only. Frame size is not adjustable in i3 cameras. Each camera has constant frame resolution.
HEIGHT	read / write	Not supported to set. Read only. Frame size is not adjustable in i3 cameras. Each camera has constant frame resolution.
DISPLAY_MODE	read / write	Not supported by I3Camera library.
VIDEO_OUTPUT	read / write	Not supported by I3Camera library.
LOG_MODE	read / write	Logging mode. Values: 0 - Disable, 1 - Only file, 2 - Only terminal (console), 3 - File and terminal.
EXPOSURE_MODE	read / write	Not supported by I3Camera library.
EXPOSURE_TIME	read / write	Not supported by I3Camera library.
WHITE_BALANCE_MODE	read / write	Not supported by I3Camera library.
WHITE_BALANCE_AREA	read / write	Not supported by I3Camera library.
WIDE_DYNAMIC_RANGE_MODE	read / write	Not supported by I3Camera library.
STABILIZATION_MODE	read / write	Not supported by I3Camera library.
ISO_SENSITIVITY	read / write	Not supported by I3Camera library.
SCENE_MODE	read / write	Not supported by I3Camera library.
FPS	read / write	FPS value that is set to i3 camera, the fps value is not supposed to be same as fps camera can provide.
BRIGHTNESS_MODE	read / write	Not supported by I3Camera library.
BRIGHTNESS	read / write	Not supported by I3Camera library.
CONTRAST	read / write	Not supported by I3Camera library.
GAIN_MODE	read / write	Not supported by I3Camera library.
GAIN	read / write	Gain value in percentage. It is internally mapped to pretested camera gain values.
SHARPENING_MODE	read / write	Not supported by I3Camera library.
SHARPENING	read / write	Not supported by I3Camera library.
PALETTE	read / write	Not supported by I3Camera library.
AGC_MODE	read / write	Analog gain control mode. Values: 0 - Manual, 1 - Auto
SHUTTER_MODE	read / write	Not supported by I3Camera library.
SHUTTER_POSITION	read / write	Not supported by I3Camera library.
SHUTTER_SPEED	read / write	Not supported by I3Camera library.
DIGITAL_ZOOM_MODE	read / write	Not supported by I3Camera library.
DIGITAL_ZOOM	read only	Not supported by I3Camera library.
EXPOSURE_COMPENSATION_MODE	read only	Not supported by I3Camera library.
EXPOSURE_COMPENSATION_POSITION	read / write	Not supported by I3Camera library.
DEFOG_MODE	read / write	Not supported by I3Camera library.
DEHAZE_MODE		Not supported by I3Camera library.
NOISE_REDUCTION_MODE	read / write	Not supported by I3Camera library.
BLACK_WHITE_FILTER_MODE	read only	Not supported by I3Camera library.
FILTER_MODE	read / write	Not supported by I3Camera library.
NUC_MODE	read / write	NUC mode for thermal cameras. Values: 0 - Manual, 1 - Auto.
AUTO_NUC_INTERVAL	read / write	Time interval in milliseconds camera will apply NUC in case NUC_MODE is set to auto. i3 camera supports time values : 30s, 60s, 90s.
IMAGE_FLIP	read / write	Not supported by I3Camera library.
DDE_MODE	read / write	Not supported by I3Camera library.
DDE_LEVEL	read / write	Not supported by I3Camera library.
ROI_X0	read / write	Not supported by I3Camera library.
ROI_Y0	read / write	Not supported by I3Camera library.
ROI_X1	read / write	Not supported by I3Camera library.
ROI_Y1	read / write	Not supported by I3Camera library.
TEMPERATURE	read only	Not supported by I3Camera library.
ALC_GATE	read / write	Not supported by I3Camera library.
SENSITIVITY	read / write	Not supported by I3Camera library.
CHANGING_MODE	read / write	Not supported by I3Camera library.
CHANGING_LEVEL	read / write	Not supported by I3Camera library.
CHROMA_LEVEL	read / write	Not supported by I3Camera library.
DETAIL	read / write	Not supported by I3Camera library.
PROFILE	read / write	Not supported by I3Camera library.
IS_CONNECTED	read only	Controller initialization status. Values: 0 - not open (not initialized), 1 - open (initialized).
IS_OPEN	read only	Controller initialization status. Values: 0 - not open (not initialized), 1 - open (initialized).
TYPE	read / write	Not supported by I3Camera library.
CUSTOM_1	read / write	Not supported by I3Camera library.
CUSTOM_2	read / write	Not supported by I3Camera library.
CUSTOM_3	read / write	Not supported by I3Camera library.

VSourceParams class description

VSourceParams class used for video source initialization or to get all actual params. Also VSourceParams provides structure to write/read params from JSON files (JSON_READABLE macro) and provides methods to encode and decode params.

VSourceParams class declaration

VSourceParams class declared in VSourceParams.h file. Class declaration:

class VSourceParams
{
public:
    /// Logging mode. Values: 0 - Disable, 1 - Only file,
    /// 2 - Only terminal, 3 - File and terminal.
    int logLevel{0};
    /// Video source: file, video stream, video device, camera num, etc.
    std::string source{"/dev/video0"};
    /// FOURCC: RGB24, BGR24, YUYV, UYVY, GRAY, YUV24, NV12, NV21, YU12, YV12.
    /// Value says to video source class which pixel format preferable for
    /// output video frame. Particular video source class can ignore this params
    /// during initialization. Parameters should be set before initialization.
    std::string fourcc{"YUYV"};
    /// Frame width. User can set frame width before initialization
    /// or after. Some video source classes may set width automatically.
    int width{1920};
    /// Frame height. User can set frame height before
    /// initialization or after. Some video source classes may set height
    /// automatically.
    int height{1080};
    /// Gain mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual control, 1 - Auto.
    int gainMode{1};
    /// Gain value. Value: 0(min for particular video source class)
    /// - 65535(max for particular video source class).
    int gain{0};
    /// Exposure mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual control, 1 - Auto.
    int exposureMode{1};
    /// Exposure value. Value: 0(min for particular video source
    /// class) - 65535(max for particular video source class).
    int exposure{1};
    /// Focus mode. Focus mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual control, 1 - Auto.
    int focusMode{1};
    /// Focus position. Value: 0(full near) - 65535(full far).
    int focusPos{0};
    /// Video capture cycle time. **VSource** class sets this value
    /// automatically. This parameter means time interval between two captured
    /// video frame.
    int cycleTimeMks{0};
    /// FPS. User can set frame FPS before initialization or after.
    /// Some video source classes may set FPS automatically.
    float fps{0};
    /// Open flag. 0 - not open, 1 - open.
    bool isOpen{false};
    /// Region of intrest upper left corner x coordinate.
    int roiX{0};
    /// Region of intrest upper left corner y coordinate.
    int roiY{0};
    /// Region of intrest width.
    int roiWidth{0};
    /// Region of intrest heigth.
    int roiHeight{0};
    /// Custom parameter. Depends on implementation.
    float custom1{0.0f};
    /// Custom parameter. Depends on implementation.
    float custom2{0.0f};
    /// Custom parameter. Depends on implementation.
    float custom3{0.0f};

    JSON_READABLE(VSourceParams, logLevel, source, fourcc, width, height,
                  gainMode, exposureMode, focusMode, fps, roiX, roiY,
                  roiWidth, roiHeight, custom1, custom2, custom3);

    /// Copy operator.
    VSourceParams& operator= (const VSourceParams& src);

    /// Encode (serialize) params.
    bool encode(uint8_t* data, int bufferSize, int& size,
                VSourceParamsMask* mask = nullptr);

    /// Decode (deserialize) params.
    bool decode(uint8_t* data, int dataSize);
};

Table 6 - VSourceParams class fields description.

Field	type	Description
logLevel	int	Logging mode. Values: 0 - Disable, 1 - Only file, 2 - Only terminal (console), 3 - File and terminal.
source	string	Unique camera identifier in string format. See detectAvailableCameras method for detection of the ids for connected cameras.
fourcc	string	Pixel format. Always GRAY.
width	int	Video frame width. Frame size is not adjustable in i3 cameras. Each camera has constant frame resolution.
height	int	Video frame height. Frame size is not adjustable in i3 cameras. Each camera has constant frame resolution.
gainMode	int	Not supported by I3Camera library.
gain	int	Gain value in percentage. It is internally mapped to pretested camera gain values.
exposureMode	int	Not supported by I3Camera library.
exposure	int	Not supported by I3Camera library.
focusMode	int	Not supported by I3Camera library.
focusPos	int	Not supported by I3Camera library.
cycleTimeMks	int	Video capture cycle time, microseconds. I3Camera class sets this value automatically depending on input FPS. This parameter means time interval in microseconds between two captured video frame.
fps	float	FPS value that is set to i3 camera, the fps value is not supposed to be same as fps camera can provide.
isOpen	bool	Video source initialization status. Values: 0 - not open (not initialized), 1 - open (initialized).
roiX	int	Not supported by I3Camera library.
roiY	int	Not supported by I3Camera library.
roiWidth	int	Not supported by I3Camera library.
roiHeight	int	Not supported by I3Camera library.
custom1	float	Not supported by I3Camera library.
custom2	float	Not supported by I3Camera library.
custom3	float	Not supported by I3Camera library.

None: VSourceParams class fields listed in Table 4 reflects params set/get by methods setParam(…) and getParam(…).

Serialize VSourceParams

VSourceParams class provides method encode(…) to serialize video source params (fields of VSourceParams class, see Table 6). Serialization of video source params necessary in case when you need to send video source params via communication channels. Method doesn’t encode fields: initString and fourcc. Method provides options to exclude particular parameters from serialization. To do this method inserts binary mask (2 bytes) where each bit represents particular parameter and decode(…) method recognizes it. Method declaration:

bool encode(uint8_t* data, int bufferSize, int& size, VSourceParamsMask* mask = nullptr);

Parameter	Value
data	Pointer to data buffer.
size	Size of encoded data. 79 bytes by default.
bufferSize	Data buffer size. If buffer size smaller than required, buffer will be filled with fewer parameters.
mask	Parameters mask - pointer to VSourceParamsMask structure. VSourceParamsMask (declared in VSource.h file) determines flags for each field (parameter) declared in VSourceParams class. If the user wants to exclude any parameters from serialization, he can put a pointer to the mask. If the user wants to exclude a particular parameter from serialization, he should set the corresponding flag in the VSourceParamsMask structure.

VSourceParamsMask structure declaration:

struct VSourceParamsMask
{
    bool logLevel{true};
    bool width{true};
    bool height{true};
    bool gainMode{true};
    bool gain{true};
    bool exposureMode{true};
    bool exposure{true};
    bool focusMode{true};
    bool focusPos{true};
    bool cycleTimeMks{true};
    bool fps{true};
    bool isOpen{true};
    bool roiX{true};
    bool roiY{true};
    bool roiWidth{true};
    bool roiHeight{true};
    bool custom1{true};
    bool custom2{true};
    bool custom3{true};
};

Example without parameters mask:

// Prepare random params.
VSourceParams in;
in.initString = "any string";
in.logLevel = 0;

// Encode data.
uint8_t data[1024];
int size = 0;
in.encode(data, 1024, size);
cout << "Encoded data size: " << size << " bytes" << endl;

Example without parameters mask:

// Prepare random params.
VSourceParams in;
in.initString = "any string";
in.logLevel = 0;

// Prepare params mask.
VSourceParamsMask mask;
mask.logLevel = false; // Exclude logLevel. Others by default.

// Encode data.
uint8_t data[1024];
int size = 0;
in.encode(data, 1024, size, &mask);
cout << "Encoded data size: " << size << " bytes" << endl;

Deserialize VSourceParams

VSourceParams class provides method decode(…) to deserialize video source params (fields of VSourceParams class, see Table 6). Deserialization of video source params necessary in case when you need to receive video source params via communication channels. Method doesn’t decode fields: initString and fourcc. Method automatically recognizes which parameters were serialized by encode(…) method. Method declaration:

bool decode(uint8_t* data, int dataSize);

Parameter	Value
data	Pointer to encode data buffer. Data size should be at least 62 bytes.
dataSize	Size of data.

Returns: TRUE if data decoded (deserialized) or FALSE if not.

Example:

// Encode data.
VSourceParams in;
uint8_t data[1024];
int size = 0;
in.encode(data, 1024, size);

cout << "Encoded data size: " << size << " bytes" << endl;

// Decode data.
VSourceParams out;
if (!out.decode(data, size))
    cout << "Can't decode data" << endl;

Read and write Vsource params to JSON file

VSource library depends on ConfigReader library which provides method to read params from JSON file and to write params to JSON file. Example of writing and reading params to JSON file:

// Write params to file.
VSurceParams in;
cr::utils::ConfigReader inConfig;
inConfig.set(in, "vSourceParams");
inConfig.writeToFile("TestVSourceParams.json");

// Read params from file.
cr::utils::ConfigReader outConfig;
if(!outConfig.readFromFile("TestVSourceParams.json"))
{
    cout << "Can't open config file" << endl;
    return false;
}

TestVSourceParams.json will look like:

{
    "vSourceParams": {
        "custom1": 150.0,
        "custom2": 252.0,
        "custom3": 30.0,
        "exposureMode": 226,
        "focusMode": 89,
        "fourcc": "skdfjhvk",
        "fps": 206.0,
        "gainMode": 180,
        "height": 61,
        "logLevel": 17,
        "roiHeight": 249,
        "roiWidth": 167,
        "roiX": 39,
        "roiY": 223,
        "source": "alsfghljb",
        "width": 35
    }
}

CameraParams class description

CameraParams class used for camera controller initialization or to get all actual params. Also CameraParams provide structure to write/read params from JSON files (JSON_READABLE macro) and provide methods to encode and decode params.

CameraParams Class declaration

CameraParams interface class declared in Camera.h file. Class declaration:

namespace cr
{
namespace camera
{
class CameraParams
{
public:
    /// Initialization string.
    std::string initString{"/dev/ttyUSB0;9600;7"};
    /// Video frame width. Value from 0 to 16384.
    int width{0};
    /// Video frame height Value from 0 to 16384.
    int height{0};
    /// Display menu mode. 
    int displayMode{0};
    /// Video output type.
    int videoOutput{0};
    /// Logging mode.
    int logMode{0};
    /// Exposure mode. 
    int exposureMode{1};
    /// Exposure time of the camera sensor.
    int exposureTime{0};
    /// White balance mode. 
    int whiteBalanceMode{1};
    /// White balance area.
    int whiteBalanceArea{0};
    /// White dynamic range mode.
    int wideDynamicRangeMode{0};
    /// Image stabilization mode.
    int stabilisationMode{0};
    /// ISO sensitivity.
    int isoSensetivity{0};
    /// Scene mode.
    int sceneMode{0};
    /// FPS.
    float fps{0.0f};
    /// Brightness mode.
    int brightnessMode{1};
    /// Brightness. Value 0 - 100%.
    int brightness{0};
    /// Contrast. Value 1 - 100%.
    int contrast{0};
    /// Gain mode.
    int gainMode{1};
    /// Gain. Value 1 - 100%.
    int gain{0};
    /// Sharpening mode.
    int sharpeningMode{0};
    /// Sharpening. Value 1 - 100%.
    int sharpening{0};
    /// Palette.
    int palette{0};
    /// Analog gain control mode.
    int agcMode{1};
    /// Shutter mode.
    int shutterMode{1};
    /// Shutter position. 0 (full close) - 65535 (full open).
    int shutterPos{0};
    /// Shutter speed. Value: 0 - 100%.
    int shutterSpeed{0};
    /// Digital zoom mode.
    int digitalZoomMode{0};
    /// Digital zoom. Value 1.0 (x1) - 20.0 (x20).
    float digitalZoom{1.0f};
    /// Exposure compensation mode.
    int exposureCompensationMode{0};
    /// Exposure compensation position.
    int exposureCompensationPosition{0};
    /// Defog mode. 
    int defogMode{0};
    /// Dehaze mode.
    int dehazeMode{0};
    /// Noise reduction mode.
    int noiseReductionMode{0};
    /// Black and white filter mode.
    int blackAndWhiteFilterMode{0};
    /// Filter mode.
    int filterMode{0};
    /// NUC mode for thermal cameras.
    int nucMode{0};
    /// Auto NUC interval for thermal cameras.
    int autoNucIntervalMsec{0};
    /// Image flip mode. 
    int imageFlip{0};
    /// DDE mode.
    int ddeMode{0};
    /// DDE level.
    float ddeLevel{0};
    /// ROI top-left horizontal position, pixels.
    int roiX0{0};
    /// ROI top-left vertical position, pixels.
    int roiY0{0};
    /// ROI bottom-right horizontal position, pixels.
    int roiX1{0};
    /// ROI bottom-right vertical position, pixels.
    int roiY1{0};
    /// Camera temperature, degree.
    float temperature{0.0f};
    /// ALC gate.
    int alcGate{0};
    /// Sensor sensitivity.
    float sensitivity{0};
    /// Changing mode (day / night).
    int changingMode{0};
    /// Changing level (day / night).
    float changingLevel{0.0f};
    /// Chroma level. Values: 0 - 100%.
    int chromaLevel{0};
    /// Details, enhancement. Values: 0 - 100%.
    int detail{0};
    /// Camera settings profile.
    int profile{0};
    /// Connection status (read only).
    bool isConnected{false};
    /// Open status (read only).
    bool isOpen{false};
    /// Camera type.
    int type{0};
    /// Camera custom param.
    float custom1{0.0f};
    /// Camera custom param.
    float custom2{0.0f};
    /// Camera custom param.
    float custom3{0.0f};

    JSON_READABLE(CameraParams, initString, width, height, displayMode,
                  videoOutput, logMode, exposureMode, exposureTime,
                  whiteBalanceMode, whiteBalanceArea, wideDynamicRangeMode,
                  stabilisationMode, isoSensetivity, sceneMode, fps,
                  brightnessMode, brightness, contrast, gainMode, gain,
                  sharpeningMode, sharpening, palette, agcMode, shutterMode,
                  shutterPos, shutterSpeed, digitalZoomMode, digitalZoom,
                  exposureCompensationMode, exposureCompensationPosition,
                  defogMode, dehazeMode, noiseReductionMode,
                  blackAndWhiteFilterMode, filterMode, nucMode,
                  autoNucIntervalMsec, imageFlip, ddeMode, ddeLevel,
                  roiX0, roiY0, roiX1, roiY1, alcGate, sensitivity,
                  changingMode, changingLevel, chromaLevel, detail,
                  profile, type, custom1, custom2, custom3)

    /// operator =
    CameraParams& operator= (const CameraParams& src);

    /// Encode params. The method doesn't encode initString.
    bool encode(uint8_t* data, int bufferSize, int& size,
                CameraParamsMask* mask = nullptr);

    /// Decode params. The method doesn't decode initString.
    bool decode(uint8_t* data, int dataSize);
};
}
}

CameraParams class fields description is equivalent to CameraParam enum description except initString. initString is unique camera identifier in string format. See detectAvailableCameras method for detection of the ids for connected cameras.

Serialize camera params

CameraParams class provides method encode(…) to serialize camera params. Serialization of camera params necessary in case when you have to send camera params via communication channels. Method doesn’t encode initString field. Method provides options to exclude particular parameters from serialization. To do this method inserts binary mask (8 bytes) where each bit represents particular parameter and decode(…) method recognizes it. Method declaration:

bool encode(uint8_t* data, int bufferSize, int& size, CameraParamsMask* mask = nullptr);

Parameter	Value
data	Pointer to data buffer. Buffer size must be >= 237 bytes.
bufferSize	Data buffer size. Buffer size must be >= 237 bytes.
size	Size of encoded data.
mask	Parameters mask - pointer to CameraParamsMask structure. CameraParamsMask (declared in Camera.h file) determines flags for each field (parameter) declared in CameraParams class. If the user wants to exclude any parameters from serialization, he can put a pointer to the mask. If the user wants to exclude a particular parameter from serialization, he should set the corresponding flag in the CameraParamsMask structure.

Returns: TRUE if params encoded (serialized) or FALSE if not.

CameraParamsMask structure declaration:

typedef struct CameraParamsMask
{
    bool width{true};
    bool height{true};
    bool displayMode{true};
    bool videoOutput{true};
    bool logMode{true};
    bool exposureMode{true};
    bool exposureTime{true};
    bool whiteBalanceMode{true};
    bool whiteBalanceArea{true};
    bool wideDynamicRangeMode{true};
    bool stabilisationMode{true};
    bool isoSensetivity{true};
    bool sceneMode{true};
    bool fps{true};
    bool brightnessMode{true};
    bool brightness{true};
    bool contrast{true};
    bool gainMode{true};
    bool gain{true};
    bool sharpeningMode{true};
    bool sharpening{true};
    bool palette{true};
    bool agcMode{true};
    bool shutterMode{true};
    bool shutterPos{true};
    bool shutterSpeed{true};
    bool digitalZoomMode{true};
    bool digitalZoom{true};
    bool exposureCompensationMode{true};
    bool exposureCompensationPosition{true};
    bool defogMode{true};
    bool dehazeMode{true};
    bool noiseReductionMode{true};
    bool blackAndWhiteFilterMode{true};
    bool filterMode{true};
    bool nucMode{true};
    bool autoNucIntervalMsec{true};
    bool imageFlip{true};
    bool ddeMode{true};
    bool ddeLevel{true};
    bool roiX0{true};
    bool roiY0{true};
    bool roiX1{true};
    bool roiY1{true};
    bool temperature{true};
    bool alcGate{true};
    bool sensitivity{true};
    bool changingMode{true};
    bool changingLevel{true};
    bool chromaLevel{true};
    bool detail{true};
    bool profile{true};
    bool isConnected{true};
    bool isOpen{true};
    bool type{true};
    bool custom1{true};
    bool custom2{true};
    bool custom3{true};
} CameraParamsMask;

Example without parameters mask:

// Encode data.
CameraParams in;
in.profile = 10;
uint8_t data[1024];
int size = 0;
in.encode(data, 1024, size);
cout << "Encoded data size: " << size << " bytes" << endl;

Example with parameters mask:

// Prepare params.
CameraParams in;
in.profile = 3;

// Prepare mask.
CameraParamsMask mask;
mask.profile = false; // Exclude profile. Others by default.

// Encode.
uint8_t data[1024];
int size = 0;
in.encode(data, 1024, size, &mask);
cout << "Encoded data size: " << size << " bytes" << endl;

Deserialize camera params

CameraParams class provides method decode(…) to deserialize camera params (fields of CameraParams class). Deserialization of camera params necessary in case when you need to receive params via communication channels. Method automatically recognizes which parameters were serialized by encode(…) method. Method doesn’t decode initString field. Method declaration:

bool decode(uint8_t* data, int dataSize);

Parameter	Value
data	Pointer to data buffer with serialized camera params.
dataSize	Size of command data.

Returns: TRUE if params decoded (deserialized) or FALSE if not.

Example:

// Encode data.
CameraParams in;
uint8_t data[1024];
int size = 0;
in.encode(data, 1024, size);
cout << "Encoded data size: " << size << " bytes" << endl;

// Decode data.
CameraParams out;
if (!out.decode(data, size))
    cout << "Can't decode data" << endl;

Read and write camera params to JSON file

Camera library depends on ConfigReader library which provides method to read params from JSON file and to write params to JSON file. Example of writing and reading params to JSON file:

// Write params to file.
cr::utils::ConfigReader inConfig;
inConfig.set(in, "cameraParams");
inConfig.writeToFile("TestCameraParams.json");

// Read params from file.
cr::utils::ConfigReader outConfig;
if(!outConfig.readFromFile("TestCameraParams.json"))
{
    cout << "Can't open config file" << endl;
    return false;
}

TestCameraParams.json will look like:

{
    "cameraParams": {
        "agcMode": 252,
        "alcGate": 125,
        "autoNucIntervalMsec": 47,
        "blackAndWhiteFilterMode": 68,
        "brightness": 67,
        "brightnessMode": 206,
        "changingLevel": 84.0,
        "changingMode": 239,
        "chromeLevel": 137,
        "contrast": 65,
        "custom1": 216.0,
        "custom2": 32.0,
        "custom3": 125.0,
        "ddeLevel": 25,
        "ddeMode": 221,
        "defogMode": 155,
        "dehazeMode": 239,
        "detail": 128,
        "digitalZoom": 47.0,
        "digitalZoomMode": 157,
        "displayMode": 2,
        "exposureCompensationMode": 213,
        "exposureCompensationPosition": 183,
        "exposureMode": 192,
        "exposureTime": 16,
        "filterMode": 251,
        "fps": 19.0,
        "gain": 111,
        "gainMode": 130,
        "height": 219,
        "imageFlip": 211,
        "initString": "dfhglsjirhuhjfb",
        "isoSensetivity": 32,
        "logMode": 252,
        "noiseReductionMode": 79,
        "nucMode": 228,
        "palette": 115,
        "profile": 108,
        "roiX0": 93,
        "roiX1": 135,
        "roiY0": 98,
        "roiY1": 206,
        "sceneMode": 195,
        "sensitivity": 70.0,
        "sharpening": 196,
        "sharpeningMode": 49,
        "shutterMode": 101,
        "shutterPos": 157,
        "shutterSpeed": 117,
        "stabilisationMode": 170,
        "type": 55,
        "videoOutput": 18,
        "whiteBalanceArea": 236,
        "whiteBalanceMode": 30,
        "wideDynamicRangeMode": 21,
        "width": 150
    }
}

Build and connect to your project

Typical commands to build I3Camera library:

cd I3Camera
mkdir build
cd build
cmake ..
make

If you want connect I3Camera library to your CMake project as source code you can make follow. For example, if your repository has structure:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp

Create folder 3rdparty and copy folder of I3Camera repository there. New structure of your repository:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    I3Camera

Create CMakeLists.txt file in 3rdparty folder. CMakeLists.txt should contain:

cmake_minimum_required(VERSION 3.13)

################################################################################
## 3RD-PARTY
## dependencies for the project
################################################################################
project(3rdparty LANGUAGES CXX)

################################################################################
## SETTINGS
## basic 3rd-party settings before use
################################################################################
# To inherit the top-level architecture when the project is used as a submodule.
SET(PARENT ${PARENT}_YOUR_PROJECT_3RDPARTY)
# Disable self-overwriting of parameters inside included subdirectories.
SET(${PARENT}_SUBMODULE_CACHE_OVERWRITE OFF CACHE BOOL "" FORCE)

################################################################################
## CONFIGURATION
## 3rd-party submodules configuration
################################################################################
SET(${PARENT}_SUBMODULE_I3_CAMERA_CAMERA                ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_I3_CAMERA_CAMERA)
    SET(${PARENT}_I3_CAMERA                             ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_I3_CAMERA_TEST                        OFF CACHE BOOL "" FORCE)
    SET(${PARENT}_I3_CAMERA_EXAMPLE                     OFF CACHE BOOL "" FORCE)
endif()

################################################################################
## INCLUDING SUBDIRECTORIES
## Adding subdirectories according to the 3rd-party configuration
################################################################################
if (${PARENT}_SUBMODULE_I3_CAMERA_CAMERA)
    add_subdirectory(I3Camera)
endif()

File 3rdparty/CMakeLists.txt adds folder I3Camera to your project and excludes test application and example from compiling (by default test applications and example are excluded from compiling if I3Camera is included as sub-repository). The new structure of your repository:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    CMakeLists.txt
    I3Camera

Next you need include folder 3rdparty in main CMakeLists.txt file of your repository. Add string at the end of your main CMakeLists.txt:

add_subdirectory(3rdparty)

Next you have to include I3Camera library in your src/CMakeLists.txt file:

target_link_libraries(${PROJECT_NAME} I3Camera)

Done!

Simple example

Simple example is application which initializes video source and gets frames from camera. The example shows how to get frame from camera and display it. The example code:

#include <iostream>
#include <opencv2/opencv.hpp>
#include "I3Camera.h"

int main()
{

    auto availableCameras = cr::video::I3Camera::detectAvailableCameras();

    std::string cameraId = availableCameras[0]; // Get first camera id.

    cr::video::I3Camera i3Camera;

    if (!i3Camera.openVSource(cameraId))
    {
        std::cerr << "Camera can't open." << std::endl;
        return -1;
    }

    if (!i3Camera.setParam(cr::video::VSourceParam::LOG_LEVEL, 0))
    {
        std::cerr << "Log level setting failed." << std::endl;
        return -1;
    }

    cr::video::Frame sourceFrame;

    while (true)
    {
        if (!i3Camera.getFrame(sourceFrame))
        {
            std::cerr << "No frame from camera." << std::endl;
            continue;
        }

        // Get frame time in us.
        float cycleTimeUs = i3Camera.getParam(cr::video::VSourceParam::CYCLE_TIME_MKS);
        float fps = 1000000.0f / cycleTimeUs;

        // Gray scale image.
        cv::Mat showFrame(sourceFrame.height, sourceFrame.width, CV_8UC1, sourceFrame.data);

        // Draw cycle time on the image.
        cv::putText(showFrame, "FPS : " + std::to_string(int(fps)), cv::Point(10, 20), cv::FONT_HERSHEY_SIMPLEX, 0.5, cv::Scalar(255, 255, 255), 1);

        // Display the grayscale image.
        cv::imshow("Gray Frame", showFrame);

        // Wait for a key press.
        cv::waitKey(33);
    }
    return 0;
}

Test application

Folder I3Camera/test contains the test application files. The test application allows user to set params, get params and execute commands while showing the captured frames from camera. Also, the test application writes captured frames into a file. The test application code:

Test application output will look like:

```bash
================================================
I3Camera v1.2.0 test application
================================================
Available cameras:
Camera [0] with id : 0
Enter camera id: 0
Do you want to show frame(0/1) : 0

Do you want to save frame(0/1) into a file : 0

===========================
0. Exit
1. Set camera parameter
2. Get camera parameter
3. Execute camera command
Choose operation: 1

23 - AGC mode
19 - Gain
14 - FPS
37 - Auto NUC interval
36 - NUC mode
Choose parameter: 19

Enter value: 28

I3Camera C++ library

Table of contents

Overview

Versions

Library files

I3Camera class description

I3Camera class declaration

getVersion method

detectAvailableCameras method

openVSource method

openCamera method

initVSource method

initCamera method

getFrame method

closeVSource method

closeCamera method

isVSourceOpen method

isCameraOpen method

isCameraConnected method

setParam method

getParam method

getParams method

executeCommand method

decodeAndExecuteCommand method

encodeSetParamCommand method of VSource class

encodeCommand method of VSource class

decodeCommand method of VSource class

encodeSetParamCommand method of Camera class

encodeCommand method of Camera class

decodeCommand method of Camera class

Data structures

VSourceCommand enum

CameraCommand enum

VSourceParam enum

CameraParam enum

VSourceParams class description

VSourceParams class declaration

Serialize VSourceParams

Deserialize VSourceParams

Read and write Vsource params to JSON file

CameraParams class description

CameraParams Class declaration

Serialize camera params

Deserialize camera params

Read and write camera params to JSON file

Build and connect to your project

Simple example

Test application

Table of contents