KTXStudio/MinecraftSkinImg-To-Img

Minecraft HD Skin Generator (ViT-B/16 Core)

Ce modèle utilise l'architecture Vision Transformer (ViT-B/16) de Google modifiée pour convertir des rendus 3D ou des images de personnages en textures plates de skins Minecraft Haute Définition (128x128 pixels).

Grâce aux mécanismes d'attention spatiale du Transformer, le modèle est capable de comprendre la structure géométrique d'un personnage (tête, bras, jambes) pour cartographier intelligemment les couleurs et les formes sur le patron 2D du jeu, évitant ainsi le bruit pixelisé des architectures GAN classiques sur de petits datasets.

🚀 Fonctionnalités

• Entrée flexible : Gère n'importe quelle taille d'image (redimensionnée automatiquement en 224x224 pour ViT).
• Sortie Haute Définition : Génère un patron propre en 128x128 pixels.
• Rendu Pixel-Art : Préservation des contrastes nets via un échantillonnage adapté.

💻 Utilisation (Inférence)

Pour utiliser ce modèle directement dans vos scripts Python avec PyTorch, copiez le code ci-dessous. Assurez-vous d'avoir téléchargé le fichier des poids vit_minecraft_core.pth.

import torch
import torch.nn as nn
from torchvision import transforms, models
from PIL import Image

# 1. Définition de l'architecture
class ViTSkinGenerator(nn.Module):
    def __init__(self, skin_size=128):
        super().__init__()
        vit = models.vit_b_16(pretrained=False)
        self.transformer_core = vit
        num_features = vit.heads.head.in_features
        self.transformer_core.heads = nn.Sequential(
            nn.Linear(num_features, 2048),
            nn.GELU(),
            nn.Dropout(0.1),
            nn.Linear(2048, 4096),
            nn.GELU(),
            nn.Linear(4096, 3 * skin_size * skin_size),
            nn.Sigmoid()
        )
        
    def forward(self, x):
        out = self.transformer_core(x)
        out = out.view(-1, 3, 128, 128)
        return out

# 2. Pipeline de génération
def generate_skin(image_path, weights_path, output_path="skin_output.png"):
    device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
    
    # Chargement du modèle
    model = ViTSkinGenerator().to(device)
    model.load_state_dict(torch.load(weights_path, map_location=device))
    model.eval()
    
    # Préparation de l'image
    img = Image.open(image_path).convert("RGB").resize((224, 224), Image.Resampling.LANCZOS)
    transform = transforms.Compose([
        transforms.ToTensor(),
        transforms.Normalize((0.5, 0.5, 0.5), (0.5, 0.5, 0.5))
    ])
    tensor_in = transform(img).unsqueeze(0).to(device)
    
    # Inférence
    with torch.no_grad():
        tensor_out = model(tensor_in).squeeze(0).cpu()
    
    # Sauvegarde au format Pixel-Art
    tensor_out = torch.clamp(tensor_out, 0, 1)
    skin_pil = transforms.ToPILImage()(tensor_out).resize((128, 128), Image.NEAREST)
    skin_pil.save(output_path)
    print(f"✨ Skin généré avec succès dans : {output_path}")

# Exemple d'appel :
# generate_skin("votre_personnage.jpg", "vit_minecraft_core.pth")

🏋️ Détails de l'entraînement

Le modèle a été entraîné par transfert d'apprentissage (Few-Shot Transfer Learning) sur un échantillon ciblé du dataset de rendu Minecraft :

• Dataset de base : zhoudoe23/minecraft-skins-1.1m-prerendered
• Taille de l'échantillon : 437 paires d'images (Rendu 3D $\leftrightarrow$ Skin plat)
• Optimiseur : AdamW (Learning Rate: 3e-4, Weight Decay: 1e-4)
• Fonction de perte : SmoothL1Loss (pour favoriser des blocs de couleurs homogènes propres au Pixel Art).

⚠️ Limitations & Améliorations futures

• Le modèle génère actuellement des textures sur 3 canaux (RGB). Pour une utilisation en jeu avec des zones transparentes complexes (couches secondaires de vêtements), un post-traitement de masquage de transparence (canal Alpha) peut être nécessaire.
• Conçu principalement pour des rendus de personnages centrés sur fond uni.

📄 Licence

Ce projet est distribué sous licence MIT. Vous êtes libre de l'utiliser, de le modifier et de le partager.