Metadata-Version: 2.4
Name: mc_skin_utils
Version: 0.1.1
Summary: Minecraft Skin Utilities
Author: EntropyDrop
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: Pillow
Requires-Dist: pyvista
Dynamic: license-file

# mc_skin_utils

A collection of utilities for Minecraft skin processing, cleaning, conversion, and 3D rendering.

## Installation

You can install this package locally or directly from the source.

```bash
pip install -e .
```

Once installed, it provides several global CLI tools for Minecraft skin manipulation.

---

## Command Line Tools

### 1. mc_skin_utils mc_render
Renders a Minecraft skin in 3D using PyVista. You can use it to preview skins interactively or save them as screenshots, complete with lighting, voxel-based secondary layers, and custom poses.

**Basic Usage:**
```bash
# Render a skin interactively in a window
mc_skin_utils mc_render skin.png --interact --light
```

**Save to File:**
```bash
# Save a 600x600 screenshot to output.png
mc_skin_utils mc_render skin.png --save output.png --output-size 600 600
```

**Advanced Usage:**
You can pose the character by defining rotations for the limbs and head.
```bash
# Render with custom rotations for head and arms, and enable lighting
mc_skin_utils mc_render skin.png \
  --rot-head 10 -20 0 \
  --rot-arm-left 0 0 -45 \
  --rot-arm-right 0 0 45 \
  --interact --light
```

**Options:**

*General & Output:*
- `skin_path` (positional): Path to the Minecraft skin image.
- `--interact`: Open an interactive GUI window instead of rendering off-screen.
- `--save <path>`: Save a screenshot to the specified file.
- `--output-size <width> <height>`: Set output image dimensions (default: `600 600`).
- `--bg <r> <g> <b>`: Set background color as RGB values from 0.0 to 1.0 (default: `0.0039 0.996 0.0039` / green).

*Rendering Styles:*
- `--flat`: Render the secondary (overlay/armor) layer as flat planes instead of full 3D voxels.
- `--ortho`: Use orthographic camera projection instead of perspective.
- `--wireframe`: Show wireframe black edges on the skin geometry.
- `--light`: Enable realistic lighting. If not set, rendering uses unlit flat texture shading.

*Lighting Configuration (Requires `--light`):*
- `--light-pos <x> <y> <z>`: Initial light position (default: `0 30 30`).
- `--light-intensity <float>`: Initial light intensity (default: `0.5`).

*Camera:*
- `--cam-front <x> <y> <z>`: Set the camera's front direction vector (default: `0.5 0.5 0.5`).

*Posing (Rotations & Positions):*
- `--rot-head <pitch> <yaw> <roll>`: Rotate the head (degrees).
- `--rot-arm-left <pitch> <yaw> <roll>`: Rotate the left arm.
- `--rot-arm-right <pitch> <yaw> <roll>`: Rotate the right arm.
- `--rot-leg-left <pitch> <yaw> <roll>`: Rotate the left leg.
- `--rot-leg-right <pitch> <yaw> <roll>`: Rotate the right leg.
- `--pos-head <x> <y> <z>`: Override head position.
- `--pos-body <x> <y> <z>`: Override body position.
- `--pos-arm-left <x> <y> <z>`: Override left arm position.
- `--pos-arm-right <x> <y> <z>`: Override right arm position.
- `--pos-leg-left <x> <y> <z>`: Override left leg position.
- `--pos-leg-right <x> <y> <z>`: Override right leg position.

---

### 2. mc_skin_utils clean_skins
Automatically cleans up artifact "extra" pixels on skin images (e.g. pixels that are drawn completely outside of the standard skin layout map). It processes all `.png` files found in a `skins` folder relative to the script.

**Usage:**
```bash
# Runs the cleaning process on the `skins` folder
mc_skin_utils clean_skins
```

*Note: You must have `skins/` folder and the mask images (`skin-mask.png`, `skin-decor-mask.png`) correctly set up for this command to process the images.*

---

### 3. mc_skin_utils ensure_skin64x64
Minecraft supports two skin formats: the legacy `64x32` format (where arms and legs are mirrored) and the modern `64x64` format (which supports independent textures for left and right limbs). 

This tool takes a legacy `64x32` skin and safely converts it to the modern `64x64` format by correctly duplicating and mirroring the limb textures.

**Usage:**
```bash
# Converts the skin and saves it as <name>_64x64.png by default
mc_skin_utils ensure_skin64x64 legacy_skin.png

# Specify a custom output path
mc_skin_utils ensure_skin64x64 legacy_skin.png -o modern_skin.png
```

---

## Development

If you'd like to build the project as a `.whl` or `.tar.gz` for PyPI distribution:
```bash
pip install build
python -m build
```

## Python API Usage

You can also import and use the core functions directly in your own Python projects.

### Rendering Skins in Python
```python
from mc_skin_utils.mc_render import load_skin, render_skin

# 1. Load the skin as a numpy array (automatically converts 64x32 to 64x64 internally)
skin_array = load_skin("path/to/skin.png")

# 2. Render and save the skin without opening a GUI
render_skin(
    skin_array,
    save_path="output.png",
    output_size=(800, 800),
    light=True,
    off_screen=True,            # Set to False to open an interactive window
    rot_args={
        "rot_head": (10, -20, 0),
        "rot_arm_right": (0, 0, 45),
        "rot_arm_left": (0, 0, -45)
    }
)
```

### Converting Legacy Skins in Python
```python
from mc_skin_utils.ensure_skin64x64 import convert_skin_64x32_to_64x64

# Converts a legacy 64x32 skin to modern 64x64 format
convert_skin_64x32_to_64x64("legacy_skin.png", "modern_skin.png")
```
