Skip to main content

Python and C++ toolkit that pulls together computer vision algorithms into highly modular run time configurable systems

Project description

KWIVER

master release version docker

Kitware Image and Video Exploitation and Retrieval

The KWIVER toolkit is a collection of software tools designed to tackle challenging image and video analysis problems and other related challenges. Recently started by Kitware’s Computer Vision and Scientific Visualization teams, KWIVER is an ongoing effort to transition technology developed over multiple years to the open source domain to further research, collaboration, and product development. KWIVER is a collection of C++ libraries with C and Python bindings and uses an permissive BSD License.

One of the primary design goals of KWIVER is to make it easier to pull together algorithms from a wide variety of third-party, open source image and video processing projects and integrate them into highly modular, run-time configurable systems.

For more information on how KWIVER achieves this goal, and how to use KWIVER visit our documentation site

Directory Structure and Provided Functionality

Below is a summary of the key directories in KWIVER and a brief summary of the content they contain.

CMake

CMake helper scripts

arrows

The algorithm plugin modules

doc

Documentation, manuals, release notes

examples

Examples for running KWIVER (currently out of date)

extras

Extra utilities (e.g. instrumentation)

sprokit

Stream processing toolkit

tests

Testing related support code

vital

Core libraries source and headers

KWIVER Docker Image

Kitware maintains a Docker image with KWIVER prebuilt. The Dockerfile used to build the image can be found here.

Pull the image from Dockerhub:

"docker pull kitware/kwiver:master" (latest master)

"docker pull kitware/kwiver:release" (latest release)

"docker pull kitware/kwiver:1.4.0" (static release)

(https://hub.docker.com/r/kitware/kwiver)

or build the KWIVER image using the dockerfile:

"docker build -t kwiver:tagname ."

Building KWIVER

Fletch

KWIVER, especially Arrows, has a number of dependencies on 3rd party open source libraries. Most of these dependencies are optional but useful in practice, and the number of dependencies is expected to grow as we expand Arrows.

Vital has minimal required dependencies (only Eigen). Sprokit additionally relies on Boost. C++ tests additionally rely on Google Test. Arrows and Sprokit processes are structured so that the code that depends on an external package is in a directory with the major dependency name (e.g. vxl, ocv). The dependencies can be turned ON or OFF through CMake variables.

To make it easier to build KWIVER, especially on systems like Microsoft Windows that do not have package manager, Fletch was developed to gather, configure and build dependent packages for use with KWIVER. Fletch is a CMake based “super-build” that takes care of most of the build details for you.

For building Fletch, refer to the README file in that repository.

Running CMake

You may run cmake directly from a shell or cmd window. On unix systems, the ccmake tool allows for interactive selection of CMake options. Available for all platforms, the CMake GUI can set the source and build directories, options, “Configure” and “Generate” the build files all with the click of a few button.

We recommend building KWIVER out of the source directory to prevent mixing source files with compiled products. Create a build directory in parallel with the KWIVER source directory for each desired configuration. For example :

\kwiver\src

contains the code from the git repository

\kwiver\build\release

contains the built files for the release configuration

\kwiver\build\debug

contains the built files for the debug configuration

The following are the most important CMake configuration options for KWIVER.

CMAKE_BUILD_TYPE

The compiler mode, usually Debug or Release

CMAKE_INSTALL_PREFIX

The path to where you want the kwiver build products to install

KWIVER_ENABLE_ARROWS

Enable algorithm implementation plugins

KWIVER_ENABLE_C_BINDINGS

Whether to build the Vital C bindings

KWIVER_ENABLE_DOCS

Turn on building the Doxygen documentation

KWIVER_ENABLE_LOG4CPLUS

Enable log4cplus logger back end

KWIVER_ENABLE_PYTHON

Enable the Vital Python bindings (requires KWIVER_ENABLE_C_BINDINGS)

KWIVER_ENABLE_SPROKIT

Enable the Stream Processing Toolkit

KWIVER_ENABLE_TESTS

Build the unit tests (requires Google Test)

KWIVER_ENABLE_TOOLS

Build the command line tools (e.g. plugin_explorer)

fletch_DIR

Install directory of a Fletch build.

There are many more options. Specifically, there are numerous options for third-party projects prefixed with KWIVER_ENABLE_ that enable building the Arrows plugins that depend on those projects. When building with the support of Fletch (set fletch_DIR) the enable options for packages built by Fletch should be turned on by default. The fletch_DIR is the fletch build directory root, which contains the fletchConfig.cmake file.

The following sections will walk you through the basic options for a minimal kwiver build.

Basic CMake generation via command line

Note, This assumes your fletch was built with python support (Turn OFF if not)

You will also need to replace the fletch path with your own:

$ cmake </path/to/kwiver/source> -DCMAKE_BUILD_TYPE=Release \
        -Dfletch_DIR:PATH=<path/to/fletch/build/dir> \
        -DKWIVER_ENABLE_ARROWS:BOOL=ON -DKWIVER_ENABLE_C_BINDINGS:BOOL=ON \
        -DKWIVER_ENABLE_EXTRAS:BOOL=ON -DKWIVER_ENABLE_LOG4CPLUS:BOOL=ON \
        -DKWIVER_ENABLE_PROCESSES:BOOL=ON -DKWIVER_ENABLE_PYTHON:BOOL=ON \
        -DKWIVER_ENABLE_SPROKIT:BOOL=ON -DKWIVER_ENABLE_TOOLS:BOOL=ON \
        -DKWIVER_ENABLE_EXAMPLES:BOOL=ON -DKWIVER_USE_BUILD_TREE:BOOL=ON

Basic CMake generation using ccmake

When first configuring a kwiver build with ccmake it is preferable to set the build configuration and fletch_DIR on the command line like this:

$ ccmake /path/to/kwiver/source -DCMAKE_BUILD_TYPE=Release -Dfletch_DIR=/path/to/fletch/install

Other CMake options can also be passed on the command line in this way if desired. Follow the recommended option setup using the cmake GUI.

Basic CMake generation using the CMake GUI

When running the cmake gui, we recommend selecting the ‘Grouped’ and ‘Advanced’ options to better organize the options available. Note, after clicking the configuration button, new options will be highlighted in the red sections.

  1. Once the source code and build directories are set, press the ‘Configuration’ button and select your compiler.

    1. Configuration will fail, but now we can set option values

  2. Set the fletch_DIR, the CMAKE_BUILD_TYPE, and these KWIVER options, and press the ‘Configuration’ button

    1. Note, if compiling with MSVC, you will not have a CMAKE_BUILD_TYPE option

KWIVER CMake Configuration Step 2
  1. Select these new options, and click ‘Generate’

    1. This assumes your fletch was build with python support, if not, do not check that option

KWIVER CMake Configuration Step 3

Compiling

Once your CMake generation has completed and created the build files, compile in the standard way for your build environment. On Linux this is typically running make.

There is also a build target, INSTALL. This target will build all code, then create an install directory inside the build directory. This install folder will be populated with all binaries, libraries, headers, and other files you will need to develop your application with kwiver. MSVC users, note that this install directory is for a single build configuration; there will not be configuration named directories in this directory structure (i.e. no /bin/release, only /bin).

Running KWIVER

Once you’ve built KWIVER, you’ll want to test that it’s working on your system. Change your terminal/command prompt to the KWIVER CMake build directory. From a command prompt execute the following command:

# via a bash shell
$ cd <path/to/kwiver/build>
$ source setup_KWIVER.sh
#
# via a windows cmd prompt
> cd <path/to/kwiver/build>
> setup_KWIVER.bat

This will set up your PATH, PYTHONPATH and other environment variables to allow KWIVER to work conveniently within in the shell/cmd window.

You can run this simple pipeline to ensure your system is configured properly:

# via a bash shell
$ cd bin
$ kwiver runner ../examples/pipelines/number_flow.pipe
#
# on windows, you will need to also be in the configuration folder
> cd bin\release
> kwiver runner ..\..\examples\pipelines\number_flow.pipe

This will generate a ‘numbers.txt’ file in the </path/to/kwiver/build>/examples/pipelines/output directory.

More examples can be found in our tutorials

KWIVER Users

Here are some applications using kwiver that serve as an example of how to leverage kwiver for a specific application

MAP-Tk

A collection tools for structure-from-motion and dense 3D reconstruction from imagery with an emphasis on aerial video. The primary component is a GUI application named TeleSculptor.

VIAME

A computer vision library designed to integrate several image and video processing algorithms together in a common distributed processing framework, majorly targeting marine species analytics

Testing

Continuous integration testing is provided by CDash. Our KWIVER dashboard hosts nightly build and test results across multiple platforms including Windows, Mac, and Linux.

Anyone can contribute a build to this dashboard using the dashboard script provided. Follow the instructions in the comments.

Contributing

For details on how to contribute to KWIVER, including code style and branch naming conventions, please read CONTRIBUTING.rst.

Getting Help

Please join the kwiver-users mailing list to discuss KWIVER or to ask for help with using KWIVER. For less frequent announcements about KWIVER and projects built on KWIVER, please join the kwiver-announce mailing list.

Acknowledgements

The authors would like to thank AFRL/Sensors Directorate for their support of this work via SBIR Contract FA8650-14-C-1820. The portions of this work funded by the above contract are approved for public release via case number 88ABW-2017-2725.

The authors would like to thank IARPA for their support of this work via the DIVA program.

The authors would like to thank NOAA for their support of this work via the NOAA Fisheries Strategic Initiative on Automated Image Analysis.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

kwiver-1.4.6-cp38-cp38-manylinux2014_x86_64.whl (54.3 MB view details)

Uploaded CPython 3.8

kwiver-1.4.6-cp37-cp37m-manylinux2014_x86_64.whl (54.2 MB view details)

Uploaded CPython 3.7m

kwiver-1.4.6-cp36-cp36m-manylinux2014_x86_64.whl (54.2 MB view details)

Uploaded CPython 3.6m

kwiver-1.4.6-cp35-cp35m-manylinux2014_x86_64.whl (54.2 MB view details)

Uploaded CPython 3.5m

File details

Details for the file kwiver-1.4.6-cp38-cp38-manylinux2014_x86_64.whl.

File metadata

  • Download URL: kwiver-1.4.6-cp38-cp38-manylinux2014_x86_64.whl
  • Upload date:
  • Size: 54.3 MB
  • Tags: CPython 3.8
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/41.2.0 requests-toolbelt/0.9.1 tqdm/4.43.0 CPython/3.8.0

File hashes

Hashes for kwiver-1.4.6-cp38-cp38-manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 f26fefce86f429c2c7d266bd03653d1ca18e7c0dae0eaa9c90067653e0ac004b
MD5 72a526a3705980a22e141a025c33b85d
BLAKE2b-256 8ae652c94774748ccd973ffc3feb45804c59eb4e16416ae7cec12d6c95da8942

See more details on using hashes here.

File details

Details for the file kwiver-1.4.6-cp37-cp37m-manylinux2014_x86_64.whl.

File metadata

  • Download URL: kwiver-1.4.6-cp37-cp37m-manylinux2014_x86_64.whl
  • Upload date:
  • Size: 54.2 MB
  • Tags: CPython 3.7m
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/39.0.1 requests-toolbelt/0.9.1 tqdm/4.43.0 CPython/3.7.0

File hashes

Hashes for kwiver-1.4.6-cp37-cp37m-manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 5e60e45ff39d2699bca81ee2fa8d833003afeac65c9fa78403ef2b92fa413714
MD5 3cdd34229be1a6c1871eb7965ad7a91b
BLAKE2b-256 3a29d9e05a1c01b27df8ce52736b1067acaba31201b69b3cee4727d9bf4175f7

See more details on using hashes here.

File details

Details for the file kwiver-1.4.6-cp36-cp36m-manylinux2014_x86_64.whl.

File metadata

  • Download URL: kwiver-1.4.6-cp36-cp36m-manylinux2014_x86_64.whl
  • Upload date:
  • Size: 54.2 MB
  • Tags: CPython 3.6m
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.23.0 setuptools/28.8.0 requests-toolbelt/0.9.1 tqdm/4.43.0 CPython/3.6.0

File hashes

Hashes for kwiver-1.4.6-cp36-cp36m-manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 3d8ac198dc95366a68eb141a8dd71316f769001c0d7d22f13d16ffc4b638f7b1
MD5 97bbb7c2a34030ce75ba4d5e43d4fec6
BLAKE2b-256 cbff07bdb6715cd9bd358e6b9925c3d01e97080ae3f1debe497acaf69804867d

See more details on using hashes here.

File details

Details for the file kwiver-1.4.6-cp35-cp35m-manylinux2014_x86_64.whl.

File metadata

  • Download URL: kwiver-1.4.6-cp35-cp35m-manylinux2014_x86_64.whl
  • Upload date:
  • Size: 54.2 MB
  • Tags: CPython 3.5m
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.15.0 pkginfo/1.5.0.1 requests/2.23.0 setuptools/45.2.0 requests-toolbelt/0.9.1 tqdm/4.43.0 CPython/3.5.0

File hashes

Hashes for kwiver-1.4.6-cp35-cp35m-manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 07494818a8b73b8ba09ea4374bd774dc1d492e39036d948d6bd1dc5ea6676de7
MD5 1cd786ba90f43553de35f6758bf2c7aa
BLAKE2b-256 a3952e2b36def529beb5fce9a28ff8edd936ccf8cae418c7d1de1b2c3bb913e7

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page