# DBoW3: a bag of words for image features, with binary files and one dependency

> DBoW3 turns images into bag-of-words vectors by building a hierarchical vocabulary over local features, and it ships an image database with inverted and direct indexes on top. Version 3 is a rewrite of the older DBoW2 library: OpenCV is the only dependency, binary descriptors work out of the box, and the on-disk format is four to five times faster to load than the YAML files it replaces.

**rmsalinas/DBow3** — Improved version of DBow2

- Repository: https://github.com/rmsalinas/DBow3
- Stars: 577 · Forks: 256
- Language: C++
- License: NOASSERTION
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/rmsalinas-dbow3

## What the library actually computes

DBoW3 is an improved version of the DBoW2 library, an open source C++ library for indexing and converting images into a bag-of-words representation. The two things it implements are the vocabulary and the database. The vocabulary side implements a hierarchical tree for approximating nearest neighbours in the image feature space and for creating a visual vocabulary, which is what turns a set of local keypoint descriptors into a discrete symbol per image, and a symbol per descriptor within it. The database side implements an image database with inverted and direct files to index images, which is what enables quick queries and feature comparisons. The vocabulary and the database are exposed as two main classes, named Vocabulary and Database, and the README says the Vocabulary class implements the visual vocabulary that converts images into bag-of-words vectors while the Database class indexes images. The usage example is a single file, utils/demo_general.cpp, which is the first thing to read.

## Why version 3 exists, in the author's own list

The README lists the differences with DBoW2, and they are all about removing work rather than adding capability. DBoW3 only requires OpenCV, and the DLIB dependency of DBoW2 has been removed. That single change is what makes the library usable in a project that already has OpenCV and nothing else. Second, DBoW3 is able to use both binary and floating point descriptors out of the box, with no need to reimplement any class for any descriptor, which removes the per-descriptor wrapper code that older versions required. Third, it compiles both on Linux and on Windows. Fourth, some pieces of code have been rewritten to optimise speed, and the interface of DBoW3 has been simplified. Fifth, binary files are possible, and they are four to five times faster to load and save than the YAML format, and they can be compressed. Sixth, and importantly for migration, it is compatible with DBoW2 YAML files, so an existing vocabulary written in the older library can be read by the new one.

## The binary format, and the vocabulary file that ships with the repo

The file format change is the practical headline. A bag-of-words vocabulary is large and is read at startup, so load time matters, and the README states that binary files are four to five times faster to load and save than YAML and that they can be compressed. The repository contains one such file, orbvoc.dbow3, at the top level. The README explains what it is: it is the ORB vocabulary used in ORB-SLAM2, but in the binary format of DBoW3, and it points at the ORB-SLAM2 repository tree for the original. So the project ships a ready to use vocabulary for a very common descriptor, which is a considerable convenience, because building one from scratch is the slow part of adopting a bag-of-words system. The compatibility note completes the picture: an existing DBoW2 YAML vocabulary still works, so the format change is a performance improvement rather than a breaking migration for the vocabulary itself.

## Building the demo, and the one configuration that catches people out

The installation notes are short. DBoW3 requires OpenCV only, and the project is built with CMake, with a CMakeLists.txt at the root, a config.cmake.in, a cmake_uninstall.cmake.in and the usual src, tests and utils directories. There is one detail in the installation notes that will stop you if you skip it. For compiling the utils/demo_general.cpp file you must compile against OpenCV 3, and if you have installed the contrib modules, you use the cmake option -DUSE_CONTRIB=ON to enable SURF. SURF is a patented algorithm that moved out of the main OpenCV distribution, which is why it sits behind a flag, and why the demo needs the contrib modules to be present. SURF is a patented algorithm that moved out of the main OpenCV distribution, which is why it sits behind a flag, and why the demo needs the contrib modules to be present. If you want a simpler start, the demo works with the standard OpenCV 3 build and no extra options, which is the configuration most people should use first.

## The reading path for a new user is short, and it is deliberate

The how-to-use section is three lines. Check utils/demo_general.cpp. The two main classes are Vocabulary and Database. See utils/demo_general.cpp for an example. That is the whole guidance, and the reason it is enough is that the library has only two entry points. You build a Vocabulary from the descriptors you have, and you use a Database to store and retrieve image entries against that vocabulary. Because the README points at one file rather than at a tutorial series, the fastest way to understand the intended flow is to read that demo end to end, which is short by the standards of a computer vision sample. The repository also has a tests directory, so the expectations for each class are visible in code as well as in the demo, and the docs directory is absent, which is a fair signal that this is a library you learn from source.

## Citing it, if your use of it ends up in a paper

The README asks that if you use this software in academic work you cite it, and gives the bibtex entry to copy.

```text
   title = {{DBoW3} DBoW3}, 
  year = 2017, 
  url = {https://github.com/rmsalinas/DBow3}, 
  urldate = {2017-02-17} 
 } 
```

The entry names Rafael Muñoz-Salinas as the author, and the year and urldate are both 2017, which tells you the library has been stable and widely used for a long time. The urldate in particular is a hint that this citation was written once and not revisited, so if you are citing a specific commit rather than the project as a whole, you would do better to point at a commit hash.

## A project that points you elsewhere for the next version

The first substantive line in the README is a redirect. For an improved version of this project, please see FBOW, which is the author's other repository. That framing tells you how to treat DBoW3. It is a stable, well-used library that the author has moved past, and the recommended starting point for new work is the successor. What remains relevant here is the design decisions that FBOW inherits, the two-class split, the hierarchical vocabulary structure and the inverted and direct index files, since those are what you are still choosing when you pick DBoW3. The licence is a custom one that GitHub cannot classify, so the LICENSE.txt file at the repository root is the authority on the terms. The repository is not archived, the last push was on 2026-05-18, and there are no GitHub releases, so there is no version history to consult beyond the file itself and the CHANGELOG in the linked successor.

## Conclusion

DBoW3 fits a vision or robotics project that needs to place images into a visual vocabulary, to detect loops in a video sequence, or to index a set of frames for retrieval, and that already depends on OpenCV. It does not fit a team that wants a learned visual vocabulary, since the vocabulary here is built by hierarchical clustering rather than by training, and it is not the place to look for new work, because the README points you to the author's FBOW project for an improved version. Verify first that your OpenCV version and the SURF option line up, since the demo only compiles against OpenCV 3, and read the DBoW2 compatibility note before you migrate an existing set of YAML files.

## FAQ

### What does DBoW3 do?

It is a C++ library for indexing images and converting them into a bag-of-words representation. It implements a hierarchical tree for approximating nearest neighbours in the image feature space and creating a visual vocabulary, plus an image database with inverted and direct files for indexing images and enabling quick queries and feature comparisons.

### What are the main differences between DBoW3 and DBoW2?

DBoW3 only requires OpenCV, with the DLIB dependency of DBoW2 removed. It handles both binary and floating point descriptors out of the box without reimplementing a class, compiles on Linux and Windows, has some code rewritten for speed with a simplified interface, supports binary files that load and save four to five times faster than YAML and can be compressed, and remains compatible with DBoW2 YAML files.

### How do I build the DBoW3 demo?

The project is built with CMake and requires OpenCV only. To compile utils/demo_general.cpp you must compile against OpenCV 3, and if you have installed the contrib modules you can use the cmake option to enable SURF.

### Does DBoW3 come with a ready to use vocabulary?

The repository includes a file named orbvoc.dbow3 at the top level, which is the ORB vocabulary used in ORB-SLAM2 but in the binary format of DBoW3. The README also points to the author's FBOW project for an improved version of the library.

## Sources

- [Issues](https://github.com/rmsalinas/DBow3/issues)
- [README](https://github.com/rmsalinas/DBow3/blob/master/README.md)
- [rmsalinas/DBow3 on GitHub](https://github.com/rmsalinas/DBow3)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rmsalinas-dbow3