Requirements¶
Hardware¶
PopSift is a GPU implementation that requires an NVIDIA GPU card with a CUDA compute capability >= 3.0 (including, e.g. the GT 650M). The code is originally developed with the compute capability 5.2 card GTX 980 Ti in mind.
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 PopSift:
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¶
The core library depends only on Cuda >= 7.0
The library includes a few sample applications that show how to use the library. They require
Boost >= 1.55 (required components atomic, chrono, date-time, system, thread)
[optionally] DevIL (libdevil-dev) can be used to load a broader range of image formats, otherwise only pgm is supported.
vcpkg¶
vcpkg is a cross-platform (Windows, Linux and MacOS), open-source package manager created by Microsoft.
We are planning to release a port of the library so that it can be easily built using the package manager on all supported platforms. Stay tuned!
Building the library¶
Building tools¶
Required tools:
CMake >= 3.14 to build the code
Git
C/C++ compiler supporting the C++11 standard (gcc >= 4.6 or visual studio or clang)
CUDA >= 7.0
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 cuda devil boost-system boost-program-options boost-thread boost-filesystem
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 libboost-all-dev libdevil-dev
For CentOS package system:
sudo yum install gcc-c++ git boost-devel devil
Getting the sources¶
git clone https://github.com/alicevision/PopSift.git
CMake configuration¶
From PopSift 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.
CMake options¶
CMake configuration can be controlled by changing the values of the following variables (here with their default value)
BUILD_SHARED_LIBS:BOOL=ON
to enable/disable the building shared librariesPopSift_BUILD_EXAMPLES:BOOL=ON
to enable/disable the building of applicationsPopSift_BUILD_DOC:BOOL=OFF
to enable/disable building this documentation and the Doxygen one.
For example, if you do not want to build the applications, you have to pass -DPopSift_BUILD_EXAMPLES:BOOL=OFF
and so on.
PopSift as third party¶
When you install PopSift a file PopSiftConfig.cmake
is installed in <install_prefix>/lib/cmake/PopSift/
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 2 3 4 5 6 7 8 9 10 | # Find the package from the PopSiftConfig.cmake
# in <prefix>/lib/cmake/PopSift/. Under the namespace PopSift::
# it exposes the target PopSift that allows you to compile
# and link with the library
find_package(PopSift CONFIG REQUIRED)
...
# suppose you want to try it out in a executable
add_executable(popsiftTest yourfile.cpp)
# add link to the library
target_link_libraries(popsiftTest PUBLIC PopSift::PopSift)
|
Then, in order to build just pass the location of PopSiftConfig.cmake
from the cmake command line:
cmake .. -DPopSift_DIR=<install_prefix>/lib/cmake/PopSift/
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 PopSift 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/popsift-deps:cuda8.0-ubuntu18.04 -f Dockerfile_deps .
The complete list of available tags can be found on the nvidia [dockerhub page](https://hub.docker.com/r/nvidia/cuda/)
Building the PopSift image¶
Once you built the dependency image, you can build the popsift image in the same manner using Dockerfile
:
docker build --tag alicevision/popsift:cuda8.0-ubuntu18.04 .
Running the PopSift 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/popsift:cuda8.0-ubuntu18.04
Official images on DockeHub¶
Check the docker hub PopSift repository for the available images.