Pangolin: OpenGL Display, Interaction and Video Input for C++ Prototypes

What Pangolin removes from a vision prototype

The problem Pangolin addresses is the boilerplate between an algorithm and a window. A camera calibration routine, a stereo matching experiment or a point cloud viewer all need the same scaffolding: create a context, open a window, handle resize and keyboard events, upload a texture, draw it, and read frames from a camera. Pangolin packages that scaffolding as a set of utility libraries rather than a framework. The README describes it as "a set of lightweight and portable utility libraries for prototyping 3D, numeric or video based programs and algorithms," and notes it is used widely in computer vision to remove platform-specific boilerplate.

The intended user is an engineer who already has C++ code and wants to see what it produces. The repository layout reflects this: examples/ contains small, single-purpose programs such as HelloPangolin, SimpleDisplay, SimpleDisplayImage, SimplePlot, SimpleVideo, SimpleRecord, SimpleScene, VBODisplay and SharedMemoryCamera, plus a PythonExamples folder. Each example is a runnable answer to one question. That is the documentation model. There is no large manual; the README states that Pangolin is "mostly documented through its simple examples."

The secondary audience is Python users. If Python 3 is found during configuration, the pypangolin module is built with the default all target, and the README points to examples/PythonExamples for the Python versions of the same ideas. This matters for researchers who prototype in Python and only later move to C++.

Windowing, viewports and video as interchangeable components

Pangolin is split into components so you can include only what you need, and most dependencies are optional. The README groups them into build system (cmake, required), windowing system (X11, Cocoa, Win, Web), rendering (OpenGL, GLES), video and image loading (DC1394, ffmpeg, jpeg, png), and wrappers or cross compilers (Python3, pybind, Emscripten). The ethos stated in the README is to "minimize boilerplate and maximize portability and flexibility through simple interfaces and factories over things like windowing and video." Factories are the architectural point: the same application code can target a native window, an off-screen buffer, or the web through Emscripten.

The data flow for a typical display program is short. You create a window and a viewport, register handlers for interaction, and then in a loop you upload your data (an image as a texture, geometry as a VBO) and call the display. SimpleDisplayImage and VBODisplay exist as the two ends of that spectrum: one shows a 2D image, one shows vertex buffer objects. For video, Pangolin provides "extensive video input/output wrappers for ordinary and machine-vision cameras and media formats" plus "a flexible filter interface for easily post-processing video channels and formats." SimpleVideo and SimpleRecord are the examples to read for capture and writing.

Two debugging utilities are unusual enough to mention. Tweak variables give one-line definitions and extensible types for values you want to change at runtime. The drop-down console is described as Quake-like and extensible for different shells, with Python live console support currently, and it can introspect tweak variables. The README is candid that "there are 101 widgeting libraries and several 'tweak' var libraries" and that Pangolin offers another implementation with its own pros and cons. That honesty is worth noting: this is not positioned as the only or the best option, just a convenient one when you are already inside Pangolin.

Installing Pangolin on Linux and running a first example

The README gives a clone command that pulls submodules, then a script that installs prerequisites through whichever package manager it detects (apt, port, brew, dnf, pacman, vcpkg), then a CMake configure and build. The script can be inspected before it changes anything, which is the reason to use --dry-run first.

git clone --recursive https://github.com/stevenlovegrove/Pangolin.git
cd Pangolin
./scripts/install_prerequisites.sh --dry-run recommended

The dry run prints the package manager and the package list for the recommended set. If that looks right, drop the flag to install. You can also force a manager and a wider set, for example ./scripts/install_prerequisites.sh -m brew all.

./scripts/install_prerequisites.sh recommended
cmake -B build
cmake --build build

After configuration, check the output of the cmake stage for the Found and Enabled lines. This is the step people skip, and it is the one that decides whether ffmpeg, jpeg, png or a camera backend are actually present. Pangolin "does its best to build something with what it gets, so dependencies which are not found will be silently ignored." A build that succeeds is therefore not proof that the feature you need was compiled in.

To build the Python bindings, the README uses a dedicated target. Note that the wheel and install targets are documented as working only on macOS and Linux.

cmake --build build -t pypangolin_pip_install

For a first real use, the examples folder is the entry point. Build the project, then run one of the example binaries from the build tree, or browse the Emscripten builds of SimplePlot, SimpleDisplay and SimpleMultiDisplay in the browser to see the intended behaviour before compiling anything yourself. If you prefer Ninja, the README gives cmake -B build -GNinja and cmake --build build. Tests require Catch2, which the README says must be manually installed on Ubuntu, and are enabled with -D BUILD_TESTS=ON followed by ctest inside the build directory.

Silent dependency skipping is the main operational risk

The most consequential limitation is stated plainly in the README: missing dependencies are silently ignored. If you need a particular feature, you are told to check the cmake output for Found and Enabled. That is a workable policy for a prototyping library, but it produces a specific failure mode: a program that compiles, links and then behaves differently on two machines because one had ffmpeg and the other did not. The mitigation the README offers is to disable a dependency that is causing trouble by setting a BUILD_PANGOLIN_ option variable to false, which implies these options exist per dependency, but the README excerpt does not enumerate them. You will be reading CMakeLists.txt and the cmake/ directory to find the exact names.

A second constraint is platform coverage for the Python path. The README states that the python wheel and install targets currently work only on macOS and Linux, with "On Windows, you're out of luck right now. Help appreciated!" For Windows, the recommendation is to build natively with the Build Tools for Visual Studio 2019 toolchain, and the README explicitly calls mingw and WSL unsupported. If your team standardizes on WSL, that is a real boundary, not a preference.

A third point is branch policy. The README warns that master is a development branch and suggests choosing a stable tag if you prefer. Releases exist (v0.9.6, v0.9.5, v0.9.4), so pinning is feasible, but the default clone command follows master. Anyone who clones as documented is on the development branch by default.

Finally, Python version mismatches are a known sharp edge. The README tells you to be careful about which Python Pangolin found and linked against, and to override it explicitly with cmake -DPython3_EXECUTABLE=/path/to/python. If you have several interpreters, verify the configure output rather than assuming.

Where Pangolin is the wrong tool

Pangolin is not a GUI toolkit. There is no widget set, no layout engine, no data binding. The tweak variables and the drop-down console are debugging aids, and the README itself notes the crowded field of widgeting libraries. If you are building an application with menus, dialogs and persistent user state, the amount of code you would write on top of Pangolin exceeds what you would write in a toolkit designed for that job.

It is also not a rendering engine. Its rendering dependency is OpenGL or GLES, and the examples are about displaying data, not about scene graphs, materials or asset pipelines. If your project needs a physically based renderer, Pangolin gives you a window and a viewport and little else.

It is not a good fit for teams that cannot tolerate optional dependencies. Because features are enabled by detection, reproducible builds require you to pin the dependency set explicitly, either through the install script's package list or through the BUILD_PANGOLIN_ options. Projects with strict supply-chain or audit requirements will find the silent-skip policy at odds with their expectations.

And it is not a replacement for a camera SDK. Pangolin wraps video input and output across ordinary and machine-vision cameras, but vendor-specific controls and calibration workflows live in the vendor's own software. Pangolin is the layer that gets frames into your program and onto the screen.

Alternatives and how their approach differs

The closest comparison in the same problem space is OpenCV's highgui module. Both give you a window and a way to show an image, and both are used heavily in vision work. The difference is scope. OpenCV is an image processing and computer vision library that happens to include a minimal display module, while Pangolin is a display, interaction and video-input library that does not do image processing. If your program already links OpenCV, imshow costs you nothing extra and you avoid a second dependency. If you need 3D viewport navigation, multiple viewports, off-screen buffers, tweak variables or the Python console, highgui does not offer them and Pangolin is the more direct fit. A practical pattern is to use OpenCV for the algorithms and Pangolin for the visualization, since the two do not conflict.

Against a general windowing layer such as GLFW, the difference is the level of abstraction. GLFW creates a window and an OpenGL context and handles input events; everything above that, including viewport management, texture upload for images and camera capture, is yours to write. Pangolin sits a level higher and includes those pieces, at the cost of a larger dependency surface and the silent-skip behaviour described above. If you want a thin, predictable window layer and you are comfortable writing the display code, GLFW gives you fewer surprises. If you want the vision-specific conveniences, Pangolin saves the work.

For Python users, the honest comparison is to the scientific Python stack. Matplotlib and similar tools are better for static plots and publication figures, and they do not require a C++ build. Pangolin's Python bindings exist so that the same visualization code can be shared with a C++ application, not to compete on plotting features. The README's own framing supports this: the Python examples mirror the C++ examples.

Licence, maintenance and upgrade cost

Pangolin is MIT licensed, with the licence file at the repository root as LICENCE. MIT is permissive: it allows use in closed-source products provided the copyright notice and permission notice are retained. That is a description of the licence text, not legal advice; if your organization has a policy on third-party licences, run it through that process. One practical consequence of a permissive licence is that there is no copyleft obligation to publish your own changes, so you can vendor a patched copy if you need to.

The last push to the repository was on 2026-08-19, and the most recent release, v0.9.6, is dated 2026-08-19 as well, following v0.9.5 on 2026-04-10 and v0.9.4 on 2025-10-08. The project is not archived. The version numbering stays in the 0.9.x series, which is worth reading as a signal about API stability expectations rather than as a statement about quality.

Upgrade cost is dominated by the dependency model, not by the library API. Because optional dependencies are detected at configure time, moving between machines or CI images can change which features are compiled in without any change to your source. Pin the dependency set and the Pangolin tag together, and re-read the Found and Enabled output whenever either changes. If you build the Python bindings, remember that the wheel and install targets are documented for macOS and Linux only, so a Windows CI job that needs pypangolin is not currently supported. The examples directory is the de facto compatibility reference: when an upgrade breaks your build, the fastest check is whether the corresponding example still compiles.

Editorial conclusion

Adopt Pangolin if you are writing C++ (or Python through pypangolin) prototypes in computer vision or robotics and want windows, viewport navigation and video capture without writing platform code. Do not adopt it if you need a stable API guarantee, a Windows Python wheel, or a library whose optional features fail loudly instead of being skipped. Before committing, run the configure step and read the Found and Enabled lines to confirm that the components you need were actually detected, and check whether the master branch or a tagged release matches what you intend to ship.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. stevenlovegrove/Pangolin on GitHub