viscacamera_web_logo

ViscaCamera C++ library

v1.2.5

Table of contents

Overview

The ViscaCamera C++ library is a software controller for VISCA (Trademark of Sony Corporation) compatible cameras and includes camera, lens, and pan-tilt control interfaces. The ViscaCamera library inherits from the Lens, Camera and PanTilt interfaces, so the library has a set of three different interfaces to control camera, lens, and pan-tilt. It depends on libraries: Lens (provides interface and data structures to control lenses), PanTilt (provides interface and data structures to control pan-tilt units), Camera (provides interface and data structures to control cameras), Logger (provides functions to print logs), SerialPort (provides functions to work with serial ports) and ViscaParser library (provides functions to encode control commands and decode responses from VISCA-compatible cameras). The ViscaCamera library provides a simple interface to be integrated into any C++ projects. The library repository (folder) is provided as source code. The libraries listed above (and the libraries they depend on) are separate repositories, see Build and connect to your project; no other third-party dependencies have to be installed in the OS. It is developed with the C++17 standard and is compatible with Linux and Windows.

ViscaCamera 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 VISCA compatible cameras.

Versions

Table 1 - Library versions.

Version Release date What’s new
1.0.0 21.02.2024 - First version of the library.
1.0.1 22.04.2024 - Documentation update.
1.0.2 24.05.2024 - Documentation update.
- Submodules updated.
1.0.3 07.08.2024 - CMake structure updated.
1.0.4 03.04.2025 - Logger submodule update.
1.0.5 15.07.2025 - Fix focus position report.
1.0.6 17.07.2025 - Fix focus position control accuracy.
1.1.0 19.09.2025 - Fix proper parameters control and conversion.
1.1.1 25.10.2025 - Fix code mistakes.
- ViscaParser submodule update.
- SerialPort submodule update.
1.2.0 22.05.2026 - Fix contrast calculation.
- Fix logs output.
- Fix iris priority mode.
- Add reporting of current exposure time and gain level.
- Improve test application.
- Fix init parameters.
- Fix documentation.
- Add SHARPENING_MODE support to getParam.
- Add priority for zoom and focus commands.
- Fix camera filter.
1.2.1 26.05.2026 - Fix initialization.
- Fix shutter speed synchronization.
1.2.2 08.06.2026 - Fix camera responses decoding.
1.2.3 23.07.2026 - Fix setting CHROMA_LEVEL.
- Update ViscaParser library to 3.0.7.
1.2.4 19.10.2026 - Git submodules removed: the dependencies are taken from sibling folders.
- Strict warnings and exploit mitigation options in the CMake files, standard C++ only.
- NaN, infinity and out-of-range values are rejected (undefined behavior fixed).
- Fix ZOOM_HW_WIDE_LIMIT range check.
- Fix FOCUS_FACTOR_THRESHOLD value 100.
- Rejected SHUTTER_MODE value is not stored.
- Check baudrate and camera address of the init string.
- Fix division by zero in the processing of the zoom and focus positions.
- decodeAndExecuteCommand(…) rejects nullptr.
- Thread-safe open and close, no busy loop of the communication thread after a failure.
- Test application: automatic tests, bounded input.
- Fix example and documentation.
1.2.5 25.10.2026 - The library links the thread library (CMake target Threads::Threads): programs built on a C library older than glibc 2.34 no longer need -pthread.

Library files

The library is provided as source code only. Users are given a set of files in the form of a CMake project (repository). The libraries which ViscaCamera depends on are separate repositories (see Build and connect to your project). The repository structure is outlined below:

CMakeLists.txt --------------- Main CMake file of the library.
src -------------------------- Folder with source code of the library.
    CMakeLists.txt ----------- CMake file of the library.
    ViscaCamera.cpp ---------- Source code file of the library.
    ViscaCamera.h ------------ Header file which includes ViscaCamera class declaration.
    ViscaCameraVersion.h ----- Header file which includes version of the library.
    ViscaCameraVersion.h.in -- CMake service file to generate version file.
test ------------------------- Folder with test application.
    CMakeLists.txt ----------- CMake file for test application.
    main.cpp ----------------- Source code file of test application.
example ---------------------- Folder with example application.
    CMakeLists.txt ----------- CMake file for example application.
    main.cpp ----------------- Source code file of example application.
static ----------------------- Folder with images of the documentation.
    viscacamera_web_logo.png - Logo of the library.

ViscaCamera class description

ViscaCamera class declaration

ViscaCamera class declared in ViscaCamera.h file. The ViscaCamera class includes Lens, Camera and PanTilt interfaces. Class declaration:

class ViscaCamera : public rapidpixel::Camera,
                    public rapidpixel::Lens,
                    public rapidpixel::PanTilt
{
public:

    /// Class constructor.
    ViscaCamera();

    /// Class destructor. Stops the communication thread and closes the serial port.
    ~ViscaCamera() override;

    /// Copying and moving are not supported.
    ViscaCamera(const ViscaCamera&) = delete;
    ViscaCamera(ViscaCamera&&) = delete;
    ViscaCamera& operator=(const ViscaCamera&) = delete;
    ViscaCamera& operator=(ViscaCamera&&) = delete;

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

    // #######################################
    // CAMERA CONTROL INTERFACE
    // #######################################

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

    /// Init camera by parameters structure.
    bool initCamera(rapidpixel::CameraParams& params) override;

    /// Method closes serial port and stops the communication thread.
    void closeCamera() override;

    /// Get serial port status.
    bool isCameraOpen() override;

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

    /// Set the camera parameter.
    bool setParam(rapidpixel::CameraParam id, float value) override;

    /// Get the camera parameter.
    float getParam(rapidpixel::CameraParam id) override;

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

    /// Execute camera command.
    bool executeCommand(rapidpixel::CameraCommand id) override;

    // #######################################
    // LENS CONTROL INTERFACE
    // #######################################

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

    /// Init lens by parameters structure.
    bool initLens(rapidpixel::LensParams& params) override;

    /// Closes serial port and stops the communication thread.
    void closeLens() override;

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

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

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

    /// Get lens parameter.
    float getParam(rapidpixel::LensParam id) override;

    /// Get the lens parameters.
    void getParams(rapidpixel::LensParams& params) override;

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

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

    // #######################################
    // PANTILT CONTROL INTERFACE
    // #######################################

    /// Open pan-tilt device.
    bool openPanTilt(std::string initString) override;

    /// Init pan-tilt device with parameters structure.
    bool initPanTilt(rapidpixel::PanTiltParams& params) override;

    /// Close pan-tilt controller connection.
    void closePanTilt() override;

    /// Get pan-tilt controller is initialized status.
    bool isPanTiltOpen() override;

    /// Get pan-tilt controller is connected status.
    bool isPanTiltConnected() override;

    /// Set the value for a specific library parameter.
    bool setParam(rapidpixel::PanTiltParam id, float value) override;

    /// Get the value of a specific library parameter.
    float getParam(rapidpixel::PanTiltParam id) override;

    /// Get the structure containing all library parameters.
    void getParams(rapidpixel::PanTiltParams& params) override;

    /// Execute a PanTilt command.
    bool executeCommand(rapidpixel::PanTiltCommand id,
                        float arg1 = 0.0f, float arg2 = 0.0f) override;

    // #######################################
    // LENS & CAMERA & PAN-TILT CONTROL INTERFACE
    // #######################################

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

getVersion method

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

static std::string getVersion();

Method can be used without ViscaCamera class instance:

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

Console output:

ViscaCamera class version: 1.2.5

openLens method

The openLens(…) opens a serial port and starts the communication thread to communicate with VISCA-based devices. To initialize the serial port the user can call openCamera(…), openLens(…) or openPanTilt(…) (no matter which one). If the serial port is already open the method returns TRUE and does nothing. Camera, lens, and pan-tilt parameters will be initialized with default values. The method does not wait for the answer of the camera: use isCameraConnected() to check if the camera answers. The method is thread-safe. Method declaration:

bool openLens(std::string initString) override;
Parameter Value
initString Initialization string. Format: “[serial port name];[baudrate];[camera address]”, the camera address is optional: “[serial port name];[baudrate]” is valid. The baudrate is an integer from 1 to 10000000. The camera address is an integer from 1 to 7, it is 1 if the address is not given. Empty parts of the string are skipped, parts after the camera address are ignored. Recommended initialization string format for controllers, which use serial port: “/dev/ttyUSB0;9600;1”.

Returns: TRUE if the controller is initialized (the serial port is open) or FALSE if the initialization string is not valid or the serial port cannot be opened.

openCamera method

The openCamera(…) opens a serial port and starts the communication thread to communicate with VISCA-based devices. To initialize the serial port the user can call openCamera(…), openLens(…) or openPanTilt(…) (no matter which one). If the serial port is already open the method returns TRUE and does nothing. Camera, lens, and pan-tilt parameters will be initialized with default values. The method does not wait for the answer of the camera: use isCameraConnected() to check if the camera answers. The method is thread-safe. Method declaration:

bool openCamera(std::string initString) override;
Parameter Value
initString Initialization string. Format: “[serial port name];[baudrate];[camera address]”, the camera address is optional: “[serial port name];[baudrate]” is valid. The baudrate is an integer from 1 to 10000000. The camera address is an integer from 1 to 7, it is 1 if the address is not given. Empty parts of the string are skipped, parts after the camera address are ignored. Recommended initialization string format for controllers, which use serial port: “/dev/ttyUSB0;9600;1”.

Returns: TRUE if the controller is initialized (the serial port is open) or FALSE if the initialization string is not valid or the serial port cannot be opened.

openPanTilt method

The openPanTilt(…) opens a serial port and starts the communication thread to communicate with VISCA-based devices. To initialize the serial port the user can call openCamera(…), openLens(…) or openPanTilt(…) (no matter which one). If the serial port is already open the method returns TRUE and does nothing. Camera, lens, and pan-tilt parameters will be initialized with default values. The method does not wait for the answer of the camera: use isCameraConnected() to check if the camera answers. The method is thread-safe. Method declaration:

bool openPanTilt(std::string initString) override;
Parameter Value
initString Initialization string. Format: “[serial port name];[baudrate];[camera address]”, the camera address is optional: “[serial port name];[baudrate]” is valid. The baudrate is an integer from 1 to 10000000. The camera address is an integer from 1 to 7, it is 1 if the address is not given. Empty parts of the string are skipped, parts after the camera address are ignored. Recommended initialization string format for controllers, which use serial port: “/dev/ttyUSB0;9600;1”.

Returns: TRUE if the controller is initialized (the serial port is open) or FALSE if the initialization string is not valid or the serial port cannot be opened.

initLens method

The initLens(…) initializes the controller and sets lens parameters (Lens interface). The method calls the openLens(…) method with the initString of the given parameters and, if the controller is open, sets the given parameters with setParam(…). A value which is rejected by setParam(…) is skipped, it does not change the result of the method. The parameters are sent to the camera when the camera answers. Camera and PanTilt parameters will be initialized by default. After successful initialization the library runs the communication thread (the thread to communicate with equipment via serial port) if it was not run before. Method declaration:

bool initLens(rapidpixel::LensParams& params) override;
Parameter Value
params LensParams class object. LensParams class includes initString, which is used in the openLens(…) method.

Returns: TRUE if the controller is initialized or FALSE if it is not (see openLens(…)).

initCamera method

The initCamera(…) initializes the controller and sets camera parameters (Camera interface). The method calls the openCamera(…) method with the initString of the given parameters and, if the controller is open, sets the given parameters with setParam(…). A value which is rejected by setParam(…) is skipped, it does not change the result of the method. The parameters are sent to the camera when the camera answers. Lens and PanTilt parameters will be initialized by default. After successful initialization the library runs the communication thread (the thread to communicate with equipment via serial port) if it was not run before. Method declaration:

bool initCamera(rapidpixel::CameraParams& params) override;
Parameter Value
params CameraParams class object. CameraParams class includes initString, which is used in the openCamera(…) method.

Returns: TRUE if the controller is initialized or FALSE if it is not (see openCamera(…)).

initPanTilt method

The initPanTilt(…) initializes the controller and sets pan-tilt parameters (PanTilt interface). The method calls the openPanTilt(…) method with the initString of the given parameters and, if the controller is open, sets the given parameters with setParam(…). A value which is rejected by setParam(…) is skipped, it does not change the result of the method. The parameters are sent to the camera when the camera answers. Camera and Lens parameters will be initialized by default. After successful initialization the library runs the communication thread (the thread to communicate with equipment via serial port) if it was not run before. Method declaration:

bool initPanTilt(rapidpixel::PanTiltParams& params) override;
Parameter Value
params PanTiltParams class object. PanTiltParams class includes initString, which is used in the openPanTilt(…) method.

Returns: TRUE if the controller is initialized or FALSE if it is not (see openPanTilt(…)).

closeLens method

The closeLens() stops the communication thread, closes the serial port and resets the open and connection status of the camera, lens and pan-tilt interfaces. The method does nothing if the controller is not open. The result of the method is equal to closeCamera() or closePanTilt() method (user can use any of them). The method is thread-safe. Method declaration:

void closeLens() override;

closeCamera method

The closeCamera() stops the communication thread, closes the serial port and resets the open and connection status of the camera, lens and pan-tilt interfaces. The method does nothing if the controller is not open. The result of the method is equal to closeLens() or closePanTilt() method (user can use any of them). The method is thread-safe. Method declaration:

void closeCamera() override;

closePanTilt method

The closePanTilt() stops the communication thread, closes the serial port and resets the open and connection status of the camera, lens and pan-tilt interfaces. The method does nothing if the controller is not open. The result of the method is equal to closeLens() or closeCamera() method (user can use any of them). The method is thread-safe. Method declaration:

void closePanTilt() override;

isLensOpen method

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

bool isLensOpen() override;

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

isCameraOpen method

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

bool isCameraOpen() override;

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

isPanTiltOpen method

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

bool isPanTiltOpen() override;

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

isLensConnected method

The isLensConnected() shows if the controller receives responses from equipment (camera). For example, if serial port open but equipment not active (no power). In this case methods isLensOpen(), isCameraOpen() and isPanTiltOpen() methods will return TRUE but isLensConnected() method will return FALSE. This method is equal to isCameraConnected() and isPanTiltConnected() methods (user can use any of them). Method declaration:

bool isLensConnected() override;

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

isCameraConnected method

The isCameraConnected() shows if the controller receives responses from equipment (camera). For example, if serial port open but equipment not active (no power). In this case methods isLensOpen(), isCameraOpen() and isPanTiltOpen() methods will return TRUE but isCameraConnected() method will return FALSE. This method is equal to isLensConnected() and isPanTiltConnected() methods (user can use any of them). Method declaration:

bool isCameraConnected() override;

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

isPanTiltConnected method

The isPanTiltConnected() shows if the controller receives responses from equipment (camera). For example, if serial port open but equipment not active (no power). In this case methods isLensOpen(), isCameraOpen() and isPanTiltOpen() methods will return TRUE but isPanTiltConnected() method will return FALSE. This method is equal to isLensConnected() and isCameraConnected() methods (user can use any of them). Method declaration:

bool isPanTiltConnected() override;

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

setParam method

The setParam(…) is overloaded method. The method intended to set Camera, Lens or PanTilt parameter value. The method checks the value and adds a command to the queue of commands (the queue holds up to 64 commands, the oldest command is dropped if the queue is full). The communication thread sends the commands to the camera one by one. Zoom and focus movement commands (setting of ZOOM_POS, ZOOM_HW_POS, FOCUS_POS and FOCUS_HW_POS) are kept in separate slots (a new command replaces the command of the slot if it is not sent yet) and are sent before other commands. The method does not wait for the execution of the command. The method can be called when the controller is not open: the commands are sent after the connection is established. The method is thread-safe. Method declaration:

bool setParam(rapidpixel::LensParam id, float value) override;
bool setParam(rapidpixel::CameraParam id, float value) override;
bool setParam(rapidpixel::PanTiltParam id, float value) override;
Parameter Description
id Lens parameter ID according to LensParam, camera parameter ID according to CameraParam or pan-tilt parameter ID according to PanTiltParam
value Parameter value. Valid values depend on parameter ID (see the tables of the parameters). A value which is not a number (NaN), an infinity or a value outside of the range of the parameter is rejected. The fractional part of the value of an integer parameter is dropped.

Returns: TRUE if the parameter is set (the command is queued) or FALSE if the parameter is not supported or the value is not valid. If FALSE is returned no command is sent to the camera and the stored parameters are not changed. The exception is setting of LensParam::IRIS_POS and LensParam::IRIS_HW_POS: the camera is switched to the iris priority mode before the value is checked.

getParam method

The getParam(…) is overloaded method. The method intended to obtain Camera, Lens or PanTilt parameter value. The value is taken from the stored parameters: it is the last value set by setParam(…) or the last value reported by the camera, see the tables of the parameters. The method is thread-safe. Method declaration:

float getParam(rapidpixel::LensParam id) override;
float getParam(rapidpixel::CameraParam id) override;
float getParam(rapidpixel::PanTiltParam id) override;
Parameter Description
id Lens parameter ID according to LensParam, camera parameter ID according to CameraParam or pan-tilt parameter ID according to PanTiltParam.

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

getParams method

The getParams(…) is overloaded method. The method intended to obtain Camera, Lens or PanTilt parameters structure (a copy of all stored parameters). The method is thread-safe. Method declaration:

void getParams(rapidpixel::LensParams& params) override;
void getParams(rapidpixel::CameraParams& params) override;
void getParams(rapidpixel::PanTiltParams& params) override;
Parameter Description
params Reference to LensParams class object, CameraParams class object or PanTiltParams class object.

executeCommand method

The executeCommand(…) is overloaded method. The method intended to execute Camera, Lens or PanTilt action command. The method checks the argument and adds a command to the queue of commands in the same way as setParam(…) (zoom and focus movement commands have priority, see the tables of the commands). The method does not wait for the execution of the command. The method is thread-safe. Method declaration:

bool executeCommand(rapidpixel::LensCommand id, float arg = 0) override;
bool executeCommand(rapidpixel::CameraCommand id) override;
bool executeCommand(rapidpixel::PanTiltCommand id, float arg1 = 0, float arg2 = 0) override;
Parameter Description
id Camera command ID according to CameraCommand, lens command ID according to LensCommand or pan-tilt command ID according to PanTiltCommand.
arg Only for lens interface. Lens command argument. Valid values depend on command ID. A command that uses the argument rejects NaN, infinity and a value outside of the range.
arg1 Only for pan-tilt interface. PanTilt command argument. Valid values depend on command ID.
arg2 Only for pan-tilt interface. PanTilt command argument. Valid values depend on command ID.

Returns: TRUE if the command is accepted (queued) or FALSE if the command is not supported or an argument is not valid. If FALSE is returned no command is sent to the camera. The exception is LensCommand::IRIS_TO_POS: the camera is switched to the iris priority mode before the argument is checked.

addVideoFrame method

The addVideoFrame(…) copies video frame data to the lens controller to perform autofocus algorithm. It is not supported by ViscaCamera. Method declaration:

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

decodeAndExecuteCommand method

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

bool decodeAndExecuteCommand(uint8_t* data, int size) override;
Parameter Description
data Pointer to input command. Must not be nullptr. The buffer must be valid for size bytes.
size Size of command, bytes. It must be the size of the encoded command: 11 bytes for a SET_PARAM command of all interfaces, 11 bytes for a lens COMMAND, 7 bytes for a camera COMMAND and 15 bytes for a pan-tilt COMMAND. Data of another size is rejected.

Returns: TRUE if command decoded (SET_PARAM or COMMAND) and executed (action command or set param command) or FALSE if data is nullptr, the data is not a valid command or the command was rejected by setParam(…) or executeCommand(…).

Data structures

LensCommand enum

Enum declaration:

enum class LensCommand
{
    /// Move zoom tele (in).
    ZOOM_TELE = 1,
    /// Move zoom wide (out).
    ZOOM_WIDE,
    /// Move zoom to position.
    ZOOM_TO_POS,
    /// Stop zoom moving including stop zoom to position command.
    ZOOM_STOP,
    /// Move focus far.
    FOCUS_FAR,
    /// Move focus near.
    FOCUS_NEAR,
    /// Move focus to position.
    FOCUS_TO_POS,
    /// Stop focus moving including stop focus to position command.
    FOCUS_STOP,
    /// Move iris open.
    IRIS_OPEN,
    /// Move iris close.
    IRIS_CLOSE,
    /// Move iris to position.
    IRIS_TO_POS,
    /// Stop iris moving including stop iris to position command.
    IRIS_STOP,
    /// Start autofocus.
    AF_START,
    /// Stop autofocus.
    AF_STOP,
    /// Restart lens controller.
    RESTART,
    /// Detect zoom and focus hardware ranges.
    DETECT_HW_RANGES
};

Table 2 - Lens commands description.

Command Description
ZOOM_TELE Move zoom tele (in). Command doesn’t have arguments. User can set zoom movement speed via lens parameters.
The command has priority.
ZOOM_WIDE Move zoom wide (out). Command doesn’t have arguments. User can set zoom movement speed via lens parameters. The command is accepted but does nothing while the wide limit of the zoom is reached.
The command has priority.
ZOOM_TO_POS Move zoom to position. Controller has zoom range from 0 (full wide) to 65535 (full tele) regardless of the hardware value of the zoom position. Valid values of the argument: 0 - 65535. The zoom speed is not used.
The command has priority.
ZOOM_STOP Stop zoom moving including stop zoom to position command.
The command has priority.
FOCUS_FAR Move focus far. Command doesn’t have arguments. User can set focus movement speed via lens parameters.
The command has priority.
FOCUS_NEAR Move focus near. Command doesn’t have arguments. User can set focus movement speed via lens parameters.
The command has priority.
FOCUS_TO_POS Move focus to position. Controller has focus range from 0 (full near) to 65535 (full far) regardless of the hardware value of the focus position. Valid values of the argument: 0 - 65535. The focus speed is not used.
The command has priority.
FOCUS_STOP Stop focus moving including stop focus to position command.
The command has priority.
IRIS_OPEN Move iris one step up (more open). Command doesn’t have arguments.
Has effect only when the camera exposure mode is Manual or Iris Priority; otherwise, the camera will switch to Iris Priority mode.
IRIS_CLOSE Move iris one step down (more closed). Command doesn’t have arguments.
Has effect only when the camera exposure mode is Manual or Iris Priority; otherwise, the camera will switch to Iris Priority mode.
IRIS_TO_POS Move iris to position. Valid values of the argument: 0 or 5 - 17. User can set the iris to position n selected from the list below (mapping: n — F):
17 — F1.6
16 — F2
15 — F2.4
14 — F2.8
13 — F3.4
12 — F4
11 — F4.8
10 — F5.6
9 — F6.8
8 — F8
7 — F9.6
6 — F11
5 — F14
0 — CLOSE
Has effect only when the camera exposure mode is Manual or Iris Priority; otherwise, the camera will switch to Iris Priority mode.
IRIS_STOP Reset iris position.
Has effect only when the camera exposure mode is Manual or Iris Priority; otherwise, the camera will switch to Iris Priority mode.
AF_START Start autofocus. Command doesn’t have arguments.
AF_STOP Stop autofocus, switch to manual focus. Command doesn’t have arguments.
RESTART Not supported by ViscaCamera library.
DETECT_HW_RANGES Not supported by ViscaCamera library.

CameraCommand enum

Enum declaration:

enum class CameraCommand
{
    /// Restart camera controller.
    RESTART = 1,
    /// Do NUC.
    NUC,
    /// Apply settings.
    APPLY_PARAMS,
    /// Save params.
    SAVE_PARAMS,
    /// Menu on.
    MENU_ON,
    /// Menu off.
    MENU_OFF,
    /// Menu set.
    MENU_SET,
    /// Menu up.
    MENU_UP,
    /// Menu down.
    MENU_DOWN,
    /// Menu left.
    MENU_LEFT,
    /// Menu right.
    MENU_RIGHT,
    /// Freeze, Argument: time msec.
    FREEZE,
    /// Disable freeze.
    DEFREEZE
};

Table 3 - Camera commands description.

Command Description
RESTART Not supported by ViscaCamera library.
NUC Not supported by ViscaCamera library.
APPLY_PARAMS Not supported by ViscaCamera library.
SAVE_PARAMS Not supported by ViscaCamera library.
MENU_ON Not supported by ViscaCamera library.
MENU_OFF Not supported by ViscaCamera library.
MENU_SET Not supported by ViscaCamera library.
MENU_UP Not supported by ViscaCamera library.
MENU_DOWN Not supported by ViscaCamera library.
MENU_LEFT Not supported by ViscaCamera library.
MENU_RIGHT Not supported by ViscaCamera library.
FREEZE Run camera freeze on. Command doesn’t have arguments.
DEFREEZE Run camera defreeze on. Command doesn’t have arguments.

PanTiltCommand enum

Enum declaration:

enum class PanTiltCommand
{
    /// Restart Pan-Tilt device.
    RESTART = 1,
    /// Stop Pan-Tilt device, block all running commands and left device in current state.
    STOP,
    /// Go to given pan motor position.
    GO_TO_PAN_POSITION,
    /// Go to given tilt motor position.
    GO_TO_TILT_POSITION,
    /// Go to given pan and tilt motor position.
    GO_TO_PAN_TILT_POSITION,
    /// Go to given pan angle.
    GO_TO_PAN_ANGLE,
    /// Go to given tilt angle.
    GO_TO_TILT_ANGLE,
    /// Go to given pan and tilt angle.
    GO_TO_PAN_TILT_ANGLE,
    /// Go to home position.
    GO_TO_HOME,
    /// Move pan motor with given speed. Positive speed is clockwise, 
    /// negative is counterclockwise.
    MOVE_PAN,
    /// Move tilt motor with given speed. Positive speed is clockwise,
    /// negative is counterclockwise.
    MOVE_TILT,
    /// Move pan and tilt motors with given speed. Positive speed is clockwise,
    /// negative is counterclockwise. First argument is pan speed, second is tilt speed.
    MOVE_PAN_TILT
};

Table 4 - Commands description.

Command Description
RESTART Not supported by ViscaCamera library.
STOP Not supported by ViscaCamera library.
GO_TO_PAN_POSITION Not supported by ViscaCamera library.
GO_TO_TILT_POSITION Not supported by ViscaCamera library.
GO_TO_PAN_TILT_POSITION Not supported by ViscaCamera library.
GO_TO_PAN_ANGLE Not supported by ViscaCamera library.
GO_TO_TILT_ANGLE Not supported by ViscaCamera library.
GO_TO_PAN_TILT_ANGLE Go to given pan and tilt angle. Valid values from -180.0° to 180.0°. Command accepts two arguments, first one defines pan angle and second one tilt angle. If one of the angles is not valid the command is rejected and the angles are not changed.
MOVE_PAN Not supported by ViscaCamera library.
MOVE_TILT Not supported by ViscaCamera library.
MOVE_PAN_TILT Not supported by ViscaCamera library.
GO_TO_HOME Not supported by ViscaCamera library.

LensParam enum

Enum declaration:

enum class LensParam
{
    /// Zoom position.
    ZOOM_POS = 1,
    /// Hardware zoom position.
    ZOOM_HW_POS,
    /// Focus position.
    FOCUS_POS,
    /// Hardware focus position. 
    FOCUS_HW_POS,
    /// Iris position.
    IRIS_POS,
    /// Hardware iris position.
    IRIS_HW_POS,
    /// Focus mode.
    FOCUS_MODE,
    /// Filter mode.
    FILTER_MODE,
    /// Autofocus ROI top-left corner horizontal position in pixels.
    AF_ROI_X0,
    /// Autofocus ROI top-left corner vertical position in pixels.
    AF_ROI_Y0,
    /// Autofocus ROI bottom-right corner horizontal position in pixels.
    AF_ROI_X1,
    /// Autofocus ROI bottom-right corner vertical position in pixels.
    AF_ROI_Y1,
    /// Zoom speed.
    ZOOM_SPEED,
    /// Zoom hardware speed. 
    ZOOM_HW_SPEED,
    /// Maximum zoom hardware speed. 
    ZOOM_HW_MAX_SPEED,
    /// Focus speed.
    FOCUS_SPEED,
    /// Focus hardware speed. 
    FOCUS_HW_SPEED,
    /// Maximum focus hardware speed. 
    FOCUS_HW_MAX_SPEED,
    /// Iris speed.
    IRIS_SPEED,
    /// Iris hardware speed. 
    IRIS_HW_SPEED,
    /// Maximum iris hardware speed. 
    IRIS_HW_MAX_SPEED,
    /// Zoom hardware tele limit. 
    ZOOM_HW_TELE_LIMIT,
    /// Zoom hardware wide limit. 
    ZOOM_HW_WIDE_LIMIT,
    /// Focus hardware far limit. 
    FOCUS_HW_FAR_LIMIT,
    /// Focus hardware near limit. 
    FOCUS_HW_NEAR_LIMIT,
    /// Iris hardware open limit.
    IRIS_HW_OPEN_LIMIT,
    /// Iris hardware close limit.
    IRIS_HW_CLOSE_LIMIT,
    /// Focus factor if it was calculated.
    FOCUS_FACTOR,
    /// Lens connection status.
    IS_CONNECTED,
    /// Focus hardware speed in autofocus mode. 
    FOCUS_HW_AF_SPEED,
    /// Threshold for changes of focus factor to start refocus.
    FOCUS_FACTOR_THRESHOLD,
    /// Timeout for automatic refocus in seconds.
    REFOCUS_TIMEOUT_SEC,
    /// Flag about active autofocus algorithm.
    AF_IS_ACTIVE,
    /// Iris mode.
    IRIS_MODE,
    /// ROI width (pixels).
    AUTO_AF_ROI_WIDTH,
    /// ROI height (pixels).
    AUTO_AF_ROI_HEIGHT,
    /// Video frame border size (along vertical and horizontal axes).
    AUTO_AF_ROI_BORDER,
    /// AF ROI mode (write/read). Value: 0 - Manual position, 1 - Auto position.
    AF_ROI_MODE,
    /// Lens extender mode.
    EXTENDER_MODE,
    /// Lens stabilization mode.
    STABILIZER_MODE,
    /// Autofocus range.
    AF_RANGE,
    /// Current horizontal Field of view, degree.
    X_FOV_DEG,
    /// Current vertical Field of view, degree.
    Y_FOV_DEG,
    /// Logging mode.
    LOG_MODE,
    /// Lens temperature, degree.
    TEMPERATURE,
    /// Lens controller initialization status.
    IS_OPEN,
    /// Lens type.
    TYPE,
    /// Lens custom parameter.
    CUSTOM_1,
    /// Lens custom parameter.
    CUSTOM_2,
    /// Lens custom parameter.
    CUSTOM_3
};

Table 5 - Lens params description.

Parameter Access Description
ZOOM_POS read / write Zoom position. Setting a parameter is equivalent to the command ZOOM_TO_POS. Controller has zoom range from 0 (full wide) to 65535 (full tele) regardless of the hardware value of the zoom position. Valid values: 0 - 65535. The zoom speed is not used. Reading returns the position reported by the camera (0 - 65535).
The command has priority.
ZOOM_HW_POS read / write Hardware zoom position (VISCA zoom position, the zoom range of the camera is 0 - 16384). Valid values to set: 0 - 65535, the value is sent to the camera as it is. Reading returns the hardware position reported by the camera.
The command has priority.
FOCUS_POS read / write Focus position. Setting a parameter is equivalent to the command FOCUS_TO_POS. Controller has focus range from 0 (full near) to 65535 (full far) regardless of the hardware value of the focus position. Valid values: 0 - 65535. The focus speed is not used. Reading returns the position reported by the camera (0 - 65535).
The command has priority.
FOCUS_HW_POS read / write Hardware focus position (VISCA focus position). Valid values to set: 0 - 65535, the value is mapped to the hardware focus range in the same way as for FOCUS_POS. Reading returns the hardware position reported by the camera.
The command has priority.
IRIS_POS read / write Iris position. Setting a parameter is equivalent to the command IRIS_TO_POS. Set the iris to position n selected from the list below (mapping: n — F):
17 — F1.6
16 — F2
15 — F2.4
14 — F2.8
13 — F3.4
12 — F4
11 — F4.8
10 — F5.6
9 — F6.8
8 — F8
7 — F9.6
6 — F11
5 — F14
0 — CLOSE
Can be set only when the camera exposure mode is Manual or Iris Priority; otherwise, the camera will switch to Iris Priority mode (before the value is checked). Reading returns the iris position reported by the camera.
IRIS_HW_POS read / write Hardware iris position. Parameter has the same valid values and the same effect as IRIS_POS parameter.
Can be set only when the camera exposure mode is Manual or Iris Priority; otherwise, the camera will switch to Iris Priority mode (before the value is checked).
FOCUS_MODE read / write Focus mode. Values to set:
0 - Manual
1 - AF ON
Reading returns 0 - Manual, 1 - AF ON (normal), 2 - AF ON (interval), 3 - AF ON (zoom trigger): the autofocus option reported by the camera.
FILTER_MODE read / write ICR (Infrared Cut Removable) filter state. Values:
0 - ICR OFF.
1 - ICR ON.
Setting the parameter is equivalent to setting CameraParam::FILTER_MODE. Reading returns the state reported by the camera.
AF_ROI_X0 read / write Not supported by ViscaCamera library.
AF_ROI_Y0 read / write Not supported by ViscaCamera library.
AF_ROI_X1 read / write Not supported by ViscaCamera library.
AF_ROI_Y1 read / write Not supported by ViscaCamera library.
ZOOM_SPEED read / write Zoom speed in percents of the maximum hardware speed (7). Valid values: 0 - 100. Setting the parameter sets ZOOM_HW_SPEED too. The speed is used by the commands ZOOM_TELE and ZOOM_WIDE.
ZOOM_HW_SPEED read / write Hardware zoom speed (VISCA variable speed). Valid values: 0 - 7. Setting the parameter sets ZOOM_SPEED too.
ZOOM_HW_MAX_SPEED read only Maximum hardware zoom speed, always 7. Setting is not supported.
FOCUS_SPEED read / write Focus speed in percents of the maximum hardware speed (7). Valid values: 0 - 100. Setting the parameter sets FOCUS_HW_SPEED too. The speed is used by the commands FOCUS_FAR and FOCUS_NEAR.
FOCUS_HW_SPEED read / write Hardware focus speed (VISCA variable speed). Valid values: 0 - 7. Setting the parameter sets FOCUS_SPEED too.
FOCUS_HW_MAX_SPEED read only Maximum hardware focus speed, always 7. Setting is not supported.
IRIS_SPEED read / write Not supported by ViscaCamera library.
IRIS_HW_SPEED read / write Not supported by ViscaCamera library.
IRIS_HW_MAX_SPEED read / write Not supported by ViscaCamera library.
ZOOM_HW_TELE_LIMIT read only Hardware tele limit of the zoom, always 65535. Setting is not supported.
ZOOM_HW_WIDE_LIMIT read / write The value of hardware wide zoom limit. It is necessary for proper calculation of zoom movement. Supported values from 0 to 16384.
FOCUS_HW_FAR_LIMIT read only Hardware far limit of the focus, always 65535. Setting is not supported.
FOCUS_HW_NEAR_LIMIT read only Hardware near limit of the focus reported by the camera. It is used to calculate the focus movement. Setting is not supported.
IRIS_HW_OPEN_LIMIT read only Hardware open limit of the iris, always 65535. Setting is not supported.
IRIS_HW_CLOSE_LIMIT read only Hardware close limit of the iris, always 0. Setting is not supported.
FOCUS_FACTOR read only Not supported by ViscaCamera library.
IS_CONNECTED read only Connection status. Connection status shows if the controller has data exchange with equipment. For example, if serial port open but equipment can be not active (no power). In this case connection status shows that controller doesn’t have data exchange with equipment (methods will return 0). If the controller has data exchange with equipment, the method will return 1. If the controller not initialize the connection status always FALSE. Values: 0 - not connected. 1 - connected.
FOCUS_HW_AF_SPEED read / write Not supported by ViscaCamera library.
FOCUS_FACTOR_THRESHOLD read / write Focus factor threshold parameter supports two states. Valid values: 0 - 100:
- value below 50.0 - AutoFocus sensitivity is set to Normal.
- value from 50.0 to 100.0 - AutoFocus sensitivity is set to Low.
Reading returns the last set value.
REFOCUS_TIMEOUT_SEC read / write Set timeout of refocusing in seconds. Supported values between 0 and 255. If value is set to 0 refocus will be off. Reading returns the value reported by the camera.
AF_IS_ACTIVE read only Not supported by ViscaCamera library.
IRIS_MODE read / write Not supported by ViscaCamera library.
AUTO_AF_ROI_WIDTH read / write Not supported by ViscaCamera library.
AUTO_AF_ROI_HEIGHT read / write Not supported by ViscaCamera library.
AUTO_AF_ROI_BORDER read / write Not supported by ViscaCamera library.
AF_ROI_MODE read / write Not supported by ViscaCamera library.
EXTENDER_MODE read / write Not supported by ViscaCamera library.
STABILIZER_MODE read / write Stabilizer mode. Values to set:
0 - OFF
1 - ON
Reading returns 0 - OFF, 1 or 2 - ON (the stabilizer level reported by the camera).
AF_RANGE read / write Not supported by ViscaCamera library.
X_FOV_DEG read only Not supported by ViscaCamera library.
Y_FOV_DEG read only Not supported by ViscaCamera library.
LOG_MODE read / write Logging mode. Values:
0 - Disable,
1 - Only file,
2 - Only terminal (console),
3 - File and terminal.
TEMPERATURE read only Not supported by ViscaCamera library.
IS_OPEN read only Not supported by ViscaCamera library. The method returns -1. Use isLensOpen() to get the initialization status.
TYPE read / write Not supported by ViscaCamera library.
CUSTOM_1 read / write Not supported by ViscaCamera library.
CUSTOM_2 read / write Not supported by ViscaCamera library.
CUSTOM_3 read / write Not supported by ViscaCamera library.

CameraParam enum

Enum declaration:

enum class CameraParam
{
    /// Video frame width. Value from 0 to 16384.
    WIDTH = 1,
    /// Video frame height. Value from 0 to 16384.
    HEIGHT,
    /// Display menu mode. Value depends on implementation but it is recommended
    /// to keep default values: 0 - Off. 1 - On.
    DISPLAY_MODE,
    /// Video output type. Value depends on implementation.
    VIDEO_OUTPUT,
    /// Logging mode. Values: 0 - Disable, 1 - Only file,
    /// 2 - Only terminal (console), 3 - File and terminal.
    LOG_MODE,
    /// Exposure mode. Value depends on implementation but it is recommended to
    /// keep default values: 0 - Manual, 1 - Auto (default),
    /// 2 - Shutter priority, 3 - Aperture priority.
    EXPOSURE_MODE,
    /// Exposure time of the camera sensor in 100 µs units. Supported range:
    /// 0 - 10000 (1 stands for 1/10000 s, 10000 for 1 s). Values are mapped
    /// to the nearest supported VISCA shutter step.
    EXPOSURE_TIME,
    /// White balance mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual, 1 - Auto.
    WHITE_BALANCE_MODE,
    /// White balance area. Value depends on implementation.
    WHITE_BALANCE_AREA,
    /// White dynamic range mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Off, 1 - On.
    WIDE_DYNAMIC_RANGE_MODE,
    /// Image stabilization mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Off, 1 - On.
    STABILIZATION_MODE,
    /// ISO sensitivity. Value depends on implementation.
    ISO_SENSITIVITY,
    /// Scene mode. Value depends on implementation.
    SCENE_MODE,
    /// FPS.
    FPS,
    /// Brightness mode. Value depends on implementation but it is recommended
    /// to keep default values: 0 - Manual, 1 - Auto.
    BRIGHTNESS_MODE,
    /// Brightness. Value 0 - 100%.
    BRIGHTNESS,
    /// Contrast. Value 0 - 100%.
    CONTRAST,
    /// Gain mode. Value depends on implementation but it is recommended to keep
    /// default values: 0 - Manual, 1 - Auto.
    GAIN_MODE,
    /// Gain. Value 0 - 100%.
    GAIN,
    /// Sharpening mode. Value depends on implementation but it is recommended
    /// to keep default values: 0 - Manual, 1 - Auto.
    SHARPENING_MODE,
    /// Sharpening. Value 1 - 100%.
    SHARPENING,
    /// Palette. Value depends on implementation but it is recommended to keep
    /// default values for thermal cameras: 0 - White hot, 1 - Black hot.
    PALETTE,
    /// Analog gain control mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual, 1 - Auto.
    AGC_MODE,
    /// Shutter mode. Value depends on implementation but it is recommended to
    /// keep default values: 0 - Manual, 1 - Auto.
    SHUTTER_MODE,
    /// Shutter position. 0 (full close) - 65535 (full open).
    SHUTTER_POSITION,
    /// Shutter speed. VISCA shutter step in range 0x00 - 0x15 (0 - 21).
    SHUTTER_SPEED,
    /// Digital zoom mode. Value depends on implementation but it is recommended
    /// to keep default values: 0 - Off, 1 - On.
    DIGITAL_ZOOM_MODE,
    /// Digital zoom. Value 1.0 (x1) - 20.0 (x20).
    DIGITAL_ZOOM,
    /// Exposure compensation mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Off, 1 - On.
    EXPOSURE_COMPENSATION_MODE,
    /// Exposure compensation position. Value depends on particular camera
    /// controller.
    EXPOSURE_COMPENSATION_POSITION,
    /// Defog mode. Value depends on implementation but it is recommended to
    /// keep default values: 0 - Off, 1 - On.
    DEFOG_MODE,
    /// Dehaze mode. Value depends on implementation but it is recommended to
    /// keep default values: 0 - Off, 1 - On.
    DEHAZE_MODE,
    /// Noise reduction mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Off, 1 - 2D, 3 - 3D.
    NOISE_REDUCTION_MODE,
    /// Black and white filter mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Off, 1 - On.
    BLACK_WHITE_FILTER_MODE,
    /// Filter mode. Value depends on implementation.
    FILTER_MODE,
    /// NUC mode for thermal cameras. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual, 1 - Auto.
    NUC_MODE,
    /// Auto NUC interval for thermal cameras. Value in milliseconds
    /// from 0 (Off) to 100000.
    AUTO_NUC_INTERVAL_MSEC,
    /// Image flip mode. Value depends on implementation but it is recommended
    /// to keep default values: 0 - Off, 1 - Horizontal, 2 - Vertical,
    /// 3 - Horizontal and vertical.
    IMAGE_FLIP,
    /// DDE mode. Value depends on implementation but it is recommended to keep
    /// default values: 0 - Off, 1 - On.
    DDE_MODE,
    /// DDE level. Value depends on implementation.
    DDE_LEVEL,
    /// ROI top-left horizontal position, pixels.
    ROI_X0,
    /// ROI top-left vertical position, pixels.
    ROI_Y0,
    /// ROI bottom-right horizontal position, pixels.
    ROI_X1,
    /// ROI bottom-right vertical position, pixels.
    ROI_Y1,
    /// Camera temperature, degree.
    TEMPERATURE,
    /// ALC gate. Value depends on implementation.
    ALC_GATE,
    /// Sensor sensitivity. Value depends on implementation.
    SENSITIVITY,
    /// Changing mode (day / night). Value depends on implementation.
    CHANGING_MODE,
    /// Changing level (day / night). Value depends on implementation.
    CHANGING_LEVEL,
    /// Chroma level. Values: 0 - 100%.
    CHROMA_LEVEL,
    /// Details, enhancement. Values: 0 - 100%.
    DETAIL,
    /// Camera settings profile. Value depends on implementation.
    PROFILE,
    /// Connection status (read only). Shows if we have respone from camera.
    /// Value: 0 - not connected, 2 - connected.
    IS_CONNECTED,
    /// Open status (read only):
    /// 1 - camera control port open, 0 - not open.
    IS_OPEN,
    /// Camera type. Value depends on implementation.
    TYPE,
    /// Camera custom param. Value depends on implementation.
    CUSTOM_1,
    /// Camera custom param. Value depends on implementation.
    CUSTOM_2,
    /// Camera custom param. Value depends on implementation.
    CUSTOM_3
};

Table 6 - Camera params description.

Parameter Access Description
WIDTH read / write Not supported by ViscaCamera library.
HEIGHT read / write Not supported by ViscaCamera library.
DISPLAY_MODE read / write Not supported by ViscaCamera library.
VIDEO_OUTPUT read / write Not supported by ViscaCamera library.
LOG_MODE read / write Logging mode. Values:
0 - Disable,
1 - Only file,
2 - Only terminal (console),
3 - File and terminal.
EXPOSURE_MODE read / write Exposure mode. Values:
0 - Manual exposure mode.
1 - Full auto exposure mode.
2 - Set exposure mode to shutter priority.
3 - Set exposure mode to iris priority.
EXPOSURE_TIME read / write Exposure time of the camera sensor expressed in 100 µs units. Supported values: 0 - 10000 (where 1 = 1/10000 s and 10000 = 1 s). The library maps the requested value to the nearest supported VISCA shutter step (see SHUTTER_SPEED).
Can be set only when the exposure mode is Manual or Shutter Priority; otherwise, the camera will override the user-defined value.
WHITE_BALANCE_MODE read / write White balance mode. Value:
0 - White balance auto mode.
1 - White balance Outdoor-auto mode.
WHITE_BALANCE_AREA read / write Not supported by ViscaCamera library.
WIDE_DYNAMIC_RANGE_MODE read / write Wide dynamic range mode. Value:
0 - Off.
1 - On.
STABILIZATION_MODE read / write Stabilization mode. Value:
0 - Off.
1 - On.
ISO_SENSITIVITY read / write Not supported by ViscaCamera library.
SCENE_MODE read / write Not supported by ViscaCamera library.
FPS read / write Not supported by ViscaCamera library.
BRIGHTNESS_MODE read / write Not supported by ViscaCamera library.
BRIGHTNESS read / write Not supported by ViscaCamera library.
CONTRAST read / write Contrast. Value 0 - 100%.
GAIN_MODE read / write Not supported by ViscaCamera library.
GAIN read / write Camera gain. Value 0 - 100% (the value is mapped to the 15 gain steps of the camera). Reading returns the gain reported by the camera in percents.
Can be set only when the exposure mode is Manual; otherwise, the camera will override the user-defined value.
SHARPENING_MODE read / write Sony Visibility Enhancer mode. Parameter n, options: 0 - Off, 1 - On.
SHARPENING read / write Not supported by ViscaCamera library.
PALETTE read / write Not supported by ViscaCamera library.
AGC_MODE read only Setting is not supported. Reading returns 1.
SHUTTER_MODE read / write Shutter mode. Values:
0 - Auto slow shutter off.
1 - Auto slow shutter on.
SHUTTER_POSITION read only Current shutter position reported by the camera. Returns the raw VISCA shutter speed code (0 - 21), matching the value table of SHUTTER_SPEED.
SHUTTER_SPEED read / write Set shutter speed. Parameter n, supported values:
21 — 1/10000
20 — 1/6000
19 — 1/4000
18 — 1/3000
17 — 1/2000
16 — 1/1500
15 — 1/1000
14 — 1/725
13 — 1/500
12 — 1/350
11 — 1/250
10 — 1/180
09 — 1/125
08 — 1/100
07 — 1/90
06 — 1/60
05 — 1/30
04 — 1/15
03 — 1/8
02 — 1/4
01 — 1/2
00 — 1/1
DIGITAL_ZOOM_MODE read / write Digital zoom mode. Values to set:
0 - Off.
1 - On.
Reading returns 0 - Off, 1 - On (combined with the optical zoom), 2 - On (separate from the optical zoom). The library selects the separate mode when it connects to the camera.
DIGITAL_ZOOM read / write Digital zoom. Values to set: 1.0 (x1.0) - 20.0 (x20.0). The value is converted to the VISCA digital zoom position 0 - 65535 and the packet encoder accepts positions up to 255 only: for a larger position no command is sent and the error is written to the log. Reading returns the digital zoom position code reported by the camera (0 - 255), it is not the zoom factor.
EXPOSURE_COMPENSATION_MODE read / write Exposure compensation mode. Values:
0 - Off.
1 - On.
EXPOSURE_COMPENSATION_POSITION read / write Exposure compensation offsets the internal reference brightness level in AE mode in 1.5 dB steps. Supported values:
14 — +10.5 dB
13 — +9 dB
12 — +7.5 dB
11 — +6 dB
10 — +4.5 dB
9 — +3 dB
8 — +1.5 dB
7 — 0 dB
6 — −1.5 dB
5 — −3 dB
4 — −4.5 dB
3 — −6 dB
2 — −7.5 dB
1 — −9 dB
0 — −10.5 dB
DEFOG_MODE read / write Defog mode. Values to set:
0 - Off
1 - Low.
2 - Mid.
3 - High.
Reading returns the defog level reported by the camera (0 - 3).
DEHAZE_MODE   Not supported by ViscaCamera library.
NOISE_REDUCTION_MODE read / write Noise reduction mode. Values:
0 - Off.
1 - On - 2D.
BLACK_WHITE_FILTER_MODE read / write Black and white picture effect. Values:
0 - Off.
1 - On.
FILTER_MODE read / write ICR (Infrared Cut Removable) filter state. Values:
0 - ICR OFF.
1 - ICR ON.
Setting the parameter is equivalent to setting LensParam::FILTER_MODE. Reading returns the state reported by the camera.
NUC_MODE read / write Not supported by ViscaCamera library.
AUTO_NUC_INTERVAL_MSEC read / write Not supported by ViscaCamera library.
IMAGE_FLIP read / write Image flip mode. Values:
0 - Off.
1 - On.
DDE_MODE read / write Not supported by ViscaCamera library.
DDE_LEVEL read / write Not supported by ViscaCamera library.
ROI_X0 read / write Not supported by ViscaCamera library.
ROI_Y0 read / write Not supported by ViscaCamera library.
ROI_X1 read / write Not supported by ViscaCamera library.
ROI_Y1 read / write Not supported by ViscaCamera library.
TEMPERATURE read only Not supported by ViscaCamera library.
ALC_GATE read / write Not supported by ViscaCamera library.
SENSITIVITY read / write Sensitivity mode. Values:
0 - High sensitivity mode off.
1 - High sensitivity mode on.
CHANGING_MODE read / write Not supported by ViscaCamera library.
CHANGING_LEVEL read / write Not supported by ViscaCamera library.
CHROMA_LEVEL read / write Chroma level value, as percentage. Supported values between 0 and 100. The library maps the value to the chroma suppress step of the camera: below 1 - off, below 33 - step 1, below 66 - step 2, from 66 - step 3.
DETAIL read / write Not supported by ViscaCamera library.
PROFILE read / write Not supported by ViscaCamera library.
IS_CONNECTED read only Connection status. Connection status shows if the controller has data exchange with equipment. For example, if serial port open but equipment can be not active (no power). In this case connection status shows that controller doesn’t have data exchange with equipment (methods will return 0). If the controller has data exchange with equipment, the method will return 1. If the controller not initialize the connection status always FALSE. Value: 0 - not connected. 1 - connected.
IS_OPEN read only Not supported by ViscaCamera library. The method returns -1. Use isCameraOpen() to get the initialization status.
TYPE read / write Not supported by ViscaCamera library.
CUSTOM_1 read / write Backlight compensation mode. Values:
0 - Off.
1 - On.
CUSTOM_2 read / write Not supported by ViscaCamera library.
CUSTOM_3 read / write Not supported by ViscaCamera library.

PanTiltParam enum

Enum declaration:

enum class PanTiltParam
{
    /// Pan motor position for encoder. Range: 0 - 65535.
    PAN_MOTOR_POSITION = 1,
    /// Tilt motor position for encoder. Range: 0 - 65535.
    TILT_MOTOR_POSITION,
    /// Pan angle. Range: -180.0 to 180.0.
    PAN_ANGLE,
    /// Tilt angle. Range: -180.0 to 180.0.
    TILT_ANGLE,
    /// Pan motor speed. Positive speed is clockwise, 
    /// negative is counterclockwise.
    PAN_MOTOR_SPEED,
    /// Tilt motor speed. Positive speed is clockwise, 
    /// negative is counterclockwise.
    TILT_MOTOR_SPEED,
    /// Status defining if the pan-tilt device is connected.
    IS_CONNECTED,
    /// Status defining if the pan-tilt device is initialized.
    IS_OPEN,
    /// PanTilt custom param. Not used in current implementation.
    CUSTOM_1,
    /// PanTilt custom param. Not used in current implementation.
    CUSTOM_2,
    /// PanTilt custom param. Not used in current implementation.
    CUSTOM_3
};

Table 7 - Params description.

Parameter Access Description
PAN_MOTOR_POSITION read / write Not supported by ViscaCamera library.
TILT_MOTOR_POSITION read / write Not supported by ViscaCamera library.
PAN_ANGLE read / write Pan angle. Range: -180.0 to 180.0. The pan and tilt angles are sent to the camera together: the tilt angle that was set last is sent with the pan angle.
TILT_ANGLE read / write Tilt angle. Range: -180.0 to 180.0. The pan angle that was set last is sent with the tilt angle.
PAN_MOTOR_SPEED read / write Not supported by ViscaCamera library.
TILT_MOTOR_SPEED read / write Not supported by ViscaCamera library.
IS_CONNECTED read only Not supported by ViscaCamera library. The method returns -1. Use isPanTiltConnected() to get the connection status.
IS_OPEN read only Not supported by ViscaCamera library. The method returns -1. Use isPanTiltOpen() to get the initialization status.
CUSTOM_1 read / write Not supported by ViscaCamera library.
CUSTOM_2 read / write Not supported by ViscaCamera library.
CUSTOM_3 read / write Not supported by ViscaCamera library.

LensParams class description

LensParams class is used for lens initialization or to get all actual parameters. Also LensParams provides the JSON_READABLE macro to write/read parameters to/from JSON files and provides methods to encode and decode parameters.

LensParams class declaration

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

class LensParams
{
public:
    /// Initialization string.
    std::string initString{"/dev/ttyUSB0;9600;20"};
    /// Zoom position.
    int zoomPos{0};
    /// Hardware zoom position.
    int zoomHwPos{0};
    /// Focus position.
    int focusPos{0};
    /// Hardware focus position.
    int focusHwPos{0};
    /// Iris position.
    int irisPos{0};
    /// Hardware iris position.
    int irisHwPos{0};
    /// Focus mode.
    int focusMode{0};
    /// Filter mode.
    int filterMode{0};
    /// Autofocus ROI top-left corner horizontal position in pixels.
    int afRoiX0{0};
    /// Autofocus ROI top-left corner vertical position in pixels.
    int afRoiY0{0};
    /// Autofocus ROI bottom-right corner horizontal position in pixels.
    int afRoiX1{0};
    /// Autofocus ROI bottom-right corner vertical position in pixels.
    int afRoiY1{0};
    /// Zoom speed.
    int zoomSpeed{50};
    /// Zoom hardware speed.
    int zoomHwSpeed{50};
    /// Maximum zoom hardware speed.
    int zoomHwMaxSpeed{50};
    /// Focus speed.
    int focusSpeed{50};
    /// Focus hardware speed.
    int focusHwSpeed{50};
    /// Maximum focus hardware speed.
    int focusHwMaxSpeed{50};
    /// Iris speed.
    int irisSpeed{50};
    /// Iris hardware speed.
    int irisHwSpeed{50};
    /// Maximum iris hardware speed.
    int irisHwMaxSpeed{50};
    /// Zoom hardware tele limit.
    int zoomHwTeleLimit{65535};
    /// Zoom hardware wide limit.
    int zoomHwWideLimit{0};
    /// Focus hardware far limit.
    int focusHwFarLimit{65535};
    /// Focus hardware near limit.
    int focusHwNearLimit{0};
    /// Iris hardware open limit.
    int irisHwOpenLimit{65535};
    /// Iris hardware close limit.
    int irisHwCloseLimit{0};
    /// Focus factor if it was calculated.
    float focusFactor{0.0f};
    /// Lens connection status.
    bool isConnected{false};
    /// Focus hardware speed in autofocus mode.
    int afHwSpeed{50};
    /// Focus factor change threshold to start refocus.
    float focusFactorThreshold{0.0f};
    /// Timeout for automatic refocus in seconds.
    int refocusTimeoutSec{0};
    /// Flag about active autofocus algorithm.
    bool afIsActive{false};
    /// Iris mode.
    int irisMode{0};
    /// ROI width (pixels) for autofocus algorithm.
    int autoAfRoiWidth{150};
    /// ROI height (pixels) for autofocus algorithm.
    int autoAfRoiHeight{150};
    /// Video frame border size (along vertical and horizontal axes).
    int autoAfRoiBorder{100};
    /// AF ROI mode (write/read).
    int afRoiMode{0};
    /// Lens extender mode.
    int extenderMode{0};
    /// Lens stabilization mode.
    int stabiliserMode{0};
    /// Autofocus range.
    int afRange{0};
    /// Current horizontal Field of view, degree.
    float xFovDeg{1.0f};
    /// Current vertical Field of view, degree.
    float yFovDeg{1.0f};
    /// Logging mode.
    int logMode{0};
    /// Lens temperature, degree (read only).
    float temperature{0.0f};
    /// Lens controller initialization status.
    bool isOpen{false};
    /// Lens type. Value depends on implementation.
    int type{0};
    /// Lens custom parameter.
    float custom1{0.0f};
    /// Lens custom parameter.
    float custom2{0.0f};
    /// Lens custom parameter.
    float custom3{0.0f};
    /// List of points to calculate field of view.
    std::vector<FovPoint> fovPoints{std::vector<FovPoint>()};

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

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

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

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

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

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

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

    /// Decode params.
    bool decode(uint8_t* data, int dataSize);
};

LensParams class fields description is equivalent to LensParam enum description except initString and fovPoints. The format of initString depends on the lens controller implementation. The recommended format for controllers which use a serial port is [serial port name];[baudrate];[serial port read timeout], for example /dev/ttyUSB0;9600;20 (the default value). fovPoints is a list of FovPoint objects (declared in Lens.h file). Each FovPoint has three fields: hwZoomPos (int, hardware zoom position, default 0), xFovDeg (float, horizontal field of view in degrees, default 0.0f) and yFovDeg (float, vertical field of view in degrees, default 0.0f).

Serialize lens params

The LensParams class provides method encode(…) to serialize lens params. Serialization of lens params is necessary when you need to send lens params via communication channels. The method doesn’t encode initString and fovPoints fields. The method provides options to exclude particular parameters from serialization. To do this, the method inserts a binary mask (7 bytes) where each bit represents a particular parameter and decode(…) method recognizes it. The first field of LensParamsMask is the most significant bit of the first mask byte. The encoded data starts with a header of 10 bytes: data type (1 byte, value 0x02), major and minor version of the Lens library (1 byte each) and the mask (7 bytes). The values of the selected params follow the header in the order of the LensParamsMask fields: int and float values use 4 bytes (byte order of the host), bool values (isConnected, afIsActive and isOpen) use 1 byte. The size of the encoded data is 201 bytes if all params are encoded and 10 bytes if all params are excluded. Method declaration:

bool encode(uint8_t* data, int bufferSize, int& size, LensParamsMask* mask = nullptr);
Parameter Value
data Pointer to data buffer. Must not be nullptr.
bufferSize Data buffer size in bytes. Buffer size must be >= 201 bytes regardless of the mask.
size Size of encoded data in bytes. Set to 0 if the method returns FALSE.
mask Parameters mask - pointer to LensParamsMask structure. LensParamsMask (declared in Lens.h file) determines flags for each field (parameter) declared in LensParams class. To exclude particular parameters from serialization, set the corresponding flags to false in the LensParamsMask structure and pass a pointer to it. If mask is nullptr, all params are encoded.

Returns: TRUE if params encoded (serialized) or FALSE if not (data is nullptr or bufferSize is less than 201). If FALSE is returned, the data buffer is not changed.

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:

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

// Encode params.
constexpr int bufferSize{1024};
uint8_t data[bufferSize];
int size{0};
if (in.encode(data, bufferSize, size))
{
    std::cout << "Encoded data size: " << size << " bytes" << std::endl;
}
else
{
    std::cout << "Can't encode params" << 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 params.
constexpr int bufferSize{1024};
uint8_t data[bufferSize];
int size{0};
if (in.encode(data, bufferSize, size, &mask))
{
    std::cout << "Encoded data size: " << size << " bytes" << std::endl;
}
else
{
    std::cout << "Can't encode params" << std::endl;
}

Deserialize lens params

The LensParams class provides method decode(…) to deserialize lens params. Deserialization of lens params is necessary when you need to receive lens params via communication channels. The method automatically recognizes which parameters were serialized by encode(…) method. Params which were not serialized are set to 0 (false for bool params). The method doesn’t decode fields initString and fovPoints: initString is set to an empty string and fovPoints is cleared. The method rejects data which has a different major or minor version of the Lens library. Bytes after the last serialized value are ignored. Method declaration:

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

Returns: TRUE if data decoded (deserialized) or FALSE if not (data is nullptr, dataSize is less than the header size of 10 bytes, data type or version is wrong, the mask has bits of unknown params, or dataSize is too small for the params selected by the mask). If FALSE is returned, the object is not changed.

Example:

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

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

Read and write lens params to JSON file

Lens interface class library depends on the ConfigReader library which provides methods to read parameters from a JSON file and to write parameters to a JSON file. The JSON_READABLE macro of LensParams lists the fields which are stored in JSON (see the class declaration). The JSON key of a field is the name of the field and the keys are written in the order of the macro list. Fields which are not listed in the macro (for example zoomPos, isConnected and isOpen) are not written to JSON and are not read from JSON. Float values are written as double values, so a value which can’t be represented exactly in float (for example 0.7f) is written with more digits (0.69999998807907104). Example of writing and reading parameters to a JSON file:

// Prepare params.
rapidpixel::LensParams in;
in.focusMode = 1;
in.logMode = 3;
in.custom1 = 2.5f;
for (int i = 1; i <= 2; ++i)
{
    rapidpixel::FovPoint point;
    point.hwZoomPos = 1000 * i;
    point.xFovDeg = 60.0f / static_cast<float>(i);
    point.yFovDeg = 34.0f / static_cast<float>(i);
    in.fovPoints.push_back(point);
}

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

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

ConfigReader::get(…) returns FALSE if the object name is not found in the file, if a key listed in the macro is missing or if a value has a wrong type. The object is not changed in this case. Keys which are not listed in the macro are ignored. If ConfigReader::get(…) returns TRUE, the object is replaced and the fields which are not listed in the macro get their default values.

TestLensParams.json will look like:

{
    "lensParams": {
        "initString": "/dev/ttyUSB0;9600;20",
        "focusMode": 1,
        "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": 2.5,
        "custom2": 0.0,
        "custom3": 0.0,
        "fovPoints": [
            {
                "hwZoomPos": 1000,
                "xFovDeg": 60.0,
                "yFovDeg": 34.0
            },
            {
                "hwZoomPos": 2000,
                "xFovDeg": 30.0,
                "yFovDeg": 17.0
            }
        ]
    }
}

CameraParams class description

CameraParams class is used for camera controller initialization or to get all actual parameters. Also CameraParams provides the JSON_READABLE macro to write/read parameters to/from JSON files and provides methods to encode and decode parameters.

CameraParams Class declaration

CameraParams interface class declared in Camera.h file. Class declaration:

class CameraParams
{
public:
    /// Initialization string.
    std::string initString{"/dev/ttyUSB0;9600;20"};
    /// Video frame width. Value from 0 to 16384.
    int width{0};
    /// Video frame height. Value from 0 to 16384.
    int height{0};
    /// Display menu mode.
    int displayMode{0};
    /// Video output type.
    int videoOutput{0};
    /// Logging mode.
    int logMode{0};
    /// Exposure mode.
    int exposureMode{1};
    /// Exposure time of the camera sensor.
    int exposureTime{0};
    /// White balance mode.
    int whiteBalanceMode{1};
    /// White balance area.
    int whiteBalanceArea{0};
    /// Wide dynamic range mode.
    int wideDynamicRangeMode{0};
    /// Image stabilization mode.
    int stabilizationMode{0};
    /// ISO sensitivity.
    int isoSensitivity{0};
    /// Scene mode.
    int sceneMode{0};
    /// FPS.
    float fps{0.0f};
    /// Brightness mode.
    int brightnessMode{1};
    /// Brightness. Value 0 - 100%.
    int brightness{0};
    /// Contrast. Value 1 - 100%.
    int contrast{0};
    /// Gain mode.
    int gainMode{1};
    /// Gain. Value 1 - 100%.
    int gain{0};
    /// Sharpening mode.
    int sharpeningMode{0};
    /// Sharpening. Value 1 - 100%.
    int sharpening{0};
    /// Palette.
    int palette{0};
    /// Analog gain control mode.
    int agcMode{1};
    /// Shutter mode.
    int shutterMode{1};
    /// Shutter position. 0 (full close) - 65535 (full open).
    int shutterPos{0};
    /// Shutter speed. Value: 0 - 100%.
    int shutterSpeed{0};
    /// Digital zoom mode.
    int digitalZoomMode{0};
    /// Digital zoom. Value 1.0 (x1) - 20.0 (x20).
    float digitalZoom{1.0f};
    /// Exposure compensation mode.
    int exposureCompensationMode{0};
    /// Exposure compensation position.
    int exposureCompensationPosition{0};
    /// Defog mode.
    int defogMode{0};
    /// Dehaze mode.
    int dehazeMode{0};
    /// Noise reduction mode.
    int noiseReductionMode{0};
    /// Black and white filter mode.
    int blackAndWhiteFilterMode{0};
    /// Filter mode.
    int filterMode{0};
    /// NUC mode for thermal cameras.
    int nucMode{0};
    /// Auto NUC interval for thermal cameras.
    int autoNucIntervalMsec{0};
    /// Image flip mode.
    int imageFlip{0};
    /// DDE mode.
    int ddeMode{0};
    /// DDE level.
    float ddeLevel{0};
    /// ROI top-left horizontal position, pixels.
    int roiX0{0};
    /// ROI top-left vertical position, pixels.
    int roiY0{0};
    /// ROI bottom-right horizontal position, pixels.
    int roiX1{0};
    /// ROI bottom-right vertical position, pixels.
    int roiY1{0};
    /// Camera temperature, degree.
    float temperature{0.0f};
    /// ALC gate.
    int alcGate{0};
    /// Sensor sensitivity.
    float sensitivity{0};
    /// Changing mode (day / night).
    int changingMode{0};
    /// Changing level (day / night).
    float changingLevel{0.0f};
    /// Chroma level. Values: 0 - 100%.
    int chromaLevel{0};
    /// Details, enhancement. Values: 0 - 100%.
    int detail{0};
    /// Camera settings profile.
    int profile{0};
    /// Connection status (read only).
    bool isConnected{false};
    /// Open status (read only).
    bool isOpen{false};
    /// Camera type.
    int type{0};
    /// Camera custom param.
    float custom1{0.0f};
    /// Camera custom param.
    float custom2{0.0f};
    /// Camera custom param.
    float custom3{0.0f};

    JSON_READABLE(CameraParams, initString, width, height, displayMode,
                  videoOutput, logMode, exposureMode, exposureTime,
                  whiteBalanceMode, whiteBalanceArea, wideDynamicRangeMode,
                  stabilizationMode, isoSensitivity, sceneMode, fps,
                  brightnessMode, brightness, contrast, gainMode, gain,
                  sharpeningMode, sharpening, palette, agcMode, shutterMode,
                  shutterPos, shutterSpeed, digitalZoomMode, digitalZoom,
                  exposureCompensationMode, exposureCompensationPosition,
                  defogMode, dehazeMode, noiseReductionMode,
                  blackAndWhiteFilterMode, filterMode, nucMode,
                  autoNucIntervalMsec, imageFlip, ddeMode, ddeLevel, roiX0,
                  roiY0, roiX1, roiY1, alcGate, sensitivity, changingMode,
                  changingLevel, chromaLevel, detail, profile, type, custom1,
                  custom2, custom3)

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

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

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

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

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

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

    /// Decode params. The method sets initString to an empty string.
    bool decode(uint8_t* data, int dataSize);
};

CameraParams class fields description is equivalent to CameraParam enum description except initString. The format of initString depends on the camera controller implementation. The default value is /dev/ttyUSB0;9600;20.

Serialize camera params

CameraParams class provides method encode(…) to serialize camera params. Serialization of camera params is necessary when you have to send camera params via communication channels. The method doesn’t encode initString field. The method provides options to exclude particular parameters from serialization. To do this, the method inserts a binary mask (8 bytes) where each bit represents a particular parameter and decode(…) method recognizes it. The first field of CameraParamsMask is the most significant bit of the first mask byte. The encoded data starts with a header of 11 bytes: data type (1 byte, value 0x02), major and minor version of the Camera library (1 byte each) and the mask (8 bytes). The values of the selected params follow the header in the order of the CameraParamsMask fields: int and float values use 4 bytes (byte order of the host), bool values (isConnected and isOpen) use 1 byte. The size of the encoded data is 237 bytes if all params are encoded and 11 bytes if all params are excluded. Method declaration:

bool encode(uint8_t* data, int bufferSize, int& size, CameraParamsMask* mask = nullptr);
Parameter Value
data Pointer to data buffer. Must not be nullptr.
bufferSize Data buffer size in bytes. Buffer size must be >= 237 bytes regardless of the mask.
size Size of encoded data in bytes. Set to 0 if the method returns FALSE.
mask Parameters mask - pointer to CameraParamsMask structure. CameraParamsMask (declared in Camera.h file) determines flags for each field (parameter) declared in CameraParams class. To exclude particular parameters from serialization, set the corresponding flags to false in the CameraParamsMask structure and pass a pointer to it. If mask is nullptr, all params are encoded.

Returns: TRUE if params encoded (serialized) or FALSE if not (data is nullptr or bufferSize is less than 237). If FALSE is returned, the data buffer is not changed.

CameraParamsMask structure declaration:

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

Example without parameters mask:

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

// Encode params.
constexpr int bufferSize{1024};
uint8_t data[bufferSize];
int size{0};
if (in.encode(data, bufferSize, size))
{
    std::cout << "Encoded data size: " << size << " bytes" << std::endl;
}
else
{
    std::cout << "Can't encode params" << std::endl;
}

Example with parameters mask:

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

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

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

Deserialize camera params

CameraParams class provides method decode(…) to deserialize camera params. Deserialization of camera params is necessary when you need to receive params via communication channels. The method automatically recognizes which parameters were serialized by encode(…) method. Params which were not serialized are set to 0 (false for bool params). The method doesn’t decode initString field: it is set to an empty string. The method rejects data which has a different major or minor version of the Camera library. Mask bits which don’t belong to any param and bytes after the last serialized value are ignored. Method declaration:

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

Returns: TRUE if params decoded (deserialized) or FALSE if not (data is nullptr, dataSize is less than the header size of 11 bytes, data type or version is wrong, or dataSize is too small for the params selected by the mask). If FALSE is returned, the object is not changed.

Example:

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

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

Read and write camera params to JSON file

Camera library depends on the ConfigReader library which provides methods to read parameters from a JSON file and to write parameters to a JSON file. The JSON_READABLE macro of CameraParams lists the fields which are stored in JSON (see the class declaration). The JSON key of a field is the name of the field and the keys are written in the order of the macro list. The fields temperature, isConnected and isOpen are not written to JSON and are not read from JSON. Float values are written as double values, so a value which can’t be represented exactly in float (for example 0.7f) is written with more digits (0.69999998807907104). Example of writing and reading parameters to a JSON file:

// Prepare params.
rapidpixel::CameraParams in;
in.width = 1920;
in.height = 1080;
in.fps = 25.5f;
in.chromaLevel = 40;

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

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

ConfigReader::get(…) returns FALSE if the object name is not found in the file, if a key listed in the macro is missing or if a value has a wrong type. The object is not changed in this case. Keys which are not listed in the macro are ignored. If ConfigReader::get(…) returns TRUE, the object is replaced and the fields which are not listed in the macro get their default values.

TestCameraParams.json will look like:

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

PanTiltParams class description

PanTiltParams class declaration

PanTiltParams class is used to provide the pan-tilt parameters structure. Also PanTiltParams provides the JSON_READABLE macro to write/read parameters to/from JSON files and provides methods to encode and decode parameters. PanTiltParams interface class is declared in the PanTilt.h file. Class declaration:

class PanTiltParams
{
public:
    /// Pan motor position for encoder. Range: 0 - 65535.
    int panMotorPosition{ 0 };
    /// Tilt motor position for encoder. Range: 0 - 65535.
    int tiltMotorPosition{ 0 };
    /// Pan angle. Range: -180.0 to 180.0.
    float panAngle{ 0.0f };
    /// Tilt angle. Range: -180.0 to 180.0.
    float tiltAngle{ 0.0f };
    /// Pan motor speed. Range: -100.0 to 100.0.
    float panMotorSpeed{ 0.0f };
    /// Tilt motor speed. Range: -100.0 to 100.0.
    float tiltMotorSpeed{ 0.0f };
    /// Status defining if the pan-tilt device is connected.
    bool isConnected{ false };
    /// Status defining if the pan-tilt device is initialized (open).
    bool isOpen{ false };
    /// Init string. Format depends on target controller.
    std::string initString{ "" };
    /// PanTilt custom parameter. Value depends on the pan-tilt controller.
    float custom1{ 0.0f };
    /// PanTilt custom parameter. Value depends on the pan-tilt controller.
    float custom2{ 0.0f };
    /// PanTilt custom parameter. Value depends on the pan-tilt controller.
    float custom3{ 0.0f };

    /// Macro from ConfigReader to make params readable/writable from JSON.
    JSON_READABLE(PanTiltParams, panMotorSpeed, tiltMotorSpeed, initString,
                  custom1, custom2, custom3)

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

    /// Copy constructor. Copies all fields.
    PanTiltParams(const PanTiltParams& src) = default;

    /// Copy assignment operator. Doesn't copy isConnected and isOpen.
    PanTiltParams& operator= (const PanTiltParams& src);

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

    /// Decode (deserialize) params. The method doesn't change initString.
    bool decode(uint8_t* data, int dataSize);
};

PanTiltParams class fields description is equivalent to the PanTiltParam enum description except initString. The format of initString depends on the pan-tilt controller implementation. The default value is an empty string.

Serialize PanTilt params

PanTiltParams class provides method encode(…) to serialize PanTilt params. Serialization of PanTilt params is necessary when PanTilt params have to be sent via communication channels. The method doesn’t encode initString field. The method provides options to exclude particular parameters from serialization. To do this, the method inserts a binary mask (2 bytes) where each bit represents a particular parameter and decode(…) method recognizes it. The first field of PanTiltParamsMask is the most significant bit of the first mask byte. The encoded data starts with a header of 5 bytes: data type (1 byte, value 0x02), major and minor version of the PanTilt library (1 byte each) and the mask (2 bytes). The values of the selected params follow the header in the order of the PanTiltParamsMask fields: int and float values use 4 bytes (byte order of the host), bool values (isConnected and isOpen) use 1 byte. The size of the encoded data is 43 bytes if all params are encoded and 5 bytes if all params are excluded. Method declaration:

bool encode(uint8_t* data, int bufferSize, int& size, PanTiltParamsMask* mask = nullptr);
Parameter Value
data Pointer to data buffer. Must not be nullptr.
bufferSize Data buffer size in bytes. Buffer size must be >= 43 bytes regardless of the mask.
size Size of encoded data in bytes. Set to 0 if the method returns FALSE.
mask Parameters mask - pointer to PanTiltParamsMask structure. PanTiltParamsMask (declared in PanTilt.h file) determines flags for each field (parameter) declared in PanTiltParams class. To exclude particular parameters from serialization, set the corresponding flags to false in the PanTiltParamsMask structure and pass a pointer to it. If mask is nullptr, all params are encoded.

Returns: TRUE if params encoded (serialized) or FALSE if not (data is nullptr or bufferSize is less than 43). If FALSE is returned, the data buffer is not changed.

PanTiltParamsMask structure declaration:

struct PanTiltParamsMask
{
    bool panMotorPosition{ true };
    bool tiltMotorPosition{ true };
    bool panAngle{ true };
    bool tiltAngle{ true };
    bool panMotorSpeed{ true };
    bool tiltMotorSpeed{ true };
    bool isConnected{ true };
    bool isOpen{ true };
    bool custom1{ true };
    bool custom2{ true };
    bool custom3{ true };
};

Example without parameters mask:

// Prepare parameters.
rapidpixel::PanTiltParams params;
params.panAngle = 160.0f;

// Encode (serialize) params.
constexpr int bufferSize{128};
uint8_t buffer[bufferSize];
int size{0};
if (!params.encode(buffer, bufferSize, size))
{
    std::cout << "Can't encode params" << std::endl;
}

Example with parameters mask:

// Prepare parameters.
rapidpixel::PanTiltParams params;
params.panAngle = 160.0f;

// Prepare mask.
rapidpixel::PanTiltParamsMask mask;
// Exclude tiltAngle.
mask.tiltAngle = false;

// Encode (serialize) params.
constexpr int bufferSize{128};
uint8_t buffer[bufferSize];
int size{0};
if (!params.encode(buffer, bufferSize, size, &mask))
{
    std::cout << "Can't encode params" << std::endl;
}

Deserialize PanTilt params

PanTiltParams class provides method decode(…) to deserialize params. Deserialization of PanTilt params is necessary when it is needed to receive params via communication channels. The method automatically recognizes which parameters were serialized by encode(…) method. Params which were not serialized are set to 0 (false for bool params). The method doesn’t change initString field. The method rejects data which has a different major or minor version of the PanTilt library. Mask bits which don’t belong to any param and bytes after the last serialized value are ignored. Method declaration:

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

Returns: TRUE if params decoded (deserialized) or FALSE if not (data is nullptr, dataSize is less than the header size of 5 bytes, data type or version is wrong, or dataSize is too small for the params selected by the mask). If FALSE is returned, the object is not changed.

Example:

// Prepare parameters.
rapidpixel::PanTiltParams params1;
params1.panAngle = 160.0f;

// Encode (serialize) params.
constexpr int bufferSize{128};
uint8_t buffer[bufferSize];
int size{0};
if (!params1.encode(buffer, bufferSize, size))
{
    std::cout << "Can't encode params" << std::endl;
}

// Decode (deserialize) params.
rapidpixel::PanTiltParams params2;
if (!params2.decode(buffer, size))
{
    std::cout << "Can't decode params" << std::endl;
}

Read pan-tilt params from JSON file and write to JSON file

PanTilt depends on the ConfigReader library which provides methods to read params from a JSON file and to write params to a JSON file. The JSON_READABLE macro of PanTiltParams lists the fields which are stored in JSON: panMotorSpeed, tiltMotorSpeed, initString, custom1, custom2 and custom3. The JSON key of a field is the name of the field and the keys are written in the order of the macro list. The fields panMotorPosition, tiltMotorPosition, panAngle, tiltAngle, isConnected and isOpen are not written to JSON and are not read from JSON. Float values are written as double values, so a value which can’t be represented exactly in float (for example 0.7f) is written with more digits (0.69999998807907104). Example of writing and reading params to a JSON file:

// Prepare params.
rapidpixel::PanTiltParams in;
in.panMotorSpeed = 50.0f;
in.tiltMotorSpeed = -25.5f;
in.initString = "/dev/ttyUSB0;9600";
in.custom1 = 0.5f;

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

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

ConfigReader::get(…) returns FALSE if the object name is not found in the file, if a key listed in the macro is missing or if a value has a wrong type. The object is not changed in this case. Keys which are not listed in the macro are ignored. If ConfigReader::get(…) returns TRUE, the fields which are not listed in the macro get their default values, except isConnected and isOpen which keep their current values (the copy assignment operator of PanTiltParams doesn’t copy them).

PanTiltParams.json will look like:

{
    "panTiltParams": {
        "panMotorSpeed": 50.0,
        "tiltMotorSpeed": -25.5,
        "initString": "/dev/ttyUSB0;9600",
        "custom1": 0.5,
        "custom2": 0.0,
        "custom3": 0.0
    }
}

Build and connect to your project

Build stand alone

The repository does not contain sub-repositories. The libraries ViscaCamera depends on (ConfigReader, Frame, SerialPort, Logger, ViscaParser, Camera, Lens and PanTilt) must be placed in the same folder as ViscaCamera: copy their folders, for example from the folder modules of the RapidPixel SDK. The folder structure must be:

<work folder>
    ViscaCamera
    ConfigReader
    Frame
    SerialPort
    Logger
    ViscaParser
    Camera
    Lens
    PanTilt

Typical commands to build the library, the test application and the example:

cd ViscaCamera
mkdir build
cd build
cmake ..
make

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

CMake options

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

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

Connect to your project

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

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

Create folder 3rdparty in your repository and copy the folders of the libraries ConfigReader, Frame, SerialPort, Logger, ViscaParser, Camera, Lens, PanTilt and ViscaCamera there (for example from the folder modules of the RapidPixel SDK). Structure of your repository:

CMakeLists.txt
src
    CMakeLists.txt
    yourLib.h
    yourLib.cpp
3rdparty
    CMakeLists.txt
    ViscaCamera
    ConfigReader
    Frame
    SerialPort
    Logger
    ViscaParser
    Camera
    Lens
    PanTilt

ViscaCamera does not add its dependencies when it is included in another project: your project must add them. Add the dependencies in dependency order (a library after the libraries it depends on) and before ViscaCamera. Create CMakeLists.txt file in 3rdparty folder. CMakeLists.txt should contain:

cmake_minimum_required(VERSION 3.13)

################################################################################
## 3RD-PARTY
## dependencies for the project
################################################################################
project(3rdparty LANGUAGES CXX)

################################################################################
## SETTINGS
## basic 3rd-party settings before use
################################################################################
# To inherit the top-level architecture when the project is used as a submodule.
SET(PARENT ${PARENT}_YOUR_PROJECT_3RDPARTY)
# Disable self-overwriting of parameters inside included subdirectories.
SET(${PARENT}_SUBMODULE_CACHE_OVERWRITE OFF CACHE BOOL "" FORCE)

################################################################################
## CONFIGURATION
## 3rd-party submodules configuration
################################################################################
SET(${PARENT}_SUBMODULE_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_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_SERIAL_PORT                     ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_SERIAL_PORT)
    SET(${PARENT}_SERIAL_PORT                           ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_SERIAL_PORT_EXAMPLES                  OFF CACHE BOOL "" FORCE)
endif()

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

SET(${PARENT}_SUBMODULE_VISCA_PARSER                    ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_VISCA_PARSER)
    SET(${PARENT}_VISCA_PARSER                          ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_VISCA_PARSER_EXAMPLES                 OFF CACHE BOOL "" FORCE)
endif()

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

SET(${PARENT}_SUBMODULE_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_PAN_TILT                        ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_PAN_TILT)
    SET(${PARENT}_PAN_TILT                              ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_PAN_TILT_EXAMPLE                      OFF CACHE BOOL "" FORCE)
    SET(${PARENT}_PAN_TILT_TEST                         OFF CACHE BOOL "" FORCE)
endif()

SET(${PARENT}_SUBMODULE_VISCA_CAMERA                    ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_VISCA_CAMERA)
    SET(${PARENT}_VISCA_CAMERA                          ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_VISCA_CAMERA_TEST                     OFF CACHE BOOL "" FORCE)
    SET(${PARENT}_VISCA_CAMERA_EXAMPLE                  OFF CACHE BOOL "" FORCE)
endif()

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

if (${PARENT}_SUBMODULE_FRAME)
    add_subdirectory(Frame)
endif()

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

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

if (${PARENT}_SUBMODULE_VISCA_PARSER)
    add_subdirectory(ViscaParser)
endif()

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

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

if (${PARENT}_SUBMODULE_PAN_TILT)
    add_subdirectory(PanTilt)
endif()

if (${PARENT}_SUBMODULE_VISCA_CAMERA)
    add_subdirectory(ViscaCamera)
endif()

File 3rdparty/CMakeLists.txt adds the dependencies and the folder ViscaCamera to your project and excludes the test applications and the examples from compiling (by default test application and example are excluded from compiling if ViscaCamera is included as sub-repository). Next you need include folder 3rdparty in main CMakeLists.txt file of your repository. Add string at the end of your main CMakeLists.txt:

add_subdirectory(3rdparty)

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

target_link_libraries(${PROJECT_NAME} ViscaCamera)

If the dependencies are not added by your project the build stops with an error like Lens.h: No such file or directory.

Done!

Portability

The library is written in standard C++17 (compiler extensions are switched off). VISCA packets are built byte by byte, so the library does not depend on the byte order or on the alignment of the CPU. The library was built and tested with GCC 9, 11 and 12 on Linux x86-64 and with GCC 11 for Linux aarch64 (the aarch64 programs were run in an emulator): the commands that the library queues for the camera and the parameter values that it reports are identical on both architectures. Builds with MSVC and clang and 32-bit builds are not tested.

Simple example

Simple example is application which initializes controller, checks the result of every call and provides few options to control camera: it opens the controller, waits until the camera answers, sets the contrast, moves the pan-tilt, zooms and prints the zoom position.

#include <chrono>
#include <iostream>
#include <string>
#include <thread>
#include "ViscaCamera.h"

/// Serial port name and baudrate of the camera.
constexpr const char* INIT_STRING{"/dev/ttyUSB0;9600"};
/// Time to wait for the answer of the camera, milliseconds.
constexpr int CONNECTION_TIMEOUT_MS{5000};
/// Period of the zoom position output, milliseconds.
constexpr int OUTPUT_PERIOD_MS{100};
/// Number of the zoom position outputs.
constexpr int OUTPUT_NUMBER{50};

int main()
{
    // Create camera controller object.
    rapidpixel::ViscaCamera controller;

    // Get references to different interfaces.
    rapidpixel::Lens& lens = controller;
    rapidpixel::Camera& camera = controller;
    rapidpixel::PanTilt& pantilt = controller;

    // Open camera connection (camera, lens or pan-tilt). The three interfaces
    // use the same serial port: it is enough to open one of them.
    if (!lens.openLens(INIT_STRING))
    {
        std::cout << "Can't open the serial port" << std::endl;
        return 1;
    }

    // The camera is connected when it answers to the requests.
    for (int time = 0; time < CONNECTION_TIMEOUT_MS &&
         !lens.isLensConnected(); time += OUTPUT_PERIOD_MS)
    {
        std::this_thread::sleep_for(
                    std::chrono::milliseconds(OUTPUT_PERIOD_MS));
    }
    if (!lens.isLensConnected())
    {
        std::cout << "The camera does not answer" << std::endl;
        return 1;
    }

    // Set camera parameter: contrast, 0 - 100 %.
    if (!camera.setParam(rapidpixel::CameraParam::CONTRAST, 50.0f))
    {
        std::cout << "Can't set contrast" << std::endl;
        return 1;
    }

    // Move pan tilt to the angles: pan 10 degrees, tilt 0 degrees.
    if (!pantilt.executeCommand(
                rapidpixel::PanTiltCommand::GO_TO_PAN_TILT_ANGLE, 10.0f,
                0.0f))
    {
        std::cout << "Can't move pan-tilt" << std::endl;
        return 1;
    }

    // Zoom to position command: 0 (full wide) - 65535 (full tele).
    if (!lens.executeCommand(rapidpixel::LensCommand::ZOOM_TO_POS, 65535.0f))
    {
        std::cout << "Can't zoom" << std::endl;
        return 1;
    }

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

    // The connection is closed by the destructor.
    return 0;
}

Test application

ViscaCamera/test folder contains test application which demonstrates how to use ViscaCamera library. The test application has two modes.

Without command line options the test application is an interactive tester of a camera connected to a serial port. The tester asks for the serial port name (baudrate 9600 and camera address 1 are used), opens the camera, lens and pan-tilt interfaces and shows the main menu. The main menu allows to set and get params of the lens, camera and pan-tilt and to execute commands. A text which is not a number is skipped, the tester exits at the end of the input.

Test application output will look like:

================================================
ViscaCamera tester v1.2.5
================================================
Enter serial port name: /dev/ttyUSB0
Chose option:
1 - Set lens param
2 - Get lens param
3 - Set camera param
4 - Get camera param
5 - Set pantilt param
6 - Get pantilt param
7 - Execute lens command
8 - Execute camera command
9 - Execute pantilt command
-1 - Exit

With the option –self-test the test application runs automatic tests which do not need a camera: values of all supported params and commands (valid and rejected, including NaN and infinity), read back of the stored values, decoding of commands (including damaged data), wrong init strings, opening and closing of a virtual serial port (Linux only) and calls from several threads. Every test prints one line with the result, the application returns 0 if all the tests passed and 1 if not. The tests do not create files. Output of the tests:

Version: OK
Camera params: OK
Lens params: OK
Pan-tilt params and commands: OK
Lens and camera commands: OK
Decode and execute command: OK
Open and close: OK
Virtual serial port: OK
Threads: OK
ALL TESTS PASSED

Table of contents