# Masks

*Masks* are entities that control where instances can and cannot be scattered. They can either be [Paint masks](#paint-masks), [Area masks](#area-masks), [Path masks](#path-masks), [Image masks](#image-masks), or [Composition masks](#composition-masks).

A mask can be **inclusive**, which means that instances can only be scattered in its area, or **exclusive**, which means that instances cannot be scattered in its area.\
To switch between those two modes, click the <img src="https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MkGzIt5oSUary5Y-nEI%2F-MkH-HCEyEfYXF8CVRcW%2Fmask_inclusive.png?alt=media&#x26;token=da080d17-0d47-4643-87ca-80be77666985" alt="" data-size="original"> and <img src="https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MkGzIt5oSUary5Y-nEI%2F-MkH-LHJAlTWg739TfCE%2Fmask_exclusive.png?alt=media&#x26;token=9e418445-c9e3-4e09-b6f8-0b2b20474c78" alt="" data-size="original"> icons.

![Inclusive / Exclusive](https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MkGzIt5oSUary5Y-nEI%2F-MkHRM_PWmBRDKFKu6_o%2Fmasks_toggle.gif?alt=media\&token=96c6141c-3ad0-427f-bf68-492eefb6c9f3)

{% hint style="info" %}
If a composition contains both types of masks, **inclusive masks are applied first** and then exclusive masks are applied over the remaining instances.

Masks are automatically reordered when toggling their inclusive/exclusive mode in order to reflect this rule.
{% endhint %}

## Paint masks

A *Paint mask* allows you to manually draw the shape of the mask. You draw the shape with a brush, just like you would in Photoshop or similar image editors.

To draw the mask, click the <img src="https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MkHz2WazrDmIyTrJ8ZG%2F-MkI-BDYXcQUvoz3Ns0V%2Fadd_paint_mask.png?alt=media&#x26;token=8058d509-97d0-4255-b680-99fc0b712b67" alt="" data-size="original"> icon, then click & drag over your hosts. You can later click the <img src="https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MkHz2WazrDmIyTrJ8ZG%2F-MkI-Te0QE5mZKkNNJTW%2Fpaint_mask_paint.png?alt=media&#x26;token=df45272f-8d89-4f74-a535-026c2b959bf8" alt="" data-size="original"> icon at any point to continue drawing the mask.

![](https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MkGzIt5oSUary5Y-nEI%2F-MkHSgujuiJcul8U1uxH%2Fpaint_mask_paint.gif?alt=media\&token=651bf606-59ff-4efb-9e53-eb8f03dd06e8)

To erase the mask, click the <img src="https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MkHz2WazrDmIyTrJ8ZG%2F-MkI-av8f0gl-V4cQ9Rs%2Fpaint_mask_erase.png?alt=media&#x26;token=30ad9e22-fed7-4c40-9abf-21457f1c7592" alt="" data-size="original"> icon, then click & drag over the existing shape.

![](https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MkGzIt5oSUary5Y-nEI%2F-MkHT8xGS5I97WztHG3-%2Fpaint_mask_erase.gif?alt=media\&token=124ecab4-b761-4572-aa26-907da470f0a8)

{% hint style="info" %}
Erasing an *inclusive* Paint mask is not the same thing as drawing an *exclusive* Paint mask!
{% endhint %}

| Key   | Description                                                                 |
| ----- | --------------------------------------------------------------------------- |
| ALT   | Change the drawing mode when pressed (toggle paint/erase)                   |
| SHIFT | Draw a straight line                                                        |
| CTRL  | Maintain pressed and move the cursor laterally to change the brush's radius |

## Area masks

An *Area mask* is a group or a component instance that defines a space under which instances will not be scattered.

To add a new Area mask, click the <img src="https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MkHz2WazrDmIyTrJ8ZG%2F-MkI1Qy8y_hzp6Wj_4Uz%2Fadd_area_mask.png?alt=media&#x26;token=fdd5837c-07f6-4586-a3d1-2cb653d722e8" alt="" data-size="original"> icon and pick a group or component in the model.

![](https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MkHz2WazrDmIyTrJ8ZG%2F-MkI1V-xsSbKuu4kn1HW%2Fpick_area_mask.gif?alt=media\&token=f18e1451-5787-4404-8edf-1524e232d1ec)

| Parameter       | Description                                                                                                                                                                                                                                                                                                                                     |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Mode            | <p>Part of the geometry used for masking.</p><p></p><p>In <code>Faces</code> mode, instances directly below the entity faces will be masked. This is useful to preserve holes in the mask.</p><p>In <code>Contours</code> mode, the whole silhouette of the picked entity is used. Only edges are considered, faces do not have any effect.</p> |
| Projection axis | <p>The direction in which instances are masked.</p><p></p><p>If unchanged, the default behavior is to use the same projection axis as the composition.</p>                                                                                                                                                                                      |

![Left: Faces mode. Right: Contours mode.](https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MkHz2WazrDmIyTrJ8ZG%2F-MkI4tofmVnEVOZrLSyQ%2Ffaces_contours.png?alt=media\&token=38517be8-064a-4bd0-90f6-641b353c1455)

## Path masks

A *Path mask* uses a curve with a configurable thickness under which instances will not be scattered.

![Path masks are particularly convenient to simulate dirt paths and tire tracks.](https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MgoMDTLxPQmsK9t71q5%2F-MgoOBJDcwH4Z3FZDaka%2Fpath_mask.jpg?alt=media\&token=4a3145c6-86a4-48e8-974b-947e76101956)

To add a new Path mask, click the <img src="https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MkI5NyBO0kKc39XljWG%2F-MkI7OKVk2SI8tSoKe9t%2Fadd_path_mask.png?alt=media&#x26;token=ccf990bb-1d87-440d-b9e8-782664a32d0d" alt="" data-size="original"> icon and pick a group/component containing curves.

![](https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MkI5NyBO0kKc39XljWG%2F-MkI6W-u-nxwtN2llAuP%2Fpick_path_mask.gif?alt=media\&token=7d3946fe-171c-4836-883d-0461f50508c0)

| Parameter       | Description                                                                     |
| --------------- | ------------------------------------------------------------------------------- |
| Thickness       | Lateral distance under which instances are masked                               |
| Projection axis | The direction in which instances are masked, like for [area masks](#area-masks) |

## Image masks

An *Image mask* uses an external image file to control where instances can be scattered. This is useful to reproduce complex patterns.

To add a new Image mask, click the <img src="https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MkIM3Rj79x_As4ieQkT%2F-MkIMVSTiBllLNweeSbQ%2Fadd_image_mask.png?alt=media&#x26;token=d8ae364e-3fd1-442b-b6b0-6405b32f6f2b" alt="" data-size="original"> icon and select an image file on your disk.&#x20;

![The black and white Skatter logo is used as an image mask to scatter vegetation.](https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MgoMDTLxPQmsK9t71q5%2F-MgoOGP1fS0RQ-E753Y4%2Fimage_mask.jpg?alt=media\&token=edd747bc-1ee3-4326-8c86-6b323d4d2691)

{% hint style="warning" %}
Image masks rely on the surface hosts having valid [texture coordinates](https://skatter.help.lindale.io/hosts#texture-coordinates). Please make sure that your surface hosts are properly set up.
{% endhint %}

| Parameter           | Description                                                                                                                                                                                                                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| File                | Image file to use as a mask.                                                                                                                                                                                                                                                                                       |
| Offset              | <p>Moves the image along the X and Y axis.</p><p></p><p>Texture coordinates are traditionally defined in the <code>\[0, 1]</code> range, so an offset of <code>0.5</code> usually moves the image by half its size (this convention might not be followed depending on the origin of the texture coordinates).</p> |
| Scale               | Size of the projected image. Tweak this value to create zoom or tiling effects.                                                                                                                                                                                                                                    |
| Rotation            | Orientation of the image, in degrees.                                                                                                                                                                                                                                                                              |
| Display the texture | Shows the image in the viewport (only for SketchUp 2020+).                                                                                                                                                                                                                                                         |

{% hint style="warning" %}
SketchUp only allows extensions to draw textures in the viewport since SketchUp 2020 so the preview will not be available for older versions.
{% endhint %}

### Darkness values

The whiter a pixel of the image is, the more likely it is for an instance to be scattered there.

A 100% white pixel means that instances can be scattered there. A 100% black pixel means that instances cannot be scattered there. Values in between are interpolated linearly.

![](https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MkI5NyBO0kKc39XljWG%2F-MkIBK7zNB1RfC6Fy9ec%2Fimage_mask_b%26w.png?alt=media\&token=23c48ba8-fc29-4ab5-98ed-55c0a582fd6c)

{% hint style="info" %}
Image masks only consider grayscale values, as shown in the SketchUp preview. Skatter accepts colored images and converts them to grayscale.
{% endhint %}

## Composition masks

A *Composition mask* uses the instances from another composition to filter where instances can and cannot be scattered.

For instance, a composition *Trees* might be used as the composition mask for a composition *Fallen leaves*, so that they only appear around the trees.

![Fallen leaves are part of a composition that uses another composition's trees as a mask so that leaves only appear around trees.](https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MgoMDTLxPQmsK9t71q5%2F-MgoQdrYpKPgi4ye98xQ%2Fcomposition_mask.jpg?alt=media\&token=73efb1e0-680f-4205-93a1-263642b4caa9)

![](https://777932824-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MJXK0YXrcDUpbe_Du_o%2F-MkI5NyBO0kKc39XljWG%2F-MkIDq-upvE39lFko476%2Fcomposition_mask.gif?alt=media\&token=2e4f6111-7e0c-479d-b94b-c31c6f2efde1)

| Parameter   | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| Composition | The other composition to use as a mask                         |
| Radius      | Distance to mask around each instance of the other composition |

{% hint style="warning" %}
It is possible to chain multiple compositions as masks of each other ("*composition A masks composition B which itself masks composition C...*").

However, Skatter does not allow to create cycles where all compositions depend on each other ("**A** → B → C → **A**") as it would be impossible to compute.
{% endhint %}
