Exporting Mask
A fixture mask is an image on which the positions of all fixtures and splines of the project are marked in white, exactly as they are arranged in the Mapping window, while the rest of the field remains transparent. Light Stream can save such a mask to a *.png file so it can be used in other programs.
What the mask is for
The mask is a pixel "map" of your object in project coordinates. It is most often used as follows:
- as a backing layer when preparing content in a third-party editor (After Effects, Photoshop, Resolume, etc.): video or images drawn over the mask will land exactly on the real fixtures;
- as a stencil: finished video is cropped by the mask, so light remains only where fixtures are actually installed;
- as a layout diagram for an artist or contractor who doesn't have Light Stream and the project;
- to check the layout itself — the mask makes it easy to see gaps, stray pixels and uneven lines.
By default the mask size matches the size of the Mapping field, so one mask pixel corresponds to one project pixel, and you won't need to align content with the fixtures manually.
Opening the window
- In the main menu choose View – Export Mask.
- The Export Fixture Mask window opens. On the left are the save buttons and parameters, on the right is a preview of the future file.
- The preview updates immediately whenever any parameter changes, so you can see the result before saving.
The mask is drawn in pure white. In the preview it is shown as white dots on a dark background, while in the saved file the background is fully transparent — the mask has no color, only white fixture pixels.
What is included in the mask
- All fixtures and splines of the project, regardless of selection and of which composition is open. The mask describes the fixture layout, not the animation, so effects, layouts, the background image and the grid are not included.
- Fixtures and splines that have the checkbox in the Enabled column unchecked in the Fixtures window are not included in the mask. Likewise, fixtures attached to a port or converter whose visibility checkbox is unchecked in the same window are not included. This is a convenient way to export a mask for only part of the object: turn off the unneeded fixtures, ports or converters and export the mask.
- Fixtures not yet attached to a port are included in the mask along with the rest: only the fixture's position matters for the mask, not its address.
- Fixtures placed outside the boundaries of the Mapping field are not included in the image — it is limited by the project size.
- The Fixtures and Splines checkboxes let you choose what to draw: only single fixtures, only splines, or both.
Window parameters
| Parameter | Description |
|---|---|
| Fixtures | Draw single fixtures in the mask. Enabled by default |
| Splines | Draw splines in the mask. Enabled by default |
| Fixture Size | Size of the white dot for a single fixture. Set in pixels of the Mapping field, default value 1. Fractional values are allowed |
| Spline Size | Thickness of the white line (dot size) for fixtures on splines, in pixels of the Mapping field. Default value 1 |
| Texture Width | Width of the saved image in pixels. Equal to the width of the Mapping field by default |
| Texture Height | Height of the saved image in pixels. Equal to the height of the Mapping field by default |
| X2 Size | Doubles the texture width and height. The button is available as long as both sides remain below 8192 pixels after doubling |
| 1/2 Size | Halves the texture width and height |
| Reset | Returns all parameters to their default values, and the texture size to the size of the current project |
Below the size buttons the current ratio of the texture to the project size is shown as 1.00x / 1.00x — separately for width and height. A value of 2.00x / 2.00x means the mask is being exported at twice the project size. Make sure both numbers match: if they differ, the image will come out stretched, and content drawn from such a mask will not line up with the fixtures.
The program remembers the parameters you set and will offer them the next time the window is opened.
Working with the preview
You can examine the preview in detail without changing the file itself:
- mouse wheel — zoom the image in or out;
- hold the mouse wheel — pan the image;
- right mouse button — reset the zoom and position to their original state.
Zooming in on the preview is useful to make sure the fixture dots haven't merged together and the spline lines aren't broken.
Saving the mask as a single file
- Enable the Fixtures and Splines checkboxes as needed.
- Set the dot and texture sizes, and check the result in the preview.
- Click Save As….
- Specify the folder and file name and click Save.
The mask is saved in *.png format with a transparent background. Everything shown in the preview goes into a single file.
Saving a separate file for each fixture
The Save Each button doesn't export a single combined mask, but a separate image for each single fixture and each spline of the project. This is needed when content is prepared for each element of the object individually — for example, when each line has its own animation.
- Enable the Fixtures and Splines checkboxes — only the marked types are exported. If both checkboxes are cleared, the button is unavailable.
- Click Save Each.
- Choose the folder the files will be saved to and click OK.
Each file receives the name of the fixture or spline from the Fixtures window and the .png extension. If a file with that name already exists in the folder, -d is appended to the new file's name, so previously saved masks are not overwritten. The texture and dot sizes are the same for all files and are taken from the window's fields, so the individual masks align exactly with each other and with the combined mask.
To make the files easy to tell apart, give the fixtures and splines meaningful names in the Fixtures window beforehand.
Choosing the mask size
- For most tasks the default size is sufficient — it equals the project size, and no alignment is needed.
- If there are many fixtures and they merge into a solid blob on the mask, increase the texture with the X2 Size button. The dots will grow along with the image, and the proportions will be preserved.
- If content is being prepared at a higher resolution than the Mapping field, export the mask at the content's resolution — but as a multiple of the project size, so the width-to-height ratio stays the same.
- The X2 Size button can be used to enlarge the mask as long as a side stays below 8192 pixels. Very large masks take longer to compute and take up more space.
- The Fixture Size and Spline Size values are set in project pixels and grow together with the texture. Increase them separately only when the dots need to be made deliberately larger than the actual pixel pitch — for example, to get a solid outline of the object.
- If you're unsure about the current values, click Reset and start over.