PopSift
PopSift is an open-source implementation of the SIFT algorithm in CUDA.
PopSift tries to stick as closely as possible to David Lowe's famous paper [1], while extracting features from an image in real-time at least on an NVidia GTX 980 Ti GPU.
Check out the documentation for more info.
HW requirements
PopSift compiles and works with NVidia cards of compute capability >= 3.0 (including the GT 650M), but the code is developed with the compute capability 5.2 card GTX 980 Ti in mind.
CUDA SDK 11 does no longer support compute capability 3.0. 3.5 is still supported with deprecation warnings.
PopSift also runs on AMD GPUs through ROCm/HIP (validated on gfx90a and gfx1100, and on Windows gfx1151); see the USE_HIP build option below.
Dependencies
PopSift depends on:
Optionally, for the provided applications:
-
Boost >= 1.71 (required components {atomic, chrono, date-time, system, thread}-dev)
-
DevIL (libdevil-dev) can be used to load a broader range of image formats, otherwise only pgm is supported.
Build
To build the library, you can run:
mkdir build && cd build
cmake ..
make
make install
Some build options are available:
-
PopSift_BUILD_EXAMPLES (default: ON) enable building the applications that showcase the use of the library.
-
BUILD_SHARED_LIBS (default: ON) controls the type of library to build (ON for shared libraries, OFF for static)
-
USE_HIP (default: OFF) builds for AMD GPUs through ROCm/HIP instead of CUDA (requires a ROCm installation); see "Building for AMD GPUs (ROCm/HIP)" below.
Building for AMD GPUs (ROCm/HIP)
With a ROCm installation, configure with -DUSE_HIP=ON to build the GPU code through HIP instead of CUDA. The CUDA build path is unchanged when USE_HIP=OFF (the default).
cmake .. -DUSE_HIP=ON -DCMAKE_HIP_ARCHITECTURES=gfx90a \
-DCMAKE_HIP_COMPILER=/opt/rocm/llvm/bin/clang++ \
-DCMAKE_PREFIX_PATH=/opt/rocm
make
Point -DCMAKE_PREFIX_PATH at the ROCm install prefix (/opt/rocm for a default install) so CMake can locate the hip and rocThrust packages when ROCm is not already on the search path.
Set the target architecture with -DCMAKE_HIP_ARCHITECTURES (e.g. gfx90a, gfx1100); pass a semicolon-separated list such as "gfx90a;gfx1100" to emit a fat binary.
Windows (gfx1151 / TheRock ROCm)
Tested with the ROCm wheels from TheRock (see its README for installing the Windows wheels). The steps below assume <rocm> is that install prefix and that clang from it is on PATH:
cmake .. -DUSE_HIP=ON -DCMAKE_HIP_ARCHITECTURES=gfx1151 ^
-DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang -DCMAKE_HIP_COMPILER=clang ^
-DCMAKE_PREFIX_PATH=<rocm> -DPopSift_BUILD_EXAMPLES=OFF ^
-DCMAKE_LINKER_TYPE=LLDFIX ^
-DCMAKE_C_USING_LINKER_LLDFIX=-fuse-ld=lld ^
-DCMAKE_CXX_USING_LINKER_LLDFIX=-fuse-ld=lld ^
-DCMAKE_HIP_USING_LINKER_LLDFIX=-fuse-ld=lld
cmake --build . --config Release
The CMAKE_LINKER_TYPE=LLDFIX block works around the -fgpu-rdc device link: CMake otherwise emits -fuse-ld=lld-link, which AMD clang rejects under --hip-link. At runtime, copy a matching amdhip64 and amd_comgr from <rocm> next to the executable (a System32 Adrenalin-driver runtime can be device-library mismatched).
On the gfx1151 APU, maxTexture2DLayered is smaller than on gfx90a, so the default upscale can overflow for large images; use native-resolution downsampling (Config::setDownsampling(0)) or cap the input size.
Usage
The main artifact created is libpopsift.
If enabled, the test application popsift-demo is created as well.
Calling popsift-demo without parameters shows the options.
Using PopSift as third party
To integrate PopSift into other software, link with libpopsift.
If you are using CMake for building your project, you can easily add PopSift to your project.
Once you have built and installed PopSift in a directory (say, <prefix>), in your CMakeLists.txt file just add the dependency
# 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(poptest yourfile.cpp)
# add link to the library
target_link_libraries(poptest PUBLIC PopSift::popsift)
Then, to build just pass the location of PopSiftConfig.cmake from the cmake command line:
cmake .. -DPopSift_DIR=<prefix>/lib/cmake/PopSift/
Calling the API
The caller must create a popart::Config struct (documented in src/sift/sift_conf.h) to control the behaviour of the PopSift, and instantiate an object of class PopSift (found in src/sift/popsift.h).
After this, images can be enqueued for SIFT extraction using (enqueue()).
A valid input is a single plane of grayscale values located in host memory.
They can be passed as a pointer to unsigned char, with a value range from 0 to 255, or as a pointer to float, with a value range from 0.0f to 1.0f.
Only host memory limits the number of images that can be enqueued.
The enqueue function returns a pointer to a SiftJob immediately and performs the feature extraction asynchronously.
The memory of the image passed to enqueue remains the caller's responsibility. Calling SiftJob::get on the returned job blocks until features are extracted, and returns them.
[1]: Lowe, D. G. (2004). Distinctive Image Features from Scale-Invariant Keypoints. International Journal of Computer Vision, 60(2), 91–110. doi:10.1023/B:VISI.0000029664.99615.94
This is the beginning of the README. Read the rest at the original. Read the full README ↗
