Olc C++ library

v3.2.2

Table of contents

• Overview
• Versions
• Library files
• Olc class description
  • Olc class declaration
  • getVersion method
  • openLens method
  • initLens method
  • closeLens method
  • isLensOpen method
  • isLensConnected method
  • setParam method
  • getParam method
  • getParams method
  • executeCommand method
  • addVideoFrame method
  • decodeAndExecuteCommand method
  • encodeSetParamCommand method of Lens class
  • encodeCommand method of Lens class
  • decodeCommand method of Lens class
• Data structures
  • LensCommand enum
  • LensParam enum
• LensParams class description
  • LensParams class declaration
  • Serialize lens params
  • Deserialize lens params
  • Read and write lens params to JSON file
• Build and connect to your project
  • Build stand alone
  • CMake options
  • Connect to your project
• Simple example
• Test application
• Portability

Overview

Olc C++ library is intended to control Ophir® infrared lenses (Ophir® is a registered trademark of MKS Instruments, Inc. or a subsidiary of MKS Instruments Inc). The Olc library inherits Lens interfaces. The library has auto focus functions based on the AFEngine library. It depends on libraries: Lens (provides interface and data structures to control lenses), Logger (provides functions to print logs), SerialPort (provides functions to work with serial ports) and AFEngine (provides auto focus functions). Lens uses the libraries Frame and ConfigReader. The dependencies are separate repositories which are not part of the Olc repository (see Build and connect to your project). The Olc library provides a simple interface to be integrated in any C++ projects. The library repository (folder) is provided by source code and doesn’t have third-party dependencies to be specially installed in the OS. It is developed with C++17 standard and is compatible with Linux and Windows.

Olc 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	21.10.2022	First version
2.0.0	10.01.2023	- Control algorithm was rebuilt. - Lens interface updated.
3.0.0	27.03.2023	- Lens interface updated. - Auto detection of zoom and focus hardware range added. - Added logging to file function. (Logger C++ library used).
3.0.1	21.02.2024	- Autofocus algorithm updated. - Documentation updated.
3.0.2	29.02.2024	- Submodules updated. - Documentation updated.
3.0.3	23.08.2024	- Submodules updated. - Documentation updated.
3.0.4	18.09.2024	- AFEngine update.
3.0.5	12.12.2024	- Fix test application.
3.0.6	17.03.2025	- AFEngine noise reduction switched on by default.
3.0.7	03.04.2025	- Logger submodule update.
3.0.8	07.05.2025	- Update parameters for AFEngine. Fixed bugs in AF procedure.
3.0.9	14.05.2025	- AFEngine submodule update.
3.0.10	26.10.2025	- SerialPort submodule update.
3.0.11	28.03.2026	- AFEngine submodule update.
3.1.0	24.06.2026	- AFEngine 3.0.0 adoption. The new band-pass (difference-of-box) focus-factor metric replaces both the previous L1 / Tenengrad measures and the dedicated denoiser: the inner-box convolution now suppresses high-frequency sensor noise inside the focus-factor measure itself, so the AFEngine-side NOISE_REDUCTION_MODE / NOISE_REDUCTION_LEVEL parameters and the FF_DECREASE_THRESHOLD knob are removed from the engine. Removed the corresponding setParam(NOISE_REDUCTION_MODE/LEVEL, …) and setParam(FF_DECREASE_THRESHOLD, 90) calls from the Olc constructor and from the FILTER_MODE case of setParam(). The FILTER_MODE parameter itself is kept (round-trip cache, see table below).
3.2.0	30.06.2026	- Critical bugs fixed. - Updated AFEngine submodule.
3.2.1	13.07.2026	- Updated AFEngine submodule.
3.2.2	17.10.2026	- Git submodules removed: the repository does not contain sub-repositories, the dependencies are expected in sibling folders. - Fixed a deadlock between the setParam(…) / executeCommand(…) methods and the communication thread, removed data races on the lens params. - NaN and out of range values are rejected, a zero maximum speed and equal hardware limits are handled without undefined behavior, the baudrate of the init string must be greater than 0. - Protocol parser: explicit byte order of 16-bit values, checks of pointers and sizes. - Test application rewritten: console control of the lens params only. - Example fixed (init string, error handling). - Compiler and linker hardening options added, compiler warnings removed.

Library files

The library is supplied by source code only. The user is 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.
    Olc.h -------------------------- Main library header file.
    Olc.cpp ------------------------ C++ implementation file.
    OphirUserProtocolU1Parser.h ---- Header file of protocol parser.
    OphirUserProtocolU1Parser.cpp -- C++ implementation file.
    OlcVersion.h ------------------- Header file with library version.
    OlcVersion.h.in ---------------- CMake file to generate version header.
test ------------------------------- Folder with console test application files.
    CMakeLists.txt ----------------- CMake file for test application.
    main.cpp ----------------------- Source C++ file of test application.
example ---------------------------- Folder with simple example files.
    CMakeLists.txt ----------------- CMake file for simple example.
    main.cpp ----------------------- Source C++ file of simple example.
static ----------------------------- Folder with the logo image of this document.

Olc class description

Olc class declaration

Olc.h file contains Olc class declaration:

namespace rapidpixel
{
class Olc : public Lens
{
public:

    /// Class constructor.
    Olc();

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

    /// Copy and move are deleted: the object owns a thread and a serial port.
    Olc(const Olc&) = delete;
    Olc(Olc&&) = delete;
    Olc& operator=(const Olc&) = delete;
    Olc& operator=(Olc&&) = delete;

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

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

    /// Init lens controller by params class.
    bool initLens(LensParams& params) override;

    /// Close serial port and stop communication thread.
    void closeLens() override;

    /// Get serial port open status.
    bool isLensOpen() override;

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

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

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

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

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

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

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

getVersion method

The getVersion() method returns a string of the current version of Olc class. Method declaration:

static std::string getVersion();

Method can be used without Olc class instance. Example:

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

Console output:

Olc version: 3.2.2

openLens method

The openLens(…) opens the serial port to communicate with Ophir lenses. If the lens is already open, the communication thread is stopped, the serial port is closed and opened again. After the successful opening, the library runs the communication thread (thread to communicate with equipment via serial port): it sends the command message to the lens about every 10 ms and processes the report messages of the lens. The lens params which were set before keep their values. The serial port is opened with 8 data bits, no parity and 1 stop bit, and it is read without waiting for data. Method declaration:

bool openLens(std::string initString) override;

Parameter

Value

initString

Initialization string contains the full serial port name, baud rate, timeout separated by “;”. Empty parts are skipped, exactly 3 parts must remain. The baud rate must be an integer greater than 0, the timeout must be an integer. The timeout is only checked: it is not used because the serial port is read without waiting. Example: “/dev/ttyUSB0;57600;20”. Default baud rate for Ophir lenses is 57600.

Returns: TRUE if the lens controller is initialized or FALSE if not (invalid initialization string or the serial port can’t be opened). If FALSE is returned for an invalid initialization string, the state of the lens is not changed; if the serial port can’t be opened, the lens is closed.

initLens method

The initLens(…) initializes the lens controller and sets lens params (Lens interface). The method will set the given lens params and then will call the openLens(…) method. A param with a value out of its valid range is not set (the previous value stays) and does not stop the initialization. After successful initialization, the library runs the communication thread (thread to communicate with equipment via serial port). Method declaration:

bool initLens(LensParams& params) override;

Parameter	Value
params	LensParams parameters class. LensParams class includes initString which is used in openLens(…) method. See description of LensParams class.

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

closeLens method

The closeLens() closes the serial port and stops the communication thread. The method does nothing if the lens is not open. The methods openLens(…), initLens(…) and closeLens() are serialized by an internal mutex, so they can be called from any thread. Method declaration:

void closeLens() override;

isLensOpen method

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

bool isLensOpen() override;

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

isLensConnected method

The isLensConnected() shows if the lens controller receives responses from equipment. For example, if the serial port is open but equipment is not active (no power). In this case, the isLensOpen(…) method 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 (data was received from the lens during the last 20 periods of the communication thread, about 200 ms) or FALSE if not.

setParam method

The setParam(…) method sets a new lens parameter value. Olc provides thread-safe setParam(…) method call. This means that the setParam(…) method can be safely called from any thread. 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). A NaN value is not valid for any parameter.

Returns: TRUE if the parameter was set or FALSE if not (the value is out of the valid range, the parameter is read only or is not supported by Olc). The parameter is not changed if FALSE is returned.

getParam method

The getParam(…) method returns the lens parameter value. Olc 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).

getParams method

The getParams(…) method returns the lens parameters class. Olc 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 executes a lens action command. Olc provides thread-safe executeCommand(…) method call. This means that the executeCommand(…) method can be safely called from any thread. 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 if the command was executed (accepted by lens controller) or FALSE if not (the command is not supported by Olc or the argument is not valid: a position of ZOOM_TO_POS and FOCUS_TO_POS must be in the range 0 - 65535, a NaN value is not valid). The command RESTART blocks the calling thread for 200 ms.

addVideoFrame method

The addVideoFrame(…) method passes the video frame to the lens controller to perform autofocus algorithm. To perform autofocus, the lens controller calculates focus factor in autofocus ROI (focus factor can be obtained with the getParam(…) method and parameter FOCUS_FACTOR). To calculate focus factor, Olc needs video frame, so to use auto focus functions, the method addVideoFrame(…) must be called for each captured video frame. If the autofocus ROI is in the manual mode and is not set (all coordinates are 0), the ROI is set in the center of the frame: its size is CUSTOM_1 percent of the frame size. The method must not be called from several threads at the same time. 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 a command on the controller side. The method will decode commands which are encoded by encodeCommand(…) and encodeSetParamCommand(…) methods of Lens interface classes. If the command is 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 and must be valid for size bytes. 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 the command is decoded (SET_PARAM or COMMAND) and executed (action command or set param command) or FALSE if not (the data is nullptr, is not a valid command or the execution failed, see setParam(…) and executeCommand(…)).

encodeSetParamCommand method of Lens class

The encodeSetParamCommand(…) static method of Lens interface class is designed to encode a 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(…) is 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 have size >= 11.
size	Size of encoded data: 11 bytes, or 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;
// Parameter value.
const float outValue = 12.0f;
// Encode command.
rapidpixel::Lens::encodeSetParamCommand(
        data, size, rapidpixel::LensParam::AF_ROI_X0, outValue);

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 have size >= 11.
size	Size of encoded data: 11 bytes, or 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;
// Command argument value.
const float outValue = 12.0f;
// Encode command.
rapidpixel::Lens::encodeCommand(
        data, size, rapidpixel::LensCommand::ZOOM_TO_POS, outValue);

decodeCommand method of Lens class

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 and must be valid for size bytes.
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).

Returns: 0 - in case decoding COMMAND, 1 - in case decoding SET_PARAM command or -1 in case errors (nullptr, wrong size, version or command type, ID outside the range of the enum). The output arguments paramId, commandId and value are changed only if the method returns 0 or 1. The value is not checked against any range: the lens controller validates it.

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 speed can be set by setParam(…) method.
ZOOM_WIDE	Move zoom wide (out). Command doesn’t have arguments. Zoom speed can be set by setParam(…) method.
ZOOM_TO_POS	Move zoom to position. Command argument: zoom position 0 (full wide) - 65535 (full tele). Zoom speed can be set by setParam(…) method.
ZOOM_STOP	Stop zoom moving including stop zoom to position command. Command doesn’t have arguments.
FOCUS_FAR	Move focus far. Command doesn’t have arguments. Focus speed can be set by setParam(…) method.
FOCUS_NEAR	Move focus near. Command doesn’t have arguments. Focus speed can be set by setParam(…) method.
FOCUS_TO_POS	Move focus to position. Command argument: focus position 0 (full near) - 65535 (full far). Focus speed can be set by setParam(…) method.
FOCUS_STOP	Stop focus moving including stop focus to position command. Command doesn’t have arguments.
IRIS_OPEN	Not supported by Olc class.
IRIS_CLOSE	Not supported by Olc class.
IRIS_TO_POS	Not supported by Olc class.
IRIS_STOP	Not supported by Olc class.
AF_START	Start autofocus. Command doesn’t have arguments.
AF_STOP	Stop autofocus. Command doesn’t have arguments.
RESTART	Restart lens controller. Command doesn’t have arguments.
DETECT_HW_RANGES	Detect zoom and focus hardware ranges. Command doesn’t have arguments.

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). Zoom speed can be set by setParam(…) method. 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 = 0, ZOOM_HW_TELE_LIMIT = 65535. Zoom speed can be set by setParam(…) method. 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). Focus speed can be set by setParam(…) method. 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_FAR_LIMIT - FOCUS_HW_NEAR_LIMIT. By default FOCUS_HW_FAR_LIMIT = -32764, FOCUS_HW_NEAR_LIMIT = 32764. Focus speed can be set by setParam(…) method. It doesn’t change the focus position value immediately. The focus position changes only when the lens moves.
IRIS_POS	read / write	Not supported by Olc class.
IRIS_HW_POS	read / write	Not supported by Olc class.
FOCUS_MODE	read / write	Focus mode: 0 - Manual focus control. 1 - Push auto focus mode. 2 - Continuous auto focus mode.
FILTER_MODE	read / write	Filter mode. Value: 0 - 100. The value is validated, stored and returned by getParam(…). It is not passed to the autofocus engine and does not affect autofocus.
AF_ROI_X0	read / write	Autofocus ROI top-left corner horizontal position in pixels. Autofocus ROI is rectangle. Value: 0 - 8192.
AF_ROI_Y0	read / write	Autofocus ROI top-left corner vertical position in pixels. Autofocus ROI is rectangle. Value: 0 - 8192.
AF_ROI_X1	read / write	Autofocus ROI bottom-right corner horizontal position in pixels. Autofocus ROI is rectangle. Value: 0 - 8192.
AF_ROI_Y1	read / write	Autofocus ROI bottom-right corner vertical position in pixels. Autofocus ROI is rectangle. Value: 0 - 8192.
ZOOM_SPEED	read / write	Zoom speed. Zoom speed range from 0 to 100 which means 0 -100% of max hardware zoom speed. If the user sets a new parameter value of the ZOOM_HW_SPEED the parameter ZOOM_SPEED updated automatically.
ZOOM_HW_SPEED	read / write	Zoom hardware speed. Zoom hardware speed range from 0 to ZOOM_HW_MAX_SPEED (255 by default). If the user sets a new parameter value of the ZOOM_SPEED parameter the parameter ZOOM_HW_SPEED updated automatically.
ZOOM_HW_MAX_SPEED	read / write	Maximum zoom hardware speed. Value: 0 - 255. Default value 255. If the user sets a new parameter value of the ZOOM_HW_MAX_SPEED parameter the parameters ZOOM_HW_SPEED and ZOOM_SPEED updated automatically. If the maximum speed is 0 the speed in percents is 0.
FOCUS_SPEED	read / write	Focus speed. Focus speed range from 0 to 100 which means 0 -100% of max hardware focus speed. If the user sets a new parameter value of the FOCUS_HW_SPEED the parameter FOCUS_SPEED updated automatically.
FOCUS_HW_SPEED	read / write	Focus hardware speed. Focus hardware speed range from 0 to FOCUS_HW_MAX_SPEED (255 by default). If the user sets a new parameter value of the FOCUS_SPEED parameter the parameter FOCUS_HW_SPEED updated automatically.
FOCUS_HW_MAX_SPEED	read / write	Maximum focus hardware speed. Value: 0 - 255. Default value 255. If the user sets a new parameter value of the FOCUS_HW_MAX_SPEED parameter the parameters FOCUS_HW_SPEED and FOCUS_SPEED updated automatically. If the maximum speed is 0 the speed in percents is 0.
IRIS_SPEED	read / write	Not supported by Olc class.
IRIS_HW_SPEED	read / write	Not supported by Olc class.
IRIS_HW_MAX_SPEED	read / write	Not supported by Olc class.
ZOOM_HW_TELE_LIMIT	read / write	Zoom hardware tele limit. Value: 0 - 65535. Default value 65535.
ZOOM_HW_WIDE_LIMIT	read / write	Zoom hardware wide limit. Value: 0 - 65535. Default value 0.
FOCUS_HW_FAR_LIMIT	read / write	Focus hardware far limit. Value: -32765 - 32765. Default value -32764.
FOCUS_HW_NEAR_LIMIT	read / write	Focus hardware near limit. Value: -32765 - 32765. Default value 32764.
IRIS_HW_OPEN_LIMIT	read / write	Not supported by Olc class.
IRIS_HW_CLOSE_LIMIT	read / write	Not supported by Olc class.
FOCUS_FACTOR	read only	Focus factor if it was calculated, otherwise -1.
IS_CONNECTED	read only	Lens connection status. Connection status shows if the lens controller has data exchange with lens equipment. Values: 0 - no response from lens. 1 - connected.
FOCUS_HW_AF_SPEED	read / write	Focus hardware speed in autofocus mode. Value: 0 - 255. Default value 50.
FOCUS_FACTOR_THRESHOLD	read / write	Threshold for changes of focus factor to start refocus. Values: 0% - no check, 100% - changing x2.
REFOCUS_TIMEOUT_SEC	read / write	Timeout for automatic refocus in seconds. Value: 0 - no automatic refocus, 100000 - maximum value.
AF_IS_ACTIVE	read only	Flag about active autofocus algorithm. Value: 0 - autofocus not working, 1 - working.
IRIS_MODE	read / write	Not supported by Olc class.
AUTO_AF_ROI_WIDTH	read / write	ROI width (pixels) for autofocus algorithm when lens controller detects ROI position automatically. Value: 1 - 8191. Default value 100.
AUTO_AF_ROI_HEIGHT	read / write	ROI height (pixels) for autofocus algorithm when lens controller detects ROI position automatically. Value: 1 - 8191. Default value 100.
AUTO_AF_ROI_BORDER	read / write	Video frame border size (along vertical and horizontal axes) in pixels. Value: 1 - 8191. Default value 100.
AF_ROI_MODE	read / write	Auto focus ROI mode. Values: 0 - Manual position. 1 - Auto position. The controller will detect “optimal” auto focus ROI position.
EXTENDER_MODE	read / write	Not supported by Olc class.
STABILIZER_MODE	read / write	Not supported by Olc class.
AF_RANGE	read / write	Not supported by Olc class.
X_FOV_DEG	read / write	Not supported by Olc class.
Y_FOV_DEG	read / write	Not supported by Olc class.
LOG_MODE	read / write	Logging mode. Values: 0 - Disable. 1 - Only file. 2 - Only terminal. 3 - File and terminal.
TEMPERATURE	read only	Not supported by Olc 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 Olc class.
CUSTOM_1	read / write	Size of the autofocus ROI in the center of the frame, percents of the frame size. Value: 1 - 100. Default value 0.
CUSTOM_2	read / write	Time adjustment for AF Engine, ms. Value: -500 - 500. Default value 0.
CUSTOM_3	read / write	Not supported by Olc 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:

/**
 * @brief Field of view point class.
 *
 * @note The class is not thread-safe: an object must not be accessed from
 * several threads at the same time without external synchronization.
 */
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)

    /**
     * @brief Default constructor.
     */
    FovPoint() = default;

    /**
     * @brief Copy constructor.
     * @param src Source object.
     */
    FovPoint(const FovPoint& src) = default;

    /**
     * @brief Move constructor.
     * @param src Source object.
     */
    FovPoint(FovPoint&& src) = default;

    /**
     * @brief Copy assignment operator.
     * @param src Source object.
     * @return Reference to this object.
     */
    FovPoint& operator= (const FovPoint& src) = default;

    /**
     * @brief Move assignment operator.
     * @param src Source object.
     * @return Reference to this object.
     */
    FovPoint& operator= (FovPoint&& src) = default;
};

/**
 * @brief Lens params class.
 *
 * @note The class is not thread-safe: an object must not be accessed from
 * several threads at the same time without external synchronization.
 */
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)

    /**
     * @brief Default constructor.
     */
    LensParams() = default;

    /**
     * @brief Copy constructor.
     * @param src Source object.
     */
    LensParams(const LensParams& src) = default;

    /**
     * @brief Move constructor.
     * @param src Source object.
     */
    LensParams(LensParams&& src) = default;

    /**
     * @brief Copy assignment operator.
     * @param src Source object.
     * @return Reference to this object.
     */
    LensParams& operator= (const LensParams& src) = default;

    /**
     * @brief Move assignment operator.
     * @param src Source object.
     * @return Reference to this object.
     */
    LensParams& operator= (LensParams&& src) = default;

    /**
     * @brief Encode (serialize) params.
     *
     * The method doesn't encode initString and fovPoints. The encoded data
     * consists of the header (data type, version Major and Minor, params mask
     * of 7 bytes: one bit for each field of LensParamsMask) and the values of
     * the selected params in the order of the LensParamsMask fields. Values of
     * int and float fields use 4 bytes in the byte order of the host, values
     * of bool fields use 1 byte.
     *
     * @param data Pointer to data buffer. Must not be nullptr and must be
     * valid for bufferSize bytes.
     * @param bufferSize Size of the data buffer, bytes. Must be >= 201 (the
     * size of the data with all params encoded).
     * @param size Size of the encoded data, bytes. Set to 0 if the params
     * are not encoded.
     * @param mask Pointer to params mask. If nullptr all params are encoded.
     * @return TRUE if params encoded or FALSE if not (data is nullptr or
     * bufferSize < 201).
     */
    bool encode(uint8_t* data, int bufferSize, int& size,
                LensParamsMask* mask = nullptr);

    /**
     * @brief Decode (deserialize) params encoded by encode(...) method.
     *
     * The method doesn't decode initString and fovPoints: initString is set
     * to empty string and fovPoints is cleared. The method checks data type,
     * version (Major and Minor) and params mask, and checks that each encoded
     * value is inside the data before reading it. Params which are not
     * encoded are set to 0 (FALSE for bool params). Bytes after the last
     * encoded value are ignored. Values of params are not checked against any
     * range: the lens controller must validate them before use.
     *
     * @param data Pointer to encoded data. Must not be nullptr and must be
     * valid for dataSize bytes.
     * @param dataSize Size of the encoded data, bytes.
     * @return TRUE if params decoded or FALSE if not. If FALSE is returned
     * the object is not changed.
     */
    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”.
zoomPos	int	Zoom position 0 (full wide) - 65535 (full tele).
zoomHwPos	int	Hardware zoom position 0 (full wide) - 65535 (full tele) by default.
focusPos	int	Focus position 0 (full near) - 65535 (full far).
focusHwPos	int	Hardware focus position -32765 (full near) - 32765 (full far) by default.
irisPos	int	Not supported by Olc class.
irisHwPos	int	Not supported by Olc class.
focusMode	int	Focus mode: 0 - Manual focus control. 1 - Push auto focus mode. 2 - Continuous auto focus mode.
filterMode	int	Filter mode. Value: 0 - 100. The value is stored only: it does not affect autofocus (see the FILTER_MODE row of Table 3).
afRoiX0	int	Autofocus ROI top-left corner horizontal position in pixels. Autofocus ROI is rectangle.
afRoiY0	int	Autofocus ROI top-left corner vertical position in pixels. Autofocus ROI is rectangle.
afRoiX1	int	Autofocus ROI bottom-right corner horizontal position in pixels. Autofocus ROI is rectangle.
afRoiY1	int	Autofocus ROI bottom-right corner vertical position in pixels. Autofocus ROI is rectangle.
zoomSpeed	int	Zoom speed. Zoom speed range from 0 to 100 which means 0-100% of max hardware zoom speed.
zoomHwSpeed	int	Zoom hardware speed. Zoom hardware speed range from 0 to 255.
zoomHwMaxSpeed	int	Maximum zoom hardware speed. Value: 0 - 255. Default value 255.
focusSpeed	int	Focus speed. Focus speed range from 0 to 100 which means 0-100% of max hardware focus speed.
focusHwSpeed	int	Focus hardware speed. Focus hardware speed range from 0 to 255.
focusHwMaxSpeed	int	Maximum focus hardware speed. Value: 0 - 255. Default value 255.
irisSpeed	int	Not supported by Olc class.
irisHwSpeed	int	Not supported by Olc class.
irisHwMaxSpeed	int	Not supported by Olc class.
zoomHwTeleLimit	int	Zoom hardware tele limit. Default value 65535.
zoomHwWideLimit	int	Zoom hardware wide limit. Default value 0.
focusHwFarLimit	int	Focus hardware far limit. Default value -32764.
focusHwNearLimit	int	Focus hardware near limit. Default value 32764.
irisHwOpenLimit	int	Not supported by Olc class.
irisHwCloseLimit	int	Not supported by Olc class.
focusFactor	float	Focus factor if it was calculated. If not calculated must be -1.
isConnected	bool	Lens connection status. Connection status shows if the lens controller has data exchange with lens equipment. Values: 0 - no response from lens. 1 - connected.
afHwSpeed	int	Focus hardware speed in autofocus mode. Value: 0 - 255.
focusFactorThreshold	float	Threshold for changes of focus factor to start refocus. Values: 0% - no check, 100% - changing x2.
refocusTimeoutSec	int	Timeout for automatic refocus in seconds. Value: 0 - no automatic refocus, 100000 - maximum value
afIsActive	bool	Flag about active autofocus algorithm. Value: 0 - autofocus not working, 1 - working.
irisMode	int	Not supported by Olc class.
autoAfRoiWidth	int	ROI width (pixels) for autofocus algorithm when lens controller detects ROI position automatically. Value: 1 - 8191.
autoAfRoiHeight	int	ROI height (pixels) for autofocus algorithm when lens controller detects ROI position automatically. Value: 1 - 8191.
autoAfRoiBorder	int	Video frame border size (along vertical and horizontal axes) in pixels. Value: 1 - 8191.
afRoiMode	int	Auto focus ROI mode. Values: 0 - Manual position. 1 - Auto position. The controller will detect “optimal” auto focus ROI position.
extenderMode	int	Not supported by Olc class.
stabiliserMode	int	Not supported by Olc class.
afRange	int	Not supported by Olc class.
xFovDeg	float	Not supported by Olc class.
yFovDeg	float	Not supported by Olc class.
logMode	int	Logging mode. Values: 0 - Disable. 1 - Only file. 2 - Only terminal. 3 - File and terminal.
temperature	float	Not supported by Olc 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 Olc class.
custom1	float	Size of the autofocus ROI in the center of the frame, percents of the frame size. Value: 1 - 100. Default value 0.
custom2	float	Time adjustment for AF Engine, ms. Value: -500 - 500.
custom3	float	Not supported by Olc class.
fovPoints	FovPoint	List of points to calculate field of view. Lens controller should calculate FOV table according to given list of points using approximation. Each point includes (FovPoint class): - hwZoomPos - hardware zoom position. - xFovDeg - horizontal FOV, degree for hwZoomPos. - yFovDeg - vertical FOV, degree for hwZoomPos.

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

Serialize lens params

The 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. Method declaration:

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

Parameter	Value
data	Pointer to data buffer.
size	Size of encoded data.
bufferSize	Data buffer size. Buffer size must be >= 201 bytes.
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.

LensParamsMask structure declaration:

/**
 * @brief Lens params mask structure.
 *
 * Each flag enables serialization of the LensParams field with the same
 * name (see LensParams::encode(...)).
 */
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:

// Encode data.
rapidpixel::LensParams in;
in.logMode = 3;
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::LensParams in;
in.logMode = 3;

// Prepare mask.
rapidpixel::LensParamsMask mask;
mask.logMode = false; // Exclude logMode. 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 lens params

The 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 and fovPoints. Method declaration:

bool decode(uint8_t* data, int dataSize);

Parameter	Value
data	Pointer to data buffer.
dataSize	Size of data.

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

Example:

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

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.logMode = 2;
for (int i = 0; i < 2; ++i)
{
    rapidpixel::FovPoint pt;
    pt.hwZoomPos = 1000 * (i + 1);
    pt.xFovDeg = 20.0f / static_cast<float>(i + 1);
    pt.yFovDeg = 15.0f / static_cast<float>(i + 1);
    in.fovPoints.push_back(pt);
}

// 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;
}

// 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;
}

TestLensParams.json will look like:

{
    "lensParams": {
        "initString": "/dev/ttyUSB0;9600;20",
        "focusMode": 0,
        "filterMode": 0,
        "afRoiX0": 0,
        "afRoiY0": 0,
        "afRoiX1": 0,
        "afRoiY1": 0,
        "zoomHwMaxSpeed": 50,
        "focusHwMaxSpeed": 50,
        "irisHwMaxSpeed": 50,
        "zoomHwTeleLimit": 65535,
        "zoomHwWideLimit": 0,
        "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": 2,
        "type": 0,
        "custom1": 0.0,
        "custom2": 0.0,
        "custom3": 0.0,
        "fovPoints": [
            {
                "hwZoomPos": 1000,
                "xFovDeg": 20.0,
                "yFovDeg": 15.0
            },
            {
                "hwZoomPos": 2000,
                "xFovDeg": 10.0,
                "yFovDeg": 7.5
            }
        ]
    }
}

Build and connect to your project

Build stand alone

The repository does not contain sub-repositories. The libraries Olc depends on must be cloned into the same folder as Olc: Frame and ConfigReader (they are used by Lens), Lens, SerialPort, Logger and AFEngine. The folder structure must be:

<work folder>
    Olc
    Frame
    ConfigReader
    Lens
    SerialPort
    Logger
    AFEngine

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

git clone <Olc 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>
git clone <AFEngine repository URL>
cd Olc
mkdir build
cd build
cmake ..
make

On Windows use cmake --build . --config Release instead of make. If Olc is the top-level CMake project, the main CMakeLists.txt file adds the folders ../Frame, ../ConfigReader, ../Lens, ../SerialPort, ../Logger and ../AFEngine (in this order) before the library itself. If a folder does not exist CMake stops with an error. The test application OlcTest and the example OlcExample are placed in the folder build/bin.

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

Option	Default	Description
${PARENT}_OLC	ON	Build the library.
${PARENT}_OLC_TEST	ON (stand alone), OFF (included in other project)	Build the test application.
${PARENT}_OLC_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 Olc as a sub-repository.
CMAKE_BUILD_TYPE	Release (if not specified)	Build type.

Connect to your project

If you want to connect the Olc library to your CMake project as source code, add the repositories of Olc and of all its dependencies (Frame, ConfigReader, Lens, SerialPort, Logger and AFEngine) as sub-repositories of your repository. 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 repositories there. New structure of your repository:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    Frame
    ConfigReader
    Lens
    SerialPort
    Logger
    AFEngine
    Olc

Create CMakeLists.txt file in 3rdparty folder. The libraries must be added in the order of their dependencies: Frame and ConfigReader first, then Lens, SerialPort, Logger, AFEngine and Olc itself. CMakeLists.txt should be containing:

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_AF_ENGINE                       ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_AF_ENGINE)
    SET(${PARENT}_AF_ENGINE                             ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_AF_ENGINE_TEST                        OFF CACHE BOOL "" FORCE)
endif()

SET(${PARENT}_SUBMODULE_OLC                             ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_OLC)
    SET(${PARENT}_OLC                                   ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_OLC_TEST                              OFF CACHE BOOL "" FORCE)
    SET(${PARENT}_OLC_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_AF_ENGINE)
    add_subdirectory(AFEngine)
endif()

if (${PARENT}_SUBMODULE_OLC)
    add_subdirectory(Olc)
endif()

File 3rdparty/CMakeLists.txt adds the folders of the libraries and of Olc to your project and excludes test applications and examples from compiling. When Olc is included in another project it does not add its dependencies: the project has to add them, as the file above does. If a dependency is missing the build stops with a compile error (for example, Lens.h: No such file or directory). The new structure of your repository will be:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    CMakeLists.txt
    Frame
    ConfigReader
    Lens
    SerialPort
    Logger
    AFEngine
    Olc

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

add_subdirectory(3rdparty)

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

target_link_libraries(${PROJECT_NAME} Olc)

Done!

Simple example

A simple application shows how to use the Olc library.

#include <chrono>
#include <iostream>
#include <memory>
#include <thread>
#include "Olc.h"

int main()
{
    // Init lens controller.
    std::unique_ptr<rapidpixel::Lens> lens = std::make_unique<rapidpixel::Olc>();
    if (!lens->openLens("/dev/ttyUSB0;57600;50"))
    {
        std::cout << "Can't open the lens controller" << std::endl;
        return 1;
    }

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

    // Set Zoom speed to 10%.
    if (!lens->setParam(rapidpixel::LensParam::ZOOM_SPEED, 10.0f))
    {
        std::cout << "Can't set zoom speed" << std::endl;
        return 1;
    }

    // Go to zoom position 65535 (Full tele).
    if (!lens->executeCommand(rapidpixel::LensCommand::ZOOM_TO_POS, 65535.0f))
    {
        std::cout << "Can't execute the command" << std::endl;
        return 1;
    }

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

    lens->closeLens();

    return 0;
}

Test application

Olc/test folder contains a console test application OlcTest which allows to control a lens through the Olc library from a terminal. The application has no graphical interface and does not use video: it opens the serial port of the lens and executes the commands which are typed in the terminal until the command exit is typed or the input ends. Usage:

OlcTest [<serial port> [<baudrate>]]

If the serial port name or the baudrate are not set in the command line, the application asks for them (default values: /dev/ttyUSB0 (COM1 on Windows) and 57600). The application returns 0 after a normal exit and 1 if the arguments are not valid or the serial port can’t be opened. After the port is open, the library prints its messages to the terminal (LOG_MODE = 2).

Table 6 - Terminal commands of the test application.

Command	Description
help	Print the list of the terminal commands.
params	List the lens params supported by Olc with their IDs, access and valid values.
commands	List the lens commands supported by Olc.
set <param> <value>	Set a lens param (setParam(…) method). The param is set by name (case insensitive) or by ID, for example set ZOOM_SPEED 50. A value which is not a finite number is rejected by the application, a value out of the valid range is rejected by the library.
get <param>	Print a lens param value (getParam(…) method). The param is set by name or by ID, get all prints all params.
exec <command> [<value>]	Execute a lens command (executeCommand(…) method), for example exec ZOOM_TO_POS 30000.
state	Print the main values of the lens params (getParams(…) method).
exit	Close the lens and exit.

Example of a terminal session:

olc> set ZOOM_SPEED 100
olc> exec ZOOM_TO_POS 30000
[Olc.cpp][1749]: Manual zoom to position command
olc> get ZOOM_POS
ZOOM_POS                30000
olc> set ZOOM_POS 70000
[Olc.cpp][532] ERROR: Zoom position 70000 out of valid range
Can't set param: the value is out of the valid range (zoom position, 0 (wide) - 65535 (tele))
olc> exit

Portability

The library is developed with the C++17 standard and does not contain processor specific code (no SIMD). 16-bit values of the Ophir User Protocol U1 (zoom and focus positions) are written and read byte by byte, least significant byte first, so the protocol data does not depend on the byte order of the host. The code of the repository (the library, the test application and the example) compiles without warnings with MSVC 2022 (x64), GCC 12 and 13, Clang 15 and 18 (x86-64 Linux) and GCC 13 (AArch64 Linux, cross build). The command messages sent to the lens and the processing of the lens reports are identical on x86-64 and AArch64.

---

Table of contents