select_by_color
Select every pixel matching a color on a chosen layer to scope edits to that material; raise tolerance to include anti-aliased or nearby colors.
Instructions
Select every pixel of one layer matching a colour, the magic-wand selection.
The usual way to scope an edit to one material: select the armour's base colour and
every later operation touches only the armour. Pair it with `shift_along_ramp` to
shade one material without disturbing its neighbours.
Args:
color: The colour to match.
tolerance: 0 matches exactly. Higher values also catch nearby colours, which is
useful on artwork that was anti-aliased or converted from a photo.
frame: Which frame to sample, 1-based.
layer: Which layer to match on. Defaults to the top layer, which is the layer the
drawing and shading tools also default to, so a selection made here scopes
the call that follows it.
**One layer, not the composite**, and that is deliberate for the same reason
`get_pixels` takes a layer: the tools this selection is for write to one layer, so a
pixel selected on a different one is selected and unreachable. Select on the layer you
are about to edit.
This used to run Aseprite's `MaskByColor` without saying which layer it meant, and the
layer it got was whichever one Aseprite made active on opening the file, which is the
*bottom* one. Measured on an 8x8 sprite with red on the bottom layer and an opaque
blue square over half of it on the layer above: matching red selected all 64 pixels,
including the 32 nothing can see, and matching blue (32 pixels, plainly visible, and
on the layer every drawing tool writes to) selected nothing at all.
Refuses when no pixel matches, rather than reporting a success with no selection. The
old behaviour cleared the sidecar on the way through, so a mistyped colour silently
unscoped every edit that followed it, which is the opposite of what asking for a
selection means. A refusal leaves the previous selection as it was.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| color | Yes | ||
| frame | No | Default: 1. | |
| layer | No | ||
| filename | Yes | ||
| tolerance | No | Default: 0. |