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
135
136
137
138
139

# analyze

Analyze Pixelsrc files and extract corpus metrics.

## Usage

```
pxl analyze [OPTIONS] [FILES]...
```

## Arguments

| Argument | Description |
|----------|-------------|
| `[FILES]...` | Files to analyze |

## Options

| Option | Description |
|--------|-------------|
| `--dir <DIR>` | Directory to scan for `.jsonl`/`.pxl` files |
| `-r, --recursive` | Include subdirectories when scanning a directory |
| `--format <FORMAT>` | Output format: `text` or `json` (default: `text`) |
| `-o, --output <OUTPUT>` | Write output to file instead of stdout |

## Description

The `analyze` command extracts statistics and metrics from Pixelsrc files:
- Total file, sprite, and palette counts
- Dimension distributions
- Color usage patterns
- Token frequency analysis
- Animation statistics

This is useful for understanding a corpus of sprites, training data analysis, or project auditing.

## Examples

### Analyze single file

```bash
# Analyze one file
pxl analyze sprite.pxl
```

### Analyze directory

```bash
# Analyze all files in a directory
pxl analyze --dir assets/sprites

# Include subdirectories
pxl analyze --dir assets --recursive
```

### JSON output

```bash
# Get machine-readable output
pxl analyze --dir sprites --format json

# Save to file
pxl analyze --dir sprites --format json -o metrics.json
```

### Analyze multiple files

```bash
# Analyze specific files
pxl analyze player.pxl enemy.pxl items.pxl

# Use glob patterns
pxl analyze *.pxl
```

## Sample Output

Text format:

```
Corpus Analysis
===============

Files:        24
Sprites:      156
Palettes:     12
Animations:   28

Dimensions:
  8x8:        42 (26.9%)
  16x16:      89 (57.1%)
  32x32:      18 (11.5%)
  Other:       7 (4.5%)

Colors:
  Average per sprite: 6.2
  Most common:
    black     (156 sprites)
    white     (142 sprites)
    skin      (98 sprites)

Tokens:
  Unique:     47
  Most used:  _ (transparent), black, white
```

JSON format:

```json
{
  "files": 24,
  "sprites": 156,
  "palettes": 12,
  "animations": 28,
  "dimensions": {
    "8x8": 42,
    "16x16": 89,
    "32x32": 18,
    "other": 7
  },
  "colors": {
    "average_per_sprite": 6.2,
    "most_common": ["black", "white", "skin"]
  }
}
```

## Use Cases

- **Corpus analysis**: Understand patterns in sprite collections
- **Training data audit**: Verify AI training data quality
- **Project metrics**: Track sprite counts and dimensions
- **Documentation**: Generate statistics for project READMEs

## See Also

- [explain](explain.md) - Detailed explanation of single file
- [validate](validate.md) - Check files for errors
- [diff](diff.md) - Compare two files