Slc C++ library

v2.2.0

Table of contents

• Overview
• Versions
• Library files
• Slc class description
  • Slc 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

Slc is a C++ software controller for Stingray SWIR lenses. The library implements the Lens interface and adds autofocus functions based on the AFEngine library. The library uses the following libraries: Lens (interface and data structures; it uses the libraries Frame and ConfigReader), Logger (logging helpers), SerialPort (serial communication), StingrayParser (command encoder/decoder; a part of the Slc repository: folder src/parser, see src/parser/README.md) and AFEngine (autofocus algorithms). The other libraries are separate repositories: the Slc repository does not contain their source code (see Build and connect to your project). The codebase targets the C++17 standard and supports Linux and Windows.

Slc 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	23.06.2023	First version.
2.0.0	22.01.2024	- Lens interface updated. - Autofocus algorithms implemented. - Submodules updated.
2.0.1	15.02.2024	- Zoom/focus position limit handling updated. - Documentation updated.
2.0.2	30.04.2024	- Submodules updated. - Documentation updated.
2.0.5	23.05.2024	- Submodules updated. - Documentation updated.
2.0.6	07.08.2024	- CMake structure updated.
2.0.7	18.09.2024	- AFEngine submodule updated.
2.0.8	17.03.2025	- AFEngine noise reduction is disabled by default.
2.0.9	03.04.2025	- Logger submodule updated.
2.0.10	14.05.2025	- AFEngine submodule updated.
2.0.11	26.10.2025	- SerialPort submodule updated. - StingrayParser submodule updated.
2.0.12	05.11.2025	- Fixed setParam mutex lock bug. - Added automatic hardware reset after lens errors. - Updated test application. - Updated StingrayParser submodule.
2.0.13	13.11.2025	- Fixed AFEngine usage. - Updated params list. - Documentation updated.
2.0.14	18.11.2025	- Updated ERROR15 handling.
2.0.15	28.03.2026	- AFEngine submodule updated.
2.1.0	01.07.2026	- AFEngine submodule updated. - Critical bugs fixed.
2.1.1	13.07.2026	- Updated AFEngine submodule.
2.1.2	17.10.2026	- Git submodules removed: the libraries which Slc depends on are placed next to the library (see Build stand alone). - Test application redone: it controls the lens params from the terminal only. - setParam(…) and executeCommand(…) reject NaN, infinity and values out of the range of the parameter. REFOCUS_TIMEOUT_SEC is limited to 100000 seconds. LOG_MODE is returned as it was set (file = 1, terminal = 2) and is reported by getParams(…). - LOG_MODE accepts only the values 0, 1, 2 and 3. addVideoFrame(…) ignores a frame without data. A part of a message to the lens that was not sent by a write call is sent by the next call. - Fixed data races of the communication thread, executeCommand(…) and addVideoFrame(…). Fixed nullptr dereference in decodeAndExecuteCommand(…). - Compiler warnings fixed, compiler and linker hardening flags added. - Documentation updated.
2.2.0	29.10.2026	- The StingrayParser library is a part of the repository (folder src/parser) and is not a separate dependency any more.

Library files

The library is distributed as source code. You receive a CMake-based project with the following structure:

CMakeLists.txt --------------------------- Main CMake file of the library.
src -------------------------------------- Folder with library source code.
    CMakeLists.txt ----------------------- CMake file of the library.
    Slc.h -------------------------------- Main library header file.
    Slc.cpp ------------------------------ C++ implementation file.
    SlcVersion.h ------------------------- Header file with library version.
    SlcVersion.h.in ---------------------- CMake file to generate version header.
    parser ------------------------------- Protocol parser library (former StingrayParser repository).
        .gitignore ----------------------- Git ignore file of the parser library.
        CMakeLists.txt ------------------- Main CMake file of the parser library.
        README.md ------------------------ Documentation of the parser library.
        src ------------------------------ Folder with source code of the parser library.
            CMakeLists.txt --------------- CMake file of the parser library (target StingrayParser).
            StingrayParser.cpp ----------- C++ implementation file of the parser library.
            StingrayParser.h ------------- Main header file of the parser library (StingrayParser class declaration).
            StingrayParserVersion.h ------ Header file with version of the parser library.
            StingrayParserVersion.h.in --- CMake service file to generate version header of the parser library.
        static --------------------------- Folder with images of the parser documentation.
            stingrayparser_web_logo.png -- Logo of the parser library.
        test ----------------------------- Folder with test application of the parser (not built by Slc).
            CMakeLists.txt --------------- CMake file for test application of the parser.
            main.cpp --------------------- Source C++ file of test application of the parser.
test ------------------------------------- Folder with test application files.
    CMakeLists.txt ----------------------- CMake file for test application.
    main.cpp ----------------------------- Source C++ file of test application.
example ---------------------------------- Folder with simple example application.
    CMakeLists.txt ----------------------- CMake file for simple example application.
    main.cpp ----------------------------- Source C++ file of simple example application.
static ----------------------------------- Folder with the images of this document.

The other libraries which Slc depends on are not part of the repository (see Build stand alone).

Slc class description

Slc class declaration

Slc.h file contains Slc class declaration.

namespace rapidpixel
{
class Slc : public Lens
{
public:

    /// Class constructor.
    Slc();

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

    /// Copy and move operations are deleted.
    Slc(const Slc&) = delete;
    Slc(Slc&&) = delete;
    Slc& operator=(const Slc&) = delete;
    Slc& operator=(Slc&&) = 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() method returns the current Slc version string. Method declaration:

static std::string getVersion();

Because the method is static, you can call it without creating an Slc instance. Example:

std::cout << "Slc version: " << rapidpixel::Slc::getVersion();

Console output:

Slc version: 2.2.0

openLens method

The openLens(…) method opens the serial port (baud rate 115200, 8 data bits, no parity, 1 stop bit) and starts the communication thread, so the controller can communicate with Stingray lenses. The communication thread sends one message to the lens every 50 ms: the next queued command or, if there is no command, the status request. If the lens is already open, the method does nothing and returns true. The method changes only the open status and the initString of the parameters. The method can be called from any thread (calls of openLens(…), initLens(…) and closeLens() are serialized). Method declaration:

bool openLens(std::string initString) override;

Parameter	Value
initString	Initialization string: the full serial port name. Example: "/dev/ttyUSB0". If the string contains several parts separated by ;, the first not empty part is the port name and the other parts are ignored. The name must not contain the NUL character. The string must come from a trusted configuration: the device with this name is opened.

Returns: true if the lens controller is initialized, otherwise false (the string has no port name, the port can’t be opened or the communication thread can’t be started).

initLens method

The initLens(…) method sets the parameters of the controller from the provided LensParams object and then calls openLens(…) with the initString field. The method sets the fields logMode (first), focusMode, afRoiX0, afRoiY0, afRoiX1, afRoiY1, zoomSpeed, focusSpeed, zoomHwTeleLimit, zoomHwWideLimit, focusHwFarLimit, focusHwNearLimit, focusFactorThreshold, refocusTimeoutSec, autoAfRoiWidth, autoAfRoiHeight, autoAfRoiBorder, afRoiMode, custom1 and custom2 in the way of setParam(…). A field with a value which the controller rejects (for example zoomHwTeleLimit 65535, the default value of the LensParams class) is skipped: the current value stays. On success the communication thread is started if it is not running yet. Method declaration:

bool initLens(LensParams& params) override;

Parameter	Value
params	LensParams object containing the desired configuration. The initString field is forwarded to openLens(…).

Returns: true if the lens controller is initialized, otherwise false (see openLens(…)).

closeLens method

The closeLens() method stops the communication thread and closes the serial port. If the lens is closed, the method does nothing. Commands which are not sent yet stay in the output queue and are sent after the next call of openLens(…) or initLens(…). Method declaration:

void closeLens() override;

isLensOpen method

The isLensOpen() method reports whether the controller has opened the serial port and completed initialization. It does not indicate whether the lens is responding. For example, if the serial port is open but the lens is unpowered, isLensOpen() still returns true. Method declaration:

bool isLensOpen() override;

Returns: true if the lens controller is initialized, otherwise false.

isLensConnected method

The isLensConnected() method indicates whether the controller is currently receiving responses from the lens. The status is true after the first period of the communication thread (50 ms) and becomes false if the controller receives no data from the lens for about one second, so after the lens is opened the status is true for about one second even if the lens does not respond. For example, if the serial port is open but the lens has no power, isLensOpen(…) returns true while isLensConnected() returns false (after about one second). Method declaration:

bool isLensConnected() override;

Returns: true when the controller has an active data exchange with the lens, otherwise false.

setParam method

The setParam(…) method sets a new lens parameter value. Slc provides a thread-safe setParam(…) method call. This means that the setParam(…) method can be safely called from any thread. The value must be inside the range of the parameter (see Table 3): NaN, infinity and a value outside of the range are rejected. A value of an integer parameter is truncated to an integer. A parameter which is not supported by Slc is rejected. If the method returns false the parameters are not changed. 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 parameter ID (LensParam enum).

Returns: true if the parameter was set, otherwise false.

getParam method

The getParam(…) method returns a lens parameter value. Slc provides a 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.0f if the parameter is not supported by Slc.

getParams method

The getParams(…) method copies the current controller settings into the supplied LensParams instance. The autofocus ROI coordinates, the focus factor and the time adjustment (custom2) are read from the autofocus engine. Slc keeps the call thread-safe, so it can be invoked from any thread. Method declaration:

void getParams(LensParams& params) override;

Parameter	Description
params	Reference to a LensParams object that receives the current lens parameters.

executeCommand method

The executeCommand(…) method executes a lens action command. Slc provides a thread-safe executeCommand(…) method call. This means that the executeCommand(…) method can be safely called from any thread. The commands which move the lens (ZOOM_TELE, ZOOM_WIDE, ZOOM_TO_POS, ZOOM_STOP, FOCUS_FAR, FOCUS_NEAR, FOCUS_TO_POS, FOCUS_STOP and RESTART) are placed into the output queue and are sent by the communication thread, one command every 50 ms. The queue holds 48 commands: if it is full the oldest command is dropped. The commands are queued even if the lens is closed. A command which is not supported by Slc is rejected. 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 argument of ZOOM_TO_POS and FOCUS_TO_POS is the position 0 - 65535. The argument is truncated to an integer, so the values from -1 to 65536 (not including them) are accepted, NaN, infinity and the other values are rejected. The other commands ignore the argument (see description of LensCommand enum).

Returns: true if the command was accepted by the lens controller (a command which moves the lens is queued, it is not executed yet), otherwise false.

addVideoFrame method

The addVideoFrame(…) method passes a video frame to the autofocus engine so the autofocus algorithm can operate. The engine calculates the focus factor inside the autofocus ROI (readable through getParam(…) with the FOCUS_FACTOR parameter). To keep autofocus active, call addVideoFrame(…) for each captured frame. If the autofocus ROI mode is manual (AF_ROI_MODE = 0) and all ROI coordinates are 0, the method sets the ROI from the frame size and the CUSTOM_1 value: the centred rectangle which has CUSTOM_1 percent of the frame width and height. A frame without data (the data pointer is nullptr or the size is not positive) is ignored. The method can be called at the same time as the other methods, but not 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 commands on the controller side. It understands payloads produced by encodeCommand(…) and encodeSetParamCommand(…). When decoding succeeds the controller dispatches the request to setParam(…) or executeCommand(…), so the values are checked by these methods. The call is thread-safe and can be made from any thread. Method declaration:

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

Parameter	Description
data	Pointer to the encoded command. Must not be nullptr and must be valid for size bytes. Generate payloads with encodeCommand(…) or encodeSetParamCommand(…).
size	Size of the command: must be 11 bytes (the size of the commands produced by the helpers).

Returns: true if the command is decoded (SET_PARAM or COMMAND) and executed, otherwise false (data is nullptr, the command can’t be decoded or was rejected by setParam(…) or executeCommand(…)).

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

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

Parameter	Description
data	Pointer to data buffer for encoded command. Must not be nullptr and must be valid for 11 bytes.
size	Size of encoded data: 11 bytes, or 0 if data is nullptr.
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.
const 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 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(…) is designed to encode COMMAND commands (action commands). Method declaration:

static void encodeCommand(uint8_t* data, int& size, LensCommand id, float arg = 0.0f);

Parameter	Description
data	Pointer to data buffer for encoded command. Must not be nullptr and must be valid for 11 bytes.
size	Size of encoded data: 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 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.
const 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 his 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 input commands (commands should be encoded by methods encodeSetParamCommand(…) 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). The value is not checked against any range.

Returns: 0 - in case decoding COMMAND, 1 - in case decoding SET_PARAM command or -1 in case errors (data is nullptr, wrong size, version, command type or ID). The output arguments are changed only if 0 or 1 is returned.

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 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 Slc class.
IRIS_CLOSE	Not supported by Slc class.
IRIS_TO_POS	Not supported by Slc class.
IRIS_STOP	Not supported by Slc 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	Not supported by Slc class.

Supported commands: The Slc implementation handles zoom, focus, autofocus, and restart commands. Iris-related commands and hardware range detection are defined by the base interface but are not implemented by Slc.

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 maximum and minimum 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 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 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. Parameter value: zoom position 0 (full wide) - 65535 (full tele). Zoom speed can be set by setParam(...). The stored value does not change immediately; it is updated while the lens moves.
ZOOM_HW_POS	read / write	Hardware zoom position. Setting this parameter moves the zoom to the specified hardware position ZOOM_HW_WIDE_LIMIT - ZOOM_HW_TELE_LIMIT (defaults: wide 0, tele 10000). Zoom speed can be set by setParam(...). The position value is updated only while 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(...). The stored value changes only while the lens moves.
FOCUS_HW_POS	read / write	Hardware focus position. Setting this parameter moves focus to FOCUS_HW_NEAR_LIMIT - FOCUS_HW_FAR_LIMIT (defaults: near 0, far 10000). Focus speed can be set by setParam(...). The position value is updated only while the lens moves.
IRIS_POS	read / write	Not supported by Slc class.
IRIS_HW_POS	read / write	Not supported by Slc 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	Not supported by Slc class.
AF_ROI_X0	read / write	Autofocus ROI top-left corner horizontal position in pixels (0 - 8192). Autofocus ROI is rectangle.
AF_ROI_Y0	read / write	Autofocus ROI top-left corner vertical position in pixels (0 - 8192). Autofocus ROI is rectangle.
AF_ROI_X1	read / write	Autofocus ROI bottom-right corner horizontal position in pixels (0 - 8192). Autofocus ROI is rectangle.
AF_ROI_Y1	read / write	Autofocus ROI bottom-right corner vertical position in pixels (0 - 8192). Autofocus ROI is rectangle.
ZOOM_SPEED	read / write	Zoom speed. Values range from 0 to 100, representing 0-100% of the maximum hardware zoom speed. If the user updates ZOOM_HW_SPEED, ZOOM_SPEED is adjusted automatically.
ZOOM_HW_SPEED	read / write	Zoom hardware speed. Zoom hardware speed range from 0 to ZOOM_HW_MAX_SPEED (128 by default in Slc). If the user sets a new value for ZOOM_SPEED, the ZOOM_HW_SPEED parameter is updated automatically.
ZOOM_HW_MAX_SPEED	read / write	Maximum zoom hardware speed. Updating this parameter adjusts ZOOM_SPEED to preserve the relative percentage. The default value in Slc is 128.
FOCUS_SPEED	read / write	Focus speed. Values range from 0 to 100, representing 0-100% of the maximum hardware focus speed. If the user updates FOCUS_HW_SPEED, FOCUS_SPEED is adjusted automatically.
FOCUS_HW_SPEED	read / write	Focus hardware speed. Focus hardware speed range from 0 to 255 (FOCUS_HW_MAX_SPEED is 50 by default in Slc). If the user sets a new value for FOCUS_SPEED, the FOCUS_HW_SPEED parameter is updated automatically.
FOCUS_HW_MAX_SPEED	read / write	Maximum focus hardware speed. Updating this parameter adjusts FOCUS_SPEED and FOCUS_HW_SPEED automatically. The default value in Slc is 50.
IRIS_SPEED	read / write	Not supported by Slc class.
IRIS_HW_SPEED	read / write	Not supported by Slc class.
IRIS_HW_MAX_SPEED	read / write	Not supported by Slc class.
ZOOM_HW_TELE_LIMIT	read / write	Zoom hardware tele limit. Default value 10000.
ZOOM_HW_WIDE_LIMIT	read / write	Zoom hardware wide limit. Default value 0.
FOCUS_HW_FAR_LIMIT	read / write	Focus hardware far limit. Default value 10000.
FOCUS_HW_NEAR_LIMIT	read / write	Focus hardware near limit. Default value 0.
IRIS_HW_OPEN_LIMIT	read / write	Not supported by Slc class.
IRIS_HW_CLOSE_LIMIT	read / write	Not supported by Slc class.
FOCUS_FACTOR	read only	Focus factor of the autofocus engine, -1 if it was not calculated. The value is updated every 50 ms while the lens is open and by getParams(…), it is 0 before the first update.
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. Valid range: 0 - FOCUS_HW_MAX_SPEED (initially 5 in Slc).
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 Slc class.
AUTO_AF_ROI_WIDTH	read / write	ROI width (pixels) for autofocus algorithm when lens controller detects ROI position automatically. Value: 0 - 8192.
AUTO_AF_ROI_HEIGHT	read / write	ROI height (pixels) for autofocus algorithm when lens controller detects ROI position automatically. Value: 0 - 8192.
AUTO_AF_ROI_BORDER	read / write	Video frame border size (along vertical and horizontal axes). Value: 0 - 2048.
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 Slc class.
STABILIZER_MODE	read / write	Not supported by Slc class.
AF_RANGE	read / write	Not supported by Slc class.
X_FOV_DEG	read / write	Not supported by Slc class.
Y_FOV_DEG	read / write	Not supported by Slc 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 Slc 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 Slc class.
CUSTOM_1	read / write	Autofocus ROI preset. Value 0 switches to automatic ROI detection. Positive values specify the centred ROI size as a percentage of the frame. The RapidPixel UI multiplies its value by 10 before transmitting, so a value of 1.0 results in a 10% ROI at the controller.
CUSTOM_2	read / write	Autofocus time adjustment helper passed to AFEngine (-500 - 500 ms).
CUSTOM_3	read / write	Not supported by Slc class.

Slc defaults: When the controller starts, it seeds the key hardware ranges and speeds with tested values: zoomHwWideLimit = 0, zoomHwTeleLimit = 10000, zoomHwMaxSpeed = 128, zoomHwSpeed = 64, focusHwNearLimit = 0, focusHwFarLimit = 10000, focusHwMaxSpeed = 50, focusHwSpeed = 25, and afHwSpeed = 5. Iris-related parameters remain 0 because the hardware used with Slc does not expose iris control. The automatic ROI is initialised to autoAfRoiWidth = 150, autoAfRoiHeight = 150, and autoAfRoiBorder = 100. These runtime defaults override the generic interface defaults shown in the tables above.

LensParams class description

The LensParams class is used to initialise the controller (via initLens(…)) and to retrieve the current configuration (via getParams(…)). It also exposes JSON serialization helpers through the JSON_READABLE macro and dedicated encode/decode methods.

LensParams class declaration

The interface is declared in Lens.h. The excerpt below shows the most relevant fields:

/// 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 maximum and minimum 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};
    /// Autofocus ROI preset helper. Value 0 enables automatic ROI detection.
    /// Positive values describe the centred ROI size as a percentage of the
    /// frame. The RapidPixel UI multiplies the slider value by 10 before
    /// sending it to the controller, so a UI value of 1.0 becomes a 10% ROI.
    float custom1{0.0f};
    /// Autofocus time adjustment helper forwarded to AFEngine. Valid range:
    /// -500..500.
    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)

    /// 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 the full serial port name. Example: “/dev/ttyUSB0”. Parts after “;” (baud rate, timeout) are ignored by Slc: the baud rate is always 115200.
zoomPos	int	Zoom position 0 (full wide) - 65535 (full tele).
zoomHwPos	int	Hardware zoom position 0 (full wide) - 10000 (full tele) by default.
focusPos	int	Focus position 0 (full near) - 65535 (full far).
focusHwPos	int	Hardware focus position 0 (full near) - 10000 (full far) by default.
irisPos	int	Not supported by Slc class.
irisHwPos	int	Not supported by Slc class.
focusMode	int	Focus mode: 0 - Manual focus control. 1 - Push auto focus mode. 2 - Continuous auto focus mode.
filterMode	int	Not supported by Slc class.
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 zoomHwMaxSpeed.
zoomHwMaxSpeed	int	Maximum zoom hardware speed. Default value 128.
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. Default value 50.
irisSpeed	int	Not supported by Slc class.
irisHwSpeed	int	Not supported by Slc class.
irisHwMaxSpeed	int	Not supported by Slc class.
zoomHwTeleLimit	int	Zoom hardware tele limit. Default value 10000.
zoomHwWideLimit	int	Zoom hardware wide limit. Default value 0.
focusHwFarLimit	int	Focus hardware far limit. Default value 10000.
focusHwNearLimit	int	Focus hardware near limit. Default value 0.
irisHwOpenLimit	int	Not supported by Slc class.
irisHwCloseLimit	int	Not supported by Slc 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. Default value 5.
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 Slc class.
autoAfRoiWidth	int	ROI width (pixels) for autofocus algorithm when lens controller detects ROI position automatically. Value: 0 - 8192.
autoAfRoiHeight	int	ROI height (pixels) for autofocus algorithm when lens controller detects ROI position automatically. Value: 0 - 8192.
autoAfRoiBorder	int	Video frame border size (along vertical and horizontal axes). Value: 0 - 2048.
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 Slc class.
stabiliserMode	int	Not supported by Slc class.
afRange	int	Not supported by Slc class.
xFovDeg	float	Not supported by Slc class.
yFovDeg	float	Not supported by Slc class.
logMode	int	Logging mode. Values: 0 - Disable. 1 - Only file. 2 - Only terminal. 3 - File and terminal.
temperature	float	Not supported by Slc 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 Slc class.
custom1	float	Autofocus ROI preset helper. 0 enables automatic ROI detection. Positive values specify the centred ROI size in percent. The RapidPixel multiplies its value by 10 before transmitting, so a value of 1.0 becomes a 10% ROI at the controller.
custom2	float	Autofocus time adjustment helper forwarded to AFEngine. Valid range: -500 - 500 ms.
custom3	float	Not supported by Slc 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 the encode(…) helper to serialise parameters for transport. The method skips the initString and fovPoints fields and can optionally omit additional parameters through a mask. Internally the encoder writes a 7-byte bitmask so decode(…) can recover which fields are present. Method declaration:

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

Parameter	Value
data	Pointer to the destination buffer.
size	Receives the number of bytes written.
bufferSize	Size of the destination buffer. Must be ≥ 201 bytes.
mask	Optional pointer to a LensParamsMask structure that disables individual fields before encoding.

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{true};
    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, 1024, size))
{
    std::cout << "Can't encode params" << 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, 1024, size, &mask))
{
    std::cout << "Can't encode params" << std::endl;
    return false;
}
std::cout << "Encoded data size: " << size << " bytes" << std::endl;

Deserialize lens params

The LensParams class provides the decode(…) method to restore parameters from a binary buffer. Use it when you receive serialized parameters over a communication channel. The method recognises which fields were present in the encoded stream and skips 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 the data was deserialized successfully, otherwise false.

Example:

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

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

Read and write lens params to JSON file

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

// Prepare params.
rapidpixel::LensParams in;
in.initString = "/dev/ttyUSB0";
in.logMode = 3;
for (int i = 1; i <= 2; ++i)
{
    rapidpixel::FovPoint pt;
    pt.hwZoomPos = 100 * i;
    pt.xFovDeg = 10.0f / static_cast<float>(i);
    pt.yFovDeg = 8.0f / static_cast<float>(i);
    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": {
        "initString": "/dev/ttyUSB0",
        "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": 3,
        "type": 0,
        "custom1": 0.0,
        "custom2": 0.0,
        "custom3": 0.0,
        "fovPoints": [
            {
                "hwZoomPos": 100,
                "xFovDeg": 10.0,
                "yFovDeg": 8.0
            },
            {
                "hwZoomPos": 200,
                "xFovDeg": 5.0,
                "yFovDeg": 4.0
            }
        ]
    }
}

Build and connect to your project

Build stand alone

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

<work folder>
    Slc
    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 <Slc 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 Slc
mkdir build
cd build
cmake ..
make

On Windows use cmake --build . --config Release instead of make. If Slc 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.

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

CMake options

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

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

Connect to your project

If you want to connect Slc library to your CMake project as source code, add the repositories of Slc and of the other libraries it depends on to your repository as sub-repositories. Slc does not add these libraries when it is included in another project: your project must add them (CMake resolves the targets by name, so they can be added before or after Slc). If your project does not add them the build stops with a compiler error like AFEngine.h: No such file or directory. 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 Slc repository and of the repositories of its dependencies there. New structure of your repository:

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

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_SLC                             ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_SLC)
    SET(${PARENT}_SLC                                   ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_SLC_TEST                              OFF CACHE BOOL "" FORCE)
    SET(${PARENT}_SLC_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_SLC)
    add_subdirectory(Slc)
endif()

File 3rdparty/CMakeLists.txt adds the folders of the libraries and of Slc to your project (the dependencies in order of their mutual dependencies, Slc at the end) and excludes test applications and examples from compiling (by default test application is excluded from compiling if Slc is included as sub-repository). The new structure of your repository:

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

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

target_link_libraries(${PROJECT_NAME} Slc)

Done!

Portability

The library is written in standard C++17 (compiler extensions are disabled) and does not contain platform specific code: the platform dependent part is the serial port library. The library is built without compiler warnings with GCC 12 and 13 and Clang 15 and 18 on Linux x86-64, with the cross compilers for Linux aarch64 and with MSVC 2022 on Windows (x64). The library does not use SIMD instructions. The Stingray protocol is a text protocol, so it does not depend on the byte order. Commands encoded by Lens::encodeCommand(…) and Lens::encodeSetParamCommand(…) and params encoded by LensParams::encode(…) store int and float values in the byte order of the host: the control system and the lens controller must have the same byte order.

Simple example

A simple application shows how to use the Slc library. The application opens the lens, sets the zoom speed, moves the zoom to the full tele position and prints the zoom position for 5 seconds.

#include <chrono>
#include <iostream>
#include <memory>
#include <string>
#include <thread>
#include "Lens.h"
#include "Slc.h"



namespace
{
/// Zoom speed, percent of the maximum speed.
constexpr float ZOOM_SPEED{10.0f};
/// Full tele zoom position.
constexpr float ZOOM_FULL_TELE{65535.0f};
/// Number of the zoom position prints.
constexpr int PRINT_NUMBER{50};
/// Period of the zoom position prints.
constexpr std::chrono::milliseconds PRINT_PERIOD{100};
}



int main()
{
    // Init lens controller.
    std::unique_ptr<rapidpixel::Lens> lens = std::make_unique<rapidpixel::Slc>();
    if (!lens->openLens("/dev/ttyUSB0"))
    {
        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, ZOOM_SPEED))
    {
        std::cout << "Can't set the zoom speed" << std::endl;
        return 1;
    }

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

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

    // Close the lens controller.
    lens->closeLens();

    return 0;
}

Test application

Slc/test folder contains a test application which allows to control a lens from the terminal. The application does not use video, does not show any user interface and does not depend on libraries other than Slc. Command line:

SlcTest [serial port name]

If the serial port name is not set in the command line the application asks for it. The application opens the lens (the library prints its errors to the terminal) and shows the menu:

1. Set lens param - the application shows the list of params, asks for the param ID and for the value (the valid values are shown, see also Table 3).

2. Get lens param - the application shows the list of params, asks for the param ID and prints the value of the param.

3. Show all lens params - the application prints the values of all params.

4. Execute lens command - the application shows the list of commands and asks for the command ID (and for the argument of ZOOM_TO_POS and FOCUS_TO_POS):

   ZOOM_TELE - move zoom tele. ZOOM_WIDE - move zoom wide. ZOOM_TO_POS - move zoom to the position 0 (full wide) - 65535 (full tele). ZOOM_STOP - stop zoom moving. FOCUS_FAR - move focus far. FOCUS_NEAR - move focus near. FOCUS_TO_POS - move focus to the position 0 (full near) - 65535 (full far). FOCUS_STOP - stop focus moving. RESTART - restart the lens.

5. Exit - close the lens and exit.

The autofocus commands (AF_START, AF_STOP) are not offered, because the application does not give video frames to the autofocus engine. An invalid input is rejected with an error message. If the input is closed (end of file) the application closes the lens and exits. The exit code is 0 after the exit from the menu and 1 if the lens can’t be opened.

---

Table of contents