Skip to content

VIAME/VIAME

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
Jan 17, 2023
Jan 23, 2023
May 10, 2022
Dec 15, 2021
Jan 23, 2023
Jan 25, 2023
Feb 14, 2022

VIAME Logo

VIAME is a computer vision application designed for do-it-yourself artificial intelligence including object detection, object tracking, image/video annotation, image/video search, image mosaicing, size measurement, rapid model generation, and tools for the evaluation of different algorithms. Both a desktop and web version exist for deployments in different types of environments, with an open annotation archive and example of the web platform available at viame.kitware.com. Originally targetting marine species analytics, VIAME now contains many common algorithms and libraries, and is also useful as a generic computer vision toolkit. It contains a number of standalone tools for accomplishing the above, a pipeline framework which can connect C/C++, python, and matlab nodes together in a multi-threaded fashion, and, lastly, multiple algorithms resting on top of the pipeline infrastructure.

Documentation

The User's Quick-Start Guide, Tutorial Videos, and Developer's Manual are more comprehensive, but select entries are also listed below broken down by individual functionality:

Documentation Overview <> Install or Build Instructions <> All Examples <> DIVE Interface <> VIEW Interface <> Search and Rapid Model Generation <> Object Detector CLI <> Object Tracker CLI <> Detector Training CLI <> Evaluation of Detectors <> Detection File Formats <> Calibration and Image Enhancement <> Registration and Mosaicing <> Stereo Measurement and Depth Maps <> Pipelining Overview <> Core Class and Pipeline Info <> Plugin Integration <> Example Plugin Templates <> Embedding Algorithms in C++

Installations

For a full installation guide and description of the various flavors of VIAME, see the quick-start guide, above. The full desktop version is provided as either a .msi, .zip or .tar file. Alternatively, standalone annotators (without any processing algorithms) are available via smaller installers. Lastly, docker files are available for both VIAME Desktop and Web (below). For full desktop installs, extract the binaries and place them in a directory of your choosing, for example /opt/noaa/viame on Linux or C:\Program Files\VIAME on Windows. If using packages built with GPU support, make sure to have sufficient video drivers installed, version 465.19 or higher. The best way to install drivers depends on your operating system. This isn't required if just using manual annotators (or frame classifiers only). The binaries are quite large, in terms of disk space, due to the inclusion of multiple default model files and programs, but if just building your desired features from source (e.g. for embedded apps) they are much smaller.

Installation Requirements:

  • Up to 8 Gb of Disk Space for the Full Installation
  • Windows 7*, 8, 10, or 11 (64-Bit) or Linux (64-Bit, e.g. RHEL, CentOS, Ubuntu)
    • Windows 7 requires some updates and service packs installed, e.g. KB2533623.
    • MacOS is currently only supported running standalone annotation tools, see below.

Installation Recommendations:

Windows Full Desktop Binaries:

Linux Full Desktop Binaries:

Web Applications:

DIVE Standalone Desktop Annotator:

SEAL Standalone Desktop Annotator:

Optional Add-Ons and Model Files:

Note: To install Add-Ons and Patches, copy them into an existing VIAME installation folder. Folders should match, for example, the Add-On packages contains a 'configs' folder, and the main installation also contains a 'configs' folder so they should just be merged.

Docker Images

Docker images are available on: https://hub.docker.com. For a default container with just core algorithms, runnable via command-line, see:

kitware/viame:gpu-algorithms-latest

This image is headless (ie, it contains no GUI) and contains a VIAME desktop (not web) installation in the folder /opt/noaa/viame. For links to the VIAME-Web docker containers see the above section in the installation documentation. Most add-on models are not included in the instance but can be downloaded via running the script download_viame_addons.sh in the bin folder.

Quick Build Instructions

These instructions are intended for developers or those interested in building the latest master branch. More in-depth build instructions can be found here, but the software can be built either as a super-build, which builds most of its dependencies alongside itself, or standalone. To build VIAME requires, at a minimum, Git, CMake, and a C++ compiler. Installing Python and CUDA is also recommended. If using CUDA, versions 11.7 or 11.6 are preferred, with CUDNN 8. Other CUDA or CUDNN versions may or may not work. For python distributions, at a minimum Python3.6 or above, Pip, and Numpy is necessary.

To build on the command line in Linux, use the following commands, only replacing [source-directory] and [build-directory] with locations of your choice. While these directories can be the same, it's good practice to have a 'src' checkout then a seperate 'build' directory alongside it:

git clone https://github.com/VIAME/VIAME.git [source-directory]

cd [source-directory] && git submodule update --init --recursive

Next, create a build directory and run the following cmake command (or alternatively use the cmake GUI if you are not using the command line interface):

mkdir [build-directory] && cd [build-directory]

cmake -DCMAKE_BUILD_TYPE:STRING=Release [source-directory]

Once your cmake command has completed, you can configure any build flags you want using 'ccmake' or the cmake GUI, and then build with the following command on Linux:

make -j8

Or alternatively by building it in Visual Studio or your compiler of choice on Windows. On Linux, '-j8' tells the build to run multi-threaded using 8 threads, this is useful for a faster build though if you get an error it can be difficult to see it, in which case running just 'make' might be more helpful. For Windows, currently VS2019 is the most tested compiler.

There are several optional arguments to viame which control which plugins get built, such as those listed below. If a plugin is enabled that depends on another dependency such as OpenCV) then the dependency flag will be forced to on. If uncertain what to turn on, it's best to just leave the default enable and disable flags which will build most (though not all) functionalities. These are core components we recommend leaving turned on:

Flag Description
VIAME_ENABLE_OPENCV Builds OpenCV and basic OpenCV processes (video readers, simple GUIs)
VIAME_ENABLE_VXL Builds VXL and basic VXL processes (video readers, image filters)
VIAME_ENABLE_PYTHON Turns on support for using python processes (multiple algorithms)
VIAME_ENABLE_PYTORCH Installs all pytorch processes (detectors, trackers, classifiers)

And a number of flags which control which system utilities and optimizations are built, e.g.:

Flag Description
VIAME_ENABLE_CUDA Enables CUDA (GPU) optimizations across all packages
VIAME_ENABLE_CUDNN Enables CUDNN (GPU) optimizations across all processes
VIAME_ENABLE_DIVE Enables DIVE GUI (annotation and training on multiple sequences)
VIAME_ENABLE_VIVIA Builds VIVIA GUIs (VIEW and SEARCH for annotation and video search)
VIAME_ENABLE_KWANT Builds KWANT detection and track evaluation (scoring) tools
VIAME_ENABLE_DOCS Builds Doxygen class-level documentation (puts in install tree)
VIAME_BUILD_DEPENDENCIES Build VIAME as a super-build, building all dependencies (default)
VIAME_INSTALL_EXAMPLES Installs examples for the above modules into install/examples tree
VIAME_DOWNLOAD_MODELS Downloads pre-trained models for use with the examples and interfaces

And lastly, a number of flags which build algorithms or interfaces with more specialized functionality:

Flag Description
VIAME_ENABLE_TENSORFLOW Builds TensorFlow object detector plugin
VIAME_ENABLE_DARKNET Builds Darknet (YOLO) object detector plugin
VIAME_ENABLE_TENSORRT Builds TensorRT object detector plugin
VIAME_ENABLE_BURNOUT Builds Burn-Out based pixel classifier plugin
VIAME_ENABLE_SMQTK Builds SMQTK plugins to support image/video indexing and search
VIAME_ENABLE_SCALLOP_TK Builds Scallop-TK based object detector plugin
VIAME_ENABLE_SEAL Builds Seal multi-modality GUI
VIAME_ENABLE_ITK Builds ITK cross-modality image registration
VIAME_ENABLE_UW_CLASSIFIER Builds UW fish classifier plugin
VIAME_ENABLE_MATLAB Turns on support for and installs all matlab processes
VIAME_ENABLE_LANL Builds an additional (Matlab) scallop detector

Source Code Layout

 VIAME
   ├── cmake               # CMake configuration files for subpackages
   ├── docs                # Documentation files and manual (pre-compilation)
   ├── configs             # All system-runnable config files and models
   │   ├── pipelines       # All processing pipeline configs
   │   │   └── models      # All models, which only get downloaded based on flags
   │   ├── prj-linux       # Default linux project files
   │   └── prj-windows     # Default windows project files 
   ├── examples            # All runnable examples and example tutorials
   ├── packages            # External projects used by the system
   │   ├── kwiver          # Processing backend infastructure
   │   ├── fletch          # Dependency builder for things which don't change often
   │   ├── kwant           # Scoring and detector evaluation tools
   │   ├── vivia           # Baseline desktop GUIs (v1.0)
   │   └── ...             # Assorted other packages (typically for algorithms)
   ├── plugins             # Integrated algorithms or wrappers around external projects
   │   └── ...             # Assorted plugins (detectors, depth maps, filters, etc.)
   ├── tools               # Standalone tools or scripts, often building on the above
   └── README.md           # Project introduction page that you are reading
   └── RELEASE_NOTES.md    # A list of the latest updates in the system per version

Update Instructions

If you already have a checkout of VIAME and want to switch branches or update your code, it is important to re-run:

git submodule update --init --recursive

After switching branches to ensure that you have on the correct hashes of sub-packages within the build. Very rarely you may also need to run:

git submodule sync

Just in case the address of submodules has changed. You only need to run this command if you get a "cannot fetch hash #hashid" error.

License, Citations, and Acknowledgements

VIAME is released under a BSD-3 license.

A non-exhaustive list of relevant papers used within the project alongside contributors can be found here.

VIAME was developed with funding from multiple sources, with special thanks to those listed here.