Skip to content

Commit 33f8219

Browse files
CodeRandomMCCodeRandomMC
committed
Enhance README for Pixel2CPP with comprehensive usage guide, key features, and supported formats. Updated quick start instructions and added detailed sections on drawing tools, image importing, and Arduino code generation. Improved overall organization and clarity for better user experience.
1 parent 866a837 commit 33f8219

File tree

1 file changed

+262
-53
lines changed

1 file changed

+262
-53
lines changed

‎README.md‎

Lines changed: 262 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,293 @@
11
# Pixel2CPP
22

3-
A browser-based pixel editor that exports Arduino-ready C++ code. Create pixel art and get optimized code for:
3+
**Create pixel art and export Arduino-ready C++ code instantly**
44

5-
- **1-bit packed bytes** for SSD1306 OLED displays (Adafruit_GFX drawBitmap)
6-
- **RGB565 16-bit values** for color TFT displays (ST7735/ILI9341/etc.)
7-
- **RGB24 24-bit values** for ESP32/high-memory color displays
8-
- **RGB332 8-bit values** for low-memory color displays (SSD1331)
9-
- **4-bit grayscale** for e-ink/EPD displays with 16 gray levels
5+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6+
[![Made by CodeRandom](https://img.shields.io/badge/Made%20by-CodeRandom-blue)](https://github.com/coderandom)
107

11-
## Features
8+
Pixel2CPP is a browser-based pixel art editor designed for Arduino and embedded display development. Draw your sprites, icons, and graphics, then export them as optimized C++ arrays ready to use with popular display libraries like Adafruit_GFX.
129

13-
- 🎨 Real-time pixel editor with drawing tools
14-
- 🔄 Undo/redo functionality
15-
- 🖼️ Image import with automatic scaling
16-
- 📐 Grid overlay and zoom controls
17-
- 🪞 Mirror drawing modes
18-
- 🧪 Built-in test suite for validation
19-
- 📱 Responsive design with Tailwind CSS
10+
🎮 **[Try it live](https://your-domain.com)** | 📖 **[Documentation](#usage-guide)** | 🐛 **[Report Issues](https://github.com/your-username/pixel-to-cpp/issues)**
2011

21-
## Quick Start
12+
![Pixel2CPP Screenshot](screenshot.png)
2213

23-
1. Install dependencies:
24-
```bash
25-
npm install
26-
```
14+
## ✨ Key Features
2715

28-
2. Start the development server:
29-
```bash
30-
npm run dev
31-
```
16+
- 🎨 **Intuitive Pixel Editor** - Draw with pen, erase, fill, and eyedropper tools
17+
- 🔄 **Smart Export Formats** - Supports 6 different display formats with optimized data structures
18+
- 🖼️ **Image Import** - Load existing images and convert them to pixel art
19+
- 📐 **Professional Tools** - Grid overlay, zoom, mirror drawing, undo/redo
20+
- 🧪 **Built-in Testing** - Validate your exports with comprehensive format tests
21+
- 📱 **Works Everywhere** - Browser-based, no installation required
22+
- ⚡ **Instant Code** - Generate complete Arduino sketches, not just data arrays
3223

33-
3. Open your browser to the local development URL (usually `http://localhost:5173`)
24+
## 🚀 Quick Start
3425

35-
## Usage
26+
### Using the Online Version (Recommended)
27+
1. Open [Pixel2CPP](https://your-domain.com) in your browser
28+
2. Set your canvas size to match your display
29+
3. Choose your export format (see [Supported Formats](#supported-formats))
30+
4. Start drawing your pixel art
31+
5. Click "Generate Code" to see the Arduino code
32+
6. Copy the code or download as `.h` file
3633

37-
1. **Set canvas size** - Choose dimensions suitable for your display
38-
2. **Select format** - Choose from 1-bit OLED, RGB565 TFT, RGB24, RGB332, or 4-bit grayscale
39-
3. **Draw your sprite** - Use pen, erase, fill, or eyedropper tools
40-
4. **Generate code** - Click "Generate Code" to see complete Arduino setup
41-
5. **Export** - Click "Export .h" to download Arduino-ready header file
42-
6. **Test** - Run built-in tests to validate all format conversions
34+
### Running Locally
35+
```bash
36+
# Clone the repository
37+
git clone https://github.com/your-username/pixel-to-cpp.git
38+
cd pixel-to-cpp
4339

44-
## Export Formats
40+
# Install dependencies
41+
npm install
4542

46-
### 1-bit (SSD1306 OLED)
43+
# Start development server
44+
npm run dev
45+
46+
# Open http://localhost:5173 in your browser
47+
```
48+
49+
## 📖 Usage Guide
50+
51+
### 1. Setting Up Your Canvas
52+
53+
**Canvas Size**: Set width and height to match your display dimensions
54+
- For SSD1306 OLED: 128x64 or 128x32
55+
- For small TFT displays: 128x128, 160x80, 240x135
56+
- For larger displays: 320x240, 480x320
57+
58+
**Draw Mode**: Choose the format that matches your display:
59+
- **1-bit Horizontal/Vertical**: For monochrome OLED displays (SSD1306, SH1106)
60+
- **RGB565**: For color TFT displays (ST7735, ILI9341, ST7789)
61+
- **RGB888 24-bit**: For high-quality displays with enough memory
62+
- **RGB888 32-bit**: For displays supporting alpha transparency
63+
- **1-bit Alpha**: For transparency masks
64+
65+
### 2. Drawing Tools
66+
67+
| Tool | Description | Usage |
68+
|------|-------------|--------|
69+
| **Pen** | Draw pixels with primary color | Left-click to draw |
70+
| **Erase** | Remove pixels (set to transparent) | Left-click to erase |
71+
| **Fill** | Flood fill areas with color | Left-click to fill area |
72+
| **Eyedropper** | Pick colors from the canvas | Left-click to sample color |
73+
74+
**Pro Tips:**
75+
- Right-click with any tool uses the secondary color
76+
- Enable "Mirror X" or "Mirror Y" for symmetrical drawing
77+
- Use the zoom slider for detailed work
78+
- Toggle grid overlay for precise pixel placement
79+
80+
### 3. Working with Colors
81+
82+
- **Primary Color**: Used with left-click
83+
- **Secondary Color**: Used with right-click
84+
- **Color Picker**: Click the color squares to choose new colors
85+
- **Swap Button**: Quickly exchange primary and secondary colors
86+
87+
### 4. Importing Images
88+
89+
1. Click "Upload Image" in the header
90+
2. Select any image file (PNG, JPG, GIF, etc.)
91+
3. The image will be automatically:
92+
- Scaled to fit your canvas
93+
- Centered on the canvas
94+
- Converted to your chosen format (e.g., 1-bit for OLED displays)
95+
96+
### 5. Generating Arduino Code
97+
98+
1. **Name Your Asset**: Enter a name in the text field (e.g., "player_sprite")
99+
2. **Choose Output Format**:
100+
- **Arduino Code**: Complete sketch with setup() and display functions
101+
- **Plain Bytes**: Just the data array with basic code
102+
- **Single Bitmap**: Minimal array declaration
103+
- **GFX Bitmap Font**: For use with Adafruit GFX font system
104+
3. **Generate**: Click "Generate Code" to see the result
105+
4. **Copy or Download**: Use "Copy Code" or "Export .h" buttons
106+
107+
## 🖥️ Supported Formats
108+
109+
### 1-Bit Monochrome (SSD1306, SH1106)
110+
**Best for**: OLED displays, e-ink, simple graphics
111+
**Memory usage**: 1 bit per pixel
112+
```cpp
113+
// 64x32 sprite = 256 bytes
114+
const uint8_t sprite_bits[] PROGMEM = { 0xFF, 0x81, 0x81, 0xFF, ... };
115+
display.drawBitmap(x, y, sprite_bits, 64, 32, WHITE);
116+
```
117+
118+
### RGB565 16-bit (ST7735, ILI9341, ST7789)
119+
**Best for**: Color TFT displays, good balance of quality and memory
120+
**Memory usage**: 2 bytes per pixel
121+
```cpp
122+
// 32x32 sprite = 2048 bytes
123+
const uint16_t sprite_pixels[] PROGMEM = { 0xF800, 0x07E0, 0x001F, ... };
124+
tft.drawRGBBitmap(x, y, sprite_pixels, 32, 32);
125+
```
126+
127+
### RGB888 24-bit (ESP32, High-Memory Displays)
128+
**Best for**: High-quality color displays with sufficient memory
129+
**Memory usage**: 3 bytes per pixel
47130
```cpp
48-
const uint8_t sprite_bits[] PROGMEM = { 0xAA, 0x55, ... };
49-
display.drawBitmap(x, y, sprite_bits, width, height, 1);
131+
// 32x32 sprite = 3072 bytes
132+
const uint8_t sprite_pixels[] PROGMEM = { 255, 0, 0, 0, 255, 0, ... };
133+
// Convert to RGB565 on-the-fly for display
50134
```
51135
52-
### RGB565 (ST7735/ILI9341 TFT)
136+
### RGB888 32-bit with Alpha
137+
**Best for**: Sprites with transparency, compositing
138+
**Memory usage**: 4 bytes per pixel
53139
```cpp
54-
const uint16_t sprite_pixels[] PROGMEM = { 0xF800, 0x07E0, ... };
55-
// Complete setup with tft.setAddrWindow() and fast pixel writing
140+
// 32x32 sprite = 4096 bytes
141+
const uint8_t sprite_pixels[] PROGMEM = { 255, 0, 0, 255, 0, 255, 0, 128, ... };
142+
// Includes alpha channel for transparency
56143
```
57144

58-
### RGB24 (ESP32/High Memory)
145+
### 1-Bit Alpha Maps
146+
**Best for**: Transparency masks, sprite masks
147+
**Memory usage**: 1 bit per pixel
59148
```cpp
60-
const uint8_t sprite_pixels[] PROGMEM = { 0xFF, 0x00, 0x00, ... };
61-
// Full 24-bit color for high-quality displays
149+
const uint8_t sprite_alpha[] PROGMEM = { 0xFF, 0x00, 0x18, 0x7E, ... };
150+
// Use for masking or transparency effects
62151
```
63152
64-
### RGB332 (SSD1331/Low Memory)
153+
## 🎯 Display Library Examples
154+
155+
### SSD1306 OLED (128x64)
65156
```cpp
66-
const uint8_t sprite_pixels[] PROGMEM = { 0xE0, 0x1C, 0x03, ... };
67-
// 8-bit color (3-3-2 bits for R-G-B)
157+
#include <Adafruit_GFX.h>
158+
#include <Adafruit_SSD1306.h>
159+
#include "my_sprite.h" // Generated by Pixel2CPP
160+
161+
Adafruit_SSD1306 display(128, 64, &Wire, -1);
162+
163+
void setup() {
164+
display.begin(SSD1306_SWITCHCAPVCC, 0x3C);
165+
display.clearDisplay();
166+
167+
// Draw your sprite at position (32, 16)
168+
display.drawBitmap(32, 16, my_sprite_bits, my_sprite_w, my_sprite_h, WHITE);
169+
display.display();
170+
}
68171
```
69172

70-
### 4-bit Grayscale (E-ink/EPD)
173+
### ST7735 TFT (128x128)
71174
```cpp
72-
const uint8_t sprite_pixels[] PROGMEM = { 0x0F, 0xA5, ... };
73-
// 16 grayscale levels, 2 pixels per byte
175+
#include <Adafruit_GFX.h>
176+
#include <Adafruit_ST7735.h>
177+
#include "my_sprite.h"
178+
179+
#define TFT_CS 10
180+
#define TFT_RST 9
181+
#define TFT_DC 8
182+
183+
Adafruit_ST7735 tft = Adafruit_ST7735(TFT_CS, TFT_DC, TFT_RST);
184+
185+
void setup() {
186+
tft.initR(INITR_BLACKTAB);
187+
tft.fillScreen(ST77XX_BLACK);
188+
189+
// Draw RGB565 sprite
190+
drawSprite(32, 32);
191+
}
192+
193+
void drawSprite(int16_t x, int16_t y) {
194+
tft.startWrite();
195+
tft.setAddrWindow(x, y, my_sprite_w, my_sprite_h);
196+
for (uint16_t i = 0; i < my_sprite_w * my_sprite_h; i++) {
197+
tft.writePixel(pgm_read_word(&my_sprite_pixels[i]));
198+
}
199+
tft.endWrite();
200+
}
74201
```
75202
76-
## Development
203+
## 🔍 Testing Your Exports
204+
205+
Pixel2CPP includes a comprehensive test suite to validate your exports:
206+
207+
1. Switch to the **"Tests"** tab
208+
2. Click **"Run Tests"**
209+
3. Verify all format conversions pass
210+
211+
The tests validate:
212+
- ✅ 1-bit horizontal and vertical packing
213+
- ✅ RGB565 color conversion accuracy
214+
- ✅ RGB24 and RGB332 format correctness
215+
- ✅ 4-bit grayscale conversion
216+
- ✅ Alpha channel handling
217+
218+
## 🛠️ Tips & Best Practices
219+
220+
### Memory Optimization
221+
- **Use 1-bit** for simple icons and text (smallest memory footprint)
222+
- **Use RGB565** for colorful sprites on TFT displays (good balance)
223+
- **Use RGB888** only when you have plenty of memory (ESP32, etc.)
224+
225+
### Performance Tips
226+
- **Horizontal packing** is faster for most displays
227+
- **Vertical packing** works better for column-oriented displays
228+
- **Pre-load sprites** in PROGMEM to save RAM
229+
- **Use setAddrWindow()** for fastest RGB565 drawing
230+
231+
### Design Guidelines
232+
- Design at actual pixel size for crisp results
233+
- Use high contrast for 1-bit displays
234+
- Test with your actual hardware - emulation isn't perfect
235+
- Keep sprites small for Arduino Uno/Nano (limited memory)
236+
237+
### Common Issues
238+
- **White export**: Check your draw mode matches your display
239+
- **Wrong colors**: Verify color format (RGB565 vs RGB888)
240+
- **Garbled display**: Check byte order and display library compatibility
241+
- **Memory errors**: Reduce sprite size or use more efficient format
242+
243+
## 📈 Updates & Changelog
244+
245+
### Version 1.2.0 (Latest)
246+
- ✨ Added RGB888 32-bit format with alpha channel support
247+
- ✨ Improved image import with automatic format conversion
248+
- ✨ Enhanced test suite with more comprehensive validation
249+
- 🐛 Fixed grid rendering on high-DPI displays
250+
- 🐛 Improved memory handling for large canvases
251+
- 🎨 Updated UI with better tool organization
252+
253+
### Version 1.1.0
254+
- ✨ Added 1-bit alpha map export format
255+
- ✨ Added GFX Bitmap Font output format
256+
- ✨ Implemented mirror drawing modes (X and Y axis)
257+
- ✨ Added eyedropper tool for color picking
258+
- 🐛 Fixed undo/redo system edge cases
259+
- 🎨 Improved responsive design for mobile devices
260+
261+
### Version 1.0.0
262+
- 🎉 Initial release
263+
- ✨ Core pixel editor with pen, erase, fill tools
264+
- ✨ Support for 1-bit, RGB565, RGB24, RGB332, and 4-bit grayscale
265+
- ✨ Image import functionality
266+
- ✨ Arduino code generation
267+
- ✨ Built-in testing framework
268+
269+
### Planned Features
270+
- 🔮 Animation frame support for sprites
271+
- 🔮 Palette-based color modes
272+
- 🔮 Advanced dithering algorithms
273+
- 🔮 Batch export multiple sprites
274+
- 🔮 Custom display library templates
275+
276+
## 🤝 Contributing
277+
278+
Found a bug or have a feature request? We'd love to hear from you!
279+
280+
- 🐛 **Report bugs**: [Open an issue](https://github.com/your-username/pixel-to-cpp/issues)
281+
- 💡 **Request features**: [Start a discussion](https://github.com/your-username/pixel-to-cpp/discussions)
282+
- 🔧 **Submit pull requests**: Fork, branch, and PR
283+
- 📖 **Improve docs**: Help make this guide even better
284+
285+
## 📄 License
286+
287+
MIT License - see [LICENSE](LICENSE) file for details.
77288
78-
- **Build**: `npm run build`
79-
- **Preview**: `npm run preview`
80-
- **Lint**: `npm run lint`
289+
Made with ❤️ by **CodeRandom** for the Arduino and embedded community.
81290
82-
## License
291+
---
83292
84-
MIT License - feel free to use for your projects!
293+
**Need help?** Check out our [examples](examples/) directory or join the [community discussions](https://github.com/your-username/pixel-to-cpp/discussions).

0 commit comments

Comments
 (0)