pix2svg 0.1.0

Convert pixel art images to optimized SVG format
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

# pix2svg

> Warning: This project is mainly created by GitHub Copilot with Claude Sonnet 4. Not fully reviewd and tested yet. Use it at your own risk. PRs and issues are welcome.

A fast and efficient command-line tool to convert pixel art images to optimized SVG format with greedy rectangle merging.

## Installation

### From Source

```bash
git clone https://github.com/LeSnow-Ye/pix2svg.git
cd pix2svg
cargo build --release
```

The binary will be available at `target/release/pix2svg`.

### Using Cargo

```bash
cargo install pix2svg
```

## Usage

### Basic Usage

```bash
# Convert image.png to image.svg
pix2svg image.png

# Specify output file
pix2svg image.png -o output.svg

# Scale pixels by 4x
pix2svg image.png -s 4

# Enable verbose output
pix2svg image.png -v
```

### Advanced Options

```bash
# Convert with custom alpha threshold
pix2svg image.png --alpha-threshold 128

# Scale up and specify output
pix2svg sprite.png -s 8 -o large-sprite.svg -v
```

### Command Line Options

- `input`: Input image file path
- `-o, --output`: Output SVG file path (default: input filename with .svg extension)
- `-s, --scale`: Pixel scale factor (1-1000, default: 1)
- `--alpha-threshold`: Minimum alpha threshold for non-transparent pixels (0-255, default: 1)
- `--skip-transparent`: Skip transparent pixels (default: true)
- `-f, --force`: Force overwrite existing output files
- `-v, --verbose`: Enable verbose output
- `-h, --help`: Show help information

## Algorithm

The tool uses a greedy rectangle merging algorithm similar to the one used in Aseprite:

1. **Scan pixels**: Process image pixel by pixel from top-left to bottom-right
2. **Find rectangles**: For each unprocessed pixel, find the largest rectangle of the same color
3. **Optimize**: Greedily expand rectangles horizontally and vertically
4. **Output**: Generate SVG `<rect>` elements for each rectangle

This approach significantly reduces the number of SVG elements compared to naive pixel-by-pixel conversion.

## Examples

### Input

> Source: [CC-29 Palette](https://lospec.com/palette-list/cc-29)

464x120 = 55680 pixels

![](imgs/cc-29-palette-example-by-revvy-611f81.png)

### Output

4738 rectangles (8.51%)

![](imgs/cc-29-palette-example-by-revvy-611f81.svg)

## License

This project is licensed under the MIT License - see the LICENSE file for details.