Ylc C++ library

v4.2.2

Table of contents

• Overview
• Versions
• Library files
• Ylc class description
  • Ylc 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
• Portability
• Simple example
• Test application

Overview

The Ylc C++ library is a software controller for Yamano lenses VS Technology lenses. These lenses provide a control interface over serial port. The Ylc library inherits the Lens interface. It depends on the following 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 the autofocus algorithm). The libraries are separate repositories, see Build stand alone. The Ylc library provides a simple interface to be integrated into any C++ projects. The library repository (folder) is provided by source code and doesn’t have third-party dependencies that need to be specially installed in the OS. It is developed with the C++17 standard and is compatible with Linux and Windows.

Ylc 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.
2.0.0	30.03.2024	- Add Logger.
3.0.0	16.05.2023	- Lens interface updated. - Submodules updated.
4.0.0	13.02.2024	- Lens interface updated. - Submodules updated. - Documentation updated.
4.0.1	30.04.2024	- Code reviewed. - Documentation updated.
4.0.2	23.04.2024	- Submodules updated. - Documentation updated.
4.0.3	08.08.2024	- CMake structure updated.
4.0.4	29.09.2024	- Fix optical extender control.
4.0.5	03.02.2025	- Add auto detection zoom/focus hardware ranges.
4.0.6	10.02.2025	- Update auto detection zoom/focus hardware ranges.
4.0.7	03.04.2025	- Logger submodule update.
4.1.0	14.05.2025	- Implement AFEngine.
4.1.1	14.05.2025	- Adjust AF engine parameters.
4.1.2	26.10.2025	- SerialPort submodule update. - Fix code mistakes.
4.1.3	28.03.2026	- AFEngine submodule updated.
4.2.0	01.07.2026	- AFEngine submodule updated. - Critical bugs fixed.
4.2.1	13.07.2026	- Updated AFEngine submodule.
4.2.2	17.10.2026	- Git submodules removed: the libraries which Ylc depends on are placed next to the Ylc folder. - Code reviewed: conversions of float values, limits of loops and thread safety of the open/close methods fixed, methods don’t throw exceptions. - Compiler warnings fixed, compiler and linker security options added. - Test application reworked: lens control only through the terminal. - Simple example fixed. - Documentation updated.

Library files

The library is supplied by source code only. The user will 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.
static --------------- Folder with images of this document.
src ------------------ Folder with library source code.
    CMakeLists.txt --- CMake file of the library.
    YlParser.h ------- Protocol parser header file.
    YlParser.cpp ----- Protocol parser C++ implementation file.
    Ylc.h ------------ Main library header file.
    Ylc.cpp ---------- C++ implementation file.
    YlcVersion.h ----- Header file with library version.
    YlcVersion.h.in -- Service CMake file to generate version header.
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.

Ylc class description

Ylc class declaration

Ylc.h file contains Ylc class declaration.

namespace rapidpixel
{
class Ylc : public Lens
{
public:

    /// Class constructor.
    Ylc();

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

    /// Copy and move constructors and assignments are deleted.
    Ylc(const Ylc&) = delete;
    Ylc(Ylc&&) = delete;
    Ylc& operator=(const Ylc&) = delete;
    Ylc& operator=(Ylc&&) = delete;

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

    /// Open serial port.
    bool openLens(std::string initString) override;

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

    /// Close serial port and stop communication thread.
    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.
    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 the string of the current version of the Ylc class. Method declaration:

static std::string getVersion();

The method can be used without a Ylc class instance. Example:

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

Console output:

Ylc version: 4.2.2

openLens method

The openLens(…) method opens the serial port to communicate with Yamano lenses and runs the communication thread (thread to communicate with equipment via serial port). If the serial port is already open, the method returns TRUE and does nothing else. After power up, the Yamano lens will start moving zoom tele/wide for hardware self-calibration. After hardware self-calibration, the library will start detecting actual zoom/focus ranges. This takes about 30 seconds (the time of the hardware self-calibration of the lens is not included). The method is thread-safe. Method declaration:

bool openLens(std::string initString) override;

Parameter

Value

initString

Initialization string. The format can be in 2 different forms: - [serial port name];[baudrate];[timeout] - [serial port name];[baudrate] The fields are divided by the ‘;’ symbol, empty fields are skipped. The baudrate must be an integer greater than 0. The timeout must be an integer, it is checked but not used: the serial port is read without waiting. An initialization string with only one field or with more than three fields is not valid. Recommended initialization string format for controllers which use serial port: “/dev/ttyUSB0;9600;100” (“/dev/ttyUSB0” - serial port name, “9600” - baudrate, “100” - timeout).

Returns: TRUE if the serial port is open or FALSE if not (the initialization string is not valid or the serial port can’t be opened).

initLens method

The initLens(…) method initializes the lens controller and sets lens params (Lens interface). The method will set the given lens params (a value that the setParam(…) method doesn’t accept is skipped) and then call the openLens(…) method. After the serial port is open, the method switches the autofocus of the lens off: the autofocus is performed by the library. After power up, the Yamano lens will start moving zoom tele/wide for hardware self-calibration. After hardware self-calibration, the library will run auto detection of zoom and focus ranges. This takes about 30 seconds. Also, after lens disconnection and reconnection (disconnection means no responses from lens), the library will run auto range detection again. The method is thread-safe. Method declaration:

bool initLens(LensParams& params) override;

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

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

closeLens method

The closeLens() method closes the serial port and stops the communication thread. The method returns after the thread is stopped (it can take up to 3 seconds). Commands that are not sent to the lens stay in the command buffer. The method is thread-safe. Method declaration:

void closeLens() override;

isLensOpen method

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

bool isLensOpen() override;

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

isLensConnected method

The isLensConnected() method shows if the lens controller receives responses from the equipment. For example, if the serial port is open but the equipment is not active (no power). In this case, the isLensOpen(…) method will return TRUE but the isLensConnected() method will return FALSE. The method is thread-safe. 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 a new lens parameter value. Ylc provides a thread-safe setParam(…) method call. This means that the setParam(…) method can be safely called from any thread. The method doesn’t throw exceptions. Method declaration:

bool setParam(LensParam id, float value) override;

Parameter	Description
id	Lens parameter ID according to LensParam enum.
value	Lens parameter value. The value depends on the parameter ID (LensParam enum). The fraction of the value is dropped for the parameters with integer values. A NaN, an infinity and a value outside of the range of the parameter are not accepted.

Returns: TRUE if the parameter was set or FALSE if not (the parameter is not supported or is read only, or the value is not accepted).

Note: Commands for the lens (for example, for the ZOOM_POS parameter) are put into the command buffer of 48 commands and are sent by the communication thread after the detection of the zoom/focus ranges is finished. If the buffer is full, the oldest command is dropped. The communication thread sends one command per cycle (about 50 ms) and requests the lens positions only when the buffer is empty. If the thread gets no data from the lens during more than 30 cycles in a row, the library considers the lens as disconnected and runs the detection of the ranges again. So, do not put more than 30 commands into the buffer at once.

getParam method

The getParam(…) method returns the lens parameter value. Ylc provides a thread-safe getParam(…) method call. This means that the getParam(…) method can be safely called from any thread. The method doesn’t throw exceptions. 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. Ylc provides a thread-safe getParams(…) method call. This means that the getParams(…) method can be safely called from any thread. The method doesn’t throw exceptions. Method declaration:

void getParams(LensParams& params) override;

Parameter	Description
params	Reference to the LensParams class object which includes all lens parameters. The object is not changed if the method fails.

executeCommand method

The executeCommand(…) method executes a lens action command. Ylc provides a thread-safe executeCommand(…) method call. This means that the executeCommand(…) method can be safely called from any thread. The method doesn’t throw exceptions. Commands for the lens are handled in the same way as the commands of the setParam(…) method (see the note of that method). 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. The value depends on the command ID (see description of LensCommand enum). The argument is used by the commands ZOOM_TO_POS, FOCUS_TO_POS and IRIS_TO_POS only: 0 - 65535, the fraction is dropped, a NaN, an infinity and a value outside of the range are not accepted.

Returns: TRUE if the command was executed (accepted by lens controller) or FALSE if not (the command is not supported, the argument is not accepted, or the command is declined: the autofocus can’t be started in the manual focus mode).

addVideoFrame method

The addVideoFrame(…) method gives a video frame to the autofocus algorithm. The user should add each video frame. The method is thread-safe. 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 the encodeCommand(…) and encodeSetParamCommand(…) methods of the Lens interface classes. If a command is decoded, the method will call the setParam(…) or executeCommand(…) methods for lens interfaces. This method is thread-safe. This means that the method can be safely called from any thread. The method doesn’t throw exceptions. Method declaration:

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

Parameter	Description
data	Pointer to the input command. Must not be nullptr. To generate an input command, you may use the encodeCommand(…) and encodeSetParamCommand(…) methods.
size	Size of the 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.

encodeSetParamCommand method of Lens class

The encodeSetParamCommand(…) static method of the 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 their 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 the 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 have size >= 11.
size	Size of encoded data. Will be 11 bytes.
id	Parameter ID according to LensParam enum.
value	Parameter value.

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

// Buffer for encoded data.
uint8_t data[11];
// Size of encoded data.
int size = 0;
// Parameter value.
float outValue = 10.0f;
// Encode command.
rapidpixel::Lens::encodeSetParamCommand(data, size, rapidpixel::LensParam::AF_ROI_X0, outValue);

encodeCommand method of Lens class

The encodeCommand(…) static method of the Lens interface class is designed to encode a lens action command. To control a lens remotely, the developer has to develop their 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(…) is designed to encode the 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 have size >= 11.
size	Size of encoded data. Will be 11 bytes.
id	Command ID according to LensCommand enum.
arg	Command argument value (the value depends on the command ID).

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

// Buffer for encoded data.
uint8_t data[11];
// Size of encoded data.
int size = 0;
// Command argument value.
float outValue = 10.0f;
// Encode command.
rapidpixel::Lens::encodeCommand(data, size, rapidpixel::LensCommand::ZOOM_TO_POS, outValue);

decodeCommand method of Lens class

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

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

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 open) 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 executing this command, the
    /// lens controller should automatically set at least the 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.
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.
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.
AF_START	Start autofocus. Command doesn’t have arguments.
AF_STOP	Stop autofocus. Command doesn’t have arguments.
RESTART	Not supported by Ylc class.
DETECT_HW_RANGES	Not supported by Ylc 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 open) 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 a new ZOOM_HW_MAX_SPEED value the parameter
    /// ZOOM_SPEED must be updated automatically. If the new value of
    /// ZOOM_HW_MAX_SPEED parameter is 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 implementation and lens
    /// hardware. The value of the parameter 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 a new FOCUS_HW_MAX_SPEED value the parameters
    /// FOCUS_SPEED and FOCUS_HW_SPEED must be updated by the lens controller
    /// automatically. If the new value of FOCUS_HW_MAX_SPEED parameter is
    /// 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 parameter 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 a new IRIS_HW_MAX_SPEED value the parameters IRIS_SPEED and
    /// IRIS_HW_SPEED must be updated automatically. If the new value of
    /// IRIS_HW_MAX_SPEED parameter is 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 is 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 is out of limits.
    ZOOM_HW_WIDE_LIMIT,
    /// Focus hardware far limit. Value depends on implementation and lens
    /// hardware. Lens controller should control focus position. Lens controller
    /// should stop focus moving if hardware focus position is 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 is 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 is 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 is 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 (method will return 0). If lens
    /// controller has data exchange with lens equipment the method will
    /// return 1. If lens controller is not initialized the connection status is 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 lens to
    /// initialize necessary parameters for particular lens hardware.
    TYPE,
    /// Lens custom parameter. Value depends on particular lens controller.
    /// Custom parameters are used when particular lens equipment has specific
    /// unusual parameters.
    CUSTOM_1,
    /// Lens custom parameter. Value depends on particular lens controller.
    /// Custom parameters are used when particular lens equipment has specific
    /// unusual parameters.
    CUSTOM_2,
    /// Lens custom parameter. Value depends on particular lens controller.
    /// Custom parameters are used when particular lens equipment has specific
    /// unusual parameters.
    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 = 0, ZOOM_HW_TELE_LIMIT = 65535. 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	Focus mode: 0 - Manual focus control. 1 - Push auto focus mode. 2 - Continuous auto focus mode.
FILTER_MODE	read / write	Filter mode: 0 - VC filter auxiliary (out) * 2 1 - VC filter auxiliary (in) * 2
AF_ROI_X0	read / write	Autofocus ROI top-left corner horizontal position in pixels. Autofocus ROI is rectangle. Value: 0 - 8162.
AF_ROI_Y0	read / write	Autofocus ROI top-left corner vertical position in pixels. Autofocus ROI is rectangle. Value: 0 - 8162.
AF_ROI_X1	read / write	Autofocus ROI bottom-right corner horizontal position in pixels. Autofocus ROI is rectangle. Value: 0 - 8162.
AF_ROI_Y1	read / write	Autofocus ROI bottom-right corner vertical position in pixels. Autofocus ROI is rectangle. Value: 0 - 8162.
ZOOM_SPEED	read / write	Not supported by Ylc class.
ZOOM_HW_SPEED	read / write	Not supported by Ylc class.
ZOOM_HW_MAX_SPEED	read / write	Not supported by Ylc class.
FOCUS_SPEED	read / write	Not supported by Ylc class.
FOCUS_HW_SPEED	read / write	Not supported by Ylc class.
FOCUS_HW_MAX_SPEED	read / write	Not supported by Ylc class.
IRIS_SPEED	read / write	Not supported by Ylc class.
IRIS_HW_SPEED	read / write	Not supported by Ylc class.
IRIS_HW_MAX_SPEED	read / write	Not supported by Ylc class.
ZOOM_HW_TELE_LIMIT	read / write	Zoom hardware tele limit. Default value 65535. Value: 0 - 65535, must be greater than ZOOM_HW_WIDE_LIMIT. After initialization the library runs auto detection of zoom/focus ranges and sets this value, so a value which is set before the end of the detection is replaced.
ZOOM_HW_WIDE_LIMIT	read / write	Zoom hardware wide limit. Default value 0. Value: 0 - 65535, must be less than ZOOM_HW_TELE_LIMIT. After initialization the library runs auto detection of zoom/focus ranges and sets this value, so a value which is set before the end of the detection is replaced.
FOCUS_HW_FAR_LIMIT	read / write	Focus hardware far limit. Default value 65535. Value: 0 - 65535, must be greater than FOCUS_HW_NEAR_LIMIT. After initialization the library runs auto detection of zoom/focus ranges and sets this value, so a value which is set before the end of the detection is replaced.
FOCUS_HW_NEAR_LIMIT	read / write	Focus hardware near limit. Default value 0. Value: 0 - 65535, must be less than FOCUS_HW_FAR_LIMIT. After initialization the library runs auto detection of zoom/focus ranges and sets this value, so a value which is set before the end of the detection is replaced.
IRIS_HW_OPEN_LIMIT	read / write	Iris hardware open limit. Default value 65535. Value: 0 - 65535, must be greater than IRIS_HW_CLOSE_LIMIT.
IRIS_HW_CLOSE_LIMIT	read / write	Iris hardware close limit. Default value 0. Value: 0 - 65535, must be less than IRIS_HW_OPEN_LIMIT.
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. After initialization the library runs auto detection of zoom/focus ranges. So, this values will be 0 before finish of auto range detection.
FOCUS_HW_AF_SPEED	read / write	Not supported by Ylc class.
FOCUS_FACTOR_THRESHOLD	read / write	Threshold for changes of focus factor to start refocus. Values: 0% - no check, 100% - changing x2. Value: 0 - 100.
REFOCUS_TIMEOUT_SEC	read / write	Timeout for automatic refocus in seconds. Value: 0 - no automatic refocus, 1000 - maximum value.
AF_IS_ACTIVE	read only	Flag about active autofocus algorithm. Value: 0 - autofocus not working, 1 - working.
IRIS_MODE	read / write	Iris mode: 0 - Auto iris off. 1 - Auto iris on.
AUTO_AF_ROI_WIDTH	read / write	ROI width (pixels) for autofocus algorithm when lens controller detects ROI position automatically. Value: 1 - 8191.
AUTO_AF_ROI_HEIGHT	read / write	ROI height (pixels) for autofocus algorithm when lens controller detects ROI position automatically. Value: 1 - 8191.
AUTO_AF_ROI_BORDER	read / write	Video frame border size (along vertical and horizontal axes). Value: 1 - 8191.
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	Extender mode: 0 - X2 extender lens out. 1 - X2 extender lens in. The fraction of the value is dropped, a value other than 0 switches the X2 extender lens in.
STABILIZER_MODE	read / write	Not supported by Ylc class.
AF_RANGE	read / write	Not supported by Ylc class.
X_FOV_DEG	read / write	Not supported by Ylc class.
Y_FOV_DEG	read / write	Not supported by Ylc 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 Ylc 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 Ylc class.
CUSTOM_1	read / write	Percentages of central ROI for AF Engine. Value: 1-100.
CUSTOM_2	read / write	Time adjustment for AF Engine, ms. Value: -500 - 500.
CUSTOM_3	read / write	Not supported by Ylc 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)

    /// Special member functions.
    FovPoint() = default;
    FovPoint(const FovPoint& src) = default;
    FovPoint(FovPoint&& src) = default;
    FovPoint& operator= (const FovPoint& src) = default;
    FovPoint& operator= (FovPoint&& src) = default;
};

/// Lens params structure.
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 open) 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 parameter 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 a new ZOOM_HW_MAX_SPEED value the parameter ZOOM_SPEED must be
    /// updated automatically. If the new value of ZOOM_HW_MAX_SPEED parameter is
    /// 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 implementation and lens
    /// hardware. The value of the parameter 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 a new FOCUS_HW_MAX_SPEED value the parameters FOCUS_SPEED and
    /// FOCUS_HW_SPEED must be updated by the lens controller automatically.
    /// If the new value of FOCUS_HW_MAX_SPEED parameter is 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 parameter 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 a new IRIS_HW_MAX_SPEED value the parameters IRIS_SPEED and
    /// IRIS_HW_SPEED must be updated automatically. If the new value of
    /// IRIS_HW_MAX_SPEED parameter is 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 is 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 is out of limits.
    int zoomHwWideLimit{0};
    /// Focus hardware far limit. Value depends on implementation and lens
    /// hardware. Lens controller should control focus position. Lens controller
    /// should stop focus moving if hardware focus position is 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 is 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 is 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 is 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 (method will return 0). If lens controller has data exchange
    /// with lens equipment the method will return 1. If lens controller is not
    /// initialized the connection status is 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};
    /// Timeout for automatic refocus in seconds. Value: 0 - no automatic
    /// refocus, 100000 - maximum value.
    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 lens to
    /// initialize necessary parameters for particular lens hardware.
    int type{0};
    /// Lens custom parameter. Value depends on particular lens controller.
    /// Custom parameters are used when particular lens equipment has specific
    /// unusual parameters.
    float custom1{0.0f};
    /// Lens custom parameter. Value depends on particular lens controller.
    /// Custom parameters are used when particular lens equipment has specific
    /// unusual parameters.
    float custom2{0.0f};
    /// Lens custom parameter. Value depends on particular lens controller.
    /// Custom parameters are used when particular lens equipment has specific
    /// unusual parameters.
    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)

    /// Special member functions.
    LensParams() = default;
    LensParams(const LensParams& src) = default;
    LensParams(LensParams&& src) = default;
    LensParams& operator= (const LensParams& src) = default;
    LensParams& operator= (LensParams&& src) = default;

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

    /// Decode params.
    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 0 (full wide) - 65535 (full tele) by default.
focusPos	int	Focus position 0 (full near) - 65535 (full far).
focusHwPos	int	Hardware focus position 0 (full near) - 65535 (full far) by default.
irisPos	int	Iris position 0 (full close) - 65535 (full open).
irisHwPos	int	Hardware iris position 0 (full close) - 65535 (full open) by default.
focusMode	int	Focus mode: 0 - Manual focus control. 1 - Push auto focus mode. 2 - Continuous auto focus mode.
filterMode	int	Filter mode: 0 - VC filter auxiliary (out) * 2 1 - VC filter auxiliary (in) * 2
afRoiX0	int	Autofocus ROI top-left corner horizontal position in pixels. Autofocus ROI is rectangle. Value: 0 - 8162.
afRoiY0	int	Autofocus ROI top-left corner vertical position in pixels. Autofocus ROI is rectangle. Value: 0 - 8162.
afRoiX1	int	Autofocus ROI bottom-right corner horizontal position in pixels. Autofocus ROI is rectangle. Value: 0 - 8162.
afRoiY1	int	Autofocus ROI bottom-right corner vertical position in pixels. Autofocus ROI is rectangle. Value: 0 - 8162.
zoomSpeed	int	Not supported by Ylc class.
zoomHwSpeed	int	Not supported by Ylc class.
zoomHwMaxSpeed	int	Not supported by Ylc class.
focusSpeed	int	Not supported by Ylc class.
focusHwSpeed	int	Not supported by Ylc class.
focusHwMaxSpeed	int	Not supported by Ylc class.
irisSpeed	int	Not supported by Ylc class.
irisHwSpeed	int	Not supported by Ylc class.
irisHwMaxSpeed	int	Not supported by Ylc class.
zoomHwTeleLimit	int	Zoom hardware tele limit. Default value 65535. Value: 0 - 65535, must be greater than ZOOM_HW_WIDE_LIMIT. After initialization the library runs auto detection of zoom/focus ranges and sets this value, so a value which is set before the end of the detection is replaced.
zoomHwWideLimit	int	Zoom hardware wide limit. Default value 0. Value: 0 - 65535, must be less than ZOOM_HW_TELE_LIMIT. After initialization the library runs auto detection of zoom/focus ranges and sets this value, so a value which is set before the end of the detection is replaced.
focusHwFarLimit	int	Focus hardware far limit. Default value 65535. Value: 0 - 65535, must be greater than FOCUS_HW_NEAR_LIMIT. After initialization the library runs auto detection of zoom/focus ranges and sets this value, so a value which is set before the end of the detection is replaced.
focusHwNearLimit	int	Focus hardware near limit. Default value 0. Value: 0 - 65535, must be less than FOCUS_HW_FAR_LIMIT. After initialization the library runs auto detection of zoom/focus ranges and sets this value, so a value which is set before the end of the detection is replaced.
irisHwOpenLimit	int	Iris hardware open limit. Default value 65535. Value: 0 - 65535, must be greater than IRIS_HW_CLOSE_LIMIT.
irisHwCloseLimit	int	Iris hardware close limit. Default value 0. Value: 0 - 65535, must be less than IRIS_HW_OPEN_LIMIT.
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: false - no response from lens. true - connected. After initialization the library runs auto detection of zoom/focus ranges. So, this value will be false before finish of auto range detection.
afHwSpeed	int	Not supported by Ylc class.
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, 1000 - maximum value.
afIsActive	bool	Flag about active autofocus algorithm. Value: false - autofocus not working, true - working.
irisMode	int	Iris mode: 0 - Auto iris off. 1 - Auto iris on.
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). 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	Extender mode: 0 - X2 extender lens out. 1 - X2 extender lens in. The fraction of the value is dropped, a value other than 0 switches the X2 extender lens in.
stabiliserMode	int	Not supported by Ylc class.
afRange	int	Not supported by Ylc class.
xFovDeg	float	Not supported by Ylc class.
yFovDeg	float	Not supported by Ylc class.
logMode	int	Logging mode. Values: 0 - Disable. 1 - Only terminal. 2 - Only file. 3 - File and terminal.
temperature	float	Not supported by Ylc 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: false - not open (not initialized), true - open (initialized).
type	int	Not supported by Ylc class.
custom1	float	Percentages of central ROI for AF Engine. Value: 1-100.
custom2	float	Time adjustment for AF Engine, ms. Value: -500 - 500.
custom3	float	Not supported by Ylc 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

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:

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

Example without parameters mask:

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

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 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, sizeof(data), size))
{
    std::cout << "Can't encode data" << 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;
}

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;
for (int i = 0; i < 5; ++i)
{
    rapidpixel::FovPoint pt;
    pt.hwZoomPos = 10 * (i + 1);
    pt.xFovDeg = 1.5f * static_cast<float>(i + 1);
    pt.yFovDeg = 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;
    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;
}

TestLensParams.json will look like:

{
    "lensParams": {
        "afHwSpeed": 93,
        "afRange": 128,
        "afRoiMode": 239,
        "afRoiX0": 196,
        "afRoiX1": 252,
        "afRoiY0": 115,
        "afRoiY1": 101,
        "autoAfRoiBorder": 70,
        "autoAfRoiHeight": 125,
        "autoAfRoiWidth": 147,
        "custom1": 91.0,
        "custom2": 236.0,
        "custom3": 194.0,
        "extenderMode": 84,
        "filterMode": 49,
        "focusFactorThreshold": 98.0,
        "focusHwFarLimit": 228,
        "focusHwMaxSpeed": 183,
        "focusHwNearLimit": 47,
        "focusMode": 111,
        "fovPoints": [
            {
                "hwZoomPos": 55,
                "xFovDeg": 6.0,
                "yFovDeg": 51.0
            },
            {
                "hwZoomPos": 63,
                "xFovDeg": 249.0,
                "yFovDeg": 33.0
            },
            {
                "hwZoomPos": 4,
                "xFovDeg": 121.0,
                "yFovDeg": 144.0
            },
            {
                "hwZoomPos": 53,
                "xFovDeg": 214.0,
                "yFovDeg": 153.0
            },
            {
                "hwZoomPos": 143,
                "xFovDeg": 15.0,
                "yFovDeg": 218.0
            }
        ],
        "initString": "dfhglsjirhuhjfb",
        "irisHwCloseLimit": 221,
        "irisHwMaxSpeed": 79,
        "irisHwOpenLimit": 211,
        "irisMode": 206,
        "logMode": 216,
        "refocusTimeoutSec": 135,
        "stabiliserMode": 137,
        "type": 125,
        "zoomHwMaxSpeed": 157,
        "zoomHwTeleLimit": 68,
        "zoomHwWideLimit": 251
    }
}

Build and connect to your project

Build stand alone

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

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

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

CMake options

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

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

Connect to your project

If you want to connect the Ylc library to your CMake project as source code, you can do the following. 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 Ylc repository and of the repositories it depends on there. New structure of your repository:

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

The Ylc library does not add the libraries it depends on when it is included in another project: your project must add them. Create CMakeLists.txt file in 3rdparty folder. 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_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_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_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_YLC                             ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_YLC)
    SET(${PARENT}_YLC                                   ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_YLC_TEST                              OFF CACHE BOOL "" FORCE)
    SET(${PARENT}_YLC_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_SERIAL_PORT)
    add_subdirectory(SerialPort)
endif()

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

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

if (${PARENT}_SUBMODULE_AF_ENGINE)
    add_subdirectory(AFEngine)
endif()

if (${PARENT}_SUBMODULE_YLC)
    add_subdirectory(Ylc)
endif()

File 3rdparty/CMakeLists.txt adds the folders of the libraries and of Ylc to your project (the libraries first, in the order of their dependencies) and excludes test applications and examples from compiling (by default test applications are excluded from compiling if Ylc is included as sub-repository). If your project does not add the libraries Ylc depends on, the compilation stops with an error that a header file of a library is not found.

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

target_link_libraries(${PROJECT_NAME} Ylc)

Done!

Portability

The library is written in standard C++17 (compiler extensions are not used) and does not use assembler or SIMD instructions. The packets of the lens protocol are built and parsed byte by byte, so the code does not depend on the byte order of the CPU. The serial port is accessed through the SerialPort library: the serial port name depends on the OS (“/dev/ttyUSB0” or “/dev/serial/by-id/…” on Linux, “COM3” or “\\.\COM10” on Windows). The library was built and run with MSVC 2022 (x86-64), GCC 12 and 13 and Clang 15 and 18 (x86-64) and with GCC 13 for aarch64 (run under qemu-user).

Simple example

A simple application shows how to use the Ylc library. The application opens the lens, waits for the connection (the library detects the hardware ranges of zoom and focus first), moves the zoom to the full tele position and shows the zoom position.

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



/// Maximum time to wait for the connection with the lens, seconds. After the
/// serial port is open the library detects the hardware ranges of the zoom and
/// the focus (about 30 seconds) and only then reports that the lens is
/// connected.
constexpr int CONNECTION_TIMEOUT_SEC{120};
/// Zoom position of the full tele.
constexpr float ZOOM_TELE_POSITION{65535.0f};
/// Number of zoom positions to show.
constexpr int ZOOM_REPORTS_NUMBER{50};
/// Period of showing the zoom position, milliseconds.
constexpr int ZOOM_REPORT_PERIOD_MSEC{100};



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

    // Wait for the connection with the lens.
    for (int i = 0; i < CONNECTION_TIMEOUT_SEC && !lens->isLensConnected(); ++i)
    {
        std::this_thread::sleep_for(std::chrono::seconds(1));
    }
    if (!lens->isLensConnected())
    {
        std::cout << "ERROR: No response from the lens" << std::endl;
        lens->closeLens();
        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, ZOOM_TELE_POSITION))
    {
        std::cout << "ERROR: Can't execute the command" << std::endl;
        lens->closeLens();
        return -1;
    }

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

    lens->closeLens();
    return 0;
}

Test application

Folder Ylc/test contains the test application files. The test application is a console application that allows the user to set params, get params and execute commands of the lens through the terminal: it does not show video and does not create a graphical user interface. The user must enter the serial port name (full name for Linux, for example “/dev/ttyUSB0”, or the port name for Windows, for example “COM3”), baudrate and timeout (Enter means the default value: 9600 and 0). The input is read line by line: a wrong value is reported and the application returns to the menu. When the input is closed, the application closes the lens and exits.

The test application sets the log mode of the library to 1 (print log messages to the terminal). Test application output will look like:

============================
Ylc v4.2.2 test.
============================
Enter serial port name (for example /dev/ttyUSB0 or COM3): COM3
Enter baudrate (Enter - 9600): 
Enter time out (Enter - 0): 

Choose option:
1 - Set lens param
2 - Get lens param
3 - Execute lens command
4 - Show all lens params
-1 - Exit
Option: 1
Lens params:
1 - ZOOM_POS                    2 - ZOOM_HW_POS
3 - FOCUS_POS                   4 - FOCUS_HW_POS
5 - IRIS_POS                    6 - IRIS_HW_POS
7 - FOCUS_MODE                  8 - FILTER_MODE
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
34 - IRIS_MODE                  39 - EXTENDER_MODE
44 - LOG_MODE                   

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

Choose option:
1 - Set lens param
2 - Get lens param
3 - Execute lens command
4 - Show all lens params
-1 - Exit
Option: 2
Lens params:
1 - ZOOM_POS                    2 - ZOOM_HW_POS
3 - FOCUS_POS                   4 - FOCUS_HW_POS
5 - IRIS_POS                    6 - IRIS_HW_POS
7 - FOCUS_MODE                  8 - FILTER_MODE
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
34 - IRIS_MODE                  39 - EXTENDER_MODE
44 - LOG_MODE                   29 - IS_CONNECTED
46 - IS_OPEN                    

Choose param to get (-1 to exit to main menu): 29
IS_CONNECTED = 0

Choose option:
1 - Set lens param
2 - Get lens param
3 - Execute lens command
4 - Show all lens params
-1 - Exit
Option: -1

---

Table of contents