Clemylia/Iris-1.0

✨ Documentation du Modèle : Iris-1.0 (Clemylia)

Bienvenue dans la documentation d'Iris-1.0, un modèle de génération d'images C-VAE (Conditional Variational Autoencoder) spécialisé dans l'imagerie conceptuelle et artistique d'insectes.

---

🌟 Aperçu du Modèle

Caractéristique	Détail
Nom du Modèle	Iris-1.0
Auteur	Clemylia
Tâche Primaire	Génération d'images (Text-to-Image Conceptuel)
Domaine	Art Génératif, Biologie Conceptuelle
Output	Images floues et conceptuelles d'Abeilles et de Guêpes
Palette de Couleurs	Dominance de Bleu, Vert, Jaune, avec des accents discrets de Rouge ou Magenta foncé

Objectif : Générer des représentations abstraites d'hyménoptères en explorant des palettes chromatiques non photoréalistes, idéales pour l'art numérique conceptuel ou comme base pour le matting et les effets visuels.

---

⚙️ Architecture et Fonctionnement

Iris-1.0 est basé sur une architecture de Conditional Variational Autoencoder (C-VAE), ce qui permet un contrôle précis sur un attribut clé de l'image générée : la couleur dominante.

1. L'Espace Latent ($Z$)

• Dimension : $LATENT_DIM$ (défini dans config.json).
• Rôle : $Z$ représente le "bruit" ou le style/forme conceptuelle de l'insecte (la position, l'inclinaison, la taille des ailes, l'aspect flou). Échantillonner un nouveau $Z$ génère une nouvelle forme d'insecte.

2. La Condition ($C$)

• Méthode : One-Hot Encoding (OHE), où un vecteur de taille $CONDITION_DIM$ est utilisé pour spécifier la couleur.
• Couleurs Supportées : $C$ mappe la couleur demandée aux dimensions de l'espace conditionnel. La liste complète des indices est :
  • {"Rouge": 0, "Vert": 1, "Bleu": 2, "Jaune": 3, "Violet": 4, "Cyan": 5, "Magenta": 6}
• Encodage : Pour renforcer l'effet, l'indice ciblé est défini à $2.0$ au lieu de $1.0$ (voir generate_conditional_image).

3. Le Décodeur (Le Générateur)

• Fonction : $\text{Image} = \text{Decoder}(Z, C)$.
• Il prend le vecteur latent $Z$ (forme) et le vecteur conditionnel $C$ (couleur), les concatène, puis utilise une série de couches de déconvolution (nn.ConvTranspose2d) pour reconstruire l'image finale de taille $64 \times 64 \times 3$.

---

💻 Guide d'Inférence (Code)

Le code d'inférence fourni permet de générer des images directement à partir des poids et de la configuration hébergés sur Hugging Face.

A. Prérequis

Assurez-vous d'avoir les dépendances Python suivantes :

pip install torch numpy Pillow hf-hub

B. Paramètres Clés de Configuration

Le modèle charge ses hyperparamètres critiques à partir de config.json:

• LATENT_DIM : La taille du vecteur de bruit $Z$.
• CONDITION_DIM : La taille du vecteur OHE $C$ (nombre total de couleurs supportées, ici 7).
• IMAGE_SIZE : La résolution de sortie (actuellement $64 \times 64$).

C. L'API de Génération

La fonction principale pour la génération est :

def generate_conditional_image(color_name: str, z_sample: torch.Tensor = None):
    # ... corps de la fonction ...
    return img, z

• color_name : (Obligatoire) Spécifie la couleur dominante souhaitée pour l'insecte. (Ex : "Bleu", "Jaune").
• z_sample : (Optionnel) Permet de réutiliser un vecteur latent (bruit) spécifique pour maintenir la forme de l'insecte tout en changeant la couleur. Si None, un nouveau bruit aléatoire est échantillonné.

D. Exemple d'Utilisation

L'exemple d'interpolation fourni dans le code illustre la puissance du C-VAE :

1. Générer un $Z$ aléatoire (Ex: _, z_initial = generate_conditional_image("Cyan")).
2. Générer une image avec une nouvelle couleur, en réutilisant le même $Z$ (Ex: test_img = generate_conditional_image("Rouge", z_sample=z_initial)[0]).

💡 Résultat : Les deux images auront une forme et une composition presque identiques, mais l'une sera dominée par le Cyan et l'autre par le Rouge. Ceci confirme que la couleur est bien contrôlée par l'entrée conditionnelle $C$, tandis que la forme est contrôlée par $Z$.

** Exemples de codes d'inférence**

import torch
import torch.nn as nn
import torch.nn.functional as F
import numpy as np
from PIL import Image
import json
import os
from huggingface_hub import hf_hub_download

# --- 1. Configuration et Téléchargement ---
HF_USERNAME = "Clemylia" # REMPLACEZ par votre nom d'utilisateur
MODEL_NAME = "Iris-1.0"
REPO_ID = f"{HF_USERNAME}/{MODEL_NAME}"
DEVICE = torch.device("cuda" if torch.cuda.is_available() else "cpu")

# Définition des classes de couleurs pour l'encodage One-Hot
# (Doit correspondre EXACTEMENT au fichier config.json du Hub)
COLOR_TO_INDEX = {
    "Rouge": 0, "Vert": 1, "Bleu": 2, "Jaune": 3, 
    "Violet": 4, "Cyan": 5, "Magenta": 6
}

print(f"🔄 Téléchargement de la configuration et des poids du modèle depuis {REPO_ID}...")

# Télécharge le fichier de configuration pour récupérer les hyperparamètres
config_path = hf_hub_download(repo_id=REPO_ID, filename="config.json")
with open(config_path, 'r') as f:
    config = json.load(f)

LATENT_DIM = config['latent_dim']
CONDITION_DIM = config['condition_dim']
CHANNELS = config['channels']
IMAGE_SIZE = (config['image_size'], config['image_size'])

# Télécharge les poids du modèle
weights_path = hf_hub_download(repo_id=REPO_ID, filename="pytorch_model.bin")

print(f"✅ Configuration chargée: LATENT_DIM={LATENT_DIM}, CONDITION_DIM={CONDITION_DIM}")

# --- 2. Définition de l'Architecture (Identique à l'entraînement) ---
# Seul le Décodeur est nécessaire pour la génération/inférence, mais nous recréons le CVAE complet
# pour charger les poids dans l'architecture correcte.

class ConditionalDecoder(nn.Module):
    """Le décodeur C-VAE : Espace latent + Condition (OHE) -> Image (64x64x3)."""
    def __init__(self, latent_dim, condition_dim):
        super().__init__()
        FLATTENED_INPUT_SIZE = 4096
        self.fc_input = nn.Linear(latent_dim + condition_dim, FLATTENED_INPUT_SIZE)
        
        # NOTE: Les dimensions des couches doivent correspondre EXACTEMENT à celles utilisées lors de l'entraînement
        self.deconv1 = nn.ConvTranspose2d(256, 128, kernel_size=4, stride=2, padding=1) 
        self.deconv2 = nn.ConvTranspose2d(128, 64, kernel_size=4, stride=2, padding=1)
        self.deconv3 = nn.ConvTranspose2d(64, 32, kernel_size=4, stride=2, padding=1)
        self.deconv4 = nn.ConvTranspose2d(32, CHANNELS, kernel_size=4, stride=2, padding=1)

    def forward(self, z, c):
        z_c = torch.cat([z, c], dim=1)
        x = self.fc_input(z_c)
        x = x.view(x.size(0), 256, 4, 4) 
        
        x = F.relu(self.deconv1(x))
        x = F.relu(self.deconv2(x))
        x = F.relu(self.deconv3(x))
        x = torch.sigmoid(self.deconv4(x)) 
        return x

class CVAE(nn.Module):
    # Pour l'inférence, seule la méthode forward est simplifiée pour appeler le décodeur.
    def __init__(self, latent_dim, condition_dim):
        super().__init__()
        # L'Encoder n'est pas utilisé pour la génération, mais on le laisse vide 
        # ou on le retire si les poids ne l'incluent pas. Ici on recrée le Décodeur
        self.decoder = ConditionalDecoder(latent_dim, condition_dim)

    def forward(self, z, c):
        return self.decoder(z, c)

# --- 3. Chargement du Modèle ---

# Crée l'instance du modèle (uniquement le Décodeur est important pour la génération)
model = CVAE(LATENT_DIM, CONDITION_DIM).to(DEVICE)

# Charge les poids. On doit s'assurer que les clés du State Dict correspondent.
# Si l'architecture complète (Encoder + Decoder) a été sauvegardée, on charge l'ensemble.
state_dict = torch.load(weights_path, map_location=DEVICE)

# Le state_dict original contenait 'encoder.' et 'decoder.'. 
# On doit charger correctement le state_dict dans le modèle CVAE (même si on n'utilise que le décodeur).
# Le code d'entraînement a sauvegardé l'intégralité du CVAE (avec un encoder vide non visible ici).
model.load_state_dict({k: v for k, v in state_dict.items() if k.startswith('decoder.')}) # Charge uniquement le décodeur

model.eval()
print(f"✅ Modèle C-VAE chargé sur le dispositif : {DEVICE}.")

# --- 4. Fonction d'Inférence et de Génération ---

def generate_conditional_image(color_name: str, z_sample: torch.Tensor = None):
    """
    Génère une image d'insecte conditionnée par la couleur demandée.
    Args:
        color_name: Le texte de la couleur (ex: "Rouge")
        z_sample: (Optionnel) Un vecteur latent spécifique pour la génération.
    """
    color_name = color_name.capitalize()
    
    # 1. Préparer le vecteur de condition pour la couleur demandée
    target_index = COLOR_TO_INDEX.get(color_name)
    if target_index is None:
        print(f"❌ Erreur: Couleur '{color_name}' non supportée. Veuillez choisir parmi {list(COLOR_TO_INDEX.keys())}")
        return None, None
    
    # Création du vecteur One-Hot Encoding (OHE)
    condition_vector = torch.zeros(1, CONDITION_DIM).to(DEVICE)
    condition_vector[0, target_index] = 2.0
    
    # 2. Préparer le vecteur latent Z (le bruit de génération)
    if z_sample is None:
        # Échantillonnage aléatoire d'un point dans l'Espace Latent
        z = torch.randn(1, LATENT_DIM).to(DEVICE)
    else:
        # Utiliser l'échantillon fourni
        z = z_sample.to(DEVICE)
    
    # 3. Générer l'image en passant Z ET la condition au Décodeur
    with torch.no_grad():
        generated_image_tensor = model(z, condition_vector)
    
    # 4. Traiter et retourner l'image PIL
    # Tenseur (1, 3, H, W) -> Image PIL (H, W, 3)
    img_tensor = generated_image_tensor.squeeze(0).cpu() 
    img_array = (img_tensor.permute(1, 2, 0).numpy() * 255).astype(np.uint8)
    img = Image.fromarray(img_array)
    
    return img, z

# --- 5. Test du Modèle avec une Demande Textuelle ---

# Simule une demande utilisateur
demande_utilisateur = "Je veux une abeille de couleur Violette"
couleur_demandee = "Rouge" # Extraction simple de la couleur

print("-" * 50)
print(f"🤖 Traitement de la demande utilisateur: '{demande_utilisateur}'")
print(f"🔬 Couleur extraite: {couleur_demandee}")
print("-" * 50)

# Génération de l'image
generated_img, _ = generate_conditional_image(couleur_demandee)

if generated_img:
    output_filename = f"generated_{couleur_demandee}_iris1_0.png"
    generated_img.save(output_filename)
    
    print(f"\n✅ Génération réussie! L'image conditionnelle a été sauvegardée sous: {output_filename}")
    print(f"   (Taille: {IMAGE_SIZE[0]}x{IMAGE_SIZE[1]})")

# --- Test de la cohérence: Générer la même image mais avec une couleur différente ---
# Réutilisons le même bruit latent 'z' pour voir la transition de couleur
if generated_img:
    couleur_test = "Rouge"
    
    # Générons un Z initial (bruit)
    _, z_initial = generate_conditional_image("Cyan") # On jette l'image, on garde le Z
    
    print(f"\n🔬 Test d'interpolation: Génération d'un insecte {couleur_test} en utilisant le même 'bruit' (Z).")
    
    # Génération conditionnelle
    test_img, _ = generate_conditional_image(couleur_test, z_sample=z_initial)
    
    if test_img:
        test_output_filename = f"fa{couleur_test}_TEST.png"
        test_img.save(test_output_filename)
        print(f"✅ Test réussi. L'image de test a été sauvegardée sous: {test_output_filename}")
        print("   -> L'insecte devrait avoir la même forme mais une couleur différente (Cyan).")

exemples de génération :