VIAME is a computer vision application designed for do-it-yourself artificial intelligence including object detection, object tracking, data annotation, multi-camera processing, size measurement, image enhancement, rapid model generation, query-based search, mosaicing, and tools for the evaluation of algorithms. Originally targeting marine species analytics, VIAME now contains many algorithms and libraries, and is useful as a generic computer vision toolkit. It contains a number of tools for accomplishing the above, a pipeline framework which can connect C++/Python nodes in a multi-threaded fashion, and multiple algorithms resting on top of the pipeline infrastructure. Lastly, a portion of the algorithms have been integrated into both desktop and web user interfaces for deployments in different environments, with an open annotation archive and example of the web platform available at viame.kitware.com.

Documentation

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

Documentation Overview <> Installation <> Building <> All Examples <> DIVE Interface <> Object Detection <> Detector Training <> Object Tracking <> Search and Rapid Model Generation <> Model Evaluation <> Detection Formats <> Python Usage <> Image Enhancement <> Registration and Mosaicing <> Size Measurement <> Pipelining Overview <> Core Classes <> Plugin Integration <> Example Templates <> Embedding Algorithms

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 .zip or .tar.gz file. Alternatively, .msi installers are available via the DIVE standalone tool, which can then install VIAME from the 'add-ons' page. 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 570.65 or higher. This isn't required if just using manual annotators or you don't care much about algorithm speed.

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 supported running web and standalone annotation tools, but not full desktop.

Installation Recommendations:

• NVIDIA Drivers (Version 570.65 or above, Windows [1] [2] Ubuntu [1] [2] CentOS [1] [2])
  
• A CUDA-enabled GPU with 8 Gb or more VRAM
  

Windows Full Desktop Binaries:

• VIAME v0.23.5 Windows, GPU Enabled, Mirror1 (.zip)
  
• VIAME v0.23.5 Windows, GPU Enabled, Mirror2 (.zip)
  
• VIAME v0.21.1 Windows, CPU Only, Mirror1 (.zip)
  
• VIAME v0.21.1 Windows, CPU Only, Mirror2 (.zip)

Linux Full Desktop Binaries:

• VIAME v0.23.5 Linux, GPU Enabled, Mirror1 (.tar.gz)
  
• VIAME v0.23.5 Linux, GPU Enabled, Mirror2 (.tar.gz)
  
• VIAME v0.21.1 Linux, CPU Only, Mirror1 (.tar.gz)
  
• VIAME v0.21.1 Linux, CPU Only, Mirror2 (.tar.gz)

Web Applications:

• VIAME Online Web Annotator and Public Annotation Archive
  
• VIAME Web Local Installation Instructions
  
• VIAME Web Source Repository

Additional Packages:

• DIVE Standalone Desktop Annotator (Linux, Mac, Windows)
• Model Zoo and Add-Ons
• Custom and Prior VIAME Versions

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-default

This image is headless (ie, it contains no GUI) and contains a command line interface installation in the folder /opt/noaa/viame. For links to the full VIAME-Web containers see the above section in the installation documentation. Most add-on models are not included by default but can be downloaded via running the script download_viame_addons.sh in the bin folder, or by using the viame add-ons tool.

Python Package

VIAME is available on pypi (for Python 3.10 through 3.14), with wrappers around both its main command line tool and libraries for running different algorithms.

To install on Linux run:

pip install viame

To install on Windows, first install torch <2.11 with CUDA 12 support, then VIAME:

pip install "torch<2.11" torchvision --index-url https://download.pytorch.org/whl/cu128

pip install viame

This puts the viame tool described below on your path. Only a minimal set of pipelines ships with it; larger models come from viame add-ons. See VIAME as a Python Package for additional details.

Command Line Interface Basics

Every command line tool is a subcommand of the viame program. viame help lists them with a one line description each, and viame help <tool> prints that tool's own options.

A desktop or docker installation needs its environment set up first, via running the below before commands (pip package installs do not require this):

source [viame-install-directory]/setup_viame.sh

Example tool usage:

viame help                                       # list every tool
viame run my_pipeline.pipe                       # run a single pipeline file as-is
viame run my_pipeline.pipe video.mp4             # run a pipeline on a video
viame run detector.zip video.mp4                 # run a detector on a video
viame run detector.zip image_list.txt            # ... or a list of images
viame run detector.pipe videos/                  # run a pipeline over a folder
viame train data/ train_detector.conf            # train a model on some data
viame score detections.csv groundtruth.csv       # score file against groundtruth
viame score computed/ groundtruth/               # score folder against groundtruth
viame csv detections.csv --print-types           # inspect a VIAME csv
viame json tracks.json --print-types             # inspect a DIVE or COCO json
viame add-ons                                    # list and install model add-ons

Quick Build Instructions

These instructions are intended for developers or those interested in building the latest release branch. Anyone interested in just running the software as-is and not modifying it should use the installers listed in the prior section, without needing to do a software build. 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, version 12.6 with CUDNN 9 is preferred, though other versions of 11 through 13 also likely work. For python distributions, at a minimum Python 3.10 or above is necessary, alongside having pip installed.

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

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:

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

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

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
   │   ├── 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 occasionally re-run:

git submodule update --init

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 && git submodule update

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. Lastly, in the advanced case of running extra manual builds for certain dependencies, a recursive module update is required:

git submodule update --init --recursive

License, Citations, and Acknowledgements

The core of VIAME is released under a BSD-3 license (see LICENSE.txt).

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.