Warping

3D mesh warping is the primary alignment tool for non-planar surfaces — sculpture, architecture, custom rigs. Instead of treating the projection as a flat image and pushing it into shape from the outside, Moonshine lets you grab vertices on the imported 3D model and pull surrounding points along with smooth Gaussian falloff. The Maya/Blender workflow, applied to projection alignment.

If your surface is flat (a wall, a screen, a piece of plywood), use 4-corner keystoning instead — it’s faster and you don’t need a mesh.

Before you start

You need an imported 3D model of the projection surface. Moonshine accepts:

• FBX
• OBJ
• glTF / GLB

Drag the file into the viewport, or use the Scene panel’s import button. The mesh appears at world origin. Use Frame Scene Model to drop the camera into a sensible starting angle.

Vertex selection

Click any vertex on the imported mesh to select it. Selected vertices show as a small highlight handle. Click empty space to deselect.

Multi-select with shift-click adds to the selection. Drag a box across vertices to select all inside the box. Esc clears the selection.

If the mesh is dense and you can’t easily click individual vertices, increase the Soft Selection Radius — even a “single-vertex” drag will then pull a smooth region of surrounding points, which is usually what you want anyway.

Soft selection

The soft-selection falloff is a Gaussian curve, controlled by three parameters in the Warp panel:

Parameter	Effect
Radius	World-space distance over which the falloff applies. Vertices outside this radius are unaffected.
Steepness	Curve shape. Low steepness = wide gentle blob; high steepness = tight punch.
Strength	Multiplier on the drag — drops to a fraction or amplifies, useful for fine work or coarse blocking.

Tune these for the surface you’re aligning. Large smooth surfaces want a big radius and low steepness; small detailed features want a small radius and high steepness.

Dragging

With one or more vertices selected, click-and-drag in the viewport to move them. The viewport’s orbit camera continues to work — middle-mouse-drag orbits, scroll zooms. Only the left-mouse drag is bound to vertex movement.

While dragging, the cursor sticks to the drag plane — by default this is the screen-space plane through the initial click. Hold Shift to constrain to the X, Y, or Z axis (the gizmo guides indicate which is locked).

Refining the mesh

If you need more detail in one area of the mesh than the imported model gave you, use Insert Knot. Click on an edge — Moonshine adds a vertex on that edge, preserving the surrounding surface curvature.

This is surface-preserving: the new vertex starts in exactly the position the original surface had at that point, so inserting a knot doesn’t change the projection. After insertion, you can drag the new vertex to refine the alignment around it.

Be careful with this on dense meshes — every knot adds another vertex to the saved warp data. Insert only where you actually need finer control.

Saving warps per projector

A warp is saved per projector, not per scene. The same imported mesh can have a different warp baked into each projector’s output. This matters for two reasons:

1. Each projector views the surface from a different angle, so the physical alignment is different. You can’t share the same warp across projectors.
2. You can blend two projectors covering the same surface area, each with its own warp, without one warp fighting the other.

Save with Cmd/Ctrl + S or via the Warp panel’s save button. The warp persists into the project file.

When to fall back to keystone

If the surface is flat and you’d be using the warp tool to drag four corners into shape, switch to the keystone tool — that’s literally what it’s for. Keystone is faster, has fewer parameters, and the math is exact for planar surfaces. The two tools coexist: you can keystone first, then add mesh warp on top for surface curvature corrections.

Collaboration

A warp is a locked resource — when you grab a vertex, you implicitly take the lock on that projector’s warp. Other users in the session see your live cursor and that the warp is locked to you. They can request access if they need to take over.

The lock releases automatically when you stop editing for the configured TTL (default 60 seconds) — see Collaboration for the full lock model.

Troubleshooting

Vertices snap back when I drag. Check that the warp isn’t locked by another user. The viewport will show a small lock icon in the corner if you don’t hold the lock.

Soft-selection radius drags vertices on the back side of the mesh. That’s expected — falloff is purely distance-based, not visibility-based. Lower the radius or temporarily hide that part of the mesh.

Insert Knot doesn’t appear in the menu. Make sure you’re hovering an edge of the imported mesh, not an empty area of the viewport. The cursor will change to indicate an edge is targetable.