gradient_map
Map pixels onto a color ramp by brightness to convert imported images, photos, or gradients into ramp-matched pixel art.
Instructions
Put every pixel on a ramp by its brightness, whatever it started as.
The other shading tools all begin with art that is *already* on a ramp:
`shift_along_ramp` moves pixels between steps they already belong to, and
`shade_region_by_light` shades a flat region painted in one of the ramp's colours.
This is the one that brings art onto a ramp in the first place, which is what an
imported image, a photo traced over, or a gradient fill actually needs.
Each pixel's luminance decides its step: darkest to `ramp[0]`, lightest to the last
entry, the rest in between. Afterwards the art uses the ramp's colours and nothing
else, so `assess_sprite(..., ramp=...)` reports a palette conformance of 1.0.
Args:
ramp: The ramp, darkest first. Order is the mapping, so a reversed ramp inverts
the image.
contrast: Stretch the mapping around mid-grey. Above 1.0 pushes pixels toward
the ends of the ramp and drops the middle steps; below 1.0 crowds everything
into the middle. The interesting control is not which colours are used but
how much of the art each step takes.
bias: Shift the whole mapping after contrast, from -1.0 to 1.0. Positive is
lighter. Use it when an image maps too dark to read.
dither: "bayer4", "bayer2" or "checker" to break the bands. A pixel landing
between two steps takes the darker or the lighter one by an ordered pattern,
which reads as a gradient without adding a colour.
x, y, width, height: Restrict the change to a region.
Luminance is weighted 0.299/0.587/0.114, the same weighting the ramp matching uses,
so a saturated red and a dull red of the same weight land on the same step. Alpha is
carried through untouched, so the silhouette does not move and anti-aliased edges
keep their coverage, even though their colour is now a ramp entry.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | No | Default: 0. | |
| y | No | Default: 0. | |
| bias | No | Default: 0.0. | |
| ramp | Yes | ||
| frame | No | Default: 1. | |
| layer | No | ||
| width | No | ||
| dither | No | ||
| height | No | ||
| contrast | No | Default: 1.0. | |
| filename | Yes |