MapMap: open source software for projection mapping onto real objects

What projection mapping is, and why the software is hard to find

The readme opens with a definition of the technique, and it is a good one. Projection mapping, also known as video mapping and spatial augmented reality, is a projection technology used to turn objects, often irregularly shaped, into a display surface for video projection. These objects may be complex industrial landscapes, such as buildings.

Then the mechanism: by using specialized software, a two or three dimensional object is spatially mapped on the virtual program which mimics the real environment it is to be projected on. The software can interact with a projector to fit any desired image onto the surface of that object.

What that means in practice is that a flat rectangle of projected light has to be deformed, per pixel, so that it appears to wrap around a corner, follow a curve, or sit correctly on a face of a building. The mapping is the correspondence between the video frame and the physical surface, and the software has to know the geometry well enough to compute it.

The readme is also clear about who uses this and why it looks the way it does. The technique is used by artists and advertisers alike who can add extra dimensions, optical illusions, and notions of movement onto previously static objects. The video is commonly combined with, or triggered by, audio to create an audio-visual narrative.

That last clause is the part that separates a demo from a performance tool. A projected show that reacts to sound needs the mapping to stay locked while the input changes, and it needs the operator to be able to trigger things live.

MapMap is described simply as free video mapping software, and the fact that it exists under a free licence is itself part of why it matters.

A Qt desktop application, not a web tool

The repository layout makes the technology choice clear. At the top level there is a mapmap.pro file, which is a Qt project file, and a main.qrc resource file, plus a src/ directory holding the code, resources/ for assets, third_party/ for vendored dependencies, translations/ for the localisation files, and an OSC entry alongside scripts/ and tests/.

The primary language is listed as C++, and the project builds on macOS, Ubuntu and Windows, with a build status badge for each of the three in the readme. The topic tags confirm the platform reach: linux, osx and windows, alongside projection-mapping, video-mapping and opensource.

The OSC entry at the top of the tree is worth a note. OSC, the Open Sound Control protocol, is a standard way to send control messages over a network, and having it in the root of the project rather than buried in a subdirectory suggests it is a first-class interface rather than an afterthought. For a live performance tool, a network control surface is how a lighting desk, a sound system or a second machine drives the show, and the readme's description of video commonly combined with, or triggered by, audio fits that picture.

The tool is a desktop application that talks to a projector. It is not a library, not a service, and not something that runs headless in a render farm. That shapes who can adopt it and how.

The naming also reflects a long history. The repository is mapmapteam/mapmap, the default branch is dev rather than main, there is a CHANGELOG.md, a TODO file, a VERSION.txt and a CODE_OF_CONDUCT.md, and the authors list includes both the original lead developer and the current one. The readme's authors section names Alexandre Quessy as lead developer, release manager, technical writer and project manager, and Sofian Audry as the original lead developer and user interface designer.

Building it: the INSTALL file and a Qt dependency you have to avoid

The installation section is short, and the first line is a pointer rather than instructions: to build and install it, see the INSTALL file provided with the source code. The repository does contain INSTALL.md at the top level, alongside the build and source directories.

That is an honest state of affairs for a project of this kind and this vintage, but it does mean the build requirements live in a file rather than in a package manager, so an adopter needs to read it before committing.

There is one Linux-specific warning that is worth repeating because it is the kind of thing that costs an afternoon. To use the software on Gnu/Linux with window managers other than Unity, make sure that this package is NOT installed: appmenu-qt5, or else the menu will not show.

That is a specific and useful piece of troubleshooting advice. appmenu-qt5 is a Qt module that puts application menus into the global desktop menu, and it interacts badly with applications that draw their own menus, which is a common pattern for creative tools. A missing menu in a full-screen projection tool is not just inconvenient, because the operator cannot reach the controls, so the workaround is to uninstall that package.

The rest of the workflow is a normal source build. The project also ships a .claude/ directory and a docs/ folder, and the readme points to mapmapteam.github.io for more information.

Free software with a sponsorship history, and what that buys you

The acknowledgements section is longer than you would expect for a desktop tool, and it says something about the project's funding model.

The project is sponsored by Art Plus Code. It was made possible by the support of the International Organization of La Francophonie, with the same acknowledgement repeated in French. It also received the support of Perte de Signal.

This is a project with institutional backing rather than a hobby, and that is relevant to an adopter because it changes the question from whether it is maintained to who maintains it. The named roles in the authors list include lead developer, release manager, technical writer and project manager as one person, which is a sign of a small team with a clear owner rather than a wide group of occasional contributors.

The licence is GNU GPL v3, linked from the develop branch's LICENSE file. For a tool that drives a projector in a venue, the copyleft terms are usually not the deciding factor, since the software is not distributed as part of a product, and the project is explicitly free software rather than freeware in the loose sense.

The repository is not archived, and the last push was on 2026-09-18. There are no GitHub releases, so the version history is in CHANGELOG.md and in the VERSION.txt file at the root rather than in tags, and a project on the dev branch with no release tags means you should expect to build from source rather than download a binary.

The examples directory is small, with a couple of PNG files, and the docs/ directory is where the tutorials and reference pages live.

Where MapMap is the wrong tool

There are three situations where this is the wrong choice, and they are worth naming before someone spends a weekend on a build.

The first is if you need a turnkey installation on a machine you do not control. The project is source-first, the readme points to an INSTALL file rather than shipping a one-click installer, and the visual and audio work in a venue usually happens on a machine you do control but on a schedule you do not. The absence of release tags makes that worse.

The second is if your workflow is plugin-driven. Commercial mapping software in this space is built around an ecosystem of effect plugins and content libraries. MapMap is a standalone C++ application with a third_party directory of vendored code, not a host for other people's plugins, so content you have bought or built for a commercial tool will not move across.

The third is if you need real-time precision on a large or complex surface. Projection mapping quality depends on the accuracy of the geometry you supply, and the mapping of a building facade with hundreds of points is a craft in itself, with the software providing the warping and the operator providing the mesh. The readme does not describe calibration aids, edge blending, or warping of complex geometry beyond the basic two or three dimensional mapping, so a demanding installation may find those features elsewhere.

The narrower point, and the honest one: MapMap is for people who want to do this without buying anything, and it will give them the mapping. Everything beyond that is the operator's craft.

Editorial conclusion

MapMap fits an artist or installer who needs to warp video onto a physical surface and wants free software rather than a commercial mapping suite, and it does not fit a team that needs a maintained cross-platform installer or a plugin-driven workflow. Before you commit, read INSTALL.md in the repository to see what the build requires, confirm your projector setup can feed the machine MapMap runs on, and try a simple test before assuming the mapping and audio triggering will suit a live performance.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. mapmapteam/mapmap on GitHub
4. Project website
5. README