Package: kwiver
Kitware Image and Video Exploitation and RetrievalThe 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 permissiveBSD 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 ourdocumentation siteDirectory Structure and Provided FunctionalityBelow is a summary of the key directories in KWIVER and a brief summary of
the content they contain.CMakeCMake helper scriptsarrowsThe algorithm plugin modulesdocDocumentation, manuals, release notesexamplesExamples for running KWIVER (currently out of date)extrasExtra utilities (e.g. instrumentation)sprokitStream processing toolkittestsTesting related support codevitalCore libraries source and headersKWIVER Docker ImageKitware maintains aDockerimage with KWIVER prebuilt.
The Dockerfile used to build the image can be foundhere.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 KWIVERFletchKWIVER, 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 (onlyEigen).
Sprokit additionally relies onBoost.
C++ tests additionally rely onGoogle 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,Fletchwas developed to gather, configure and build dependent packages
for use with KWIVER.  Fletch is aCMakebased
“super-build” that takes care of most of the build details for you.For buildingFletch, refer to the README file in that repository.Running CMakeYou 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\srccontains the code from the git repository\kwiver\build\releasecontains the built files for the release configuration\kwiver\build\debugcontains the built files for the debug configurationThe following are the most important CMake configuration options for KWIVER.CMAKE_BUILD_TYPEThe compiler mode, usually Debug or ReleaseCMAKE_INSTALL_PREFIXThe path to where you want the kwiver build products to installKWIVER_ENABLE_ARROWSEnable algorithm implementation pluginsKWIVER_ENABLE_C_BINDINGSWhether to build the Vital C bindingsKWIVER_ENABLE_DOCSTurn on building the Doxygen documentationKWIVER_ENABLE_LOG4CPLUSEnable log4cplus logger back endKWIVER_ENABLE_PYTHONEnable the Vital Python bindings (requires KWIVER_ENABLE_C_BINDINGS)KWIVER_ENABLE_SPROKITEnable the Stream Processing ToolkitKWIVER_ENABLE_TESTSBuild the unit tests (requires Google Test)KWIVER_ENABLE_TOOLSBuild the command line tools (e.g. plugin_explorer)fletch_DIRInstall directory of a Fletch build.There are many more options.  Specifically, there are numerous options
for third-party projects prefixed withKWIVER_ENABLE_that enable
building the Arrows plugins that depend on those projects.  When building
with the support ofFletch(setfletch_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 lineNote, 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=ONBasic CMake generation using ccmakeWhen first configuring a kwiver build with ccmake it is preferable to set the build
configuration andfletch_DIRon the command line like this:$ ccmake /path/to/kwiver/source -DCMAKE_BUILD_TYPE=Release -Dfletch_DIR=/path/to/fletch/installOther 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 GUIWhen 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.Once the source code and build directories are set, press the ‘Configuration’
button and select your compiler.Configuration will fail, but now we can set option valuesSet the fletch_DIR, the CMAKE_BUILD_TYPE, and these KWIVER options,
and press the ‘Configuration’ buttonNote, if compiling with MSVC, you will not have a CMAKE_BUILD_TYPE optionSelect these new options, and click ‘Generate’This assumes your fletch was build with python support,
if not, do not check that optionCompilingOnce your CMake generation has completed and created the build files,
compile in the standard way for your build environment.  On Linux
this is typically runningmake.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).NoteIf you are on Windows and enable tests (KWIVER_ENABLE_TESTS=ON),
and are building shared libraries (BUILD_SHARED_LIBS=ON), you will
need to add the path togtest.dllto thePATHin your environment
in order to build and run the tests.The easiest way to achieve this is to use thesetup_KWIVER.batscript
(described in the next session), and to run builds and/or launch Visual
Studio from a command prompt which has been so configured.Running KWIVEROnce 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.batThis 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.pipeThis will generate a ‘numbers.txt’ file in the </path/to/kwiver/build>/examples/pipelines/output directory.More examples can be found in ourtutorialsKWIVER UsersHere are some applications using kwiver that serve as an example of how to
leverage kwiver for a specific applicationMAP-TkA 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.VIAMEA computer vision library designed to integrate several image and
video processing algorithms together in a common distributed
processing framework, majorly targeting marine species analyticsTestingContinuous integration testing is provided byCDash.
OurKWIVER dashboardhosts nightly build and test results across multiple platforms including
Windows, Mac, and Linux.Anyone can contribute a build to this dashboard using thedashboard scriptprovided.  Follow the instructions in the comments.ContributingFor details on how to contribute to KWIVER, including code style and branch
naming conventions, please readCONTRIBUTING.rst.Getting HelpPlease join thekwiver-usersmailing 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 thekwiver-announcemailing list.AcknowledgementsThe 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.