TL;DR: Don’t.
Installing
I’ve been interested in projection mapping for a long time. Due to various factors it’s been difficult to have all the right things at my disposal to work with it. You have to have a decent video card to handle distorting video in real time and push all the pixels to your main display and your projector. You need a projector, the brighter the better. High resolution is obviously nice. It all comes down to having somewhat expensive equipment, so it can be a hard hobby to crack.
![](https://crumpled.com/wp-content/uploads/2023/03/mpamap-layout-1-1024x575.png)
Luckily, I recently obtained a pretty good 1080p projector from the local Habitat for Humanity Restore for $45, and have been accumulating PC hardware for a couple decades. So, I finally got to throw some light at some shapes, but I needed the right software. My go-to is to try to find something open source, and go with that. Strangely (in my opinion) there are very few options for open source projection mapping software. Of the two I saw, Splash and MapMap, MapMap looked like it would be the easiest to spin up on. So down a rabbit hole I go….
First of all, the newest code repository for MapMap targets Ubuntu 16.04, which was released in 2016. Why would I want a Linux version? MapMap runs on Windows. Well, it’s the only version that supports cameras as an input. I’m definitely willing to do the ill-advised thing of installing an out-of-support operating system to install a niche piece of software, even if it means disassembling my laptop to install a second drive. Of course I tried it on the latest Ubuntu Studio first, just in case it would work; It didn’t. After trying Ubuntu 22.04, I wiped the drive and installed 16.04. MapMap installed nicely and actually ran pretty well.
Using
The first thing I wanted to try was the webcam input, since I went to all the trouble of installing Linux for the privilege. It worked! But only for a USB camera, or my integrated camera, whichever I chose first. If I cared to switch to the other camera, that would not work and I would need to restart the software. So one camera is okay, I could deal with that!
The next thing I wanted to try out is the OSC (Open Sound Control) support. OSC, I learned, is basically like MIDI, but for networks. You send little UDP packets with a parameter, and a value. The MapMap interface was truly nice, but it’s not something you could really wrangle during a performance. The main interface is there for you to set up your scenes, but you’d want to use something like MIDI or OSC to actually trigger your cues, or make some adjustments in real-time. MapMap, or any projection mapping software, leverages those protocols because there are a ton of flavors of interface out there, and they don’t have to design any of them.
![](https://crumpled.com/wp-content/uploads/2023/03/touchosc-screens-16-1-1024x682.jpg)
The intention was to use OSC from Processing to interface with MapMap so I could use various devices as inputs and I could use Processing’s art magic to do cool stuff by writing code. I had never used OSC, and I was looking for a quick “Hello World”. After trying some open-source things, I discovered TouchOSC, which is a sweet-ass app that runs on every platform. TouchOSC is used to make interfaces, which they call “Control Surfaces”, that you can wire up to send MIDI and/or OSC messages. It even can send MIDI over the network if you install their MIDI bridge on the destination device. By default, the TouchOSC control surfaces look almost like the interfaces on Star Trek: The Next Generation. Anyway, TouchOSC is absolutely great and I’m literally sold on it.
Looking at the MapMap OSC documentation was very encouraging. Here’s a picture of a excerpt:
![](https://crumpled.com/wp-content/uploads/2023/03/mapmap-osc-mappings.png)
When you make a TouchOSC control surface, you create interface elements that automatically send OSC messages. Unfortunately, you’re going to have to do a little more to get these messages to send to MapMap. Notice above, in the documentation image, see those paths? They’re nested paths, and you can see that some of them take multiple parameters. Then there’s also that ‘,is’, or ‘,if’ thing.
At this point, I need to backtrack a little. I didn’t try TouchOSC right away. First I tried to find any evidence of anybody, anywhere, using OSC with MapMap. I could not find anything real besides the documentation and was ready to leave this path altogether (for what? IDK), when I finally found this YouTube video of someone using OSC with MapMap. It’s just a brief, hand-held video pointing at a computer screen. The author doesn’t say anything or explain sh*t. It’s like that photo of bigfoot, I saw real evidence of something. The person was using a program called QLC+, which I was able to install on Ubuntu 16.04. I don’t recall the details, but that software was more than I wanted to reckon with. But, I saw the crummy video, and I now knew I could use OSC, so what else could I try? That’s when I looked deeper and found TouchOSC.
If you want to send messages to the paths listed in the MapMap documentation, you’ll have to write scripts for each of your interface elements in TouchOSC. I’d share my examples, but nobody is going to be doing this on my account.
I also struggled with those ‘,is’ and ‘,if’ things in the documentation. What are those? What’s the correct way to pass that part of the message? I was laying in bed one night and realized they weren’t even part of the messages. They are the data-types for the parameters! ‘is’ means Int and String! There could have been a sentence explaining that, or a different way to document that, but really it’s my fault for not knowing OSC, or whatever this documentation convention is.
Finally I was off and away! every OSC command I tried worked! MapMap for Linux was starting to look pretty good!
MapMap’s Conclusion, or, How it Went Down
Remember how I was running a Linux from 2016? Well, I was prompted to install version 18.04. I went for it. I figured that it was going to keep the apps I had managed to install. It did keep MapMap, but it wouldn’t run. I then built MapMap from the source code, and it ran again. Unfortunately, this time, the webcams didn’t work at all, which was the whole reason I was on Linux in the first place. I then followed another update prompt to bring me to version 20.04, knowing full well that MapMap would be very unlikely to run. It didn’t build or run again. I think the incompatibility stems from the version of QT used to write the app, and lack of contemporary support for that version of QT.
Epilogue: Next Steps
After abandoning MapMap I looked at Splash (the other open-source software I mentioned earlier) but was repelled by the interface. I downloaded HeavyM, which was probably, partially, inspired by MapMap, based on the interface. If there’s some cross-over in development there I’m not aware of it. HeavyM is closed-source software but it is excellent. It’s much easier to map to OSC commands as well, without the need to write any scripts in TouchOSC. I kept my Linux drive in my laptop, but installed the latest Ubuntu Studio instead.
4 out of 4 of the first projection mapping software packages I’ve looked at seem to come from France. Is video mapping a French art form?
— Richard Call (@crumpledelex) February 6, 2023