hitachicamera_web_logo

HitachiCamera C++ library

v2.0.9

Table of contents

Overview

The HitachiCamera C++ library is a software controller for Hitachi HD-SDI Camera Series. The HitachiCamera library inherits interface from Camera. It depends on libraries: Camera (provides interface and data structures to control cameras, depends on the ConfigReader library), Logger (provides function to print log information in console and files), SerialPort (provides functions to work with serial ports). The repositories of these libraries are not part of the HitachiCamera repository: see Build and connect to your project. The HitachiCamera library provides simple interface to be integrated in any C++ projects. The library repository (folder) provided by source code and doesn’t have third-party dependencies to be specially installed in OS. It is developed with C++17 standard and compatible with Linux and Windows.

HitachiCamera is general-purpose software: it is not tied to any sector or application, and the developer of a program decides what the program does with it.

The library code was developed by reverse engineering the serial port communication protocol of the cameras.

Versions

Table 1 - Library versions.

Version Release date What’s new
1.0.0 30.05.2023 - First version.
2.0.0 20.10.2023 - New Camera interface.
2.0.1 21.02.2024 - Camera interface updated.
- Examples added.
- Documentation updated.
2.0.2 29.04.2024 - Code reviewed.
- Documentation updated.
2.0.3 23.04.2024 - Submodules updated.
- Documentation updated.
2.0.4 07.08.2024 - CMake structure updated.
2.0.5 03.04.2025 - Logger submodule update.
2.0.6 26.10.2025 - SerialPort submodule update.
2.0.7 17.09.2026 - Menu commands fixed: MenuOn and MenuOff now send the menu-operation open and close frames the camera documents, instead of the menu-display flag, which is what made the menu open only sometimes.
- MenuOn / MenuOff now update displayMode in CameraParams, so the OSD state is readable through getParam / getParams.
- Seven parameters - GainMode, AgcMode, DefogMode, BlackAndWhiteFilterMode, AlcGate, ChromaLevel, Detail - were stubs that reported success without sending anything or caching the value; they now work.
- ChromaLevel and Detail encoded the value in decimal because the hex manipulator was applied to a float, and Detail wrote the value into the checksum field; both fixed.
- Serial exchange rewritten: the ENQ/ACK session the camera requires is now opened, the reply is checked so a rejection (NAK) is reported as failure, the wait is a deadline rather than a fixed pause, and the receive drain can no longer spin forever on a closed port.
- One command transaction at a time: the shared frame buffers are now serialised.
2.0.8 12.10.2026 - Submodules updated.
2.0.9 17.10.2026 - Sub-repositories removed: the repositories of the Camera, ConfigReader, SerialPort and Logger libraries are expected next to the library folder (stand alone build) or are added by the parent project.
- Frames for the camera are built by one function from the relative address and the data bytes (frames sent to the camera for valid values are not changed).
- ALC_GATE value 11 is rejected (it sent the CHROMA_LEVEL command); CHROMA_LEVEL and DETAIL accept only values from 0 to 100 (values from -1 to 0 and from 100 to 101 were accepted: values below -0.39 and above 100.4 produced a wrong frame).
- NaN, infinity and values outside the int range are rejected without undefined behavior.
- Command frames are built in a local buffer: commands from several threads no longer share a buffer. Opening and closing of the port are serialised with commands. The serial port is closed by the destructor.
- getParam(LOG_MODE) returns the log mode.
- openCamera rejects a baudrate which is not greater than 0, decodeAndExecuteCommand rejects nullptr.
- Example and test application rewritten: the test application controls the camera only through the terminal.
- Compiler warnings fixed, compiler and linker hardening options added, documentation updated.

Library files

The library supplied by source code only. The user would be given a set of files in the form of a CMake project (repository). The repository doesn’t include the libraries it depends on. The repository structure is shown below:

CMakeLists.txt ----------------- Main CMake file of the library.
static ------------------------- Folder with the logo of the library.
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.
src ---------------------------- Folder with source code of the library.
    CMakeLists.txt ------------- CMake file of the library.
    HitachiCamera.cpp ---------- C++ implementation file.
    HitachiCamera.h ------------ Header file which includes HitachiCamera class declaration.
    HitachiCameraVersion.h ----- Header file which includes version of the library.
    HitachiCameraVersion.h.in -- CMake service file to generate version file.

HitachiCamera class description

HitachiCamera Class declaration

The HitachiCamera class declared in HitachiCamera.h file. The HitachiCamera class inherits from Camera interface. All public methods are thread-safe. Commands to the camera are sent one at a time: a method which sends a command waits until the command which is in progress is finished. Class declaration:

class HitachiCamera : public rapidpixel::Camera
{
public:

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

    /// Class constructor.
    HitachiCamera() = default;

    /// Class destructor. The serial port is closed.
    ~HitachiCamera() override;

    /// The class is not copyable and not movable.
    HitachiCamera(const HitachiCamera&) = delete;
    HitachiCamera(HitachiCamera&&) = delete;
    HitachiCamera& operator= (const HitachiCamera&) = delete;
    HitachiCamera& operator= (HitachiCamera&&) = delete;

    /// Init camera controller.
    bool openCamera(std::string initString) override;

    /// Init camera controller by parameters class.
    bool initCamera(CameraParams& params) override;

    /// Close camera serial port.
    void closeCamera() override;

    /// Get camera open status.
    bool isCameraOpen() override;

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

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

    /// Get the camera controller param.
    float getParam(CameraParam id) override;

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

    /// Execute camera controller action command.
    bool executeCommand(CameraCommand id) override;

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

getVersion method

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

static std::string getVersion();

Method can be used without HitachiCamera class instance:

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

Console output:

HitachiCamera class version: 2.0.9

openCamera method

The openCamera(…) opens serial port to communicate with Hitachi camera. Method declaration:

bool openCamera(std::string initString) override;
Parameter Value
initString Initialization string. Format : [serial port name];[baudrate];
For example : “/dev/ttyUSB0;9600” (“/dev/ttyUSB0” - serial port name, “9600” - baudrate). The baudrate must be a decimal number greater than 0 (characters after the number are ignored). Fields after the baudrate are ignored.

Nothing is sent to the camera and the stored camera parameters are not changed. The serial port is opened with 8 data bits, no parity and 1 stop bit. If the serial port is already open the method returns TRUE and doesn’t change the serial port (the init string is not checked against the init string of the open port).

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

initCamera method

The initCamera(…) initializes controller and sets camera params (Camera interface). The method will call openCamera(…) method and then will set given camera params in the order: log mode (before the serial port is opened), display mode, black and white filter mode, ALC gate, defog mode, detail, chroma level, AGC mode, gain mode, profile. Method declaration:

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

Returns: TRUE if the serial port is open or FALSE if not. The result of each parameter is not part of the return value: a value which is not valid is skipped, a value which the camera doesn’t acknowledge is stored anyway (see setParam(…)). Use isCameraConnected() to check the data exchange with the camera.

closeCamera method

The closeCamera() method closes serial port. The method waits for the command which is in progress. After closing the open status and the connection status are FALSE. Method declaration:

void closeCamera() override;

isCameraOpen method

The isCameraOpen() method returns serial port open 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 inactive (no power). In this case open status just shows that the serial port is open. Method declaration:

bool isCameraOpen() override;

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

isCameraConnected method

The isCameraConnected() shows if the controller receives responses from equipment (camera). For example, if serial port is open but equipment inactive (no power). In this case method isCameraOpen(…) will return TRUE but isCameraConnected() method will return FALSE. The HitachiCamera library checks connection status every time when send command to camera: the status is TRUE after the camera answered the command (also if the camera rejected the command) and FALSE if the camera didn’t answer or the serial port is not open. Method declaration:

bool isCameraConnected() override;

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

setParam method

The setParam(…) method sets new camera controller parameter value. The value is converted to int: the fractional part is discarded, NaN, infinity and values outside of the int range are rejected. The values of CHROMA_LEVEL and DETAIL must be from 0 to 100: the stored value is the value without the fractional part and the camera gets the value multiplied by 2.55 (the result without the fractional part, 0 - 255). The method returns FALSE without sending anything to the camera if the value is not valid. The stored parameter value is changed before the command is sent and it is not restored if the camera doesn’t acknowledge the command. Supported parameters and their values are described in Table 3. Method declaration:

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

Returns: TRUE if the parameter was set (the camera acknowledged the command; LOG_MODE is not sent to the camera: TRUE if the value is valid) or FALSE if the parameter is not supported, the value is not valid, the serial port is not open, the camera rejected the command or didn’t answer.

getParam method

The getParam(…) method intended to obtain Camera parameter value. Method declaration:

float getParam(CameraParam id) override;
Parameter Description
id Camera controller parameter ID according to CameraParam enum.

The method returns the values which were set by setParam(…) method, it doesn’t read the camera.

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

getParams method

The getParams(…) method intended to obtain Camera parameters structure. Method declaration:

void getParams(CameraParams& params) override;
Parameter Description
params Reference to CameraParams class object.

executeCommand method

The executeCommand(…) method intended to execute Camera action command. Supported commands are described in Table 2. MENU_ON and MENU_OFF change the stored DISPLAY_MODE parameter after the camera acknowledged the command. Method declaration:

bool executeCommand(CameraCommand id) override;
Parameter Description
id Camera controller command ID according to CameraCommand enum.

Returns: TRUE if the command was executed (the camera acknowledged it) or FALSE if the command is not supported, the serial port is not open, the camera rejected the command or didn’t answer.

decodeAndExecuteCommand method

The decodeAndExecuteCommand(…) method decodes and executes command on controller side. Method will decode commands which encoded by encodeCommand(…) and encodeSetParamCommand(…) methods of Camera interface class. If command decoded, the method will call setParam(…) or executeCommand(…) methods for camera 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 data. Must not be nullptr. The method can’t check that the buffer is valid for size bytes: this is the contract of the method.
size Size of command. Must be 11 bytes for SET_PARAM and 7 bytes for COMMAND.

Returns: TRUE if command decoded (SET_PARAM or COMMAND) and executed (action command or set param command) or FALSE if not (nullptr, wrong size, wrong command or the command failed).

encodeSetParamCommand method of Camera class

encodeSetParamCommand(…) static method of Camera interface class encodes command to change any remote camera parameter value. To control a camera remotely, the developer has to design his own protocol and according to it encode the command and deliver it over the communication channel. To simplify this, the Camera class contains static methods for encoding the control command. The Camera class provides two types of commands: a parameter change command (SET_PARAM) and an action command (COMMAND). encodeSetParamCommand(…) designed to encode SET_PARAM command. Method declaration:

static void encodeSetParamCommand(uint8_t* data, int& size, CameraParam id, float value);
Parameter Description
data Pointer to data buffer for encoded command. Must not be nullptr. The method can’t check that the buffer is valid for 11 bytes: this is the contract of the method.
size Size of encoded data, bytes. Is 11 after encoding and 0 if data is nullptr.
id Parameter ID according to CameraParam enum.
value Parameter value. The value is not checked: it is transported as is (also NaN and infinity).

encodeSetParamCommand(…) is static and used without Camera class instance. This method used on client side (control system). Command encoding example:

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

encodeCommand method of Camera class

encodeCommand(…) static method of Camera interface class encodes command for camera remote control. To control a camera remotely, the developer has to design his own protocol and according to it encode the command and deliver it over the communication channel. To simplify this, the Camera class contains static methods for encoding the control command. The Camera class provides two types of commands: a parameter change command (SET_PARAM) and an action command (COMMAND). encodeCommand(…) designed to encode COMMAND command (action command). Method declaration:

static void encodeCommand(uint8_t* data, int& size, CameraCommand id);
Parameter Description
data Pointer to data buffer for encoded command. Must not be nullptr. The method can’t check that the buffer is valid for 7 bytes: this is the contract of the method.
size Size of encoded data, bytes. Is 7 after encoding and 0 if data is nullptr.
id Command ID according to CameraCommand enum.

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

// Buffer for encoded data.
uint8_t data[7];
// Size of encoded data.
int size = 0;
// Encode command.
rapidpixel::Camera::encodeCommand(
        data, size, rapidpixel::CameraCommand::MENU_ON);

decodeCommand method of Camera class

decodeCommand(…) static method of Camera interface class decodes command on camera controller side. The method checks the pointer, the size, the version and the ID: the ID must be inside the range of CameraCommand or CameraParam enum. The output arguments are changed only if the command was decoded. Method declaration:

static int decodeCommand(uint8_t* data, int size, CameraParam& paramId, CameraCommand& commandId, float& value);
Parameter Description
data Pointer to input command. Must not be nullptr.
size Size of command. Must be 11 bytes for SET_PARAM and 7 bytes for COMMAND.
paramId Camera parameter ID according to CameraParam enum. After decoding SET_PARAM command the method will return parameter ID.
commandId Camera command ID according to CameraCommand enum. After decoding COMMAND the method will return command ID.
value Camera parameter value (after decoding SET_PARAM command) or 0 (after decoding COMMAND).

Returns: 0 - in case decoding COMMAND, 1 - in case decoding SET_PARAM command or -1 in case errors (nullptr, wrong size, wrong version, ID outside of the enum).

Data structures

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 image.
    FREEZE,
    /// Disable freeze. The last value of the enum.
    DEFREEZE
};

Table 2 - Camera commands description.

Command Description
RESTART Not supported by HitachiCamera library.
NUC Not supported by HitachiCamera library.
APPLY_PARAMS Not supported by HitachiCamera library.
SAVE_PARAMS Not supported by HitachiCamera library.
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 Not supported by HitachiCamera library.
DEFREEZE Not supported by HitachiCamera 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.
    DISPLAY_MODE,
    /// Video output type.
    VIDEO_OUTPUT,
    /// Logging mode.
    LOG_MODE,
    /// Exposure mode.
    EXPOSURE_MODE,
    /// Exposure time of the camera sensor.
    EXPOSURE_TIME,
    /// White balance mode.
    WHITE_BALANCE_MODE,
    /// White balance area.
    WHITE_BALANCE_AREA,
    /// White dynamic range mode.
    WIDE_DYNAMIC_RANGE_MODE,
    /// Image stabilization mode.
    STABILIZATION_MODE,
    /// ISO sensitivity.
    ISO_SENSITIVITY,
    /// Scene mode.
    SCENE_MODE,
    /// FPS.
    FPS,
    /// Brightness mode.
    BRIGHTNESS_MODE,
    /// Brightness. Value 0 - 100%.
    BRIGHTNESS,
    /// Contrast. Value 1 - 100%.
    CONTRAST,
    /// Gain mode.
    GAIN_MODE,
    /// Gain. Value 1 - 100%.
    GAIN,
    /// Sharpening mode.
    SHARPENING_MODE,
    /// Sharpening. Value 1 - 100%.
    SHARPENING,
    /// Palette.
    PALETTE,
    /// Analog gain control mode.
    AGC_MODE,
    /// Shutter mode.
    SHUTTER_MODE,
    /// Shutter position. 0 (full close) - 65535 (full open).
    SHUTTER_POSITION,
    /// Shutter speed. Value: 0 - 100%.
    SHUTTER_SPEED,
    /// Digital zoom mode.
    DIGITAL_ZOOM_MODE,
    /// Digital zoom. Value 1.0 (x1) - 20.0 (x20).
    DIGITAL_ZOOM,
    /// Exposure compensation mode.
    EXPOSURE_COMPENSATION_MODE,
    /// Exposure compensation position. 
    EXPOSURE_COMPENSATION_POSITION,
    /// Defog mode.
    DEFOG_MODE,
    /// Dehaze mode.
    DEHAZE_MODE,
    /// Noise reduction mode.
    NOISE_REDUCTION_MODE,
    /// Black and white filter mode.
    BLACK_WHITE_FILTER_MODE,
    /// Filter mode.
    FILTER_MODE,
    /// NUC mode for thermal cameras.
    NUC_MODE,
    /// Auto NUC interval for thermal cameras. 
    AUTO_NUC_INTERVAL_MSEC,
    /// Image flip mode.
    IMAGE_FLIP,
    /// DDE mode.
    DDE_MODE,
    /// DDE level.
    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.
    ALC_GATE,
    /// Sensor sensitivity.
    SENSITIVITY,
    /// Changing mode (day / night).
    CHANGING_MODE,
    /// Changing level (day / night).
    CHANGING_LEVEL,
    /// Chroma level. Values: 0 - 100%.
    CHROMA_LEVEL,
    /// Details, enhancement. Values: 0 - 100%.
    DETAIL,
    /// Camera settings profile.
    PROFILE,
    /// Connection status (read only). Shows if we have response from camera.
    /// Value: 0 - not connected, 1 - connected.
    IS_CONNECTED,
    /// Open status (read only):
    /// 1 - camera control port open, 0 - not open.
    IS_OPEN,
    /// Camera type.
    TYPE,
    /// Camera custom param.
    CUSTOM_1,
    /// Camera custom param.
    CUSTOM_2,
    /// Camera custom param. The last value of the enum.
    CUSTOM_3
};

Table 3 - Camera params description.

Parameter Access Description
WIDTH read / write Not supported by HitachiCamera library.
HEIGHT read / write Not supported by HitachiCamera library.
DISPLAY_MODE read / write Display mode. Values:
0 - Menu Off
1 - Menu On
VIDEO_OUTPUT read / write Not supported by HitachiCamera 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 Not supported by HitachiCamera library.
EXPOSURE_TIME read / write Not supported by HitachiCamera library.
WHITE_BALANCE_MODE read / write Not supported by HitachiCamera library.
WHITE_BALANCE_AREA read / write Not supported by HitachiCamera library.
WIDE_DYNAMIC_RANGE_MODE read / write Not supported by HitachiCamera library.
STABILIZATION_MODE read / write Not supported by HitachiCamera library.
ISO_SENSITIVITY read / write Not supported by HitachiCamera library.
SCENE_MODE read / write Not supported by HitachiCamera library.
FPS read / write Not supported by HitachiCamera library.
BRIGHTNESS_MODE read / write Not supported by HitachiCamera library.
BRIGHTNESS read / write Not supported by HitachiCamera library.
CONTRAST read / write Not supported by HitachiCamera library.
GAIN_MODE read / write Gain mode (the camera gets the same command as for AGC_MODE). Values:
0 - Off
1 - AUTOx2
2 - AUTOx4
3 - AUTOx6
4 - AUTOx8
5 - AUTOx10
6 - AUTOx12
7 - AUTOx16
8 - AUTOx32
GAIN read / write Not supported by HitachiCamera library.
SHARPENING_MODE read / write Not supported by HitachiCamera library.
SHARPENING read / write Not supported by HitachiCamera library.
PALETTE read / write Not supported by HitachiCamera library.
AGC_MODE read / write AGC mode (the camera gets the same command as for GAIN_MODE). Values:
0 - Off
1 - AUTOx2
2 - AUTOx4
3 - AUTOx6
4 - AUTOx8
5 - AUTOx10
6 - AUTOx12
7 - AUTOx16
8 - AUTOx32
SHUTTER_MODE read / write Not supported by HitachiCamera library.
SHUTTER_POSITION read / write Not supported by HitachiCamera library.
SHUTTER_SPEED read / write Not supported by HitachiCamera library.
DIGITAL_ZOOM_MODE read / write Not supported by HitachiCamera library.
DIGITAL_ZOOM read only Not supported by HitachiCamera library.
EXPOSURE_COMPENSATION_MODE read only Not supported by HitachiCamera library.
EXPOSURE_COMPENSATION_POSITION read / write Not supported by HitachiCamera library.
DEFOG_MODE read / write Defog mode. Values:
0 - Off
1 - Low
2 - Medium
3 - High
DEHAZE_MODE read / write Not supported by HitachiCamera library.
NOISE_REDUCTION_MODE read / write Not supported by HitachiCamera library.
BLACK_WHITE_FILTER_MODE read / write Black white filter mode. Values:
0 - Off
1 - On
2 - AutoHigh
3 - AutoMed
4 - AutoLow
FILTER_MODE read / write Not supported by HitachiCamera library.
NUC_MODE read / write Not supported by HitachiCamera library.
AUTO_NUC_INTERVAL_MSEC read / write Not supported by HitachiCamera library.
IMAGE_FLIP read / write Not supported by HitachiCamera library.
DDE_MODE read / write Not supported by HitachiCamera library.
DDE_LEVEL read / write Not supported by HitachiCamera library.
ROI_X0 read / write Not supported by HitachiCamera library.
ROI_Y0 read / write Not supported by HitachiCamera library.
ROI_X1 read / write Not supported by HitachiCamera library.
ROI_Y1 read / write Not supported by HitachiCamera library.
TEMPERATURE read only Not supported by HitachiCamera library.
ALC_GATE read / write ALC gate mode (value 1 and value 2 send the same command to the camera). Values:
0 - Off
1 - On
2 - Zone1
3 - Zone2
4 - Zone3
5 - Zone4
6 - Zone5
7 - Zone6
8 - Zone7
9 - Zone8
10 - Zone9
SENSITIVITY read / write Not supported by HitachiCamera library.
CHANGING_MODE read / write Not supported by HitachiCamera library.
CHANGING_LEVEL read / write Not supported by HitachiCamera library.
CHROMA_LEVEL read / write Chroma level, per cent. Values: 0 - 100. Sent to the camera as 0 - 255.
DETAIL read / write Detail (sharpness) level, per cent. Values: 0 - 100. Sent to the camera as 0 - 255.
PROFILE read / write Camera profile. Values: 0 - 4 (FILE1 - FILE5).
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 (method will return 0). It 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 Controller initialization status. Open status shows if the controller initialized or not but doesn’t show if controller has communication with equipment. For example, if serial port open but equipment can be not active (no power). In this case open status just shows that the controller has opened serial port. Values: 0 - not open (not initialized), 1 - open (initialized).
TYPE read / write Not supported by HitachiCamera library.
CUSTOM_1 read / write Not supported by HitachiCamera library.
CUSTOM_2 read / write Not supported by HitachiCamera library.
CUSTOM_3 read / write Not supported by HitachiCamera library.

CameraParams class description

CameraParams class used for camera controller initialization or to get all actual params. Also CameraParams provide structure to write/read params from JSON files (JSON_READABLE macro) and provide methods to encode and decode params.

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};
    /// White 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. All fields have default values.
    CameraParams() = default;

    /// Copy and move constructors, copy and move assignment operators.
    CameraParams(const CameraParams& src) = default;
    CameraParams(CameraParams&& src) = default;
    CameraParams& operator= (const CameraParams& src) = default;
    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 doesn't decode initString.
    bool decode(uint8_t* data, int dataSize);
};

Table 4 - CameraParams class fields description is equivalent to CameraParam enum description.

Field type Description
initString string Initialization string contains full serial port name, baudrate separated by “;”. Fields after the baudrate are ignored. Example: “/dev/ttyUSB0;9600”. Default value: “/dev/ttyUSB0;9600;20”.
width int Not supported by HitachiCamera class.
height int Not supported by HitachiCamera class.
displayMode int Display mode. Values:
0 - Menu Off
1 - Menu On
videoOutput int Not supported by HitachiCamera class.
logMode int Logging mode. Values:
0 - Disable
1 - Only file
2 - Only terminal (console)
3 - File and terminal
exposureMode int Not supported by HitachiCamera class.
exposureTime int Not supported by HitachiCamera class.
whiteBalanceMode int Not supported by HitachiCamera class.
whiteBalanceArea int Not supported by HitachiCamera class.
wideDynamicRangeMode int Not supported by HitachiCamera class.
stabilizationMode int Not supported by HitachiCamera class.
isoSensitivity int Not supported by HitachiCamera class.
sceneMode int Not supported by HitachiCamera class.
fps float Not supported by HitachiCamera class.
brightnessMode int Not supported by HitachiCamera class.
brightness int Not supported by HitachiCamera class.
contrast int Not supported by HitachiCamera class.
gainMode int Gain mode. Values:
0 - Off
1 - AUTOx2
2 - AUTOx4
3 - AUTOx6
4 - AUTOx8
5 - AUTOx10
6 - AUTOx12
7 - AUTOx16
8 - AUTOx32
gain int Not supported by HitachiCamera class.
sharpeningMode int Not supported by HitachiCamera class.
sharpening int Not supported by HitachiCamera class.
palette int Not supported by HitachiCamera class.
agcMode int AGC mode. Values:
0 - Off
1 - AUTOx2
2 - AUTOx4
3 - AUTOx6
4 - AUTOx8
5 - AUTOx10
6 - AUTOx12
7 - AUTOx16
8 - AUTOx32
shutterMode int Not supported by HitachiCamera class.
shutterPos int Not supported by HitachiCamera class.
shutterSpeed int Not supported by HitachiCamera class.
digitalZoomMode int Not supported by HitachiCamera class.
digitalZoom float Not supported by HitachiCamera class.
exposureCompensationMode int Not supported by HitachiCamera class.
exposureCompensationPosition int Not supported by HitachiCamera class.
defogMode int Defog mode. Values:
0 - Off
1 - Low
2 - Medium
3 - High
dehazeMode int Not supported by HitachiCamera class.
noiseReductionMode int Not supported by HitachiCamera class.
blackAndWhiteFilterMode int Black white filter mode. Values:
0 - Off
1 - On
2 - AutoHigh
3 - AutoMed
4 - AutoLow
filterMode int Not supported by HitachiCamera class.
nucMode int Not supported by HitachiCamera class.
autoNucIntervalMsec int Not supported by HitachiCamera class.
imageFlip int Not supported by HitachiCamera class.
ddeMode int Not supported by HitachiCamera class.
ddeLevel float Not supported by HitachiCamera class.
roiX0 int Not supported by HitachiCamera class.
roiY0 int Not supported by HitachiCamera class.
roiX1 int Not supported by HitachiCamera class.
roiY1 int Not supported by HitachiCamera class.
temperature float Not supported by HitachiCamera class.
alcGate int ALC gate mode. Values:
0 - Off
1 - On
2 - Zone1
3 - Zone2
4 - Zone3
5 - Zone4
6 - Zone5
7 - Zone6
8 - Zone7
9 - Zone8
10 - Zone9
sensitivity float Not supported by HitachiCamera class.
changingMode int Not supported by HitachiCamera class.
changingLevel float Not supported by HitachiCamera class.
chromaLevel int Chroma level, per cent. Values: 0 - 100. Sent to the camera as 0 - 255.
detail int Detail (sharpness) level, per cent. Values: 0 - 100. Sent to the camera as 0 - 255.
profile int Profile. Values: 0 - 4 (FILE1 - FILE5).
isConnected bool 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 (method will return 0). It 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.
isOpen bool Controller initialization status. Open status shows if the controller initialized or not but doesn’t show if controller has communication with equipment. For example, if serial port open but equipment can be not active (no power). In this case open status just shows that the controller has opened serial port. Values: 0 - not open (not initialized), 1 - open (initialized).
type int Not supported by HitachiCamera class.
custom1 float Not supported by HitachiCamera class.
custom2 float Not supported by HitachiCamera class.
custom3 float Not supported by HitachiCamera class.

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

Serialize camera params

CameraParams class provides method encode(…) to serialize camera params. Serialization of camera params necessary in case when you have to send camera params via communication channels. Method doesn’t encode initString field. Method provides options to exclude particular parameters from serialization. To do this method inserts binary mask (8 bytes) where each bit represents particular parameter and decode(…) method recognizes it. The values are stored in the byte order of the host. 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. The method can’t check that the buffer is valid for bufferSize bytes: this is the contract of the method.
bufferSize Data buffer size, bytes. Buffer size must be >= 237 bytes (the size of the data with all fields selected).
size Size of encoded data, bytes. Set to 0 if the method returns FALSE.
mask Parameters mask - pointer to CameraParamsMask structure. If nullptr all fields are encoded. CameraParamsMask (declared in Camera.h file) determines flags for each field (parameter) declared in CameraParams class. If the user wants to exclude any parameters from serialization, he can put a pointer to the mask. If the user wants to exclude a particular parameter from serialization, he should set the corresponding flag in the CameraParamsMask structure to false.

Returns: TRUE if params encoded (serialized) or FALSE if not (data is nullptr or bufferSize is too small).

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:

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

Example with parameters mask:

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

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

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

Deserialize camera params

CameraParams class provides method decode(…) to deserialize camera params (fields of CameraParams class, see Table 4). Deserialization of camera params necessary in case when you need to receive params via communication channels. Method automatically recognizes which parameters were serialized by encode(…) method. The method checks the data type, the version and the size of the data before reading each field. A field which is not selected by the mask of the encoded data is set to zero (false). Method doesn’t decode initString field: it is set to an empty string. Values of the fields are not checked against any range: the camera controller validates them. 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 the serialized data, bytes. Must be >= 11 (the size of the data without fields).

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

Example:

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

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

Read and write camera params to JSON file

Camera library depends on ConfigReader library which provides method to read params from JSON file and to write params to JSON file. The fields temperature, isConnected and isOpen are not stored in JSON. Example of writing and reading params to JSON file:

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

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

TestCameraParams.json will look like:

{
    "cameraParams": {
        "initString": "/dev/ttyUSB0;9600;20",
        "width": 0,
        "height": 0,
        "displayMode": 0,
        "videoOutput": 0,
        "logMode": 0,
        "exposureMode": 1,
        "exposureTime": 0,
        "whiteBalanceMode": 1,
        "whiteBalanceArea": 0,
        "wideDynamicRangeMode": 0,
        "stabilizationMode": 0,
        "isoSensitivity": 0,
        "sceneMode": 0,
        "fps": 0.0,
        "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": 50,
        "detail": 0,
        "profile": 3,
        "type": 0,
        "custom1": 0.0,
        "custom2": 0.0,
        "custom3": 0.0
    }
}

Build and connect to your project

Build stand alone

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

<work folder>
    HitachiCamera
    ConfigReader
    Camera
    SerialPort
    Logger

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

git clone <HitachiCamera repository URL>
git clone <ConfigReader repository URL>
git clone <Camera repository URL>
git clone <SerialPort repository URL>
git clone <Logger repository URL>
cd HitachiCamera
mkdir build
cd build
cmake ..
make

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

CMake options

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

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

Connect to your project

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

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

Create folder 3rdparty and copy folders of the HitachiCamera repository and of the repositories of the libraries it depends on there (ConfigReader, Camera, SerialPort, Logger). New structure of your repository:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    HitachiCamera
    ConfigReader
    Camera
    SerialPort
    Logger

Create CMakeLists.txt file in 3rdparty folder. CMakeLists.txt should contain the libraries in dependency order (a library is added after the libraries it depends on):

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)
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_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_HITACHI_CAMERA                  ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_HITACHI_CAMERA)
    SET(${PARENT}_HITACHI_CAMERA                        ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_HITACHI_CAMERA_TEST                   OFF CACHE BOOL "" FORCE)
    SET(${PARENT}_HITACHI_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_CAMERA)
    add_subdirectory(Camera)
endif()

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

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

if (${PARENT}_SUBMODULE_HITACHI_CAMERA)
    add_subdirectory(HitachiCamera)
endif()

File 3rdparty/CMakeLists.txt adds the folders to your project and excludes test applications and examples from compiling (by default test application and example are excluded from compiling if HitachiCamera is included as sub-repository). When HitachiCamera is included in another project it doesn’t add the libraries it depends on: they must be added by your project (as above), otherwise the compiler stops with an error like “Camera.h: No such file or directory”. The new structure of your repository:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    CMakeLists.txt
    HitachiCamera
    ConfigReader
    Camera
    SerialPort
    Logger

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

target_link_libraries(${PROJECT_NAME} HitachiCamera)

Done!

Portability

The library doesn’t depend on the byte order of the host: the data sent to the camera is ASCII text. The library doesn’t contain SIMD code. The library was built with GCC 11 and GCC 12 for x86-64 Linux and with the GCC 11 cross compiler for aarch64 Linux (run under qemu): the data sent to the camera is the same on both architectures.

Simple example

Simple example is application which initializes controller and provide few options to user to control camera.

#include <algorithm>
#include <cstdlib>
#include <iostream>
#include <string>
#include "HitachiCamera.h"

namespace
{
/// Step of the chroma level change, per cent.
constexpr int CHROMA_STEP{10};

/// Range of the chroma level, per cent.
constexpr int CHROMA_MIN{0};
constexpr int CHROMA_MAX{100};

/// Change the chroma level of the camera by the step. The result is kept
/// inside of the range of the chroma level.
bool changeChroma(rapidpixel::HitachiCamera& controller, int step)
{
    rapidpixel::CameraParams cameraParams;
    controller.getParams(cameraParams);
    const int level = std::min(
            std::max(cameraParams.chromaLevel + step, CHROMA_MIN), CHROMA_MAX);
    return controller.setParam(rapidpixel::CameraParam::CHROMA_LEVEL,
                               static_cast<float>(level));
}
}

int main()
{
    // Init camera controller.
    rapidpixel::HitachiCamera controller;
    if (!controller.openCamera("/dev/ttyUSB0;9600"))
    {
        std::cout << "Can't open the serial port." << std::endl;
        return 1;
    }

    while (true)
    {
        // Main dialog.
        std::cout << "Options (1:Menu on, 2:Menu off, 3:Chroma+10, "
                  << "4:Chroma-10, 0:Exit) : ";
        std::string line;
        if (!std::getline(std::cin, line))
        {
            return 0;
        }
        char* end = nullptr;
        const long option = std::strtol(line.c_str(), &end, 10);
        if (line.empty() || *end != '\0')
        {
            std::cout << "Wrong option." << std::endl;
            continue;
        }

        bool done = true;
        switch (option)
        {
        case 0:
            return 0;
        case 1:
            done = controller.executeCommand(
                        rapidpixel::CameraCommand::MENU_ON);
            break;
        case 2:
            done = controller.executeCommand(
                        rapidpixel::CameraCommand::MENU_OFF);
            break;
        case 3:
            done = changeChroma(controller, CHROMA_STEP);
            break;
        case 4:
            done = changeChroma(controller, -CHROMA_STEP);
            break;
        default:
            std::cout << "Wrong option." << std::endl;
            break;
        }
        if (!done)
        {
            std::cout << "The camera did not accept the command." << std::endl;
        }
    }
}

Test application

Folder HitachiCamera/test contains the test application files. The test application controls the camera only through the terminal: it has no video output and no graphical user interface. The test application allows user to set params, get params, execute commands and show all params. User must enter the full serial port name (for example /dev/ttyUSB0 for Linux or COM3 for Windows) and baudrate. The application ends when the user enters -1 or when the input is closed.

Test application output will look like:

========================================
HitachiCamera v2.0.9 test.
========================================
Enter serial port name: /dev/ttyUSB0
Enter baudrate: 9600

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

Camera params:
3 - DISPLAY_MODE (0 - menu off, 1 - menu on)
5 - LOG_MODE (0 - disable, 1 - file, 2 - terminal, 3 - file and terminal)
18 - GAIN_MODE (0 - off, 1 - 8 - AUTOx2, x4, x6, x8, x10, x12, x16, x32)
23 - AGC_MODE (0 - off, 1 - 8 - AUTOx2, x4, x6, x8, x10, x12, x16, x32)
31 - DEFOG_MODE (0 - off, 1 - low, 2 - medium, 3 - high)
34 - BLACK_WHITE_FILTER_MODE (0 - off, 1 - on, 2 - auto high, 3 - auto medium, 4 - auto low)
46 - ALC_GATE (0 - off, 1 - on, 2 - 10 - zone 1 - 9)
50 - CHROMA_LEVEL (0 - 100 per cent)
51 - DETAIL (0 - 100 per cent)
52 - PROFILE (0 - 4 (FILE1 - FILE5))

Choose param (-1 to exit to main menu): 50
Set CHROMA_LEVEL (0 - 100 per cent): 50
OK

Table of contents