Documentation

Getting Started

What is 4mapper?

4mapper is a browser-based projection mapping tool for visual artists, performers and VJs who want to create striking visuals without wrestling with complex software. Whether you are mapping onto buildings, stage props or art installations, it gives you a direct interface for real-time visual control.

System requirements

• Browser: Chrome, Firefox or Edge, latest versions recommended.
• Computer: a reasonably recent machine with GPU acceleration enabled.
• Projector: any HDMI or DisplayPort projector, 1920×1080 or better recommended.
• Connection: required to sign in and load your projects.

Interface Overview

Main workspace

The interface is split into four main areas.

1. Canvas area (centre)

Your main workspace, where you create and position mapping surfaces. This is where you see your content and arrange the projection layout.

2. Layer panel (left)

Manage surfaces and videos as layers. Drag to reorder, toggle visibility, or lock layers so you do not move them by accident during a show.

3. Properties panel (right)

Fine-tune the selected surface: position, rotation, scale, opacity and blend modes.

4. Toolbar (top)

Quick access to the things you do often: add surfaces, import media, save the project and control playback.

Projection Mapping Basics

Creating your first surface

Surfaces are the foundation of projection mapping: they define the areas your content will be projected onto.

1. Add a surface: click "+" in the layer panel and choose a shape (quad, triangle, circle or polygon).
2. Position it: drag it over the physical area you want to project on.
3. Warp the corners: drag the four corner handles until they match the real object.
4. Add content: drag a video or image file onto the surface.

Warping and alignment

Warping is what makes flat video content look right on a surface that is not flat.

Corner pinning

The most common technique: select a surface and drag its corner handles until the image lines up with the physical object.

Mesh warping

For curved surfaces, enable mesh mode to get control points across the whole area. This is what you need for spheres, cylinders and irregular shapes, where four corners are not enough.

Masking

Masks hide parts of your projection: useful for working around windows, doors or anything that should stay dark.

• Add a mask: select a surface and click "Add Mask" in the properties panel.
• Draw the shape: click to place points around the area you want to exclude.
• Invert: inverting projects only inside the masked area instead of outside it.

Live Performance

Before the show

Almost every problem during a show comes from a check that was skipped beforehand.

Pre-show checklist

• Projectors: powered, connected and working.
• Alignment: re-check surface warping before doors open.
• Content: load every video file and play each one at least once.
• Backup plan: keep spare content and an alternative scene ready.
• Save: save several versions of the project.

Dual monitor setup

Professional setups use two outputs: one for control, one for projection.

1. Connect the projector as a second display in your operating system.
2. Open 4mapper on the primary monitor for the controls.
3. Enable full-screen output mode.
4. The output window appears full screen on the projector.
5. You keep controlling everything from the primary display.

Adjusting during the show

You can make changes while the projection is running.

• Opacity: fade layers in and out smoothly.
• Position and scale: move and resize surfaces on the fly.
• Visibility: show or hide individual elements instantly.

Tips and Good Habits

Performance

• Video format: use MP4 with H.264. Avoid heavy codecs like ProRes.
• Resolution: match your projector's native resolution, usually 1920×1080.
• File size: keeping clips under 10MB keeps playback smooth.
• GPU acceleration: check it is enabled in your browser settings.
• Memory: 8GB minimum, 16GB if the project is complex.

Preparing content

• High contrast: bold colours and strong contrast read far better when projected.
• Test grids: always project one before loading the final content.
• Feathered edges: softening edges makes blends far less visible.
• Safe zones: keep important elements away from surface edges.
• Frame rate: 30fps is almost always enough and saves file size.

Mistakes that cost you

• Wrong aspect ratio: if source and surface ratios do not match, content gets distorted.
• Underpowered projector: most venues need at least 2000 ANSI lumens.
• Too many layers: beyond 5-10 active layers, performance starts to suffer.
• Ambient light: light surfaces and controlled lighting change the result more than any setting.
• No backup: always keep content and project files saved elsewhere.

Positioning the projector

• Throw distance: calculate it from your lens and surface size.
• Keystone correction: use as little as possible — move the projector instead.
• Focus: check it with a fine grid, not with a general image.
• Colour: calibrate before loading the final content.

Troubleshooting

Video playback

Video stutters

• Lower the resolution or bitrate of the file.
• Close other browser tabs and applications.
• Check GPU usage — it should stay under 80%.
• Make sure hardware acceleration is enabled in the browser.
• Re-encode the video as MP4 H.264.

Video will not load

• Check the format — MP4 H.264 is the recommended one.
• Open the file in a media player to rule out corruption.
• Re-encode it with HandBrake or a similar tool.
• Check the browser console: the error is often written there.

Projection problems

Mapping no longer lines up

• Project a test grid to see where it has drifted.
• Check the projector has not moved or is not vibrating.
• If it is badly off, redo the corners from scratch.
• Verify zoom and focus have not changed.
• Make sure the projected object has not been moved.

Colours look wrong

• Calibrate the projector colour settings.
• Look at the surface colour — white or light grey gives the best result.
• Disable auto-brightness on the projector.
• Test with a reference image you know well.

Browser performance

Interface feels slow

• Close tabs you are not using.
• Temporarily disable browser extensions.
• Clear the cache and reload the page.
• Update the browser to the latest version.
• Try Chrome, which is what we test against most.

Project will not save

• Check your internet connection.
• Verify you are still signed in.
• Check you have not run out of storage on your plan.
• If it persists, get in touch.