alicevision/CCTag: concentric-circle fiducials for pose estimation

What CCTag markers are and the problem they solve

A CCTag is a printed fiducial made of concentric circles rather than the black-and-white square grid used by ArUco or AprilTag families. The library is the implementation of a CVPR 2016 paper by Calvet, Gurdjos, Griwodz and Gasparini, titled "Detection and Accurate Localization of Circular Fiducials Under Highly Challenging Conditions". The problem it addresses is recovering both the identity of a marker and its position with high accuracy from a single image, when the marker is small in frame, viewed at an angle, or lit unevenly. Circular geometry is what makes that possible: the center of a set of concentric rings is a stable point under perspective, and the ring pattern carries the identity.

The intended user is an engineer building a vision pipeline, not an end user. The repository ships C++ source, a detection executable, a library interface in src/cctag/ICCTag.hpp, and a folder of markers to print. There is no application, no viewer, and no service. If you want a marker system you can drop into a Unity scene without compiling anything, this is the wrong layer of the stack.

How detection works: CPU and GPU paths over the same marker model

The README states that implementations exist for both CPU and GPU. The GPU path is not optional decoration: the README notes that CCTag requires either CUDA 8.0 and newer, or CUDA 7.0, and that CUDA 7.5 builds are known to have runtime errors on some devices including the GTX980Ti. The device must have at least compute capability 3.5. That is a hard constraint on the GPU route, and the README points readers to an external compatibility list to check their card.

The marker model is what drives the pipeline. A CCTag is a set of concentric rings whose radii and arrangement encode identity, so detection means finding ring-like edge structures, fitting their common center, and then reading the pattern. The public entry point for embedding this in your own code is the ICCTag.hpp header, which the README names as the library interface. The repository layout confirms the split: src/ holds the implementation, the top-level CMakeLists.txt and CMakePresets.json drive the build, and vcpkg.json declares dependencies for a vcpkg-based configuration. The Dockerfile shows the intended build shape, configuring with CCTAG_WITH_CUDA set to ON and CMAKE_BUILD_TYPE set to Release.

What the README does not describe is the internal algorithm: no edge detector is named, no fitting method is documented, and there is no description of how the ring pattern is decoded into an identifier. For that you have to read the paper or the source. That is a real gap for anyone evaluating accuracy claims, because the reported detection rate and localization accuracy are tied to the paper's conditions, not to your camera and lighting.

Installing CCTag and running the sample detection

The README does not give install steps inline. It says to see the INSTALL.md text file for building, and the documentation lives on the Read the Docs page at cctag.readthedocs.io. The repository also carries a Dockerfile and a Dockerfile_deps, so a container build is a supported route. The Dockerfile copies the source to /opt/cctag and builds in /opt/cctag/build with CMake, passing CCTAG_WITH_CUDA, CMAKE_BUILD_TYPE, BUILD_SHARED_LIBS and CMAKE_PREFIX_PATH. If you build in a container, that is the configuration the project itself uses.

Once compiled, the README gives one concrete command to try. It runs detection on the bundled sample image and asks for three markers:

build/src/detection -n 3 -i sample/01.png

The -n flag is the marker count and -i is the input image; sample/01.png and sample/02.png are the two images in the sample directory. Run it from the repository root after a build, and the executable is expected at build/src/detection. If you build with the Dockerfile above, the binary lands under /opt/cctag/build rather than your working tree, so adjust the path or run inside the container.

For library use rather than the CLI, the README points to src/cctag/ICCTag.hpp. That header is the documented interface; the README does not show a code example for it, so you will be reading the header itself to learn the call sequence. Budget time for that. This is a research-derived library, and the README treats the header as the documentation.

The planar-support warning is the main failure mode

The README carries an explicit warning about margins and support. It asks users to respect the provided margins, and states that the reported detection rate and localization accuracy are valid with completely planar support, warning against bent support such as a corrugated sheet of paper. Read that as the boundary of the tool. The accuracy numbers in the paper assume the marker is flat; a curved or wrinkled print breaks the geometry the detector relies on, and the README does not offer a degraded-mode fallback or a confidence signal for that case.

A second limitation is stated just as plainly: the four-ring CCTags will be available soon. If your design assumes a four-ring family, the README does not claim it exists yet, so treat the current marker set as what markersToPrint contains today.

There is also a platform limitation. The GPU path needs CUDA 8.0 or newer, or CUDA 7.0, with compute capability 3.5 at minimum, and CUDA 7.5 is called out as producing runtime errors on some devices. On a machine without a qualifying NVIDIA GPU you are on the CPU implementation, and the README makes no performance claim about that path. Anyone choosing CCTag for a real-time pipeline should measure the CPU path themselves rather than assume it matches the GPU one.

CCTag compared with square fiducial systems

The obvious alternative is a square-marker library such as ArUco or AprilTag. The difference in approach is geometric. Square markers give you four corners, and pose is recovered from those corners; the corners are easy to find and the identity is read from the interior bit pattern. CCTag gives you concentric circles, and the design goal stated in the paper title is accurate localization of circular fiducials under conditions the authors call highly challenging. A circle center is estimated from many edge points around the ring rather than from four corners, which is the argument for using it when sub-pixel center accuracy matters more than the simplicity of corner detection.

The trade-off runs the other way too. Square markers are trivially printable on any flat surface with an ordinary printer, and their detection libraries are widely embedded in robotics and AR tooling. CCTag requires you to respect the margins the project provides and to keep the support planar, and it requires a C++ build with CMake. If your markers will end up on a curved object, or you want a marker system you can prototype in an afternoon with a Python binding, the square families are the more practical choice. The related searches around CCTag do include people looking for Python usage, but the README documents no Python binding, only the C++ library interface and the detection executable.

Maintenance, licensing and what upgrades cost

The repository is not archived, and the last push was on 2026-08-01. That is recent enough that the develop branch is receiving changes. Releases move more slowly: v1.0.4 landed on 2024-06-23, preceded by v1.0.3 on 2022-10-18 and v1.0.2 on 2022-07-14. The pattern is a stable tagged line with a much busier default branch, so if you pin to a release you are pinning to something roughly two years behind the current tree. CHANGES.md exists at the top level for reading what moved, and there is no separate stable branch documented in the README.

The upgrade cost is dominated by the CUDA constraint. The Dockerfile defaults to CUDA_TAG 10.2 and OS_TAG 18.04, with a comment showing how to override them, for example building an Ubuntu 16.04 image with CUDA 8.0 for development. If your toolchain has moved past those base images, you are rebuilding the dependency layer yourself; the Dockerfile_deps file is the starting point. The vcpkg.json manifest is the other dependency route.

On licensing, CCTag is under MPL v2, per COPYING.md. The MPL is file-level copyleft: modifications to files already covered by the licence stay under it, while larger works that combine CCTag with other code can generally be licensed differently. That is a summary of the licence's structure, not legal advice. If you are shipping a closed product that links the library, have your own counsel read COPYING.md rather than relying on a blog summary.

Editorial conclusion

Adopt CCTag if you need sub-pixel localization of printed circular fiducials on flat, rigid support and you can build a CMake project against a CUDA-capable GPU or accept the CPU path. Do not adopt it if your markers will be printed on corrugated or bent paper, or if you need four-ring tags right now, since the README says those are still to come. Before committing, print a marker from markersToPrint at the documented margins, run build/src/detection -n 3 -i sample/01.png to confirm the build works on your machine, and check your card against the CUDA compatibility list the README links, because compute capability 3.5 is the stated floor.

Frequently asked questions

Official sources

1. alicevision/CCTag on GitHub
2. License: MPL-2.0
3. Project website
4. README
5. Releases