cyvlfeat

A Python (cython) wrapper of the VLFeat library

We intend for this to be a light wrapper around the VLFeat toolbox. cyvlfeat will provide a mixture of pure Python and Cython code that looks to replicate the existing Matlab toolbox. Cython is intended to fulfill the role of mex files.

We respect the original BSD 2-clause license and thus release this wrapper under the same license.

We thank the authors of VLFeat for their contribution to the computer vision community.

Current State

At the moment, the following methods from vlfeat are exposed:

• fisher
  • fisher
• generic
  • set_simd_enabled, get_simd_enabled, cpu_has_avx, cpu_has_sse3, cpu_has_sse2
  • get_num_cpus,
  • get_max_threads, set_num_threads, get_thread_limit
• hog
  • hog
• kmeans
  • kmeans
  • kmeans_quantize
  • ikmeans, ikmeans_push
  • hikmeans, hikmeans_push
• sift
  • dsift
  • sift
  • phow

To install cyvlfeat, we strongly suggest you use conda:

conda install -c conda-forge cyvlfeat

If you don't want to use conda, your mileage will vary. In particular, you must satisfy the linking/compilation requirements for the package, which include the vlfeat dynamic library.

Development

To develop cyvlfeat (to extend its functionality), you will need to be comfortable using Cython. To begin re-implementing Matlab's mex methods in Cython, you will to install the following requirements:

• cython >=0.22
• numpy >= 1.9
• vlfeat >= 0.9.20

To make this easier, we suggest you use conda. This makes installing the dependencies much simpler.

This library dynamically links against the vlfeat, and therefore you will need to ensure that it is available to the Python setup environment at build time. As mentioned, this is mostly easily done using conda:

conda install vlfeat -c conda-forge

This will install all of cyvlfeat's dependencies, including vlfeat, numpy and cython. You will likely want to install this into a new conda environment for cyvlfeat development. Please see the conda documentation for an explanation about environments.

To begin developing, you will need to git fork and clone this repository:

• Fork using the Github fork button
• Clone your repo: git clone git@github.com:YOUR_GITHUB_USERNAME/cyvlfeat.git
• Add this repo as upstream: git remote add upstream git@github.com:menpo/cyvlfeat.git

You can now locally install a development version/build cyvlfeat by using:

CFLAGS="-I$CONDA_PREFIX/include" LDFLAGS="-L$CONDA_PREFIX/lib" pip install -e ./

You can also only build the Cython extensions locally using the MakeFile:

make

This will build and install a local version of cyvlfeat for your development. You can also build and test this by using conda itself (from inside the cyvlfeat git repository):

conda install conda-build
CONDACI_VERSION=VERSION_HERE conda build ./conda

You need to fill in the version number, as this is normally supplied by the continuous integration systems (CI). Usually, you want to use a number that is tagged to the git repository. For example, in bash you could use the command:

CONDACI_VERSION=`git describe --tags` conda build ./conda

For Windows, you will need to set the variable before building:

set CONDACI_VERSION=VERSION_HERE
conda build ./conda

To run the tests manually, ensure pytest is installed (conda install -c conda-forge pytest), and run

pytest -v

From inside the git repository.

To add a new feature, please start a pull request. This will also kick off the automated building systems for both Linux and Windows. I will oversee any new additions, and providing they pass on both automated build systems, will merge the new functionality in.