StageMask Help & Troubleshooting

StageMask lets you paint grayscale masks for stage projection. Black areas are fully hidden, white areas are fully visible, and gray areas partially dim the projection.

Getting Started

  1. Open StageMask. A new untitled mask document appears automatically.
  2. Set Stage Size to match your projection output.
  3. Choose Mask, Dim, or Reveal.
  4. Paint directly on the canvas.
  5. Optional: add a Vignette for smooth edge falloff.
  6. Save the editable .mask file, or export a grayscale PNG for projection software.

Tools

  • Mask: Paints black to fully hide projected content.
  • Dim: Paints gray to partially reduce brightness. Use the Dim slider to set the level.
  • Reveal: Paints white to restore visibility.
  • Soft Brush: Feathers brush edges for smoother transitions.
  • Grid: Shows or hides the alignment grid.

Stage Size

Set width and height to match the pixel resolution of your projector, media server, or output display. Use the preset buttons for common sizes such as HD, WUXGA, UHD, and 2xHD. On macOS, choose a connected display and click Use Display Size to match it automatically.

Base Level

Base sets the starting brightness before any strokes are painted: Visible starts white, 50% starts gray, and Masked starts black.

Vignette

Use Add Vignette to apply a smooth darkening effect from the center toward the edges of the mask. This is useful for softening projection edges, reducing spill, or blending into scenic borders.

  • Strength: Higher values make the edges darker.
  • Feather: Higher values make the fade wider and more gradual.
  • Edit Vignette: Reopen the vignette controls and adjust the effect.
  • Remove Vignette: Deletes the vignette without removing painted strokes.

Reference Images

Use Import Reference Image or drag an image onto the canvas to show a semi-transparent overlay. Reference images help with alignment but are not included in exported PNG masks.

Saving and Exporting

  • Save: Saves an editable .mask project file.
  • Open: Opens a saved .mask file.
  • Export PNG: Exports the final grayscale mask, including strokes, base level, and vignette.

Full Screen Editor

The Full Screen Editor opens the mask editor on the selected display so you can paint directly over the projection output. Use the floating controls to change tools, brush size, soft brush, and grid visibility. Press Escape or click Close to leave the editor.

Navigation

  • Pinch to zoom the canvas.
  • Hold Option and drag to pan.
  • Click the zoom percentage button, or use Command + 0, to return to actual size.

Keyboard Shortcuts

ActionShortcut
New documentCommand + N
Open documentCommand + O
Save documentCommand + S
Export mask PNGShift + Command + E
Undo / RedoCommand + Z / Shift + Command + Z
Mask, Dim, Reveal toolsM, D, R
Brush smaller / larger[ / ]
Zoom in / out / actual sizeCommand + +, Command + -, Command + 0
HelpCommand + ?

Troubleshooting

The exported PNG does not line up with my projection
  • Confirm Stage Size matches the exact pixel resolution of your output.
  • Use Use Display Size for a connected display when possible.
  • Check that your projection software is not stretching, cropping, or scaling the PNG.
The mask looks inverted

Use Invert Mask to flip brightness values. Masked areas become visible and visible areas become masked.

The vignette is too dark or too wide
  • Choose Edit Vignette.
  • Lower Strength if the edges are too dark.
  • Lower Feather if the fade spreads too far toward the center.
  • Use Remove Vignette to delete the effect completely.
I cannot paint on the canvas
  • Make sure the pointer is inside the canvas boundary.
  • Check the selected tool.
  • If you are holding Option, StageMask pans instead of painting.
Export fails or the mask could not be rendered
  • Try reducing Stage Size and exporting again.
  • Very large canvases can require significant memory, especially with soft strokes.
  • Save your .mask project before making major changes.
Full Screen Editor opens on the wrong display
  • Select the correct display before opening Full Screen Editor.
  • If displays were connected or disconnected while StageMask was open, close and reopen the Full Screen Editor.

Best Practices

  • Match Stage Size to the final output before painting.
  • Use a reference image or stage screenshot for alignment.
  • Use broad hard strokes first, then smaller soft strokes for cleanup.
  • Add a vignette last, after the main mask shape is working.
  • Keep the editable .mask file and export PNGs as needed.