Installation

Python Package

The VQF Python package can easily be installed from PyPI via pip, e.g.:

pip install vqf

(Depending on your Python installation, it might be necessary to use pip3 instead of pip and/or to add the --user option.)

C++ Implementation

In order to use the C++ implementation in your own project, simply add the two files vqf.hpp and vqf.cpp to your project.

The files are located in the directory vqf/cpp/ of the repository. They are also shipped when installing the Python package. In order to find out the installation path, use the following command:

python -c "import vqf; print(vqf.get_cpp_path())"

The basic implementation is also self-contained and consists of the two files basicvqf.hpp and basicvqf.cpp. In order to compile the offline version, the files offline_vqf.hpp, offline_vqf.cpp. vqf.hpp, and vqf.cpp are needed.

CMake

VQF also provides CMake. support, so you can easily add VQF to your CMake project. Here is an example CMakeLists.txt file for a project which consists of a single file main.cpp:

cmake_minimum_required(VERSION 3.10)

project(myproject)

add_executable(myproject main.cpp)

# <Insert one of the 3 snippets below here...>

target_link_libraries(myproject PUBLIC vqf)

You can download and add VQF to CMake via several methods:

Using git submodules + add_subdirectory():

Run git submodule add https://github.com/dlaidig/vqf in your project directory and add the following line to CMakeLists.txt:
```
add_subdirectory(vqf)
```
Using FetchContent:

Add the following lines to CMakeLists.txt:
```
include(FetchContent)

FetchContent_Declare(
  vqf
  GIT_REPOSITORY https://github.com/dlaidig/vqf)
FetchContent_MakeAvailable(vqf)
```
Note: To use a specific git tag (e.g., development), add GIT_TAG development to the FetchContent_Declare command.

Using the CPM package manager:

Add the following lines to CMakeLists.txt:

file(
  DOWNLOAD
  https://github.com/cpm-cmake/CPM.cmake/releases/download/v0.42.0/CPM.cmake
  ${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake)
include(${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake)

CPMAddPackage("gh:dlaidig/vqf#development")

Note: To use a specific git tag (e.g., development), use gh:dlaidig/vqf#development in the CPMAddPackage command.

To build your project (with all VQF features enabled), run:

cmake -DVQF_SINGLE_PRECISION=0 -DVQF_NO_MOTION_BIAS_ESTIMATION=0 -S . -B build
cmake --build build

Matlab Implementation

The Matlab implementation is self-contained in the file VQF.m. In order to use this implementation, add the directory containing the file to your Matlab path or copy this file to your own project.

The file is located in the directory vqf/matlab/ of the repository. It is also shipped when installing the Python package. In order to find out the installation path, use the following command:

python -c "import vqf; print(vqf.get_matlab_path())"

Development Notes

The source code can be found at https://github.com/dlaidig/vqf.

To install the package from a clone of the git repository, use pip with a dot as the package name. With [dev], additional dependencies for development will automatically be installed. Editable installs (-e) are also possible. Therefore, use the following command to install the package for development:

pip install --user -e ".[dev]"

To build the documentation:

sphinx-build -b html docs build/sphinx/html/ -E

To run unit tests and coding style checks (optionally with --nomatlab and --nooctave to disable testing the Matlab implementation):

flake8 && pytest
flake8 && pytest --nomatlab --nooctave

To test RESUE compliance:

reuse lint

The source distributation and wheels of the Python package for various platforms and Python versions are automatically built using cibuildwheel via GitHub Actions (see the file .github/workflows/build.yml in the repository). The resulting files are then uploaded to PyPI via twine upload.