Projection Mapping with the Raspberry Pi

They’re compact, affordable, and powerful enough to handle a wide range of projects. In this article, I’ll go over some Pi-powered options and simple setup. Whether you’re a projection mapping beginner or pro, the RPi may be perfect for your next project.

As a disclaimer to this article. Basic Linux commands and knowledge are recommended for anyone looking to work with a Raspberry Pi. The exception to this, the minimad, integrates with MadMapper’s software and is easier to set up. PocketVJ runs off of ofxPiMapper and features a web portal for control, but ofxPiMapper by itself will take a little bit of research to become proficient at it. I’ve been using Raspberry Pi’s for installations and various projects for years now.  My longest running Pi install has been going on for 3 years now, and I have yet to replace anything more than a microSD card. This is not a guarantee that the Pi is perfect for you, but it should come as a reassurance that they’re built to last.

When it comes to projection mapping with the Raspberry Pi, a few options come to mind. Madmapper’s miniMAD, ofxPiMapper, and the all-in-one PocketVJ. All three are excellent choices, and between each of them, there are some pro’s and con’s that you’ll want to take into consideration.


If you haven’t tried it already, open frameworks PiMapper, simply works. You’ll want to plug a keyboard and mouse into the device to control it, but it boasts a wide feature load and continual developer support.


  • Price (Free)
  • Open source
  • Circle Surface
  • Grid Warping


  • Small learning curve
  • No Sync



I’ve documented how easy it is to get up and running with the miniMAD here: but with its price point of $220 + a mad mapper license ($420 own, $42 / month rent), it may stretch your budget further than you’d like. Currently, the considerable advantage that the miniMAD has over all other RPi mappers that you can Sync a lot of them over ethernet for multi-mapped installations. It uses Madmapper (Mac/PC) for setup, which makes it the most natural RPi projection mapper that I’ve tested. Here’s a gif from the developer of 28 miniMADs in sync.



  • Intuitive setup
  • Video sync
  • DMX lighting control
  • OSC control w/ TouchOSC layouts
  • GPIO buttons


  • Limited customization (not open source)
  • No Wifi
  • Price / Requires MadMapper (not a terrible thing!)



PocketVJ 3.5 is a portable multimedia tool based off of the Rasberry Pi platform. It hosts a wide feature set that easily accessed on a Phone or computer through a custom web control panel (CP). Unlike the miniMAD, the PVJ supports wifi connections and video player sync. But like ofxPiMapper (which the PVJ uses), you cannot sync mapped content. An easy way around this is to record the mapped output from a computer. Load the pre-rendered videos back onto the Pi and play them in sync. Since the PVJ has Pi Wall and a sync’ed video player, you string them together for a multi-projector installation. Not to mention, you can run custom scripts through the web CP and automate your installations.


  • Open source
  • Web control panel (Access from phone or computer)
  • Video sync over Ethernet or Wifi (not with mapping)
  • Projector remote control & scheduling
  • Screen Sharing
  • VJing
  • Pi 3 compatible
  • Image view
  • FTP Browser
  • Image player
  • TCPSyphon
  • OLA, DMX, & QLC+ support.
  • Customizable
  • Video Sync*
  • Pi Camera supported
  • OSC control (Latest version 8.15.2018)
  • Tutorial videos and documentation


  • No video sync with mapping.
  • Learning curve.


If you have a Raspberry Pi 2 or 3 laying around, you can go here, follow the instructions and build a pocketVJ from scratch or support the developers by buying a PVJ from Switzerland. If you do it yourself, make sure to update the CP (control panel) to the latest version: here follow the instructions on the page, and you’re up to date.


If you want a miniMAD, you’ll have to buy one from Madmapper. Don’t forget to buy or rent a MadMapper license if you don’t already have one.

USA customers:

Everywhere Else:


ofxPiMapper & install

Here’s one you can set up now.

Go to and download the disk image. (It should end in a

Support the developers 🙂 if you’d like.

Download and install Etcher (Mac/PC/Linux).

Insert a MicroSD card into your computer, open Etcher (it should auto-select the drive) select the PiMapper image, and click Flash.

projectileobjects pi mapper install

Once it’s done. Insert the microSD card into your pi. Plug in a USB mouse &/or keyboard. Power up the pi with it plugged into your projector. (optional, connect it to a network via Ethernet for additional features and control).

The Pi should boot up and present you with an example Triangle.

02 tutorial ofxpimapper1_4

Using 1, 2, 3, 4 to switch between the different modes, you can manipulate, and add layers, change the source video, and other adjustments using the keyboard. I recommend a “wired” USB mouse as I’ve run into issues with wireless mice movement being choppy. Experiment with it, and hit the “i” key if you want keyboard command info on the screen.

03 tutorial ofxpimapper2_4

If you want to access the Raspberry Pi command prompt, hit the “Esc” key and find yourself at a screen that says opm login: The username is “pi” and the password is “raspberry.” If you’re stuck at this menu. Log in and, type in “sudo reboot now” this will restart the pi and get you back to the example of ofPiMapper.

If you want to use your media plug in a USB thumb drive with the photos and videos (.mp4) and reboot the Pi. It should detect the files on the thumb drive for use in your new layers. (see the ofxPiMapper documentation for file types and troubleshooting).

04 tutorial ofxpimapper3_4-1

ofxPiMapper is not as easy as the PocketVJ’s web FTP & control panel or Madmapper’s export feature to the miniMAD, but if have a Pi and 30 minutes, this basic ofx mapping example is good enough to get you started.

If you like what you see thank the developers by supporting their projects.

Support PocketVJ with a purchase or by donating to via PayPal

Similarly, PiMapper has multiple donation options on their website:


17 thoughts on “Projection Mapping with the Raspberry Pi

  1. kida23 says:

    Thanks so much for putting all this ace info out! Really informative. I recently was gifted a Rasberry Pi 4 and I am wondering if the 4 is compatible with Pocket VJ or Pi Mapper? If not is there an alternative that you know of?


    – john jack


  2. john jack says:

    Such an ace article. Thanks so much for putting this all out. I have a question, I was recently just gifted a brand new Rasberry Pi 4 for Christmas. Is Pocket VJ or Pi Mapper installable and useable on the 4?


      • syntheticlives says:

        Haha, here I am 3 years later actually putting this thread to use! Thanks again for posting this. Have you run into any problems with Pi Mapper and certain projectors? I got everything set up and working on my Pi with my Optoma projector yesterday, then when I went to test out an installation on a BenQ today, Pi Mapper no longer worked. It would essentially show that booting screen that looks like a bunch of command lines then nothing would happen, the projector would say searching for source. I connected everything in the proper order, rebooted, etc. It seemed like the BenQ thought there was no source when the Pi was booting. I had switched off the auto source select as well. Have you run into anything like this?


      • projectileobjects says:

        It sounds like an EDID issue. You can usually test to see if this is the problem with something like the Dr.HDMI. It’s also possible that the Pi is sending out a resolution (or Pi Mapper is forcing a resolution) that the BenQ does not accept. I’ve definitely ran into Raspberry Pi issues in the past where my older Viewsonic projector couldn’t find the source. I got around this by manually setting the resolution for the pi at boot in the config file. This might help:

        Let me know if it works and thanks!


      • syntheticlives says:

        Wow, thanks so much for the response, it’s really awesome to have someone to bounce questions off of. It sounds like the link you posted might help, unfortunately the projectors in question are being used in a gallery install at the moment (not running off Pi unfortunately) so I can’t test for sure. But will definitely give this a shot once I have access again. Thanks so much for your help and all the info you post on here, it’s really appreciated!

        Liked by 1 person

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s