Surfaces and models

A surface is the geometry your projectors light. This page covers adding surfaces, importing 3D models, placing them where the real objects stand, and setting how media lies on them.

Each piece of geometry is a mesh, and a scene can hold several. The active surface is the one the Properties panel edits, the one F frames when nothing is selected, and the one warping applies to.

Adding a surface

Add one of the built-in shapes, or a surface from a 3D model: a file on your computer (OBJ, FBX, glTF or GLB) or a model already in Assets.

SceneScene graphCommand paletteA model from Assets

1. Click + Add at the left of the Scene toolbar, or right-click empty space in the viewport and open Add.
2. Choose a shape (Plane, Box, Pyramid, Cylinder, Cone, Sphere, Dome, Curved screen or Disc), 3D file…, or a model under From Assets. From the right-click menu, the surface lands where you clicked.

See Adding projectors and surfaces.

1. Press G to open the scene graph if it's closed.
2. Right-click empty space in the graph, or the Scene node.
3. Open Add and choose as in the Scene.

1. Press / to open the command palette.
2. Type surface and pick a shape (Add Surface: Plane, Add Surface: Sphere and so on), Add Surface: 3D File… or Add Surface: Empty (choose its shape later).

1. Upload the model on the Assets tab.
2. Open Add (the Scene's +, or Add ▸ on a right-click in the Scene or on empty space in the scene graph) and pick the model under From Assets.

Dropping the model onto the scene graph only moves the model's own node in the Assets column. It doesn't create a surface.

3D file… uploads the file to Assets first, so you can reuse it. The surface appears when the upload finishes.

New surfaces are named after their shape (Plane 1, Plane 2, Box 1, Curved screen 1) or their model (Stage, then Stage 2). Each one is offset so it doesn't sit exactly on another, and is selected. To rename a surface, right-click its node in the scene graph and choose Rename. Undo removes one added surface at a time.

Add Surface: Empty, in the command palette only, creates a placeholder with no geometry. Give it a shape later with Change Source.

Built-in shapes

Moonshine has nine built-in shapes, each already divided into segments so you can sculpt it in Warp mode right away. Sizes are in meters. Each shape is centered on its origin, except the dome, which stands on its rim.

Shape	Use it for	Size (default)	Density (default)	How a picture lies on it
Plane	Screens, walls, banners, flats	Width 8, Height 4.5	Across 32, Up 18	Flat across its face. 8 × 4.5 is 16:9, the shape of most projectors and content
Box	Pillars, plinths, stacked cubes	Width, Height, Depth 4	Per side 16	The whole picture on each face
Pyramid	Set pieces, roofs	Width 4, Depth 4, Height 3	Per side 8	A triangle of the picture on each side, apex at top center; the base as the box's bottom
Cylinder	Columns, drums, tanks	Radius 1.5, Height 4	Around 48, Up 8	Wrapped once around the side, from the back round to the back; a round picture on each cap
Cone	Spires, lamp shades	Radius 1.5, Height 4	Around 48, Up 8	As on the cylinder, with the picture's top at the tip
Sphere	Globes, balls	Radius 2	Around 48, Up 24	Equirectangular: a 2:1 360° picture, like a map of the Earth
Dome	Planetariums, domes	Radius 5	Around 64, Up 16	A 180° fisheye (the domemaster format of fulldome content): the zenith at the center, the rim at the circle's edge, and the front (the side facing you when added) at the bottom
Curved screen	Cycloramas, panoramic screens	Radius 8, Angle 90°, Height 4.5	Across 64, Up 18	Left to right along the arc, facing inward, so the screen curves toward you
Disc	Round screens, floor circles, tables	Radius 2	Around 64	Flat: a round picture facing you

With a built-in surface selected, the Properties panel shows its Size and Density fields. Density is the number of segments, and so the number of points a warp moves: more gives a finer warp, fewer is lighter to work with. A plane goes up to 256 × 256, a box to 64 per side and a sphere to 256 around. A plane whose Up you never set keeps square segments as you resize it.

Density is held while the surface has a warp or point selections

A warp stores the position of every point, and a selection set stores the points it picked, so both need the point count to stay the same. While a surface has a warp or a baked warp that moves any point (anyone's), or a selection set, its Density fields are read-only. The note under them says what to do: Reset Warp for a warp or Revert to Source for a baked warp (both in Warp mode), or delete the selection sets. Nothing is cleared for you. A reset warp, baked or not, no longer holds them. Resizing a surface you've worked on keeps its points and its warp.

In the Scene, the plane shows a faint grid across its face and the box shows its twelve edges. To see any shape's segments, use the Mesh view mode.

Tip

Size, Density, Position, Rotation, Scale and Pivot Offset all support the value ladder: hold the middle mouse button on a field, move up or down to pick the step size, then left or right to change the value. It's the quickest way to dial a value in against the projection. The scroll wheel scrolls the panel and leaves fields alone.

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
A shape (Plane, Box, Pyramid … Disc)	Replaces the geometry with that shape at its default size

Warning

Changing the source rebuilds the geometry from scratch, so sculpting on the old shape doesn't carry over. The transform (position, rotation, scale and pivot) stays.

Importing a 3D model

Moonshine reads four model formats:

Format	Extension
Wavefront OBJ	.obj
glTF	.gltf uploads, but appears in the scene as a placeholder box; see File formats
glTF binary	.glb
FBX	.fbx

Upload the file on the Assets tab (see Uploading media), then add it from From Assets in any Add menu. 3D file… in the same menu does both at once: see Adding a surface. Projectors draw FBX, OBJ and GLB models; a .gltf stays a placeholder.

A model with several parts becomes one surface with one transform. The parts move, rotate and scale together, you can click and sculpt any part in 3D surface warping, and F and Home frame the whole model.

To leave out a part that isn't in your venue, select the surface and click the part's eye under Parts in the Properties panel. The part disappears from the viewport and no projector lights it. Click the eye again to bring it back. An FBX's or GLB's parts are its meshes; an OBJ's are its objects.

Tip

Export models at real-world size, with the origin close to the geometry. A model built in millimeters arrives 1000× too large in a scene measured in meters, and a distant origin makes rotating awkward. Scale and Pivot Offset fix both here, but fixing them at export also survives a re-import.

While a large model loads, the viewport shows Loading mesh....

Placing a surface

Select the surface, in the scene graph or by clicking it in the viewport in Object mode, to show its transform in the Properties panel. Select several to edit them together: see Several at once.

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

A typed value applies when you press Enter or leave the field; Escape cancels it. A value below a field's minimum is raised to it: 0 in Scale becomes 0.01.

Position

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

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

Rotation

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

For a surface against a wall, rotation Y is usually all you need: it turns the surface around the vertical axis to face into the room.

Scale

X, Y and Z scale, plus Uniform, which sets all three at once. Uniform is both a field and a slider, covering 0.01 to 5.

Use Uniform when a model came in at the wrong size, and the separate axes only when you mean to stretch the geometry: that's fine for a plane, but rarely right for a scanned object. Uniform shows the average of the three axes, so after you set them separately it shows their mean.

Pivot Offset

Moves the point the surface rotates and scales around, relative to the geometry's own origin. The surface doesn't move: its Position is the pivot's position, so Position changes with the offset. The pivot tool (L) moves the same point by dragging: see Pivots.

Use it when a model's origin is in the wrong place. A pillar whose origin sits at the world center swings through a wide arc when you rotate it. Offset the pivot to the pillar's base and it turns in place.

Reset Transform

The button at the bottom of the panel resets position, rotation and pivot to 0,0,0 and scale to 1,1,1 in one step. It's also on the surface's right-click menu in the scene graph.

The transform gizmos

In Object mode, click a surface in the viewport to attach a gizmo, then drag an arrow, ring or handle to transform it.

Key	Gizmo
M	Move: three arrows, one per axis
R	Rotate: three rings
S	Scale: three handles
L	Pivot: moves the point the surface turns and scales about, not the surface
O	Switch between World and Local

• World and Local. In World, the default, the arrows follow the world axes however the surface is turned, which is predictable while you place things in a room. In Local they follow the surface's own rotation, so you can slide an angled surface along its own face. Switch with O or the globe button beside the tools. With several surfaces selected, it also sets whether they turn and scale as one group or each in place: see Several at once.
• Hold Shift for fine control. Move and rotate drop to a tenth of your pointer movement.
• Scale is slow to start with, so a small movement doesn't blow the surface up. Shift makes it ten times finer.
• One drag is one undo step. Ctrl+Z (Cmd+Z on macOS) undoes it and Ctrl+Shift+Z redoes it.
• Esc deselects, and the gizmo goes with the selection.

Drag roughly with the gizmo, then round the values off in the Properties panel, which shows the same numbers. A surface at x = 2.0 is easier to work with later than one at x = 1.9873.

Tip

Use the Beams view mode while you place a surface, so you can see where the light falls as you drag. See View modes.

Visibility, renaming and removal

Show, hide, rename, duplicate and delete a surface from its node in the scene graph:

Action	How
Show / hide	Click the eye button on the mesh node
Rename	Right-click the node and choose Rename
Duplicate	Hold Alt (Option on a Mac) and drag its gizmo to place the copy, press Ctrl+D, or right-click it and choose Duplicate. See Duplicating
Delete	Select it and press Del, or right-click it (here or in the viewport) and choose Delete

A hidden surface leaves the viewport, no projector lights it and Moonblend ignores it, but it keeps its settings. Hide a surface to work on one behind it.

Warning

Deleting a surface doesn't ask first. Ctrl+Z brings the surface back, but not its selection sets or its saved warp. See Deleting.

A Material's mapping

A Material's Mapping sets how its picture lies on the surface. Select the Material under the surface in the scene graph (the first one is called Main) to see its mapping in the Properties panel. The node's second line shows it too, before the media: UV · Test movie.

Mapping	The picture	Placed by
UV	The whole picture across the whole surface, by the surface's own UV coordinates, on every projector	The surface: a built-in shape's coordinates, or a model's as it was built
Projector view	One projector's own, across its whole picture on what it lights, blend zone included. No other projector shows it	Moonshine, again whenever the projector or the surface moves
Manual	Wherever you put it on the surface. Past its edge, its Extend	You: the Map tool, Fit to, or its numbers

A new Material starts as UV, and each change is one undo step. The projectors use the same mapping, as do the UV, Beams and PJ View modes in the Scene, the Warp tab and the Preview card. On a phone, the mapping is read-only.

Any Material can also show only part of its picture: see Cropping the picture.

UV

Each point of the surface shows the picture at its UV coordinates, from 0 to 1 across and up. A plane is filled edge to edge, and a model shows the picture as it was built. To show part of the picture, crop it. To put the picture on part of the surface, use Manual.

Projector view

Choose Projector view, then pick the projector under Projector. Only that projector shows the Material, across its whole picture, blend zone included. Where two projectors overlap, each shows its own view and the blend fades between them. The edge is worked out per pixel, so it ends exactly at the edge of the projector's picture, however few points the surface has.

Moonshine fits the picture to what the projector lights on the surface (the bounding box of that area, in the surface's UV). It refits whenever you move the projector, change its lens, or move or warp the surface. You don't place it by hand: dragging it with the Map tool makes the Material Manual, starting from where the picture was.

In the Scene, UV mode shows each view where its projector lights, with the later Material on top where two overlap. Use PJ View to see one projector's picture, or Beams to see the overlap as the room will, each projector's media in its own light.

The first Material can be a projector view too. Then every other projector shows the surface black, except where a later Material covers it.

Manual

Choose Manual and the picture stays where it was, for you to place. Drag it with the Map tool, or use Fit to to fit it to the bounding box of an area in the surface's UV: Whole surface, a projector's view, a selection set, or one of the model's own materials. The picture isn't confined to that area; it can sit anywhere on the surface and past it.

Frame numbers shows the same placement as numbers:

Field	Default	What it does
Offset X, Offset Y	0	Slides the picture across the surface, in picture widths (X) or heights (Y). A positive offset moves the picture left (X) or down (Y).
Scale X, Scale Y	1	How much of the picture fits across the surface: 0.5 shows half of it at twice the size, and 2 shows all of it in half the surface. Scaling works from the surface's bottom-left corner.

Each point of the surface shows the picture at its UV × scale + offset. Reset UV resets all four fields. Type a value, or middle-drag a field to use the value ladder.

To show one part of the canvas on a surface, crop to that part. For example, two planes side by side, each showing half the canvas, are each cropped to their half, in pixels.

Extend

Extend sets what a Manual Material shows past the edge of its picture, or of its crop when it has one:

Extend	Past the picture
Hold	Its edge pixels continue outward on every side
Repeat	The picture again, side by side
Black	Black
Transparent	The Materials under it, or black where there are none

A Material you make Manual for the first time starts at Transparent, so its picture sits over what's under it. The first Material has nothing under it, and a Material limited to a selection set or a model material has those faces to itself, so for them Transparent shows black. UV and Projector view Materials always hold their edge pixels.

Several materials on one surface

A surface can carry up to eight Materials, each with its own media and mapping. Use them to show different media on different parts of a surface, or one picture over another.

1. Choose Add Material: right-click the surface, one of its selection sets or empty space in the scene graph, use the Material tile in the Scene's + Add grid, or press / and type material. Moonshine adds a UV Material across the whole surface, after its other Materials, and selects it. From a selection set, the new Material is limited to that set. From empty space, the grid or the palette, Moonshine asks which surface when there are several.
2. Link media into the new Material 2 node as into any Material: drop an asset or a cuelist on it, wire one to it, or use its right-click menu.
3. In its Properties, set its Mapping and, to keep it to part of the surface, its Limit to.

How Materials combine:

• A later Material is drawn over the ones before it. A UV Material covers everything below it. A Manual one covers what's below inside its picture, and past it as its Extend says.
• Limit to keeps a Material other than the first to a selection set, or to one of the model's own materials: the ones an imported FBX, OBJ or GLB model was made with, such as a car's glass and its body. It appears once the surface has a selection set or a model with two or more materials, and starts at Whole surface. The Material takes those faces over from the ones before it, on every projector.
• A Projector view Material shows only on its projector, over the Materials before it, across that projector's whole picture. It has no Limit to: the projector's picture is its edge.
• The first Material, Main, lies under all the others across the whole surface. Its node carries a small lock, and it can't be removed.
• Remove Material, on a later Material's right-click menu, removes it and uncovers what was under it. Each change is one undo step.
• A Material whose selection set, model material or projector no longer exists covers nothing. It stays, and its panel says what's missing.

Which faces a limit covers. A model material covers exactly the faces (the surface's triangles) the model gives that material. A selection set covers every face whose three corners are all in the set, counting its points and the area each point's Radius reaches. So a face with one corner outside the set stays with the Material before. Limit to lists each set by name, the projector it was made for when the name is different, and its point count: Projector A · 15 points, Rim · Projector B · 40 points.

A selection set of what a projector lights. Add Selection Set makes a set of every point a projector lights on the surface, including the points along the edge of its picture. It's on the surface's right-click menu in the scene graph (which asks which projector when there are several), the projector's right-click menu, the Selection Set tile of the + Add grid and the / palette. The set is named after the projector (Projector A, then Projector A 2 for a second one on the same surface) and follows the projector's name when you rename it. Rename the set from its node's right-click menu, or with Rename in Point Select. Its edge follows the surface's triangles, so it can fall up to one face short of the picture's edge; more points make that step smaller but never remove it. For an edge that matches the picture exactly, use a Projector view Material. The set doesn't move with the projector; change it in Point Select to add or remove points.

From a selection set to a Material. Right-click the set's node in the scene graph:

• Add Material adds a Material limited to the set and selects it, ready for media.
• Use for ▸ Material 2 (or a later Material, listed by name) limits an existing Material to the set instead. It appears once the surface has a second Material.

Wires. A Projector view Material has a dashed wire from its projector's node, and a Material limited to a selection set has one from the set's node, in that node's color. Drag a wire from a projector's node to any of a surface's Materials to make it that projector's view. Drag one from a set's node to Material 2 or later to limit it to the set. Each is one undo step.

What counts as lit

A point counts as lit when it's inside the projector's picture or on its edge, in front of the lens, and on the side of its face that's turned toward the lens, so the far side of a box or a sphere is left out. A surface the projector sees only from behind, such as a dome from inside or a rear-projection screen, is lit on that side. Obstructions aren't checked: a surface hidden behind another still counts as lit if it faces the projector. A set made before the surface has loaded in the Scene starts empty.

Naming a Material. Materials are called Main, Material 2 and so on until you name them. Right-click the node and choose Rename, or type in Name at the top of its Properties, then press Enter or click away. The name shows on its node, in Use for on a selection set's node, and on its wire. Clear it to go back to the default. Names can be up to 64 characters, each rename is one undo step, and names don't change the output.

What a further Material plays. A still, a movie or a live source linked into a Material other than the first plays there on its own, on every projector, whatever the cuelist is doing. In the Scene, a movie or a live source shows as its thumbnail. A Material linked to a cuelist, or to nothing, shows what the outputs show, as the first Material does. There's one show at a time, so a cuelist linked into any Material plays on every surface that shows the show.

A project saved before October 20, 2026

It opens looking as it did. A Material on a projector's view becomes Projector view, refitted to the projector even if the Map tool had moved it. A Material whose picture had been moved or scaled (as one on a selection set or a model material was from the start) becomes Manual and still holds its edges. Every other Material becomes UV. A Material on a selection set or a model material keeps it as its Limit to.

The Map tool

To place a picture by eye, select its Material's node in the scene graph and turn on the Map tool: the mode button after Warp in the Scene toolbar, or U.

Selecting a Material in the scene graph turns the tool on, whether you click the node, Ctrl- or Shift-click it, or add it with Add Material. Deselecting brings back the tool you had before. A tool you choose yourself while the Material is selected, such as V, stays. The button is grayed out until a Material is selected. Phones don't have the Map tool.

The button and U cycle from off to Resize, then Crop, then off again, back to your previous tool; it always starts in Resize. Each mode has its own icon and color on the button and the border, Resize white and Crop amber, and the line above the canvas names it.

In Resize, a white border with square handles shows where the picture lies, following the surface even on a curved screen or a dome. Drag:

Drag	What it does
A corner	Scales the picture in proportion, about the opposite corner
A corner, with Shift held	Scales it freely: the corner follows the pointer
A side	Stretches it one way
Inside the border	Moves it

• The first drag makes a UV or Projector view Material Manual, starting from where its picture was. One Ctrl+Z undoes the drag and the change of mapping together.
• The picture can go anywhere on the surface, and past it. Beyond the surface, the border continues more faintly on a flat extension of the surface, and its handles still work there.
• Each drag is one undo step. Frame numbers update as you drag, and the projectors receive the change like any other edit.
• With the snap magnet on, a side dragged near the edge of the whole surface, a projector's view, a selection set or a model material snaps to it.
• A click off the border is ignored. Clicking a projector selects it and switches back to the Object tool, as selecting anything other than a Material does.
• While someone else holds the surface, a drag shows a notice instead.

Fit to, in a Manual Material's Properties, fits the picture to an area again in one undo step: after a stray drag, or to start from a projector's view or a selection set. Rotating the picture isn't possible yet.

Cropping the picture

A Material's crop is the part of its picture it shows. Use it to take a strip of a wide picture for one surface, or to give two surfaces side by side half each, in pixels, the way an LED processor or a pixel map counts them. Past the crop's edge, the Material's Extend applies: Hold continues the crop's edge pixels and Repeat repeats the crop.

In the Map tool's Crop mode, the amber border is a window onto the picture, with the whole picture outlined faintly around it, past the surface too. Drag:

Drag	What it does
A corner	Crops two sides, in proportion; with Shift held, freely
A side	Crops that side
Inside the border	Slides the picture under the window, which stays where it is

The picture stays put on the surface while you crop; only what's outside the window goes. A crop lands on whole pixels and can't go past the picture's edge. Each drag is one undo step, Crop picture or Slide picture, and like a Resize drag it makes a UV or Projector view Material Manual in the same step.

Crop, in the Material's Properties, shows the same crop as X, Y, W and H, in the picture's pixels from its top-left corner, whatever the mapping. It reads Whole picture until you crop, then for example 1920 × 1080 at 960, 0. Typing a number changes the crop but leaves the frame where it is, so the part you keep stretches to fill it: on a UV Material, the whole surface. Reset crop shows the whole picture again. Each change is one undo step. On a phone, the crop is read-only.

The pixels are those of the picture being cropped:

• a still's or a movie's own;
• a live source's, once it has reported its size (until then, the crop reads 0 to 1);
• for the show's picture (the first Material's, and a Material linked to a cuelist, a component or nothing), the project's canvas.

Every show machine and app together

A show machine running a version from before Crop refuses any change to a surface that has a crop. Update the show machines, their followers and the apps together, as for any new surface setting.

Several pictures at once

To line pictures up with each other, select several Materials: Ctrl-click (Cmd-click on macOS) or Shift-click their nodes in the scene graph, on one surface or several. With the Map tool on, each picture gets a border in its own color, the first one selected in the mode's color (white or amber). In Crop mode, every border's handles are amber.

• A press takes the border nearest the pointer. Any border's corner or side under the pointer comes before the inside of a border; with no handle there, you get the inside of the nearest one. The drag moves or scales that picture alone, as one undo step.
• With the snap magnet on, a border's sides snap to the areas Fit to offers and to the other selected borders on the same surface, which share its UV. The snap mark the gizmos use shows where a side lands. Borders on other surfaces have a different UV, so they don't attract it.
• A border on a surface someone else holds is drawn, but a drag on it only shows the same notice.

The Properties panel then lists the selected Materials with their surfaces; click one to select it alone. Fit to area there fits each picture to the part of the surface its Material is limited to (the whole surface without a Limit to) and makes it Manual, in one undo step. It leaves Projector view Materials alone, since they already fit their projector, and skips surfaces someone else holds.

Putting media on a surface

Without media, a surface renders gray. To link an image, a video or a cuelist to a surface, see Putting media on a surface.

Where to go next

• Projectors: aim light at what you just built
• The scene graph: the full tree and its context menus
• 3D surface warping: sculpt the surface to match the real object