Fuzzy Dot Refiner

This tool converts AI-generated pixel art-like images into proper pixel art. It optimizes AI-generated images with smooth gradients and noise into pixel-perfect pixel art style.

Features

• Convert images to pixel art style
• Automatic detection of appropriate dot size
• Automatic color palette optimization (prioritizing frequently used colors)
• Background removal with transparency threshold setting
• Three different conversion approaches to choose from
• PNG format output support

Installation

npm install -g @creating-cat/fuzzy-dot-refiner

Usage

Basic usage

fdr <input_image> <output_image> [options]

Options

| Option | Short | Description | |------------|--------|------| | --size <number> | -s | Manually specify output size (e.g., 32, 48, 64, 32x48). If not specified, it will be automatically detected. | | --colors <number> | -C | Number of colors after color reduction (e.g., 16, 32, 64). Default is 32 colors. Specify 0 to disable color reduction. | | --dot-size <number> | -d | Manually specify dot size (e.g., 8, 16, 32). If not specified, it will be automatically detected. | | --scale <number> | | Output scale factor (e.g., 1, 2, 3). Each dot is output as N×N pixels. Default is 1 (actual size). | | --mode <mode> | -m | Processing mode (resize/dot/grid/all). Default is dot. | | --silent | -S | Silent mode (no log output). Disabled by default. | | --mcp | | Start as MCP server | | --help | -h | Show help |

About modes

• resize: Resize processing. Simple processing that can be handled relatively quickly.
• dot (default): Dot-by-dot processing. Aims to generate high-quality pixel art by analyzing each dot's boundaries individually.
• grid: Grid-based reconstruction processing. Attempts to convert to pixel art by correcting grid misalignments.
• all: Processes with all modes, generating images for each mode. The mode name is added to the output file name (e.g., output_dot.png).

Examples

# Basic conversion
fdr input.png output.png

# Convert with resize mode
fdr input.png output.png --mode resize

# Convert with specified size
fdr input.png output.png --size 32x64

# Convert with limited color count
fdr input.png output.png --colors 16

# Convert with specified dot size
fdr input.png output.png --dot-size 16

# Convert with scale factor (2x, 3x, etc.)
fdr input.png output.png --scale 2
fdr input.png output.png --scale 3

# Convert with combined options
fdr input.png output.png --scale 2 --size 32 --colors 16
fdr input.png output.png --scale 3 --mode dot --dot-size 8

# Convert with all modes
fdr input.png output.png --mode all

# Run in silent mode (no log output)
fdr input.png output.png --silent

Environment Variables

This tool also supports configuration via environment variables. To use a configuration file, copy the .env.local.example file to .env.local and enable the necessary settings.

For detailed explanations of environment variables, please refer to the .env.local.example file in the repository.

Sample Gallery

The following are sample images converted using Fuzzy Dot Refiner. Each image is an AI-generated pixel art-like image converted to pixel-perfect pixel art using each mode of this tool. Please note that the conversion doesn't always turn out well.

MCP (Model Context Protocol) Support

This tool can also function as an MCP server, allowing other AI tools to call the image conversion feature.

MCP Configuration Example

{
  "mcpServers": {
    "fuzzy-dot-refiner": {
      "command": "npx",
      "args": [
        "-y",
        "@creating-cat/fuzzy-dot-refiner",
        "--mcp"
      ]
    }
  }
}

Provided MCP Tools

• convert_image: Convert images to pixel art style
  • Input: input_path, output_path, mode (optional), size (optional), colors (optional), scale (optional)
  • Output: Success/failure of conversion result and file path information
  • Modes: dot (default), resize, grid, all
  • Scale: 1 (actual size, default), 2 (2x), 3 (3x), etc.

License

MIT