Skip to content

Latest commit

 

History

History
212 lines (141 loc) · 10.5 KB

BUILDING.md

File metadata and controls

212 lines (141 loc) · 10.5 KB

Building MoonRegistration library from source code

If you only want to get library binary, consider download pre-build binary or build using docker

Build System

This project uses CMake (version >= 3.11) as its build system. You need to install CMake in your system first

Build & Use MoonRegistration library natively

To build and use MoonRegistration library natively, you need to have OpenCV C++ library installed in your system. Checkout OpenCV version & modules that we use. And learn more about how to get OpenCV

Note

MoonRegistration-js library is an exception: it is a WASM + JavaScript library runs on the browser, so it doesn't require you to install OpenCV natively. You just need to download the release archive and extract it and use it as Node.js module.

About OpenCV versions & modules

This library is heavily rely on OpenCV, linking with different version of OpenCV or with different OpenCV modules will enable/disable some feature of the library.

Starting from version 4.8.1, OpenCV provide a new algorithm (HOUGH_GRADIENT_ALT) for hough circle detection function, thus increase the overall accuracy. If this library is linked with OpenCV >= 4.8.1, the MoonDetect module will use an optimized circle detection pipeline utilizing the new algorithm from OpenCV by default. Otherwise, the MoonDetect module will use the original HOUGH_GRADIENT algorithm for circle detection.

OpenCV Contrib is a set of community contributed extra modules thats not include in the main repository. Some modules and algorithms inside maybe patented in some countries or have some other limitations on the use. The MoonRegistrate module uses some image registration algorithms from OpenCV Contrib module. Therefore, when linking with an OpenCV that doesn't contain OpenCV Contrib, part of the image registration algorithms are not available.

Table below is a list of non-free modules & algorithms from OpenCV Contrib that we use, and the image registration algorithms relating to it.

non-free OpenCV modules used non-free OpenCV algorithms used mr::RegistrationAlgorithms related
XFeatures2D SURF SURF_NONFREE

Note

When OpenCV Contrib is not present, above mr::RegistrationAlgorithms are not available.

How to get OpenCV Contrib

OpenCV Contrib is not included in normal OpenCV release. If you want to enable those non-free registration algorithms, you need to:

Build Using Docker (recommend)

Dependencies

Build library

build the docker image with:

docker build -t moonregistration -f ./dockerfiles/cpp_demo.dockerfile .

once docker image is built, all MoonRegistration library is inside the container, launch the container by:

docker run -it --rm --name moonregistration moonregistration

built library binaries are inside folder /src/MoonRegistration/build

all the build environments are set, so you can easily rebuild the library following these steps and modify build arguments

Build release package

build the docker image with:

docker build -t moonregistration -f ./dockerfiles/release_env.dockerfile .

once docker image is built, all MoonRegistration library is inside the container, launch the container by:

docker run -it --rm --name moonregistration moonregistration

built library release packages are in /src/MoonRegistration/*.zip archives

all the build environments are set, so you can easily rebuild the library following these steps and modify build arguments

Develope with Dev Container

You can use Docker container to develope this library.

  • If you use VSCode as your Editor, you can follow this doc to install docker and VSCode Dev Container Extension.
    • After installation, you can use VSCode Command Palette to search & execute command: Dev Containers: Reopen in Container
    • This command will reopen this folder inside a Dev Container
    • If git is breaking inside Dev Container, follow this doc to fix it.
  • If you don't use VSCode as your Editor, you can launch a container from ./dockerfiles/dev_env.dockerfile and trying to connect to it.
    • Remember to mount repository root into this container.

Build with vcpkg

vcpkg is a cross-platform C++ Library Manager (Dependency Package Manager). You can use it for easy dependency setup. In following examples, we will use powershell as our shell, checkout this doc for other shells and more detail.

Note

vcpkg will download and build opencv4 for your machine, so it will take a while.

Note

Until March 24, 2024, vcpkg only have opencv version 4.8.0. Which means you cannot use HOUGH_CIRCLE_ALT algorithm for MoonDetect module (learn more here). Checkout this manifest file for the latest version.

  1. Setup vcpkg
# get vcpkg
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg; .\bootstrap-vcpkg.bat
# setup environment variables
$env:VCPKG_ROOT = "C:\path\to\vcpkg"
$env:PATH = "$env:VCPKG_ROOT;$env:PATH"
  1. Go to MoonRegistration repository root and install dependency
vcpkg install
  1. Now, you can use the dependency you just built to build MoonRegistration. You need to use vcpkg's cmake toolchain file with cmake.
mkdir build
# set cmake toolchain file using cmake flag
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"
# or set cmake toolchain file using environment variable
$env:CMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"
cmake -S . -B build

Build Manually from Source

Dependencies

Build Steps

# clone this repo
git clone --recursive https://github.com/Gavin1937/MoonRegistration

cd MoonRegistration

mkdir build && cd build

# use cmake to build the library
cmake ..
cmake --build .

CMake Build Arguments

  • Build Static / Shared Library
    • You can tell cmake to build the library into a shared library by setting -DMR_BUILD_SHARED_LIBS=ON (this is on by default)
    • Or, you can turn it off to build the library into a static library -DMR_BUILD_SHARED_LIBS=OFF
  • Use Custom build of opencv
    • You can tell cmake to use your opencv build with flag -DOPENCV_DIR. This flag should point to a folder that contains cmake files like "OpenCVConfig.cmake" or "opencv-config.cmake"
  • Specify OpenCV modules to link
    • By default, MoonRegistration will link with following OpenCV modules:
      • opencv_core
      • opencv_flann
      • opencv_calib3d
      • opencv_imgcodecs
      • opencv_imgproc
      • opencv_features2d
      • opencv_xfeatures2d (when MR_ENABLE_OPENCV_NONFREE is enable)
    • You can change these modules by setting cmake flag -DOpenCV_LIBS_TO_USE=module1;module2;module3
  • To enable MoonRegistration library to use OpenCV non-free modules and algorithms, you can set cmake flag -DMR_ENABLE_OPENCV_NONFREE=ON. By default, this option is OFF by default.

Install with CMake

To install this library with cmake, simply use cmake --install command:

cmake --install /path/to/build/dir --prefix /path/to/install/dir

If you don't supply --prefix flag, cmake will try to install all the library & header files to:

  • If in Windows or is cross-compiling this library, install to:
    • "${CMAKE_BINARY_DIR}/install"
  • Otherwise install to:
    • "/usr/local"

Tip

Checkout ./demo/CMakeLists.txt for an example of linking with MoonRegistration install directory or release package