🎨 Minecraft Pixel Art Builder

Turn any image into a Minecraft pixel art wall in seconds!
Just upload an image, click a button, and watch it build instantly.

---

---

📖 Table of Contents

• Quick Start
• How It Works
• Installation
• Step-by-Step Guide
• In-Game Instructions
• Tips & Tricks
• Troubleshooting
• Reference

---

⚡ Quick Start

# 1. Install dependencies
pip install pillow pyautogui pyperclip

# 2. Run the tool
python image.py

# 3. In Minecraft
/reload
/function your_art:build

That's it! Your pixel art appears instantly ✨

---

🔧 How It Works

High-Level Architecture

📷 Image → 🎨 Color Matching → 📝 Command Generation → 📦 Datapack → ⛏️ Minecraft

Core Components

1. 🖼️ Image Processor

• Resizes using NEAREST interpolation (preserves pixel edges)
• Extracts RGB values from each pixel
• Stores grid in memory: block_grid[y][x] = block_name

2. 🎯 Color Matcher

• Loads CSV with min/max hex ranges
• Calculates block color as average of range
• Uses Euclidean distance: d² = (r1-r2)² + (g1-g2)² + (b1-b2)²
• Caches results for blazing-fast O(1) lookup

3. ⚡ Command Generator

• Scans rows bottom→top (Y-axis flip)
• Detects consecutive same-color pixels → creates horizontal runs
• Outputs /fill for runs (≥2 blocks) or /setblock for singles
• Reduces 50,000 block commands to ~5,000!

4. 📦 Datapack Builder

• Splits commands into 500 per file
• Creates batch chain: build → batch_0 → batch_1 → ...
• Generates pack.mcmeta with pack_format: 105
• Each file calls next in sequence to prevent stack overflow

Performance Metrics

Metric	Value
⚡ Blocks/second	50,000+
📉 Command reduction	10×
📐 Max resolution	2048×2048
📄 File limit	500 commands/file
⏱️ Build time	<1 second

---

📥 Installation

###I have put a also a exe of tool, You can get it in release.

1. Install Python

Download from python.org (version 3.10 or newer)

2. Install Required Libraries

Open Command Prompt (CMD) and run:

pip install pillow pyautogui pyperclip

3. Download the Tool

Place these two files in the same folder:

• image.py - The main program
• blocks.csv - Block color data

💡 Pro Tip: Create a shortcut to run from anywhere:

doskey mcimage=python "D:\YourFolder\image.py"

---

🚀 Step-by-Step Guide

Step 1: Launch the Tool

Double-click image.py or run:

python image.py

Step 2: Upload Your Image

Click "Upload Image" and select your picture (PNG, JPG, BMP, or GIF).

Step 3: Set Resolution

• Width: How wide you want the wall (recommended: 64-200)
• Height: Auto-calculates to keep proportions

Step 4: Set Position

• Start X / Start Z: Where the wall begins
• Bottom Y: Height level (recommended: 100 for easy viewing)
• Facing: Choose South, North, East, or West

💡 Tip: Use Y=100 and Facing=South for the easiest viewing.

Step 5: Choose Background

Pick a color for empty areas (black concrete works great).

Step 6: Generate the Datapack

Click "Start Building" → Select "Generate Datapack"

• Enter a name (lowercase, no spaces)
• Example: cat_art or mural
• Select your world's datapacks folder

📁 Path: .minecraft/saves/YourWorld/datapacks/

---

---

🎮 In-Game Instructions

1. Load the Datapack

Open your world and run:

/reload

2. Build Your Art

Run this command (replace cat_art with your datapack name):

/function cat_art:build

Done! Your pixel art appears instantly ✨

3. If It Stops Midway

Sometimes Minecraft pauses large builds. Just run:

/function cat_art:build

Again and it continues right where it left off.

---

💡 Tips & Tricks

For Best Results

• Use high-contrast images (simple designs work better)
• 64×64 is a good starting size
• Y=100 keeps it above ground
• Facing=South gives the best view

Save Time

• Save your setup as a JSON file for quick reuse
• Click "Save JSON" after processing an image
• Click "Load JSON" to restore it later

Coordinate Reference

Facing	X	Y	Z
South	x0 + col	y0 + (h - 1 - row)	z0
North	x0 + col	y0 + (h - 1 - row)	z0 - 1
East	x0 + 1	y0 + col	z0 + row
West	x0 - 1	y0 + col	z0 + row

---

⚠️ Troubleshooting

Issue	Solution
"CSV file not found"	Make sure blocks.csv is in the same folder as image.py
Datapack doesn't load	Run /reload • Check folder name (must be lowercase) • Verify correct datapacks folder
Colors look wrong	Tool matches closest available block. Some colors aren't perfect but very accurate!
Image is upside down	Check your Facing setting. South usually works best.
Missing blocks/holes	Disable "Use /fill for horizontal runs" in settings

---

📋 Reference

Dependencies

Library	Purpose
Pillow	Image processing
PyAutoGUI	Keyboard automation
Pyperclip	Clipboard access

CSV Format

block_name,min_hex,max_hex
minecraft:stone,7a7a7a,8e8e8e
minecraft:grass_block,5a8a2a,6e9e3e
minecraft:black_concrete,121212,242424

File Structure

Your datapack will look like this:

cat_art/
├── pack.mcmeta
└── data/
    └── cat_art/
        └── functions/
            ├── build.mcfunction      ← Entry point
            ├── batch_0.mcfunction    ← Calls build_0 → build_4
            ├── batch_1.mcfunction    ← Calls build_5 → build_9
            ├── build_0.mcfunction    ← 500 commands
            ├── build_1.mcfunction    ← 500 commands
            └── ...

Example Command

Builds a 100×100 wall at X=0, Y=100, Z=0, facing South:

/function cat_art:build

---

🎉 That's It!

📤 Upload → ⚙️ Generate → 🔄 /reload → ⚡ /function yourname:build

Your pixel art is ready! 🎨

---

Made for Minecraft Java Edition 1.20+