Skip to content

Projectors

A projector in Moonshine stands in for a real machine in your room — this page covers adding one, and what every setting on it means for the hardware you are aiming.

The closer these numbers are to your actual install, the less correction you need later. A projector with the right position, rotation and throw ratio produces a preview you can trust and a first alignment that is already close.

Adding a projector

Three routes:

  1. Click the projector name in the top bar to open the Projectors view.
  2. Click + Add Projector at the bottom of the list.
  1. Press G to open the scene graph.
  2. Right-click empty space (or the scene node) and choose Add Projector.
  1. Press / to open the command palette.
  2. Choose Add Projector.

New projectors are named Projector 1, Projector 2 and so on, and each gets its own color from a rotating palette of eight — that color is the throw cone, the name label under the projector body, and the dot beside it in every list.

A new projector starts at:

Setting Value
Position 0, 0, 12
Rotation 0, 0, 0
Throw Ratio 1.5
Focus Distance 12
Lens Shift 0, 0
Lumens (ANSI) 3000
Brightness / Contrast / Gamma 1
Resolution Copied from your first projector, or 1920 × 1080 if this is the first

Copying the resolution is deliberate: most installs use identical machines, so the second projector onward arrives already correct.

The projector selector

The top bar carries the name of the selected projector (or Projectors when none is selected). Hover it for a dropdown listing every projector under a Select Projector heading, with its color dot and a check on the current one. Manage Projectors at the bottom opens the full view, as does clicking the name itself.

Press 1 through 9 anywhere in the app to select a projector by position in the list. It is the fastest way to step through machines while you compare their coverage.

The selection follows you everywhere: the Properties panel, the settings form, keystone and warp, and the projector-eye view all act on the projector selected here.

The Projectors view

The view splits into a list of projector cards on the left and two sub-tabs on the right.

Sub-tab Contents
Settings Every parameter for the selected projector — the rest of this page
Outputs Where this projector's render lands on a physical display — see Display outputs

Each card in the list shows the projector's color swatch, its name, its identifier, a connection status of Online, Offline or Error, and an Output pill you can click to enable or disable that projector's output.

To rename a projector, double-click its name on the card, or hover the card and use the pencil button. The trash button beside it deletes the projector after a confirmation.

Note

Connection status and live telemetry come from projectors reachable over the network. See Projector health.

The settings form

Open Projectors → Settings with a projector selected.

Resolution

Width and Height in pixels, minimum 1 each.

Set this to the native resolution of the machine. Two things depend on it:

  • The image's aspect ratio. Moonshine derives the projector's field of view from the throw ratio and the aspect ratio, so a 16:10 projector entered as 16:9 covers the wrong area.
  • The projector-eye view, which letterboxes to exactly this aspect so you see the frame the projector really produces.

Position

X, Y and Z in scene units — where the lens sits in the room. Y is up.

Measure to the lens, not the case, and measure from the same origin you used for your surfaces. A tape measure and five minutes here saves an hour of nudging later.

Rotation

X, Y and Z in degrees — the direction the projector is aimed.

  • Y is pan: swinging the projector left and right.
  • X is tilt: aiming up or down.
  • Z is roll: rotating the image, for a projector mounted on its side or inverted.

Tip

Do not aim by rotation numbers alone. Select the projector, use Frame Scene Model in the Scene panel to point it at your surface, then refine. See Aiming quickly below.

Lens Shift

X and Y, in percent, from -150 to 150.

Lens shift is what a real projector's lens-shift mechanism does: it moves the image up, down, left or right without tilting the projector. That matters because tilting a projector puts the image into keystone — a trapezoid — while shifting the lens keeps it a clean rectangle. A projector hung near a ceiling and shifted down lands an un-keystoned rectangle on the wall below it; the same projector tilted down does not.

Moonshine expresses shift as a percentage of half the image dimension:

Value Meaning
0 The image is centered on the optical axis
+100 The image is shifted by half its own height (or width), putting its edge on the optical axis
+50 Shifted by a quarter of the image dimension

Positive X shifts the image right; positive Y shifts it up.

Note

Manufacturers quote lens shift several different ways — some as a percentage of full image height, some as a percentage of half. Read your projector's spec sheet carefully and convert if needed, rather than typing its number in directly.

Lens shift skews the throw cone drawn in the Scene and skews the projector-eye view by the same amount, so both show the frame the shifted lens would put on the surface.

Warning

Lens shift is a modelling and preview control. It shapes the throw cone and the projector-eye view, but it is not applied to the frame Moonshine renders and sends to the display — position, rotation, resolution and throw ratio are. Use it to describe your rig and read coverage; correct the delivered image with 4-corner keystone or warping.

Throw Ratio

A slider from 0.3 to 5, in steps of 0.01.

Throw ratio is the single most useful number on a projector's spec sheet:

throw ratio = throw distance ÷ image width

A 1.5 throw ratio at 15 m from the wall produces a 10 m wide image. The same lens at 6 m produces 4 m. Lower numbers are short-throw lenses that fill a wide area from close in; higher numbers are long-throw lenses that put a narrow image on a distant surface.

Read it from the lens, not from the projector — a zoom lens covers a range (say 1.2–1.8), and the value you want is where the zoom is actually set. If you have not decided yet, use Frame Scene Model and let Moonshine pick a ratio that fits your surface, then check that the answer is inside your lens's range.

Note

The Throw Ratio field in the Scene tab's Properties panel accepts values up to 8, for long-throw lenses beyond the settings slider's range.

Lumens (ANSI)

A slider from 0 to 30000, in steps of 100, default 3000.

The projector's rated light output, in ANSI lumens, at full brightness and full white. Take it from the spec sheet.

This is the input to Lux display mode, which turns projector positions, angles and distances into an illuminance heatmap on your surfaces. Without a truthful lumen figure that heatmap is decorative; with one, it tells you whether a surface is going to read at the back of the room and where two projectors are doubling up. See View modes.

Tip

If your projector is running an economy or eco lamp mode, enter the rated output for that mode, not the headline number on the box. The gap between them is often 30%.

Brightness, Contrast and Gamma

Three sliders applied to that projector's output image:

Control Range Neutral
Brightness 0 – 1 1
Contrast 0 – 1 1
Gamma 0.1 – 3 1

Their most common use is matching machines. Projectors of the same model with different lamp hours do not put out the same light, and the one with 4000 hours on it needs its neighbors pulled down to meet it rather than being pushed up past its ceiling. Work down from 1, never up — a projector cannot exceed its own output.

Brightness also scales the projector's contribution in Projection and Lux display modes, so the preview follows what you set.

Gamma is the one to reach for when two projectors match on a white field but diverge in the mid-tones — a common symptom of different panel technologies or different picture presets. Values below 1 lift the mid-tones; values above 1 push them down.

Red Gain, Green Gain, Blue Gain

Three sliders from 0 to 2, in steps of 0.01, neutral 1. Each is a direct multiplier on that color channel of the projector's output.

This is white balance. Point two projectors at the same white surface and their whites will rarely match — one leans green, the next leans magenta. Correct the outlier by pulling its dominant channel down rather than pushing the other two up, so you keep headroom.

A workable procedure:

  1. Put a white field on the surface from both projectors — the Solid display mode with a white swatch is a quick source.
  2. Pick the projector whose white you like least and identify which channel dominates.
  3. Reduce that channel's gain in small steps until the two whites read the same.
  4. Re-check the mid-tones with Gamma afterwards; a gain change can shift the apparent mid-tone balance.

The last section of the form takes a Host, Port, Class and Password for projectors that support network control. Leave Host blank for machines you do not control over the network. Details are in Projector health.

The Scene tab's projector panel

Selecting a projector on the Scene tab fills the Properties panel with the settings you most often adjust while looking at the result.

Control What it does
Projection Preview Include or mute this projector in the Projection and Lux previews
Frustum Preview Show or hide this projector's throw-cone wireframe in the viewport
Throw Ratio As above; the field accepts 0.3 to 8
Focus Distance How far out the throw cone is drawn (see below)
Lens Shift X and Y in percent, as above
Position X, Y, Z
Rotation (degrees) X, Y, Z
Frame Scene Model Aims this projector at the active surface and fits it
Projector Settings Jumps to the full settings form

Projection Preview is the toggle to use when you are trying to work out which projector is responsible for a hot spot: mute them one at a time and watch what disappears. It is a view control — muting a projector here does not switch off its output.

Focus Distance

Ranges from 0.5 to 50, default 12.

This controls how far the throw cone is drawn into the scene — the distance at which the outlined rectangle at the end of the cone sits. Together with throw ratio it sets that rectangle's width:

rectangle width = focus distance ÷ throw ratio

Set it to roughly the distance from the projector to the surface and the cone lands on your geometry, which makes it easy to see at a glance whether a projector is aimed correctly and whether its coverage is short.

Note

Focus Distance is a visualization control. It does not change how bright the projection is — pull the cone in or push it out freely while you are aiming.

Aiming quickly

Frame Scene Model does the arithmetic for you. With a projector selected on the Scene tab, click it and Moonshine:

  1. Rotates the projector to point at the center of the active surface.
  2. Sets the focus distance to the actual distance between them.
  3. Picks a throw ratio that fits the surface into the frame with about 10% margin, kept within 0.4 and 8.

It is a starting point, not an answer — check that the throw ratio it lands on is one your real lens can reach, then adjust position and rotation to match where the projector is physically hung.

Note

A Frame Scene Model item also appears on a projector's right-click menu in the scene graph, but that one does something different: it frames the viewport camera on the surface, exactly like Home. Only the button in the Scene tab's Properties panel aims the projector.

Moving a projector in the viewport

Click a projector's body in the viewport while in Object mode. A gizmo attaches, and the throw cone follows in real time as you drag, so you can aim against a live Projection preview.

Key Gizmo
T Translate — move the projector
R Rotate — aim the projector
L Toggle between world and local space
  • Hold Shift while dragging for a tenth of the movement — essential when aiming, where a degree matters.
  • Ctrl+Z (Cmd+Z on macOS) undoes a whole drag; Ctrl+Shift+Z redoes it.
  • Esc detaches the gizmo and deselects.
  • Only position and rotation are stored for a projector. Scaling a projector body has no meaning.

Rotation uses world space by default, which keeps pan on the world vertical and tilt on the world horizontal — the way you would describe aiming a real machine.

The projector-eye view

Press P to look through the selected projector. Press P again, or Esc, to come back.

The viewport becomes exactly what that projector sees:

  • The frame is letterboxed or pillarboxed to the projector's Resolution aspect ratio, with bars filling the rest of the panel.
  • Lens shift skews the view the same way it skews the real lens.
  • The world grid is hidden, since a real projector does not project the editor's grid.
  • Camera controls are disabled — you are locked to the projector's viewpoint.
  • Changing position, rotation, throw ratio, resolution or lens shift updates the view live.

Selecting a different projector while in this view switches you to that projector's viewpoint, which makes stepping through machines with 1–9 a fast way to check every frame.

There is also an eye button on the selected projector's node in the scene graph that enters and leaves the view.

Tip

This is the view to trust when you are asking "does my content actually fit the surface from this machine?" The Scene camera can flatter a bad aim from a helpful angle; the projector's own frame cannot.

Duplicating and deleting

Right-click a projector's body in the viewport for three actions above the usual scene menu:

Item What it does
Projector Settings Opens the settings form for that projector
Duplicate Copies the projector
Delete Removes the projector, after a confirmation

Duplicate copies every setting — resolution, throw ratio, lens shift, lumens, image adjustments, color gains, output assignment — gives the copy a new color and the name <original> copy, and offsets it slightly above the original so the two bodies do not sit inside each other. Keystone and warp corrections are deliberately not copied: the copy starts clean, exactly like a new projector.

That makes duplication the right way to add the second, third and fourth machine of a matched rig. Set one up properly, then duplicate and reposition.

Deleting is also available from the trash button on the projector card and from Delete on the projector's scene-graph node. It is permanent, and it takes that projector's settings with it.

Where to go next