Get the pixel scale of an image, or scale it up or down without quality loss. Useful for pixel art!
- Zero loss of quality.
- Zero dependencies.
- Works directly on ImageData.
Click to open
npm install pixel-scaleAll inputs are validated at runtime. Invalid arguments throw TypeError or RangeError.
scalePixels(imageData, to, options?)Scales an image up or down to a specific pixel scale without losing quality or
changing any colors. The current scale is detected with getPixelScale unless
options.from is provided.
// detect the current scale and rescale it to 1
scalePixels(imageData, 1);
// upscale from a known scale of 5 to 10
scalePixels(imageData, 10, { from: 5 });
// detect the current scale, allowing a per-channel diff of 10
scalePixels(imageData, 2, { maxColorDiff: 10 });multiplyPixelScale(imageData, multiplier, options?)Upscales an image by multiplying its current pixel scale. For example, scale 5 multiplied by 2
becomes scale 10. The current scale is detected with getPixelScale unless
options.from is provided.
// detect the current scale and double it
multiplyPixelScale(imageData, 2);
// take an image of known scale 5 and multiply it by 10
multiplyPixelScale(imageData, 10, { from: 5 });dividePixelScale(imageData, divider, options?)Downscales an image by dividing its current pixel scale. For example, scale 8 divided by 4 becomes
scale 2. The current scale is detected with getPixelScale unless options.from is
provided. divider must evenly divide the current scale.
// detect the current scale and halve it
dividePixelScale(imageData, 2);
// take an image of known scale 8 and divide it by 4
dividePixelScale(imageData, 4, { from: 8 });getPixelScale(imageData, options?)Detects the current pixel scale of an image. Returns the largest scale for which
every scale × scale block of pixels is a solid color, or 1 if no larger scale can be found.
Accepts the looser ImageDataLike shape, so it works on any { data, width, height }
object.
const scale = getPixelScale(imageData);
// allow a per-channel diff of 10 when comparing pixels
const scale = getPixelScale(imageData, { maxColorDiff: 10 });scalePixels, multiplyPixelScale, and dividePixelScale accept the same options object.
getPixelScale only accepts maxColorDiff.
| Option | Type | Default | Description |
|---|---|---|---|
from |
number |
auto-detected | The current scale of the image. Only provide this if you already know the scale and want to skip detection. |
maxColorDiff |
number |
0 |
Maximum allowed per-channel difference (0-255) when comparing pixels during scale detection. Useful for images from lossy formats (e.g. JPEG). Ignored when from is set. |
All functions operate on ImageData,
which you can get from a canvas
in the browser, or from libraries like node-canvas or
sharp on Node.
getPixelScale is the most lenient and accepts any { data, width, height } object (typed as
ImageDataLike). The other functions return a real ImageData instance, so they need the
ImageData constructor to be available globally.
The pixel scale referred to in this readme is the number of times a pixel of e.g. a pixel art image has been multiplied to increase the image size. For example, this image has a pixel scale of 1, while this image has a pixel scale of 10.
To detect an image's pixel scale, pixel-scale first finds the common divisors of its width and
height. This is done using Euclid's algorithm for the greatest common divisor, and then counting
down. A more performant method (like prime factorization) isn't needed here, since image dimensions
stay relatively small.
It then tests each common divisor, starting from the largest, by splitting the image into
divisor * divisor blocks and checking that every block is a solid color (within maxColorDiff).
The first divisor where every block passes is the pixel scale.