klc_web_logo

Klc C++ library

v1.1.0

Table of contents

Overview

The Klc C++ library is a software controller for KOWA lenses. These lenses provide control interface over serial port. The Klc library inherits Lens interface. It depends on libraries: Lens (provides interface and data structures to control lenses), Logger (provides function to print logs), SerialPort (provides functions to work with serial ports) and KowaLensParser (provides encoding commands and decoding responses from lens; it is a part of the Klc repository: folder src/parser, see src/parser/README.md). The Lens library depends on the libraries Frame and ConfigReader. The repository of Klc doesn’t contain the source code of the other libraries: they are cloned next to the library (see Build stand alone). The Klc 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 is developed with C++17 standard and compatible with Linux and Windows.

Klc 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 lenses.

Versions

Table 1 - Library versions.

Version Release date What’s new
1.0.0 11.09.2022 - First version.
1.0.1 22.09.2022 - Fix focus position report.
1.0.2 03.04.2025 - Logger submodule update.
1.0.3 26.10.2025 - SerialPort submodule update.
- KowaLensParser submodule update.
1.0.4 02.02.2026 - Zoom/Focus speed ranges updated.
1.0.5 12.10.2026 - Submodules updated.
1.0.6 17.10.2026 - Git submodules removed: the libraries which Klc depends on are cloned next to the library (see Build stand alone).
- Warning options and security hardening options added to the CMake files.
- setParam(…) and executeCommand(…) reject NaN and values outside of the int range on all platforms.
- Iris speed is stored in the iris speed params.
- Negative baudrate or timeout in the init string is rejected.
- Positions received from the lens are limited to 0 - 65535 for any hardware limits.
- Data races of the communication thread fixed (lens params, response parser, closeLens()).
- Documentation corrected. Test application and example reworked.
1.1.0 29.10.2026 - The KowaLensParser library is a part of the repository (folder src/parser) and is not a separate dependency any more.

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.
src --------------------------------------- Folder with library source code.
    CMakeLists.txt ------------------------ CMake file of the library.
    Klc.h --------------------------------- Main library header file.
    Klc.cpp ------------------------------- C++ implementation file.
    KlcVersion.h -------------------------- Header file with library version.
    KlcVersion.h.in ----------------------- Service CMake file to generate version header.
    parser -------------------------------- Protocol parser library (former KowaLensParser repository).
        .gitignore ------------------------ Git ignore file of the parser library.
        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 (target KowaLensParser).
            KowaLensParser.cpp ------------ C++ implementation file of the parser library.
            KowaLensParser.h -------------- Main header file of the parser library (KowaLensParser class declaration).
            KowaLensParserVersion.h ------- Header file with version of the parser library.
            KowaLensParserVersion.h.in ---- CMake service file to generate version header of the parser library.
        static ---------------------------- Folder with images of the parser documentation.
            kowalensparser_web_logos.png -- Logo of the parser library.
        test ------------------------------ Folder with test application of the parser (not built by Klc).
            CMakeLists.txt ---------------- CMake file for test application of the parser.
            main.cpp ---------------------- Source C++ file of test application of the parser.
test -------------------------------------- Folder with test application files.
    CMakeLists.txt ------------------------ CMake file for test application.
    main.cpp ------------------------------ Source C++ file of test application.
example ----------------------------------- Folder with simple example application files.
    CMakeLists.txt ------------------------ CMake file for simple application example.
    main.cpp ------------------------------ Source C++ file of simple application example.
static ------------------------------------ Folder with the logo image of this document.

Klc class description

Klc class declaration

Klc.h file contains Klc class declaration.

namespace rapidpixel
{
class Klc : public Lens
{
public:

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

    /// Class constructor.
    Klc();

    /// Class destructor.
    ~Klc() override;

    /// Copy and move operations are deleted.
    Klc(const Klc&) = delete;
    Klc(Klc&&) = delete;
    Klc& operator=(const Klc&) = delete;
    Klc& operator=(Klc&&) = delete;

    /// Open the serial port and run the communication thread.
    bool openLens(std::string initString) override;

    /// Set lens params and open the controller.
    bool initLens(LensParams& params) override;

    /// Stop the communication thread and close the serial port.
    void closeLens() override;

    /// Get controller initialization status.
    bool isLensOpen() override;

    /// Get connection status.
    bool isLensConnected() override;

    /// Set the lens controller parameter.
    bool setParam(LensParam id, float value) override;

    /// Get the lens controller param.
    float getParam(LensParam id) override;

    /// Get the lens controller params.
    void getParams(LensParams& params) override;

    /// Execute command.
    bool executeCommand(LensCommand id, float arg = 0) override;

    /// Add video frame for auto focus purposes (not supported).
    void addVideoFrame(rapidpixel::Frame& frame) override;

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

getVersion method

The getVersion() static method returns string of current version of Klc class. Method declaration:

static std::string getVersion();

Method can be used without Klc class instance. Example:

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

Console output:

Klc version: 1.1.0

openLens method

The openLens(…) method opens serial port to communicate with KOWA lenses, sets the speed values of the lens speed slots and runs the communication thread (thread to communicate with equipment via serial port). The method returns after about 0.8 s: the lens needs a pause after each of 8 speed slot commands. The communication thread repeats a loop with 50 ms pause and the serial port read timeout. In each loop iteration the thread sends one command from the command buffer or, if the buffer is empty, one request of zoom, focus or iris position (in turn). If serial port already open this method does nothing and returns TRUE. Method declaration:

bool openLens(std::string initString) override;
Parameter Value
initString Initialization string. Format can be in 2 different forms:
- [serial port name];[baudrate];[timeout]
- [serial port name];[baudrate]
The baudrate is required. The timeout is the serial port read timeout in milliseconds (0 if it is not given). The baudrate and the timeout must be integers >= 0. Empty parts of the string are skipped. The string with another number of parts (for example only the serial port name) is not accepted. Recommended initialization string format for controllers which uses serial port: “/dev/ttyUSB0;19200;100” (“/dev/ttyUSB0” - serial port name, “19200” - baudrate, “100” - timeout).

Returns: TRUE if the controller is open (or was already open) or FALSE if not: invalid initialization string, the serial port can’t be opened or the communication thread can’t be started. If FALSE is returned the controller stays closed. The method doesn’t throw exceptions.

initLens method

The initLens(…) method initializes lens controller and sets lens params (Lens interface). The method sets the given log mode and the zoom, focus and iris hardware limits (logMode, zoomHwTeleLimit, zoomHwWideLimit, focusHwFarLimit, focusHwNearLimit, irisHwOpenLimit, irisHwCloseLimit fields of LensParams in this order) and after calls openLens(…) method. A value which is not accepted by setParam(…) is ignored: each limit is checked against the current value of its counterpart (for example the new tele limit must be greater than the current wide limit), so a pair of limits which is not accepted in this order is applied partly. The other fields (focus mode, filter mode, iris mode and extender mode) are not supported and are ignored. The params stay set if the controller can’t be opened. After successful initialization the library will run communication thread (thread to communicate with equipment via serial port) if it is not running already. Method declaration:

bool initLens(LensParams& params) override;
Parameter Value
params LensParams parameters class. LensParams class includes initString that is used in openLens(…) method. See description of LensParams class.

Returns: TRUE if the lens controller initialized or FALSE if not. The method doesn’t throw exceptions.

closeLens method

The closeLens() method stops the communication thread and closes serial port. The lens params isOpen and isConnected become FALSE. The commands which are not sent yet stay in the command buffer: the thread sends them after the next successful openLens(…) call. If another thread opens the controller at the same moment the method waits until the opening is finished. Method declaration:

void closeLens() override;

isLensOpen method

The isLensOpen() method returns lens controller initialization 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 not active (no power). In this case open status just shows that the serial port is open. Method declaration:

bool isLensOpen() override;

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

isLensConnected method

The isLensConnected() shows if the lens controller receives data from equipment: the status becomes TRUE when any data is received from the serial port after the controller was opened. For example, if serial port open but equipment not active (no power). In this case method isLensOpen(…) will return TRUE but isLensConnected() method will return FALSE. Method declaration:

bool isLensConnected() override;

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

setParam method

The setParam(…) method sets new lens parameters value. Klc provides thread-safe setParam(…) method call. This means that the setParam(…) method can be safely called from any thread. The supported parameters and their valid values are listed in Table 3. Position and speed parameters are converted to lens commands: the commands are put to the command buffer (48 commands, the oldest command is dropped if the buffer is full) and are sent by the communication thread. The method returns TRUE when the command is put to the buffer: it doesn’t wait for the lens. The position parameters are updated from the lens responses. Method declaration:

bool setParam(LensParam id, float value) override;
Parameter Description
id Lens parameter ID according to LensParam enum.
value Lens parameter value. Value depends on parameter ID (LensParam enum).

Returns: TRUE if the parameter was set or FALSE if not: unsupported parameter ID, the value is NaN or is outside of the valid range of the parameter. The lens params and the command buffer are not changed if FALSE is returned.

getParam method

The getParam(…) method returns lens parameter value. Klc provides thread-safe getParam(…) method call. This means that the getParam(…) method can be safely called from any thread. Method declaration:

float getParam(LensParam id) override;
Parameter Description
id Lens parameter ID according to LensParam enum.

Returns: parameter value or -1 if the parameter doesn’t exist (not supported, see Table 3).

getParams method

The getParams(…) method returns lens parameters class. Klc provides thread-safe getParams(…) method call. This means that the getParams(…) method can be safely called from any thread. Method declaration:

void getParams(LensParams& params) override;
Parameter Description
params Reference to LensParams class object which includes all lens parameters.

executeCommand method

The executeCommand(…) method to execute lens action command. Klc provides thread-safe executeCommand(…) method call. This means that the executeCommand(…) method can be safely called from any thread. The commands are put to the command buffer and are sent by the communication thread (see setParam(…)). The supported commands are listed in Table 2. Method declaration:

bool executeCommand(LensCommand id, float arg = 0) override;
Parameter Description
id Lens action command ID according to LensCommand enum.
arg Lens action command argument. Value depends on command ID (see description of LensCommand enum).

Returns: TRUE is the command was put to the command buffer or FALSE if not: unsupported command ID, the argument is NaN or is outside of the valid range of the command.

addVideoFrame method

The addVideoFrame(…) method copies video frame data to lens controller to perform autofocus algorithm. Autofocus algorithm not supported by Klc. The method doesn’t do anything and only provides an Lens interface. Method declaration:

void addVideoFrame(rapidpixel::Frame& frame) override;
Parameter Description
frame Video frame object (see Frame class description).

decodeAndExecuteCommand method

The decodeAndExecuteCommand(…) method decodes and executes command on controller side. Method will decode commands which encoded by encodeCommand(…) and encodeSetParamCommand(…) methods of Lens interface classes. If command decoded the method will call setParam(…) or executeCommand(…) methods for lens 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. Must not be nullptr. To generate input command you may use encodeCommand(…) and encodeSetParamCommand(…) methods.
size Size of command. 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) or FALSE if not: data is nullptr, the command can’t be decoded (wrong size, version, type or ID) or it is not accepted by setParam(…) or executeCommand(…).

encodeSetParamCommand method of Lens class

The encodeSetParamCommand(…) static method of Lens interface class designed to encode command to change any remote lens parameter. To control a lens 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 Lens class contains static methods for encoding the control command. The Lens 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, LensParam id, float value);
Parameter Description
data Pointer to data buffer for encoded command. Must not be nullptr and must be valid for 11 bytes.
size Size of encoded data. Will be 11 bytes (0 if data is nullptr).
id Parameter ID according to LensParam enum.
value Parameter value.

encodeSetParamCommand(…) is static and used without Lens class instance. This method used on client side (control system). Example:

// Buffer for encoded data.
uint8_t data[11];
// Size of encoded data.
int size{0};
// Encode command.
rapidpixel::Lens::encodeSetParamCommand(data, size, rapidpixel::LensParam::ZOOM_POS, 20000.0f);

encodeCommand method of Lens class

The encodeCommand(…) static method of Lens interface class designed to encode lens action command. To control a lens 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 Lens class contains static methods for encoding the control command. The Lens 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, LensCommand id, float arg = 0.0f);
Parameter Description
data Pointer to data buffer for encoded command. Must not be nullptr and must be valid for 11 bytes.
size Size of encoded data. Will be 11 bytes (0 if data is nullptr).
id Command ID according to LensCommand enum.
arg Command argument value (value depends on command ID).

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

// Buffer for encoded data.
uint8_t data[11];
// Size of encoded data.
int size{0};
// Encode command.
rapidpixel::Lens::encodeCommand(data, size, rapidpixel::LensCommand::ZOOM_TO_POS, 20000.0f);

decodeCommand method of Lens class

The decodeCommand(…) static method of Lens interface class designed to decode command on lens controller side. To control a lens remotely, the developer has to develop his own protocol and according to it decode the command on lens controller side. To simplify this, the Lens interface class contains static method to decode input command (commands should be encoded by methods encodeSetParamsCommand(…) or encodeCommand(…)). The Lens 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, LensParam& paramId, LensCommand& commandId, float& value);
Parameter Description
data Pointer to input command. Must not be nullptr.
size Size of command. Must be 11 bytes.
paramId Lens parameter ID according to LensParam enum. After decoding SET_PARAM command the method will return parameter ID.
commandId Lens command ID according to LensCommand enum. After decoding COMMAND the method will return command ID.
value Lens parameter value (after decoding SET_PARAM command) or lens command argument (after decoding COMMAND). The value is not checked against any range.

Returns: 0 - in case decoding COMMAND, 1 - in case decoding SET_PARAM command or -1 in case errors (null pointer, wrong size, version, command type or ID). The output arguments are changed only if the method returns 0 or 1.

Data structures

LensCommand enum

Enum declaration:

enum class LensCommand
{
    /// Move zoom tele (in). Command doesn't have arguments. User should be able
    /// to set zoom movement speed via lens parameters.
    ZOOM_TELE = 1,
    /// Move zoom wide (out). Command doesn't have arguments. User should be
    /// able to set zoom movement speed via lens parameters.
    ZOOM_WIDE,
    /// Move zoom to position. Lens controller should have zoom range from
    /// 0 (full wide) to 65535 (full tele) regardless of the hardware value of
    /// the zoom position. If the minimum and maximum zoom position limits are
    /// set by the user in the lens parameters, the range of the hardware zoom
    /// position must be scaled to the user space 0-65535 range.
    /// Command argument: zoom position 0-65535. User should be able to set zoom
    /// movement speed via lens parameters.
    ZOOM_TO_POS,
    /// Stop zoom moving including stop zoom to position command.
    ZOOM_STOP,
    /// Move focus far. Command doesn't have arguments. User should be able to
    /// set focus movement speed via lens parameters.
    FOCUS_FAR,
    /// Move focus near. Command doesn't have arguments. User should be able to
    /// set focus movement speed via lens parameters.
    FOCUS_NEAR,
    /// Move focus to position. Lens controller should have focus range from 0
    /// (full near) to 65535 (full far) regardless of the hardware value of the
    /// focus position. If the minimum and maximum focus position limits are
    /// set by the user in the lens parameters, the range of the hardware focus
    /// position must be scaled to the 0-65535 user space range.
    /// Command argument: focus position 0-65535. User should be able to set
    /// focus movement speed via lens parameters.
    FOCUS_TO_POS,
    /// Stop focus moving including stop focus to position command.
    FOCUS_STOP,
    /// Move iris open. Command doesn't have arguments. User should be able to
    /// set iris movement speed via lens parameters.
    IRIS_OPEN,
    /// Move iris close. Command doesn't have arguments. User should be able
    /// to set iris movement speed via lens parameters.
    IRIS_CLOSE,
    /// Move iris to position. Lens controller should have iris range
    /// from 0 (full close) to 65535 (full far) regardless of the hardware
    /// value of the iris position. If the minimum and maximum iris position
    /// limits are set by the user in the lens parameters, the range of the
    /// hardware iris position must be scaled to the 0-65535 user space range.
    /// Command argument: iris position 0-65535. User should be able to set
    /// iris movement speed via lens parameters.
    IRIS_TO_POS,
    /// Stop iris moving including stop iris to position command.
    /// Command doesn't have arguments.
    IRIS_STOP,
    /// Start autofocus.  Command doesn't have arguments.
    AF_START,
    /// Stop autofocus.  Command doesn't have arguments.
    AF_STOP,
    /// Restart lens controller.
    RESTART,
    /// Detect zoom and focus hardware ranges. After execution this command the
    /// lens controller should automatically set at least parameters
    /// (LensParam enum): ZOOM_HW_TELE_LIMIT, ZOOM_HW_WIDE_LIMIT,
    /// FOCUS_HW_FAR_LIMIT and FOCUS_HW_NEAR_LIMIT.
    DETECT_HW_RANGES
};

Table 2 - Lens commands description. Some commands may be unsupported by lens controller.

Command Description
ZOOM_TELE Move zoom tele (in). Command doesn’t have arguments.
ZOOM_WIDE Move zoom wide (out). Command doesn’t have arguments.
ZOOM_TO_POS Move zoom to position. Command argument: zoom position 0 (full wide) - 65535 (full tele).
ZOOM_STOP Stop zoom moving including stop zoom to position command. Command doesn’t have arguments. The lens command stops all motors (zoom, focus and iris).
FOCUS_FAR Move focus far. Command doesn’t have arguments.
FOCUS_NEAR Move focus near. Command doesn’t have arguments.
FOCUS_TO_POS Move focus to position. Command argument: focus position 0 (full near) - 65535 (full far).
FOCUS_STOP Stop focus moving including stop focus to position command. Command doesn’t have arguments. The lens command stops all motors (zoom, focus and iris).
IRIS_OPEN Move iris open. Command doesn’t have arguments.
IRIS_CLOSE Move iris close. Command doesn’t have arguments.
IRIS_TO_POS Move iris to position. Command argument: iris position 0 (full close) - 65535 (full open).
IRIS_STOP Stop iris moving including stop iris to position command. Command doesn’t have arguments. The lens command stops all motors (zoom, focus and iris).
AF_START Start autofocus (the lens executes auto focus one time). Command doesn’t have arguments.
AF_STOP Not supported by Klc class.
RESTART Not supported by Klc class.
DETECT_HW_RANGES Not supported by Klc class.

LensParam enum

Enum declaration:

enum class LensParam
{
    /// Zoom position. Setting a parameter is equivalent to the command
    /// ZOOM_TO_POS. Lens controller should have zoom range from 0 (full wide)
    /// to 65535 (full tele) regardless of the hardware value of the zoom
    /// position. If the minimum and maximum zoom position limits are set by
    /// the user in the lens parameters, the range of the hardware zoom position
    /// must be scaled to the user space 0-65535 range. Parameter value: zoom
    /// position 0-65535. User should be able to set zoom movement speed via
    /// lens parameters.
    ZOOM_POS = 1,
    /// Hardware zoom position. Parameter value depends on implementation and
    /// lens hardware.
    ZOOM_HW_POS,
    /// Focus position. Setting a parameter is equivalent to the command
    /// FOCUS_TO_POS. Lens controller should have focus range from 0 (full near)
    /// to 65535 (full far) regardless of the hardware value of the focus
    /// position. If the minimum and maximum focus position limits are set by
    /// the user in the lens parameters, the range of the hardware focus
    /// position must be scaled to the 0-65535 user space range. Parameter
    /// value: focus position 0-65535. User should be able to set focus movement
    /// speed via lens parameters.
    FOCUS_POS,
    /// Hardware focus position. Parameter value depends on implementation and
    /// lens hardware.
    FOCUS_HW_POS,
    /// Iris position. Setting a parameter is equivalent to the command
    /// IRIS_TO_POS. Lens controller should have iris range from 0 (full close)
    /// to 65535 (full far) regardless of the hardware value of the iris
    /// position. If the minimum and maximum iris position limits are set by the
    /// user in the lens parameters, the range of the hardware iris position
    /// must be scaled to the 0-65535 user space range. Parameter value: iris
    /// position 0-65535. User should be able to set iris movement speed via
    /// lens parameters.
    IRIS_POS,
    /// Hardware iris position. Parameter value depends on particular lens
    /// controller.
    IRIS_HW_POS,
    /// Focus mode. Parameter value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual focus control,
    /// 1 - Auto focus control.
    FOCUS_MODE,
    /// Filter mode. Parameter value depends on implementation but it is
    /// recommended to keep default values: 0 - Filter on, 1 - Filter off.
    FILTER_MODE,
    /// Autofocus ROI top-left corner horizontal position in pixels.
    /// Autofocus ROI is rectangle.
    AF_ROI_X0,
    /// Autofocus ROI top-left corner vertical position in pixels.
    /// Autofocus ROI is rectangle.
    AF_ROI_Y0,
    /// Autofocus ROI bottom-right corner horizontal position in pixels.
    /// Autofocus ROI is rectangle.
    AF_ROI_X1,
    /// Autofocus ROI bottom-right corner vertical position in pixels.
    /// Autofocus ROI is rectangle.
    AF_ROI_Y1,
    /// Zoom speed. Lens controller should have zoom speed range from 0 to
    /// 100% of max hardware zoom speed (parameter ZOOM_HW_MAX_SPEED).
    /// If the user sets a new parameter value of the ZOOM_HW_SPEED the
    /// parameter ZOOM_SPEED must be updated automatically. Formula for
    /// calculating speed:
    /// ZOOM_SPEED = ( ZOOM_HW_SPEED / ZOOM_HW_MAX_SPEED) * 100.
    ZOOM_SPEED,
    /// Zoom hardware speed. Value depends on implementation and lens hardware.
    /// The value of the parameters must be <= ZOOM_HW_MAX_SPEED parameter.
    /// If the user sets a new parameter value of the ZOOM_SPEED parameter
    /// the parameter ZOOM_HW_SPEED must be updated automatically.
    /// Formula for calculating hardware speed:
    /// ZOOM_HW_SPEED = ( ZOOM_SPEED / 100 ) * ZOOM_HW_MAX_SPEED.
    ZOOM_HW_SPEED,
    /// Maximum zoom hardware speed. Value depends on implementation.
    /// If user sets new ZOOM_HW_MAX_SPEED value the parameters
    /// ZOOM_SPEED must be updated automatically. If new value of
    /// ZOOM_HW_MAX_SPEED parameter will be less than ZOOM_HW_SPEED the
    /// parameter ZOOM_HW_SPEED must be reduced automatically.
    ZOOM_HW_MAX_SPEED,
    /// Focus speed. Lens controller should have focus speed range from 0 to
    /// 100% of max hardware focus speed (parameter FOCUS_HW_MAX_SPEED).
    /// If the user sets a new parameter value of the FOCUS_HW_SPEED the
    /// parameter FOCUS_SPEED must be updated automatically. Formula for
    /// calculating speed: FOCUS_SPEED = ( FOCUS_HW_SPEED / FOCUS_HW_MAX_SPEED)
    /// * 100.
    FOCUS_SPEED,
    /// Focus hardware speed. Value depends on on implementation and lens
    /// hardware. The value of the parameters must be <= FOCUS_HW_MAX_SPEED
    /// parameter. If the user sets a new parameter value of the FOCUS_SPEED
    /// parameter the parameter FOCUS_HW_SPEED must be updated automatically.
    /// Formula for calculating hardware speed:
    /// FOCUS_HW_SPEED = ( FOCUS_SPEED / 100 ) * FOCUS_HW_MAX_SPEED.
    FOCUS_HW_SPEED,
    /// Maximum focus hardware speed. Value depends on implementation.
    /// If user sets new FOCUS_HW_MAX_SPEED value the parameters
    /// FOCUS_SPEED and FOCUS_HW_SPEED must be updated by lens controller
    /// automatically. If new value of FOCUS_HW_MAX_SPEED parameter will be
    /// less than FOCUS_HW_SPEED the parameter FOCUS_HW_SPEED must be reduced
    /// automatically.
    FOCUS_HW_MAX_SPEED,
    /// Iris speed. Lens controller should have iris speed range from 0 to 100%
    /// of max hardware iris speed (parameter IRIS_HW_MAX_SPEED). If the user
    /// sets a new parameter value of the IRIS_HW_SPEED the parameter IRIS_SPEED
    /// must be updated automatically. Formula for calculating speed:
    /// IRIS_SPEED = ( IRIS_HW_SPEED / IRIS_HW_MAX_SPEED) * 100.
    IRIS_SPEED,
    /// Iris hardware speed. Value depends on implementation and lens hardware.
    /// The value of the parameters must be <= IRIS_HW_MAX_SPEED parameter.
    /// If the user sets a new parameter value of the IRIS_SPEED parameter
    /// the parameter IRIS_HW_SPEED must be updated automatically. Formula
    /// for calculating hardware speed:
    /// IRIS_HW_SPEED = ( IRIS_SPEED / 100 ) * IRIS_HW_MAX_SPEED.
    IRIS_HW_SPEED,
    /// Maximum iris hardware speed. Value depends on implementation. If user
    /// sets new IRIS_HW_MAX_SPEED value the parameters IRIS_SPEED and
    /// IRIS_HW_SPEED must be updated automatically. If new value of
    /// IRIS_HW_MAX_SPEED parameter will be less than IRIS_HW_SPEED the
    /// parameter IRIS_HW_SPEED must be reduced automatically.
    IRIS_HW_MAX_SPEED,
    /// Zoom hardware tele limit. Value depends on implementation and lens
    /// hardware. Lens controller should control zoom position. Lens controller
    /// should stop zoom moving if hardware zoom position will be out of limits.
    ZOOM_HW_TELE_LIMIT,
    /// Zoom hardware wide limit. Value depends on implementation and lens
    /// hardware. Lens controller should control zoom position. Lens controller
    /// should stop zoom moving if hardware zoom position will be out of limits.
    ZOOM_HW_WIDE_LIMIT,
    /// Focus hardware far limit. Value depends on on implementation and lens
    /// hardware. Lens controller should control focus position. Lens controller
    /// should stop focus moving if hardware focus position will be out of
    /// limits.
    FOCUS_HW_FAR_LIMIT,
    /// Focus hardware near limit. Value depends on implementation and lens
    /// hardware. Lens controller should control focus position. Lens controller
    /// should stop focus moving if hardware focus position will be out of
    /// limits.
    FOCUS_HW_NEAR_LIMIT,
    /// Iris hardware open limit. Value depends on implementation and lens
    /// hardware. Lens controller should control iris position. Lens controller
    /// should stop iris moving if hardware iris position will be out of limits.
    IRIS_HW_OPEN_LIMIT,
    /// Iris hardware close limit. Value depends on implementation and lens
    /// hardware. Lens controller should control iris position. Lens controller
    /// should stop iris moving if hardware iris position will be out of limits.
    IRIS_HW_CLOSE_LIMIT,
    /// Focus factor if it was calculated. If not calculated must be -1.
    /// Value depends on particular lens controller.
    FOCUS_FACTOR,
    /// Lens connection status. Connection status shows if the lens controller
    /// has data exchange with lens equipment. For example, if lens has serial
    /// port lens controller connects to serial port
    /// (opens serial port file in OS) but lens can be not active (no power).
    /// In this case connection status shows that lens controller doesn't have
    /// data exchange with lens equipment (the value is 0). If lens controller
    /// has data exchange with lens equipment the value is 1. If lens controller
    /// not initialize the connection status always FALSE. Value: 0 - not
    /// connected. 1 - connected.
    IS_CONNECTED,
    /// Focus hardware speed in autofocus mode. Value depends on implementation
    /// and lens hardware.
    FOCUS_HW_AF_SPEED,
    /// Threshold for changes of focus factor to start refocus. Value:
    /// 0% - no check, 100% - changing x2.
    FOCUS_FACTOR_THRESHOLD,
    /// Timeout for automatic refocus in seconds. Value:
    /// 0 - no automatic refocus, 100000 - maximum value.
    REFOCUS_TIMEOUT_SEC,
    /// Flag about active autofocus algorithm. Value: 0 - autofocus not working,
    /// 1 - working.
    AF_IS_ACTIVE,
    /// Iris mode. Value depends on implementation but it is recommended to keep
    /// default values: 0 - manual iris control, 1 - auto iris control.
    IRIS_MODE,
    /// ROI width (pixels) for autofocus algorithm when lens controller detects
    /// ROI position automatically. Value: from 8 to (video frame width -
    /// AUTO_AF_ROI_BORDER * 2).
    AUTO_AF_ROI_WIDTH,
    /// ROI height (pixels) for autofocus algorithm when lens controller
    /// detects ROI position automatically. Value: from 8 to
    /// (video frame height - AUTO_AF_ROI_BORDER * 2).
    AUTO_AF_ROI_HEIGHT,
    /// Video frame border size (along vertical and horizontal axes).
    /// Value: border size from 0 to video frame
    /// min(video frame width/height) / 2.
    AUTO_AF_ROI_BORDER,
    /// AF ROI mode (write/read). Value: 0 - Manual position, 1 - Auto position.
    AF_ROI_MODE,
    /// Lens extender mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - no extender, 1 - x2 extender.
    EXTENDER_MODE,
    /// Lens stabilization mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - no stabilization,
    /// 1 - stabilization.
    STABILIZER_MODE,
    /// Autofocus range. Value depends on implementation.
    AF_RANGE,
    /// Current horizontal Field of view, degree. Field of view calculated by
    /// lens controller according to initial params or by reading directly from
    /// lens hardware.
    X_FOV_DEG,
    /// Current vertical Field of view, degree. Field of view calculated by lens
    /// controller according to initial params or by reading directly from lens
    /// hardware.
    Y_FOV_DEG,
    /// Logging mode. Values: 0 - Disable, 1 - Only file, 2 - Only terminal,
    /// 3 - File and terminal.
    LOG_MODE,
    /// Lens temperature, degree.
    TEMPERATURE,
    /// Lens controller initialization status. Open status shows if the lens
    /// controller initialized or not but doesn't show if lens controller has
    /// communication with lens equipment. For example, if lens has serial port
    /// lens controller connects to serial port (opens serial port file in OS)
    /// but lens can be not active (no power). In this case open status just
    /// shows that lens controller has opened serial port. Values: 0 - not open
    /// (not initialized), 1 - open (initialized).
    IS_OPEN,
    /// Lens type. Value depends on implementation. Type allows to lens
    /// initialize necessary parameters for particular lens hardware.
    TYPE,
    /// Lens custom parameter. Value depends on particular lens controller.
    /// Custom parameters used when particular lens equipment has specific
    /// unusual parameter.
    CUSTOM_1,
    /// Lens custom parameter. Value depends on particular lens controller.
    /// Custom parameters used when particular lens equipment has specific
    /// unusual parameter.
    CUSTOM_2,
    /// Lens custom parameter. Value depends on particular lens controller.
    /// Custom parameters used when particular lens equipment has specific
    /// unusual parameter.
    CUSTOM_3
};

Table 3 - Lens params description. Some params may be unsupported by lens controller.

Parameter Access Description
ZOOM_POS read / write Zoom position. Setting a parameter is equivalent to the command ZOOM_TO_POS. Param argument: zoom position 0 (full wide) - 65535 (full tele). It doesn’t change the zoom position value immediately. The zoom position changes only when the lens moves.
ZOOM_HW_POS read / write Hardware zoom position. Setting a parameter move zoom to HW position. Param argument: zoom position ZOOM_HW_WIDE_LIMIT - ZOOM_HW_TELE_LIMIT. By default ZOOM_HW_WIDE_LIMIT = 1126, ZOOM_HW_TELE_LIMIT = 64461. It doesn’t change the zoom position value immediately. The zoom position changes only when the lens moves.
FOCUS_POS read / write Focus position. Setting a parameter is equivalent to the command FOCUS_TO_POS. Parameter value: focus position 0 (full near) - 65535 (full far). It doesn’t change the focus position value immediately. The focus position changes only when the lens moves.
FOCUS_HW_POS read / write Focus position. Setting a parameter move focus to HW position. Parameter value: focus position FOCUS_HW_NEAR_LIMIT - FOCUS_HW_FAR_LIMIT. By default FOCUS_HW_NEAR_LIMIT = 0, FOCUS_HW_FAR_LIMIT = 65535. It doesn’t change the focus position value immediately. The focus position changes only when the lens moves.
IRIS_POS read / write Iris position. Setting a parameter is equivalent to the command IRIS_TO_POS. Param argument: iris position 0 (full close) - 65535 (full open). It doesn’t change the iris position value immediately. The iris position changes only when the lens moves.
IRIS_HW_POS read / write Iris position. Setting a parameter move iris to HW position. Parameter value: iris position IRIS_HW_CLOSE_LIMIT - IRIS_HW_OPEN_LIMIT. By default IRIS_HW_CLOSE_LIMIT = 0, IRIS_HW_OPEN_LIMIT= 65535. It doesn’t change the iris position value immediately. The iris position changes only when the lens moves.
FOCUS_MODE read / write Not supported by Klc class.
FILTER_MODE read / write Not supported by Klc class.
AF_ROI_X0 read / write Not supported by Klc class.
AF_ROI_Y0 read / write Not supported by Klc class.
AF_ROI_X1 read / write Not supported by Klc class.
AF_ROI_Y1 read / write Not supported by Klc class.
ZOOM_SPEED read / write Zoom speed 0-100%. Kowa lens doesn’t support direct speed control. Kowa lens has 4 speed slots with predefined speed values: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed. Zoom speed value [0:24] set speed slot 0, [25:49] set speed slot 1, [50:74] set speed slot 2, [75:100] set speed slot 3. After the speed is set the parameter has the upper value of the range of the slot: 25, 50, 75 or 100. Default value 50.
ZOOM_HW_SPEED read only Zoom speed slot: 0 - slowest speed, 3 - fastest speed. The slot is selected by ZOOM_SPEED. Default value 1.
ZOOM_HW_MAX_SPEED read / write Not supported by Klc class.
FOCUS_SPEED read / write Focus speed 0-100%. Kowa lens doesn’t support direct speed control. Kowa lens has 4 speed slots with predefined speed values: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed. Focus speed value [0:24] set speed slot 0, [25:49] set speed slot 1, [50:74] set speed slot 2, [75:100] set speed slot 3. After the speed is set the parameter has the upper value of the range of the slot: 25, 50, 75 or 100. Default value 50.
FOCUS_HW_SPEED read only Focus speed slot: 0 - slowest speed, 3 - fastest speed. The slot is selected by FOCUS_SPEED. Default value 1.
FOCUS_HW_MAX_SPEED read / write Not supported by Klc class.
IRIS_SPEED read / write Iris speed 0-100%. Kowa lens doesn’t support direct speed control. Kowa lens has 4 speed slots with predefined speed values: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed. Iris speed value [0:24] set speed slot 0, [25:49] set speed slot 1, [50:74] set speed slot 2, [75:100] set speed slot 3. After the speed is set the parameter has the upper value of the range of the slot: 25, 50, 75 or 100. Default value 50.
IRIS_HW_SPEED read only Iris speed slot: 0 - slowest speed, 3 - fastest speed. The slot is selected by IRIS_SPEED. Default value 1.
IRIS_HW_MAX_SPEED read / write Not supported by Klc class.
ZOOM_HW_TELE_LIMIT read / write Zoom hardware tele limit 0 - 65535, must be greater than ZOOM_HW_WIDE_LIMIT. Default value 64461.
ZOOM_HW_WIDE_LIMIT read / write Zoom hardware wide limit 0 - 65535, must be less than ZOOM_HW_TELE_LIMIT. Default value 1126.
FOCUS_HW_FAR_LIMIT read / write Focus hardware far limit 0 - 65535, must be greater than FOCUS_HW_NEAR_LIMIT. Default value 65535.
FOCUS_HW_NEAR_LIMIT read / write Focus hardware near limit 0 - 65535, must be less than FOCUS_HW_FAR_LIMIT. Default value 0.
IRIS_HW_OPEN_LIMIT read / write Iris hardware open limit 0 - 65535, must be greater than IRIS_HW_CLOSE_LIMIT. Default value 65535.
IRIS_HW_CLOSE_LIMIT read / write Iris hardware close limit 0 - 65535, must be less than IRIS_HW_OPEN_LIMIT. Default value 0.
FOCUS_FACTOR read only Not supported by Klc class.
IS_CONNECTED read only Lens connection status. Connection status shows if the lens controller has received data from lens equipment. Values:
0 - no data from lens.
1 - connected.
FOCUS_HW_AF_SPEED read / write Not supported by Klc class.
FOCUS_FACTOR_THRESHOLD read / write Not supported by Klc class.
REFOCUS_TIMEOUT_SEC read / write Not supported by Klc class.
AF_IS_ACTIVE read only Not supported by Klc class.
IRIS_MODE read / write Not supported by Klc class.
AUTO_AF_ROI_WIDTH read / write Not supported by Klc class.
AUTO_AF_ROI_HEIGHT read / write Not supported by Klc class.
AUTO_AF_ROI_BORDER read / write Not supported by Klc class.
AF_ROI_MODE read / write Not supported by Klc class.
EXTENDER_MODE read / write Not supported by Klc class.
STABILIZER_MODE read / write Not supported by Klc class.
AF_RANGE read / write Not supported by Klc class.
X_FOV_DEG read / write Not supported by Klc class.
Y_FOV_DEG read / write Not supported by Klc class.
LOG_MODE read / write Logging mode. Values:
0 - Disable.
1 - Only terminal.
2 - Only file.
3 - File and terminal.
TEMPERATURE read only Not supported by Klc class.
IS_OPEN read only Lens controller initialization status. Open status shows if the lens controller initialized or not but doesn’t show if lens controller has communication with lens equipment. Values:
0 - not open (not initialized).
1 - open (initialized).
TYPE read / write Not supported by Klc class.
CUSTOM_1 read / write Not supported by Klc class.
CUSTOM_2 read / write Not supported by Klc class.
CUSTOM_3 read / write Not supported by Klc class.

LensParams class description

LensParams class used for lens controller initialization (initLens method) or to get all actual params (getParams method). Also LensParams provides structure to write/read params from JSON files (JSON_READABLE macro) and provides methods to encode and decode params.

LensParams class declaration

LensParams interface class declared in Lens.h file. Class declaration:

/// Field of view point class.
class FovPoint
{
public:
    /// Hardware zoom pos.
    int hwZoomPos{0};
    /// Horizontal field of view, degree.
    float xFovDeg{0.0f};
    /// Vertical field of view, degree.
    float yFovDeg{0.0f};

    JSON_READABLE(FovPoint, hwZoomPos, xFovDeg, yFovDeg)

    /// Default constructor.
    FovPoint() = default;

    /// Copy constructor.
    FovPoint(const FovPoint& src) = default;

    /// Move constructor.
    FovPoint(FovPoint&& src) = default;

    /// Copy assignment operator.
    FovPoint& operator= (const FovPoint& src) = default;

    /// Move assignment operator.
    FovPoint& operator= (FovPoint&& src) = default;
};

/// Lens params class.
class LensParams
{
public:
    /// Initialization string. Particular lens controller can have unique init
    /// string format. But it is recommended to use '**;**' symbol to divide
    /// parts of initialization string. Recommended initialization string format
    /// for controllers which uses serial port: "/dev/ttyUSB0;9600;100"
    /// ("/dev/ttyUSB0" - serial port name, "9600" - baudrate, "100" - serial
    /// port read timeout).
    std::string initString{"/dev/ttyUSB0;9600;20"};
    /// Zoom position. Setting a parameter is equivalent to the command
    /// ZOOM_TO_POS. Lens controller should have zoom range from 0 (full wide)
    /// to 65535 (full tele) regardless of the hardware value of the zoom
    /// position. If the minimum and maximum zoom position limits are set by
    /// the user in the lens parameters, the range of the hardware zoom position
    /// must be scaled to the user space 0-65535 range. Parameter value: zoom
    /// position 0-65535. User should be able to set zoom movement speed via
    /// lens parameters.
    int zoomPos{0};
    /// Hardware zoom position. Parameter value depends on implementation and
    /// lens hardware.
    int zoomHwPos{0};
    /// Focus position. Setting a parameter is equivalent to the command
    /// FOCUS_TO_POS. Lens controller should have focus range from 0 (full near)
    /// to 65535 (full far) regardless of the hardware value of the focus
    /// position. If the minimum and maximum focus position limits are set by
    /// the user in the lens parameters, the range of the hardware focus
    /// position must be scaled to the 0-65535 user space range. Parameter
    /// value: focus position 0-65535. User should be able to set focus movement
    /// speed via lens parameters.
    int focusPos{0};
    /// Hardware focus position. Parameter value depends on implementation and
    /// lens hardware.
    int focusHwPos{0};
    /// Iris position. Setting a parameter is equivalent to the command
    /// IRIS_TO_POS. Lens controller should have iris range from 0 (full close)
    /// to 65535 (full far) regardless of the hardware value of the iris
    /// position. If the minimum and maximum iris position limits are set by the
    /// user in the lens parameters, the range of the hardware iris position
    /// must be scaled to the 0-65535 user space range. Parameter value: iris
    /// position 0-65535. User should be able to set iris movement speed via
    /// lens parameters.
    int irisPos{0};
    /// Hardware iris position. Parameter value depends on implementation.
    int irisHwPos{0};
    /// Focus mode. Parameter value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual focus control,
    /// 1 - Auto focus control.
    int focusMode{0};
    /// Filter mode. Parameter value depends on implementation but it is
    /// recommended to keep default values: 0 - Filter on, 1 - Filter off.
    int filterMode{0};
    /// Autofocus ROI top-left corner horizontal position in pixels.
    /// Autofocus ROI is rectangle.
    int afRoiX0{0};
    /// Autofocus ROI top-left corner vertical position in pixels.
    /// Autofocus ROI is rectangle.
    int afRoiY0{0};
    /// Autofocus ROI bottom-right corner horizontal position in pixels.
    /// Autofocus ROI is rectangle.
    int afRoiX1{0};
    /// Autofocus ROI bottom-right corner vertical position in pixels.
    /// Autofocus ROI is rectangle.
    int afRoiY1{0};
    /// Zoom speed. Lens controller should have zoom speed range from 0 to
    /// 100% of max hardware zoom speed (parameter ZOOM_HW_MAX_SPEED). If the
    /// user sets a new parameter value of the ZOOM_HW_SPEED the parameter
    /// ZOOM_SPEED must be updated automatically. Formula for calculating speed:
    /// ZOOM_SPEED = ( ZOOM_HW_SPEED / ZOOM_HW_MAX_SPEED) * 100.
    int zoomSpeed{50};
    /// Zoom hardware speed. Value depends on implementation and lens hardware.
    /// The value of the parameters must be <= ZOOM_HW_MAX_SPEED parameter.
    /// If the user sets a new parameter value of the ZOOM_SPEED parameter
    /// the parameter ZOOM_HW_SPEED must be updated automatically. Formula for
    /// calculating hardware speed:
    /// ZOOM_HW_SPEED = ( ZOOM_SPEED / 100 ) * ZOOM_HW_MAX_SPEED.
    int zoomHwSpeed{50};
    /// Maximum zoom hardware speed. Value depends on implementation. If user
    /// sets new ZOOM_HW_MAX_SPEED value the parameters ZOOM_SPEED must be
    /// updated automatically. If new value of ZOOM_HW_MAX_SPEED parameter will
    /// be less than ZOOM_HW_SPEED the parameter ZOOM_HW_SPEED must be reduced
    /// automatically.
    int zoomHwMaxSpeed{50};
    /// Focus speed. Lens controller should have focus speed range from 0 to
    /// 100% of max hardware focus speed (parameter FOCUS_HW_MAX_SPEED). If the
    /// user sets a new parameter value of the FOCUS_HW_SPEED the parameter
    /// FOCUS_SPEED must be updated automatically. Formula for calculating
    /// speed: FOCUS_SPEED = ( FOCUS_HW_SPEED / FOCUS_HW_MAX_SPEED) * 100.
    int focusSpeed{50};
    /// Focus hardware speed. Value depends on on implementation and lens
    /// hardware. The value of the parameters must be <= FOCUS_HW_MAX_SPEED
    /// parameter. If the user sets a new parameter value of the FOCUS_SPEED
    /// parameter the parameter FOCUS_HW_SPEED must be updated automatically.
    /// Formula for calculating hardware speed:
    /// FOCUS_HW_SPEED = ( FOCUS_SPEED / 100 ) * FOCUS_HW_MAX_SPEED.
    int focusHwSpeed{50};
    /// Maximum focus hardware speed. Value depends on implementation. If user
    /// sets new FOCUS_HW_MAX_SPEED value the parameters FOCUS_SPEED and
    /// FOCUS_HW_SPEED must be updated by lens controller automatically.
    /// If new value of FOCUS_HW_MAX_SPEED parameter will be less than
    /// FOCUS_HW_SPEED the parameter FOCUS_HW_SPEED must be reduced
    /// automatically.
    int focusHwMaxSpeed{50};
    /// Iris speed. Lens controller should have iris speed range from 0 to 100%
    /// of max hardware iris speed (parameter IRIS_HW_MAX_SPEED). If the user
    /// sets a new parameter value of the IRIS_HW_SPEED the parameter IRIS_SPEED
    /// must be updated automatically. Formula for calculating speed:
    /// IRIS_SPEED = ( IRIS_HW_SPEED / IRIS_HW_MAX_SPEED) * 100.
    int irisSpeed{50};
    /// Iris hardware speed. Value depends on implementation and lens hardware.
    /// The value of the parameters must be <= IRIS_HW_MAX_SPEED parameter.
    /// If the user sets a new parameter value of the IRIS_SPEED parameter the
    /// parameter IRIS_HW_SPEED must be updated automatically. Formula for
    /// calculating hardware speed:
    /// IRIS_HW_SPEED = ( IRIS_SPEED / 100 ) * IRIS_HW_MAX_SPEED.
    int irisHwSpeed{50};
    /// Maximum iris hardware speed. Value depends on implementation. If user
    /// sets new IRIS_HW_MAX_SPEED value the parameters IRIS_SPEED and
    /// IRIS_HW_SPEED must be updated automatically. If new value of
    /// IRIS_HW_MAX_SPEED parameter will be less than IRIS_HW_SPEED the
    /// parameter IRIS_HW_SPEED must be reduced automatically.
    int irisHwMaxSpeed{50};
    /// Zoom hardware tele limit. Value depends on implementation and lens
    /// hardware. Lens controller should control zoom position. Lens controller
    /// should stop zoom moving if hardware zoom position will be out of limits.
    int zoomHwTeleLimit{65535};
    /// Zoom hardware wide limit. Value depends on implementation and lens
    /// hardware. Lens controller should control zoom position. Lens controller
    /// should stop zoom moving if hardware zoom position will be out of limits.
    int zoomHwWideLimit{0};
    /// Focus hardware far limit. Value depends on on implementation and lens
    /// hardware. Lens controller should control focus position. Lens controller
    /// should stop focus moving if hardware focus position will be out of
    /// limits.
    int focusHwFarLimit{65535};
    /// Focus hardware near limit. Value depends on implementation and lens
    /// hardware. Lens controller should control focus position. Lens controller
    /// should stop focus moving if hardware focus position will be out of
    /// limits.
    int focusHwNearLimit{0};
    /// Iris hardware open limit. Value depends on implementation and lens
    /// hardware. Lens controller should control iris position. Lens controller
    /// should stop iris moving if hardware iris position will be out of limits.
    int irisHwOpenLimit{65535};
    /// Iris hardware close limit. Value depends on implementation and lens
    /// hardware. Lens controller should control iris position. Lens controller
    /// should stop iris moving if hardware iris position will be out of limits.
    int irisHwCloseLimit{0};
    /// Focus factor if it was calculated. If not calculated must be -1.
    /// Value depends on particular lens controller.
    float focusFactor{0.0f};
    /// Lens connection status. Connection status shows if the lens controller
    /// has data exchange with lens equipment. For example, if lens has serial
    /// port lens controller connects to serial port (opens serial port file
    /// in OS) but lens can be not active (no power). In this case connection
    /// status shows that lens controller doesn't have data exchange with lens
    /// equipment. If lens controller has data exchange with lens equipment
    /// the value is TRUE. If lens controller not initialize the connection
    /// status always FALSE. Value: false - not connected. true - connected.
    bool isConnected{false};
    /// Focus hardware speed in autofocus mode. Value depends on implementation
    /// and lens hardware.
    int afHwSpeed{50};
    /// Threshold for changes of focus factor to start refocus. Value:
    /// 0% - no check, 100% - changing x2.
    float focusFactorThreshold{0.0f};
    /// Timeout for automatic refocus in seconds. Value:
    /// 0 - no automatic refocus, 100000 - maximum value.
    int refocusTimeoutSec{0};
    /// Flag about active autofocus algorithm. Value: 0 - autofocus not working,
    /// 1 - working.
    bool afIsActive{false};
    /// Iris mode. Value depends on implementation but it is recommended to keep
    /// default values: 0 - manual iris control, 1 - auto iris control.
    int irisMode{0};
    /// ROI width (pixels) for autofocus algorithm when lens controller detects
    /// ROI position automatically. Value: from 8 to (video frame width -
    /// AUTO_AF_ROI_BORDER * 2).
    int autoAfRoiWidth{150};
    /// ROI height (pixels) for autofocus algorithm when lens controller detects
    /// ROI position automatically. Value: from 8 to (video frame height -
    /// AUTO_AF_ROI_BORDER * 2).
    int autoAfRoiHeight{150};
    /// Video frame border size (along vertical and horizontal axes).
    /// Value: border size from 0 to video
    /// frame min(video frame width/height) / 2.
    int autoAfRoiBorder{100};
    /// AF ROI mode (write/read). Value: 0 - Manual position, 1 - Auto position.
    int afRoiMode{0};
    /// Lens extender mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - no extender, 1 - x2 extender.
    int extenderMode{0};
    /// Lens stabilization mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - no stabilization,
    /// 1 - stabilization.
    int stabiliserMode{0};
    /// Autofocus range. Value depends on implementation.
    int afRange{0};
    /// Current horizontal Field of view, degree. Field of view calculated by
    /// lens controller according to initial params or by reading directly from
    /// lens hardware.
    float xFovDeg{1.0f};
    /// Current vertical Field of view, degree. Field of view calculated by lens
    /// controller according to initial params or by reading directly from lens
    /// hardware.
    float yFovDeg{1.0f};
    /// Logging mode. Values: 0 - Disable, 1 - Only file, 2 - Only terminal,
    /// 3 - File and terminal.
    int logMode{0};
    /// Lens temperature, degree (read only).
    float temperature{0.0f};
    /// Lens controller initialization status. Open status shows if the lens
    /// controller initialized or not but doesn't show if lens controller has
    /// communication with lens equipment. For example, if lens has serial port
    /// lens controller connects to serial port (opens serial port file in OS)
    /// but lens can be not active (no power). In this case open status just
    /// shows that lens controller has opened serial port.
    /// Values: false - not open (not initialized), true - open (initialized).
    bool isOpen{false};
    /// Lens type. Value depends on implementation. Type allows to lens
    /// initialize necessary parameters for particular lens hardware.
    int type{0};
    /// Lens custom parameter. Value depends on particular lens controller.
    /// Custom parameters used when particular lens equipment has specific
    /// unusual parameter.
    float custom1{0.0f};
    /// Lens custom parameter. Value depends on particular lens controller.
    /// Custom parameters used when particular lens equipment has specific
    /// unusual parameter.
    float custom2{0.0f};
    /// Lens custom parameter. Value depends on particular lens controller.
    /// Custom parameters used when particular lens equipment has specific
    /// unusual parameter.
    float custom3{0.0f};
    /// List of points to calculate field of view. Lens controller should
    /// calculate FOV table according to given list of points using
    /// approximation.
    std::vector<FovPoint> fovPoints{std::vector<FovPoint>()};

    JSON_READABLE(LensParams, initString, focusMode, filterMode,
                  afRoiX0, afRoiY0, afRoiX1, afRoiY1, zoomHwMaxSpeed,
                  focusHwMaxSpeed, irisHwMaxSpeed, zoomHwTeleLimit,
                  zoomHwWideLimit, focusHwFarLimit, focusHwNearLimit,
                  irisHwOpenLimit, irisHwCloseLimit, afHwSpeed,
                  focusFactorThreshold, refocusTimeoutSec, irisMode,
                  autoAfRoiWidth, autoAfRoiHeight, autoAfRoiBorder,
                  afRoiMode, extenderMode, stabiliserMode, afRange,
                  logMode, type, custom1, custom2, custom3, fovPoints)

    /// Default constructor.
    LensParams() = default;

    /// Copy constructor.
    LensParams(const LensParams& src) = default;

    /// Move constructor.
    LensParams(LensParams&& src) = default;

    /// Copy assignment operator.
    LensParams& operator= (const LensParams& src) = default;

    /// Move assignment operator.
    LensParams& operator= (LensParams&& src) = default;

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

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

Table 4 - LensParams class fields description is equivalent to LensParam enum description.

Field type Description
initString string Initialization string contains full serial port name, baudrate, timeout separated by “;”. Example: “/dev/ttyUSB0;9600;50”. The same string used in openLens(…) method.
zoomPos int Zoom position 0 (full wide) - 65535 (full tele).
zoomHwPos int Hardware zoom position between the wide and tele hardware limits (zoomHwWideLimit - zoomHwTeleLimit).
focusPos int Focus position 0 (full near) - 65535 (full far).
focusHwPos int Hardware focus position between the near and far hardware limits (focusHwNearLimit - focusHwFarLimit).
irisPos int Iris position 0 (full close) - 65535 (full open).
irisHwPos int Hardware iris position between the close and open hardware limits (irisHwCloseLimit - irisHwOpenLimit).
focusMode int Not supported by Klc class.
filterMode int Not supported by Klc class.
afRoiX0 int Not supported by Klc class.
afRoiY0 int Not supported by Klc class.
afRoiX1 int Not supported by Klc class.
afRoiY1 int Not supported by Klc class.
zoomSpeed int Zoom speed 0-100%. Kowa lens doesn’t support direct speed control. Kowa lens has 4 speed slots with predefined speed values: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed. Zoom speed value [0:24] set speed slot 0, [25:49] set speed slot 1, [50:74] set speed slot 2, [75:100] set speed slot 3. After the speed is set the parameter has the upper value of the range of the slot: 25, 50, 75 or 100. Default value 50.
zoomHwSpeed int Zoom speed slot: 0 - slowest speed, 3 - fastest speed. Default value 1.
zoomHwMaxSpeed int Not supported by Klc class.
focusSpeed int Focus speed 0-100%. Kowa lens doesn’t support direct speed control. Kowa lens has 4 speed slots with predefined speed values: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed. Focus speed value [0:24] set speed slot 0, [25:49] set speed slot 1, [50:74] set speed slot 2, [75:100] set speed slot 3. After the speed is set the parameter has the upper value of the range of the slot: 25, 50, 75 or 100. Default value 50.
focusHwSpeed int Focus speed slot: 0 - slowest speed, 3 - fastest speed. Default value 1.
focusHwMaxSpeed int Not supported by Klc class.
irisSpeed int Iris speed 0-100%. Kowa lens doesn’t support direct speed control. Kowa lens has 4 speed slots with predefined speed values: 0 - slowest speed, 1 - low medium speed, 2 - high medium speed, 3 - fastest speed. Iris speed value [0:24] set speed slot 0, [25:49] set speed slot 1, [50:74] set speed slot 2, [75:100] set speed slot 3. After the speed is set the parameter has the upper value of the range of the slot: 25, 50, 75 or 100. Default value 50.
irisHwSpeed int Iris speed slot: 0 - slowest speed, 3 - fastest speed. Default value 1.
irisHwMaxSpeed int Not supported by Klc class.
zoomHwTeleLimit int Zoom hardware tele limit. Default value 64461.
zoomHwWideLimit int Zoom hardware wide limit. Default value 1126.
focusHwFarLimit int Focus hardware far limit. Default value 65535.
focusHwNearLimit int Focus hardware near limit. Default value 0.
irisHwOpenLimit int Iris hardware open limit. Default value 65535.
irisHwCloseLimit int Iris hardware close limit. Default value 0.
focusFactor float Not supported by Klc class.
isConnected bool Lens connection status. Connection status shows if the lens controller has received data from lens equipment. Values:
0 - no data from lens.
1 - connected.
afHwSpeed int Not supported by Klc class.
focusFactorThreshold float Not supported by Klc class.
refocusTimeoutSec int Not supported by Klc class.
afIsActive bool Not supported by Klc class.
irisMode int Not supported by Klc class.
autoAfRoiWidth int Not supported by Klc class.
autoAfRoiHeight int Not supported by Klc class.
autoAfRoiBorder int Not supported by Klc class.
afRoiMode int Not supported by Klc class.
extenderMode int Not supported by Klc class.
stabiliserMode int Not supported by Klc class.
afRange int Not supported by Klc class.
xFovDeg float Not supported by Klc class.
yFovDeg float Not supported by Klc class.
logMode int Logging mode. Values:
0 - Disable.
1 - Only terminal.
2 - Only file.
3 - File and terminal.
temperature float Not supported by Klc class.
isOpen bool Lens controller initialization status. Open status shows if the lens controller initialized or not but doesn’t show if lens controller has communication with lens equipment. Values: 0 - not open (not initialized), 1 - open (initialized).
type int Not supported by Klc class.
custom1 float Not supported by Klc class.
custom2 float Not supported by Klc class.
custom3 float Not supported by Klc class.
fovPoints FovPoint Not supported by Klc class.

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

Serialize lens params

LensParams class provides method encode(…) to serialize lens params. Serialization of lens params necessary in case when you need to send lens params via communication channels. Method doesn’t encode initString string field and fovPoints. Method provides options to exclude particular parameters from serialization. To do this method inserts binary mask (7 bytes) where each bit represents particular parameter and decode(…) method recognizes it. Values of int and float fields are encoded as 4 bytes in the byte order of the host. Method declaration:

bool encode(uint8_t* data, int bufferSize, int& size, LensParamsMask* mask = nullptr);
Parameter Value
data Pointer to data buffer. Must not be nullptr.
bufferSize Data buffer size. Buffer size must be >= 201 bytes.
size Size of encoded data (0 if the params are not encoded).
mask Parameters mask - pointer to LensParamsMask structure. LensParamsMask (declared in Lens.h file) determines flags for each field (parameter) declared in LensParams 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 LensParamsMask structure to FALSE. If the pointer is nullptr all params are encoded.

Returns: TRUE if params encoded or FALSE if not (data is nullptr or bufferSize < 201).

LensParamsMask structure declaration:

typedef struct LensParamsMask
{
    bool zoomPos{true};  ///< Serialize zoomPos.
    bool zoomHwPos{true};  ///< Serialize zoomHwPos.
    bool focusPos{true};  ///< Serialize focusPos.
    bool focusHwPos{true};  ///< Serialize focusHwPos.
    bool irisPos{true};  ///< Serialize irisPos.
    bool irisHwPos{true};  ///< Serialize irisHwPos.
    bool focusMode{true};  ///< Serialize focusMode.
    bool filterMode{true};  ///< Serialize filterMode.
    bool afRoiX0{true};  ///< Serialize afRoiX0.
    bool afRoiY0{true};  ///< Serialize afRoiY0.
    bool afRoiX1{true};  ///< Serialize afRoiX1.
    bool afRoiY1{true};  ///< Serialize afRoiY1.
    bool zoomSpeed{true};  ///< Serialize zoomSpeed.
    bool zoomHwSpeed{true};  ///< Serialize zoomHwSpeed.
    bool zoomHwMaxSpeed{true};  ///< Serialize zoomHwMaxSpeed.
    bool focusSpeed{true};  ///< Serialize focusSpeed.
    bool focusHwSpeed{true};  ///< Serialize focusHwSpeed.
    bool focusHwMaxSpeed{true};  ///< Serialize focusHwMaxSpeed.
    bool irisSpeed{true};  ///< Serialize irisSpeed.
    bool irisHwSpeed{true};  ///< Serialize irisHwSpeed.
    bool irisHwMaxSpeed{true};  ///< Serialize irisHwMaxSpeed.
    bool zoomHwTeleLimit{true};  ///< Serialize zoomHwTeleLimit.
    bool zoomHwWideLimit{true};  ///< Serialize zoomHwWideLimit.
    bool focusHwFarLimit{true};  ///< Serialize focusHwFarLimit.
    bool focusHwNearLimit{true};  ///< Serialize focusHwNearLimit.
    bool irisHwOpenLimit{true};  ///< Serialize irisHwOpenLimit.
    bool irisHwCloseLimit{true};  ///< Serialize irisHwCloseLimit.
    bool focusFactor{true};  ///< Serialize focusFactor.
    bool isConnected{true};  ///< Serialize isConnected.
    bool afHwSpeed{true};  ///< Serialize afHwSpeed.
    bool focusFactorThreshold{true};  ///< Serialize focusFactorThreshold.
    bool refocusTimeoutSec{true};  ///< Serialize refocusTimeoutSec.
    bool afIsActive{true};  ///< Serialize afIsActive.
    bool irisMode{true};  ///< Serialize irisMode.
    bool autoAfRoiWidth{true};  ///< Serialize autoAfRoiWidth.
    bool autoAfRoiHeight{true};  ///< Serialize autoAfRoiHeight.
    bool autoAfRoiBorder{true};  ///< Serialize autoAfRoiBorder.
    bool afRoiMode{true};  ///< Serialize afRoiMode.
    bool extenderMode{true};  ///< Serialize extenderMode.
    bool stabiliserMode{true};  ///< Serialize stabiliserMode.
    bool afRange{true};  ///< Serialize afRange.
    bool xFovDeg{true};  ///< Serialize xFovDeg.
    bool yFovDeg{true};  ///< Serialize yFovDeg.
    bool logMode{true};  ///< Serialize logMode.
    bool temperature{true};  ///< Serialize temperature.
    bool isOpen{true};  ///< Serialize isOpen.
    bool type{true};  ///< Serialize type.
    bool custom1{true};  ///< Serialize custom1.
    bool custom2{true};  ///< Serialize custom2.
    bool custom3{true};  ///< Serialize custom3.
} LensParamsMask;

Example without parameters mask:

// Prepare params.
rapidpixel::LensParams in;
in.logMode = 3;

// Encode all params. The buffer must be >= 201 bytes.
uint8_t data[1024];
int size{0};
if (!in.encode(data, static_cast<int>(sizeof(data)), size))
{
    std::cout << "Can't encode params" << std::endl;
    return false;
}
std::cout << "Encoded data size: " << size << " bytes" << std::endl;

Console output:

Encoded data size: 201 bytes

Example with parameters mask:

// Prepare params.
rapidpixel::LensParams in;
in.logMode = 3;

// Prepare mask: exclude logMode, other params are encoded.
rapidpixel::LensParamsMask mask;
mask.logMode = false;

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

Console output:

Encoded data size: 197 bytes

Deserialize lens params

LensParams class provides method decode(…) to deserialize lens params. Deserialization of lens params necessary in case when you need to receive lens params via communication channels. Method automatically recognizes which parameters were serialized by encode(…) method. Method doesn’t decode fields: initString (it is set to empty string) and fovPoints (it is cleared). The method checks data type, version and params mask, and checks that each encoded value is inside the data. Params which are not encoded are set to 0 (FALSE for bool params). Values of the params are not checked against any range: the lens controller must validate them before use. Method declaration:

bool decode(uint8_t* data, int dataSize);
Parameter Value
data Pointer to data buffer. Must not be nullptr.
dataSize Size of data, bytes.

Returns: TRUE if data decoded (deserialized) or FALSE if not. If FALSE is returned the object is not changed.

Example:

// Encode data.
rapidpixel::LensParams in;
in.logMode = 3;
uint8_t data[1024];
int size{0};
if (!in.encode(data, static_cast<int>(sizeof(data)), size))
{
    std::cout << "Can't encode params" << std::endl;
    return false;
}
std::cout << "Encoded data size: " << size << " bytes" << std::endl;

// Decode data.
rapidpixel::LensParams out;
if (!out.decode(data, size))
{
    std::cout << "Can't decode data" << std::endl;
    return false;
}
std::cout << "Decoded log mode: " << out.logMode << std::endl;

Console output:

Encoded data size: 201 bytes
Decoded log mode: 3

Read and write lens params to JSON file

Lens interface class 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::LensParams in;
in.initString = "/dev/ttyUSB0;19200;100";
in.logMode = 1;
in.zoomHwTeleLimit = 60000;
in.zoomHwWideLimit = 2000;
const float xFov[3]{60.0f, 30.0f, 15.0f};
const float yFov[3]{34.0f, 17.0f, 8.5f};
for (int i = 0; i < 3; ++i)
{
    rapidpixel::FovPoint point;
    point.hwZoomPos = 1000 * (i + 1);
    point.xFovDeg = xFov[i];
    point.yFovDeg = yFov[i];
    in.fovPoints.push_back(point);
}

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

// Read params from file.
rapidpixel::ConfigReader outConfig;
rapidpixel::LensParams out;
if (!outConfig.readFromFile("TestLensParams.json") ||
    !outConfig.get(out, "lensParams"))
{
    std::cout << "Can't read config file" << std::endl;
    return false;
}
std::cout << "Read init string: " << out.initString << ", FOV points: " <<
             out.fovPoints.size() << std::endl;

Console output:

Read init string: /dev/ttyUSB0;19200;100, FOV points: 3

TestLensParams.json will look like:

{
    "lensParams": {
        "initString": "/dev/ttyUSB0;19200;100",
        "focusMode": 0,
        "filterMode": 0,
        "afRoiX0": 0,
        "afRoiY0": 0,
        "afRoiX1": 0,
        "afRoiY1": 0,
        "zoomHwMaxSpeed": 50,
        "focusHwMaxSpeed": 50,
        "irisHwMaxSpeed": 50,
        "zoomHwTeleLimit": 60000,
        "zoomHwWideLimit": 2000,
        "focusHwFarLimit": 65535,
        "focusHwNearLimit": 0,
        "irisHwOpenLimit": 65535,
        "irisHwCloseLimit": 0,
        "afHwSpeed": 50,
        "focusFactorThreshold": 0.0,
        "refocusTimeoutSec": 0,
        "irisMode": 0,
        "autoAfRoiWidth": 150,
        "autoAfRoiHeight": 150,
        "autoAfRoiBorder": 100,
        "afRoiMode": 0,
        "extenderMode": 0,
        "stabiliserMode": 0,
        "afRange": 0,
        "logMode": 1,
        "type": 0,
        "custom1": 0.0,
        "custom2": 0.0,
        "custom3": 0.0,
        "fovPoints": [
            {
                "hwZoomPos": 1000,
                "xFovDeg": 60.0,
                "yFovDeg": 34.0
            },
            {
                "hwZoomPos": 2000,
                "xFovDeg": 30.0,
                "yFovDeg": 17.0
            },
            {
                "hwZoomPos": 3000,
                "xFovDeg": 15.0,
                "yFovDeg": 8.5
            }
        ]
    }
}

Build and connect to your project

Build stand alone

The repository doesn’t contain sub-repositories. The libraries Klc depends on (Frame, ConfigReader, Lens, SerialPort and Logger) must be cloned into the same folder as Klc. The folder structure must be:

<work folder>
    Klc
    Frame
    ConfigReader
    Lens
    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 <Klc repository URL>
git clone <Frame repository URL>
git clone <ConfigReader repository URL>
git clone <Lens repository URL>
git clone <SerialPort repository URL>
git clone <Logger repository URL>
cd Klc
mkdir build
cd build
cmake ..
make

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

The KowaLensParser library is a part of the repository (folder src/parser, see src/parser/README.md) and is not cloned separately: the main CMakeLists.txt file of Klc adds the folder src/parser before the library in every build (stand alone and when Klc is included in another project). The test application of the parser (folder src/parser/test) is not built.

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 Klc is the top-level project).

Option Default Description
${PARENT}_KLC ON Build the library.
${PARENT}_KLC_TEST ON (stand alone), OFF (included in other project) Build the test application.
${PARENT}_KLC_EXAMPLE ON (stand alone), OFF (included in other project) Build the example.
CMAKE_BUILD_TYPE Release (if not specified) Build type.

Connect to your project

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

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

Create folder 3rdparty in your repository and clone (or copy) the repositories of Frame, ConfigReader, Lens, SerialPort, Logger and Klc there. Structure of your repository with the libraries:

CMakeLists.txt
src
    CMakeLists.txt
    yourLib.h
    yourLib.cpp
3rdparty
    Frame
    ConfigReader
    Lens
    SerialPort
    Logger
    Klc

When Klc is included in another project it doesn’t add the other libraries it depends on: your project must add Frame, ConfigReader, Lens, SerialPort and Logger by itself. If they are not added the compiler stops with the error SerialPort.h: No such file or directory. 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_FRAME                           ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_FRAME)
    SET(${PARENT}_FRAME                                 ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_FRAME_TEST                            OFF CACHE BOOL "" FORCE)
endif()

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_LENS                            ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_LENS)
    SET(${PARENT}_LENS                                  ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_LENS_TEST                             OFF CACHE BOOL "" FORCE)
    SET(${PARENT}_LENS_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_KLC                             ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_KLC)
    SET(${PARENT}_KLC                                   ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_KLC_TEST                              OFF CACHE BOOL "" FORCE)
    SET(${PARENT}_KLC_EXAMPLE                           OFF CACHE BOOL "" FORCE)
endif()

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

if (${PARENT}_SUBMODULE_CONFIG_READER)
    add_subdirectory(ConfigReader)
endif()

if (${PARENT}_SUBMODULE_LENS)
    add_subdirectory(Lens)
endif()

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

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

if (${PARENT}_SUBMODULE_KLC)
    add_subdirectory(Klc)
endif()

File 3rdparty/CMakeLists.txt adds folders Frame, ConfigReader, Lens, SerialPort, Logger and Klc (in this order: Klc is added after the libraries it depends on) to your project and excludes test applications and examples from compiling (by default test application and example excluded from compiling if Klc included as sub-repository). Structure of your repository will be:

CMakeLists.txt
src
    CMakeLists.txt
    yourLib.h
    yourLib.cpp
3rdparty
    CMakeLists.txt
    Frame
    ConfigReader
    Lens
    SerialPort
    Logger
    Klc

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

target_link_libraries(${PROJECT_NAME} Klc)

Done!

Simple example

A simple application shows how to use the Klc library. The application opens the lens controller, goes to full tele zoom and shows the zoom position. The source code is in the file example/main.cpp. The serial port name, baudrate and timeout in the init string must be changed according to your equipment.

#include <chrono>
#include <iostream>
#include <thread>
#include "Klc.h"
#include "Lens.h"



/// Number of zoom position reads.
constexpr int POSITION_READS_NUM{50};
/// Pause between zoom position reads, milliseconds.
constexpr int READ_PAUSE_MSEC{100};
/// Zoom position of full tele.
constexpr float FULL_TELE_POSITION{65535.0f};



int main()
{
    // Open lens: serial port name, baudrate and timeout (ms).
    rapidpixel::Klc lens;
    if (!lens.openLens("/dev/ttyUSB0;19200;100"))
    {
        std::cout << "ERROR: Can't open lens controller." << std::endl;
        return 1;
    }

    // Get lens zoom position.
    std::cout << "Zoom pos: " <<
                 lens.getParam(rapidpixel::LensParam::ZOOM_POS) << std::endl;

    // Go to zoom position 65535 (full tele).
    if (!lens.executeCommand(rapidpixel::LensCommand::ZOOM_TO_POS,
                             FULL_TELE_POSITION))
    {
        std::cout << "ERROR: Can't execute command." << std::endl;
        lens.closeLens();
        return 1;
    }

    // Show zoom movement (changing position).
    for (int i = 0; i < POSITION_READS_NUM; ++i)
    {
        std::cout << "Zoom pos: " <<
                     lens.getParam(rapidpixel::LensParam::ZOOM_POS) <<
                     std::endl;
        std::this_thread::sleep_for(std::chrono::milliseconds(READ_PAUSE_MSEC));
    }

    lens.closeLens();
    return 0;
}

Test application

Folder Klc/test contains the test application files. The test application is a terminal application to control the lens: it doesn’t use a video source and doesn’t show any window. The application doesn’t write files by itself (the library writes a log file only if the user selects a file log mode by the LOG_MODE parameter). The application asks the serial port name, baudrate and timeout (an empty answer selects the default value shown in square brackets), opens the lens controller and shows the menu. The menu allows user to set params, get params, execute commands and show all lens params. Serial port name format depends on OS (for example “/dev/ttyUSB0” for Linux). A wrong answer is asked again, the application stops after 5 wrong answers in a row. The application returns exit code 0 after the menu item -1 (exit) and exit code 1 if the lens controller can’t be opened, the input is closed or there are too many wrong answers.

Test application output will look like:

Kowa lens controller test v1.1.0

Enter serial port name [/dev/ttyUSB0]: /dev/ttyUSB1
Enter baudrate [19200]: 19200
Enter timeout, ms [0]: 100
Lens controller is open.

Choose option:
1 - Set lens param
2 - Get lens param
3 - Execute lens command
4 - Show all lens params
-1 - Exit
1
Lens params:
1 - ZOOM_POS
2 - ZOOM_HW_POS
13 - ZOOM_SPEED
3 - FOCUS_POS
4 - FOCUS_HW_POS
16 - FOCUS_SPEED
5 - IRIS_POS
6 - IRIS_HW_POS
19 - IRIS_SPEED
22 - ZOOM_HW_TELE_LIMIT
23 - ZOOM_HW_WIDE_LIMIT
24 - FOCUS_HW_FAR_LIMIT
25 - FOCUS_HW_NEAR_LIMIT
26 - IRIS_HW_OPEN_LIMIT
27 - IRIS_HW_CLOSE_LIMIT
44 - LOG_MODE

Choose param to set (-1 to exit to main menu): 1
Set ZOOM_POS (0 (full wide) - 65535 (full tele)): 30000
OK

Portability

The library uses standard C++17 only (no compiler extensions) and the libraries listed in the Overview. It was built and tested in Release and Debug configurations with: Visual Studio 2022 (MSVC, Windows, x86-64), GCC 12 and 13 (Linux, x86-64), Clang 15 and 18 (Linux, x86-64) and the GCC cross compiler for Linux aarch64 (the tests were run with QEMU). The 16 bit values of the lens protocol are sent with the most significant byte first on all these platforms. The positions which the controller calculates from percent and limits use float arithmetic: on aarch64 the compiler can fuse multiplication and addition, so a calculated position can differ by 1 (of 65535) from the position calculated on x86-64 in about 0.05 % of the values.

Table of contents