Start Now

English | 简体中文

---

Before you start contributing

• Make sure you agree to contribute your code under FlyCV (Apache 2.0) license.
• You have to agree with the FlyCV Contributor License Agreement（CLA）.
• You should fully understand our workflow and coding standards.
• Always check if a new feature already exists before developing.
• If you're going to fix a bug, make sure it's still there in the latest version.

Now let's see how to develop a function module.

Source Directory Structure

First of all, we need to understand the directory organization of the source code.

benchmark                        // performance test
cmake                            // cmake files
  ├── external                   // configuration for dependent libraries
  ├── platform                   // configuration about platforms
  └── ......
docs
  └── assets                     // assets for documents
include
  ├── flycv.h.in                 // user-oriented interface
  ├── flycv_namespace.h.in       // namespace record
  └── version.h.in               // version record
modules                          // function implementation directory              
  ├── img_transform              // module A
  │      ├── color_convert       // function ①
  │      ├── resize              // function ②
  │      ├── warp_affine         // function ③
  │      └── ......              // other functions
  ├── fusion_api                 // module B
  ├── img_calculation            // module C
  └── ......                     // other modules
scripts                          // compile scripts for different platforms
samples                          // demo for different platforms
tests                            // unit test
third_party                      // dependent libraries
tools                            // tools for developing
  └── add_module                 // python scripts for quickly adding new functions

How to add a new function

To make it easier for everyone to develop, We provide a tool to quickly generate templates.

You can use the script to add a new function. The script location is tools/add_module.

To use the script, You need to follow the steps below.

1. Install python dependencies

sudo pip3 install Jinja2

2. Add a new module

python3 tools/add_module.py modules/<parent_module>/<child_module> <ON|OFF>

parent_module: Corresponds to the folder in the modules directory.

child_module: Corresponds to the folder in the specific function directory.

ON|OFF: Specify whether to enable compilation by default for new modules.

for example:

python3 tools/add_module/add_module.py modules/img_transform/blur OFF

After executing the above command, view the changes with git status.

On branch my-work
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   cmake/FCVBuildList.cmake
	modified:   include/flycv.h.in

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	benchmark/modules/img_transform/blur_bench.cpp
	modules/img_transform/blur/
	tests/modules/img_transform/blur_test.cpp

Here is a brief introduction to these files:

1. cmake/FalconCVBuildList.cmake : Automatically add compile option in the file.

option(WITH_FCV_BLUR "Build module blur" OFF)

2. include/falconcv.h.in : The header file automatically added to the user-oriented file.

#cmakedefine WITH_FCV_BLUR

#ifdef WITH_FCV_BLUR
#include "modules/img_transform/blur/interface/blur.h"
#endif

3. View the generated module directory structure.

modules/img_transform/blur
    ├── include
    │   └── blur_common.h
    ├── interface
    │   └── blur.h
    └── src
        ├── blur.cpp
        └── blur_common.cpp

interface： user-oriented header files directory
include：   internal header files directory
src：       implementation directory

4. tests/modules/img_transform/blur_test.cpp : unit test file.

5. benchmark/modules/img_transform/blur_bench.cpp : performance test file.

Then you can fully focus on writing functional code.

Compile

Please refer to the compilation documentation. We provide compilation methods for different platforms.

Unit Test

Like many open source libraries, we use GoogleTest as our unit test framework, learn about GoogleTest.

The tool generates a simple unit test template, here is an example.

class BlurTest : public ::testing::Test {
    void SetUp() override {
        // (optional) prepare test data for every case
    }
};

TEST_F(BlurTest, PositiveInput) {
    // add your test code here
}

Just modify this file to complete the test case.

Benchmark Test

we use benchmark as our performance test framework, learn about benchmark.

The tool generates a simple performance test template, here is an example.

class BlurBench : public benchmark::Fixture {
public:
    void SetUp(const ::benchmark::State& state) {
        set_thread_num(G_THREAD_NUM);

        // (optional) prepare test data for every case
    }
};

BENCHMARK_DEFINE_F(BlurBench, PlaceHolder)
        (benchmark::State& state) {
    // add your code here
    // don't forget to replace the PlaceHolder with a meaningful one
};

// don't forget to replace the PlaceHolder with a meaningful one
BENCHMARK_REGISTER_F(BlurBench, PlaceHolder)
        ->Unit(benchmark::kMicrosecond)
        ->Iterations(100)
        ->DenseRange(55, 255, 200);

Just modify this file to complete the performance test case.