live2d-halfbody

Demi-corps : d'une illustration à VTube Studio

Pour ceux qui ne veulent pas modéliser manuellement ni régler les maillages. Une illustration ou une description de personnage, et l'Agent construit étape par étape un avatar Live2D demi-corps prêt pour VTS. L'utilisateur ne fait que trois choses :

1. Confirmer l'illustration (étape 1) ;
2. Accepter d'envoyer l'illustration vers See-through (étape 3, Hugging Face, ModelScope en secours) ;
3. Voir le résultat dans VTS et répondre OK ou NOK : <phénomène> (étape 5).

Le reste est fait par l'Agent, avec auto-vérification avant transmission.

Fonctionnalités fournies en un seul passage

Fonction	Pilotage
Rotation de la tête gauche/droite, haut/bas (±30), corps incliné avec la tête	Caméra
Suivi du corps : rotation gauche/droite, avant/arrière, respiration	Caméra, respiration automatique VTS
Clignement d'yeux, clignement d'un seul œil (remplacé par l'œil fermé dessiné juste avant fermeture) ; paupière double qui s'estompe en semi-fermeture	Caméra (œil gauche/droit séparés)
Suivi des pupilles, sourcils haut/bas	Caméra
Bouche ouverte pour parler, sourire	Caméra
Cheveux segmentés : frange (optionnelle), côtés (trois segments, de la racine aux pointes, un par un ; peut être rentré derrière l'oreille), cheveux arrière ou chignon ; rebond vertical en hochant la tête. Chaque queue de cheval oscille indépendamment à partir de l'attache, également en trois segments. Cheveux longs sous les épaules suivent le corps	Physique
Accessoires (pendentifs, boucles d'oreilles) oscillent	Physique
Lunettes suivent la rotation de la tête	Caméra
Expressions : yeux souriants N1, bouche en O N2, yeux fâchés N3, perplexe N4, effacer N0	Raccourcis clavier
Gestes : saluer N5, paume ouverte N6, pointer N7	Raccourcis clavier (gestes caméra aussi, voir "Problèmes connus")
Rougir N8	Raccourcis clavier

Impossible : grande rotation de tête (nécessite un visage de profil), corps entier, bras suivant la caméra en continu (nécessite des segments de bras). Le résultat est un fichier .moc3 directement utilisable dans VTS, pas un fichier de projet Cubism Editor (.cmo3) — Editor ne peut pas l'ouvrir. Pour un niveau de finition professionnel (physique plus détaillé, plus d'expressions, maillage commercial), il faut importer les calques de layers-st/ dans Cubism Editor et les relier.

Arborescence

素材/nom_du_personnage/         Illustration, prompt, variantes, résultat See-through, calques
  A0-base.png                  Illustration finale
  prompts/                    Copié depuis references/prompts/default/, remplit les [[…]]
  check/                      Images de contrôle pour chaque variante
  seethrough.psd              Résultat brut de See-through
  seethrough/                 Décomposé en un PNG par calque
  layers/                     Calques autodécomposés : uniquement base pour la composition See-through, non livrés séparément
  layers-st/                  Calques finaux (composition See-through, incluant gestes et rougir)
  R0-rest.png                 Composition statique des calques finaux, fond des variantes gestes et rougir
角色/nom_du_personnage/
  character.json              Positions, amplitudes, correspondance des calques
  标注.png                    Positions de character.json dessinées sur l'illustration
  素材检查/  prepared/  build/runtime/  自查/  vts/

Étapes

Les commandes sont exécutées dans le répertoire de travail de l'utilisateur (contenant 素材/, 角色/), précédées de PYTHONPATH=<chemin du skill> (ex. ~/.claude/skills/live2d-halfbody) pour que Python trouve rigkit.

0. Vérification de l'environnement

python -m rigkit.doctor

Résoudre d'abord tout élément marqué ✗ avant de générer des images, sinon le processus bloquera après une vingtaine d'images. ! n'affecte qu'une partie : sans token See-through, le quota anonyme peut être insuffisant ; sans ffmpeg, pas de vidéo d'auto-contrôle ; sans Codex, utiliser d'autres outils de génération d'images (voir étape 2).

1. Illustration — confirmation utilisateur

Copier tout references/prompts/default/ vers 素材/nom_du_personnage/prompts/, puis remplir les [[…]] dans A0-base.txt (apparence, frange, cheveux latéraux, longueur des cheveux, lunettes, boucles d'oreilles).

• Description uniquement : remplir selon la description, générer l'illustration.
• Illustration fournie : enregistrer sous 素材/nom_du_personnage/参考.png, l'inclure comme image de référence lors de la génération pour obtenir une version respectant les contraintes de liaison (cou dégagé ; si frange, s'arrête au-dessus des sourcils ; cheveux latéraux couvrant l'oreille jusqu'au menton, ou rentrés derrière l'oreille ; éclairage plat, fond blanc, espace entre bras et corps). Si l'original ne respecte pas ces contraintes, la décomposition directe posera problème en animation.

python -m rigkit.variants 素材/nom_du_personnage A0-base

Sans Codex, utiliser la méthode "Autre outil de génération d'images" de l'étape 2 pour générer A0. Montrer le résultat à l'utilisateur, ne continuer qu'après confirmation.

Si des calques déjà séparés selon la liste des calques existent, passer à l'étape 4.

2. Génération d'images

Remplacer les autres [[…]] dans prompts/ par la description du personnage ; supprimer les prompts correspondant aux parties absentes : chapeau ou ornement V1, mèche latérale devant l'oreille V2, frange V3, accessoire V9 (supprimer aussi la ligne correspondante dans S1, voir Génération). Puis :

python -m rigkit.variants 素材/nom_du_personnage

Génère séquentiellement 13 à 17 variantes "une seule modification par image", chacune avec une image de contrôle. Un décalage inférieur à 4 px et une modification limitée à la zone concernée sont considérés comme valides ; sinon, supprimer et régénérer, maximum trois tentatives par variante. Détails dans Génération.

Avec un autre outil de génération d'images (pas de Codex, ou l'Agent peut générer ses propres images) : variants ne fait que vérifier les images déjà présentes sans les régénérer, donc on peut d'abord générer les images avec un autre outil et les placer.

python -m rigkit.variants 素材/nom_du_personnage --list

Chaque ligne correspond à une image : image jointe, fichier de prompt, générée ou non. Générer une par une dans l'ordre ; attendre que l'image marquée "pas encore" soit produite :

• Utiliser le texte complet du fichier prompts/<nom>.txt, sans réécriture ; ne joindre que l'image listée, demander à l'outil de modifier cette même image.
• L'outil doit pouvoir modifier une image : recevoir une image et un prompt, retourner la même image modifiée. Un outil ne produisant que du nouveau texte ne peut générer que A0.
• Enregistrer sous 素材/nom_du_personnage/<nom>.png, avec le même rapport largeur/hauteur que l'image jointe. Ne pas recadrer, ajouter de bordures, détourer ou réparer.
• A0 doit être carré ; si différent de 1254×1254, redimensionner à cette taille (tous les personnages déjà créés ont cette taille).

Une fois un lot terminé, exécuter python -m rigkit.variants 素材/nom_du_personnage pour générer les images de contrôle ; les critères de validité sont les mêmes. Les gestes et rougir de l'étape 3 suivent le même principe : --list F1-blush P1-wave P2-explain P3-point. Aucun personnage complet n'a encore été réalisé avec un outil autre que Codex.

3. Décomposition des calques — accord utilisateur pour l'envoi

D'abord autodécomposer les variantes comme base de composition :

python -m rigkit.split 素材/nom_du_personnage 素材/nom_du_personnage/layers --pad-top 90

Puis demander à l'utilisateur s'il accepte d'envoyer l'illustration vers See-through ; après accord :

python -m rigkit.seethrough fetch 素材/nom_du_personnage/A0-base.png 素材/nom_du_personnage/seethrough
python -m rigkit.seethrough split 素材/nom_du_personnage 素材/nom_du_personnage/layers 素材/nom_du_personnage/layers-st --pad-top 90

fetch essaie d'abord Hugging Face, puis ModelScope en cas d'échec (--site hf ou --site modelscope pour spécifier), chacun avec la plus haute résolution disponible. On peut aussi lui donner un PSD issu de la version web, de ComfyUI ou de sa propre carte graphique : fetch chemin.psd 素材/nom_du_personnage/seethrough. Avec See-through installé localement, utiliser --site local : pas d'envoi d'image, pas de consommation de quota (voir "Environnement").

Les calques finaux doivent absolument passer par See-through : les calques autodécomposés ont des bords pixelisés en mouvement, les cheveux cachés ne sont pas complètement reconstruits, ils ne sont pas livrés seuls. En cas de quota épuisé pour la journée, changer de site, attendre le lendemain, ou utiliser un PSD.

split affiche ligne par ligne les corrections appliquées aux calques See-through (découpage des parties débordant sur d'autres, repositionnement des accessoires mal placés, ajout des parties manquantes). Règles dans Règles section "Composition See-through". Voir layers-st/apercu_decomposition.png : chaque calque ne contient que son élément, la composition statique ne diffère de l'illustration que par le style.

Les yeux fermés et souriants sont autodécomposés. S'ils transportent des traits voisins ou des bords irréguliers, et que deux corrections n'ont pas suffi, envoyer ces deux variantes à See-through, puis relancer split ci-dessus — il utilisera alors les calques de cils See-through (règle n°103) :

python -m rigkit.seethrough fetch 素材/nom_du_personnage/D5-eyes-closed.png 素材/nom_du_personnage/seethrough-D5-eyes-closed
python -m rigkit.seethrough fetch 素材/nom_du_personnage/D6-eyes-smile.png 素材/nom_du_personnage/seethrough-D6-eyes-smile

Demander également l'accord à l'utilisateur avant d'envoyer chaque image sur le site ; chaque image consomme un quota. En local, ajouter --site local --head-from 素材/nom_du_personnage/seethrough pour ne décomposer que la tête.

Puis générer les gestes et rougir :

python -m rigkit.extras 素材/nom_du_personnage 素材/nom_du_personnage/layers-st        # écrit R0-rest.png
python -m rigkit.variants 素材/nom_du_personnage F1-blush P1-wave P2-explain P3-point
python -m rigkit.extras 素材/nom_du_personnage 素材/nom_du_personnage/layers-st        # ajoute aux calques

Voir layers-st/gestes_et_rougir.png : chaque ligne montre l'état statique, la variante, et l'apparence une fois activée dans le modèle ; bras et corps se raccordent, bords des mains nets avant de continuer.

4. Génération et auto-vérification

python -m rigkit.estimate 素材/nom_du_personnage/layers-st 角色/nom_du_personnage --name prenom
python -m rigkit.check_art 角色/nom_du_personnage/character.json
python -m rigkit.prepare 角色/nom_du_personnage/character.json
python -m rigkit.build 角色/nom_du_personnage/character.json             # quelques minutes

• estimate n'écrase pas un character.json existant, il écrit character.draft.json ; si des calques ont été modifiés et nécessitent une réestimation, les comparer et remplacer.
• 标注.png : si l'ellipse du visage, les yeux/nez/bouche, l'axe d'inclinaison, la base du cou, les épaules, la taille ou la ligne des racines ne sont pas aux bonnes positions, modifier les nombres correspondants dans character.json, puis relancer prepare et build.
• 素材检查/ : si 露底 (fond visible) contient du magenta, ou 原画对照 (comparaison avec l'original) des lignes rouges, retourner à l'étape 3. 透出背景 (zones transparentes) liste les endroits non couverts à l'arrêt et devenus transparents lors des gestes ; regarder aussi 青底.png (image statique et chaque geste sur fond cyan) : les trous sur vêtements blancs ou peau claire sont invisibles sur fond blanc. Les zones devenues transparentes là où le bras se déplace sont normales ; sinon, retourner à l'étape 3.

Auto-vérification :

python -m rigkit.preview flips 角色/nom_du_personnage/build/runtime
python -m rigkit.preview sheet 角色/nom_du_personnage/character.json 角色/nom_du_personnage/自查 version_nouvelle=角色/nom_du_personnage/build/runtime
python -m rigkit.preview clip 角色/nom_du_personnage/character.json 角色/nom_du_personnage/自查/mouvement.mp4 version_nouvelle=角色/nom_du_personnage/build/runtime

Les triangles retournés doivent être à 0. Examiner les zones de contrôle fixes sur les agrandissements et la vidéo (sourcils et frange, bord du visage, menton et cou, tempes et oreilles, coins des yeux et cils, commissures des lèvres) ; corriger les problèmes avant de transmettre à l'utilisateur. S'il existe une version précédente, la placer côte à côte pour comparaison.

Ensuite, sur le fond de couleur VTS, rendre chaque image : yeux fermés, mi-clos, souriants, bouche grande ouverte, mi-ouverte, trois gestes, rotation gauche/droite, puis zoomer 3 à 4 fois sur les jonctions œil/ bouche/cheveux : ce sont les premières images que l'utilisateur verra dans VTS.

5. Installation dans VTS — validation utilisateur

python -m rigkit.vts 角色/nom_du_personnage/character.json --install

Un nouveau modèle peut être installé pendant que VTS est ouvert ; pour remplacer un modèle déjà installé, quitter d'abord VTS — les réglages utilisateur sont conservés, seuls les raccourcis et mappages manquants sont ajoutés. Pour installer une nouvelle version tout en gardant VTS ouvert, modifier vts.name et vts.folder pour créer un nouveau dossier.

Présenter à l'utilisateur l'image côte à côte, la vidéo et la liste ci-dessous. Répondre OK ou NOK : <phénomène> :

Quoi regarder	Comment faire
Rotation, inclinaison	Tourner la tête gauche/droite, haut/bas, incliner : visage, cheveux, chapeau, oreilles suivent, sans fissure, points résiduels ou éléments restés en place
Yeux	Clignement, clignement d'un œil, mi-clos ; cils ne traversent pas les cheveux en tournant la tête
Bouche	Parler, sourire ; bouche ne se tord pas quand la tête tourne en position fermée
Cheveux	Secouer la tête : frange, côtés, arrière oscillent en segments, de la racine aux pointes avec un délai croissant ; rebond vertical en hochant la tête ; cheveux longs sous les épaules suivent le corps
Accessoires	Les pendentifs oscillent quand le corps bouge, les vêtements en dessous restent complets
Corps	Suivi du corps en rotation gauche/droite, avant/arrière, respiration
Expressions	Bascule N1~N4, effacer N0
Gestes	N5~N7 : le style du corps ne change pas, bords des mains nets ; en tournant la tête pendant un geste, les bras suivent le corps
Rougir	N8 : bords doux ; en secouant la tête, pas de bord visible sous les cheveux

Réglage des amplitudes

Les amplitudes se règlent dans character.json :

Ce qu'on veut modifier	Champ
Angle d'inclinaison	head.tilt_deg (degrés à pleine amplitude)
Distance de déplacement du visage en rotation	head.yaw_px, head.pitch_px
Inclinaison du corps	body.tilt_deg (degrés par unité de paramètre, pleine amplitude ×10)
Amplitude de respiration	body.breath.head, body.breath.shoulder (en pixels)
Suivi du corps	body.turn, body.shift, body.lean_y
Amplitude des cheveux	hair.locks.<calque>.swing ; segments médians et pointes hair.locks.<calque>.bend ; hochement hair.locks.<calque>.pitch
Ressenti physique	hair.locks.<calque>.chain (trois segments) ou physics : delay plus petit = plus traînant, length plus long = plus lent
Amplitude des accessoires	dangles.<calque>.deg (degrés à pleine amplitude)
Mi-clos des yeux	eyes.crease_fade (plage d'estompage de la paupière double), eyes.lower_from (position de début de fermeture de la paupière inférieure)
Début d'ouverture de la bouche	mouth.open_from : en dessous de cette lecture caméra, la bouche reste fermée

Les amplitudes sont jugées par rapport au cadrage demi-corps VTS et aux mouvements humains réels : une inclinaison normale est d'environ 15°, si le modèle ne tourne que de 3°, c'est comme rien. Modifier, puis relancer build. Les autres champs sont expliqués dans Configuration.

Règles

Toutes les règles et leurs justifications se trouvent dans Règles. Les plus fréquemment enfreintes :

• Avant d'agir, vérifier les pratiques standard Live2D et expliquer clairement ce qu'on compte faire.
• Utiliser See-through pour la découpe ; l'outil de génération d'images ne fournit que ce qu'il ne peut pas donner (expressions, parties cachées, gestes).
• Ne traiter que ce qu'on maîtrise : utiliser les calques See-through en bloc, le code ne fait que sélectionner, repositionner et séparer des parties non connectées, il ne découpe pas pixel par pixel dans un calque (résultat toujours irrégulier). Avant de modifier une zone, l'agrandir côte à côte avec l'original See-through ; ne modifier que si c'est clairement meilleur.
• Toute nouvelle règle doit d'abord être mesurée sur tous les personnages existants pour déterminer son champ d'application ; après modification, exécuter l'ancien et le nouveau code et comparer calque par calque pour ne pas endommager les personnages déjà validés. Chaque règle précise son périmètre : générale, ou seulement dans certaines conditions (déclencheur, cas exclus).
• Pour chaque itération, fournir une image côte à côte et une vidéo de même taille, la décision revient à l'humain ; le nombre de triangles retournés et les différences de pixels ne servent qu'à repérer les cassures de surface.
• Si le même symptôme persiste après trois corrections, arrêter de modifier le code, résoudre avec les assets plutôt.
• L'outil de génération d'images ne reçoit que des instructions "modifier une seule chose sur toute l'image", jamais "ne conserver qu'une partie" ; les parties à conserver sont calculées par le code par différence.
• Demander l'accord de l'utilisateur avant d'envoyer une image à un service externe ; le compte et le token sont à la charge de l'utilisateur, qui les renseigne lui-même sans les répéter dans la conversation.
• Lors de l'installation, ne pas écraser le vtube.json de l'utilisateur ; pour remplacer un modèle déjà installé, VTS doit être quitté.

Environnement

• Python 3.10+ : pip install -r <chemin_du_skill>/requirements.txt (si le Python système interdit l'installation, créer un environnement virtuel). ffmpeg nécessaire pour la vidéo d'auto-contrôle.
• Codex en ligne de commande (génération d'images) : fourni avec l'application de bureau ChatGPT, ou installé séparément (codex doit être dans le PATH) ; connectez-vous à votre compte ChatGPT. Sinon, définir la variable d'environnement CODEX vers l'exécutable. Sans Codex, utiliser un autre outil de modification d'images, voir étape 2.
• See-through (découpage), les deux sites utilisent le même modèle, en préparer au moins un :
  • Hugging Face (préféré, quelques minutes, max 1280) : le temps GPU gratuit quotidien sans connexion peut ne pas suffire pour un passage ; l'utilisateur crée un compte gratuit, génère un jeton de lecture, et le place dans la variable d'environnement HF_TOKEN ou dans ~/.cache/huggingface/token (emplacement créé par hf auth login), environ 1 à 2 passages par jour.
  • ModelScope (secours, gratuit, max 1536) : l'utilisateur crée un compte, génère un jeton d'accès, et le place dans MODELSCOPE_API_TOKEN ou ~/.cache/modelscope/token. File d'attente possible, environ 30 minutes par passage. Les contours des cheveux et yeux en 1536 sont plus proches de l'illustration originale qu'en 1280.
  • Local (optionnel, pas d'envoi d'image, pas de limite) : testé sur Apple Silicon avec 24 Go de RAM, environ 21 minutes pour une image complète en 1280, environ 9 minutes pour la tête seule ; premier lancement télécharge ~13 Go de modèles. Une fois installé, pointer la variable SEETHROUGH_DIR vers le dossier d'installation, voir Génération section "See-through local".
• VTube Studio (version Steam).
• Live2D Cubism Core (pour preview, auto-contrôle, icônes) : automatiquement trouvé si Cubism Editor est installé ; sinon télécharger le Cubism SDK for Native et définir CUBISM_CORE vers la bibliothèque dynamique Core correspondante. Core est utilisé selon la licence Live2D, non distribué avec ce skill.

Testé sur macOS ; non testé sur Windows.

Problèmes connus

• Gestes caméra (paume ouverte = saluer, deux paumes ouvertes = paume ouverte, index pointé = pointer) : le premier personnage les déclenche, le second avec la même configuration ne les déclenche pas — cause non identifiée. Les raccourcis clavier N5~N7 ne sont pas affectés.
• Au repos, le rendu est celui de See-through, un peu plus doux que l'illustration originale, avec moins de détails sur les cils et les contours des pointes.
• Avec des lunettes dont la monture est proche de la paupière double, See-through perd la ligne de la paupière et dessine une bande gris clair le long du bord supérieur des cils ; on la conserve telle quelle.
• Lorsque le coin externe de l'œil est proche de la ligne de contour entre la joue et l'oreille (cas d'un bonnet en laine), les calques autodécomposés des yeux fermés et souriants transportent un petit segment de cette ligne, qui apparaît sur le bord du visage lors de la rotation. Envoyer ces deux variantes à See-through permet de s'en débarrasser (étape 3).