⚠️ WORK IN PROGRESS: This project is currently under active development and is not yet ready for production use.

Convert images into pixel art guides with color reference numbers for easy crafting.

Pixeld is a versatile pixel art guide generator that converts any image into a numbered pixel art pattern. It's perfect for cross-stitch, Perler beads, LEGO creations, quilt patterns, or digital pixel art.

⚠️ This project is currently in BETA stage. While most features are implemented, you may encounter bugs or incomplete functionality. Use at your own risk and please report any issues you find.

• Multiple Processing Modes:

  • Numbered Outline: Displays each pixel with a number corresponding to its color
  • Colored Numbers: Shows colored pixels with numbers for reference
  • Real Colors: Displays the actual colors with numbers

• Customization Options:

  • Adjustable output size (8x8, 16x16, 32x32, 64x64, or custom dimensions)
  • Color reduction with smart clustering algorithms
  • Optional dithering for smoother transitions
  • Adjustable grid settings (thickness, color, visibility)
  • Multiple pixel shapes (square, circle, diamond)
  • Background color and transparency options
  • Image enhancement (contrast, brightness, saturation)

• Multiple Export Formats:

  • PNG images for digital use
  • SVG vector graphics for high-quality printing
  • Template exports for physical crafting projects

• Multiple User Interfaces:

  • Native desktop application with Tkinter
  • Web interface with Streamlit
  • RESTful API with FastAPI

1. Easy Install: Run the installer script:

   scripts\install_windows.bat

2. Using pre-built executable:

   • Download the latest release
   • Extract and run Pixeld.exe

You can run Pixeld in Docker:

# Build the image
docker build -t pixeld .

# Run the container
docker run -p 8501:8501 pixeld

Alternatively, use Docker Compose:

docker-compose up

1. Clone the repository:

   git clone https://github.com/1ordo/pixeld.git
   cd pixeld

2. Create a virtual environment:

   python -m venv venv

3. Activate the virtual environment:

   • Windows: venv\Scripts\activate
   • macOS/Linux: source venv/bin/activate

4. Install dependencies:

   pip install -r requirements.txt

Run the Tkinter UI:

python pixel_helper_ui.py

Run the Streamlit web app:

python scripts/run_streamlit.py

Then open your browser to http://localhost:8501

Run the FastAPI server:

python scripts/run_api.py

API documentation will be available at http://localhost:8000/docs

The RESTful API provides the following endpoints:

• GET /: API information
• GET /settings: Get default processing settings
• POST /settings: Save custom settings
• POST /process: Process an image and receive the resulting pixel art
• POST /process_info: Process an image and get information about colors and pixel count
• GET /health: Health check endpoint

To build a standalone executable:

scripts\build_exe.bat

The executable will be created in the dist folder.

pixeld/
│
├── pixeld/             # Core package
│   ├── __init__.py
│   ├── api/            # FastAPI implementation
│   ├── core/           # Core processing logic
│   ├── ui/             # Tkinter UI
│   └── web/            # Streamlit web app
│
├── scripts/            # Helper scripts
│   ├── build_exe.bat
│   ├── install_windows.bat
│   ├── run_api.py
│   ├── run_streamlit.py
│   └── run_tkinter.py
│
├── requirements.txt    # Dependencies
├── pixel_helper_ui.py  # Main entry point
├── Dockerfile          # Docker configuration
├── docker-compose.yml  # Docker Compose configuration
└── README.md

• Core language
• Image processing
• Data manipulation
• Color clustering
• Desktop UI
• RESTful API
• Web UI
• Containerization
• Executable packaging

Contributions to Pixeld are welcome and encouraged! Here's how you can contribute:

1. Fork the repository: Create your own fork of the project
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin feature/your-feature-name
5. Submit a pull request: Create a PR to the main repository

• Follow the existing code style and naming conventions
• Write clear, descriptive commit messages
• Update documentation as needed
• Add tests for new features
• Make sure all tests pass before submitting your PR

By contributing to this project, you agree that your contributions will be licensed under the same proprietary license as the original project. All contributors must sign a Contributor License Agreement (CLA) confirming this understanding.

This project is licensed under a proprietary license - see the LICENSE file for details.

PRIVATE USE ONLY: This software is provided for private use only. Redistribution in any form is strictly prohibited without prior written permission from the copyright holder.