README.md

Shape Mapper

shapemapper.dev/

Shape Mapper is a Processing library for projection mapping.

Warning

Shape Mapper is currently in beta. The library has been used for production installations, but has not yet been tested by the wider community, and some changes may occur based on feedback.

👩‍💻 Example code

Here is a minimal example showing what the library interface looks like:

import spacefiller.shapemapper.ShapeMapper;
import processing.core.PShape;

ShapeMapper mapper;
PShape shape;

void setup() {
  fullScreen(P3D);
  shape = createShape(BOX, 100, 200, 300);
  mapper = new ShapeMapper(this, shape);
}

void draw() {
  background(0);

  mapper.beginMapping();
  shape(shape);
  mapper.endMapping();
}

Find more examples in the repository, packaged within the library, or on the documentation site.

🪛 Installation

1. Ensure you have the most recent version of Processing installed.
2. Download Shape Mapper v0.1.7.
3. Open file on your computer; the library will be automatically installed.

📜 Documentation

Go to the documentation site.

💪 Use cases

Projection mapping is the process of calibrating a digital projection to align with a three dimensional surface. The Shape Mapper library is useful if you have a 3D model of the object you want to projection map. Some example workflows:

• Create a model using 3D software such as Blender, fabricate it with a 3D printer, and projection map it using Shape Mapper.
• Take precise measurements of an object and reconstruct it using 3D software such as Blender, then projection map it using Shape Mapper.
• Use Processing code to model a physical object, then projection map it using Shape Mapper (works well for simple primitives such as cubes).

If you do not have a 3D model of the object you are trying to projection map, or you are not able to create a model in code, this library will probably not be useful to you. It is still very much possible to projection map your object, though! Check out the Keystone library for Processing, or software such as MadMapper, Resolume or TouchDesigner for alternative projection mapping solutions.

✨ Features

• 🧮 Calibrate your projection by manually aligning at least 6 points; the mapping for the rest of the object will be automatically estimated.
• 🗺 Supports mapping multiple shapes at once (i.e. if you have two or more separate objects).
• 📽 Supports multiple mappings per shape (i.e. if you have two or more projectors).
• 💾 Calibrations are saved to disk.
• 🎭 Supports face masking, which allows you to avoid projecting twice onto the same face if using more than one projector.

🤷‍♂️ Non-features

Shape Mapper does not (yet) support:

• Blending between projectors
• Built in projection mapping effects (all effects must be drawn by the user with code)

🙏 Credits & Acknowledgements

Shape Mapper is by Alex Miller (x: @spacefillerart, ig: @space.filler.art, bs: @spacefiller).

Shape Mapper is heavily inspired by and based on the mapamok library for openFrameworks, originally developed by Kyle McDonald as part of ProCamToolkit, co-developed by YCAM Interlab. It expands on the feature set of mapamok with multi-shape and multi-projection support.

Thanks to Raphaël de Courville (@SableRaf) and Claudine Chen (@mingness) for their help & support with Processing library development.

For camera control, Shape Mapper uses the Peasycam library by Jonathan Feinberg.

For estimating the projection mapping matrix, Shape Mapper uses OpenCV.

This library was initially developed at Gradient. Thanks to Avi for the week of focus.