pngv 0.1.0

A library and CLI tool for converting PNG images to color matrices and reconstructing them as PNG or SVG
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

# pngv

[![Crates.io](https://img.shields.io/crates/v/pngv.svg)](https://crates.io/crates/pngv)
[![Documentation](https://docs.rs/pngv/badge.svg)](https://docs.rs/pngv)
[![License](https://img.shields.io/crates/l/pngv.svg)](https://github.com/vmaspad/pngv#license)

A Rust library and CLI tool for converting PNG images to color matrices and reconstructing them as PNG or SVG files with 1x1 vector pixels.

## Features

- **Encode**: Convert PNG images to JSON color matrices (`.pngv` format) where each cell contains a hex color with alpha channel (`#RRGGBBAA`)
- **Decode**: Reconstruct PNG images from `.pngv` files with 1x1 pixels
- **SVG Export**: Generate SVG files with 1x1 vector rectangles from `.pngv` files
- Simple CLI with automatic output path generation
- Can be used as a library in your own projects

## Installation

### As a CLI tool

```bash
cargo install pngv
```

### As a library

Add this to your `Cargo.toml`:

```toml
[dependencies]
pngv = "0.1"
```

## CLI Usage

The CLI requires a command and an input file. The output path is optional and will be auto-generated if not provided.

### Basic syntax

```bash
pngv <COMMAND> <INPUT> [OUTPUT]
```

### Commands

#### Encode: PNG → .pngv

Convert a PNG image to a color matrix:

```bash
pngv encode image.png
# Creates: image.pngv

pngv encode input.png output.pngv
# Creates: output.pngv
```

#### Decode: .pngv → PNG

Reconstruct a PNG from a color matrix:

```bash
pngv decode image.pngv
# Creates: image.png

pngv decode input.pngv output.png
# Creates: output.png
```

#### SVG: .pngv → SVG

Generate an SVG with 1x1 vector pixels:

```bash
pngv svg image.pngv
# Creates: image.svg

pngv svg input.pngv output.svg
# Creates: output.svg
```

## Library Usage

```rust
use pngv::{encode_to_pngv, decode_from_pngv, decode_to_svg};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Encode a PNG to .pngv format
    encode_to_pngv("image.png", "image.pngv")?;
    
    // Decode back to PNG
    decode_from_pngv("image.pngv", "output.png")?;
    
    // Export to SVG
    decode_to_svg("image.pngv", "output.svg")?;
    
    Ok(())
}
```

## .pngv Format

The `.pngv` file is a JSON array of arrays, where each element represents a pixel color:

```json
[
  ["#FF0000FF", "#00FF00FF", "#0000FFFF"],
  ["#FFFFFFFF", "#000000FF", "#808080FF"]
]
```

- Each row represents a horizontal line of pixels (top to bottom)
- Each color is in `#RRGGBBAA` format (Red, Green, Blue, Alpha in hexadecimal)
- Alpha channel is fully supported

## Use Cases

- **Pixel art editing**: Edit images as JSON matrices
- **Image analysis**: Process images as structured data
- **Vector conversion**: Convert pixel art to scalable SVG format
- **Data visualization**: Represent images as color data
- **Backup/versioning**: Store images in text-friendly format

## License

Licensed under either of:

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.