contact-dots

Que fait contact-dots ?

Place des points sur les mains, les membres, les pieds et le pelvis de chaque personnage (et sur tout autre élément nommé), puis mesure, image par image dans Blender headless, l'écart de chaque point à une surface, la distance entre les points et l'angle entre les directions. Écrit dots.json, affiche un court résumé et génère dots-sheet.png (un gros plan par vérification et par la pire pénétration).

Il ne modifie jamais un fichier source et écrit uniquement dans le dossier de sortie que vous nommez.

Quand l'utiliser

• "Sa paume droite touche-t-elle vraiment sa cuisse gauche à l'image 40 ?" (contact corporel, touch)
• "Un doigt passe-t-il à l'intérieur de la tasse ?" (les pénétrations sont toujours vérifiées)
• "Le chargeur est encastré à l'image 40", "la boîte repose à plat", "le pistolet reste dans la main", "le pied planté ne glisse pas" (structurel : seat, rest, hold, distance)
• "Le coude ne se plie jamais en arrière", "le couvercle s'ouvre de 0 à 110 degrés", "la paume fait face à la table" (rotationnel : range, align)

Pas pour : corriger des poses, la physique ou l'équilibre, le contact de la bouche ou du tissu, le chevauchement maille-contre-maille.

Prérequis

Blender (n'importe quelle version récente ; son propre Python est utilisé en interne) et la bibliothèque standard Python 3 pour le script hôte. Blender est trouvé via --blender PATH, puis $BLENDER, puis PATH, puis les dossiers d'installation habituels.

Commandes

Toutes via scripts/dots.py dans ce dossier de compétence :

python scripts/dots.py selftest [--out DIR]       # réponses connues ; à exécuter en premier sur une nouvelle machine
python scripts/dots.py bones <file.fbx|.blend>    # les os du rig et la correspondance d'os proposée
python scripts/dots.py measure <config.json>      # mesurer, juger, écrire dots.json + dots-sheet.png
python scripts/dots.py sheet <dots.json>          # regénérer la planche uniquement

Options : --blender PATH, --timeout S (défaut 600), --limits finger|limb (mesure), --no-sheet (mesure, chiffres uniquement).

La ligne de résultat (après tout avertissement ou lignes d'auto-test) : dots: PASS ... (sortie 0), dots: FAIL ... (sortie 1) ou dots: skipped (<raison>) (sortie 2 : pas de Blender, timeout, erreur Blender ou une mauvaise configuration ; la raison indique laquelle). Une exécution ignorée n'est pas un résultat : corrigez la raison et relancez.

D'une phrase à une configuration

1. Exécutez dots.py bones <fichier> pour chaque fichier de personnage si vous n'êtes pas sûr de la correspondance du rig (Mixamo et les noms d'humanoïdes Unity se correspondent automatiquement ; sinon écrivez un boneMap).
2. Donnez à chaque personnage un role court (her, him, a, b) : les points sont <role>.<dot>.
3. Transformez chaque chose à vérifier en une entrée de checks, avec les images où elle doit être valide.
4. Nommez un dossier out (les chemins relatifs sont relatifs au fichier de configuration).

"Sa paume droite sur sa cuisse gauche à l'image 40" :

{"out": "dots_out",
 "characters": [{"role": "her", "file": "her.fbx"}, {"role": "him", "file": "him.fbx"}],
 "frames": [40],
 "checks": [{"id": "palm-on-thigh", "kind": "touch", "a": "her.R.palm", "b": "him.LeftUpLeg", "frames": [40]}]}

"Sa main droite sur sa cuisse gauche" (n'importe quelle partie de la main) : "a": "her.R.hand" (le point le plus proche du groupe est pris en compte).

Points corporels (S = R ou L) : S.<doigt>.tip, S.<doigt>.mid (thumb, index, middle, ring, pinky), S.palm, S.forearm.1-3, S.upperarm.1-3, S.thigh.1-3, S.shin.1-3, S.knee, S.heel, S.ball, S.toe, pelvis.front, pelvis.back. Groupes : S.hand, S.foot, S.forearm, S.upperarm, S.thigh, S.shin, pelvis.

Surfaces (b d'un touch) : <role> (corps entier), <role>.<os canonique> (une partie du corps, p. ex. him.LeftUpLeg, him.Spine1, him.Head), self, self.<os>, prop:<nom d'objet>, floor, nearest.

Les vérifications structurelles et rotationnelles utilisent des points personnalisés (sur un os, un objet ou une région de maillage) et des directions (axe d'os ou d'objet, ligne entre deux points, normale de surface, normale de paume, axe mondial). Configuration complète : references/config.md. Un exemple travaillé par type de vérification : references/checks.md. Une scène entière avec touch, hold, align, range et rest (une main de mannequin saisit et soulève une barre) : examples/grab/ dans le dépôt ContactDots (config.json ; le résultat attendu est PASS 10/10, 0 pénétrations).

Limites : préréglage finger (défaut : un contact peut être au maximum à 3 mm de son point cible aux images spécifiées et au maximum à 2 mm à l'intérieur sur toute image) ou limb (10 mm / 10 mm), ou vos propres nombres.

Lecture des résultats

Le résumé liste chaque vérification avec son numéro, sa pire image, la limite et PASS/FAIL, puis les pénétrations plus profondes que la limite. Les écarts sont de la peau à la surface en mm : positif = éloigné, négatif = enfoncé. Détails de dots.json : references/results.md.

• Un échec touch avec un écart maximal positif = pas de contact (flottant) ; avec un écart maximal négatif important = enfoncement.
• skinMm dans dots.json est le rayon de peau propre à chaque point ; un rayon étrange signifie de mauvais poids de peau ou un mauvais maillage corporel, et l'écart de ce point est approximatif.
• Aucune vérification déclarée : le résumé liste les contacts observés (points à moins de 30 mm) à la place.

Avertissement sur le repère mondial

Deux fichiers FBX ne partagent pas toujours un même repère mondial (racines d'exportation ou décalages différents). Avec deux personnages ou plus, le résumé affiche la position racine de chaque personnage à la première image. Confirmez qu'ils se tiennent là où ils devraient, les uns par rapport aux autres, avant de faire confiance à toute mesure de paire. Si ce n'est pas le cas, les nombres sont dénués de sens : corrigez l'exportation, ne décalez pas les nombres.

REGARDEZ la planche

Les nombres seuls ne suffisent pas. Ouvrez dots-sheet.png (dans le dossier out) avant de rapporter : chaque maillage dans une couleur unie par personnage ou accessoire sur fond sombre, petits points par personnage, la paire mesurée reliée par une ligne (jaune = succès, magenta = échec ; un anneau autour d'un écart proche de zéro), un disque translucide sur la surface touchée (couleur complémentaire, contour et flèche de normale), trièdre XYZ (X rouge, Y vert, Z bleu clair) sur la paume, le poignet, la tête et le pelvis dans les vues rapprochées, flèches pour les vérifications angulaires, une légende par vignette (id, valeur, limite, PASS/FAIL). La paire mesurée, les flèches, le contour du disque et les trièdres sont dessinés devant les maillages ; les petits points peuvent se cacher derrière eux. Vérifiez que chaque vignette montre les parties souhaitées (main droite, cuisse droite, bonne image). Un succès sur le mauvais point est une mauvaise réponse.

Rapportez

La première ligne du résumé, chaque numéro de vérification avec sa limite et son image, les pénétrations au-dessus de la limite, les positions racines si deux personnages, et ce que montre la planche. Dites que cela a seulement mesuré.