Image Processing Template

Image Processing Template

Specs

This is a template project for IP. It contains a handful of utilities and it should be considered as a playground for image processing. It should work on any device with conan and cmake installed.

It features:

.cpp and .h files are automatically included into the main executable
Automatic target_include_directories via the HEADER_DIRECTORIES CMAKE macro
Mini script runner to enchance the build process.
Lightweight macro wrappers over spdlog (for debugging)

Currently, windows requires manual adjustments for OpenCV's find_package.

Notes

The following folder structure is mandatory

assets \
  exports

The following packages are mandatory:

gcc make cmake python conan opencv

Setup the requirements on your system

Arch Linux

sudo pacman -S base-devel cmake opencv

There is a Conan AUR package

yay -S conan

Unknown Linux

Search for base devel packages, usually every distro has one.

Debian based example:

apt-get install build-essential

Check the conan installation options. You can go for the python package installation via pip.

pip install conan

MacOS

Homebrew instructions are available here.

brew install opencv

brew update && brew upgrade && brew cleanup

brew install pkg-config

Taken from the conan download options available:

brew install conan

Windows

Manual setup is required. After the installation of CMake and Conana, you must download the OpenCV library and point find_package(OpenCV REQUIRED) to the correct location or manually overwrite ${OpenCV_LIBS} such that target_link_libraries(${PROJECT_NAME} PUBLIC ${OpenCV_LIBS}) works

Build

Generally, the order is

Install dependencies
Build
Run

Several ways to do that will be provided, both using the helper script, and without using it.

At the time of writing this, the conan version used is Conan version 1.44.0 with experimental features enabled. Future versions of conan (>2.0+) should not be affected.

The following aliases are used in this document:

alias run="./run.sh"
alias log="./log_run.sh"

Both run and log accept the same arguments, that of the command to run. Both commands will log runtime information, however log.sh will also log the whole building process.

Help menu

run help

Example:
  run clean build opengl_template
  run opengl_template
  run build
  run clean build
  run clean
  run conan

  :help   displays this message
  :clean  clean build folder
  :build  build project
  :exec   execute the executable
  :cb     clean build shorthand
  :conan  same as build
  :dependencies  conan install dependencies

The run script will take its arguments and execute them sequentially.

Custom commands can be provided as stringified paths to the run command.

Since this is a simple script, i recommend to read it for further customisation and understanding of the build process.

Get up and running

run clean dependencies build execute

Fast rebuild and run

run build execute

Build without the helper script

# Create build folder
mkdir build 
cd build
# Copy dependencies that will be compiled alongside this project
conan source .. --source-folder dependencies
# Build and Link other dependencies that do not require dependency management
conan install .. --build missing
# Build the project
conan build ..

Recommendations

VSCode

If using VSCode, I recommend the following settings for command-runner.

"command-runner.terminal.autoClear": true,
"command-runner.terminal.autoFocus": true,
"command-runner.commands": {
  "install": "./run.sh dependencies",
  "build": "./run.sh conan",
  "run": "./run.sh conan execute",
  "clean": "./run.sh clean",
  "build run": "./run.sh dependencies conan execute",
  "log build": "./log_run.sh dependencies conan",
  "log run": "./log_run.sh conan execute",
  "log build run": "./log_run.sh dependencies conan execute"
}

Now useful commands are accesible via the CTRL + SHIFT + R shortcut.

If you want to extend the build process with packages that are not on the conan repository, you can fill in the source method of the ImageProcessingTemplate class inside the conan.py file.

More details about extending the codebase using source can be read here.

CLion

I recommend using the VSCode setup, it provides enough functionality and intelisence. However, if you are going for CLion, try to explicitly disable the automatic append of new files in the add_executable() statement of the CMakeLists.txt file. It is redundant since it already scans for all the .cpp and .h and includes them in the executable. This can cause errors such as function x redefined here or undefined refference to x.

VisualStudio

Bruh...

GaussianWonder/image-processing