Pixelify is a powerful and flexible TypeScript library for
converting images to pixel art with customizable options.

Demo




Brought to you by the HokkiAI team

Features

✨ Easy to use: Simple API with sensible defaults
🎨 Highly customizable: Control pixel size, color count, dithering, and more
🚀 High performance: Optimized processing with caching and efficient algorithms
📦 Multiple formats: Save to file or get as buffer for further processing
🔧 TypeScript support: Fully typed with comprehensive IntelliSense

Installation

npm install @hokkiai/pixelify
# or
yarn add @hokkiai/pixelify
# or
pnpm add @hokkiai/pixelify

Quick Start

import { pixelify } from "@hokkiai/pixelify";

// Basic usage
const result = await pixelify("./input.jpg", "./output.png", {
  pixelSize: 12,
  colors: 24,
});

console.log(
  `Converted to ${result.colors} colors in ${result.processingTime}ms`
);

API Reference

pixelify(inputPath, outputPath, options?)

Convert an image to pixel art and save it to a file.

Parameters:

• inputPath (string): Path to the input image
• outputPath (string): Path where the pixel art will be saved
• options (PixelifyOptions, optional): Customization options

Returns: Promise<PixelifyStats>

pixelifyToBuffer(inputPath, options?)

Convert an image to pixel art and return as a buffer.

Parameters:

• inputPath (string): Path to the input image
• options (PixelifyOptions, optional): Customization options

Returns: Promise<{ buffer: Buffer, stats: PixelifyStats }>

Options

interface PixelifyOptions {
  /** Size of each pixel in the output image (default: 12) */
  pixelSize?: number;

  /** Maximum number of colors to use (default: 24, range: 2-256) */
  colors?: number;

  /** Maximum height of the output image (default: 1000) */
  maxHeight?: number;

  /** Whether to maintain aspect ratio when resizing (default: true) */
  maintainAspectRatio?: boolean;

  /** Strength of dithering effect (default: 0, range: 0-1) */
  ditherStrength?: number;
}

Examples

Basic Usage

import { pixelify } from "@hokkiai/pixelify";

// Simple pixel art conversion
await pixelify("./photo.jpg", "./pixelart.png", {
  pixelSize: 16,
  colors: 32,
});

Advanced Usage with Dithering

import { pixelify } from "@hokkiai/pixelify";

// Create retro-style pixel art with dithering
const stats = await pixelify("./landscape.jpg", "./retro.png", {
  pixelSize: 12,
  colors: 16,
  ditherStrength: 0.3,
  maxHeight: 600,
});

console.log(
  `Created ${stats.width}x${stats.height} pixel art with ${stats.colors} colors`
);

Working with Buffers

import { pixelifyToBuffer } from "@hokkiai/pixelify";
import fs from "fs";

// Get pixel art as buffer for further processing
const { buffer, stats } = await pixelifyToBuffer("./image.jpg", {
  pixelSize: 8,
  colors: 8,
});

// Process the buffer or save with custom logic
fs.writeFileSync("./custom-output.png", buffer);

Batch Processing

import { pixelify } from "@hokkiai/pixelify";
import { readdir } from "fs/promises";
import path from "path";

async function batchPixelify(inputDir: string, outputDir: string) {
  const files = await readdir(inputDir);

  for (const file of files) {
    if (file.match(/\.(jpg|jpeg|png|webp)$/i)) {
      const inputPath = path.join(inputDir, file);
      const outputPath = path.join(
        outputDir,
        `pixel_${file.replace(/\.[^.]+$/, ".png")}`
      );

      try {
        await pixelify(inputPath, outputPath, {
          pixelSize: 14,
          colors: 20,
        });
        console.log(`✅ Processed ${file}`);
      } catch (error) {
        console.error(`❌ Failed to process ${file}:`, error);
      }
    }
  }
}

Presets

Here are some recommended presets for different styles:

// Retro gaming style
const retroPreset = {
  pixelSize: 16,
  colors: 8,
  ditherStrength: 0.5,
};

// Modern pixel art
const modernPreset = {
  pixelSize: 12,
  colors: 32,
  ditherStrength: 0.2,
};

// High detail pixel art
const detailedPreset = {
  pixelSize: 8,
  colors: 64,
  ditherStrength: 0.1,
};

// Minimalist style
const minimalPreset = {
  pixelSize: 20,
  colors: 4,
  ditherStrength: 0,
};

Performance Tips

• Reduce maxHeight for faster processing of large images
• Use fewer colors for simpler images and faster processing
• Disable dithering (ditherStrength: 0) for maximum speed
• Use pixelifyToBuffer when you need to process the result further

Supported Input Formats

• JPEG (.jpg, .jpeg)
• PNG (.png)
• WebP (.webp)
• TIFF (.tiff)
• And many others supported by Sharp

Requirements

• Node.js 16.0.0 or higher
• Sharp library (automatically installed as dependency)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.