KowaCamera C++ library

v2.1.0

Table of contents

• Overview
• Versions
• Library files
• KowaCamera class description
  • KowaCamera class declaration
  • getVersion method
  • openCamera method
  • initCamera method
  • closeCamera method
  • isCameraOpen method
  • isCameraConnected method
  • setParam method
  • getParam method
  • getParams method
  • executeCommand method
  • decodeAndExecuteCommand method
  • encodeSetParamCommand method of Camera class
  • encodeCommand method of Camera class
  • decodeCommand method of Camera class
• Data structures
  • CameraCommand enum
  • CameraParam enum
• 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
  • Build stand alone
  • CMake options
  • Connect to your project
• Portability
• Simple example
• Test application

Overview

The KowaCamera C++ library is a software controller for KOWA camera. The KowaCamera library inherits interface from Camera. It depends on libraries: Camera (provides interface and data structures to control cameras), Logger (provides function to print logs), SerialPort (provides functions to work with serial ports) and KowaProtocolParser (provides function to encode control commands for Kowa camera; it is a part of this repository: folder src/parser, see src/parser/README.md). The Camera library depends on the ConfigReader library (reads and writes parameters from JSON files). Except KowaProtocolParser, the libraries are separate repositories: they are not included in the KowaCamera repository and must be placed next to it (see Build and connect to your project). The KowaCamera library provides simple interface to be integrated in any C++ projects. The library repository (folder) provided by source code and doesn’t have third-party dependencies to be specially installed in OS. It developed with C++17 standard and compatible with Linux and Windows.

KowaCamera is general-purpose software: it is not tied to any sector or application, and the developer of a program decides what the program does with it.

The library code was developed by reverse engineering the serial port communication protocol of the camera.

Versions

Table 1 - Library versions.

Version	Release date	What’s new
1.0.0	30.05.2023	First version
2.0.0	07.03.2024	- Interface updated. - Example added. - Test application updated. - Documentation updated.
2.0.1	26.04.2024	- Documentation updated. - Code reviewed.
2.0.2	23.05.2024	- Documentation updated. - Submodules updated.
2.0.3	07.08.2024	- CMake structure updated.
2.0.4	29.09.2024	- Fix camera initialization in initCamera(…) method.
2.0.5	03.04.2025	- Logger submodule update.
2.0.6	26.10.2025	- KowaProtocolParser submodule update. - SerialPort submodule update.
2.0.7	12.10.2026	- Submodules updated.
2.0.8	17.10.2026	- Git submodules removed: the dependencies are expected next to the library. - Code reviewed: values of params are checked (NaN, infinity, out of range), the size of a command is checked in decodeAndExecuteCommand(…), the access to the serial port is thread-safe, the cleanup of the input buffer is bounded. - Baudrate must be greater than 0. SHUTTER_MODE accepts values 0 - 14. DIGITAL_ZOOM and CHROMA_LEVEL values which the camera protocol does not allow are rejected. - Rejected commands are logged according to the log mode. - CMake: warning and hardening options added. - Test application and example redone, documentation updated.
2.1.0	29.10.2026	- The KowaProtocolParser library is a part of the repository (folder src/parser) and is not a separate dependency any more.

Library files

The library is supplied as source code only. The user would be given a set of files in the form of a CMake project (repository). Except the protocol parser KowaProtocolParser (folder src/parser), the repository doesn’t contain the source code of the libraries which KowaCamera depends on (see Build and connect to your project). The repository structure is shown below:

CMakeLists.txt ------------------------------- Main CMake file of the library.
static --------------------------------------- Folder with images of this document.
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.
    KowaCamera.cpp --------------------------- C++ implementation file.
    KowaCamera.h ----------------------------- Header file which includes KowaCamera class declaration.
    KowaCameraVersion.h ---------------------- Header file which includes version of the library.
    KowaCameraVersion.h.in ------------------- CMake service file to generate version file.
    parser ----------------------------------- Protocol parser library (former KowaProtocolParser repository).
        .gitignore --------------------------- Git ignore rules of the parser folder.
        CMakeLists.txt ----------------------- Main CMake file of the parser library.
        README.md ---------------------------- Documentation of the parser library.
        src ---------------------------------- Folder with source code of the parser library.
            CMakeLists.txt ------------------- CMake file of the parser library.
            KowaProtocolParser.cpp ----------- C++ implementation file of the parser library.
            KowaProtocolParser.h ------------- Header file which includes KowaProtocolParser class declaration.
            KowaProtocolParserVersion.h ------ Header file which includes version of the parser library.
            KowaProtocolParserVersion.h.in --- CMake service file to generate version file.
        static ------------------------------- Folder with images of the parser documentation.
            kowaprotocolparser_web_logo.png -- Logo of the parser library.
        test --------------------------------- Folder with test application of the parser (not built by the library).
            CMakeLists.txt ------------------- CMake file for test application of the parser.
            main.cpp ------------------------- Source code file of test application of the parser.

KowaCamera class description

KowaCamera Class declaration

The KowaCamera interface class declared in KowaCamera.h file. The KowaCamera class inherits Camera interfaces. All methods are thread-safe. The object can’t be copied or moved. Class declaration:

class KowaCamera : public rapidpixel::Camera
{
public:

    /// Default constructor. The camera is closed, the log is disabled.
    KowaCamera() = default;

    /// Copy and move constructors and assignment operators are deleted.
    KowaCamera(const KowaCamera& src) = delete;
    KowaCamera(KowaCamera&& src) = delete;
    KowaCamera& operator=(const KowaCamera& src) = delete;
    KowaCamera& operator=(KowaCamera&& src) = delete;

    /// Get class version string.
    static std::string getVersion();

    /// Init camera controller (open serial port).
    bool openCamera(std::string initString) override;

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

    /// Close camera serial port.
    void closeCamera() override;

    /// Get camera open status (the serial port is open).
    bool isCameraOpen() override;

    /// Get camera connection status (the camera responds).
    bool isCameraConnected() override;

    /// Set the camera controller param.
    bool setParam(CameraParam id, float value) override;

    /// Get the camera controller param.
    float getParam(CameraParam id) override;

    /// Get the camera controller params.
    void getParams(CameraParams& params) override;

    /// Execute camera controller action command.
    bool executeCommand(CameraCommand id) override;

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

getVersion method

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

static std::string getVersion();

Method can be used without KowaCamera class instance:

std::cout << "KowaCamera class version: " <<
    rapidpixel::KowaCamera::getVersion() << std::endl;

Console output:

KowaCamera class version: 2.1.0

openCamera method

The openCamera(…) opens serial port to communicate with Kowa camera. Method declaration:

bool openCamera(std::string initString) override;

Parameter

Value

initString

Initialization string. Format : serial port name;baudrate For example : “/dev/ttyUSB0;9600” (“/dev/ttyUSB0” - serial port name, “9600” - baudrate). The string must have exactly two parts (empty parts are ignored). The baudrate is read by std::stoi (characters after the number are ignored), it must be greater than 0. The string is a configuration of the application: the method opens the serial port with this name.

Returns: TRUE if the serial port is open (also if it was already open) or FALSE if not (invalid initialization string or the serial port can’t be opened). The method doesn’t send commands to the camera and doesn’t change camera parameters. The method is thread-safe.

initCamera method

The initCamera(…) initializes controller and sets camera params (Camera interface). The method will call openCamera(…) method and after will set given camera params with setParam(…) method. Method declaration:

bool initCamera(CameraParams& params) override;

Parameter	Value
params	CameraParams class object. CameraParams class includes initString which used in openCamera(…) method. The method uses only initString and the parameters which are supported by setParam(…) method.

Returns: TRUE if the serial port is open or FALSE if not. A parameter which is rejected by setParam(…) method or is not confirmed by the camera doesn’t change the result: use isCameraConnected() method and getParam(…) method to check the camera. Each parameter takes more than 100 ms because the method waits for the answer of the camera. The method is thread-safe.

closeCamera method

The closeCamera() method closes serial port. The method waits for the end of the command which is being sent. The method is thread-safe. Method declaration:

void closeCamera() override;

isCameraOpen method

The isCameraOpen() method returns serial port open status. Open status shows if the controller initialized (serial port open) but doesn’t show if controller has communication with equipment. For example, if serial port is open (opens serial port file in OS) but equipment can be inactive (no power). In this case open status just shows that the serial port is open. Method declaration:

bool isCameraOpen() override;

Returns: TRUE is the controller initialized (serial port open) or FALSE if not.

isCameraConnected method

The isCameraConnected() shows if the controller receives responses from equipment (camera). For example, if serial port open but equipment is inactive (no power). In this case method isCameraOpen(…) will return TRUE but isCameraConnected() method will return FALSE. The KowaCamera library checks connection status every time when send command to camera. If no output commands to camera the method will return FALSE. Method declaration:

bool isCameraConnected() override;

Returns: TRUE if the controller has data exchange with equipment or FALSE if not.

setParam method

The setParam(…) method sets new camera controller parameter value. Method declaration:

bool setParam(CameraParam id, float value) override;

Parameter	Description
id	Camera controller parameter ID according to CameraParam enum.
value	Parameter value. Value depends on parameter ID.

The method checks the value before it is used. The fractional part of the value is truncated when the range is checked (see Table 3). NaN, infinity, a value which doesn’t fit into int and a value which the camera protocol doesn’t allow (for example 10.5 for DIGITAL_ZOOM) are rejected. A valid value is stored (see getParam(…) method) even if the camera doesn’t respond to the command. LOG_MODE is not sent to the camera. Each command waits for the answer of the camera, so the method takes more than 100 ms. The method is thread-safe.

Returns: TRUE if the value is valid and the camera responded to the command or FALSE if not (the parameter is not supported, the value is invalid or the camera doesn’t respond). If the value is invalid nothing is changed.

getParam method

The getParam(…) method intended to obtain Camera parameter value. Method declaration:

float getParam(CameraParam id) override;

Parameter	Description
id	Camera controller parameter ID according according to CameraParam enum.

The method returns the last value which was stored by setParam(…) method (or by initCamera(…) method), it doesn’t read the camera. The method is thread-safe.

Returns: parameter value or -1 if the parameter is not supported.

getParams method

The getParams(…) method intended to obtain Camera parameters structure. Method declaration:

void getParams(CameraParams& params) override;

Parameter	Description
params	Reference to CameraParams class object. Parameters which are not supported by the controller have default values.

executeCommand method

The executeCommand(…) method intended to execute Camera action command. Method declaration:

bool executeCommand(CameraCommand id) override;

Parameter	Description
id	Camera controller command ID according to CameraCommand enum.

Returns: TRUE if the command was executed (the camera responded) or FALSE if not (the command is not supported or the camera doesn’t respond). The method is thread-safe.

decodeAndExecuteCommand method

The decodeAndExecuteCommand(…) method decodes and executes command on controller side. Method will decode commands which encoded by encodeCommand(…) and encodeSetParamCommand(…) methods of Camera interface class. If command decoded the method will call setParam(…) or executeCommand(…) methods for camera interfaces. This method is thread-safe. This means that the method can be safely called from any thread. Method declaration:

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

Parameter	Description
data	Pointer to input command data. Must not be nullptr. The data is not changed.
size	Size of command. Must be exactly 11 bytes for SET_PARAM and exactly 7 bytes for COMMAND. A message of another size, with another version or with an unknown type is rejected.

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

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 not be nullptr, must have size >= 11.
size	Size of encoded data. Will be 11 bytes (0 if data is nullptr).
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;
// Parameter value.
float value = 2.0f;
// Encode command.
rapidpixel::Camera::encodeSetParamCommand(
    data, size, rapidpixel::CameraParam::DIGITAL_ZOOM, value);

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 not be nullptr, must have size >= 7.
size	Size of encoded data. Will be 7 bytes (0 if data is nullptr).
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.
rapidpixel::Camera::encodeCommand(
    data, size, rapidpixel::CameraCommand::MENU_ON);

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. Must not be nullptr.
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 (the output arguments are not changed in this case).

Data structures

CameraCommand enum

Enum declaration:

/// Camera controller commands enum. The values are consecutive: the first
/// value is RESTART and the last one is DEFREEZE. Camera::decodeCommand(...)
/// uses them to check the command ID.
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 image.
    FREEZE,
    /// Disable freeze. The last value of the enum.
    DEFREEZE
};

Table 2 - Camera commands description.

Command	Description
RESTART	Not supported by KowaCamera library.
NUC	Not supported by KowaCamera library.
APPLY_PARAMS	Not supported by KowaCamera library.
SAVE_PARAMS	Not supported by KowaCamera library.
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	Not supported by KowaCamera library.
DEFREEZE	Not supported by KowaCamera library.

CameraParam enum

Enum declaration:

/// Camera controller params. The values are consecutive: the first value is
/// WIDTH and the last one is CUSTOM_3. Camera::decodeCommand(...) uses them to
/// check the param ID.
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. Value depends on implementation but it is recommended
    /// to keep default values: 0 - Off. 1 - On.
    DISPLAY_MODE,
    /// Video output type. Value depends on implementation.
    VIDEO_OUTPUT,
    /// Logging mode. Values: 0 - Disable, 1 - Only file,
    /// 2 - Only terminal (console), 3 - File and terminal.
    LOG_MODE,
    /// Exposure mode. Value depends on implementation but it is recommended to
    /// keep default values: 0 - Manual, 1 - Auto (default),
    /// 2 - Shutter priority, 3 - Aperture priority.
    EXPOSURE_MODE,
    /// Exposure time of the camera sensor. The exposure time is limited by the
    /// frame interval. Camera controller should interpret the values as 100 us
    /// units, where the value 1 stands for 1/10000th of a second, 10000 for
    /// 1 second and 100000 for 10 seconds.
    EXPOSURE_TIME,
    /// White balance mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual, 1 - Auto.
    WHITE_BALANCE_MODE,
    /// White balance area. Value depends on implementation.
    WHITE_BALANCE_AREA,
    /// White dynamic range mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Off, 1 - On.
    WIDE_DYNAMIC_RANGE_MODE,
    /// Image stabilization mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Off, 1 - On.
    STABILIZATION_MODE,
    /// ISO sensitivity. Value depends on implementation.
    ISO_SENSITIVITY,
    /// Scene mode. Value depends on implementation.
    SCENE_MODE,
    /// FPS.
    FPS,
    /// Brightness mode. Value depends on implementation but it is recommended
    /// to keep default values: 0 - Manual, 1 - Auto.
    BRIGHTNESS_MODE,
    /// Brightness. Value 0 - 100%.
    BRIGHTNESS,
    /// Contrast. Value 1 - 100%.
    CONTRAST,
    /// Gain mode. Value depends on implementation but it is recommended to keep
    /// default values: 0 - Manual, 1 - Auto.
    GAIN_MODE,
    /// Gain. Value 1 - 100%.
    GAIN,
    /// Sharpening mode. Value depends on implementation but it is recommended
    /// to keep default values: 0 - Manual, 1 - Auto.
    SHARPENING_MODE,
    /// Sharpening. Value 1 - 100%.
    SHARPENING,
    /// Palette. Value depends on implementation but it is recommended to keep
    /// default values for thermal cameras: 0 - White hot, 1 - Black hot.
    PALETTE,
    /// Analog gain control mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual, 1 - Auto.
    AGC_MODE,
    /// Shutter mode. Value depends on implementation but it is recommended to
    /// keep default values: 0 - Manual, 1 - Auto.
    SHUTTER_MODE,
    /// Shutter position. 0 (full close) - 65535 (full open).
    SHUTTER_POSITION,
    /// Shutter speed. Value: 0 - 100%.
    SHUTTER_SPEED,
    /// Digital zoom mode. Value depends on implementation but it is recommended
    /// to keep default values: 0 - Off, 1 - On.
    DIGITAL_ZOOM_MODE,
    /// Digital zoom. Value 1.0 (x1) - 20.0 (x20).
    DIGITAL_ZOOM,
    /// Exposure compensation mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Off, 1 - On.
    EXPOSURE_COMPENSATION_MODE,
    /// Exposure compensation position. Value depends on particular camera
    /// controller.
    EXPOSURE_COMPENSATION_POSITION,
    /// Defog mode. Value depends on implementation but it is recommended to
    /// keep default values: 0 - Off, 1 - On.
    DEFOG_MODE,
    /// Dehaze mode. Value depends on implementation but it is recommended to
    /// keep default values: 0 - Off, 1 - On.
    DEHAZE_MODE,
    /// Noise reduction mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Off, 1 - 2D, 3 - 3D.
    NOISE_REDUCTION_MODE,
    /// Black and white filter mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Off, 1 - On.
    BLACK_WHITE_FILTER_MODE,
    /// Filter mode. Value depends on implementation.
    FILTER_MODE,
    /// NUC mode for thermal cameras. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual, 1 - Auto.
    NUC_MODE,
    /// Auto NUC interval for thermal cameras. Value in milliseconds
    /// from 0 (Off) to 100000.
    AUTO_NUC_INTERVAL_MSEC,
    /// Image flip mode. Value depends on implementation but it is recommended
    /// to keep default values: 0 - Off, 1 - Horizontal, 2 - Vertical,
    /// 3 - Horizontal and vertical.
    IMAGE_FLIP,
    /// DDE mode. Value depends on implementation but it is recommended to keep
    /// default values: 0 - Off, 1 - On.
    DDE_MODE,
    /// DDE level. Value depends on implementation.
    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. Value depends on implementation.
    ALC_GATE,
    /// Sensor sensitivity. Value depends on implementation.
    SENSITIVITY,
    /// Changing mode (day / night). Value depends on implementation.
    CHANGING_MODE,
    /// Changing level (day / night). Value depends on implementation.
    CHANGING_LEVEL,
    /// Chroma level. Values: 0 - 100%.
    CHROMA_LEVEL,
    /// Details, enhancement. Values: 0 - 100%.
    DETAIL,
    /// Camera settings profile. Value depends on implementation.
    PROFILE,
    /// Connection status (read only). Shows if we have response from camera.
    /// Value: 0 - not connected, 1 - connected.
    IS_CONNECTED,
    /// Open status (read only):
    /// 1 - camera control port open, 0 - not open.
    IS_OPEN,
    /// Camera type. Value depends on implementation.
    TYPE,
    /// Camera custom param. Value depends on implementation.
    CUSTOM_1,
    /// Camera custom param. Value depends on implementation.
    CUSTOM_2,
    /// Camera custom param. Value depends on implementation. The last value
    /// of the enum.
    CUSTOM_3
};

Table 3 - Camera params description.

Parameter	Access	Description
WIDTH	read / write	Not supported by KowaCamera library.
HEIGHT	read / write	Not supported by KowaCamera library.
DISPLAY_MODE	read / write	Display mode. Values: 0 - Menu Off 1 - Menu On
VIDEO_OUTPUT	read / write	Not supported by KowaCamera 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 KowaCamera library.
EXPOSURE_TIME	read / write	Not supported by KowaCamera library.
WHITE_BALANCE_MODE	read / write	White balance mode. Values: 0 - ATW1. 1 - ATW2. 2 - AWC. 3 - MANUAL. 4 - AWC exec.
WHITE_BALANCE_AREA	read / write	Not supported by KowaCamera library.
WIDE_DYNAMIC_RANGE_MODE	read / write	Wide dynamic range mode. Values: 0 - OFF. 1 - WDR. 2 - Auto Knee. 3 - Black Stretch.
STABILIZATION_MODE	read / write	Not supported by KowaCamera library.
ISO_SENSITIVITY	read / write	Not supported by KowaCamera library.
SCENE_MODE	read / write	Not supported by KowaCamera library.
FPS	read / write	Not supported by KowaCamera library.
BRIGHTNESS_MODE	read / write	Not supported by KowaCamera library.
BRIGHTNESS	read / write	Not supported by KowaCamera library.
CONTRAST	read / write	Not supported by KowaCamera library.
GAIN_MODE	read / write	Gain mode. Values: 0 - AGC. 1 - H AGC. 2 - MANUAL.
GAIN	read / write	Not supported by KowaCamera library.
SHARPENING_MODE	read / write	Not supported by KowaCamera library.
SHARPENING	read / write	Not supported by KowaCamera library.
PALETTE	read / write	Not supported by KowaCamera library.
AGC_MODE	read / write	AGC mode. Values: 0 - AGC. 1 - H AGC. 2 - MANUAL. The value is sent to the camera with the same command as GAIN_MODE.
SHUTTER_MODE	read / write	Shutter mode. Values: 0 - OFF. 1 - 1/125. 2 - 1/250. 3 - 1/500. 4 - 1/1000. 5 - 1/2000. 6 - 1/4000. 7 - 1/10000. 8 - 1/50. 9 - 1/60. 10 - x1. 11 - x2. 12 - x4. 13 - x8. 14 - x16.
SHUTTER_POSITION	read / write	Not supported by KowaCamera library.
SHUTTER_SPEED	read / write	Shutter speed. Value: 1 - 100 (%).
DIGITAL_ZOOM_MODE	read / write	Not supported by KowaCamera library.
DIGITAL_ZOOM	read / write	Digital zoom. Value: 1 - 10. Fractional values are allowed (for example 2.5), values from 10.1 are rejected.
EXPOSURE_COMPENSATION_MODE	read only	Not supported by KowaCamera library.
EXPOSURE_COMPENSATION_POSITION	read / write	Not supported by KowaCamera library.
DEFOG_MODE	read / write	Defog mode. Values: 0 - Off 1 - Low 2 - Medium 3 - High
DEHAZE_MODE	read / write	Not supported by KowaCamera library.
NOISE_REDUCTION_MODE	read / write	Noise reduction mode. Value: 0 - OFF. 1 - LOW. 2 - HIGH.
BLACK_WHITE_FILTER_MODE	read only	Not supported by KowaCamera library.
FILTER_MODE	read / write	Not supported by KowaCamera library.
NUC_MODE	read / write	Not supported by KowaCamera library.
AUTO_NUC_INTERVAL_MSEC	read / write	Not supported by KowaCamera library.
IMAGE_FLIP	read / write	Not supported by KowaCamera library.
DDE_MODE	read / write	Not supported by KowaCamera library.
DDE_LEVEL	read / write	Not supported by KowaCamera library.
ROI_X0	read / write	Not supported by KowaCamera library.
ROI_Y0	read / write	Not supported by KowaCamera library.
ROI_X1	read / write	Not supported by KowaCamera library.
ROI_Y1	read / write	Not supported by KowaCamera library.
TEMPERATURE	read only	Not supported by KowaCamera library.
ALC_GATE	read / write	ALC gate mode. Values: 0 - OFF 1 - S/N 2 - STD 3 - MOVE 4 - MANUAL
SENSITIVITY	read / write	Not supported by KowaCamera library.
CHANGING_MODE	read / write	IR cut filter changing mode. Value: 0 - AUTO. 1 - REMOTE. 2 - COLOR. 3 - B/W.
CHANGING_LEVEL	read / write	IR cut filter changing level. Value: 0 - DARK. 1 - MID. 2 - BRIGHT. 3 - MANUAL.
CHROMA_LEVEL	read / write	Chroma level. Value: 0 - 100 (%).
DETAIL	read / write	Detail. Value: 0 - 100 (%).
PROFILE	read / write	Not supported by KowaCamera library.
IS_CONNECTED	read only	Connection status. Connection status shows if the controller has data exchange with equipment. For example, if serial port open but equipment can be not active (no power). In this case connection status shows that controller doesn’t have data exchange with equipment (methods will return 0). It the controller has data exchange with equipment the method will return 1. If the controller not initialize the connection status always FALSE. The KowaCamera library checks connection status every time when send command to camera. If no output commands to camera the method will return FALSE. Value: 0 - not connected. 1 - connected.
IS_OPEN	read only	Controller initialization status. Open status shows if the controller initialized or not but doesn’t show if controller has communication with equipment. For example, if serial port open but equipment can be not active (no power). In this case open status just shows that the controller has opened serial port. Values: 0 - not open (not initialized), 1 - open (initialized).
TYPE	read / write	Not supported by KowaCamera library.
CUSTOM_1	read / write	Not supported by KowaCamera library.
CUSTOM_2	read / write	Not supported by KowaCamera library.
CUSTOM_3	read / write	Not supported by KowaCamera library.

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:

class CameraParams
{
public:
    /// Initialization string. Formats depends on implementation.
    std::string initString{"/dev/ttyUSB0;9600;20"};
    /// 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. Value depends on implementation but it is recommended
    /// to keep default values: 0 - Off. 1 - On.
    int displayMode{0};
    /// Video output type. Value depends on implementation.
    int videoOutput{0};
    /// Logging mode. Values: 0 - Disable, 1 - Only file,
    /// 2 - Only terminal (console), 3 - File and terminal.
    int logMode{0};
    /// Exposure mode. Value depends on implementation but it is recommended to
    /// keep default values: 0 - Manual, 1 - Auto (default),
    /// 2 - Shutter priority, 3 - Aperture priority.
    int exposureMode{1};
    /// Exposure time of the camera sensor. The exposure time is limited by the
    /// frame interval. Camera controller should interpret the values as 100 us
    /// units, where the value 1 stands for 1/10000th of a second, 10000 for
    /// 1 second and 100000 for 10 seconds.
    int exposureTime{0};
    /// White balance mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual, 1 - Auto.
    int whiteBalanceMode{1};
    /// White balance area. Value depends on implementation.
    int whiteBalanceArea{0};
    /// White dynamic range mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Off, 1 - On.
    int wideDynamicRangeMode{0};
    /// Image stabilization mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Off, 1 - On.
    int stabilizationMode{0};
    /// ISO sensitivity. Value depends on implementation.
    int isoSensitivity{0};
    /// Scene mode. Value depends on implementation.
    int sceneMode{0};
    /// FPS.
    float fps{0.0f};
    /// Brightness mode. Value depends on implementation but it is recommended
    /// to keep default values: 0 - Manual, 1 - Auto.
    int brightnessMode{1};
    /// Brightness. Value 0 - 100%.
    int brightness{0};
    /// Contrast. Value 1 - 100%.
    int contrast{0};
    /// Gain mode. Value depends on implementation but it is recommended to keep
    /// default values: 0 - Manual, 1 - Auto.
    int gainMode{1};
    /// Gain. Value 1 - 100%.
    int gain{0};
    /// Sharpening mode. Value depends on implementation but it is recommended
    /// to keep default values: 0 - Manual, 1 - Auto.
    int sharpeningMode{0};
    /// Sharpening. Value 1 - 100%.
    int sharpening{0};
    /// Palette. Value depends on implementation but it is recommended to keep
    /// default values for thermal cameras: 0 - White hot, 1 - Black hot.
    int palette{0};
    /// Analog gain control mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual, 1 - Auto.
    int agcMode{1};
    /// Shutter mode. Value depends on implementation but it is recommended to
    /// keep default values: 0 - Manual, 1 - Auto.
    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. Value depends on implementation but it is recommended
    /// to keep default values: 0 - Off, 1 - On.
    int digitalZoomMode{0};
    /// Digital zoom. Value 1.0 (x1) - 20.0 (x20).
    float digitalZoom{1.0f};
    /// Exposure compensation mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Off, 1 - On.
    int exposureCompensationMode{0};
    /// Exposure compensation position. Value depends on particular camera
    /// controller.
    int exposureCompensationPosition{0};
    /// Defog mode. Value depends on implementation but it is recommended to
    /// keep default values: 0 - Off, 1 - On.
    int defogMode{0};
    /// Dehaze mode. Value depends on implementation but it is recommended to
    /// keep default values: 0 - Off, 1 - On.
    int dehazeMode{0};
    /// Noise reduction mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Off, 1 - 2D, 3 - 3D.
    int noiseReductionMode{0};
    /// Black and white filter mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Off, 1 - On.
    int blackAndWhiteFilterMode{0};
    /// Filter mode. Value depends on implementation.
    int filterMode{0};
    /// NUC mode for thermal cameras. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual, 1 - Auto.
    int nucMode{0};
    /// Auto NUC interval for thermal cameras. Value in milliseconds
    /// from 0 (Off) to 100000.
    int autoNucIntervalMsec{0};
    /// Image flip mode. Value depends on implementation but it is recommended
    /// to keep default values: 0 - Off, 1 - Horizontal, 2 - Vertical,
    /// 3 - Horizontal and vertical.
    int imageFlip{0};
    /// DDE mode. Value depends on implementation but it is recommended to keep
    /// default values: 0 - Off, 1 - On.
    int ddeMode{0};
    /// DDE level. Value depends on implementation.
    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. Value depends on implementation.
    int alcGate{0};
    /// Sensor sensitivity. Value depends on implementation.
    float sensitivity{0};
    /// Changing mode (day / night). Value depends on implementation.
    int changingMode{0};
    /// Changing level (day / night). Value depends on implementation.
    float changingLevel{0.0f};
    /// Chroma level. Values: 0 - 100%.
    int chromaLevel{0};
    /// Details, enhancement. Values: 0 - 100%.
    int detail{0};
    /// Camera settings profile. Value depends on implementation.
    int profile{0};
    /// Connection status (read only). Shows if we have response from camera.
    /// Value: false - not connected, true - connected.
    bool isConnected{false};
    /// Open status (read only):
    /// true - camera control port open, false - not open.
    bool isOpen{false};
    /// Camera type. Value depends on implementation.
    int type{0};
    /// Camera custom param. Value depends on implementation.
    float custom1{0.0f};
    /// Camera custom param. Value depends on implementation.
    float custom2{0.0f};
    /// Camera custom param. Value depends on implementation.
    float custom3{0.0f};

    // JSON read / write of the fields. The fields temperature, isConnected and
    // isOpen are not stored in JSON.
    JSON_READABLE(CameraParams, initString, width, height, displayMode,
                  videoOutput, logMode, exposureMode, exposureTime,
                  whiteBalanceMode, whiteBalanceArea, wideDynamicRangeMode,
                  stabilizationMode, isoSensitivity, 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)

    /// Default constructor. All fields have default values.
    CameraParams() = default;

    /// Copy and move constructors and assignment operators.
    CameraParams(const CameraParams& src) = default;
    CameraParams(CameraParams&& src) = default;
    CameraParams& operator= (const CameraParams& src) = default;
    CameraParams& operator= (CameraParams&& src) = default;

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

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

Table 4 - CameraParams class fields description is equivalent to CameraParam enum description.

Field	type	Description
initString	string	Initialization string contains full serial port name, baudrate separated by “;”. Example: “/dev/ttyUSB0;9600”. The default value of the field (“/dev/ttyUSB0;9600;20”) has three parts and is not valid for KowaCamera: set the field before initCamera(…).
width	int	Not supported by KowaCamera class.
height	int	Not supported by KowaCamera class.
displayMode	int	Display mode. Values: 0 - Menu Off 1 - Menu On
videoOutput	int	Not supported by KowaCamera class.
logMode	int	Logging mode. Values: 0 - Disable 1 - Only file 2 - Only terminal (console) 3 - File and terminal
exposureMode	int	Not supported by KowaCamera class.
exposureTime	int	Not supported by KowaCamera class.
whiteBalanceMode	int	White balance mode. Values: 0 - ATW1. 1 - ATW2. 2 - AWC. 3 - MANUAL. 4 - AWC exec.
whiteBalanceArea	int	Not supported by KowaCamera class.
wideDynamicRangeMode	int	Wide dynamic range mode. Values: 0 - OFF. 1 - WDR. 2 - Auto Knee. 3 - Black Stretch.
stabilizationMode	int	Not supported by KowaCamera class.
isoSensitivity	int	Not supported by KowaCamera class.
sceneMode	int	Not supported by KowaCamera class.
fps	float	Not supported by KowaCamera class.
brightnessMode	int	Not supported by KowaCamera class.
brightness	int	Not supported by KowaCamera class.
contrast	int	Not supported by KowaCamera class.
gainMode	int	Gain mode. Values: 0 - AGC. 1 - H AGC. 2 - MANUAL.
gain	int	Not supported by KowaCamera class.
sharpeningMode	int	Not supported by KowaCamera class.
sharpening	int	Not supported by KowaCamera class.
palette	int	Not supported by KowaCamera class.
agcMode	int	AGC mode. Values: 0 - AGC. 1 - H AGC. 2 - MANUAL. The value is sent to the camera with the same command as gainMode.
shutterMode	int	Shutter mode. Values: 0 - OFF. 1 - 1/125. 2 - 1/250. 3 - 1/500. 4 - 1/1000. 5 - 1/2000. 6 - 1/4000. 7 - 1/10000. 8 - 1/50. 9 - 1/60. 10 - x1. 11 - x2. 12 - x4. 13 - x8. 14 - x16.
shutterPos	int	Not supported by KowaCamera class.
shutterSpeed	int	Shutter speed. Value: 1 - 100 (%).
digitalZoomMode	int	Not supported by KowaCamera class.
digitalZoom	float	Digital zoom. Value: 1 - 10. Fractional values are allowed (for example 2.5), values from 10.1 are rejected.
exposureCompensationMode	int	Not supported by KowaCamera class.
exposureCompensationPosition	int	Not supported by KowaCamera class.
defogMode	int	Defog mode. Values: 0 - Off 1 - Low 2 - Medium 3 - High
dehazeMode	int	Not supported by KowaCamera class.
noiseReductionMode	int	Noise reduction mode. Value: 0 - OFF. 1 - LOW. 2 - HIGH.
blackAndWhiteFilterMode	int	Not supported by KowaCamera class.
filterMode	int	Not supported by KowaCamera class.
nucMode	int	Not supported by KowaCamera class.
autoNucIntervalMsec	int	Not supported by KowaCamera class.
imageFlip	int	Not supported by KowaCamera class.
ddeMode	int	Not supported by KowaCamera class.
ddeLevel	float	Not supported by KowaCamera class.
roiX0	int	Not supported by KowaCamera class.
roiY0	int	Not supported by KowaCamera class.
roiX1	int	Not supported by KowaCamera class.
roiY1	int	Not supported by KowaCamera class.
temperature	float	Not supported by KowaCamera class.
alcGate	int	ALC gate mode. Values: 0 - OFF 1 - S/N 2 - STD 3 - MOVE 4 - MANUAL
sensitivity	float	Not supported by KowaCamera class.
changingMode	int	IR cut filter changing mode. Value: 0 - AUTO. 1 - REMOTE. 2 - COLOR. 3 - B/W.
changingLevel	float	IR cut filter changing level. Value: 0 - DARK. 1 - MID. 2 - BRIGHT. 3 - MANUAL.
chromaLevel	int	Chroma level. Value: 0 - 100 (%).
detail	int	Detail. Value: 0 - 100 (%).
profile	int	Not supported by KowaCamera class.
isConnected	bool	Connection status. Connection status shows if the controller has data exchange with equipment. For example, if serial port open but equipment can be not active (no power). In this case connection status shows that controller doesn’t have data exchange with equipment (methods will return 0). It the controller has data exchange with equipment the method will return 1. If the controller not initialize the connection status always FALSE. The KowaCamera library checks connection status every time when send command to camera. If no output commands to camera the method will return FALSE. Value: 0 - not connected. 1 - connected.
isOpen	bool	Controller initialization status. Open status shows if the controller initialized or not but doesn’t show if controller has communication with equipment. For example, if serial port open but equipment can be not active (no power). In this case open status just shows that the controller has opened serial port. Values: 0 - not open (not initialized), 1 - open (initialized).
type	int	Not supported by KowaCamera class.
custom1	float	Not supported by KowaCamera class.
custom2	float	Not supported by KowaCamera class.
custom3	float	Not supported by KowaCamera class.

None: CameraParams class fiellds listed in above reflect params set/get by methods setParam(…) and getParam(…).

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 to false.

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

CameraParamsMask structure declaration:

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

Example without parameters mask:

// Encode data.
rapidpixel::CameraParams in;
in.profile = 10;
uint8_t data[1024];
int size = 0;
if (!in.encode(data, 1024, size))
{
    std::cout << "Can't encode data" << std::endl;
}
std::cout << "Encoded data size: " << size << " bytes" << std::endl;

Example with parameters mask:

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

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

// Encode.
uint8_t data[1024];
int size = 0;
if (!in.encode(data, 1024, size, &mask))
{
    std::cout << "Can't encode data" << std::endl;
}
std::cout << "Encoded data size: " << size << " bytes" << std::endl;

Deserialize camera params

CameraParams class provides method decode(…) to deserialize camera params (fields of CameraParams class, see Table 4). 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.
rapidpixel::CameraParams in;
uint8_t data[1024];
int size = 0;
if (!in.encode(data, 1024, size))
{
    std::cout << "Can't encode data" << std::endl;
}
std::cout << "Encoded data size: " << size << " bytes" << std::endl;

// Decode data.
rapidpixel::CameraParams out;
if (!out.decode(data, size))
{
    std::cout << "Can't decode data" << std::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:

// Prepare params.
rapidpixel::CameraParams in;
in.initString = "/dev/ttyUSB0;9600";

// Write params to file.
rapidpixel::ConfigReader inConfig;
if (!inConfig.set(in, "cameraParams") ||
    !inConfig.writeToFile("TestCameraParams.json"))
{
    std::cout << "Can't write config file" << std::endl;
    return false;
}

// Read params from file.
rapidpixel::ConfigReader outConfig;
rapidpixel::CameraParams out;
if (!outConfig.readFromFile("TestCameraParams.json") ||
    !outConfig.get(out, "cameraParams"))
{
    std::cout << "Can't read config file" << std::endl;
    return false;
}

TestCameraParams.json will look like:

{
    "cameraParams": {
        "initString": "/dev/ttyUSB0;9600",
        "width": 0,
        "height": 0,
        "displayMode": 0,
        "videoOutput": 0,
        "logMode": 0,
        "exposureMode": 1,
        "exposureTime": 0,
        "whiteBalanceMode": 1,
        "whiteBalanceArea": 0,
        "wideDynamicRangeMode": 0,
        "stabilizationMode": 0,
        "isoSensitivity": 0,
        "sceneMode": 0,
        "fps": 0.0,
        "brightnessMode": 1,
        "brightness": 0,
        "contrast": 0,
        "gainMode": 1,
        "gain": 0,
        "sharpeningMode": 0,
        "sharpening": 0,
        "palette": 0,
        "agcMode": 1,
        "shutterMode": 1,
        "shutterPos": 0,
        "shutterSpeed": 0,
        "digitalZoomMode": 0,
        "digitalZoom": 1.0,
        "exposureCompensationMode": 0,
        "exposureCompensationPosition": 0,
        "defogMode": 0,
        "dehazeMode": 0,
        "noiseReductionMode": 0,
        "blackAndWhiteFilterMode": 0,
        "filterMode": 0,
        "nucMode": 0,
        "autoNucIntervalMsec": 0,
        "imageFlip": 0,
        "ddeMode": 0,
        "ddeLevel": 0.0,
        "roiX0": 0,
        "roiY0": 0,
        "roiX1": 0,
        "roiY1": 0,
        "alcGate": 0,
        "sensitivity": 0.0,
        "changingMode": 0,
        "changingLevel": 0.0,
        "chromaLevel": 0,
        "detail": 0,
        "profile": 0,
        "type": 0,
        "custom1": 0.0,
        "custom2": 0.0,
        "custom3": 0.0
    }
}

Build and connect to your project

Build stand alone

The repository does not contain sub-repositories. The protocol parser library KowaProtocolParser is a part of the repository (folder src/parser, see src/parser/README.md): the main CMakeLists.txt file of the library adds it before the library itself in every build (stand alone and included in another project), so it is not cloned and not added separately; its test application (src/parser/test) is not built. The other libraries KowaCamera depends on (ConfigReader, Camera, SerialPort, Logger) must be cloned into the same folder as KowaCamera. The folder structure must be:

<work folder>
    KowaCamera
    ConfigReader
    Camera
    SerialPort
    Logger

Typical commands to build the library, the test application and the example (use the URLs of the repositories provided to you):

git clone <KowaCamera repository URL>
git clone <ConfigReader repository URL>
git clone <Camera repository URL>
git clone <SerialPort repository URL>
git clone <Logger repository URL>
cd KowaCamera
mkdir build
cd build
cmake ..
make

On Windows use cmake --build . --config Release instead of make. If KowaCamera is the top-level CMake project, the main CMakeLists.txt file adds the folders ../ConfigReader, ../Camera, ../SerialPort and ../Logger (in this order) before the library itself. If a folder does not exist CMake stops with an error.

CMake options

Table 5 - CMake options of the repository. In the options below ${PARENT} is the prefix defined by the top-level project (empty if KowaCamera is the top-level project).

Option	Default	Description
${PARENT}_KOWA_CAMERA	ON	Build the library.
${PARENT}_KOWA_CAMERA_TEST	ON (stand alone), OFF (included in other project)	Build the test application.
${PARENT}_KOWA_CAMERA_EXAMPLE	ON (stand alone), OFF (included in other project)	Build the example.
${PARENT}_SUBMODULE_CACHE_OVERWRITE	ON	Forced rewriting of the options above in the CMake cache. The top-level project sets it to OFF when it includes KowaCamera as a sub-repository.
CMAKE_BUILD_TYPE	Release (if not specified)	Build type.

Connect to your project

If you want connect KowaCamera 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 the folders of the KowaCamera repository and of the repositories it depends on there (ConfigReader, Camera, SerialPort, Logger). New structure of your repository:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    ConfigReader
    Camera
    SerialPort
    Logger
    KowaCamera

Create CMakeLists.txt file in 3rdparty folder. CMakeLists.txt should contain (the libraries are added in the order of their dependencies, KowaCamera is the last):

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_CONFIG_READER                   ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_CONFIG_READER)
    SET(${PARENT}_CONFIG_READER                         ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_CONFIG_READER_EXAMPLES                OFF CACHE BOOL "" FORCE)
    SET(${PARENT}_CONFIG_READER_TESTS                   OFF CACHE BOOL "" FORCE)
endif()

SET(${PARENT}_SUBMODULE_CAMERA                          ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_CAMERA)
    SET(${PARENT}_CAMERA                                ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_CAMERA_TEST                           OFF CACHE BOOL "" FORCE)
    SET(${PARENT}_CAMERA_EXAMPLE                        OFF CACHE BOOL "" FORCE)
endif()

SET(${PARENT}_SUBMODULE_SERIAL_PORT                     ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_SERIAL_PORT)
    SET(${PARENT}_SERIAL_PORT                           ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_SERIAL_PORT_EXAMPLES                  OFF CACHE BOOL "" FORCE)
endif()

SET(${PARENT}_SUBMODULE_LOGGER                          ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_LOGGER)
    SET(${PARENT}_LOGGER                                ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_LOGGER_EXAMPLE                        OFF CACHE BOOL "" FORCE)
endif()

SET(${PARENT}_SUBMODULE_KOWA_CAMERA                     ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_KOWA_CAMERA)
    SET(${PARENT}_KOWA_CAMERA                           ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_KOWA_CAMERA_TEST                      OFF CACHE BOOL "" FORCE)
    SET(${PARENT}_KOWA_CAMERA_EXAMPLE                   OFF CACHE BOOL "" FORCE)
endif()

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

if (${PARENT}_SUBMODULE_CAMERA)
    add_subdirectory(Camera)
endif()

if (${PARENT}_SUBMODULE_SERIAL_PORT)
    add_subdirectory(SerialPort)
endif()

if (${PARENT}_SUBMODULE_LOGGER)
    add_subdirectory(Logger)
endif()

if (${PARENT}_SUBMODULE_KOWA_CAMERA)
    add_subdirectory(KowaCamera)
endif()

File 3rdparty/CMakeLists.txt adds the folders of the libraries to your project and excludes test applications and examples from compiling (by default test application is excluded from compiling if KowaCamera is included as sub-repository). When KowaCamera is included in another project it does not add its dependencies: the project must add ConfigReader, Camera, SerialPort and Logger itself, as in the file above (the order of the libraries is not important for CMake, but a library must be added to the project). If a dependency is missing the build stops with a compile error (for example “SerialPort.h: No such file or directory”). The new structure of your repository:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    CMakeLists.txt
    ConfigReader
    Camera
    SerialPort
    Logger
    KowaCamera

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 KowaCamera library in your src/CMakeLists.txt file:

target_link_libraries(${PROJECT_NAME} KowaCamera)

Done!

Portability

The library is written in C++17. It has no SIMD code and its code does not depend on the byte order. The library converts the values of params (for example percents) to the arguments of the camera commands with float arithmetic: the commands sent to the camera are identical on Linux x86-64 and on Linux AArch64. The library was built and run (with a camera emulated on a pseudo-terminal) with GCC 9, 11 and 12 on Linux x86-64 and with GCC 11 on Linux AArch64.

Simple example

Simple example is application which initializes controller and provide few options to user to control camera: change the digital zoom and switch the menu of the camera. A wrong input or the end of the input exits the application.

#include <iostream>
#include "KowaCamera.h"



namespace
{
/// Minimum digital zoom of the camera.
constexpr float MIN_ZOOM{1.0f};

/// Maximum digital zoom of the camera.
constexpr float MAX_ZOOM{10.0f};

/// Change of the digital zoom for one step.
constexpr float ZOOM_STEP{1.0f};
}



int main()
{
    // Init camera controller.
    rapidpixel::KowaCamera controller;
    if (!controller.openCamera("/dev/ttyUSB0;9600"))
    {
        std::cout << "Can't open the serial port" << std::endl;
        return 1;
    }

    while (true)
    {
        // Main dialog. A wrong input or the end of the input exits.
        int option = 0;
        std::cout << "Options (1:Zoom in, 2:Zoom out, 3:Menu on, "
                  << "4:Menu off, 0:Exit): ";
        if (!(std::cin >> option) || option == 0)
        {
            break;
        }
        std::cout << std::endl;

        switch (option)
        {
        case 1:
        case 2:
        {
            // Get the current zoom and change it inside the camera limits.
            const float step = (option == 1) ? ZOOM_STEP : -ZOOM_STEP;
            const float zoom = controller.getParam(
                rapidpixel::CameraParam::DIGITAL_ZOOM) + step;
            if (zoom < MIN_ZOOM || zoom > MAX_ZOOM)
            {
                std::cout << "Zoom limit reached" << std::endl;
            }
            else if (!controller.setParam(
                rapidpixel::CameraParam::DIGITAL_ZOOM, zoom))
            {
                std::cout << "Can't set zoom" << std::endl;
            }
            break;
        }
        case 3:
            if (!controller.executeCommand(
                rapidpixel::CameraCommand::MENU_ON))
            {
                std::cout << "Can't execute command" << std::endl;
            }
            break;
        case 4:
            if (!controller.executeCommand(
                rapidpixel::CameraCommand::MENU_OFF))
            {
                std::cout << "Can't execute command" << std::endl;
            }
            break;
        default:
            std::cout << "Wrong option" << std::endl;
            break;
        }
    }

    controller.closeCamera();
    return 0;
}

Test application

Folder KowaCamera/test contains the test application files. The test application works in the terminal only (no video, no graphical interface). It allows user to set params, get params, execute commands and show all params of the camera. The serial port name (for example /dev/ttyUSB0 for Linux) and the baudrate can be given in the command line:

KowaCameraTest [serial port name [baudrate]]

If the serial port name is not given the application asks it and the baudrate (an empty answer is 9600). The application checks everything the user enters and shows the result of every operation. The exit option (-1) or the end of the input in the main menu exits the application with code 0. The application exits with code 1 if the arguments are wrong, the input ends before the serial port is chosen, the serial port can’t be opened or 20 wrong menu options are entered in a row.

Test application output will look like:

========================================
KowaCamera v2.1.0 test
========================================
Enter serial port name: /dev/ttyUSB0
Enter baudrate (empty for 9600):
Choose option:
1 - Set camera param
2 - Get camera param
3 - Execute camera command
4 - Show all camera params
-1 - Exit
Enter option: 1
Camera params:
3 - DISPLAY_MODE (0 - menu off, 1 - menu on)
5 - LOG_MODE (0 - disable, 1 - file, 2 - terminal, 3 - file and terminal)
8 - WHITE_BALANCE_MODE (0 - ATW1, 1 - ATW2, 2 - AWC, 3 - manual, 4 - AWC exec)
10 - WIDE_DYNAMIC_RANGE_MODE (0 - off, 1 - WDR, 2 - auto knee, 3 - black stretch)
18 - GAIN_MODE (0 - AGC, 1 - H AGC, 2 - manual)
23 - AGC_MODE (0 - AGC, 1 - H AGC, 2 - manual)
24 - SHUTTER_MODE (0 - off, 1 - 1/125, 2 - 1/250, 3 - 1/500, 4 - 1/1000, 5 - 1/2000, 6 - 1/4000, 7 - 1/10000, 8 - 1/50, 9 - 1/60, 10 - x1, 11 - x2, 12 - x4, 13 - x8, 14 - x16)
26 - SHUTTER_SPEED (1 - 100 (%))
28 - DIGITAL_ZOOM (1 - 10 (x1 - x10))
31 - DEFOG_MODE (0 - off, 1 - low, 2 - middle, 3 - high)
33 - NOISE_REDUCTION_MODE (0 - off, 1 - low, 2 - high)
46 - ALC_GATE (0 - off, 1 - S/N, 2 - STD, 3 - move, 4 - manual)
48 - CHANGING_MODE (0 - auto, 1 - remote, 2 - color, 3 - B/W)
49 - CHANGING_LEVEL (0 - dark, 1 - middle, 2 - bright, 3 - manual)
50 - CHROMA_LEVEL (0 - 100 (%))
51 - DETAIL (0 - 100 (%))
Choose param (-1 to exit to main menu): 28
Enter value of DIGITAL_ZOOM (1 - 10 (x1 - x10)): 2.5
OK: DIGITAL_ZOOM = 2.5
Choose option:
1 - Set camera param
2 - Get camera param
3 - Execute camera command
4 - Show all camera params
-1 - Exit
Enter option: 3
Camera commands:
5 - MENU_ON
6 - MENU_OFF
7 - MENU_SET
8 - MENU_UP
9 - MENU_DOWN
10 - MENU_LEFT
11 - MENU_RIGHT
Choose command (-1 to exit to main menu): 5
OK: MENU_ON
Choose option:
1 - Set camera param
2 - Get camera param
3 - Execute camera command
4 - Show all camera params
-1 - Exit
Enter option: -1

---

Table of contents