Skip to content

Surfaces and models

A surface is the geometry your projectors light up — this page covers creating one, bringing in a 3D model, and placing it exactly where the real object stands.

Moonshine calls each piece of geometry a mesh. A scene can hold several. One of them is the active surface — the one the Properties panel edits, the one F frames when nothing is selected, and the one warping applies to.

Adding a surface

Three routes. The first two give you a built-in shape or an empty placeholder; the third builds the surface from a model you have already uploaded.

  1. Press G to open the scene graph if it is closed.
  2. Right-click empty space in the graph.
  3. Open Add Mesh and choose Plane, Box or Empty.
  1. Press / to open the command palette.
  2. Type mesh and pick Add Mesh: Plane, Add Mesh: Box or Add Mesh: Empty.
  1. Upload the model on the Assets tab.
  2. Open the scene graph and drag the mesh asset from the Assets tab onto it.

The new surface is named after the asset.

New surfaces are called Mesh 1, Mesh 2 and so on unless they came from an asset. Rename one by right-clicking its node in the scene graph and choosing Rename.

Empty creates a surface with no geometry yet — a placeholder you can point at a built-in shape later with Change Source.

Built-in shapes

Two primitives ship with Moonshine. Both arrive pre-subdivided, so you can sculpt them in Warp mode without adding geometry first, and both carry a faint dark line overlay: a regular grid across the plane's face, and the twelve edges of the box.

Plane

A flat rectangle standing upright, facing you. The workhorse for screens, walls, banners and flats.

Field Default Notes
Width 8 Minimum 0.1
Height 4.5 Minimum 0.1

The default 8 × 4.5 is 16:9, which matches most projectors and most content, so a fresh plane already has the right shape for a video wall.

Box

A rectangular solid. Use it for pillars, plinths, stacked cubes, and as a stand-in for any blocky object while you rough out a design.

Field Default Notes
Width 4 Minimum 0.1
Height 4 Minimum 0.1
Depth 4 Minimum 0.1

Size fields appear under the Size heading in the Properties panel whenever the selected surface is a built-in shape.

Tip

The surface's Size, Position, Rotation, Scale and Pivot Offset fields all scrub with the scroll wheel while the pointer is over them. Plain scroll moves one step, Ctrl or Cmd + scroll moves ten steps, and Alt + scroll moves a tenth of a step. It beats selecting text and retyping when you are dialing a value in against the projection.

Changing an existing surface's shape

Right-click a surface's node in the scene graph and open Change Source:

Choice Result
None Removes the geometry, leaving an empty placeholder
Plane Replaces the geometry with a default plane
Box Replaces the geometry with a default box

Warning

Changing the source rebuilds the geometry from scratch, and sculpting done on the old shape does not carry across to a different one. The transform — position, rotation, scale and pivot — stays.

Importing a 3D model

Moonshine reads four model formats:

Format Extension
Wavefront OBJ .obj
glTF .gltf
glTF binary .glb
FBX .fbx

Upload the file on the Assets tab first — see Uploading media — then drag it from the asset list onto the scene graph. Moonshine creates a surface for it, names it after the asset, and selects it.

A model may arrive as several parts. Moonshine treats the whole file as one surface with one transform, so every part moves, rotates and scales together.

Tip

Export your model with real-world dimensions and a sensible origin. A model authored in millimeters lands 1000× too large in a scene measured in meters, and a model whose origin sits far from the geometry is awkward to rotate. Both are fixable here with Scale and Pivot Offset, but fixing them at export is cleaner and survives a re-import.

Large models take a moment to load. The viewport shows Loading mesh... while it works.

Placing a surface

Select the surface — click it in the viewport in Object mode, or click its node in the scene graph — and the Properties panel fills with its transform under the surface's name.

Group Fields Step
Position X, Y, Z 0.1
Rotation (degrees) X, Y, Z 1
Scale X, Y, Z, plus Uniform 0.1, minimum 0.01
Pivot Offset X, Y, Z 0.1

Position

Where the surface sits in the world, in scene units. Y is up.

Measure the real object once and type the numbers in. A surface placed by measurement and a projector placed by measurement will line up on the first try far more often than two objects placed by eye.

Rotation

Yaw, pitch and roll in degrees, one field per axis.

For a surface standing against a wall, rotation Y alone is usually all you need — it swings the surface around the vertical axis to face into the room.

Scale

Three independent axis scales plus a Uniform control that drives all three together. Uniform is both a typed field and a slider, and the slider covers 0.01 to 5.

Uniform is what you want for the common case of "this model came in at the wrong size." Reach for the individual X/Y/Z fields only when you deliberately want to stretch geometry — a plane scaled non-uniformly is fine, a scanned object usually is not.

The Uniform value shown is the average of the three axes, so if you have set X, Y and Z separately it reads as their mean until you touch it.

Pivot Offset

Moves the point the surface rotates and scales around, relative to the geometry's own origin.

This is the fix for an imported model whose origin sits in an odd place. If a pillar model has its origin at the world center rather than at the base of the pillar, rotating it swings it through a wide arc instead of spinning it in place. Offsetting the pivot puts the center of rotation back where it belongs.

Reset Transform

The button at the bottom of the panel returns position to 0,0,0, rotation to 0,0,0, scale to 1,1,1 and pivot to 0,0,0 in one step. The same action is on the surface's scene-graph right-click menu as Reset Transform.

The transform gizmos

Click a surface in the viewport while in Object mode and a gizmo attaches to it. Drag an arrow, ring or handle to transform directly in the view.

Key Gizmo
T Translate — three arrows, one per axis
R Rotate — three rings
S Scale — three handles
L Toggle between world and local space
  • World vs local space. In world space the arrows always point along the world axes, so dragging the X arrow moves the surface along world X no matter how the surface is turned. In local space the arrows follow the surface's own rotation. World is the default and is the predictable choice while you are placing things against a room; local is what you want once a surface is already angled and you need to slide it along its own face.
  • Hold Shift for fine control. Translate and rotate drop to a tenth of your pointer movement while Shift is down, which is the difference between "roughly there" and "on it."
  • Scale is deliberately slow. The scale gizmo already moves at a fraction of your drag so a small hand movement does not blow the surface up; Shift makes it ten times finer again.
  • Undo works on the whole drag. Press Ctrl+Z (Cmd+Z on macOS) to undo a completed move, rotate or scale, and Ctrl+Shift+Z to redo. One drag is one undo step, not hundreds.
  • Press Esc to detach the gizmo and deselect.

The viewport values and the Properties fields are the same numbers. Drag roughly with the gizmo, then read the panel and round the values off — a surface at x = 2.0 is easier to reason about later than one at x = 1.9873.

Tip

Switch the display mode to Projection while you place a surface. You are then dragging against a live picture of where the light actually falls, instead of guessing and checking. See View modes.

Visibility, renaming and removal

These all live on the surface's node in the scene graph rather than in the Properties panel:

Action How
Show / hide Click the eye button on the mesh node
Rename Right-click the node → Rename
Remove Right-click the node → Remove Mesh

Hiding a surface takes it out of the viewport without deleting it or losing its settings — useful when two surfaces overlap and you need to work on the one behind.

Warning

Remove Mesh is permanent. It also discards that surface's selection sets and its saved warp, since both are stored against the surface.

Putting media on a surface

Geometry alone renders grey. Wiring an image, a video or a playlist to a surface is covered in Putting media on a surface.

Where to go next