This framework contains various libraries, executables and scripts originating from computer vision R&D projects undertaken in the LITIV lab (Laboratoire d'Interprétation et de Traitement d'Images et Vidéo), at Polytechnique Montréal. For now, it primarily consists of C++ algorithm implementations and utilities, most of which rely on OpenCV. Its build system is based on CMake, and its structure is inspired by OpenCV. The framework should be compatible with most Unix/Windows systems given proper configuration; it has been developed in part on Windows 7/8/10 with MSVC2015v3, and Ubuntu/Fedora with CLion.
Most of the source code behind the LITIV framework is available under the Apache 2.0 license; see the LICENSE file for more information. Some third-party libraries and utilities are provided under their own BSD (2-clause or 3-clause) licenses. Specific licensing details are available in each source file or folder. While this means the LITIV framework source code can be used in distributed commercial applications, be aware that external algorithms that may be used therein (e.g. ViBe, FastPD) are covered by patents in some countries. Note that we will offer no legal advice on possible patent infringements cases; the LITIV framework should be primarily used for testing, evaluation, research, and development purposes in an academic setting.
The framework currently has little documentation outside doxygen comments in header files. If you want to learn more about the algorithms, your best bet is to read the papers that introduced them. More minimalist code samples & unit tests are also always in the works. For now, module behavior validation primarily relies on assertions, and part of these are only enabled for debug builds. If you are looking for a place to start digging, it is recommended to start in the apps and samples folders; their executable projects can provide a high-level look at some features of the framework. The apps folder contains mostly development sandboxes and testbenches (mostly uncommented), while the samples folder contains cleaner use-case examples with more adequate descriptions.
As stated before, the LITIV framework structure is inspired by OpenCV's structure. This means libraries are split into modules, and they are all assembled under a global library (world) for easier linking. Third-party components are kept in their own folder (3rdparty) at the root level. The apps and samples folders contain various executables which rely on LITIV algorithms and utilities for testing and evaluation. The scripts folder contains evaluation/test scripts that once had some purpose in the lab (it needs cleaning). For testing, each subproject can have its own test directory, and it will automatically be parsed and added via CTest.
All internal modules can be dynamically or statically linked on Unix systems, and only statically linked on Windows (symbol exports are still missing).
The primary goal here is to have the framework core only depend on OpenCV/CMake, and have as many OpenCV-based implementations as possible. This is not always possible however, so building without all dependencies will disable some features. Here is the list of required and optional dependencies:
- CMake >= 3.1.0 (required)
- OpenCV >= 3.0.0 (required)
- GLFW >= 3.0.0 or FreeGLUT >= 2.8.0 (optional, for GLSL implementations)
- GLEW >= 1.9.0 (optional, for GLSL implementations)
- GLM (optional, for GLSL implementations)
- CUDA >= 7.0 with compute >=3.0 (optional, for some optimizations)
- Boost >= 1.49 (optional, for some 3rdparty implementations, e.g. SoSPD)
- OpenGM (optional, for mutual segmentation algorithms)
A dockerfile which builds an Ubuntu image including all these dependencies is available here. The images built by Travis are periodically uploaded to Docker Hub here and here.
This is a CMake-based project; to get your desired solution format (Makefiles, .sln, ...) and compile the framework, you must create a 'build' directory somewhere (ideally, in this directory), startup cmake from there (via command-line or gui), and point to the source directory (where this README is located). For example, in command-line:
git clone https://github.com/plstcharles/litiv
cd litiv
mkdir build
cd build
cmake ../
Using the CMake GUI is highly encouraged, as you will have direct access to more options when configuring the framework. It is also easier to set paths to missing/optional 3rd party libraries using the interface.
A list of all internal modules is presented below; for more information, refer to their README files.
- datasets : Provides dataset parsing and evaluation utilities with precaching and async processing support.
- features2d : Provides feature descriptors & matchers (LBSP, DASC, LSS, MI, ShapeContext).
- imgproc : Provides image processing algos and utilities (edge detectors, SLIC superpixels extractor, image warper, ...).
- test : Provides utilities for project-wide unit/performance testing; never exported for external usage.
- utils : Equivalent of OpenCV's "core" module; contains miscellaneous common utilities (see list here).
- video : Provides background subtraction algos & utilities (LOBSTER, SuBSENSE, PAWCS and others).
- vptz : Provides a compact version of the VirtualPTZ library used to evaluate PTZ trackers.
- world : Provides nothing, and pre-links other modules to make linking easier/faster elsewhere.
For a more user-friendly, stable and documented background subtraction/video segmentation framework with various other utilities, see Andrews Sobral's BGSLibrary.
Release notes and versions for the LITIV framework are maintained through Github Releases. You are expected to configure and compile the framework yourself based on your own needs & your machine's capabilities.
If you use a module from this framework in your own work, please cite its related LITIV publication(s) as acknowledgment. See this page for a full list.
If you have something you'd like to contribute to the LITIV framework (algorithm, improvement or bugfix), you can send it in as a pull request.