Iridescence is a viewer for looking at point clouds while you write the algorithm

The stated scope is narrow, and the README says so twice

Iridescence is described as a light-weight visualization library for rapid prototyping of 3D algorithms, and the README is unusually blunt about who it is for and who it is not for. It says the library is designed for accelerating personal research and development projects, mainly focusing on point-cloud-related algorithms, and that it is NOT intended to be a general-purpose visualization library with rich rendering capabilities.

The features section then lists what it provides and what it does not, side by side. It provides an easy-to-use 3D visualization framework, particularly suitable for rendering point clouds, with tightly integrated Dear ImGui interfaces for rapid UI design. It does not provide realistic rendering and shading, and it does not provide rich textured 3D mesh rendering.

That double negative is unusual in a README and it is the most useful thing in it. Most visualization libraries advertise what they do; this one tells you the two categories of thing you will not find, which saves you from choosing it for a project that needs a textured mesh and then discovering the gap.

The repository topics list tells you the domain: imgui, localization, mapping, opengl, point-cloud, slam and visualization. That is the toolkit of someone working on SLAM and mapping, and the academic use examples in the README, images labelled with 2021 and 2022 paper acronyms, suggest the library grew out of published work.

The primary language is C++, the licence is MIT, the default branch is master, and the last push was on 2026-10-05. There are no GitHub releases, so the packaged distributions are the way to consume it.

Two languages, one viewer, and a Python package with a different name

The library ships as two things that share a codebase but not a name. The C++ side is Iridescence, consumed through CMake with a find_package call and a namespaced target. The Python side is pyridescence, published on PyPI, and the setup.py records version 1.0.3.

The Python binding is built with pybind11, and pyproject.toml shows the build stack: setuptools, scikit-build, scikit-build-core and pybind11, with the scikit-build cmake define BUILD_PYTHON_BINDINGS set to true and BUILD_SHARED_LIBS set to false. Building a static library into the wheel is what lets the wheel ship without asking users to match a shared object ABI.

The packaging details that matter for an install are in the same files. python_requires is 3.7 or later, install_requires is just numpy, and the package data lists pyridescence_data with its texture, shader and models subpackages mapped to the data/ directory in the repository. That is where the runtime assets live, the colormaps and the models the viewer draws.

There is also a MANIFEST.in at the top level and a package.xml, which is the ROS package manifest format, so the same library is packaged for ROS as well as for PyPI and the PPA.

The C++ side has its own build system. The repository has a CMakeLists.txt at the top level, a cmake/ directory, a thirdparty/ directory for the vendored dependencies, a src/ and include/ tree, and a docs/ directory with an mkdocs.yml for the documentation site.

Installing the C++ package on Ubuntu and the Python wheel

The C++ install is a personal package archive, and it is two commands.

sudo add-apt-repository -y ppa:koide3/iridescence
sudo apt install libiridescence-dev

The build badge lists Ubuntu 22.04 and 24.04 and Windows, so the PPA is the supported path on Ubuntu and something else is expected on Windows.

The Python install is a single pip command.

pip install pyridescence

And there is one constraint worth reading before you install. The README notes that source installation is required for Python 3.14.

That is a packaging detail with a real consequence. The wheel set is built with cibuildwheel, and pyproject.toml configures the manylinux images for x86_64 and aarch64 against manylinux_2_28, with the skip list excluding PyPy, Win32, i686 and musllinux. If your interpreter is outside that matrix, you are building from source, which means a C++ toolchain and a working CMake setup on your machine.

The source route for C++ is the one that documents its dependencies.

sudo apt-get install -y libglm-dev libglfw3-dev libpng-dev libjpeg-dev libeigen3-dev

git clone https://github.com/koide3/iridescence --recursive
mkdir iridescence/build && cd iridescence/build
cmake ..
make -j
sudo make install

Note the --recursive on the clone. The dependency list includes GLFW, gl3w, Dear ImGui, ImGuizmo, implot, Eigen, rapidhash and portable-file-dialogs, and several of those are submodules, so a plain clone leaves you with a tree that will not configure.

The Python source install is shorter, since pip handles the build.

git clone https://github.com/koide3/iridescence --recursive
cd iridescence
pip install .

Again with --recursive, and again for the same reason.

Consuming the C++ library from a CMake project

Once installed, the C++ side is consumed as a normal CMake package, and the README gives the three-step form.

find_package(Iridescence REQUIRED)

add_executable(your_program
  src/your_program.cpp
)
target_link_libraries(your_program
  Iridescence::Iridescence
)

The find_package call, the target definition and the namespaced target name. There is no include directory to add by hand and no library path to set, because the imported target carries them, which means the compiler flags the library needs, such as the C++ standard and the OpenGL libraries, come with the target rather than from your own flags.

That matters for a library that pulls in GLFW and Dear ImGui. If you had to configure those yourself you would be tracking the OpenGL loader and the ImGui backends by hand, and the versions would drift from what the library was built against. The imported target is the mechanism that prevents that.

The alternative is building from source, which the README describes as cloning with --recursive, creating a build directory, running cmake and make, then installing. The difference from the package route is that you own the build of the vendored third-party code as well, which is what you want when you need to patch a dependency or build against a local copy of Eigen.

A viewer singleton, drawables by name, and ImGui inside the render loop

The C++ minimum example is short enough to read in full, and it shows the shape of the API.

#include <glk/primitives/primitives.hpp>
#include <guik/viewer/light_viewer.hpp>

  // Create a viewer instance (global singleton)
  auto viewer = guik::LightViewer::instance();

The viewer is obtained from LightViewer::instance() and is described in the example as a global singleton, so there is one window per process and the example never constructs one itself.

Then there is a UI callback registered with register_ui_callback, and inside it you call Dear ImGui commands directly.

  viewer->register_ui_callback("ui", [&]() {
    ImGui::DragFloat("Angle", &angle, 0.01f);

    if (ImGui::Button("Close")) {
      viewer->close();
    }
  });

That is the tight ImGui integration the features list promises. Your widget code and your 3D content live in the same process and the same frame, so a slider that controls a point cloud transform updates the cloud with no marshalling between a GUI framework and a renderer.

The drawable model is the other half. Objects to be rendered are called drawables and are managed with unique names, and the example registers a solid sphere and a wire sphere with the names sphere and wire_sphere. The coloring schemes are named too: the Rainbow scheme encodes the height of each fragment using the turbo colormap by default, and FlatColor takes an RGBA value. The Rainbow scheme is the one that matters for point cloud work, because height colouring is how you see the structure of a scan.

The Python example mirrors this exactly, with guik.LightViewer.instance(), imgui.drag_float, viewer.update_drawable and the same sphere and wire_sphere names, and it transforms the primitives with a rotation matrix built from scipy.spatial.transform.Rotation. The parallel structure is deliberate, so a workflow transfers between the two languages.

The dependencies, and what each one is doing there

The dependency list is short enough to read one by one, and each entry tells you what part of the design it supports.

GLFW is the windowing and input layer, gl3w is the OpenGL function loader, Dear ImGui is the immediate mode GUI, and ImGuizmo is the transform gizmo, the little arrows and rings you drag to move things in the viewport. implot is the plotting library, which is what you would use to draw a residual plot or a histogram next to the 3D view.

Eigen is the linear algebra library, which a point cloud pipeline needs anyway, and portable-file-dialogs is the native file open and save dialog, so the viewer can load a point cloud without you wiring a file dialog yourself. rapidhash is a fast hashing library.

The licences are listed per dependency, which is a good sign for a project that vendors them: GLFW is under the zlib and libpng licence, gl3w is public domain, Dear ImGui, ImGuizmo, implot and rapidhash are MIT, Eigen is MPL2, and portable-file-dialogs is WTFPL.

That mixture is the practical detail. Iridescence itself is MIT, but the binary you ship includes ImGuizmo under MIT, Eigen under MPL2, which is a file-level copyleft licence, and portable-file-dialogs under WTFPL, which is the most permissive of the group. Anyone distributing a build should read those terms, and the README helpfully links each one, rather than assuming the top-level licence covers the tree.

Where Iridescence is the wrong tool

Two cases, both of them stated in the README rather than inferred, and one that is about your own workflow.

The first is a product that needs to look good. Realistic rendering and shading is out of scope, and so is rich textured 3D mesh rendering. If your output is going to be seen by anyone other than you, a figure in a paper, a demo, a screenshot for a marketing page, Iridescence is the wrong tool, because you would spend your time fighting the absence of shading rather than doing your algorithm work. The library is a research instrument and it is shaped like one, with a Dear ImGui interface and no asset pipeline.

The second is if you need a general 3D viewer with the features you already know. The stated design intent is accelerating personal research and development projects, and the opinionated parts are the ones that make it fast for its audience: a global singleton viewer, drawables registered by name, and the ImGui callback loop. A general library would give you more control over the render pipeline and less of a shortcut.

There is also a Python version constraint that bites at the wrong moment. The README says source installation is required for Python 3.14, and the wheel matrix skips PyPy, 32-bit Windows and musllinux entirely. If your team is on one of those, the pip install line in the README is not enough and you are in the C++ build path with all that implies.

One last practical note on the C++ side. The clone in the README uses --recursive, and the repository carries a thirdparty/ directory plus submodules. A plain clone gives you a tree that looks complete and does not configure, which is a confusing way to spend an afternoon.

Editorial conclusion

Adopt Iridescence if you are prototyping a point-cloud or localization algorithm and want to look at the output while you work, and you are comfortable with a Dear ImGui interface rather than a polished one. Do not adopt it for a product that needs realistic shading or textured meshes, since the README rules both out explicitly. Verify first that the wheel you install matches your Python version, because the README says source installation is required for Python 3.14, and read the build workflow before you build the C++ side yourself, since several dependencies are vendored as submodules.

Frequently asked questions

Official sources

1. Issues
2. koide3/iridescence on GitHub
3. License: MIT
4. Project website
5. README