pixelated

Pixelate images from the command line or as a Node.js library. Supports PNG, JPEG, WebP, AVIF, SVG, and ANSI terminal output.

CLI

Install globally:

npm install -g pixelated

Basic usage — output defaults to photo_pixelated_20.jpg:

pixelated photo.jpg

Specify an output file:

pixelated photo.jpg -o out.png

Batch — multiple files processed in parallel, all auto-named:

pixelated *.jpg --palette gb --dither
pixelated photo1.jpg photo2.jpg photo3.jpg --format webp

Demo

Generate ~100 variants in parallel to explore the full option space — pixel sizes, all palettes, shapes, gaps, and effects:

pixelated demo photo.jpg

Output lands in photo_demo/, named photo_<variant>.jpg. Optional flags:

| Flag | Long | Description | |---|---|---| | -o | --output-dir [dir] | Output directory (default: <basename>_demo) | | -f | --format [format] | Convert all variants to a specific format |

Options

| Flag | Long | Description | |---|---|---| | -o | --output [path] | Output file path (single file only) | | -p | --pixel [size] | Block size: 20, 10x20 for non-square, or auto (default: 20) | | -D | --pixel-density [n] | Target blocks across short axis for --pixel auto (default: 50) | | -g | --greyscale | Convert to greyscale | | -B | --blur [sigma] | Gaussian blur before pixelating — smooths noisy sources | | -r | --brightness [n] | Brightness multiplier before pixelating, e.g. 1.2 | | -C | --contrast [n] | Contrast multiplier before pixelating, e.g. 1.5 | | -a | --saturation [n] | Saturation multiplier before pixelating, e.g. 1.5 | | -h | --hue [degrees] | Hue rotation in degrees before pixelating, e.g. 90 | | -i | --invert | Invert colors before pixelating | | -P | --palette [preset\|...hex] | Named palette preset or space-separated hex colors | | -d | --dither | Floyd-Steinberg dithering (use with --palette) | | -c | --colors [n] | Reduce output to N colors via k-means quantization | | -v | --vibrancy [amount] | Bias palette lookup toward more saturated colors, 0–1 (use with --palette) | | -R | --remap [amount] | Pre-shift pixels toward nearest palette color before pixelating, 0–1 (use with --palette) | | -n | --noise [amount] | Random color variation per block, e.g. 10 | | -e | --seed [n] | Seed for reproducible noise/jitter output | | -f | --format [format] | Output format: png jpeg webp avif svg ansi | | -s | --scale [n] | Output scale multiplier (0.05 for pixel-art, 2 for 2×) | | -S | --shape [shape] | Block shape — see shapes table (default: rect) | | -A | --alt | Alternate shape orientation on a checkerboard pattern | | -O | --offset | Offset every other row by half a block width | | -G | --gap [px] | Gap between blocks — mosaic effect | | -l | --scanlines [px] | Scanline gap height per block row — CRT effect | | -b | --background [hex] | Gap/scanline fill color — transparent if omitted | | -j | --jitter [px] | Randomly displace each block by up to N pixels | | -V | --size-variance [amount] | Randomly scale each block by ±amount, e.g. 0.3 | | -u | --pulse [delta] | Alternate block size on a checkerboard — delta as a fraction, e.g. 0.25 | | -w | --wave [wavelength] | Sinusoidal size wave across the grid — wavelength in blocks, e.g. 6 | | -L | --brightness-size [strength] | Scale block size by luminance — dark=big, bright=small, 0–1 |

Examples

# Game Boy palette with dithering
pixelated photo.jpg --palette gb --dither

# Auto pixel size — picks a block size that produces ~50 blocks across the short axis
pixelated photo.jpg --pixel auto

# Pre-blur smooths high-frequency detail before applying a limited palette
pixelated photo.jpg --blur 2 --palette pico8 --dither

# Reduce to 8 colors via k-means quantization
pixelated photo.jpg --colors 8

# Boost contrast and saturation before pixelating
pixelated photo.jpg --contrast 1.4 --saturation 1.3

# Invert colors
pixelated photo.jpg --invert

# Noise for a hand-placed pixel-art feel (seeded for reproducibility)
pixelated photo.jpg --noise 15 --seed 42

# Convert to WebP
pixelated photo.jpg -o out.webp

# Tiny pixel-art export — each 20px block becomes 1 output pixel
pixelated scene.png --scale 0.05

# 2× upscale for big blocky display
pixelated scene.png --scale 2

# Render directly in the terminal — image builds row by row as it processes
pixelated photo.jpg --format ansi

# Circle mosaic SVG with dark background
pixelated photo.jpg --format svg --shape circle --gap 3 --background '#111111'

# Hexagon mosaic PNG with transparent gaps
pixelated photo.png --shape hexagon --gap 2

# Triangle mosaic with scanlines
pixelated photo.jpg --shape triangle --scanlines 2

# Triangular tiling — offset rows of same-direction triangles
pixelated photo.jpg --shape triangle --offset

# Alternating up/down triangles
pixelated photo.jpg --shape triangle --alt

# Diamond mosaic PNG with transparent gaps
pixelated photo.png --shape diamond --gap 4

# 5-pointed star mosaic
pixelated photo.jpg --shape star --gap 2

# Alternating star orientations
pixelated photo.jpg --shape star --alt --gap 2

# Plus-sign cross mosaic
pixelated photo.jpg --shape cross --gap 2

# Saltire (×) mosaic
pixelated photo.jpg --shape x --gap 2

# Alternating + and × by block position
pixelated photo.jpg --shape cross --alt --gap 2

# 6-arm asterisk mosaic
pixelated photo.jpg --shape asterisk --gap 2

# Hash/pound sign mosaic
pixelated photo.jpg --shape hash --gap 2

# Pentagon mosaic
pixelated photo.jpg --shape pentagon --gap 2

# Hollow ring / donut mosaic
pixelated photo.jpg --shape ring --gap 2

# Rounded rectangle mosaic
pixelated photo.jpg --shape round-rect --gap 2

# Heart mosaic
pixelated photo.jpg --shape heart --gap 2

# Crescent moons (alternating orientation)
pixelated photo.jpg --shape crescent --alt --gap 2

# Leaf / lens mosaic
pixelated photo.jpg --shape leaf --gap 2

# Pacman — 4 orientations on a checkerboard
pixelated photo.jpg --shape pacman --alt --gap 2

# Bowtie mosaic / hourglass (--alt)
pixelated photo.jpg --shape bowtie --gap 2
pixelated photo.jpg --shape bowtie --alt --gap 2

# Arrow mosaic (alternating left/right with --alt)
pixelated photo.jpg --shape arrow --gap 2

# 5-petal flower mosaic
pixelated photo.jpg --shape flower --gap 2

# Bacon — wavy horizontal strips (vertical with --alt)
pixelated photo.jpg --shape bacon
pixelated photo.jpg --shape bacon --alt

# Block modifiers — jitter, size variance, pulse, wave, brightness-size
pixelated photo.jpg --shape circle --jitter 4 --gap 3
pixelated photo.jpg --shape circle --size-variance 0.3 --gap 3
pixelated photo.jpg --shape circle --pulse 0.25 --gap 3
pixelated photo.jpg --shape circle --wave 6 --gap 3
pixelated photo.jpg --shape circle --brightness-size 0.8 --gap 3

# Combine modifiers
pixelated photo.jpg --shape circle --jitter 3 --size-variance 0.2 --gap 3

# Custom hex palette
pixelated photo.jpg --palette '#ff0000' '#00ff00' '#0000ff'

# Non-square pixel blocks (wide scanlines look)
pixelated photo.jpg --pixel 4x20

# Batch with neon palette, output as WebP
pixelated *.jpg --palette neon --format webp

Palettes

Game Boy

| Name | Colors | Notes | |---|---|---| | gb | 4 | Original DMG green | | gbp | 4 | Game Boy Pocket greyscale | | gbc | 16 | Game Boy Color | | gba | 19 | Game Boy Advance |

Nintendo / Sega / SNK

| Name | Colors | Notes | |---|---|---| | nes | 55 | NES 2C02 hardware palette | | snes | 29 | Super Nintendo (5-bit RGB) | | n64 | 22 | Nintendo 64 mood palette | | vb | 4 | Virtual Boy red phosphor | | genesis | 35 | Sega Genesis (9-bit RGB) | | sms | 64 | Sega Master System (6-bit RGB, full palette) | | gg | 31 | Game Gear (12-bit color) | | tg16 | 29 | TurboGrafx-16 / PC Engine (9-bit RGB) | | neogeo | 28 | Neo Geo AES arcade palette | | ps1 | 24 | PlayStation 1 |

Retro computers

| Name | Colors | Notes | |---|---|---| | c64 | 16 | Commodore 64 | | pico8 | 16 | PICO-8 fantasy console | | cga | 4 | IBM CGA magenta/cyan | | ega | 16 | IBM EGA standard | | zxspectrum | 15 | ZX Spectrum | | msx | 15 | MSX / TMS9918 VDP (exact hardware) | | atari | 34 | Atari 2600 NTSC | | amstrad | 27 | Amstrad CPC (3-level RGB, full palette) | | amiga | 30 | Commodore Amiga OCS (12-bit color) | | apple2 | 6 | Apple II Hi-Res NTSC artifact colors |

Aesthetic / mood

| Name | Colors | Notes | |---|---|---| | mono | 2 | Black & white | | rainbow | 7 | ROYGBIV | | neon | 8 | Cyberpunk/synthwave | | sepia | 8 | Vintage warm browns | | pastel | 8 | Soft dreamy | | amber | 8 | Amber phosphor monitor | | terminal | 8 | Green phosphor terminal | | monokai | 9 | Monokai | | sunset | 10 | Dusk to night | | sakura | 10 | Cherry blossom | | vaporwave | 10 | Retrowave | | ocean | 10 | Deep sea blues | | lava | 11 | Volcanic reds to gold | | dracula | 11 | Dracula theme | | forest | 12 | Deep forest greens | | nord | 16 | Nord Arctic | | solarized | 16 | Solarized |

Pass custom colors instead of a preset name:

pixelated photo.jpg --palette '#0f380f' '#306230' '#8bac0f' '#9bbc0f'

Shapes

| Shape | Description | |---|---| | rect | Solid rectangle (default) | | round-rect | Rectangle with rounded corners | | circle | Solid circle | | ring | Hollow circle (donut) | | diamond | Square rotated 45° | | hexagon | Regular hexagon | | pentagon | Regular pentagon | | triangle | Triangle | | star | 5-pointed star | | cross | Plus sign (+) | | x | Saltire (×) | | asterisk | 6-arm asterisk (*) | | hash | Hash / pound sign (#) | | heart | Heart ♥ | | crescent | Crescent moon | | leaf | Lens/leaf — intersection of two circles | | pacman | Pacman — circle with a wedge cut out | | bowtie | Two triangles meeting at center — --alt for hourglass | | arrow | Rightward arrow — --alt alternates direction | | flower | 5-petal flower | | bacon | Wavy horizontal strips — --alt for vertical |

--alt and --offset

These flags modify how shapes tile across the grid and can be combined with any shape:

| Flag | Effect | |---|---| | --alt | Alternates shape orientation on a checkerboard — every other block flips. Triangles go up/down, pentagons rotate, stars invert, hearts flip upside-down. | | --offset | Shifts every other row by half a block width — rows interlock like brickwork. Makes triangles and hexagons tile seamlessly. |

# Interlocking triangles (offset rows, same direction)
pixelated photo.jpg --shape triangle --offset

# Alternating up/down triangles
pixelated photo.jpg --shape triangle --alt

# Offset hexagon grid
pixelated photo.jpg --shape hexagon --offset

# Alternating star orientations
pixelated photo.jpg --shape star --alt

Block modifiers

These flags adjust the size or position of individual blocks for texture and depth effects:

| Flag | Effect | |---|---| | --jitter [px] | Randomly displaces each block by up to N pixels. Creates an organic, hand-stamped feel. Use --seed for reproducibility. | | --size-variance [amount] | Randomly scales each block by ±amount (e.g. 0.3 = ±30%). | | --pulse [delta] | Alternates block size on a checkerboard — one set of blocks is delta fraction larger, the other smaller. | | --wave [wavelength] | Applies a sinusoidal size wave across the grid. Wavelength is in blocks (e.g. 6). | | --brightness-size [strength] | Scales each block by its luminance — dark blocks grow, bright blocks shrink. |

# Scattered circles with jitter
pixelated photo.jpg --shape circle --jitter 4 --gap 3

# Organic size variation
pixelated photo.jpg --shape circle --size-variance 0.3 --gap 3

# Checkerboard size alternation
pixelated photo.jpg --shape circle --pulse 0.25 --gap 3

# Sinusoidal size wave
pixelated photo.jpg --shape circle --wave 6 --gap 3

# Dark areas rendered with larger blocks
pixelated photo.jpg --shape circle --brightness-size 0.8 --gap 3

Library

Install:

npm install pixelated

ESM:

import pixelated from 'pixelated'
import type { PixelatedOptions, PaletteKey, PixelatedFormat, PixelatedShape } from 'pixelated'

const output = await pixelated({
  input: 'photo.jpg',
  output: 'out.png',          // optional — defaults to 'photo_pixelated_20.jpg'
  pixel: 'auto',              // number, [width, height] for non-square, or 'auto'
  autoPixelDensity: 50,       // target blocks across short axis when pixel is 'auto'
  greyscale: false,
  blur: 2,                    // Gaussian blur sigma before pixelating
  brightness: 1.2,            // multiplier — >1 brighter, <1 darker
  contrast: 1.5,              // multiplier — >1 more contrast, <1 less
  saturation: 1.3,            // multiplier — >1 more saturated, 0 greyscale
  hue: 90,                    // hue rotation in degrees
  invert: false,              // invert colors before pixelating
  palette: 'gb',              // PaletteKey or string[] of hex colors
  dither: true,               // Floyd-Steinberg (use with palette)
  colorCount: 8,              // reduce to N colors via k-means after pixelating
  vibrancy: 0.5,              // bias palette lookup toward saturated colors, 0–1
  remap: 0.5,                 // pre-shift pixels toward palette before pixelating, 0–1
  noise: 15,                  // random ±N color variation per block
  seed: 42,                   // seed for reproducible noise/jitter
  format: 'webp',             // 'png' | 'jpeg' | 'jpg' | 'webp' | 'avif' | 'svg' | 'ansi'
  scale: 2,                   // output scale multiplier
  shape: 'hexagon',           // see shapes table
  alt: true,                  // alternate shape orientation on a checkerboard
  offset: true,               // offset every other row by half a block width
  gap: 4,                     // px gap between blocks
  scanlines: 2,               // px scanline gap at bottom of each block row
  background: '#000000',      // gap/scanline fill color (transparent if omitted)
  jitter: 4,                  // randomly displace each block by up to N pixels
  sizeVariance: 0.3,          // randomly scale each block by ±amount
  pulse: 0.25,                // checkerboard size alternation delta
  wave: 6,                    // sinusoidal size wave wavelength in blocks
  brightnessSize: 0.8         // scale block size by luminance, 0–1
})

// output: resolved file path, or 'stdout' when format is 'ansi' with no output file

CommonJS:

const pixelated = require('pixelated').default

await pixelated({ input: 'photo.jpg', palette: 'pico8', dither: true })

ANSI output

When format is 'ansi' and no output file is specified, the image streams directly to the terminal row by row as it processes — the building image is the progress indicator. Each pixel block renders as two colored spaces using 24-bit ANSI background color codes.

// Streams to terminal, returns 'stdout'
await pixelated({ input: 'photo.jpg', format: 'ansi' })

// Writes ANSI escape codes to a file
await pixelated({ input: 'photo.jpg', output: 'photo.ansi' })

Shapes and gaps

shape, gap, and scanlines work for both raster and SVG output. Pixels outside the shape are filled with background color, or left transparent (alpha 0) if background is omitted — use a format that supports transparency (PNG, WebP, AVIF, SVG) to see the effect. JPEG always fills with white.

// Transparent hexagon mosaic PNG
await pixelated({ input: 'photo.png', shape: 'hexagon', gap: 2 })

// Offset triangle tiling
await pixelated({ input: 'photo.jpg', shape: 'triangle', offset: true, gap: 2 })

// Alternating up/down triangles
await pixelated({ input: 'photo.jpg', shape: 'triangle', alt: true, gap: 2 })

// Star mosaic with neon palette
await pixelated({ input: 'photo.jpg', shape: 'star', palette: 'neon', gap: 2 })

// Alternating + and × cross mosaic
await pixelated({ input: 'photo.jpg', shape: 'cross', alt: true, gap: 2 })

// Triangle mosaic with CRT scanlines
await pixelated({ input: 'photo.jpg', shape: 'triangle', scanlines: 2, background: '#000000' })

// Solid circle mosaic SVG with dark background
await pixelated({ input: 'photo.jpg', format: 'svg', shape: 'circle', gap: 3, background: '#111111' })

// Jittered circles
await pixelated({ input: 'photo.jpg', shape: 'circle', jitter: 4, gap: 3, seed: 42 })

License

MIT — Jay Deaton