Requirements¶
Hardware¶
CCTag has a CPU and a GPU implementation. The GPU implementation requires an NVIDIA GPU card with a CUDA compute capability >= 3.5. You can check your NVIDIA GPU card CC support here or on the NVIDIA dev page. If you do not have a NVIDIA card you will still able to compile and use the CPU version.
Here are the minimum hardware requirements for CCTag:
Minimum requirements |
|
---|---|
Operating systems |
Windows x64, Linux, macOS |
CPU |
Recent Intel or AMD cpus |
RAM Memory |
8 GB |
Hard Drive |
No particular requirements |
GPU |
NVIDIA CUDA-enabled GPU (compute capability >= 3.5) |
Software¶
CCTag depends on the following libraries:
Eigen3 >= 3.3.4
Boost >= 1.66
OpenCV >= 3.1
TBB >= 2021.5.0
Warning
In order to have Cuda support on Windows, at least Eigen 3.3.9 is required
CCTag can be installed from the following package managers.
vcpkg¶
vcpkg is a cross-platform (Windows, Linux and MacOS), open-source package manager created by Microsoft.
Since v1.0.0 of the library it is possible to build and install the library through vcpkg on Linux, Windows and MacOS by running:
vcpkg install cctag[cuda,apps]
where cuda
and apps
are the options to build the library with the cuda support and the sample applications, respectively.
conan¶
conan is a decentralized and multi-platform package manager.
Since v1.0.1, you can install CCTag from conan by running:
conan install cctag/1.0.1@
where 1.0.1@
is the version you want to install. See CCTag as third party for how to use CCTag as third party in your project.
Building the library¶
Building tools¶
Required tools:
CMake >= 3.14 to build the code
Git
C/C++ compiler supporting the C++14 standard (gcc >= 5, clang >= 3.4, msvc >= 2017)
Optional tool:
CUDA >= 9.0
Note
On Windows, there are compatibility issues to build the GPU part due to conflicts between msvc/nvcc/thrust/eigen/boost.
Dependencies¶
vcpkg¶
vcpkg can be used to install all the dependencies on all the supported platforms. This is particularly useful on Windows. To install the dependencies:
vcpkg install
boost-accumulators
boost-algorithm
boost-container
boost-date-time
boost-exception
boost-filesystem
boost-iterator
boost-lexical-cast
boost-math
boost-mpl
boost-multi-array
boost-ptr-container
boost-program-options
boost-serialization
boost-spirit
boost-static-assert
boost-stacktrace
boost-test
boost-thread
boost-throw-exception
boost-timer
boost-type-traits
boost-unordered
opencv
tbb
eigen3
You can add the flag --triplet
to specify the architecture and the version you want to build.
For example:
--triplet x64-windows
will build the dynamic version for Windows 64 bit--triplet x64-windows-static
will build the static version for Windows 64 bit--triplet x64-linux-dynamic
will build the dynamic version for Linux 64 bit
and so on. More information can be found here
Linux¶
On Linux you can install from the package manager:
For Ubuntu/Debian package system:
sudo apt-get install g++ git-all libpng12-dev libjpeg-dev libeigen3-dev libboost-all-dev libtbb-dev
For CentOS package system:
sudo yum install gcc-c++ git libpng-devel libjpeg-turbo-devel eigen3-devel boost-devel tbb-devel
MacOS¶
On MacOs using Homebrew install the following packages:
brew install git libpng libjpeg eigen boost tbb
Getting the sources¶
git clone https://github.com/alicevision/CCTag.git
CMake configuration¶
From CCTag root folder you can run cmake:
mkdir build && cd build
cmake ..
make -j `nproc`
On Windows add -G "Visual Studio 16 2019" -A x64
to generate the Visual Studio solution according to your VS version (see CMake documentation).
If you are using the dependencies built with VCPKG you need to pass -DCMAKE_TOOLCHAIN_FILE=path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
at cmake step to let it know where to find the dependencies.
Otherwise you can specify the path where each dependency can be found (if not installed in system folders) by passing its related path.
For example, for OpenCV you can pass -DOpenCV_DIR=path/to/opencv/install/share/OpenCV/
to tell where the OpenCVConfig.cmake
file can be found.
CMake options¶
CMake configuration can be controlled by changing the values of the following variables (here with their default value)
CCTAG_WITH_CUDA:BOOL=ON
to enable/disable the Cuda implementationBUILD_SHARED_LIBS:BOOL=ON
to enable/disable the building shared librariesCCTAG_ENABLE_SIMD_AVX2:BOOL=OFF
to enable/disable the AVX2 optimizationsCCTAG_BUILD_TESTS:BOOL=OFF
to enable/disable the building of the unit testsCCTAG_BUILD_APPS:BOOL=ON
to enable/disable the building of applicationsCCTAG_BUILD_DOC:BOOL=OFF
to enable/disable building this documentation
So if you do not want to build the Cuda part, you have to pass -DCCTAG_WITH_CUDA:BOOL=OFF
and so on.
CCTag as third party¶
When you install CCTag a file CCTagConfig.cmake
is installed in <install_prefix>/lib/cmake/CCTag/
that allows you to import the library in your CMake project.
In your CMakeLists.txt
file you can add the dependency in this way:
1# Find the package from the CCTagConfig.cmake
2# in <prefix>/lib/cmake/CCTag/. Under the namespace CCTag::
3# it exposes the target CCTag that allows you to compile
4# and link with the library
5find_package(CCTag CONFIG REQUIRED)
6...
7# suppose you want to try it out in a executable
8add_executable(cctagtest yourfile.cpp)
9# add link to the library
10target_link_libraries(cctagtest PUBLIC CCTag::CCTag)
Then, in order to build just pass the location of CCTagConfig.cmake
from the cmake command line:
cmake .. -DCCTag_DIR=$CCTAG_INSTALL/lib/cmake/CCTag/
If you are using conan for your project then you need to add cctag to your conanfile.txt
:
[requires]
cctag/1.0.1
[generators]
CMakeToolchain
CMakeDeps
and when building you may need to follow these steps:
mkdir build
cd build
conan install .. -s build_type=Release
cmake .. -DCMAKE_TOOLCHAIN_FILE=conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release
Docker image¶
A docker image can be built using the Ubuntu based Dockerfile
, which is based on nvidia/cuda image (https://hub.docker.com/r/nvidia/cuda/ )
Building the dependency image¶
We provide a Dockerfile_deps
containing a cuda image with all the necessary CCTag dependencies installed.
A parameter CUDA_TAG
can be passed when building the image to select the cuda version.
Similarly, OS_TAG
can be passed to select the Ubuntu version.
By default, CUDA_TAG=10.2
and OS_TAG=18.04
For example to create the dependency image based on ubuntu 18.04 with cuda 8.0 for development, use
docker build --build-arg CUDA_TAG=8.0 --tag alicevision/cctag-deps:cuda8.0-ubuntu18.04 -f Dockerfile_deps .
The complete list of available tags can be found on the nvidia dockerhub page
Building the CCTag image¶
Once you built the dependency image, you can build the cctag image in the same manner using Dockerfile
:
docker build --tag alicevision/cctag:cuda8.0-ubuntu18.04 .
Running the CCTag image¶
In order to run the image nvidia docker is needed: see the installation instruction. Once installed, the docker can be run, e.g., in interactive mode with
docker run -it --runtime=nvidia alicevision/cctag:cuda8.0-ubuntu18.04
Official images on DockeHub¶
Check the docker hub CCTag repository for the available images.