SketchMapper

The SketchMapper library offers a GUI tool and code to allow you to
create sketches and map them onto surfaces.
This is built off of SurfaceMapper by ixagon
and SurfaceMapperGui by Jason Webb
and works in Processing 2.2.1 and 3

Last update: 08/17/2018

Download

4.2.0 for Processing 3 released 08/17/2018

3.0.2 for Processing 2 released 03/10/2016

Previous Versions

Installation

Unzip the SketchMapper.zip archive and put the extracted SketchMapper
folder into the libraries folder of your processing sketches.
The reference, examples, and source are included.

Reference

Check out the Javadocs.

Source Code

View the source on GitHub.

Examples

SketchMapperTest

Simple example. You will need both of these files:
SketchMapperTest.pde
TestSketch.pde

LoadLayoutTest

Example showing loading a default layout. You will need:
SketchMapperTest.pde
TestSketch.pde
test_layout.xml ( in the sketch's data folder.)

Usage in Code

This section is about how to use the library in your processing sketches.

Creating sketches

NOTE: in order to use this library you must also import ControlP5 v2.2.6

This library provides a Sketch interface and AbstractSketch base implementation that are to be extended to create skeches. This is a base template for a TestSketch that draws an ellipse in the middle of the screen:


public class TestSketch extends AbstractSketch

  public TestSketch(final PApplet parent,
                    final int width,
                    final int height) {
    super(parent, width, height);
  }

  @Override
  public void draw() {
    graphics.beginDraw();
    graphics.background(255);
    graphics.fill(0);
    graphics.ellipse(graphics.width / 2,
                     graphics.height / 2,
                     25, 25);
    graphics.endDraw();
  }

  @Override
  public void keyEvent(KeyEvent event) {

  }

  @Override
  public void mouseEvent(MouseEvent event) {

  }

  @Override
  public void setup() {

  }
}

The constructor must be present and at least have thatsupercall. Notice in thedrawmethod we are usinggraphicsto do the drawing.graphicsis defined in AbstractSketchand is an instance ofPGraphicsthat is unique to this sketch. AbstractSketchalso has aparentvariable that is the parentPApplet class or the main sketch creating this sketch. Use theparentobject when you need to call processing methods. setupis invoked once bySketchMapperwhen the sketch is initialized. ThekeyEventandmouseEvent methods get invoked on key events and mouse events respectively.

Using the SketchMapper object

Construct the SketchMapper object by passing it this from your main sketch.


  SketchMapper sketchMapper = new SketchMapper(this);

You can also construct a SketchMapper object with a default layout to load.


  SketchMapper sketchMapper = new SketchMapper(this, "myLayout.xml");

As of version 4.2.0, SketchMapper will automatically find any classes that extend `AbstractSketch` and add them to the list.

Alternatively, you can add sketches to the `SketchMapper` using the `addSketch()` method.

  sketchMapper.addSketch(new TestSketch(this, 500, 500));

The sketches that are added will show up in the sketch dropdown in the UI.
The only other requirement is that you call the draw method on the object at the top of your draw function.


  public void draw() {
    sketchMapper.draw();
  }

Using the GUI Tool

This section is about how to use the gui tool itself.

Adding surfaces

quad surfaces and bezier surfaces can be added to the sketch by using the buttons
Create a new Quad Surface and Create a new Bezier Surface

Selecting a sketch for a surface

Click on a surface to select it.
Select the desired sketch from the dropdown list of sketches

Setting up your layout

You can move a surface by clicking in the middle of it and dragging it.
You can change the shape of the surface by dragging it's corners.
Alternatively, if you click on a corner to highlight it, you can use the arrow keys to move it more precisely

Removing a surface

Surfaces can be removed by clicking on them to highlight them and pressing the delete key.

Saving layouts

Your surface layout can be saved by clicking on Save Layout.
The sketch will prompt you for a place to save it.
Layouts are saved in XML format and include the layout of the surfaces and which sketches are on which surfaces.

Loading layouts

To load a layout, click on Load Layout and open the layout in the pop-up dialog.

Running the sketch(es)

To run the thing, click on Switch to render mode.

Returning to the configuration mode.

Double click anywhere on the canvas while in render mode to return to calibration mode.

Tested

Platforms: linux, windows
Processing: 2.2.1, 3.0a5, 3.0.1, 3.1, 3.4

Keywords

SketchMapper, projection mapping, geometry, projection