minecraft-skin-preprocessing

A Minecraft skin preprocessing Python script.

Features

• Convert legacy 64x32 skins to modern 64x64 format.
• Convert regular (steve) skin to slim (alex) and vice versa.
• Swap layer2 and layer1 for skins.
• Swap layer2 and layer1 twice to remove invalid areas.
• Remove specified layer (1 or 2) for skins.
• Process skins from Base64-encoded strings.
• Batch processing of skins in folders.
• Customizable output folder for converted skins.
• Option to overwrite existing files.
• Skin type detection (regular or slim).
• Pixels and transparency detection in specific regions.

---

Update

• 2025-11-11: Add pixel and transparency detection in specific regions.
• 2025-11-4: refactor code.
• 2025-11-1: Add support for skin convert between regular and slim (steve and alex).
• 2025-10-30: Add function for skin type detection (steve or alex).
• 2025-10-29: Initial release.

---

Installation

Install the package using pip:

pip install mcskinprep

---

Usage

Command Line Interface

The package provides a command line interface for easy skin preprocessing.

Arguments

• input: Input file or folder path (optional).
• -c, --convert: Convert 64x32 skins to 64x64 format.
• -i, --input-folder: Specify the input folder containing skins.
• -o, --output-folder: Specify the output folder for processed skins or output jsonl.
• -t, --type: Specify the source skin type (steve or alex) for conversion.
• -s, --swap-layer2-to-layer1: Swap layer2 to layer1 for skins.
• -ss, --twice-swap-layer2-to-layer1: Swap layer2 and layer1 twice to remove invalid areas.
• -rm, --remove-layer: Remove specified layer (1 or 2) for skins.
• -to, --target-type: Convert skin between regular (steve) and slim (alex) types.
• -b, --base64: Process Base64-encoded skin images.
• -dp, --detect-properties: Detect properties (skintype, pixels, transparency) , all for detect all properties.
• -dp_layer, --detect-properties-layer: Layer for detect properties (e.g., 1, 2, 1 2) default is 1.
• -dp_region, --detect-properties-region: Regions for detect properties (e.g., head, body, right_arm), None for all regions.
• -dp_base64, --detect-properties-base64: Save detect results in base64 format in jsonl file.
• --overwrite: Overwrite existing files.
• -h, --help: Show help message.
• -v, --version: Show version information.

Examples

---

New examples

Detect skin type (regular or slim):

mcskinprep old_skin.png -dp skintype

Detect skin layer pixels in layer 1(result save in xx_all_l1_has_pixels.jsonl):

mcskinprep old_skin.png -dp pixels

Detect skin specific region pixels in layer 1 (save in xx_h_l1_has_pixels.jsonl):

mcskinprep old_skin.png -dp pixels -dp_region head  -dp_layer 1

Detect skin layer transparency(save in xx_hra_l1_has_transparency.jsonl):

mcskinprep old_skin.png -dp transparency -dp_region head right_arm -dp_layer 1

---

Convert format of a single skin (64x32 to 64x64)

mcskinprep -c old_skin.png

Convert all skins in a folder

mcskinprep -c -i skins_folder

Convert with a custom output folder

mcskinprep -c -i old_skins -o new_skins

Convert and overwrite existing files

mcskinprep -c -i skins_folder --overwrite

Swap layer2 and layer1 for a single skin

mcskinprep -s old_skin.png

Swap layer2 and layer1 twice (to remove invalid areas)

mcskinprep -ss old_skin.png

Remove layer2 from a skin

mcskinprep -rm 2 old_skin.png

Convert skin type (steve to alex or vice versa)

mcskinprep -to alex old_skin.png
mcskinprep -to steve old_skin.png

Convert skin from a Base64 string

mcskinprep -c -b base64_skin_string

Python API

The package also provides a Python API for programmatic skin preprocessing.

Examples

usage of core tools

from mcskinprep import MCSkinTools, MCSkinType
from PIL import Image

# Create tools instance
tools = MCSkinTools()

# Load an image
img = Image.open("skin.png")

# Convert 64x32 to 64x64
converted_img = tools.convert_skin_64x32_to_64x64(img)

# Detect skin type
skin_type_detector = MCSkinType()
skin_type = skin_type_detector.auto_detect_skin_type(img)
print(f"Detected skin type: {skin_type}")

# convert skin type (steve to alex or vice versa)
converted_img = tools.convert_skin_type(img, target_type="alex")
# or
converted_img = tools.steve_to_alex(img)

# Swap layers
swapped_img = tools.swap_skin_layer2_to_layer1(img)

# Remove layer
layer_removed_img = tools.remove_layer(img, layer_index=1)

# Save results
converted_img.save("converted_skin.png")

usage of file processor

from mcskinprep import MCSkinFileProcessor

# Create processor instance
processor = MCSkinFileProcessor()

# Convert a single 64x32 skin to 64x64
processor.convert_skin_64x32_to_64x64("old_skin.png", "new_skin.png")

# Swap layers in a skin
processor.swap_skin_layer2_to_layer1("skin.png", "swapped_skin.png")

# Swap layers twice to remove invalid areas
processor.twice_swap_skin_layers("skin.png", "clean_skin.png")

# Remove a specific layer
processor.remove_layer("skin.png", "no_layer1_skin.png", layer_index=1)

# Batch process skins in a folder
processor.batch_convert_folder(
    convert_func=processor.convert_skin_64x32_to_64x64,
    input_folder="input_skins/",
    output_folder="output_skins/",
    overwrite=False
)

# Detect wheather head region in layer 1 has transparent pixels in a folder
batch_detect_folder(
     detect_func=processor.detect_region_transparency, 
     input_folder="input_skins/",
     output_folder="output_skins/",
     regions=["head"],
     layers=[1], 
     overwrite=False
)

License

This project is licensed under the MIT License.