formatconverteropencv_logo

FormatConverterOpenCv C++ library

v5.0.7

Overview
Versions
Library files
FormatConverterOpenCv class description
Build and connect to your project

Overview

FormatConverterOpenCv library intended to convert pixels formats of images between each others. FormatConverterOpenCv supports all uncompressed pixel formats (conversion between each other) listed in Fourcc enum (RGB24, BGR24, YUYV, UYVY, GRAY, YUV24, NV12, NV21, YU12, YV12) of Frame library (defines video frame object and pixel formats). FormatConverterOpenCv uses OpenCV library (version 4.5.0 and more) to convert particular pixel formats. Main file FormatConverterOpenCv.h contains declaration of FormatConverterOpenCv class. The motivation of the library is to provide conversion method between all pixel formats listed in Frame library even if it is not supported by OpenCV library. The library uses C++17 standard and compatible with Linux and Windows.

Versions

Table 1 - Library versions.

Version	Release date	What’s new
1.0.0	08.09.2020	First version.
2.0.0	19.11.2020	- New formats added.
3.0.0	20.12.2020	- Code optimized.
4.0.0	20.01.2023	- Programming interface changed.
5.0.0	19.03.2023	- New base Frame class added. - Programming interface changed.
5.0.1	29.05.2023	- Frame class updated.
5.0.2	12.11.2023	- Frame class updated.
5.0.3	04.01.2024	- Frame class updated. - Documentation updated.
5.0.4	20.03.2024	- Frame class updated. - Default constructor and destructor removed. - Documentation updated.
5.0.5	17.05.2024	- Frame class updated. - Documentation updated.
5.0.6	07.07.2024	- Frame class updated. - CMake updated. - Copy data between same fourcc fixed.
5.0.7	23.07.2024	- Files structure changed.

Library files

The library is supplied only by source code. The user is given a set of files in the form of a CMake project (repository). The repository structure is shown below:

CMakeLists.txt ------------------------- Main CMake file of the library.
3rdparty ------------------------------- Folder with third-party libraries.
    CMakeLists.txt --------------------- CMake file for to include third-party libraries.
    Frame ------------------------------ Folder with Frame library source code.
src ------------------------------------ Folder with library source code.
    CMakeLists.txt --------------------- CMake file of the library.
    FormatConverterOpenCv.cpp ---------- C++ implementation file.
    FormatConverterOpenCv.h ------------ Main library header file.
    FormatConverterOpenCvVersion.h ----- Header file with library version.
    FormatConverterOpenCvVersion.h.in -- Service CMake file to generate version file.
    Impl ------------------------------- Folder with format converter implementation.
        FormatConverterOpenCvImpl.cpp -- C++ implementation file.
        FormatConverterOpenCvImpl.h ---- Format converter implementation header file.
test ----------------------------------- Folder for test application.
    CMakeLists.txt --------------------- CMake file of the test application.
    main.cpp --------------------------- Source C++ file of the test application.
    logo_GRAY.cpp ---------------------- Source file which contains test image data.
    logo_NV12.cpp ---------------------- Source file which contains test image data.
    logo_NV21.cpp ---------------------- Source file which contains test image data.
    logo_RGB24.cpp --------------------- Source file which contains test image data.
    logo_UYVY.cpp ---------------------- Source file which contains test image data.
    logo_YU12.cpp ---------------------- Source file which contains test image data.
    logo_YUV24.cpp --------------------- Source file which contains test image data.
    logo_YUYV.cpp ---------------------- Source file which contains test image data.
    logo_YV12.cpp ---------------------- Source file which contains test image data.

FormatConverterOpenCv class description

FormatConverterOpenCv class declaration

FormatConverterOpenCv.h file contains FormatConverterOpenCv class declaration. Class declaration:

namespace cr
{
namespace video
{
/// Frame pixel format converter class.
class FormatConverterOpenCv
{
public:

    /// Static method to obtain class version.
    static std::string getVersion();

    /// Convert pixel format.
    bool convert(Frame& src, Frame& dst);
};
}
}

convert method

The convert(…) method intended to convert Frame class data between pixel formats. The method understands which pixel format to convert from based on the fourcc field of the Frame class objects. Method declaration:

bool convert(Frame& src, Frame& dst);

Parameter	Description
src	Source Frame object. Method doesn’t support H264, HEVC and JPEG pixel formats.
dst	Destination Frame object. User must at least initialize fourcc field of destination Frame object. Method doesn’t support H264, HEVC and JPEG pixel formats.

Returns: TRUE if pixel format converted or FALSE if not.

Example:

// Init frame converter.
FormatConverterOpenCv converter;

// Init source image filled by 0.
Frame src(640, 480, Fourcc::BGR24);

// Init output image.
Frame dst;
dst.fourcc = Fourcc::YUV24;

// Convert.
converter.convert(src, dst);

getVersion method

The getVersion() method returns string of current version of FormatConverterOpenCv class. Method declaration:

static std::string getVersion();

Method can be used without Frame class instance. Example:

cout << "FormatConverterOpenCv class version: " << FormatConverterOpenCv::getVersion() << endl;

Console output:

FormatConverterOpenCv class version: 5.0.6

Build and connect to your project

Before build user should install OpenCV library and additional libraries to build project. Typical install commands in Linux:

sudo apt-get install build-essential cmake libopencv-dev

Typical commands to build FormatConverterOpenCv library:

cd FormatConverterOpenCv
mkdir build
cd build
cmake ..
make

If you want to connect FormatConverterOpenCv library to your CMake project as source code, you can do the following. For example, if your repository has structure:

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

Create folder 3rdparty in your repository folder and copy FormatConverterOpenCv repository folder there. The new structure of your repository will be as follows:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    FormatConverterOpenCv

Create CMakeLists.txt file in 3rdparty folder. CMakeLists.txt should be containing:

cmake_minimum_required(VERSION 3.13)

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

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

################################################################################
## CONFIGURATION
## 3rd-party submodules configuration
################################################################################
SET(${PARENT}_SUBMODULE_FORMAT_CONVERTER_OPENCV         ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_FORMAT_CONVERTER_OPENCV)
    SET(${PARENT}_FORMAT_CONVERTER_OPENCV               ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_FORMAT_CONVERTER_OPENCV_TEST          OFF CACHE BOOL "" FORCE)
endif()

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

File 3rdparty/CMakeLists.txt adds folder FormatConverterOpenCv to your project and excludes test application from compiling (by default test application excluded from compiling if FormatConverterOpenCv included as sub-repository). The new structure of your repository will be:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    CMakeLists.txt
    FormatConverterOpenCv

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

add_subdirectory(3rdparty)

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

target_link_libraries(${PROJECT_NAME} FormatConverterOpenCv)

Done!