ps_layer_mask
Create, delete, apply, or draw gradients on layer masks. Use with a selection to mask content to a frame, or fade edges with a linear gradient.
Instructions
Manage the active layer's mask — choose with op. create: add a layer mask; if a selection is active it reveals the selection and hides the rest (the one-call "mask the placed image to the frame opening" — make the selection first, then create); with no selection, a reveal-all mask; adjustment layers load the current selection into their built-in mask. delete: remove the mask (layer pixels preserved). apply: DESTRUCTIVE — permanently bake the mask into the pixels (outside-mask pixels lost). gradient: draw a linear fade into the mask (fade_to names the side that ends hidden; start/end place the fade; auto-creates the mask; replaces existing mask content and clears any active selection first) — the standard fade for reflections, sky blends, and soft edge falloff. Verify with ps_get_preview. Prefer keeping masks non-destructive unless flattening for export. Don't write Mk Chnl At=Msk or Grdn AM scripts in execute_script — this tool already does both.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| op | Yes | create: add a layer mask on the active layer (if a selection is active it reveals the selection — the "mask to the frame opening" answer; adjustment layers load the selection into their built-in mask). delete: remove the mask (layer pixels preserved). apply: DESTRUCTIVE — bake the mask into pixels (pixels outside the mask are lost). gradient: draw a linear white→black fade INTO the mask (auto-creates a reveal-all mask if none) — the universal fade-out primitive (reflections, sky blends, edge feathering). REPLACES existing mask content. | |
| end | No | op=gradient: 0-1 fraction where the fade completes — fully hidden from here on. Must be greater than start. | |
| start | No | op=gradient: 0-1 fraction along the fade direction where the fade begins — the layer stays fully visible up to here. | |
| extent | No | op=gradient: measure start/end over the active layer's pixel bounds (default) or the whole canvas. A layer with no pixel bounds falls back to canvas. | layer |
| fade_to | No | op=gradient: the side that ends fully HIDDEN (mask black). The opposite side stays fully visible. E.g. a water reflection fades with fade_to=bottom. | bottom |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | op=gradient: fully-hidden end of the drawn fade, doc pixels. | |
| from | No | op=gradient: fully-visible end of the drawn fade, doc pixels. | |
| extent | No | op=gradient: 'layer' or 'canvas' — reports the extent actually used. | |
| context | No | ||
| fade_to | No | ||
| layer_name | No | ||
| bounds_used | No | ||
| maskApplied | No | ||
| maskCreated | No | ||
| maskDeleted | No | ||
| created_mask | No | op=gradient: true when the reveal-all mask had to be created first. | |
| hadSelection | No | ||
| mask_gradient | No | ||
| activeLayerKind | No | ||
| modifiedExistingMask | No |