SLStudio: real-time structured light from a camera and a projector

A scanner you assemble, not a scanner you buy

SLStudio is designed to enable anyone to implement a custom 3D structured light scanner using a single camera and light projector. It is modular and has a focus on processing speed, enabling real-time structured light capture at 20 Hz and more.

The performance number comes with a caveat that the README states plainly: when using a standard commercial projector and a webcam, the obtainable speed is lower due to the lack of hardware triggering. That is the central engineering fact of the project. A structured light scanner is a camera and a projector that have to agree on exactly when each frame was captured relative to each projected pattern, and without a hardware trigger line the timing is a guess. Everything else in the software exists to make that timing work.

The project is the academic work of the author and there is a specific publication to cite when using it in research: Wilm et al., SLStudio: Open-Source Framework for Real-Time Structured Light, IPTA 2014.

The repository layout matches a research codebase rather than a packaged application. There is a src/ directory, example_data/ with the demo data, a matlab/ directory, a tools/ directory, a trigger_circuit/ directory for the hardware side, and a circles_calibration_pattern.pdf in the root. There are no GitHub releases, so the project is a repository you build rather than a package you install.

The last push was on 2026-09-13 and the repository is not archived, and the primary language is C++.

The licence changed in August 2021, and that is the first thing to read

The licensing paragraph is the most consequential text in the README, and it is worth reading in full before anything else.

Usage is permitted under GPLv3 license since August 2021, and any distributed derivative work, internally or externally, must be published openly. Use before that date constitutes copyright violation. A commercial license can be obtained for commercial users not wanting to disclose their source code, and feature and functionalty development on a contract basis are also offered, with a request to contact the author.

That is a licence change with a hard cutoff, and it applies to more than you might expect. The wording covers work distributed internally as well as externally, so an organisation that forks SLStudio and keeps the fork private is in scope, not just one that ships a product.

The repository itself is recorded as carrying a custom licence that GitHub could not classify, with the LICENSE file named as the place to look. Combined with the GPLv3 statement in the README, the practical advice is to read the LICENSE file rather than infer from the badge, and to contact the author if your use case is proprietary.

The demo videos are a good way to see what the software does before reading further. There are demos of real-time 2x3 phase shifted patterns, of calibration, and of example data, and a screenshot of the realtime setup with optical filters and an enclosure, which is the physical arrangement the timing requirements force on you.

Dependencies, and a project file rather than a package manager

SLStudio is being developed with qmake, in QtCreator, and the /src/SLStudio.pro file is the project file which contains all information about the project and its dependencies needed for compiling.

The dependency list is long and specific. Qt 5.X is the baseline, with the note that 4.x or 6.x could be used with relatively few modifications. OpenCV 4.x or newer, with 3.x usable with relatively few modifications. Point Cloud Library 1.7 or newer. VTK 7, with the warning that newer versions do not seem to support PCLVisualizer. Then Boost, Eigen, FLANN and GLEW. And depending on the camera, libdc1394, the FlyCapture API, the XIMEA xiApi or the IDS Imaging uEye API.

The camera libraries are the part that tells you what hardware this was tested with. FireWire, Point Grey, XIMEA and IDS are four different vendor stacks, and the project treats them as first-class rather than hiding them behind a generic interface.

On Ubuntu 22.04 all of the dependencies are available as packages except the camera libraries, and the README gives the install line:

    sudo apt-get install libpcl-dev libopencv-dev libvtk9-qt-dev libglew-dev freeglut3-dev qtcreator libusb-1.0-0-dev qmake6 libxrandr-dev

The project has been successfully compiled on Ubuntu 22.04, OS X 10.9 and Windows 7, and the tested and recommended OS is Ubuntu 22.04.

The Windows story is the cautionary one. OpenCV and PCL are available as downloads there, but since everything needs to be ABI compatible, it is probably best to compile the dependencies from source with the same compiler, for example MSVC, which is rather time-consuming but possible. And it is some time since the code was last compiled on Windows, though all of the code should be compatible.

The algorithm classes are meant to be copied, not linked

The component structure is the most reusable part of the project and the README is direct about how to use it.

The mathematical, algorithmic and hardware interface parts reside in individual classes from the presentation layer and business logic. The algorithmic classes, named as Codec*, Triangulator, Camera and Projector, have very few external dependencies and are designed to be used on their own or in different environments. The Matlab interface shows what this might look like.

And then the recommendation, which is unusual and worth respecting: while the algorithm classes could easily be separated into a static or dynamic library, the maintainers see little value in doing so, and recommend copying the relevant classes to a new project, with a note to check the licence terms.

That is an honest position rather than sloppiness. A static library of this kind would carry a build configuration burden, and the classes that matter, the codec for the pattern sequences, the triangulator for turning correspondences into points, the camera and projector wrappers, are self-contained enough to lift.

The Matlab side follows the same logic. The project contains Matlab mex-wrappers for the OpenGL projector and Camera, which makes it possible to determine the gamma response of a camera and projector setup or handle other debugging tasks. Those are compiled from Matlab by running matlab/make.m, and they were tested on Ubuntu only.

The gamma response point is a good example of what a research user needs that a product user never would. A camera and a projector do not agree on what grey means, and without characterising that mismatch the reconstruction is biased.

Hardware triggering, pattern rates and the Ubuntu two screen trick

The realtime section explains why the trigger hardware exists and what it costs to set up.

In the preference pane, software and hardware triggering can be selected, and the calibration procedure always uses software triggering. For real-time structured light you need hardware triggering from the projector to the camera by means of a trigger signal cable. Few projectors provide the trigger output signal, but with some effort you may be able to source one from the HDMI vsync pin. LightCrafter4500 has trigger output pins and is the recommended device, and you have to produce a trigger cable with the specific headers of your projector and camera.

The throughput arithmetic follows from that. With commercial projectors you can usually project 60 patterns per second at most, and the LC4500 allows for 120 8-bit patterns per second. Usually the camera requires a pause between two consecutive exposures, so you need to waste one refresh period. With the LC4500 that works out to 60 grayscale patterns per second, resulting in up to 20 point clouds per second.

The camera side has a similar caveat. Because high performance operation of cameras often requires vendor or device specific features or setup, the project does not use an intermediate layer such as OpenCV to communicate with the camera, and instead provides wrappers for a number of camera APIs, inviting others to contribute. The warning is that only a limited number of cameras have been tested, some of the configurations performed may only apply to the specific models used, such as images being assumed to be in grayscale, and in any case you may need to modify some of the camera code to get this to work with hardware triggering, which is required for real time performance.

On Ubuntu there is a detail worth knowing before you start. Ubuntu has all the dependencies as packages except the camera libraries, and one advantage of using Ubuntu is that you are able to render structured light patterns on a secondary X screen, which does not interfere with the main screen in which the Gnome desktop and the SLStudio GUI run. By setting up two X screens in xorg.conf with a gap in between them, you can make Gnome completely ignore the second screen so it is only SLStudio that draws onto it, and that depends on the graphics driver supporting multiple X screens, which works with current proprietary nVidia and AMD drivers.

On OS X the dependencies come through MacPorts, but you do not get completely independent screens, so your measurements may be corrupted by GUI activity.

For projection, SLStudio can run in different projector modes, and OpenGL projection renders the structured light patterns on screen 2, with an HDMI connection to the projector. For the LightCrafter 3500, the 4500 and newer models, the software can communicate over USB with these projectors, which can preload the patterns.

Editorial conclusion

SLStudio suits a research group building its own structured light rig, since the camera and projector back ends are vendor specific and the algorithm classes are written to be lifted into another project, and the hardware triggering support is what separates real-time work from a demo. It does not suit you if you want a turnkey scanner, because the camera, projector, trigger cable and X screen setup are all your problem, and it does not suit a commercial product under the open source terms, since usage has been permitted under GPLv3 since August 2021 and a commercial licence is the alternative for proprietary work. Before you start, read the LICENSE file rather than assuming the earlier permissive terms still apply, and check that your camera and projector combination can output a trigger signal at all.

Frequently asked questions

Official sources

1. Issues
2. jakobwilm/slstudio on GitHub
3. README