pixelsrc 0.2.0

Pixelsrc - GenAI-native pixel art format and compiler
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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

# import

Import a PNG image and convert it to Pixelsrc format.

## Usage

```
pxl import [OPTIONS] <INPUT>
```

## Arguments

| Argument | Description |
|----------|-------------|
| `<INPUT>` | Input PNG file to convert |

## Options

| Option | Description |
|--------|-------------|
| `-o, --output <OUTPUT>` | Output file (default: `{input}.jsonl`, use `.pxl` extension for new format) |
| `--max-colors <MAX_COLORS>` | Maximum number of colors in the palette (2-256, default: 16) |
| `-n, --name <NAME>` | Name for the generated sprite (default: derived from filename) |

## Description

The `import` command analyzes a PNG image and generates a Pixelsrc file containing:
- A palette with the detected colors
- A sprite with tokens referencing the palette

This is useful for converting existing pixel art into the Pixelsrc format for editing or animation.

## Examples

<!-- DEMOS cli/import#basic -->
**Import Workflow**

Convert a PNG image to Pixelsrc format. The import command detects colors and creates a palette and sprite definition.

<div class="demo-source">

```bash
# Input: hero.png (16x16 pixel art)
pxl import hero.png -o hero.pxl

# Output: hero.pxl contains:
# {"type": "palette", "name": "hero", "colors": {"{_}": "#00000000", ...}}
# {"type": "sprite", "name": "hero", "palette": "hero", "grid": [...]}
```

</div>

<div class="demo-container" data-demo="basic">
</div>
<!-- /DEMOS -->

### Basic import

```bash
# Import with default settings
pxl import hero.png

# Creates hero.jsonl with detected colors and sprite data
```

### Custom output format

```bash
# Output as .pxl format (preferred)
pxl import hero.png -o hero.pxl

# Output to specific location
pxl import hero.png -o assets/sprites/hero.pxl
```

### Controlling colors

<!-- DEMOS cli/import#quantization -->
**Color Quantization**

Limit the palette size during import for retro-style constraints.

<div class="demo-source">

```bash
# Limit to 4 colors (Game Boy style)
pxl import hero.png --max-colors 4

# Result: palette has at most 4 colors
# Colors are quantized to fit the constraint
```

</div>

<div class="demo-container" data-demo="quantization">
</div>
<!-- /DEMOS -->

```bash
# Limit to 4 colors (Game Boy style)
pxl import hero.png --max-colors 4

# Allow more colors for detailed sprites
pxl import detailed.png --max-colors 64
```

### Custom sprite name

```bash
# Name the sprite instead of using filename
pxl import player-idle-frame1.png --name player_idle
```

## Color Quantization

When the source image has more colors than `--max-colors`, the importer will reduce the color count through quantization. This may result in slight color differences from the original.

For best results:
- Use source images that are already limited to your target palette
- Import at the original resolution (don't scale up before importing)
- Review the generated palette and adjust colors if needed

## Tips

- Import works best with clean pixel art (no anti-aliasing)
- Transparent pixels are preserved
- Very similar colors may be merged during import
- Use `pxl show` after import to preview the result

## See Also

- [render](render.md) - Render sprites back to PNG
- [palettes](palettes.md) - Use built-in palettes instead of importing colors
- [new](new.md) - Create new sprites from templates